Exchange-Calendar Alignment

Install and import

bash

npm install fintech-algorithms

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

Name	Type	Notes
`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

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