{"id":13357,"library":"isoformat","title":"isoformat","description":"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).","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/mbostock/isoformat","tags":["javascript"],"install":[{"cmd":"npm install isoformat","lang":"bash","label":"npm"},{"cmd":"yarn add isoformat","lang":"bash","label":"yarn"},{"cmd":"pnpm add isoformat","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`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.","wrong":"import format from 'isoformat'","symbol":"format","correct":"import { format } from 'isoformat'"},{"note":"While CommonJS `require` might be coerced by bundlers, the library's primary intended usage is with ESM named imports.","wrong":"const parse = require('isoformat').parse","symbol":"parse","correct":"import { parse } from 'isoformat'"},{"note":"For environments strictly enforcing ESM, `require` will fail. Use named imports or `import * as` for broader compatibility in modern JavaScript.","wrong":"const isoformat = require('isoformat')","symbol":"All exports","correct":"import * as isoformat from 'isoformat'"}],"quickstart":{"code":"import { format, parse } from 'isoformat';\n\n// Format a Date object to a concise ISO 8601 UTC string\nconst date1 = new Date(Date.UTC(2001, 0, 1));\nconst formattedDate1 = format(date1); // \"2001-01-01\"\nconsole.log(`Formatted date 1: ${formattedDate1}`);\n\nconst date2 = new Date(Date.UTC(2020, 0, 1, 12, 23, 45, 123));\nconst formattedDate2 = format(date2); // \"2020-01-01T12:23:45.123Z\"\nconsole.log(`Formatted date 2: ${formattedDate2}`);\n\n// Format an invalid date, providing a fallback string\nconst invalidDateFormatted = format(new Date('invalid date'), 'N/A');\nconsole.log(`Formatted invalid date: ${invalidDateFormatted}`);\n\n// Parse an ISO 8601 string back into a Date object\nconst parsedDate1 = parse(\"2001-01-01\");\nconsole.log(`Parsed date 1: ${parsedDate1.toISOString()}`);\n\nconst parsedDate2 = parse(\"2020-01-01T12:23Z\");\nconsole.log(`Parsed date 2: ${parsedDate2.toISOString()}`);\n\n// Parse an invalid string, providing a fallback value (undefined by default)\nconst invalidStringParsed = parse(\"not-an-iso-string\", null);\nconsole.log(`Parsed invalid string: ${invalidStringParsed}`);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Change your import statement from `import format from 'isoformat'` to `import { format } from 'isoformat'`.","message":"The `format` function, previously a default export, is now a named export. Direct default imports will fail.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Update your code to handle `undefined` return values or provide a `fallback` argument to the `format` function (e.g., `format(date, 'Invalid Date')`).","message":"The `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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure that any ISO 8601 strings passed to `parse` use supported time zone offset formats (Z, +HH:MM, -HH:MM, +HHMM, or -HHMM).","message":"The `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.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"TypeError: (0 , isoformat__WEBPACK_IMPORTED_MODULE_0__.format) is not a function"},{"fix":"Update your code to check for `undefined` or provide a `fallback` argument to the `format` function, e.g., `format(myDate, 'Invalid Date')`.","cause":"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'`.","error":"My date formatting now returns `undefined` instead of `'Invalid Date'`."},{"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`.","cause":"The input ISO 8601 string contains a time zone offset in the unsupported `+HH` or `-HH` format.","error":"`parse(\"2024-01-01+05\").getTime()` returns `NaN`"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}