TypeScript – How to accurately type dates in ISO 8601 format

TS - More precise return type method Date#toISOString.d.ts

// In TS, interfaces are "open" and can be extended
interface Date {
  /**
   * Give a more precise return type to the method `toISOString()`:
   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
   */
  toISOString(): TDateISO;
}

type TYear         = `${number}${number}${number}${number}`;
type TMonth        = `${number}${number}`;
type TDay          = `${number}${number}`;
type THours        = `${number}${number}`;
type TMinutes      = `${number}${number}`;
type TSeconds      = `${number}${number}`;
type TMilliseconds = `${number}${number}${number}`;

/**
 * Represent a string like `2021-01-08`
 */
type TDateISODate = `${TYear}-${TMonth}-${TDay}`;

/**
 * Represent a string like `14:42:34.678`
 */
type TDateISOTime = `${THours}:${TMinutes}:${TSeconds}.${TMilliseconds}`;

/**
 * Represent a string like `2021-01-08T14:42:34.678Z` (format: ISO 8601).
 *
 * It is not possible to type more precisely (list every possible values for months, hours etc) as
 * it would result in a warning from TypeScript:
 *   "Expression produces a union type that is too complex to represent. ts(2590)
 */
type TDateISO = `${TDateISODate}T${TDateISOTime}Z`;

Here's what I've been using:

type oneToNine = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
type d = oneToNine | 0;
type YYYY = `19${d}${d}` | `20${d}${d}`;
type MM = `0${oneToNine}` | `1${0 | 1 | 2}`;
type DD = `${0}${oneToNine}` | `${1 | 2}${d}` | `3${0 | 1}`;
type DateYMString = `${YYYY}-${MM}`;
type THours = `${number}${number}`;
type TMinutes = `${number}${number}`;
type TSeconds = `${number}${number}`;
type TMilliseconds = `${number}${number}${number}`;

// type: DateYMD ex. "2021-01-01"
export type DateYMD = `${DateYMString}-${DD}`;

/**
 * type: TDateISOTime ex. "14:42:34.678"
 */
type TDateISOTime = `${THours}:${TMinutes}:${TSeconds}.${TMilliseconds}`;

/**
 * type: DateYMDZoneString ex. "2021-01-01T14:42:34.678Z"
 */
export type ISO8601 = `${DateYMD}T${TDateISOTime}Z`;

My aim was not to make this perfect but to help point people in the right direction.

This approach is somewhat flawed. ISODate isn't a type—it's a format. The actual type would still be a string.

According to the ISO 8601 standard, timezones can include a Z to indicate UTC or an offset.. For example, you could define a type like this:

type TDateISODateTimeZone = 'Z' | `+${THours}:${TMinutes}` | `-${THours}:${TMinutes}`;

The Offset can actually be empty (eg. 2021-01-01T14:42:34.678) which is implicit +0 = Z.

That said, it's important to differentiate between types and validators. What you’re really looking for here is a validator, such as:

// sadly will say true for `2021-01-01T14:42:34.678ZASDFADFADF` as well
moment(value, moment.ISO_8601, true).isValid();

In my opinion, it's best to avoid relying heavily on ISODate formats. Instead, work with Date objects in your application logic, and if you need to transfer data, use a more reliable format like epoch milliseconds (UTC).

I'm currently just using:

export function isValidISODate(value: string): value is ReturnType<typeof Date.prototype.toISOString> {
  const byMoment: boolean = moment(value, moment.ISO_8601, true).isValid(); // tests only format, not if date is valid
  const byJs: boolean = Number.isSafeInteger(new Date(value).getTime()); // getTime can return NaN or non-safe-integers but isSafeInteger doesnt allow non-safe-integer nor NaN nor Infinity.
  return byJs && byMoment;
}

If Typescript ever decided to add a type for ISODate (highly doubt that) then this method would just return it as is.