TypeScript Types

This page documents the TypeScript types exported by the ms package. These types enable type-safe usage of time string parsing and formatting, ensuring that string literals conform to the expected format at compile time.

Exported Types

The package exports the following TypeScript types from its main entry point. All types are defined in src/index.ts and re-exported through the package's package.json "exports" field.

The type definitions are generated automatically from the TypeScript source and included in the distributed package. The package's tsdown.config.ts configures dts: { bundle: true } to produce a single bundled declaration file tsdown.config.ts.

StringValue Type

The StringValue type is a template literal type that represents any valid time duration string that the ms() and parse() functions can accept. It is defined in src/index.ts as:

export type StringValue = `${number}${Unit}` | `${number} ${Unit}`;

src/index.ts

This type constrains string parameters to only those that match the pattern of a numeric value followed by an optional space and a unit suffix. For example, "5s", "10 minutes", "2h", and "100ms" are all valid StringValue literals, while "5" (no unit) or "seconds" (no number) would be rejected by TypeScript's type checker.

The StringValue type is used as the parameter type for the ms() function:

export default function ms(value: StringValue, options?: msOptions): number;

src/index.ts

This ensures that callers must provide a properly formatted time string at compile time, catching malformed inputs before runtime.

Unit Type

The Unit type is a string literal union that enumerates all supported time unit suffixes. It is defined in src/index.ts:

type Unit =
 | "Years"
 | "Year"
 | "Yrs"
 | "Yr"
 | "Y"
 | "years"
 | "year"
 | "yrs"
 | "yr"
 | "y"
 | "Days"
 | "Day"
 | "D"
 | "days"
 | "day"
 | "d"
 | "Hours"
 | "Hour"
 | "Hrs"
 | "Hr"
 | "H"
 | "hours"
 | "hour"
 | "hrs"
 | "hr"
 | "h"
 | "Minutes"
 | "Minute"
 | "Mins"
 | "Min"
 | "M"
 | "minutes"
 | "minute"
 | "mins"
 | "min"
 | "m"
 | "Seconds"
 | "Second"
 | "Secs"
 | "Sec"
 | "S"
 | "seconds"
 | "second"
 | "secs"
 | "sec"
 | "s"
 | "Milliseconds"
 | "Millisecond"
 | "Msecs"
 | "Msec"
 | "Ms"
 | "milliseconds"
 | "millisecond"
 | "msecs"
 | "msec"
 | "ms";

src/index.ts:9-63

The Unit type covers all case variations and abbreviations for each unit:

• Years: Years, Year, Yrs, Yr, Y, years, year, yrs, yr, y
• Days: Days, Day, D, days, day, d
• Hours: Hours, Hour, Hrs, Hr, H, hours, hour, hrs, hr, h
• Minutes: Minutes, Minute, Mins, Min, M, minutes, minute, mins, min, m
• Seconds: Seconds, Second, Secs, Sec, S, seconds, second, secs, sec, s
• Milliseconds: Milliseconds, Millisecond, Msecs, Msec, Ms, milliseconds, millisecond, msecs, msec, ms

This comprehensive union ensures that all commonly used time unit strings are recognized at the type level.

Template Literal Type Mechanics

The StringValue type uses TypeScript's template literal type feature to construct valid time string patterns. The definition:

export type StringValue = `${number}${Unit}` | `${number} ${Unit}`;

Creates two patterns:

1. No space: A number immediately followed by a unit (e.g., "5s", "10ms")
2. With space: A number, a space, then a unit (e.g., "5 s", "10 ms")

The ${number} part uses TypeScript's built-in number type within a template literal, which expands to all possible numeric string representations (integers, floats, negative numbers, etc.). The ${Unit} part is replaced with each member of the Unit union type.

This means StringValue is a union of all combinations of (any number string) + (any unit string), both with and without a space separator. For example, valid values include:

• "5s", "5 s"
• "100ms", "100 ms"
• "2h", "2 h"
• "1.5 minutes", "1.5minutes"
• "-30s", "-30 s"

Type Usage in Functions

The StringValue type is used in the signatures of the parsing functions:

ms() function (default export):

export default function ms(value: StringValue, options?: msOptions): number;

parse() function (named export):

export function parse(value: StringValue, options?: msOptions): number;

src/index.ts

Both functions accept a StringValue as their first parameter and return a number (milliseconds). The options parameter is typed as msOptions, which is defined as:

type msOptions = {
 long?: boolean;
};

src/index.ts

The long option controls whether the output of format() uses long unit names (e.g., "hours") or short abbreviations (e.g., "h").

Type Safety Benefits

Using StringValue provides several compile-time guarantees:

1. No missing units: A string like "500" (without a unit) is rejected at compile time
2. No invalid units: A string like "5 centuries" is rejected because "centuries" is not in the Unit union
3. No malformed spacing: Both "5s" and "5 s" are valid, but "5 s" (double space) is not captured by the type (though runtime parsing handles it gracefully)
4. Autocomplete in editors: TypeScript-aware editors will suggest valid unit strings when typing a StringValue parameter

Related Pages

• parse() and ms()
• format()
• parseStrict()
• Architecture