Skip to main content
The parseMilliseconds() function converts a duration in milliseconds into an object containing individual time units (years, days, hours, etc.).

​
Import

import { parseMilliseconds } from 'enhanced-ms';

​
Signature

function parseMilliseconds(
  milliseconds: number,
  includedUnits?: ParseUnit[]
): Record<ParseUnit, number | null>
​
milliseconds
number
required
The duration in milliseconds to parse
​
includedUnits
ParseUnit[]
Which units should be calculated. Units not included will be null in the result.
​
return
Record<ParseUnit, number | null>
An object with time unit keys and their calculated values. Excluded units have null values.

​
Usage

​
Basic parsing

Parse milliseconds into all available units: 
import { parseMilliseconds } from 'enhanced-ms';

parseMilliseconds(90061000)
// Returns: {
//   year: 0,
//   day: 1,
//   hour: 1,
//   minute: 1,
//   second: 1,
//   millisecond: 0,
//   microsecond: 0,
//   nanosecond: 0
// }

​
Selective unit parsing

Specify which units to include in the calculation: 
parseMilliseconds(90061000, ['day', 'minute'])
// Returns: {
//   year: null,
//   day: 1,
//   hour: null,
//   minute: 61,  // Note: includes the hour converted to minutes
//   second: null,
//   millisecond: null,
//   microsecond: null,
//   nanosecond: null
// }
When units are excluded, the next smaller unit absorbs their value. In the example above, the hour (60 minutes) is added to the minute count, resulting in 61 minutes total.

​
Parse specific units only

Get just the units you care about: 
parseMilliseconds(3661000, ['hour', 'minute', 'second'])
// Returns: {
//   year: null,
//   day: null,
//   hour: 1,
//   minute: 1,
//   second: 1,
//   millisecond: null,
//   microsecond: null,
//   nanosecond: null
// }

​
ParseUnit type

The available unit keys are: 
type ParseUnit = 
  | 'year' 
  | 'day' 
  | 'hour' 
  | 'minute' 
  | 'second' 
  | 'millisecond' 
  | 'microsecond' 
  | 'nanosecond';

​
How it works

The function works by dividing the total milliseconds by each unit’s value (largest to smallest) and tracking the remainder:
  1. Divide by the unit’s millisecond value
  2. Store the integer part as the unit count
  3. Use the remainder for the next unit
For example, with 90061000 milliseconds:
  • 90061000 ÷ 86400000 (day) = 1 day, remainder 3661000
  • 3661000 ÷ 3600000 (hour) = 1 hour, remainder 61000
  • 61000 ÷ 60000 (minute) = 1 minute, remainder 1000
  • 1000 ÷ 1000 (second) = 1 second, remainder 0

​
When to use this function

Use parseMilliseconds() when:
  • You need the raw breakdown of time units
  • Building custom formatting logic
  • Displaying individual unit values separately
  • You want precise control over which units to calculate
For most formatting use cases, formatMilliseconds() or ms() are more convenient.

​
parseUnits constant

The parseUnits constant object contains the millisecond values for each unit: 
import { parseUnits } from 'enhanced-ms';

parseUnits.second      // 1000
parseUnits.minute      // 60000
parseUnits.hour        // 3600000
parseUnits.day         // 86400000
parseUnits.year        // 31536000000
This is the same as the units constant exported from the main package, but only includes the units used in formatting (excludes week, month, decade, century, millennium).

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us