typed-duration-parser

Minimal duration string parser for backend configs. Converts human-readable duration strings like "1h30m" to milliseconds.

Zero dependencies. TypeScript. ESM + CJS.

Install

npm install typed-duration-parser

Usage

import { parseDuration } from 'typed-duration-parser';

parseDuration('15m');     // 900000
parseDuration('1h30m');   // 5400000
parseDuration('2 days');  // 172800000
parseDuration('1.5h');    // 5400000
parseDuration('-30m');    // -1800000
parseDuration('invalid'); // null

API

parseDuration(input: string): number | null

Parse a duration string to milliseconds. Returns null if the input is invalid.

parseDurationToSeconds(input: string): number

Parse a duration string to seconds. Throws if the input is invalid.

parseDurationMs(input: string): number

Parse a duration string to milliseconds (strict). Throws if the input is invalid.

isValidDuration(input: string): boolean

Check if a string is a valid duration format.

formatDuration(ms: number): string

Format milliseconds to a compact duration string (e.g., 5400000 → "1h30m").

Supported Units

| Unit | Aliases | | ------------ | -------------------------- | | Year | y, yr, year, years | | Month | mo, mth, month, months | | Week | w, wk, week, weeks | | Day | d, day, days | | Hour | h, hr, hour, hours | | Minute | m, min, minute, minutes | | Second | s, sec, second, seconds | | Millisecond | ms, millisec, millisecond, milliseconds |

Why?

Packages like ms or parse-duration are great, but typed-duration-parser is designed specifically for backend config parsing where you need:

• TypeScript-first with proper types
• Both ESM and CJS support
• Minimal footprint, zero dependencies
• Simple string-to-ms conversion for env vars and config files

License

MIT