iso8601-duration

What is iso8601-duration?

The iso8601-duration npm package is a utility for parsing, encoding, and manipulating ISO 8601 durations. It provides a simple interface to work with durations specified in the ISO 8601 format, which is commonly used in various applications and systems for representing time intervals.

What are iso8601-duration's main functionalities?

Parsing ISO 8601 Duration Strings

This feature allows you to parse an ISO 8601 duration string into a JavaScript object. The parsed object contains properties for years, months, days, hours, minutes, and seconds.

const iso8601Duration = require('iso8601-duration');
const duration = iso8601Duration.parse('P1Y2M10DT2H30M');
console.log(duration);

Encoding Durations to ISO 8601 Strings

This feature allows you to encode a JavaScript object representing a duration into an ISO 8601 duration string.

const iso8601Duration = require('iso8601-duration');
const duration = { years: 1, months: 2, days: 10, hours: 2, minutes: 30 };
const durationString = iso8601Duration.encode(duration);
console.log(durationString);

Adding Durations

This feature allows you to add two durations together, resulting in a new duration object.

const iso8601Duration = require('iso8601-duration');
const duration1 = iso8601Duration.parse('P1Y2M10DT2H30M');
const duration2 = iso8601Duration.parse('P0Y1M5DT1H15M');
const addedDuration = iso8601Duration.add(duration1, duration2);
console.log(addedDuration);

Subtracting Durations

This feature allows you to subtract one duration from another, resulting in a new duration object.

const iso8601Duration = require('iso8601-duration');
const duration1 = iso8601Duration.parse('P1Y2M10DT2H30M');
const duration2 = iso8601Duration.parse('P0Y1M5DT1H15M');
const subtractedDuration = iso8601Duration.subtract(duration1, duration2);
console.log(subtractedDuration);

Other packages similar to iso8601-duration

moment

Moment.js is a widely-used library for parsing, validating, manipulating, and formatting dates and times in JavaScript. While it is more comprehensive than iso8601-duration, it also supports ISO 8601 durations through its duration function. However, Moment.js is a larger library and may be overkill if you only need to work with durations.

luxon

Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It provides a more modern API and better performance. Luxon also supports ISO 8601 durations through its Duration class, offering similar functionality to iso8601-duration but with a more extensive feature set for date and time manipulation.

date-fns

date-fns is a lightweight library for date and time manipulation in JavaScript. It provides a wide range of functions for working with dates and times, including support for ISO 8601 durations. date-fns is modular, allowing you to include only the functions you need, making it a good choice for projects where bundle size is a concern.

README

ISO8601-duration

Node/Js-module for parsing and making sense of ISO 8601 durations

A new standard is on it's way, see Temporal.Duration
Tests (most) in this module now validate against @js-temporal/polyfill

The ISO 8601 duration format

TL;DR
PnYnMnWnDTnHnMnS - P<date>T<time>.
(P) Years, Months, Weeks, Days (T) Hours, Minutes, Seconds.
Example: P1Y1M1DT1H1M1.1S = One year, one month, one day, one hour, one minute, one second, and 100 milliseconds

Durations in ISO 8601 comes in 2 variants:

ISO 8601-1
Weeks are not allowed to appear together with any other units and durations can only be positive (used until v2.0.0 in this module).
Valid patterns with weeks: P2W.
Invalid patterns with weeks: P2W2D.

ISO 8601-2
An extension to the standard, allows combining weeks with other units (supported since v2.1.0 in this module).
Valid patterns with weeks: P2W & P2W2DT5H, etc.

ISO 8601-2 also allows for a sign character at the start of the string (-P1D, +P1M), this is not yet supported by this module.

PnYnMnWnDTnHnMnS - P<date>T<time>

• The n is replaced by the value for each of the date and time elements that follow the n.
• Leading zeros are not required.
• Fractions are allowed on the smallest unit in the string, e.g. P0.5D or PT1.0001S but not PT0.5M0.1S.

Check out the details on Wikipedia or in the coming Temporal.Duration spec.

Install

npm install iso8601-duration

Usage

Most noteworthy of the interface is the ability to provide a date for toSeconds-calculations.
Why becomes evident when working with durations that span dates as all months are not equally long.
E.g January of 2016 is 744 hours compared to the 696 hours of February 2016.

If a date is not provided for toSeconds the timestamp Date.now() is used as baseline.

Interface

export const toSeconds; // fn = (obj, date?) => number
export const pattern;   // ISO 8601 RegExp
export const parse;     // fn = string => obj
export default {
	toSeconds,
	pattern,
	parse
}

Example

Simple usage

import { parse, end, toSeconds, pattern } from "iso8601-duration";

console.log(parse("P1Y2M4DT20H44M12.67S"));
/* outputs =>
{
	years: 1,
	months: 2,
	days: 4,
	hours: 20,
	minutes: 44,
	seconds: 12.67
}
*/

console.log(toSeconds(parse("PT1H30M10.5S")));
// outputs => 5410.5

console.log(end(parse("P1D")));
// outputs => DateObj 2017-10-04T10:14:50.190Z

A more complete usecase / example

import { parse, toSeconds, pattern } from "iso8601-duration";

// convert iso8601 duration-strings to total seconds from some api
const getWithSensibleDurations = (someApiEndpoint) => {
  // return promise, like fetch does
  return new Promise((resolve) => {
    // fetch text
    fetch(someApiEndpoint)
      .then((res) => res.text())
      .then((jsonString) => {
        // create new pattern that matches on surrounding double-quotes
        // so we can replace the string with an actual number
        const replacePattern = new RegExp(`\\"${pattern.source}\\"`, "g");
        jsonString = jsonString.replace(replacePattern, (m) => {
          return toSeconds(parse(m));
        });
        // resolve original request with sensible durations in object
        resolve(JSON.parse(jsonString));
      });
  });
};

License

MIT @ https://tolu.mit-license.org/