mbostock / isoformat

Formats dates as the shortest equivalent ISO 8601 UTC string

isoformat

This library implements a concise formatter and parser for ISO 8601 date and date-times. It is intended for use as an interchange format, for example in CSV, that is more human-readable than the full ISO date-time string used by date.toISOString.

To use:

import {format, parse} from "isoformat";

format(date, fallback)

Given a Date, format(date) returns the shortest equivalent ISO 8601 UTC string. If date is not a Date instance, it is assumed to represent milliseconds since UNIX epoch. If date is not a valid date, returns the given fallback value, which defaults to undefined; if fallback is a function, it is invoked to produce a fallback value if needed, being passed the date.

format(new Date(Date.UTC(2001, 0, 1))) // "2001-01-01"
format(new Date(Date.UTC(2020, 0, 1, 12, 23))) // "2020-01-01T12:23Z"

The following forms may be returned by format:

• YYYY-MM-DD
• YYYY-MM-DDTHH:MMZ
• YYYY-MM-DDTHH:MM:SSZ
• YYYY-MM-DDTHH:MM:SS.MMMZ

The year YYYY may also be represented as +YYYYYY or -YYYYYY. Note that while YYYY and YYYY-MM are valid ISO 8601 date strings, these forms are never returned by format; YYYY can be easily misinterpreted as a number, and YYYY-MM… well, I guess that would be okay, but it felt simpler to stop at YYYY-MM-DD to make it more obvious that it was a date.

parse(date, fallback)

Given an ISO 8601 date or date-time string, parse(string) returns an equivalent Date instance. If string is not a valid ISO 8601 date or date-time string, returns the given fallback value, which defaults to undefined; if fallback is a function, it is invoked to produce a fallback value if needed, being passed the string.

parse("2001-01-01") // new Date(Date.UTC(2001, 0, 1))
parse("2020-01-01T12:23Z") // new Date(Date.UTC(2020, 0, 1, 12, 23))

The following forms are accepted by parse:

• YYYY
• YYYY-MM
• YYYY-MM-DD
• YYYY-MM-DDTHH:MM
• YYYY-MM-DDTHH:MMZ
• YYYY-MM-DDTHH:MM:SS
• YYYY-MM-DDTHH:MM:SSZ
• YYYY-MM-DDTHH:MM:SS.MMM
• YYYY-MM-DDTHH:MM:SS.MMMZ

The year YYYY may also be represented as +YYYYYY or -YYYYYY. The time zone Z may be represented as a literal Z for UTC, or as +HH:MM, -HH:MM, +HHMM, or -HHMM. (The two-digit time zone offset +HH or -HH is not supported; although part of ISO 8601, this format is not recognized by Chrome or Node. And although ISO 8601 does not allow the time zone -00:00, it is allowed here because it is widely supported in implementations.)