format()

The format() function converts a millisecond value into a human-readable string representation. It is the inverse of parse() and is the primary export for converting numeric time values into formatted output suitable for display in user interfaces, logs, or any context where a compact time representation is needed.

Signature

function format(ms: number,
 options?: FormatOptions & { format?: string }
): string

The function accepts a numeric millisecond value and an optional options object, returning a formatted string.

The FormatOptions type is defined as:

interface FormatOptions {
 long?: boolean
}

Behavior

Basic Usage

When called with only a millisecond value, format() returns a compact string using short unit labels:

format(60000) // "1m"
format(3600000) // "1h"
format(86400000) // "1d"

The function handles zero and negative values as well:

format(0) // "0ms"
format(-60000) // "-1m"

The long Option

When long is set to true, the function uses full unit names instead of abbreviations. This is controlled by the FormatOptions interface src/index.ts.

format(60000, { long: true }) // "1 minute"
format(3600000, { long: true }) // "1 hour"
format(86400000, { long: true }) // "1 day"

The long option affects all unit labels in the output. For plural values, the unit name is pluralized:

format(120000, { long: true }) // "2 minutes"
format(7200000, { long: true }) // "2 hours"
format(172800000, { long: true }) // "2 days"

Unit Labels

The function uses the following unit mappings, defined in the source code src/index.ts:5-20:

Negative Values

When a negative number is passed, the function prepends a minus sign (-) to the formatted output. The absolute value is used for the unit calculation:

format(-60000) // "-1m"
format(-3600000) // "-1h"
format(-60000, { long: true }) // "-1 minute"

This behavior is implemented by taking the absolute value of the input for unit computation and then applying the sign to the final string src/index.ts:22-24.

Zero Values

A value of 0 milliseconds is formatted as "0ms" in short format and "0 milliseconds" in long format. This is handled as a special case before the main unit calculation logic src/index.ts:22-24.

Implementation Details

The function is defined in src/index.ts and follows this flow:

1. Input validation: The function checks if the input is 0 and returns the zero-case string immediately src/index.ts:22-24.
2. Sign handling: For negative values, the absolute value is computed and a minus sign is stored for later prepending src/index.ts:22-24.
3. Unit calculation: The function iterates through the unit definitions in descending order (years to milliseconds), dividing the remaining milliseconds by each unit's millisecond value. For each unit where the quotient is greater than zero, it appends the formatted unit label src/index.ts:26-44.
4. Label selection: For each unit, the function selects either the short label or the appropriate long label (singular or plural) based on the long option and the count src/index.ts:26-44.
5. String construction: The formatted parts are joined with spaces, and the sign is prepended if the original value was negative src/index.ts.

The unit definitions are stored as an array of tuples, each containing the millisecond value, short label, singular long label, and plural long label src/index.ts:5-20.

Related Pages

• parse() and ms()
• parseStrict()
• TypeScript Types
• Architecture