Human-readable, convenient, friendly durations.
Converts durations given as strings to milliseconds or to custom units from milliseconds to weeks.
🤔 Why?
-
1.: It's more intuitive for everyday use, when dealing with durations
❤️ :// 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
💪 :// 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 :
// 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
📦 Installation
-
NPM:
npm install @standards/duration
-
Yarn:
yarn add @standards/duration
☕ 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.
-
CommonJS:
const duration = require('@standards/duration')
-
ES Module:
import duration from '@standards/duration'
-
In Browser:
<script src="https://cdn.jsdelivr.net/npm/@standards/duration/dist/duration.umd.min.js"></script> <script> document.addEventListener('DOMContentLoaded', function () { console.log(duration('42 sec')) // === 42000 }) </script>
-
AMD, SystemJS, IIFE, and Others:
Check out the additional variations and SRI hashes on jsDelivr CDN.
😆 Usage - General
// 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
😋 Usage - Custom Fallback
// these will return the fallback duration
duration(undefined, '1 hour') // === 3600000
duration(null, '45 min') // === 2700000
duration(false, '60sec') // === 60000
😍 Usage - Custom Return Unit
// 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
😧 Usage - Custom Duration Function
// ---------- 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' })
// ---------- 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' })
// 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
💻 API
@standards/duration
-
@standards/duration
-
~duration([duration], [defaultOrOptions], [options]) ⇒
number
-
~createCustom([duration], [defaultOrOptions], [options]) ⇒
duration
-
~durationOptions :
Object
-
~duration([duration], [defaultOrOptions], [options]) ⇒
number
@standards/duration~duration([duration], [defaultOrOptions], [options]) ⇒ 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. |
Example (General Usage)
// these will return milliseconds
duration('3.5h') // === 12600000
duration('1.5h') // === 5400000
duration('175min') // === 10500000
duration('300ms') // === 300
Example (Unit Varieties)
// 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
Example (Whitespaces)
// whitespaces don't matter
duration('42 sec') // === 42000
duration(' 42sec') // === 42000
duration('42sec ') // === 42000
duration(' 42 sec ') // === 42000
Example (Separators)
// 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
Example (Unit Tolerance)
// 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
Example (Custom Fallback)
// these will return the fallback duration
duration(undefined, '1 hour') // === 3600000
duration(null, '45 min') // === 2700000
duration(false, '60sec') // === 60000
Example (Custom Return Unit)
// 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
Example (CommonJS Require)
const duration = require('@standards/duration')
duration('42 sec') // === 42000
Example (ES Module Import)
import duration from '@standards/duration'
duration('42 sec') // === 42000
duration
@standards/duration~createCustom([duration], [defaultOrOptions], [options]) ⇒ Creates a customized duration function with the given arguments.
Returns: duration
- The customized duration function.
See: @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. |
Example (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' })
Example (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' })
Example (Custom Duration Function)
// 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
Object
@standards/duration~durationOptions : 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 |
Example (Duration Options)
// without fallback
duration('42 sec', { unit: 'sec', round: false })
// with fallback
duration('42 sec', '1 sec', { unit: 'sec', round: false })
⭐ Related
Check out the official website for more tools, utilities, and packages.
Find more @standards packages on NPM and GitHub.
🍻 Contribution
Any contribution is highly appreciated. To get going, check out the contribution guidelines.
Thank you and have fun!