parseStrict()

The parseStrict() function provides compile-time type safety for parsing time strings into milliseconds. It is a type-safe wrapper around parse() that enforces the return type to be a number rather than number | undefined.

Signature

function parseStrict<Input extends string>(input: Input): ParseResult<Input>

The function is generic over the input string type, allowing TypeScript to infer the exact string literal type and return a corresponding numeric literal type when possible.

How It Differs from `parse()`

The standard parse() function has the following signature:

function parse(input: string): number | undefined

Key differences:

Aspect	`parse()`	`parseStrict()`
Return type	`number \| undefined`	`ParseResult<Input>` (always a number type)
Input type	`string`	Generic `Input extends string`
Type safety	Runtime undefined possible	Compile-time guarantee of number
Use case	General parsing with error handling	Type-safe parsing with known valid inputs

TypeScript Types Involved

The function relies on the ParseResult type, which is a conditional type that maps valid time string patterns to their corresponding numeric literal types:

type ParseResult<Input extends string> =
 Input extends `${infer NumberPart}${infer UnitPart}`?
 NumberPart extends `${number}`?
 UnitPart extends 'ms'? number:
 UnitPart extends 's'? number:
 UnitPart extends 'm'? number:
 UnitPart extends 'h'? number:
 UnitPart extends 'd'? number:
 UnitPart extends 'w'? number:
 UnitPart extends 'y'? number:
 never:
 never:
 never

This type performs pattern matching at the type level:

It splits the input string into a numeric part and a unit part
If the numeric part is a valid number and the unit part is one of the supported time units (ms, s, m, h, d, w, y), it returns number
Otherwise, it returns never, causing a compile-time error

When to Use `parseStrict()`

Use parseStrict() when:

You have known valid time strings - When you are working with time strings that you know are valid (e.g., from configuration constants or validated user input)
You want compile-time guarantees - When you want TypeScript to catch invalid time strings during development rather than handling undefined at runtime
You are building type-safe APIs - When creating functions that accept time strings and need to guarantee a numeric return type
You want to avoid runtime checks - When you don't want to add if (result === undefined) checks after every parse call

Example scenarios where parseStrict() is appropriate:

Parsing hardcoded time constants in configuration files
Processing time strings that have already been validated by a schema validator
Working with time strings from trusted sources (e.g., environment variables with known formats)

Behavior with Invalid Input

When parseStrict() receives an invalid time string, TypeScript will produce a compile-time error because the ParseResult type resolves to never. This is different from parse(), which would return undefined at runtime.

For example:

parseStrict("5 minutes") - Compile-time error (invalid unit "minutes")
parseStrict("5m") - Valid, returns number
parseStrict("abc") - Compile-time error (invalid number part)

Implementation Details

The function delegates to parse() internally:

export function parseStrict<Input extends string>(input: Input): ParseResult<Input> {
 const result = parse(input);
 return result as ParseResult<Input>;
}

The type assertion as ParseResult<Input> is necessary because TypeScript cannot verify the conditional type at runtime. The actual runtime behavior is identical to parse() - it will return undefined for invalid inputs, but the type system guarantees that the return value is always a number when the input is valid.

parse() and ms() - The base parsing functions
format() - Formatting milliseconds to time strings
TypeScript Types - Type definitions used across the library
Architecture - Overall library design