Formatting ​

format() renders a view of the instant. It accepts a named format or a specifier pattern, and it is locale- and calendar-aware.

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

d.format('YYYY-MM-DD HH:mm:ss')        // pattern, local view
d.format('YYYY-MM-DD', {utc: true})    // pattern, UTC view
d.format('rfc9557')                    // 2024-01-15T06:00:00-06:00[America/Chicago]
d.format('rfc3339')
d.format('rfc9110')                    // HTTP date, always GMT

Named Formats ​

Named formats produce spec-compliant output for the formats zdate parses: rfc9557, rfc3339, rfc9110, rfc850, rfc5322, and friends. Fixed-UTC formats (like rfc9110) always render in their required zone; zone-capable formats render the local view unless utc is requested.

Round-tripping holds: output from a named format parses back to the same instant.

Patterns ​

Patterns use format specifiers — YYYY, MM, DD, HH, mm, ss, fractional FFF/fff, offset OOO, zone Z, and many more. Literals are escaped with brackets:

ts
d.format('dddd, MMMM D [at] h:mm A')   // 'Monday, January 15 at 6:00 AM'

The full table lives in Format Specifiers.

Locale and Calendar ​

Names and numbers follow the view's locale and calendar:

ts
d.with({locale: 'fr-FR'}).format('DD MMMM YYYY')          // '15 janvier 2024'
d.with({calendar: 'hebrew'}).format('DD MMMM YYYY')       // Hebrew month names
d.format('DD MMMM YYYY', {calendar: 'islamic-umalqura'})  // per-call calendar

Relative Time ​

Durations render as human text:

ts
zdate().diff(deadline).toRelative()    // 'in 3 days'

See Durations.