nish/temporal

Dates, times, instants and durations in the ISO 8601 calendar, under the names and the rules of TC39's Temporal (docs/wp64-temporal.md).

import {
  Duration,
  Instant,
  PlainDate,
  PlainDateTime,
  PlainTime,
  durationCompare,
  durationFrom,
  durationFromOrNull,
  instantCompare,
  instantFrom,
  instantFromEpochMilliseconds,
  instantFromOrNull,
  nowInstant,
  plainDateCompare,
  plainDateFrom,
  plainDateFromOrNull,
  plainDateTimeCompare,
  plainDateTimeFrom,
  plainDateTimeFromOrNull,
  plainTimeCompare,
  plainTimeFrom,
  plainTimeFromOrNull,
} from "nish/temporal";
import { PlainDate, Duration, plainDateFrom } from "nish/temporal";

export const main = (): i32 => {
  const due: PlainDate = plainDateFrom("2024-01-31");
  const next: PlainDate = due.add(new Duration(0, 1));   // 2024-02-29
  console.log(next.toString());
  console.log(due.until(next).toString());              // P29D
  return 0;
};
Five types, each immutable

PlainDate, PlainTime and PlainDateTime are wall-clock values with no time zone; Instant is an exact point on the UTC timeline; Duration is ten signed fields, years to nanoseconds. Every method answers a new value. A field reads as Temporal's getter of the same name does (d.year, d.dayOfWeek, t.nanosecond), and the string forms are Temporal's byte for byte.

What is Temporal's and what is this module's

A class here is the Temporal class of the same name, and plainDateFrom(s) is Temporal.PlainDate.from(s), plainDateCompare(a, b) is Temporal.PlainDate.compare(a, b), and so on for each type: Nish has no static members, so the class's statics are free functions named after it. The arithmetic follows the specification's: add constrains a day past the end of the month (2024-01-31 plus a month is 2024-02-29), until and since answer the largest unit Temporal's default does (days for a date or a date-time, hours for a time, seconds for an instant), and a string Temporal refuses with a RangeError panics here with a message that starts RangeError:. The ...OrNull functions are this module's own: the same parse, answering null instead.

What is not here yet

What is not here yet (docs/wp64-temporal.md §6): ZonedDateTime and every time zone but UTC, PlainYearMonth, PlainMonthDay, the option bags ({ largestUnit: "year" }, with({ day: 1 }), round, total), calendars other than iso8601, toLocaleString, and epochNanoseconds, which is a bigint in JavaScript. An Instant is any nanosecond in Temporal's range of ±10^8 days from 1970, held as i64 seconds and i32 nanoseconds; a Duration's fields are i64, which is narrower than Temporal's for microseconds and nanoseconds alone.

Private helpers carry the module's name

Private helpers carry the module's name because they share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e).

Functions

durationCompare

Temporal.Duration.compare(a, b): -1, 0 or 1 as a is shorter than, as long as, or longer than b, each day counted as 24 hours. Panics with a RangeError when either has years, months or weeks, which Temporal compares only against a relativeTo date; two durations with the same fields compare equal whatever they hold.

const durationCompare: (a: Duration, b: Duration) => i32
aDurationrequired

the first duration

bDurationrequired

the second duration

returnsi32

the order of the two

durationFrom

Temporal.Duration.from(text): the duration an ISO 8601 string names, [+-]P[nY][nM][nW][nD][T[nH][nM][nS]] in either case, where the last time field may have a fraction of up to nine digits (PT1.5H is an hour and 30 minutes). Panics with a RangeError on anything else.

const durationFrom: (text: string) => Duration
textstringrequired

such as P1Y2M, PT36H or -P1DT0.5S

returnsDuration

the duration

durationFromOrNull

durationFrom, answering null instead of panicking on a string it refuses. Not part of Temporal.

const durationFromOrNull: (text: string) => Duration | null
textstringrequired

the string to parse

returnsDuration | null

the duration, or null

instantCompare

Temporal.Instant.compare(a, b): -1, 0 or 1 as a is before, the same as, or after b.

const instantCompare: (a: Instant, b: Instant) => i32
aInstantrequired

the first instant

bInstantrequired

the second instant

returnsi32

the order of the two

instantFrom

Temporal.Instant.from(text): the instant an RFC 9557 string names. It must have a date, a time and either Z or a numeric offset, which is subtracted (2024-01-15T09:05+01:00 is 2024-01-15T08:05:00Z); a bracketed time zone after it is ignored. Panics with a RangeError on anything else.

const instantFrom: (text: string) => Instant
textstringrequired

such as 2024-01-15T09:05:00Z

returnsInstant

the instant

instantFromEpochMilliseconds

