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

Exchange-Calendar Alignment

Install and import#

bash
npm install fintech-algorithms
ts
import { validateCalendar } from "fintech-algorithms/market-data-engineering/time-synchronization/exchange-calendar-alignment";

Signature#

validateCalendar(bundle)

Validates a trading-calendar bundle before anything is aligned to it: that sessions do not overlap, that closures are consistent with sessions, and that the licence terms permitting redistribution are present.

Parameters#

NameTypeNotes
bundle{ license, calendar, sessions, closed_dates }The calendar under test together with its licence metadata. Calendars are usually licensed data, which is why the licence block is part of the contract rather than an afterthought.

Returns#

void

Returns nothing on success. Validation is a gate, not a transform — the value of calling it is the failure.

Errors#

  • When sessions overlap or are out of order — throws
  • When a closed date contradicts a defined session — throws
  • When required licence metadata is missing — throws

Complexity: time O(n log n), space O(n).

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#

bundle
{
  "license": "CC0-1.0 teaching transcription; contains calendar facts, not market data",
  "calendar": {
    "calendar_id": "nyse-tape-a-core-teaching",
    "calendar_version": "2026-07-22",
    "retrieved_at": "2026-07-22",
    "venue": "New York Stock Exchange",
    "market": "NYSE Tape A core equities",
    "time_zone": "America/New_York",
    "tzdb_version": "2026c",
    "boundary": "[open, close)",
    "outside_coverage": "fail_closed",
    "local_time_policy": "reject_nonexistent_require_fold_for_ambiguous",
    "opening_auction_policy": "include_at_open",
    "closing_auction_policy": "exclude_at_close",
    "extended_hours_policy": "exclude",
    "supported_dates": [
      "2018-12-05",
      "2025-03-07",
      "2025-03-10",
      "2025-07-03",
      "2025-07-04",
      "2026-07-03"
    ]
  },
  "sessions": [
    {
      "session_id": "XNYS-2025-03-07-CORE",
      "session_date": "2025-03-07",
      "local_open": "2025-03-07T09:30:00",
      "local_close": "2025-03-07T16:00:00",
      "open": "2025-03-07T14:30:00.000Z",
      "close": "2025-03-07T21:00:00.000Z",
      "session_type": "regular",
      "source_ids": ["R03", "R04"]
    },
    {
      "session_id": "XNYS-2025-03-10-CORE",
      "session_date": "2025-03-10",
      "local_open": "2025-03-10T09:30:00",
      "local_close": "2025-03-10T16:00:00",
      "open": "2025-03-10T13:30:00.000Z",
      "close": "2025-03-10T20:00:00.000Z",
      "session_type": "regular",
      "source_ids": ["R03", "R04"]
    },
    {
      "session_id": "XNYS-2025-07-03-CORE",
      "session_date": "2025-07-03",
      "local_open": "2025-07-03T09:30:00",
      "local_close": "2025-07-03T13:00:00",
      "open": "2025-07-03T13:30:00.000Z",
      "close": "2025-07-03T17:00:00.000Z",
      "session_type": "early_close",
      "source_ids": ["R02", "R03", "R04"]
    }
  ],
  "closed_dates": [
    {
      "session_date": "2018-12-05",
      "closure_type": "exceptional_closure",
      "reason": "National Day of Mourning for President George H. W. Bush",
      "source_ids": ["R05"]
    },
    {
      "session_date": "2025-07-04",
      "closure_type": "holiday",
      "reason": "Independence Day",
      "source_ids": ["R02", "R03"]
    },
    {
      "session_date": "2026-07-03",
      "closure_type": "holiday",
      "reason": "Independence Day observed",
      "source_ids": ["R01"]
    }
  ]
}

Call#

validateCalendar(bundle)

Returns#

undefined

undefined

Other exports#

This module also exports localWallToUtc, alignEvents, sessionGrid. 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#

Exchange-Calendar Alignment — article hero
Exchange-Calendar Alignment — dst session alignment

Calculation flow#

Calendar alignment decision flow 
flowchart LR
  A["Pinned venue and versioned calendar"] --> B["Convert UTC event to named-zone date"]
  B --> C{"Date explicitly supported?"}
  C -->|No| D["Fail closed: calendar_unsupported"]
  C -->|Closure| E["closed_date plus source evidence"]
  C -->|Open session| F{"Kind allowed and open <= t < close?"}
  F -->|Yes| G["in_session plus lineage"]
  F -->|No| H["outside_session or excluded_by_policy"]

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#

  • R01 - NYSE Holidays and Trading Hours
  • R02 - 2025 NYSE Trading Calendar
  • R03 - NYSE 2025-2027 Holidays and Trading Hours snapshot
  • R04 - IANA Time Zone Database
  • R05 - New York Stock Exchange to Honor President George H. W. Bush
  • R06 - RFC 3339: Date and Time on the Internet
  • R07 - RFC 9557: Date and Time on the Internet with Additional Information
  • Evidence classification

The rest of the Time Synchronization family#