Creating Instants

zdate() and new ZDate() accept the same sources and behave identically. Every form follows one contract: the source resolves the epoch, and the view options control how that epoch is read — they never participate in resolution. The full contract lives in the ZDate reference; this page shows each source shape in practice.

import {zdate, ZDate} from '@sajajs/zdate'

Now

No source means the current instant:

zdate()
zdate(undefined, {zone: 'Asia/Tokyo'})   // now, viewed in Tokyo

Passing view options as the first argument is shorthand for the same thing:

zdate({zone: 'Asia/Tokyo'})              // identical to the line above

From Strings

Any supported format — ISO 8601, RFC 9557, the RFC header dates, log formats, and natural dates:

zdate('2024-01-15T12:00:00Z')
zdate('2024-01-15 12:00:00')             // SQL datetime, treated as UTC
zdate('Mon, 15 Jan 2024 12:00:00 GMT')   // RFC 9110
zdate('tomorrow at noon')                // natural, anchored to now

A string with no offset and no zone is treated as UTC. Natural dates are the one case where view options participate: they are relative, so they anchor to the current time with the given view options before being applied.

From RFC 9557 Strings

The suffix zone resolves the wall time to an epoch; it does not become the local view unless adopted:

const stored = '2024-01-15T12:00:00-05:00[America/New_York][u-ca=hebrew]'

zdate.defaults.setZone('America/Chicago')
zdate.defaults.setCalendar('iso8601')  // this is already the default

// .local view in Chicago, calendar is iso8601
zdate(stored)                        
// .local view in New York, calendar is japanese
zdate(stored, {zone: 'source', calendar: 'japanese'})      
// .local view in Tokyo, calendar is hebrew
zdate(stored, {zone: 'Asia/Tokyo', calendar: 'source'})
// shorthand: sets all ViewOptions to 'source': .local view in New York, calendar is hebrew
zdate(stored, 'source')

A suffix calendar follows the same rule: it is adopted only when requested with calendar: 'source'. Nothing from the suffix is applied implicitly, and the whole suffix stays available on parsedSuffix. See Time Zones and DST.

From Epoch Values

An epoch is nanoseconds as a bigint:

zdate(1705338000000000000n)

A platform Date is accepted at its millisecond precision:

zdate(new Date())

From Calendar Fields

Fields name the calendar they are expressed in; without it they are ISO 8601. Time fields default to zero and resolve in the fields' zone (default UTC):

zdate({year: 2024, month: 1, day: 15})                              // iso8601, midnight UTC
zdate({year: 5784, month: 5, day: 5, calendar: 'hebrew'})           // Hebrew date
zdate({year: 2024, month: 1, day: 15, hour: 12, zone: 'America/New_York'})

The era field is required for gregory, japanese, roc, ethiopic, and coptic; it is ignored for all other calendars. See Calendars.

From Snapshots

A snapshot is the serializable record a view produces, and the constructor accepts it back — the round trip preserves the instant and the view context:

const snap = d.local.snapshot()      // plain object; also what toJSON() emits
const restored = zdate(snap, 'source')

See Views and Snapshots.

From Another ZDate

A ZDate source copies the epoch. Views are not copied unless you ask:

const other = zdate(d)               // same epoch, default views
const alike = zdate(d, 'source')     // same epoch, d's zone, locale, and calendar

Adopting Source Views

'source' — as the whole second argument, or per field — adopts view data the source carries. When the source has no data for a requested field, the default is used.

zdate(input, 'source')               // zone, locale, and calendar from the source
zdate(input, {zone: 'source'})       // just the zone

What each source can provide:

Source	zone	calendar	locale
RFC 9557 string	suffix zone	u-ca tag	—
Snapshot	✓	✓	✓
ZDate	✓	✓	✓
Calendar fields	zone field	calendar field	—
ISO string, bigint, Date	—	—	—