A lightweight, TypeScript-first library for parsing and formatting time durations.
NPM version NPM downloads NPM License Build Status
- π Lightweight: Zero dependencies
- π TypeScript-first: Full type safety and IntelliSense support
- π Bidirectional: Parse strings to milliseconds and format milliseconds to strings
- π― Precise: Handles decimal values and negative numbers
- π Comprehensive: Supports all common time units including months
- π§ͺ Well-tested: >95% test coverage
npm install chrono-ms
yarn add chrono-ms
pnpm add chrono-ms
import ms from 'chrono-ms'; // Parse string to milliseconds ms('2 hours'); // 7200000 ms('1d'); // 86400000 ms('10h'); // 36000000 ms('2.5 hrs'); // 9000000 ms('1y'); // 31557600000 // Format milliseconds to string ms(60000); // "1m" ms(2 * 60 * 1000); // "2m" ms(ms('10 hours') as number); // "10h" ms(60000, { long: true }); // "1 minute" ms(2 * 60 * 1000, { long: true }); // "2 minutes"
import { parse, format } from 'chrono-ms'; // Parse only const milliseconds = parse('1.5h'); // 5400000 // Format only const shortFormat = format(3600000); // "1h" const longFormat = format(3600000, { long: true }); // "1 hour"
import { parseMultiple } from 'chrono-ms'; parseMultiple('1h 30m'); // 5400000 parseMultiple('2d 4h 30m'); // 189000000 parseMultiple('1w 3d'); // 864000000
import { tryParse } from 'chrono-ms'; // Returns null instead of throwing on invalid input tryParse('2h'); // 7200000 tryParse('invalid'); // null tryParse(''); // null
import { format } from 'chrono-ms'; format(5400000, { verbose: true }); // "1h 30m" format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes" format(3661000, { verbose: true }); // "1h 1m 1s" format(90000, { verbose: true }); // "1m 30s"
import ms, { parse, format, type FormatOptions, type ParseOptions, } from 'chrono-ms'; // Custom parsing options const result = parse('30m', { maxLength: 50 }); // Custom formatting options const formatted = format(7200000, { long: true }); // Type-safe string values type TimeString = `${number}h` | `${number}m` | `${number}s`; const timeValue: TimeString = '2h'; const parsed = ms(timeValue); // 7200000
| Unit | Long Format | Short Format |
|---|---|---|
| Years | years, year, yrs, yr |
y |
| Weeks | weeks, week |
w |
| Months | months, month |
mo |
| Days | days, day |
d |
| Hours | hours, hour, hrs, hr |
h |
| Minutes | minutes, minute, mins, min |
m |
| Seconds | seconds, second, secs, sec |
s |
| Milliseconds | milliseconds, millisecond, msecs, msec |
ms |
Note:
mois used for months to avoid ambiguity withm(minutes). Month is defined as exactly 30 days.
All units are case-insensitive and support both singular and plural forms.
Main function that can parse strings or format numbers.
Parameters:
value: string | number- String to parse or number to formatoptions?: FormatOptions | ParseOptions- Configuration options
Returns:
numberwhen parsing stringsstringwhen formatting numbers
Parse a time string into milliseconds.
Parameters:
value: string- Time string to parseoptions?: ParseOptions- Parsing configuration
Returns: number - Parsed time in milliseconds
Options:
maxLength?: number- Maximum string length, must be a positive number (default: 100)
Parse a time string and return null instead of throwing on invalid input.
Parameters:
value: string- Time string to parseoptions?: ParseOptions- Parsing configuration
Returns: number | null - Parsed milliseconds, or null on failure
Parse a compound time string with multiple space-separated tokens.
Parameters:
value: string- Compound time string (e.g.,"1h 30m","2d 4h 30m")options?: ParseOptions- Parsing configuration applied to each token
Returns: number - Total duration in milliseconds
Format milliseconds into a human-readable string.
Parameters:
ms: number- Milliseconds to formatoptions?: FormatOptions- Formatting configuration
Returns: string - Formatted time string
Options:
long?: boolean- Use long format (default: false)verbose?: boolean- Show all non-zero components decomposed (default: false)
ms('1s'); // 1000 ms('1m'); // 60000 ms('1h'); // 3600000 ms('1d'); // 86400000 ms('1w'); // 604800000 ms('1y'); // 31557600000
ms('1.5h'); // 5400000 ms('0.5d'); // 43200000 ms('2.5 hours'); // 9000000
ms('-1h'); // -3600000 ms('-30m'); // -1800000
// Short format (default) ms(60000); // "1m" ms(3600000); // "1h" ms(604800000); // "1w" ms(31557600000); // "1y" // Long format ms(60000, { long: true }); // "1 minute" ms(120000, { long: true }); // "2 minutes" ms(3600000, { long: true }); // "1 hour" ms(7200000, { long: true }); // "2 hours" // Verbose format (decomposed) format(5400000, { verbose: true }); // "1h 30m" format(5400000, { verbose: true, long: true }); // "1 hour 30 minutes"
parse('1mo'); // 2592000000 (30 days) parse('6 months'); // 15552000000
The library throws descriptive errors for invalid inputs:
try { ms('invalid'); } catch (error) { console.log(error.message); // "Invalid time format: "invalid"" } try { ms('a'.repeat(101)); } catch (error) { console.log(error.message); // "String too long. Maximum length is 100 characters" } try { format(NaN); } catch (error) { console.log(error.message); // "Value must be a finite number" }
- Maximum string length is 100 characters by default (configurable via
maxLength) - Uses approximate year length (365.25 days)
- Month is defined as exactly 30 days (not calendar-aware)
format()does not output months; useparse('1mo')for input only
# Install dependencies pnpm install # Run tests pnpm test # Run tests in watch mode pnpm run test:watch # Run tests with coverage pnpm run test:coverage # Build the package pnpm run build # Lint the code pnpm run lint # Type check pnpm run type-check
- Node.js >= 20.0.0
- Supports ES Modules
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT Β© Francisco Luis Rios Vega