DateTime

🕒 An immutable date and time in an IANA time zone.

Months and days are 1-based and dayOfWeek runs 1 (Monday) to 7 (Sunday), following Temporal and ISO-8601 rather than the legacy Date. Every method returns a new instance; nothing mutates.

Syntax

import { DateTime } from '@opentf/std';
new DateTime(input?, options?);

Parameters

Parsing is strict ISO-8601 — it throws a RangeError rather than yielding an Invalid Date, because Date.parse is implementation-defined outside the ISO subset and disagrees across runtimes.

new DateTime('2026-07-29');
new DateTime('2026-07-29T14:30:15.250');
new DateTime('2026-07-29T14:30:15+05:30');
new DateTime('2026-07-29T14:30:15+05:30[Asia/Kolkata]');
new DateTime(1785315615250);
new DateTime({ year: 2026, month: 7, day: 29 }, { timeZone: 'Asia/Kolkata' });

Statics

Getters

Methods

Units are 'year', 'month', 'week', 'day', 'hour', 'minute', 'second' and 'millisecond'.

Arithmetic

Calendar units (years, months, weeks, days) move the wall clock. Exact units (hours and below) move the instant. Across a DST boundary the two differ:

const dt = new DateTime('2026-03-07T12:00:00', { timeZone: 'America/New_York' });

dt.add({ days: 1 }).format('HH:mm');  //=> '12:00'  — 23 real hours later
dt.add({ hours: 24 }).format('HH:mm'); //=> '13:00' — exactly 24 hours later

Month arithmetic clamps rather than rolling over:

new DateTime('2026-01-31').add({ months: 1 }).format('yyyy-MM-dd'); //=> '2026-02-28'

diff counts whole units for year, month, week and day, truncated toward zero, and returns fractional elapsed time for hour and below.

Time zones and DST

A wall-clock time can be missing or repeated at a DST transition. disambiguation decides, matching Temporal:

const wall = '2026-03-08T02:30:00';           // never happens in New York
const timeZone = 'America/New_York';

new DateTime(wall, { timeZone }).format('HH:mm ZZ');
//=> '03:30 -04:00'  — 'compatible' shifts a gap forward

new DateTime(wall, { timeZone, disambiguation: 'earlier' }).format('HH:mm ZZ');
//=> '01:30 -05:00'

new DateTime(wall, { timeZone, disambiguation: 'reject' });
//=> throws RangeError

For an overlap — a wall time that happens twice — 'compatible' takes the earlier instant. 'reject' throws in both cases.

Format tokens

Text in single quotes is literal. Only month and weekday names depend on locale; everything else is locale-independent, so a pattern produces the same bytes on every runtime — safe for filenames, log lines and database columns.

const dt = new DateTime('2026-07-29T14:30:15.250', { timeZone: 'Asia/Kolkata' });

dt.format("yyyy-MM-dd'T'HH:mm:ss");  //=> '2026-07-29T14:30:15'
dt.format('EEEE, d MMMM yyyy');      //=> 'Wednesday, 29 July 2026'
dt.format('MMMM', 'fr-FR');          //=> 'juillet'
dt.toISOString();                    //=> '2026-07-29T14:30:15.250+05:30[Asia/Kolkata]'

toISOString round-trips through the constructor exactly, and toJSON uses it, so instances survive JSON.stringify.

Compared with other date libraries

The @opentf/std figure is measured, not estimated: import { DateTime } from '@opentf/std' bundled with esbuild against a real install, minified and gzipped. The other columns are the sizes those projects publish for themselves.

Where this wins. Real IANA time-zone support with zero dependencies and no bundled database. Temporal precision, which no other library in the table has. Strict parsing that throws instead of handing back an invalid object that propagates silently. And it is already installed if you use @opentf/std.

Where it does not. DateTime is one class, so it cannot be tree-shaken the way date-fns can — importing it costs the full 4.6 KB even if you only format. date-fns also ships far more functions, including business-day maths and dozens of differenceIn* variants. Luxon and date-fns have absorbed a decade of DST and calendar bug reports; this is new. And there is no Duration or Interval type yet, so diff returns a plain number.

If bundle size dominates your decision, use date-fns. If you already depend on @opentf/std and want correct dates without another package, use this.

Runtime support

The whole API works on every runtime. Only the machinery underneath changes.

Try it