Temporal.Instant.fromEpochMilliseconds(ms): the instant ms milliseconds after 1970-01-01T00:00:00Z. Panics with a RangeError when ms is not a whole number or is outside ±8.64 × 10^15.

const instantFromEpochMilliseconds: (ms: f64) => Instant
msf64required

milliseconds since the epoch

returnsInstant

the instant

instantFromOrNull

instantFrom, answering null instead of panicking on a string it refuses. Not part of Temporal.

const instantFromOrNull: (text: string) => Instant | null
textstringrequired

the string to parse

returnsInstant | null

the instant, or null

nowInstant

Temporal.Now.instant(): the wall clock now, to the nanosecond the operating system reports. Capability: clock.

const nowInstant: () => Instant
returnsInstant

the current instant

plainDateCompare

Temporal.PlainDate.compare(a, b): -1, 0 or 1 as a is before, the same as, or after b, which is the comparator sort takes.

const plainDateCompare: (a: PlainDate, b: PlainDate) => i32
aPlainDaterequired

the first date

bPlainDaterequired

the second date

returnsi32

the order of the two

plainDateFrom

Temporal.PlainDate.from(text): the date an RFC 9557 string names. A time, an offset and annotations may follow the date and are ignored but for a calendar, which must be iso8601; a Z is refused, as it is in Temporal. Panics with a RangeError on anything else.

const plainDateFrom: (text: string) => PlainDate
textstringrequired

such as 2024-01-15, 20240115 or 2024-01-15T12:00[u-ca=iso8601]

returnsPlainDate

the date

plainDateFromOrNull

plainDateFrom, answering null instead of panicking on a string it refuses. Not part of Temporal.

const plainDateFromOrNull: (
  text: string,
) => PlainDate | null
textstringrequired

the string to parse

returnsPlainDate | null

the date, or null

plainDateTimeCompare

Temporal.PlainDateTime.compare(a, b): -1, 0 or 1 as a is before, the same as, or after b.

const plainDateTimeCompare: (
  a: PlainDateTime,
  b: PlainDateTime,
) => i32
aPlainDateTimerequired

the first date-time

bPlainDateTimerequired

the second date-time

returnsi32

the order of the two

plainDateTimeFrom

Temporal.PlainDateTime.from(text): the date-time an RFC 9557 string names; a date alone is midnight. An offset and annotations are ignored but for a calendar, which must be iso8601; a Z is refused. Panics with a RangeError on anything else.

const plainDateTimeFrom: (text: string) => PlainDateTime
textstringrequired

such as 2024-01-15T09:05 or 2024-01-15 09:05:00.5

returnsPlainDateTime

the date-time

plainDateTimeFromOrNull

plainDateTimeFrom, answering null instead of panicking on a string it refuses. Not part of Temporal.

const plainDateTimeFromOrNull: (
  text: string,
) => PlainDateTime | null
textstringrequired

the string to parse

returnsPlainDateTime | null

the date-time, or null

plainTimeCompare

Temporal.PlainTime.compare(a, b): -1, 0 or 1 as a is earlier than, the same as, or later than b.

const plainTimeCompare: (a: PlainTime, b: PlainTime) => i32
aPlainTimerequired

the first time

bPlainTimerequired

the second time

returnsi32

the order of the two

plainTimeFrom

Temporal.PlainTime.from(text): the time an RFC 9557 string names, either a time alone (12:30, T1230, 12:30:15.5) or a date-time, whose date is ignored. A string with no time, one with a Z, and a time alone without its T that would also read as a year and month or a month and day (2021-12, 1214) are refused, as Temporal refuses them. Panics with a RangeError on anything else.

const plainTimeFrom: (text: string) => PlainTime
textstringrequired

the string to parse

returnsPlainTime

the time

plainTimeFromOrNull

plainTimeFrom, answering null instead of panicking on a string it refuses. Not part of Temporal.

const plainTimeFromOrNull: (
  text: string,
) => PlainTime | null
textstringrequired

the string to parse

returnsPlainTime | null

the time, or null

Classes

Duration

A length of time in ten signed fields: Temporal.Duration. A duration is not balanced: PT90M keeps its 90 minutes. Every non-zero field has the same sign.

