isoformat

library0.2.1jsnpmunverified

isoformat is a JavaScript library designed for concise formatting and parsing of ISO 8601 date and date-time strings. It aims to provide a 'tidier' alternative to the standard `Date.toISOString()` by returning the shortest equivalent UTC string for formatting, and offering flexible parsing of common ISO forms. The current stable version is v0.2.1, indicating a library that is actively maintained with recent minor releases, focusing on usability and adherence to specific subsets of the ISO 8601 standard. Key differentiators include its focus on minimal output for `format` (e.g., explicitly excluding YYYY or YYYY-MM forms) and a more permissive `parse` function that handles various ISO 8601 date and time formats, including different timezone offsets and even the widely supported but non-standard -00:00, while explicitly not supporting two-digit time zone offsets (+HH or -HH).

serialization

npm install isoformat

github ↗package ↗

INSTALL

IMPORT

SIG · ISOFORMAT

isoformat

serializationjavascriptv0.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

format

✓ import { format } from 'isoformat'

✗ import format from 'isoformat'

`format` was changed from a default export to a named export in v0.2.0. Using the old default import will result in a runtime error.

parse

✓ import { parse } from 'isoformat'

✗ const parse = require('isoformat').parse

While CommonJS `require` might be coerced by bundlers, the library's primary intended usage is with ESM named imports.

All exports

✓ import * as isoformat from 'isoformat'

✗ const isoformat = require('isoformat')

For environments strictly enforcing ESM, `require` will fail. Use named imports or `import * as` for broader compatibility in modern JavaScript.

Demonstrates how to format Date objects into concise ISO 8601 strings and parse various ISO strings back into Date objects, including handling invalid inputs with fallbacks.

import { format, parse } from 'isoformat'; // Format a Date object to a concise ISO 8601 UTC string const date1 = new Date(Date.UTC(2001, 0, 1)); const formattedDate1 = format(date1); // "2001-01-01" console.log(`Formatted date 1: ${formattedDate1}`); const date2 = new Date(Date.UTC(2020, 0, 1, 12, 23, 45, 123)); const formattedDate2 = format(date2); // "2020-01-01T12:23:45.123Z" console.log(`Formatted date 2: ${formattedDate2}`); // Format an invalid date, providing a fallback string const invalidDateFormatted = format(new Date('invalid date'), 'N/A'); console.log(`Formatted invalid date: ${invalidDateFormatted}`); // Parse an ISO 8601 string back into a Date object const parsedDate1 = parse("2001-01-01"); console.log(`Parsed date 1: ${parsedDate1.toISOString()}`); const parsedDate2 = parse("2020-01-01T12:23Z"); console.log(`Parsed date 2: ${parsedDate2.toISOString()}`); // Parse an invalid string, providing a fallback value (undefined by default) const invalidStringParsed = parse("not-an-iso-string", null); console.log(`Parsed invalid string: ${invalidStringParsed}`);

Debug

Known issues

breakingThe `format` function, previously a default export, is now a named export. Direct default imports will fail.

fix

Change your import statement from `import format from 'isoformat'` to `import { format } from 'isoformat'`.

affects: >=0.2.0

breakingThe `format` function now returns `undefined` for invalid Date instances instead of the string `'Invalid Date'`. If your application relies on the specific string, it will break.

fix

Update your code to handle `undefined` return values or provide a `fallback` argument to the `format` function (e.g., `format(date, 'Invalid Date')`).

affects: >=0.2.0

gotchaThe `format` function only returns specific, terse ISO 8601 forms (e.g., YYYY-MM-DD, YYYY-MM-DDTHH:MMZ, etc.) and explicitly *does not* return YYYY or YYYY-MM forms to avoid ambiguity or oversimplification.

fix

If YYYY or YYYY-MM formats are required, you will need to manually construct these strings from the Date object or use a different formatting library.

affects: >=0.1.0

gotchaThe `parse` function does not support two-digit time zone offsets like `+HH` or `-HH` (e.g., `2024-01-01+05`), despite them being part of ISO 8601, due to inconsistent browser/Node support.

fix

Ensure that any ISO 8601 strings passed to `parse` use supported time zone offset formats (Z, +HH:MM, -HH:MM, +HHMM, or -HHMM).

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: (0 , isoformat__WEBPACK_IMPORTED_MODULE_0__.format) is not a function

Attempting to use `format` as a named import when it was imported as a default, or vice versa, especially after the v0.2.0 breaking change.

fix

Ensure your import statement for `format` is `import { format } from 'isoformat'`. If using CommonJS, consider modernizing to ESM or explicitly accessing `require('isoformat').format`.

My date formatting now returns `undefined` instead of `'Invalid Date'`.

The `format` function's behavior for invalid dates changed in v0.2.0; it now returns `undefined` by default instead of the string `'Invalid Date'`.

fix

Update your code to check for `undefined` or provide a `fallback` argument to the `format` function, e.g., `format(myDate, 'Invalid Date')`.

`parse("2024-01-01+05").getTime()` returns `NaN`

The input ISO 8601 string contains a time zone offset in the unsupported `+HH` or `-HH` format.

fix

Modify the input string to use a supported time zone offset format, such as `2024-01-01T00:00:00+05:00` or `2024-01-01Z`.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mbostock/isoformat ↗

packagehttps://www.npmjs.com/package/isoformat ↗