DateCalendar

Defined in: packages/engine/src/calendar/DateCalendar.ts:27

The default CalendarBackend: the JavaScript Date object, read in the host process’s time zone, with Intl.DateTimeFormat for named zones.

This is the calendar code the engine has always run, moved behind the interface method by method rather than rewritten, so a host that configures nothing sees the same instants and the same strings it did before the backend existed. Where Date has a quirk (a two-digit year in a constructor maps to the 1900s, an out-of-range instant answers NaN), the quirk is kept here deliberately: the point of this backend is to be the behaviour the Temporal backend is measured against, not to improve on it.

It stays the default because it is the one calendar every supported runtime has. Temporal ships unflagged in Node 26 and in current Chrome, Firefox and Deno, but not in Safari or in the Node 22 and 24 the engine supports, and the smallest polyfill adds about twenty kilobytes gzipped to a bundle that a host doing plain arithmetic never needs. A host that wants Temporal opts in through the engine’s calendar option with the backend from solve-engine/temporal, and pays for it only then.

Implements

• CalendarBackend

Constructors

Constructor

new DateCalendar(): DateCalendar;

Returns

DateCalendar

Methods

addDays()

addDays(epochMs, days): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:58

Move an instant by whole calendar days, holding the local wall-clock time. A day that contains a daylight-saving transition is 23 or 25 hours long, so this is a field step, not an addition of milliseconds.

Parameters

Parameter	Type
epochMs	number
days	number

Returns

number

Implementation of

CalendarBackend.addDays

---

addMonths()

addMonths(epochMs, months): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:64

Move an instant by whole calendar months, holding the local wall-clock time and clamping the day to the length of the month landed in: 31 January plus a month is 28 February, or 29 in a leap year, never 3 March.

Parameters

Parameter	Type
epochMs	number
months	number

Returns

number

Implementation of

CalendarBackend.addMonths

---

fields()

fields(epochMs): CalendarFields;

Defined in: packages/engine/src/calendar/DateCalendar.ts:32

The local calendar fields of an instant, weekday included. See CalendarFields.

Parameters

Parameter	Type
epochMs	number

Returns

CalendarFields

Implementation of

CalendarBackend.fields

---

fieldsInZone()

fieldsInZone(zone, epochMs): ZonedFields;

Defined in: packages/engine/src/calendar/DateCalendar.ts:106

The calendar date and wall-clock time a named IANA zone shows for an instant. Throws the runtime’s RangeError for a zone it does not know or an instant it cannot represent.

Parameters

Parameter	Type
zone	string
epochMs	number

Returns

ZonedFields

Implementation of

CalendarBackend.fieldsInZone

---

formatDateInZone()

formatDateInZone(zone, epochMs): string;

Defined in: packages/engine/src/calendar/DateCalendar.ts:114

The calendar date in a named IANA zone, July 31, 2026, in the en-US style the timezone forms answer in. Throws the runtime’s RangeError for a zone it does not know or an instant it cannot represent.

Parameters

Parameter	Type
zone	string
epochMs	number

Returns

string

Implementation of

CalendarBackend.formatDateInZone

---

formatLongDate()

formatLongDate(epochMs, locale): string;

Defined in: packages/engine/src/calendar/DateCalendar.ts:89

The spelled-out local date in a locale, Tuesday, March 10, 2026 in en.

Parameters

Parameter	Type
epochMs	number
locale	string

Returns

string

Implementation of

CalendarBackend.formatLongDate

---

formatTimeInZone()

formatTimeInZone(zone, epochMs): string;

Defined in: packages/engine/src/calendar/DateCalendar.ts:110

The wall-clock time in a named IANA zone, 1:00 AM, in the en-US style the timezone forms answer in. Throws the runtime’s RangeError for a zone it does not know or an instant it cannot represent.

Parameters

Parameter	Type
zone	string
epochMs	number

Returns

string

Implementation of

CalendarBackend.formatTimeInZone

---

formatTimeOfDay()

formatTimeOfDay(epochMs, locale): string;

Defined in: packages/engine/src/calendar/DateCalendar.ts:93

The local time of day in a locale, 9:30:00 AM in en.

Parameters

Parameter	Type
epochMs	number
locale	string

Returns

string

Implementation of

CalendarBackend.formatTimeOfDay

---

localMidnight()

localMidnight(
   year,
   month0,
   day
): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:46

Local midnight on a calendar date, in epoch milliseconds.

Fields overflow the way Date’s do (month 12 is January of the next year, day 0 the last day of the month before), which is what a caller checking for a rolled-over literal relies on: build the date, read its fields back, and a 30 February shows up as 1 or 2 March.

Parameters

Parameter	Type
year	number
month0	number
day	number

Returns

number

Implementation of

CalendarBackend.localMidnight

---

localWallClock()

localWallClock(
   year,
   month0,
   day,
   minutesPastMidnight
): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:50

A wall-clock time on a calendar date, given as minutes past local midnight, in epoch milliseconds.

The minutes name a clock reading, not an elapsed span: 540 minutes is 09:00 on that date even on a day with a daylight-saving transition, where 540 minutes of elapsed time from midnight would land at 10:00 or 08:00.

Parameters

Parameter	Type
year	number
month0	number
day	number
minutesPastMidnight	number

Returns

number

Implementation of

CalendarBackend.localWallClock

---

now()

now(): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:28

The current instant, in epoch milliseconds. Read at evaluation time, never baked into bytecode.

Returns

number

Implementation of

CalendarBackend.now

---

parseIso8601()

parseIso8601(text): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:85

Parse an ISO 8601 date or date-time string to epoch milliseconds, or NaN when it names no instant.

A date-only string (2019-04-01) is UTC midnight; a date-time with no offset and no Z is local time. Both readings are the ECMAScript ones, and every backend reproduces them so the two spellings of a literal keep meaning the same instant whichever backend is in use.

Parameters

Parameter	Type
text	string

Returns

number

Implementation of

CalendarBackend.parseIso8601

---

utcOffsetMinutes()

utcOffsetMinutes(epochMs): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:77

The local zone’s offset from UTC at an instant, in minutes, positive when ahead of UTC.

Parameters

Parameter	Type
epochMs	number

Returns

number

Implementation of

CalendarBackend.utcOffsetMinutes

---

zoneOffsetMinutes()

zoneOffsetMinutes(zone, epochMs): number;

Defined in: packages/engine/src/calendar/DateCalendar.ts:97

A named IANA zone’s offset from UTC at an instant, in minutes, positive when ahead of UTC. Throws the runtime’s RangeError for a zone it does not know or an instant it cannot represent.

Parameters

Parameter	Type
zone	string
epochMs	number

Returns

number

Implementation of

CalendarBackend.zoneOffsetMinutes