DateConfig

Defined in: packages/engine/src/constants/Configuration.ts:89

Date-related engine configuration: offset limits, input order, holidays.

Properties

defaultFormat

readonly defaultFormat: string;

Defined in: packages/engine/src/constants/Configuration.ts:165

Default date string format for display (moment.js format string)

---

firstDayOfWeek?

readonly optional firstDayOfWeek?: WeekdayName;

Defined in: packages/engine/src/constants/Configuration.ts:200

The day a week starts on, by name, for this week, next week, start of week and end of week (#702). Unset, the locale decides as for weekend, and otherwise Monday. The ISO week number (week number of) stays ISO, Monday-based, whatever this says.

---

holidays?

readonly optional holidays?: HolidayCalendar;

Defined in: packages/engine/src/constants/Configuration.ts:180

Public-holiday calendar for working-day arithmetic (N working days after <date>, working days between <date> and <date>, <date> + N workdays). See HolidayCalendar.

Optional and unset by default: with no calendar, working-day arithmetic skips weekends only. A host that wants holidays excluded too supplies one here (new ExpressionEngine({ config: { date: { holidays } } })), the same way stocks and weather take a host data source. Threaded into the VM by engine/ExpressionEngine.ts exactly as maxOffsetYears is, because working-day math is a VM operation several grammar forms share, so the calendar has to be one source the VM owns rather than per-package state the VM cannot see.

---

inputLocale?

readonly optional inputLocale?: string;

Defined in: packages/engine/src/constants/Configuration.ts:113

The BCP-47 tag 'locale' reads the order from, "en-US" or "de-DE". Unset, the host machine is asked.

Read ONLY when inputOrder is 'locale'. Setting it beside any other order changes no result: a field that quietly switched inference on would make the predictable mistake a wrong reading rather than no change. Its shape is checked wherever it is set, though, and a tag Intl refuses ("en_US", with an underscore) raises DATE_INPUT_LOCALE_INVALID at construction, because a locale silently ignored is a date order silently wrong.

Deliberately separate from the engine’s locale option, which is a language ('en' | 'de' | 'fr') and carries no region. Day/month order is a region question: a bare en probes as month-first while a UK machine resolves to en-GB and probes as day-first, so wiring the two together would flip every existing British engine to month-first.

---

inputOrder

readonly inputOrder: DateInputOrder;

Defined in: packages/engine/src/constants/Configuration.ts:94

The order an ambiguous all-numeric date literal is read in. Defaults to 'auto' (by separator, the historic behaviour). See DateInputOrder.

---

maxOffsetYears

readonly maxOffsetYears: number;

Defined in: packages/engine/src/constants/Configuration.ts:161

How far forward a date offset whose COST grows with the offset may reach, in years. Enforced by vm/VM.ts’s addBusinessDays().

Bounds the walk, not the calendar. Every other date offset in the engine is arithmetic on a Date field, so today + 100000 days costs exactly what one day costs and needs no ceiling; workdays are the one offset that has to step day by day, because which days are skipped depends on where each step lands. today + 100000000 workdays therefore froze the host for thirteen seconds inside a single ADD opcode (where vm.maxInstructions cannot see it) and then answered “Invalid Date”, and a trillion never returned at all.

Release hardening: this field was declared, documented as a “safety limit”, and read nowhere, so it bounded nothing. A limit a host can configure and the engine ignores is worse than no limit, because it reads as protection that is not there.

---

minOffsetYears

readonly minOffsetYears: number;

Defined in: packages/engine/src/constants/Configuration.ts:163

How far BACK the same walk may reach, in years, as a negative number. See maxOffsetYears.

---

onAmbiguous

readonly onAmbiguous: DateAmbiguity;

Defined in: packages/engine/src/constants/Configuration.ts:142

What a date-shaped numeric run the resolved order cannot read does. Defaults to 'refuse'.

• 'refuse': the line reports a structured Error value naming the problem, DATE_ORDER_MISMATCH when another order would have read it and DATE_NOT_A_CALENDAR_DAY when no order names a real day. 12/25/2026 on a day-first engine says there is no month 25, rather than answering 0.00.
• 'arithmetic': the run falls through to the division or subtraction it is spelled like, which is what every version before this one did. 12/25/2026 is 0.00 again, and 2026-02-29 is 1,995. A spelled month that names no real day (29 February 2026) falls through to multiplying a date, which is refused by name wherever it is written, so it answers that refusal rather than its old fourteen-digit number.

The refusal is scoped to runs nobody writes as arithmetic: a two-step chain ending in a four-digit denominator (03/04/2026 as division is 0.0004), and an ISO-shaped hyphen run. A four-digit LEADING group is ordinary arithmetic (1000/10/5 is 20, 1024/8/2 is 64) and is never refused, and neither is a run whose groups are all one or two digits (12/13/14 stays 0.07), because a two-digit year is too weak a signal to hang a refusal on.

The one refusal this setting does not restore is the dot form (25.12.2026 under a month-first order): its only other outcome is a parse error, and an error is not an answer.

---

weekend?

readonly optional weekend?: readonly WeekdayName[];

Defined in: packages/engine/src/constants/Configuration.ts:193

The weekend days, by name: ["friday", "saturday"] where the weekend is Friday and Saturday (#702). Working-day arithmetic skips them, and is a weekend answers true for them. An empty list makes every day a working day.

Unset, the engine’s locale decides when its tag names a region (createEngine({ locale: "ar-SA" })) and the runtime reports that region’s week through Intl.Locale; otherwise Saturday and Sunday. A name that is not a day raises DATE_WEEKDAY_INVALID at construction. See calendar/WeekShape.ts.