class Duration
Member
new Duration(years: i64 = 0, months: i64 = 0, weeks: i64 = 0, days: i64 = 0, hours: i64 = 0, minutes: i64 = 0, seconds: i64 = 0, milliseconds: i64 = 0, microseconds: i64 = 0, nanoseconds: i64 = 0) The duration, as new Temporal.Duration(...); every field defaults to 0. Panics with a RangeError when two fields have different signs, when years, months or weeks reaches 2^32, or when the rest comes to 2^53 seconds or more.
readonly blank: boolean Whether every field is zero.
readonly days: i64 Days.
readonly hours: i64 Hours.
readonly microseconds: i64 Microseconds.
readonly milliseconds: i64 Milliseconds.
readonly minutes: i64 Minutes.
readonly months: i64 Months.
readonly nanoseconds: i64 Nanoseconds.
readonly seconds: i64 Seconds.
readonly sign: i32 -1, 0 or 1: the sign every non-zero field shares.
readonly weeks: i64 Weeks.
readonly years: i64 Years.
abs(): Duration This duration with every field made non-negative.
add(other: Duration): Duration The sum of this duration and other, balanced up to the larger of the two's largest non-zero unit, as Temporal's Duration.prototype.add balances it (P1D plus PT25H is P2DT1H). Panics with a RangeError when either has years, months or weeks, whose length depends on a date.
negated(): Duration This duration with every field's sign flipped.
subtract(other: Duration): Duration This duration minus other: add of its negation.
toJSON(): string The same string as toString.
toString(): string The duration as ISO 8601 writes it: P1Y2M3W4DT5H6M7.008S, -PT90M, and PT0S when blank. The seconds and their fractions are written as one decimal number, so PT1.5S reads back as 1 second and 500 milliseconds.

Instant

An exact point on the UTC timeline, to the nanosecond: Temporal.Instant. It has no calendar and no time zone; toString writes it in UTC.

