TinyDuration
A small (< 1kb minified + gzipped ) javascript package to parse and serialize ISO-8601 durations.
This package does only 2 things:
It parses a duration string to an object
(e.g. P1DT12H to { days: 1, hours: 12 })
The reverse, i.e. serialize an object to a string.
This lib has 0 dependencies.
Installation
NPM: npm install --save tinyduration
Yarn: yarn add tinyduration
Usage
import { parse, serialize } from 'tinyduration'
// Basic parsing
const durationObj = parse ( 'P1Y2M3DT4H5M6S' )
assert (durationObj, {
years: 1 ,
months: 2 ,
days: 3 ,
hours: 4 ,
minutes: 5 ,
seconds: 6 ,
})
// Serialization
assert ( serialize (durationObj), 'P1Y2M3DT4H5M6S' ) copy
Development
This library is written in TypeScript .
During publication of the package, the code is transpiled to javascript and put into the dist folder.
The tests can be found the src folder under *.test.ts, testing is done using Jest
Additional commands you'll need for development:
npm test to run all tests
npm run lint to run the linter
npm run prettify to auto-fix the indenting issues
npm run ci to run coverage and linting
npx changeset to add a changeset
npx changeset version to adopt a changeset, prepping for release
npx changeset publish to publish to NPM
API
Type: Duration
Property Type Description negative boolean or undefinedDuration is positive if undefined years number or undefinedmonths number or undefinedweeks number or undefineddays number or undefinedhours number or undefinedminutes number or undefined
Type: ParseConfig
Property Type Description allowMultipleFractions boolean or undefinedDefaults to true.
Function: parse(durationStr: string, config: ParseConfig): Duration
parse accepts a string and returns a Duration object.
No attempt is made to change lower units into higher ones, e.g. to change 120 minutes into 2 hours.
Throws InvalidDurationError if an invalid duration string is supplied.
Throws MultipleFractionsError if an the duration string contains multiple fractions while disabled in the config.
According to the spec multiple fractions are not allowed. Currently this is not enforced and the allowMultipleFractions config parameter defaults to true.
import { parse } from 'tinyduration'
const duration = parse ( 'P1W' )
assert (duration, { weeks: 1 })
try {
parse ( 'invalid-duration' )
} catch (e) {
assert (e.message === 'Invalid duration' )
} copy
Function: serialize(Duration): string
serialize accepts a Duration object and returns a serialized duration according to ISO-8601.
If the duration is empty (i.e. all values are 0), PT0S is returned.
import * as Duration from 'tinyduration'
const durationStr = Duration. serialize ({ weeks: 1 })
assert (durationStr, 'P1W' )
const durationStr = Duration. serialize ({})
assert (durationStr, 'PT0S' ) copy
License
MIT