Parsing

One strict parser handles every supported string format. zdate('tomorrow') and zdate('2024-01-15T12:00:00Z') are the same operation — you should not have to think about which kind of string you typed.

Supported Specifications

Spec	Covers
iso	ISO 8601 extended and compact, SQL datetime (space separator), expanded +/- years
iso-week-ordinal	ISO week dates (2024-W03-5) and ordinal dates (2024-015)
rfc3339	The RFC 3339 profile of ISO 8601
rfc9557	IXDTF suffixes: [America/New_York], [u-ca=hebrew], critical ! tags
rfc5322	Email/SMTP dates, including RFC 2822, 1123, and 822 forms
rfc9110	HTTP IMF-fixdate
rfc850	Obsolete HTTP date
asctime	C asctime() output
commonlog	Common Log Format (15/Jan/2024:12:00:00 +0000)
generalized-time	RFC 4517 LDAP / ASN.1 GeneralizedTime
natural	zdate's grammar-based natural dates

ZEpoch.parseSpec(string) reports which spec matched and contains RFC 9557 suffix data.

Input Formats

Parsing has a single deterministic rule set. There are no modes and no parse options that change what a timestamp means.

Input	Behavior
12:00:00	No offset, no zone — treated as UTC
12:00:00Z	Explicit UTC
12:00:00-05:00	Offset math determines the epoch
12:00:00[America/New_York]	Local wall time in that zone, offset resolved from TZDB
12:00:00-05:00[America/New_York]	Offset and zone must agree at that instant, else throws
12:00:00-03:00[America/New_York]	Offset contradicts zone — throws

A zone-only wall time that falls in a DST fold (two valid instants) or gap (no valid instant) is also rejected: the source did not provide enough information to identify one instant, and zdate does not make hidden choices during parsing. These conditions throw a 'resolution' error and can be repaired explicitly — see Repairing Timestamps.

Strictness Details

• Z and -00:00 mean "UTC is known, local offset is unknown" (RFC 9557 2.2, 3.4) and skip zone matching. +00:00 asserts a local offset and must agree with the zone.
• Noncanonical negative-zero offsets (-0000, -00) are invalid.
• Leap seconds (23:59:60) are accepted and normalized.
• Duplicate RFC 9557 suffix tags follow spec rules: a duplicate involving a critical (!) tag throws; otherwise the first value wins. A duplicate zone always throws.

Custom Formats

For localized input in a known shape, use ZEpoch.parseFormat():

import {ZEpoch} from '@sajajs/zdate'

const epoch = ZEpoch.parseFormat('14 juillet 2025 14:30', 'DD MMMM YYYY HH:mm', {locale: 'fr-FR'})