full-ms

Parse duration strings to milliseconds and format milliseconds to human-readable strings. Drop-in compatible with ms — with compound durations, ISO 8601, and colon notation on top.

parse('1h30m')    // 5400000
parse('PT4M13S')  // 253000
format(5400000)   // '1h 30m'
format(90061000)  // '1d 1h 1m 1s'

Install

npm install full-ms

Usage

import { parse, format } from 'full-ms'

parse(str)

Converts a duration string to milliseconds. Returns undefined for invalid input.

// Single units
parse('1d')          // 86400000
parse('10h')         // 36000000
parse('2.5 hrs')     // 9000000
parse('1m')          // 60000
parse('5s')          // 5000
parse('500ms')       // 500
parse('1y')          // 31557600000
parse('-1h')         // -3600000
parse('100')         // 100

// Compound — the main advantage over ms
parse('1h30m')               // 5400000
parse('2d 12h 30m')          // 217800000
parse('1 hour 30 minutes')   // 5400000
parse('1d 1h 1m 1s')         // 90061000

// ISO 8601
parse('PT1H30M')   // 5400000
parse('PT4M13S')   // 253000
parse('P1DT12H')   // 129600000
parse('P2W')       // 1209600000
parse('PT0.5S')    // 500
parse('-PT1H')     // -3600000

// Invalid
parse('P1Y')       // undefined — year/month are ambiguous
parse('banana')    // undefined

format(ms, options?)

Converts milliseconds to a human-readable duration string.

format(60000)      // '1m'
format(5400000)    // '1h 30m'
format(90061000)   // '1d 1h 1m 1s'
format(500)        // '500ms'
format(-3600000)   // '-1h'

options.long

format(60000,    { long: true })   // '1 minute'
format(5400000,  { long: true })   // '1 hour 30 minutes'
format(90061000, { long: true })   // '1 day 1 hour 1 minute 1 second'

options.iso

format(5400000,  { iso: true })   // 'PT1H30M'
format(86400000, { iso: true })   // 'P1D'
format(500,      { iso: true })   // 'PT0.5S'
format(-3600000, { iso: true })   // '-PT1H'

options.colon

format(5400000,  { colon: true })   // '1:30:00'
format(253000,   { colon: true })   // '4:13'
format(500,      { colon: true })   // '0:00.5'
format(-3661000, { colon: true })   // '-1:01:01'

options.largest

Limits the number of units in the output.

format(90061000, { largest: 1 })   // '1d'
format(90061000, { largest: 2 })   // '1d 1h'
format(90061000, { largest: 3 })   // '1d 1h 1m'

Default export

Auto-detects input type. Strings are parsed, numbers are formatted. API-compatible with ms.

import ms from 'full-ms'

ms('1h30m')               // 5400000
ms('PT1H30M')             // 5400000
ms(5400000)               // '1h 30m'
ms(60000, { long: true }) // '1 minute'
ms(5400000, { iso: true}) // 'PT1H30M'

CommonJS

const { parse, format } = require('full-ms')

Supported units

| Unit | Aliases | |--------------|------------------------------------------------------| | years | y yr yrs year years | | weeks | w wk wks week weeks | | days | d day days | | hours | h hr hrs hour hours | | minutes | m min mins minute minutes | | seconds | s sec secs second seconds | | milliseconds | ms msec msecs millisecond milliseconds |

TypeScript

Types ship with the package. No @types/ install needed.

import { parse, format, type FormatOptions } from 'full-ms'

const ms: number | undefined = parse('1h30m')
const str: string = format(5400000, { long: true })

License

MIT