Converts durations given as strings to milliseconds or to custom units from milliseconds to weeks.
--- ## :thinking: Why? - **1.:** It's **more intuitive** for everyday use, when dealing with durations :heart:: ```javascript // general job cycle const cycle = duration('36 hours') // === 129600000 in milliseconds // movie playtime const length = duration('2h 41m') // === 9660000 in milliseconds // will log out "It is time!" in ~60,000 milliseconds setTimeout(() => console.log('It is time!'), duration('1 min')) // delays the execution for ~15,000 milliseconds await delay(duration('15 seconds')) ``` - **2.:** It's easier, when **handling larger or more complex durations** :muscle:: ```javascript // custom notification set manually by a user const notifyIn = duration('24 hours 36 minutes 49 seconds') // === 88609000 // cookie will expire in 7776000000 milliseconds from now const date = new Date(Date.now() + duration('90 days')) document.cookie = 'value=42;expires=' + date.toUTCString() + ';path=/') // 24192000000 milliseconds from now User.update( { logged_out_warn_time: Date.now() + duration('280 days'), }, { where: { id } } ) ``` - **3.:** It's **highly configurable** and the inputs are **cached** :godmode:: ```javascript // custom return unit with a default fallback duration('42 hours', '1 hour', { unit: 'seconds' }) // === 151200 in seconds // create a custom duration function with predefined arguments const custom = createCustom(0, '1 day', { unit: 'seconds' }) // will return the given duration in seconds ({ unit: 'seconds' }) custom('1 hour') // === 3600 in seconds ``` ## :package: Installation - **NPM:** ```bash npm install @standards/duration ``` - **Yarn:** ```bash yarn add @standards/duration ``` ## :coffee: Usage **@standards/duration** can be used in **Node.js**, in the **Browser**, and ***in every*** current module format, system, environment, and variety including **CommonJS**, **ESM**, **UMD**, **AMD**, **SystemJS** and [***more***][url-cdn]. - **CommonJS:** ```javascript const duration = require('@standards/duration') ``` - **ES Module:** ```javascript import duration from '@standards/duration' ``` - **In Browser**: ```html ``` - **AMD, SystemJS, IIFE, and Others:** Check out the [**additional variations and SRI hashes on jsDelivr CDN**][url-cdn]. ### :satisfied: Usage - General ```javascript // these will return milliseconds duration('3.5h') // === 12600000 duration('1.5h') // === 5400000 duration('175min') // === 10500000 duration('300ms') // === 300 // singulars, plurals, and shorthands work as expected duration('2s') // === 2000 duration('2sec') // === 2000 duration('2second') // === 2000 duration('2seconds') // === 2000 duration('2 second') // === 2000 duration('2 seconds') // === 2000 // whitespaces don't matter duration('42 sec') // === 42000 duration(' 42sec') // === 42000 duration('42sec ') // === 42000 duration(' 42 sec ') // === 42000 // commas, underscores, and dashes are allowed duration('10000 sec') // === 10000000 duration('10,000 sec') // === 10000000 duration('10_000 sec') // === 10000000 duration('10-000 sec') // === 10000000 // multiple units are allowed too, even the crazier ones duration('1 hour 23 minutes 45 seconds 600 milliseconds') // === 5025600 duration('100ms 200ms') // === 300 duration('500ms 400ms 300ms 200ms 100ms') // === 1500 duration('1s 2sec 3secs 4second 5seconds') // === 15000 duration('1.1h 2.2h 3.3h 4.4h 5.5h') // === 59400000 duration('0.5d 1.0day 1.5day 2.0days') // === 432000000 ``` ### :yum: Usage - Custom Fallback ```javascript // these will return the fallback duration duration(undefined, '1 hour') // === 3600000 duration(null, '45 min') // === 2700000 duration(false, '60sec') // === 60000 ``` ### :heart_eyes: Usage - Custom Return Unit ```javascript // 1 hour in seconds duration('1 h', { unit: 's' }) // === 3600 // 2 days in minutes duration('2 days', { unit: 'minutes' }) // === 2880 // 3 weeks, 5 days and 12 hours in hours duration('3w 5days 12 h', { unit: 'h' }) // === 636 ``` ### :anguished: Usage - Custom Duration Function ```javascript // ---------- in CommonJS -------------------- const duration = require('@standards/duration') // custom duration function // with 1 hour as a fallback, return unit is in seconds const custom = duration.createCustom(null, '1 hour', { unit: 'sec' }) ``` ```javascript // ---------- in ES Module ---------------------- import { createCustom } from '@standards/duration' // custom duration function // with 1 hour as a fallback, return unit is in seconds const custom = createCustom(null, '1 hour', { unit: 'sec' }) ``` ```javascript // will return the fallback, which is "1 hour" in seconds ({ unit: 'sec' }) custom() // === 3600 // will return 2 hours in seconds, since the return unit is "sec" custom('2 hours') // === 7200 ``` --- ## :computer: API ## @standards/duration * [@standards/duration](#module_@standards/duration) * [~duration([duration], [defaultOrOptions], [options])](#module_@standards/duration..duration) ⇒number
* [~createCustom([duration], [defaultOrOptions], [options])](#module_@standards/duration..createCustom) ⇒ duration
* [~durationOptions](#module_@standards/duration..durationOptions) : Object
### @standards/duration~duration([duration], [defaultOrOptions], [options]) ⇒ number
Converts different types of string durations to milliseconds, seconds, minutes, and more as numbers.
**Returns**: number - The duration in number.
If the given duration is invalid, the returned duration will be `0` *(zero)*.
| Param | Type | Description |
|---|---|---|
| [duration] | string | number | * | The duration(s) to parse. Multiple durations are allowed in the string separated by spaces and/or commas. Valid duration units: weeks, days, hours, minutes, seconds, and milliseconds. Possible duration unit variations:
|
| [defaultOrOptions] | string | number | durationOptions | The default duration as a fallback or additional options. If unspecified, the default fallback duration is 0 (zero). |
| [options] | durationOptions | Additional options to change the default behavior. |
duration
Creates a customized duration function with the given arguments.
**Returns**: duration - The customized duration function.
**See**: [@standards/duration~duration](@standards/duration~duration)
| Param | Type | Description |
|---|---|---|
| [duration] | string | number | * | The duration(s) to parse. |
| [defaultOrOptions] | string | number | durationOptions | The default duration as a fallback or additional options. |
| [options] | durationOptions | Additional options to change the default behavior. |
Object
Additional options to change the default behavior.
**Properties**
| Name | Type | Default | Description |
|---|---|---|---|
| [unit] | string | "ms" | The unit in which the returned duration will be converted to. By default, the returned duration will be in milliseconds ( |
| [round] | boolean | true | If true, the returned duration will be rounded. By default, it's |