Skip to main content
Enhanced MS exports several TypeScript types and interfaces for use in your code.

​
Ms

The main function interface that formats and parses durations. 
interface Ms {
  (milliseconds: number): string | null;
  (milliseconds: number, options: FormatOptions): string | null;
  (milliseconds: number, preset: FormatOptionsPreset): string | null;
  (duration: string): number;
}

​
Format overloads

When you pass a number, the function formats milliseconds to a human-readable string: 
ms(90061) // "1 minute 30 seconds"
ms(90061, { useAbbreviations: true }) // "1m 30s"
ms(90061, 'short') // "1m 30s"

​
Parse overload

When you pass a string, the function parses a duration string into milliseconds: 
ms("1 minute 30 seconds") // 90061
ms("1m 30s") // 90061

​
CreateMsOptions

Options for creating a custom ms instance with createMs(). 
interface CreateMsOptions {
  language?: keyof typeof languages | LanguageDefinition;
  formatOptions?: FormatOptions | FormatOptionsPreset;
}
​
language
string | LanguageDefinition
default:"'en'"
The language to use for formatting and parsing. Can be a language key (e.g., 'en', 'de', 'ru') or a custom language definition object.
​
formatOptions
FormatOptions | FormatOptionsPreset
Default formatting options to use when formatting milliseconds. See FormatOptions below.

​
Example

import { createMs } from 'enhanced-ms';

const ms = createMs({
  language: 'de',
  formatOptions: { useAbbreviations: true }
});

ms(90061) // "1m 30s" (in German)

​
FormatOptions

Options for customizing duration formatting. 
interface FormatOptions {
  extends?: FormatOptionsPreset;
  hideUnitNames?: boolean;
  useAbbreviations?: boolean;
  includeZero?: boolean;
  includeMs?: boolean;
  includeSubMs?: boolean;
  includedUnits?: ParseUnit[];
  unitLimit?: number;
  unitSeparator?: string;
  minimumDigits?: number;
}
​
extends
FormatOptionsPreset
Extends a preset with the given options. See Format presets.
​
hideUnitNames
boolean
default:false
Hide unit names from the output. Used as part of the colonNotation preset.
​
useAbbreviations
boolean
default:false
Use abbreviations for unit names (e.g., “m” instead of “minute”).
​
includeZero
boolean
default:false
Include units with the value 0 in the output. Used as part of the colonNotation preset.
​
includeMs
boolean
default:false
Include milliseconds in the output. Shorthand for adding 'millisecond' to the includedUnits option.
​
includeSubMs
boolean
default:false
Include sub-millisecond units (microseconds and nanoseconds) in the output. Enabling this option automatically enables includeMs. Shorthand for adding 'microsecond' and 'nanosecond' to the includedUnits option.
​
includedUnits
ParseUnit[]
default:["year","day","hour","minute","second"]
Which units should be included in the output. Valid units: 'year', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond'.
​
unitLimit
number
The maximum number of units to include in the output. If set to -1, all units will be included.
​
unitSeparator
string
default:" "
The separator to use between units.
​
minimumDigits
number
default:0
The minimum number of digits for a unit. Will pad with leading zeroes. Used as part of the colonNotation preset.

​
Example

ms(90061000, {
  useAbbreviations: true,
  unitLimit: 2
}) // "1d 1h"

ms(90061000, {
  includeMs: true,
  unitSeparator: ', '
}) // "1 day, 1 hour, 1 minute, 1 second, 0 milliseconds"

​
FormatOptionsPreset

Pre-configured formatting presets. 
type FormatOptionsPreset = 'short' | 'fullPrecision' | 'colonNotation';
​
short
preset
Uses abbreviations and limits output to 2 units.Example: 1m 30s
​
fullPrecision
preset
Includes milliseconds, microseconds, and nanoseconds.Example: 10 seconds 100 milliseconds 100 microseconds 100 nanoseconds
​
colonNotation
preset
Uses colon-separated format without unit names, similar to digital clocks.Example: 01:30:45

​
Example

ms(90061, 'short') // "1m 30s"
ms(90061, 'colonNotation') // "01:30"

​
ParseUnit

Valid unit types that can be used in formatting. 
type ParseUnit = 'year' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond';
These are the units you can include in the includedUnits option of FormatOptions.

​
LanguageDefinition

Interface for defining custom language support. 
interface LanguageDefinition {
  decimal: '.' | ',';
  and?: string | ((words: string[]) => string[]);
  units: Record<Unit, LanguageUnitDefinition>;
}
​
decimal
'.' | ','
The decimal separator the language uses. For example, '.' for English, ',' for German.
​
and
string | ((words: string[]) => string[])
The string or factory function to use for the “and” conjunction. For example, 'and' for English, 'und' for German.
​
units
Record<Unit, LanguageUnitDefinition>
Definitions for each time unit in the language. See LanguageUnitDefinition.

​
Example

import { createMs } from 'enhanced-ms';

const customLanguage = {
  decimal: '.',
  and: 'and',
  units: {
    second: {
      name: (c) => c === 1 ? 'second' : 'seconds',
      abbreviation: 's',
      matches: ['second', 'seconds', 's']
    },
    // ... other units
  }
};

const ms = createMs({ language: customLanguage });

​
LanguageUnitDefinition

Definition for a single time unit in a language. 
interface LanguageUnitDefinition {
  name: string | ((count: number) => string);
  abbreviation?: string | ((count: number) => string);
  matches: Lowercase<string>[];
}
​
name
string | ((count: number) => string)
The string or factory function to use for the unit name. For example, 'hour' for English, or a function that returns 'hour' or 'hours' based on count.
​
abbreviation
string | ((count: number) => string)
The string or factory function to use for the unit abbreviation. For example, 'h' for English. Required if you want to use useAbbreviations option.
​
matches
Lowercase<string>[]
A list of lowercase strings to use for matching units when parsing duration strings. For example, ['h', 'hr', 'hour', 'hours'] for English hours.

​
Example

const minuteDefinition = {
  name: (c) => c === 1 ? 'minute' : 'minutes',
  abbreviation: 'm',
  matches: ['minute', 'minutes', 'm', 'min']
};

Build docs developers (and LLMs) love

Get started for freeTalk to us