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

Install

$ npm install iso8601-duration

Usage

Interface

export const toSeconds; // fn = obj => number
export const pattern;   // ISO8601 RegExp
export const parse;     // fn = string => obj
export default {
	toSeconds,
	pattern,
	parse
}

Example

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

const getWithSensibleDUrations = someApiEndpoint => {
	// return promise
	return new Promise(resolve => {
		// fetch text
		fetch('some-api-endpoint')
			.then(res => res.text())
			.then(jsonString => {
				// convert iso8601 durations to total seconds
				// create new pattern that matche son surrounding double-quotes
				const pattern = new RegExp(`\\"${pattern.source}\\"`, 'g');
				jsonString = jsonString.replace(pattern, m => {
					return toSeconds(parse(m));
				});
				// resolve original request with sensible durations
				resolve( JSON.parse(jsonString) );
		});
	});
}

License

MIT © Tobias Lundin