ISO-8601 duration parsing and serialization
npm install tinydurationA small (< 1kb minified + gzipped) javascript package to parse and serialize ISO-8601 durations.
This package does only 2 things:
1. It parses a duration string to an object
- (e.g. P1DT12H to { days: 1, hours: 12 })
2. The reverse, i.e. serialize an object to a string.
This lib has 0 dependencies.
- NPM: npm install --save tinyduration
- Yarn: yarn add tinyduration
``js
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')
`
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 testsnpm run lint
- to run the linternpm run prettify
- to auto-fix the indenting issuesnpm run ci
- to run coverage and lintingnpx changeset
- to add a changesetnpx changeset version
- to adopt a changeset, prepping for releasenpx changeset publish
- to publish to NPM
| Property | Type | Description |
| -------- | ------------------------ | --------------------------------- |
| negative | boolean or undefined | Duration is positive if undefined |number
| years | or undefined | |number
| months | or undefined | |number
| weeks | or undefined | |number
| days | or undefined | |number
| hours | or undefined | |number
| minutes | or undefined | |number
| seconds | or undefined | |
| Property | Type | Description |
| ---------------------- | ------------------------ | ------------------- |
| allowMultipleFractions | boolean or undefined | Defaults to true. |
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.allowMultipleFractions
According to the spec multiple fractions are not allowed. Currently this is not enforced and the config parameter defaults to true.
`js
import { parse } from 'tinyduration'
const duration = parse('P1W')
assert(duration, { weeks: 1 })
try {
parse('invalid-duration')
} catch (e) {
assert(e.message === 'Invalid duration')
}
`
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.
`js
import * as Duration from 'tinyduration'
const durationStr = Duration.serialize({ weeks: 1 })
assert(durationStr, 'P1W')
const durationStr = Duration.serialize({})
assert(durationStr, 'PT0S')
``
MIT