# duration

> Time duration utilities

Latest version **0.2.2** (published 2018-10-31) · ISC license · 0 weekly downloads

## Install

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

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2018-10-31 |
| First published | 2012-05-28 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 44 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 30 |
| Author | Mariusz Nowak |
| Maintainers | medikoo |
| Keywords | date, duration, time |

## Links

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

## Dependencies (2)

- [d](https://npm.io/package/d.md) 1
- [es5-ext](https://npm.io/package/es5-ext.md) ~0.10.46

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

- 0.2.2 (latest) — 2018-10-31
- 0.2.1 — 2018-08-31
- 0.2.0 — 2014-04-27
- 0.1.4 — 2013-01-03
- 0.1.3 — 2013-01-02
- 0.1.2 — 2012-11-10
- 0.1.1 — 2012-10-04
- 0.1.0 — 2012-05-28

## README

[![*nix build status][nix-build-image]][nix-build-url]
[![Windows build status][win-build-image]][win-build-url]
![Transpilation status][transpilation-image]
[![npm version][npm-image]][npm-url]

# duration - Time duration utilities

_Formerly part of [es5-ext](https://github.com/medikoo/es5-ext) project._

## Installation

### Node.js

    $ npm install duration

### Browser

Can be bundled for browser with help of [modules-webmake](https://github.com/medikoo/modules-webmake)

## Example usage:

```javascript
var Duration = require("duration");

var duration = new Duration(new Date(2000, 6, 7), new Date(2010, 8, 13, 3, 23, 8, 456));

console.log("Years: ", duration.years);
console.log("Months: ", duration.months);
console.log("Days: ", duration.days);
console.log("Hours: ", duration.hours);
console.log("Minutes: ", duration.minutes);
console.log("Seconds: ", duration.seconds);
console.log("Milliseconds: ", duration.milliseconds);

console.log("Trailing months: ", duration.month);
console.log("Trailing days: ", duration.day);
console.log("Trailing hours: ", duration.hour);
console.log("Trailing minutes: ", duration.minute);
console.log("Trailing seconds: ", duration.second);
console.log("Trailing milliseconds: ", duration.millisecond);

console.log("Default string representation: ", duration.toString());
console.log("Alternative string representation: ", duration.toString(1));
console.log("Custom string representation: ", duration.toString("H: %Hs m: %M"));
```

Output:

```
Years:  10
Months:  122
Days:  3720
Hours:  89283
Minutes:  5357003
Seconds:  321420188
Milliseconds:  321420188456
Trailing months:  2
Trailing days:  6
Trailing hours:  3
Trailing minutes:  23
Trailing seconds:  8
Trailing milliseconds:  456
Default string representation:  10y 2m 6d 03:23:08.456
Alternative string representation:  10y 2m 6d 3h 23m 8s 456ms
Custom string representation:  H: 89283 m: 23
```

## Duration(from[, to])

Main module is both constructor and factory method, and can be used either way.  
`from` and `to` are expected to be JavaScript Date objects. `to` is optional, and if not provided it defaults to current time.

## Duration.prototype properties

### years

Returns full years of the duration

### months

Returns full months of the duration

### days

Returns full days of the duration

### hours

Returns full hours of the duration

### seconds

Returns full seconds of the duration

### minutes

Returns full minutes of the duration

### milliseconds

Returns milliseconds of the duration

### year

Same as `years`. Returns full years of the duration

### month

Returns trailing months of the duration

### day

Returns trailing days of the duration

### hour

Returns trailing hours of the duration

### minute

Returns trailing minutes of the duration

### second

Returns trailing seconds of the duration

### millisecond

Returns trailing seconds of the duration

## valueOf()

Same as `milliseconds`. Returns milliseconds of the duration

## toString([mode[, threshold]])

Returns readable representation of the duration.  
When invoked without arguments (defaults to _mode=0_), returns as:

    10y 2m 6d 03:23:08.456

When invoked with mode `1`, returns alternative representation:

    10y 2m 6d 3h 23m 8s 456ms

Representation returned by default modes can be customized with threshold setting that trims lowest units:

```javascript
duration.toString(); // 10y 2m 6d 03:23:08.456
duration.toString(0, 1); // 10y 2m 6d 03:23:08
duration.toString(0, 2); // 10y 2m 6d 03:23

duration.toString(1); // 10y 2m 6d 3h 23m 8s 456ms
duration.toString(1, 1); // 10y 2m 6d 3h 23m 8s
duration.toString(1, 2); // 10y 2m 6d 3h 23m
```

## toString(format)

When invoked with string, formats the duration according to given pattern, where:

-   `%y` - `duration.year`
-   `%m` - `duration.month`
-   `%d` - `duration.day`
-   `%H` - `duration.hour`
-   `%M` - `duration.minute`
-   `%S` - `duration.second`
-   `%L` - `duration.millisecond`
-   `%ms` - `duration.months`
-   `%ds` - `duration.days`
-   `%Hs` - `duration.hours`
-   `%Ms` - `duration.minutes`
-   `%Ss` - `duration.seconds`
-   `%Ls` - `duration.milliseconds`
-   `%sign` - If duration is negative outputs `-` otherwise empty string

## Tests

    $ npm test

[nix-build-image]: https://semaphoreci.com/api/v1/medikoo-org/duration/branches/master/shields_badge.svg
[nix-build-url]: https://semaphoreci.com/medikoo-org/duration
[win-build-image]: https://ci.appveyor.com/api/projects/status/nt9c72n1ay9coree?svg=true
[win-build-url]: https://ci.appveyor.com/project/medikoo/duration
[transpilation-image]: https://img.shields.io/badge/transpilation-free-brightgreen.svg
[npm-image]: https://img.shields.io/npm/v/duration.svg
[npm-url]: https://www.npmjs.com/package/duration

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