Overview

ZDate has one parser shared by the ZDate constructor and the lower-level ZEpoch API.

ZEpoch.parse() invokes the parser directly and returns the resolved nanosecond epoch as a bigint. It does not create a ZDate object.
ZEpoch.parseSpec() invokes the parser directly and returns the epoch, detected specification, and any parsed suffix data. It does not create a ZDate object.
The ZDate constructor, or function-style zdate(), uses the same parser to resolve a string source before creating the instance. Its views remain lazy.

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

const epoch: bigint = ZEpoch.parse('2024-01-15T12:00:00Z')
const parsed: ParsedSpecResult = ZEpoch.parseSpec('2024-01-15T12:00:00Z')
const date1: ZDate = new ZDate('2024-01-15T12:00:00Z')
const date2: ZDate = zdate('2024-01-15T12:00:00Z')

The sections below document each accepted format and the spec tag returned by ZEpoch.parseSpec().

One Parser, One Doorway

ZDate accepts every supported date string through the same parser. Callers do not choose between ISO 8601, RFC 3339, RFC 9557, Internet headers, log formats, or natural dates. Pass the source and ZDate detects the format.

const date = zdate('Sun, 06 Nov 1994 08:49:37 GMT') // rfc9110

Use ZEpoch.parse() when only the resolved epoch is needed:

const epoch = ZEpoch.parse('2024-01-15') // iso

When the detected format matters, use ZEpoch.parseSpec():

const {epoch, spec, suffix} = ZEpoch.parseSpec('2024-01-15T12:00:00-05:00[America/New_York]')

spec         // 'rfc9557'
suffix?.zone // 'America/New_York'

The input formats below show what can enter that doorway. The dedicated sections document each format's boundaries, extensions, and resolution rules.

ParseSpecResult

ZEpoch.parseSpec() returns a ParseSpecResult:

export type ParseSpecResult = {
    epoch: bigint
    spec: ParsedSpecId
    suffix?: ParsedSuffix
}

Field	Description
`epoch`	The resolved instant as nanoseconds from the Unix epoch
`spec`	The specification or syntax recognized by the parser
`suffix`	RFC 9557 zone, calendar, critical markers, and extension tags

The suffix field is present for RFC 9557 input:

import {ZEpoch} from '@sajajs/zdate'

const result = ZEpoch.parseSpec(
    '2024-01-15T12:00:00-05:00[America/New_York][u-ca=hebrew]'
)

result.epoch                      // 1705338000000000000n
result.spec                       // 'rfc9557'
result.suffix?.zone               // 'America/New_York'
result.suffix?.zoneRequired       // false
result.suffix?.calendar           // 'hebrew'
result.suffix?.calendarRequired   // false
result.suffix?.tags               // {'u-ca': 'hebrew'}

ISO 8601

The zdate parser tags this format as iso.

ISO 8601 defines numeric representations for calendar dates, times, offsets, week dates, ordinal dates, and related date/time values. ZDate accepts the common extended forms, compact forms, expanded years, and a few documented extensions.

Input Formats

Form	Example	Notes
Year and month	`2024-01`	Day defaults to 1
Calendar date	`2024-01-15`	Time defaults to midnight UTC
Extended timestamp	`2024-01-15T12:00:00.123456789+0530`	Colonless offset keeps ISO classification
Compact date	`20240115`	Separators are omitted
Compact timestamp	`20240115T120000.123456789Z`	Separators are omitted
Expanded year	`+012024-01-15T12:00:00+0530`	Expanded years require a sign
SQL datetime extension	`2024-01-15 12:00:00`	A space may replace `T`

Rules

ISO 8601 Week and Ordinal Dates

The zdate parser tags these formats as iso-week-ordinal.

ISO 8601 also defines dates by week number or day of year. ZDate resolves both forms to the same epoch model used by calendar dates.

Input Formats

Form	Example	Notes
Ordinal date	`2024-015`	Day 15 of the year
Ordinal timestamp	`2024-015T12:00:00Z`
Week date	`2024-W03-1`	Monday of ISO week 3
Week timestamp	`2024-W03-1T12:00:00Z`

Rules

RFC 3339

The zdate parser tags this format as rfc3339.

RFC 3339 defines an Internet timestamp profile of ISO 8601. It uses a four-digit year, a complete date and time separated by T, and either Z or a +/-HH:MM offset.

Input Formats

Form	Example	Notes
UTC	`2024-01-15T12:00:00Z`
Numeric offset	`2024-01-15T12:00:00+05:30`	Offset requires a colon
Fractional seconds	`2024-01-15T12:00:00.123456789-05:00`	ZDate preserves nanosecond precision

Rules

RFC 9557

The zdate parser tags this format as rfc9557.

RFC 9557 extends an RFC 3339 timestamp with bracketed time-zone, calendar, and extension information. ZDate also accepts a zone-only form and Java's exact offset-seconds form as documented extensions.

Input Formats

Form	Example	Notes
Zone suffix	`2024-01-15T12:00:00-05:00[America/New_York]`	Offset and zone must agree
Calendar suffix	`2024-01-15T12:00:00Z[u-ca=hebrew]`	Calendar is suffix metadata
Zone-only extension	`2024-01-15T12:00:00[America/New_York]`	Zone resolves the wall time
Java offset-seconds extension	`1883-11-17T12:00:00-04:56:02[America/New_York]`	Offset seconds require a suffix

