ms-long

An extended time conversion utility that builds upon the popular ms library, supporting extremely large time values and multiple units, including those needed for scientific projects.

Features

• Parse time strings to milliseconds (using BigInt for large values)
• Format milliseconds to human-readable strings
• Support for extremely large time values (up to eras - billions of years)
• Combine multiple time units in a single string (e.g., "1 hour 30 minutes")
• More precise calculations, accounting for leap years
• TypeScript support with improved type safety
• Separate parse and format functions for flexible usage
• Support for decades, centuries, millennia, epochs, and eras
• Custom time scales for scientific fields
• Support for BigInt to handle extremely large numbers
• Scientific notation support for input values

Installation

1npm install @anonymort/ms-long

Usage

1import msLong, { parse, format } from '@anonymort/ms-long';
2
3// Parse time strings
4console.log(msLong('2 hours 30 minutes')); // 9000000n
5
6// Format milliseconds
7console.log(msLong(9000000n)); // '2h 30m'
8console.log(msLong(9000000n, { long: true })); // '2 hours 30 minutes'
9
10// Parse complex time strings with large units
11console.log(parse('2 epochs 1 era')); // 1002000000000000000000n
12
13// Format large values
14console.log(format(1002000000000000000000n, { long: true })); 
15// '1 era 2 epochs'
16
17// Use scientific notation
18console.log(parse('1.5e9 years')); // 47304000000000000000000n
19
20// Custom time scales
21const customUnits = {
22  galacticYear: 230000000000n * 365n * 24n * 60n * 60n * 1000n, // ~230 million years
23};
24
25console.log(parse('2 galacticYears', customUnits)); // 14515200000000000000000n
26
27console.log(format(14515200000000000000000n, { long: true, customUnits }));
28// '2 galacticYears'

API

msLong(value: string | number | bigint, options?: { long?: boolean; customUnits?: Record<string, bigint> }): string | bigint

The main function that can both parse and format time values.

• When given a string, it parses it to milliseconds (as BigInt).
• When given a number or BigInt, it formats it to a time string.
• The long option determines whether to use long format (e.g., "2 hours" vs "2h").
• The customUnits option allows for defining custom time units.

parse(value: string, customUnits?: Record<string, bigint>): bigint

Parses a time string to milliseconds (as BigInt). Supports multiple units and extremely large time values.

format(ms: bigint | number, options?: { long?: boolean; customUnits?: Record<string, bigint> }): string

Formats milliseconds (as BigInt or number) to a time string. Can handle extremely large values and provides precise output for large durations.

Supported Units

• Millisecond(s)
• Second(s)
• Minute(s)
• Hour(s)
• Day(s)
• Week(s)
• Month(s)
• Year(s)
• Decade(s)
• Century(ies)
• Millennium(a)
• Epoch(s) (millions of years)
• Era(s) (billions of years)

Custom units can be defined as needed.

Scientific and Large-Scale Time Handling

• Supports parsing and formatting of time spans up to billions of years
• Uses BigInt for precise calculations with extremely large numbers
• Allows scientific notation input (e.g., "1.5e9 years")
• Custom time scales can be defined for specific scientific applications

Differences from original ms library

• Supports much larger time values (up to eras - billions of years)
• Allows combining multiple units in a single string
• More precise calculations for large time values using BigInt
• Separate parse and format functions exposed
• Written in TypeScript for improved type safety
• Throws more informative errors for invalid inputs
• Includes 'decade', 'century', 'millennium', 'epoch', and 'era' as time units
• Supports custom time scales and units

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.