class Instant
Member
new Instant(epochSeconds: i64, nanoseconds: i64 = 0) The instant epochSeconds seconds and nanoseconds nanoseconds after the epoch. This is this module's constructor, not Temporal's, whose new Temporal.Instant(epochNanoseconds) takes a bigint; use instantFromEpochMilliseconds or instantFrom for a portable program. Panics with a RangeError outside ±10^8 days of the epoch.
readonly epochMilliseconds: f64 Milliseconds since 1970-01-01T00:00:00Z, rounded toward negative infinity.
add(duration: Duration): Instant This instant moved by duration, which may hold hours and smaller units only: a day is not always 24 hours once a zone is involved, so Temporal refuses days and larger units here, and so does this, with a RangeError.
equals(other: Instant): boolean Whether other is the same instant.
since(other: Instant): Duration The time from other to this instant: other.until(this).
subtract(duration: Duration): Instant This instant moved back by duration: add of its negation.
toJSON(): string The same string as toString.
toString(): string The instant in UTC as Temporal writes it: 2024-01-15T09:05:00Z, with the fraction of the second to as many digits as it needs.
until(other: Instant): Duration The time from this instant to other in seconds and smaller units (Temporal's default largestUnit: "second").

PlainDate

A calendar date with no time and no time zone: Temporal.PlainDate in the ISO 8601 calendar. Every field is Temporal's getter of the same name.

class PlainDate
Member
new PlainDate(isoYear: i32, isoMonth: i32, isoDay: i32) The date isoYear-isoMonth-isoDay, as new Temporal.PlainDate(y, m, d). Panics with a RangeError when the fields name no date, or one outside Temporal's range of -271821-04-19 to +275760-09-13.
readonly calendarId: string The calendar, always iso8601.
readonly day: i32 The day of the month, from 1.
readonly dayOfWeek: i32 The weekday, 1 for Monday to 7 for Sunday.
readonly dayOfYear: i32 The day of the year, 1 for 1 January.
readonly daysInMonth: i32 Days in this date's month.
readonly daysInWeek: i32 Days in a week: 7.
readonly daysInYear: i32 Days in this date's year: 365 or 366.
readonly inLeapYear: boolean Whether this date's year is a leap year.
readonly month: i32 The month, 1 to 12.
readonly monthCode: string The month as Temporal codes it: M01 to M12.
readonly monthsInYear: i32 Months in a year: 12.
readonly weekOfYear: i32 The ISO week number, 1 to 53.
readonly year: i32 The year; negative before 1 BCE's year 0.
readonly yearOfWeek: i32 The year the ISO week belongs to, which differs from year near New Year.
add(duration: Duration): PlainDate This date moved by duration: its years and months first, with a day past the end of the new month moved back to its last day (Temporal's overflow: "constrain"), then its weeks and days, then whole days of its time fields. Panics with a RangeError when the answer is outside Temporal's range.
equals(other: PlainDate): boolean Whether other is the same date.
since(other: PlainDate): Duration The days from other to this date: other.until(this).
subtract(duration: Duration): PlainDate This date moved back by duration: add of its negation.
toJSON(): string The same string as toString, which is what JSON.stringify writes.
toPlainDateTime(time: PlainTime): PlainDateTime This date at time.
toString(): string The date as Temporal writes it: 2024-01-15, or +012345-01-15 for a year past 9999 or before 0.
until(other: PlainDate): Duration The days from this date to other, as a duration of days alone (Temporal's default largestUnit: "day"); negative when other is earlier.

PlainDateTime

A date and a time of day with no time zone: Temporal.PlainDateTime in the ISO 8601 calendar. It has every field of PlainDate and of PlainTime.

class PlainDateTime
Member
new PlainDateTime(isoYear: i32, isoMonth: i32, isoDay: i32, hour: i32 = 0, minute: i32 = 0, second: i32 = 0, millisecond: i32 = 0, microsecond: i32 = 0, nanosecond: i32 = 0) The date-time, as new Temporal.PlainDateTime(...); the time fields default to 0. Panics with a RangeError on a field out of range, or a moment outside Temporal's range of -271821-04-19T00:00:00.000000001 to +275760-09-13T23:59:59.999999999.
readonly calendarId: string The calendar, always iso8601.
readonly day: i32 The day of the month, from 1.
readonly dayOfWeek: i32 The weekday, 1 for Monday to 7 for Sunday.
readonly dayOfYear: i32 The day of the year, 1 for 1 January.
readonly daysInMonth: i32 Days in this date's month.
readonly daysInWeek: i32 Days in a week: 7.
readonly daysInYear: i32 Days in this date's year: 365 or 366.
readonly hour: i32 The hour, 0 to 23.
readonly inLeapYear: boolean Whether this date's year is a leap year.
readonly microsecond: i32 The microsecond, 0 to 999.
readonly millisecond: i32 The millisecond, 0 to 999.
readonly minute: i32 The minute, 0 to 59.
readonly month: i32 The month, 1 to 12.
readonly monthCode: string The month as Temporal codes it: M01 to M12.
readonly monthsInYear: i32 Months in a year: 12.
readonly nanosecond: i32 The nanosecond, 0 to 999.
readonly second: i32 The second, 0 to 59.
readonly weekOfYear: i32 The ISO week number, 1 to 53.
readonly year: i32 The year.
readonly yearOfWeek: i32 The year the ISO week belongs to.
add(duration: Duration): PlainDateTime This date-time moved by duration: the time fields first, carrying whole days, then the years and months with the day constrained to the new month, then the weeks, the days and the carried days — Temporal's AddDurationToDateTime. Panics with a RangeError outside Temporal's range.
equals(other: PlainDateTime): boolean Whether other is the same date-time.
since(other: PlainDateTime): Duration The time from other to this date-time: other.until(this).
subtract(duration: Duration): PlainDateTime This date-time moved back by duration: add of its negation.
toJSON(): string The same string as toString.
toPlainDate(): PlainDate The date part.
toPlainTime(): PlainTime The time part.
toString(): string The date-time as Temporal writes it: 2024-01-15T09:05:00, with the fraction of the second to as many digits as it needs.
until(other: PlainDateTime): Duration The time from this date-time to other in days and smaller units (Temporal's default largestUnit: "day"), every field with one sign.
withPlainTime(time: PlainTime): PlainDateTime This date-time with its time replaced by time.

PlainTime

A time of day with no date and no time zone: Temporal.PlainTime.

class PlainTime
Member
new PlainTime(hour: i32 = 0, minute: i32 = 0, second: i32 = 0, millisecond: i32 = 0, microsecond: i32 = 0, nanosecond: i32 = 0) The time hour:minute:second.millisecond microsecond nanosecond, as new Temporal.PlainTime(...); every field defaults to 0, so new PlainTime() is midnight. Panics with a RangeError on a field out of range.
readonly hour: i32 The hour, 0 to 23.
readonly microsecond: i32 The microsecond, 0 to 999.
readonly millisecond: i32 The millisecond, 0 to 999.
readonly minute: i32 The minute, 0 to 59.
readonly nanosecond: i32 The nanosecond, 0 to 999.
readonly second: i32 The second, 0 to 59.
add(duration: Duration): PlainTime This time moved by the time fields of duration, wrapping past midnight; the years, months, weeks and days are ignored, as Temporal ignores them.
equals(other: PlainTime): boolean Whether other is the same time.
since(other: PlainTime): Duration The time from other to this time: other.until(this).
subtract(duration: Duration): PlainTime This time moved back by duration: add of its negation.
toJSON(): string The same string as toString.
toString(): string The time as Temporal writes it: 09:05:00, with the fraction of the second to as many digits as it needs (09:05:00.25).
until(other: PlainTime): Duration The time from this time to other on the same day, in hours and smaller units (Temporal's default largestUnit: "hour").