fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Asynchronous Return Alignment

Install and import#

bash
npm install fintech-algorithms
ts
import { classifyIntervalPair } from "fintech-algorithms/market-data-engineering/time-synchronization/asynchronous-return-alignment";

Signature#

classifyIntervalPair(left, right, evaluatedAt)

Compares two return intervals and reports exactly how they overlap. Correlating returns measured over intervals that only partly coincide is a quiet and common source of wrong numbers.

Parameters#

NameTypeNotes
leftReturnIntervalFirst return, carrying event_start, event_end, available_at and return_value.
rightReturnIntervalSecond return, in the same shape.
evaluatedAtstringDecision time, ISO 8601. Omitted, no evaluation cutoff is applied and availability is reported without being judged against a moment.
optional

Returns#

{ geometry, event_overlap_start, event_overlap_end, event_overlap_ms, left_overlap_fraction, right_overlap_fraction, … }

The overlap geometry — disjoint, partial, nested or identical — with the overlapping window and what fraction of each interval it represents.

Errors#

  • When an interval ends before it starts — throws

Complexity: time O(1), space O(1).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

left
{
  "return_id": "L1",
  "instrument": "L",
  "partition": "S",
  "event_start": "2026-01-01T00:00:00.000Z",
  "event_end": "2026-01-01T00:00:04.000Z",
  "available_at": "2026-01-01T00:00:04.000Z",
  "return_value": 0.01
}
right
{
  "return_id": "R1",
  "instrument": "R",
  "partition": "S",
  "event_start": "2026-01-01T00:00:00.000Z",
  "event_end": "2026-01-01T00:00:04.000Z",
  "available_at": "2026-01-01T00:00:04.000Z",
  "return_value": 0.01
}

Call#

classifyIntervalPair(left, right, evaluatedAt)

Returns#

object with 11 fields: left_return_id, right_return_id, partition, geometry, event_overlap_start, event_overlap_end, event_overlap_ms, left_overlap_fraction, …

{
  "left_return_id": "L1",
  "right_return_id": "R1",
  "partition": "S",
  "geometry": "exact",
  "event_overlap_start": "2026-01-01T00:00:00.000Z",
  "event_overlap_end": "2026-01-01T00:00:04.000Z",
  "event_overlap_ms": 4000,
  "left_overlap_fraction": 1,
  "right_overlap_fraction": 1,
  "pair_available_at": "2026-01-01T00:00:04.000Z",
  "jointly_available_at_evaluation": null
}

Other exports#

This module also exports diagnoseAsynchronousReturnAlignment. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Asynchronous Return Alignment — article hero
Asynchronous Return Alignment — return overlaps

Calculation flow#

Diagnostic interval-overlap flow 
flowchart LR
    A["Correction-resolved returns"] --> B["Validate identity, time, and partition"]
    B --> C["Compare same-partition event intervals"]
    C --> D["Classify geometry and coverage"]
    D --> E["Evaluate pair availability"]
    E --> F["Emit diagnostic only"]
    F -. "separate specification" .-> G["Optional downstream estimator"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

The rest of the Time Synchronization family#