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;
};
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.
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).
durationFromOrNull
durationFrom, answering null instead of panicking on a string it refuses.
instantCompare
Temporal.Instant.compare(a, b): -1, 0 or 1 as a is before, the same as, or after b.
instantFrom
Temporal.Instant.from(text): the instant an RFC 9557 string names.
instantFromEpochMilliseconds
Temporal.Instant.fromEpochMilliseconds(ms): the instant ms milliseconds after 1970-01-01T00:00:00Z.
instantFromOrNull
instantFrom, answering null instead of panicking on a string it refuses.
nowInstant
Temporal.Now.instant(): the wall clock now, to the nanosecond the operating system reports.
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.
plainDateFrom
Temporal.PlainDate.from(text): the date an RFC 9557 string names.
plainDateFromOrNull
plainDateFrom, answering null instead of panicking on a string it refuses.
plainDateTimeCompare
Temporal.PlainDateTime.compare(a, b): -1, 0 or 1 as a is before, the same as, or after b.
plainDateTimeFrom
Temporal.PlainDateTime.from(text): the date-time an RFC 9557 string names; a date alone is midnight.
plainDateTimeFromOrNull
plainDateTimeFrom, answering null instead of panicking on a string it refuses.
plainTimeCompare
Temporal.PlainTime.compare(a, b): -1, 0 or 1 as a is earlier than, the same as, or later than b.
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.
plainTimeFromOrNull
plainTimeFrom, answering null instead of panicking on a string it refuses.
Duration
A length of time in ten signed fields: Temporal.Duration.
Instant
An exact point on the UTC timeline, to the nanosecond: Temporal.Instant.
PlainDate
A calendar date with no time and no time zone: Temporal.PlainDate in the ISO 8601 calendar.
PlainDateTime
A date and a time of day with no time zone: Temporal.PlainDateTime in the ISO 8601 calendar.
PlainTime
A time of day with no date and no time zone: Temporal.PlainTime.
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
aDurationrequiredthe first duration
bDurationrequiredthe second duration
returnsi32the 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
textstringrequiredsuch as P1Y2M, PT36H or -P1DT0.5S
returnsDurationthe duration
durationFromOrNull
durationFrom, answering null instead of panicking on a string it
refuses. Not part of Temporal.
const durationFromOrNull: (text: string) => Duration | null
textstringrequiredthe string to parse
returnsDuration | nullthe 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
aInstantrequiredthe first instant
bInstantrequiredthe second instant
returnsi32the 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
textstringrequiredsuch as 2024-01-15T09:05:00Z
returnsInstantthe 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
msf64requiredmilliseconds since the epoch
returnsInstantthe instant
instantFromOrNull
instantFrom, answering null instead of panicking on a string it
refuses. Not part of Temporal.
const instantFromOrNull: (text: string) => Instant | null
textstringrequiredthe string to parse
returnsInstant | nullthe instant, or null
nowInstant
Temporal.Now.instant(): the wall clock now, to the nanosecond the
operating system reports. Capability: clock.
const nowInstant: () => Instant
returnsInstantthe 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
aPlainDaterequiredthe first date
bPlainDaterequiredthe second date
returnsi32the 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
textstringrequiredsuch as 2024-01-15, 20240115 or 2024-01-15T12:00[u-ca=iso8601]
returnsPlainDatethe date
plainDateFromOrNull
plainDateFrom, answering null instead of panicking on a string it
refuses. Not part of Temporal.
const plainDateFromOrNull: (
text: string,
) => PlainDate | null
textstringrequiredthe string to parse
returnsPlainDate | nullthe 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
aPlainDateTimerequiredthe first date-time
bPlainDateTimerequiredthe second date-time
returnsi32the 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
textstringrequiredsuch as 2024-01-15T09:05 or 2024-01-15 09:05:00.5
returnsPlainDateTimethe date-time
plainDateTimeFromOrNull
plainDateTimeFrom, answering null instead of panicking on a string it
refuses. Not part of Temporal.
const plainDateTimeFromOrNull: (
text: string,
) => PlainDateTime | null
textstringrequiredthe string to parse
returnsPlainDateTime | nullthe 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
aPlainTimerequiredthe first time
bPlainTimerequiredthe second time
returnsi32the 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
textstringrequiredthe string to parse
returnsPlainTimethe time
plainTimeFromOrNull
plainTimeFrom, answering null instead of panicking on a string it
refuses. Not part of Temporal.
const plainTimeFromOrNull: (
text: string,
) => PlainTime | null
textstringrequiredthe string to parse
returnsPlainTime | nullthe 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"). |

