Quick Start

Install

npm install @sajajs/zdate

Create an Instant

zdate() accepts an ISO/RFC timestamp, a natural date string, an epoch bigint, a Date, calendar fields, or nothing (now):

import {zdate} from '@sajajs/zdate'

zdate()                                      // now
zdate('2024-01-15T12:00:00Z')                // ISO 8601 / RFC 3339
zdate('2024-01-15T12:00:00[America/New_York]') // RFC 9557
zdate('tomorrow at noon')                    // natural date
zdate({year: 2024, month: 1, day: 15})       // fields

An input without an offset or zone is treated as UTC. Input that cannot identify exactly one instant — a wrong offset for a zone, an ambiguous or nonexistent wall time — throws. See Repairing Timestamps.

Read It

const d = zdate('2024-01-15T12:00:00Z')

d.epoch          // bigint nanoseconds — the identity
d.utc.year       // 2024
d.local.hour     // hour in your zone
d.local.zone.name
d.local.weekdayName

utc and local are views. See Views and Snapshots.

The Six Verbs

// by — move by an amount
d.by('2 days')
d.by({months: 1, hours: -3})

// to — move to a destination
d.to('start of month')                    // boundary
d.to({nearest: 'minute', interval: 30})   // snapped interval
d.to({month: 2, hour: 22})                // explicit fields

// diff — measure the distance to another instant
d.diff(zdate(), 'day')

// compare — order two instants
d.compare(other)                          // -1, 0, 1

// format — render a view
d.format('YYYY-MM-DD HH:mm')
d.format('rfc9557')

// with — same instant, different view options
d.with({zone: 'Asia/Tokyo', calendar: 'hebrew'})

Every verb returns a new value; nothing mutates.

Defaults

Zone, locale, and calendar defaults are process-wide and explicit:

import {ZDate} from '@sajajs/zdate'

ZDate.defaults.setZone('America/Chicago').setLocale('en-US').setCalendar('iso8601')

Per-instance view options always win over defaults. See ZDate reference.