This package has been deprecated

Author message:

use @standards/duration instead: https://www.npmjs.com/package/@standards/duration

@jessling/duration

---

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 ❤️:

  // will log out "It is time!" in ~60,000 milliseconds
  setTimeout(() => console.log('It is time!'), duration('1 min'))
  
  // 15552000000 milliseconds from now
  const date = new Date(Date.now() + duration('180 days'))
  document.cookie = 'value=42;expires=' + date.toUTCString() + ';path=/')
  
  // delays the execution for ~15,000 milliseconds
  await delay(duration('15 seconds'))

• 2.: It's easier, when handling larger or more complex durations 💪:

  // general job cycle
  const cycle = duration('36 hours') // === 129600000 in milliseconds
  
  // movie playtime
  const length = duration('2h 41m') // === 9660000 in milliseconds
  
  // custom notification set by a user
  const notifyIn = duration('24 hours 36 minutes 49 seconds') // === 88609000

• 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 @jessling/duration --save

• Yarn:

  $ yarn add @jessling/duration

😎 Usage

@jessling/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('@jessling/duration')

• ES Module:

  import duration from '@jessling/duration'

• In Browser:

  <script src="https://cdn.jsdelivr.net/npm/@jessling/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('@jessling/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 '@jessling/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

@jessling/duration

• @jessling/duration
  • ~duration([duration], [defaultOrOptions], [options]) ⇒ number
  • ~createCustom([duration], [defaultOrOptions], [options]) ⇒ duration
  • ~durationOptions : Object

@jessling/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: milliseconds: 'ms', 'millisecond', 'milliseconds' seconds: 's', 'sec', 'second', 'seconds' minutes: 'm', 'min', 'minute', 'minutes' hours: 'h', 'hour', 'hours' days: 'd', 'day', 'days' weeks: 'w', 'week', 'weeks'
[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('@jessling/duration')

duration('42 sec') // === 42000

Example (ES Module Import)

import duration from '@jessling/duration'

duration('42 sec') // === 42000

@jessling/duration~createCustom([duration], [defaultOrOptions], [options]) ⇒ duration

Creates a customized duration function with the given arguments.

Returns: duration - The customized duration function.
See: @jessling/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('@jessling/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 '@jessling/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

@jessling/duration~durationOptions : 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 ('ms'). Possible units are the same as for the durations to parse (from milliseconds to weeks).
[round]	boolean	true	If true, the returned duration will be rounded. By default, it's true.

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 and follow on Twitter.

Find more @jessling packages on NPM and GitHub.

🍻 Contribution

Any contribution is highly appreciated. To get going, check out the contribution guidelines.

Thank you and have fun!

©️ License

ISC @ Richard King