!cute animal nomming on carrot

Nominal Date Types

A library of TypeScript types related to Javascript Date.

The types add type safety to various strings and numbers used to serialize or calculate with Date values.
This provides support for conversion and validation, but only minimal support for calculation.

This library has no runtime dependencies.

DateLike

This is a union type of built-in representations of a moment in time.
It includes Date, number of milliseconds since UNIX epoch, and string ISO timestamps.

$3

Returns or constructs a Date object from DateLike.

Timestamp

This is a type for strings obtained from Date.toISOString().

$3

Type-guard for x being a valid string representing a Timestamp.

$3

Returns a Timestamp representing the current moment in time.

$3

Returns x if it represents a valid Timestamp string, null otherwise.

$3

Returns x if it represents a valid Timestamp string, and throws otherwise.

$3

Converts a valid DateLike to Timestamp.

DurationMs

DurationMs is a type for numbers that represents duration as a number of milliseconds.

$3

Type-guard for x being a valid number that represents a DurationMs.
Succeeds for any number.

$3

Returns a DurationMs given a DurationSpec:

``
export interface DurationSpec {
days?: number;
hours?: number;
minutes?: number;
seconds?: number;
ms?: number;
}
`

Negative values are supported.

EpochMs

EpochMs is a type for numbers that represents a number of milliseconds since the UNIX epoch (midnight, Jan 1, 1970, UTC).
This has the same semantics as Date.now().

$3

Type-guard for x being a valid number that represents an EpochMs.
Succeeds for any number.

$3

Returns an EpochMs representing the current moment in time.

$3

Converts a valid DateLike to EpochMs.

DurationCalc

A namespace of functions for calculating with DurationMs and EpochMs.

$3

Returns base + duration, works for negative values.

$3

Returns end - start, works for negative values.
Note the order is opposite subtraction--if the earlier EpochMs comes first the result is positive.

$3

Returns the sum of zero or more DurationMs.

$3

Negates a DurationMs.

$3

Returns the maximum of DurationMss or EpochMss.
Note, arguments must all be of the same type.

$3

Returns the minimum of DurationMss or EpochMss.
Note, arguments must all be of the same type.

CalendarDay

CalendarDay is a type for strings that represents a particular calendar day in the form "YYYY-MM-DD".
It is a goal that this type be sortable, so values are restricted to positive years with 4 digits.

$3

A Timestamp representing the earliest valid CalendarDay.

$3

A Timestamp representing the latest valid CalendarDay.

$3

An EpochMs representing the earliest valid CalendarDay.

$3

An EpochMs representing the latest valid CalendarDay.

$3

For use in date calculations via EpochMs and DurationMs.
Returns an EpochMs between MIN_EPOCH_MS and MAX_EPOCH_MS inclusive that represents the closest EpochMs that falls in the range of valid CalendarDays.

$3

Type-guard for x being a valid string that represents a CalendarDay.

$3

Returns x if it represents a valid CalendarDay string, null otherwise.

$3

Returns x if it represents a valid CalendarDay string, and throws otherwise.

$3

Converts a valid DateLike to CalendarDay.

CalendarMonth and CalendarYear

Experimental.
These have the same semantics as CalendarDay` except for month and year respectively, and support the same set of functions.