io-ts-datetime

io-ts codec types for dates, datetimes using luxon date time library

Install

npm i io-ts-datetime

Note. luxon, fp-ts, and io-ts are peer dependencies for io-ts-datetime

Usage

dateTimeFromDate(decodeOptions, encodeOptions)

returns a codec that decodes DateTime from a Date instance and encodes back to a string.

decodeOptions

• zone - (string | Zone) (default 'local') use this zone if no offset is specified in the input string itself. Will also convert the time to this zone

encodeOptions

the same as below

dateTimeFromFormat(decodeOptions, encodeOptions)

returns a codec that decodes DateTime from a string and encodes back to a string.

When decodeOptions or encodeOptions are ommited the ISO DateTime format will be used.

When decodeOptions set but encodeOptions are omitted will encode into the same format as set in decodeOptions

decodeOptions

• format - "ISO", "SQL", string format. For format tokens look into table of tokens
• zone - (string | Zone) (default 'local') use this zone if no offset is specified in the input string itself. Will also convert the time to this zone
• setZone - boolean (default false) override the zone with a fixed-offset zone specified in the string itself, if it specifies one
• locale - string (default 'system'slocale') a locale to set on the resulting DateTime instance
• outputCalendar - string the output calendar to set on the resulting DateTime instance
• numberingSystem - string the numbering system to set on the resulting DateTime instance

encodeOptions

• format - "ISODate", "ISO", "Basic", "Extended", "SQL", string format. For format tokens look into table of tokens
  • "Extended" is the same as "ISO"
  • "Basic" is ISO format without - and : delimeters

Other encode options depend on the format.

• ISODate - there is no additional options
• ISO, Basic, Extended - accepts all toISO method options
  • suppressSeconds - boolean (default false) exclude seconds from the format if they're 0
  • suppressMilliseconds - boolean (default false) exclude milliseconds from the format if they're 0
  • includeOffset - boolean (default true) include the offset, such as 'Z' or '-04:00'
  • extendedZone - boolean (default false) add the time zone format extension
• SQL - accepts all toSQL method options
  • includeZone - boolean (default false) include the zone, such as 'America/New_York'. Overrides includeOffset.
  • includeOffset - boolean (default true) include the offset, such as 'Z' or '-04:00'
  • includeOffsetSpace - boolean (default true) include the space between the time and the offset, such as '05:15:16.345 -04:00'
• Custom format - accepts all toFormat method options to override the configuration options on this DateTime

Example

const ISOCodec = dateTimeFromFormat();
const dateTime = ISOCodec.decode("2023-03-14T14:25:22.663-04:00").right;
const isoString = ISOCodec.encode(dateTime);
// "2023-03-14T14:25:22.663-04:00"

const SQLCodec = dateTimeFromFormat({ format: "SQL" }, { format: "ISODate" });
const dateTime = SQLCodec.decode("2023-03-14 14:25:22").right;
const isoDateString = SQLCodec.encode(dateTime);
// "2023-03-14"

From and To Number

There are two extra helper codecs for the cases when date has to be a number.

fromNumber

wraps the codec to validate the input as number and passes it through down to codec as a string for future parsing

toNumber

wraps the codec to represent encode results as a number

const codec = dateTimeFromFormat(
  { format: "yyyyMMdd" },
  { format: "yyyyMMdd" },
);

const dateFromNumber = fromNumber(codec);
const dateToNumber = toNumber(codec);
const dateFromAndToNumber = toNumber(dateFromNumber);

License

MIT