@anonymort/ms-long
v2.0.0
Published
Extended time conversion utility supporting large values and multiple units
Downloads
6
Maintainers
Readme
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
andformat
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
npm install @anonymort/ms-long
Usage
import msLong, { parse, format } from '@anonymort/ms-long';
// Parse time strings
console.log(msLong('2 hours 30 minutes')); // 9000000n
// Format milliseconds
console.log(msLong(9000000n)); // '2h 30m'
console.log(msLong(9000000n, { long: true })); // '2 hours 30 minutes'
// Parse complex time strings with large units
console.log(parse('2 epochs 1 era')); // 1002000000000000000000n
// Format large values
console.log(format(1002000000000000000000n, { long: true }));
// '1 era 2 epochs'
// Use scientific notation
console.log(parse('1.5e9 years')); // 47304000000000000000000n
// Custom time scales
const customUnits = {
galacticYear: 230000000000n * 365n * 24n * 60n * 60n * 1000n, // ~230 million years
};
console.log(parse('2 galacticYears', customUnits)); // 14515200000000000000000n
console.log(format(14515200000000000000000n, { long: true, customUnits }));
// '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
andformat
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.