1.1.0 • Published 5 years ago

@jessling/duration v1.1.0

Weekly downloads
7
License
ISC
Repository
github
Last release
5 years ago

@jessling/duration

:confused: Why?

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

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

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

:floppy_disk: Installation

  • NPM:

    $ npm install @jessling/duration --save

  • Yarn:

    $ yarn add @jessling/duration

:sunglasses: 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.

: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('@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

:computer: API

@jessling/duration

@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).

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

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

Example (Duration Options) 

// without fallback
duration('42 sec', { unit: 'sec', round: false })

// with fallback
duration('42 sec', '1 sec', { unit: 'sec', round: false })

:star: Related

Check out the official website for more tools, utilities, and packages and follow on Twitter.

Find more @jessling packages on NPM and GitHub.

:beers: Contribution

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

Thank you and have fun!

:copyright: License

ISC @ Richard King

durationdurhumanreadableusableconvenientfriendlyprettyeasyconvertvarioustimeweeksdayshoursminutessecondsmillisecondmillisecondsmsunitrangeperiodtextstringnumberumdeses6esmamdcjsiifecommonjsbrowserjessling@jessling
@infinitebrahmanuniverse/nolb-_jes@everything-registry/sub-chunk-486
1.1.0

5 years ago

1.0.4-beta

5 years ago

1.0.4

5 years ago

1.0.3

5 years ago

1.0.2

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago