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 ISO8601-durations

A new standard is on it's way, see Temporal.Duration

The ISO8601 duration format

Durations in ISO8601 comes in two formats:

• PnYnMnDTnHnMnS - 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
• PnW - the week format

Check out the details on Wikipedia

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;   // ISO8601 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/