std/date

Import from @norbital-ai/std/date

std/date (§3.7, rule 68, X-11): a date is a zone-free calendar day, an instant is UTC, and a date period is inclusive { from, to | null } (null = open). Values are branded strings, so they are their own wire form.

DateFormatOptions type

type DateFormatOptions = Intl.DateTimeFormatOptions & {
    locale?: string;
};

Intl.DateTimeFormat options plus the locale to format in.

Members

Name	Type	Description
locale?	string

Source: packages/std/src/date.ts:12

DatePeriod type

type DatePeriod = {
    readonly from: PlainDate;
    readonly to: PlainDate | null;
};

An inclusive period of dates; to: null is open-ended.

Members

Name	Type	Description
from	PlainDate
to	PlainDate | null

Source: packages/std/src/date.ts:10

Instant function

function Instant(v: string | Date): Instant

An ISO instant with Z or an offset (or a Date), as canonical UTC …Z.

Parameters

Name	Type	Description
v	string | Date

Source: packages/std/src/date.ts:7

PlainDate function

function PlainDate(s: string): PlainDate

A calendar day YYYY-MM-DD; anything else throws.

Parameters

Name	Type	Description
s	string

Source: packages/std/src/date.ts:6

Zone function

function Zone(v: string): Zone

An IANA zone id the runtime knows.

Parameters

Name	Type	Description
v	string

Source: packages/std/src/date.ts:8

addDays function

function addDays(d: DateIn, n: number): PlainDate

The day n days after d (before, when negative).

Parameters

Name	Type	Description
d	DateIn
n	number

Example

addDays('2026-02-27', 2) // '2026-03-01'

Source: packages/std/src/date.ts:93

addMonths function

function addMonths(d: DateIn, n: number): PlainDate

Calendar months; clamp to the target month's last day, refusing results outside four-digit calendar years.

Parameters

Name	Type	Description
d	DateIn
n	number

Source: packages/std/src/date.ts:95

contains function

function contains(p: DatePeriod, d: DateIn): boolean

Whether day d is inside period p (ends included).

Parameters

Name	Type	Description
p	DatePeriod	from: PlainDate to: PlainDate | null
d	DateIn

Source: packages/std/src/date.ts:66

datePeriod function

function datePeriod(from: DateIn, to: DateIn | null): DatePeriod

An inclusive period; to < from throws.

Parameters

Name	Type	Description
from	DateIn
to	DateIn | null

Source: packages/std/src/date.ts:59

days function

function days(p: DatePeriod): number

Inclusive day count; an open period throws.

Parameters

Name	Type	Description
p	DatePeriod	from: PlainDate to: PlainDate | null

Source: packages/std/src/date.ts:78

eachDay function

function eachDay(p: DatePeriod): PlainDate[]

Every day of a closed period, in order; an open period throws.

Parameters

Name	Type	Description
p	DatePeriod	from: PlainDate to: PlainDate | null

Source: packages/std/src/date.ts:83

formatDate function

function formatDate(d: DateIn, opts?: DateFormatOptions): string

A calendar day for people (Jan 5, 2026 by default); never shifted by a zone.

Parameters

Name	Type	Description
d	DateIn
opts?	DateFormatOptions

Source: packages/std/src/date.ts:130

formatInstant function

function formatInstant(i: Instant | string, opts?: DateFormatOptions): string

An instant in opts.timeZone (default the runtime's).

Parameters

Name	Type	Description
i	Instant | string
opts?	DateFormatOptions

Source: packages/std/src/date.ts:133

formatPeriod function

function formatPeriod(p: DatePeriod | null | undefined, opts?: DateFormatOptions): string

Jan 5, 2026 – Feb 1, 2026; an open end is …, no period is —.

Parameters

Name	Type	Description
p	DatePeriod | null | undefined
opts?	DateFormatOptions

Source: packages/std/src/date.ts:136

intersect function

function intersect(a: DatePeriod, b: DatePeriod): DatePeriod | null

The days two periods share, or null when they do not overlap.

Parameters

Name	Type	Description
a	DatePeriod	from: PlainDate to: PlainDate | null
b	DatePeriod	from: PlainDate to: PlainDate | null

Source: packages/std/src/date.ts:72

isPlainDate function

function isPlainDate(value: unknown): value is PlainDate

An actual four-digit Gregorian calendar day, without allocating or parsing a Date.

Parameters

Name	Type	Description
value	unknown

Source: packages/std/src/date.ts:29

monthOf function

function monthOf(d: DateIn): DatePeriod

The calendar month containing d, as a closed period.

Parameters

Name	Type	Description
d	DateIn

Source: packages/std/src/date.ts:110

overlaps function

function overlaps(a: DatePeriod, b: DatePeriod): boolean

Whether two periods share at least one day.

Parameters

Name	Type	Description
a	DatePeriod	from: PlainDate to: PlainDate | null
b	DatePeriod	from: PlainDate to: PlainDate | null

Source: packages/std/src/date.ts:69

parseInstant function

function parseInstant(text: string, zone?: Zone | string): Instant | null

An ISO instant with a zone, or a wall time YYYY-MM-DD HH:MM[:SS] read in zone; null when the text is neither (never a throw: the caller decides whether a blank or bad cell refuses).

Parameters

Name	Type	Description
text	string
zone?	Zone | string

Source: packages/std/src/date.ts:146

yearOf function

function yearOf(d: DateIn): DatePeriod

The calendar year containing d, as a closed period.

Parameters

Name	Type	Description
d	DateIn

Source: packages/std/src/date.ts:115