Rules

RFC 5322

The zdate parser tags this format as rfc5322.

RFC 5322 defines the date and time syntax used by Internet messages. The same parser accepts the related RFC 2822 and RFC 1123 forms.

Input Formats

Form	Example	Notes
Numeric offset	`Mon, 15 Jan 2024 12:00:00 -0500`
No weekday	`15 Jan 2024 12:00:00 GMT`	Weekday is optional
Zone abbreviation	`15 Jan 2024 12:00:00 EST`	Known abbreviations are resolved

Rules

RFC 9110

The zdate parser tags this format as rfc9110.

RFC 9110 defines IMF-fixdate, the preferred HTTP date format. It always uses GMT.

Input Formats

Form	Example	Notes
IMF-fixdate	`Sun, 06 Nov 1994 08:49:37 GMT`	Always GMT

Rules

RFC 850 HTTP Date

The zdate parser tags this format as rfc850.

RFC 9110 retains the obsolete RFC 850 date shape for compatibility with older HTTP senders. This is the fixed-GMT HTTP form, not RFC 850's broader original Usenet date syntax.

Input Formats

Form	Example	Notes
Obsolete HTTP date	`Sunday, 06-Nov-94 08:49:37 GMT`	Full weekday and two-digit year

Rules

Generalized Time

The zdate parser tags this format as generalized-time.

RFC 4517 defines the LDAP encoding of ASN.1 GeneralizedTime. It uses a compact timestamp followed by Z or a numeric offset.

Input Formats

Form	Example	Notes
Hour	`2024011512Z`	Omitted fields default to zero
Minute	`202401151230Z`	Seconds default to zero
Second	`20240115123045Z`
Fractional second	`20240115123045.123456789Z`	Fraction requires seconds
Numeric offset	`202401150700-0500`	Offset or `Z` is required

Rules

Common Log Format

The zdate parser tags this format as commonlog.

The Common Log Format timestamp is used in traditional web-server access logs. It combines a named month with a required numeric offset.

Input Formats

Form	Example	Notes
Common Log Format	`15/Jan/2024:12:00:00 +0000`	Numeric offset is required
Single-digit day	`6/Nov/1994:08:49:37 -0500`	Day may be one or two digits

Rules

`asctime()`

The zdate parser tags this format as asctime.

The C asctime() shape contains a weekday, named month, local clock time, and year, but no offset. ZDate treats it as UTC.

Input Formats

Form	Example	Notes
Space-padded day	`Sun Nov 6 08:49:37 1994`	No offset; treated as UTC
Two-digit day	`Mon Jan 15 12:00:00 2024`	No offset; treated as UTC

Rules

Natural Dates

The zdate parser tags this format as natural.

Natural dates are ZDate's relative and conversational date specification. They are resolved against an anchor instant using the requested view options.

Input Formats

Form	Example	Notes
Anchor	`now`	Anchored to the current instant
Relative day	`tomorrow at noon`
Relative amount	`2 hours ago`
Relative weekday	`next friday at 10am`
Ordinal weekday	`first friday of month`
Absolute date	`jan 15 at noon`	Missing year comes from the anchor

Rules

Custom Formats

Custom formats are parsed by ZEpoch.parseFormat() and do not receive a parseSpec() tag.

Custom parsing accepts a caller-supplied format and optional locale. It always uses the ISO 8601 calendar.

Input Formats

Format	Example	Notes
`YYYY-MM-DD`	`2024-01-15`	Caller supplies the format
`MMMM DD, YYYY`	`January 15, 2024`	Locale month name
`YYYY-MM-DD HH:mm:ss.fff`	`2024-01-15 12:00:00.123456789`	Nanosecond fraction
`DD MMMM YYYY HH:mm` with `fr-FR`	`14 juillet 2025 14:30`	Caller supplies the locale

Overview ​

One Parser, One Doorway ​

ParseSpecResult ​

ISO 8601 ​

Input Formats ​

Rules ​

ISO 8601 Week and Ordinal Dates ​

Input Formats ​

Rules ​

RFC 3339 ​

Input Formats ​

Rules ​

RFC 9557 ​

Input Formats ​

Rules ​

RFC 5322 ​

Input Formats ​

Rules ​

RFC 9110 ​

Input Formats ​

Rules ​

RFC 850 HTTP Date ​

Input Formats ​

Rules ​

Generalized Time ​

Input Formats ​

Rules ​

Common Log Format ​

Input Formats ​

Rules ​

asctime() ​

Input Formats ​

Rules ​

Natural Dates ​

Input Formats ​

Rules ​

Custom Formats ​

Input Formats ​

Rules ​

Overview

One Parser, One Doorway

ParseSpecResult

ISO 8601

Input Formats

Rules

ISO 8601 Week and Ordinal Dates

Input Formats

Rules

RFC 3339

Input Formats

Rules

RFC 9557

Input Formats

Rules

RFC 5322

Input Formats

Rules

RFC 9110

Input Formats

Rules

RFC 850 HTTP Date

Input Formats

Rules

Generalized Time

Input Formats

Rules

Common Log Format

Input Formats

Rules

`asctime()`

Input Formats

Rules

Natural Dates

Input Formats

Rules

Custom Formats

Input Formats

Rules