# tinyduration

> ISO-8601 duration parsing and serialization

Latest version **3.4.1** (published 2025-01-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install tinyduration
pnpm add tinyduration
yarn add tinyduration
bun add tinyduration
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.4.1 |
| Published | 2025-01-18 |
| First published | 2020-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 53 |
| Author | MelleB |
| Maintainers | melleb |
| Keywords | iso-8601, duration, period, date, time |

## Links

- npm: https://www.npmjs.com/package/tinyduration
- Repository: https://github.com/MelleB/tinyduration
- Homepage: https://github.com/MelleB/tinyduration#readme
- Issues: https://github.com/MelleB/tinyduration/issues
- npm.io page: https://npm.io/package/tinyduration

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 3.4.1 (latest) — 2025-01-18
- 3.4.0 — 2025-01-18
- 3.3.1 — 2024-06-11
- 3.3.0 — 2023-06-29
- 3.2.6 — 2023-06-17
- 3.2.5 — 2023-06-17
- 3.2.4 — 2023-01-09
- 3.2.3 — 2022-11-01
- 3.2.2 — 2021-09-01
- 3.2.1 — 2021-03-31
- 3.2.0 — 2020-10-08
- 3.1.1 — 2020-04-01
- 3.0.0 — 2020-03-19
- 2.0.1 — 2020-03-18
- 2.0.0 — 2020-03-18
- … 2 more at https://npm.io/package/tinyduration/versions

## README

# TinyDuration

A small ([< 1kb minified + gzipped](https://bundlephobia.com/package/tinyduration)) 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.

![Node.js CI](https://github.com/MelleB/tinyduration/workflows/Node.js%20CI/badge.svg)

This lib has 0 dependencies.

## Installation

-   NPM: `npm install --save tinyduration`
-   Yarn: `yarn add tinyduration`

## Usage

```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')
```

## Development

This library is written in [TypeScript](https://typescriptlang.org).
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](https://jestjs.io)

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 `undefined` | Duration is positive if undefined |
| years    | `number` or `undefined`  |                                   |
| months   | `number` or `undefined`  |                                   |
| weeks    | `number` or `undefined`  |                                   |
| days     | `number` or `undefined`  |                                   |
| hours    | `number` or `undefined`  |                                   |
| minutes  | `number` or `undefined`  |                                   |
| seconds  | `number` or `undefined`  |                                   |

## _Type:_ ParseConfig

| Property               | Type                     | Description         |
| ---------------------- | ------------------------ | ------------------- |
| allowMultipleFractions | `boolean` or `undefined` | Defaults 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`.

```js
import { parse } from 'tinyduration'

const duration = parse('P1W')
assert(duration, { weeks: 1 })

try {
    parse('invalid-duration')
} catch (e) {
    assert(e.message === 'Invalid duration')
}
```

## _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.

```js
import * as Duration from 'tinyduration'

const durationStr = Duration.serialize({ weeks: 1 })
assert(durationStr, 'P1W')

const durationStr = Duration.serialize({})
assert(durationStr, 'PT0S')
```

# License

MIT

---
_Source: https://npm.io/package/tinyduration · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._