@livefolio/sdk / Calendar

Interface: Calendar

Defined in: interfaces/calendar.ts:65

Exchange calendar — the single source of truth for trading-day arithmetic.

Implementations MUST guarantee:

• isOpen(t) returns true only for instants strictly within a session [session.open, session.close).
• next(t) returns the midnight-UTC Date of the next trading day after t; it MUST never return a weekend or holiday.
• previous(t) is the symmetric inverse of next.
• sessions(range) returns one Date per trading day in the half-open interval [range.from, range.to), in ascending order.
• schedule(range) returns the same dates as sessions but enriched with open/close instants for each session.
• isEarlyClose(t) returns true if the session containing (or nearest to) t ends before the exchange's normal close time.

Reference implementation: NYSEExchangeCalendar, LSEExchangeCalendar.

Example

import { NYSEExchangeCalendar } from '@livefolio/sdk';

const cal = new NYSEExchangeCalendar();
const today = new Date('2024-11-29'); // Black Friday (early close)
console.log(cal.isEarlyClose(today)); // true
const next = cal.next(today);
console.log(next.toISOString());      // 2024-12-02T00:00:00.000Z

Methods

isEarlyClose()

isEarlyClose(t): boolean

Defined in: interfaces/calendar.ts:131

Returns true if the exchange closes early on the day containing t. Common examples: Black Friday (US), Christmas Eve, New Year's Eve.

Parameters

Parameter	Type	Description
t	Date	The instant or day to test.

Returns

boolean

---

isOpen()

isOpen(t): boolean

Defined in: interfaces/calendar.ts:73

Returns true if t falls inside an open trading session for this exchange (i.e. between session open and session close, inclusive of open, exclusive of close).

Parameters

Parameter	Type	Description
t	Date	The instant to test.

Returns

boolean

---

next()

next(t): Date

Defined in: interfaces/calendar.ts:82

Returns the midnight-UTC Date of the next trading day strictly after t. Skips weekends, exchange holidays, and any days with no scheduled session.

Parameters

Parameter	Type	Description
t	Date	Reference date. If t itself is a trading day the result is the following trading day, not t.

Returns

Date

---

previous()

previous(t): Date

Defined in: interfaces/calendar.ts:90

Returns the midnight-UTC Date of the most recent trading day strictly before t. Symmetric inverse of Calendar.next.

Parameters

Parameter	Type	Description
t	Date	Reference date.

Returns

Date

---

schedule()

schedule(range): readonly Session[]

Defined in: interfaces/calendar.ts:123

Returns full Session records (date, open instant, close instant) for every trading day in the half-open interval [range.from, range.to).

Parameters

Parameter	Type	Description
range	DateRange	Half-open date range.

Returns

readonly Session[]

Ascending array of Session objects. Early-close days have a close earlier than the normal session close.

---

sessions()

sessions(range): readonly Date[]

Defined in: interfaces/calendar.ts:113

Returns the trading days (as midnight-UTC Dates) within the half-open interval [range.from, range.to), in ascending order.

Parameters

Parameter	Type	Description
range	DateRange	Half-open date range; range.from is inclusive, range.to is exclusive.

Returns

readonly Date[]

Ascending array of trading-day Dates. Empty if no trading days fall in the range.

Example

import { NYSEExchangeCalendar } from '@livefolio/sdk';

const cal = new NYSEExchangeCalendar();
const days = cal.sessions({
  from: new Date('2024-12-23'),
  to:   new Date('2025-01-02'),
});
// days.length === 5 (skips Christmas, Boxing Day is US-only partial, New Year's)