:thinking: Why?

• 1.: It's more intuitive for everyday use, when dealing with durations :heart::

  // 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::

  // 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::

  // 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:

  npm install @standards/duration

• Yarn:

  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:

  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][url-cdn].

:satisfied: 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

:yum: Usage - Custom Fallback

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

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

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

:computer: API