https://github.com/apteryxxyz/enhanced-ms
Convert human readable time-frame strings to milliseconds and vice versa, with support for i10n and operators!
https://github.com/apteryxxyz/enhanced-ms
browser convert duration humanise javascript milliseconds ms node parse pretty readable seconds string time typescript
Last synced: 7 months ago
JSON representation
Convert human readable time-frame strings to milliseconds and vice versa, with support for i10n and operators!
- Host: GitHub
- URL: https://github.com/apteryxxyz/enhanced-ms
- Owner: apteryxxyz
- License: mit
- Created: 2021-03-15T06:02:30.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-20T19:49:29.000Z (about 1 year ago)
- Last Synced: 2025-08-11T20:42:19.621Z (10 months ago)
- Language: TypeScript
- Homepage: https://npmjs.com/enhanced-ms
- Size: 1.19 MB
- Stars: 17
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
Enhanced MS
Convert milliseconds to human-readable duration strings and vice versa
npm install enhanced-ms
## π€ About
`enhanced-ms` is a flexible library for formatting milliseconds into human-readable durations and vice versa. It is an enhanced version of the popular [`ms`](https://www.npmjs.com/package/ms) with support for multiple inputs, localization, and more options.
## π Table of Contents
- [π¦ Installation](#-installation)
- [π§ Comparison](#-comparison)
- [π Usage](#-usage)
- [π Examples](#-examples)
## π¦ Installation
Install using your preferred package manager:
```bash
npm install enhanced-ms
pnpm add enhanced-ms
yarn add enhanced-ms
```
## π§ Comparison
As mentioned above, `enhanced-ms` is an enhanced version of the popular [`ms`](https://www.npmjs.com/package/ms), so how does it compare?
| Feature | `enhanced-ms` | [`ms`](https://www.npmjs.com/package/ms) | [`pretty-ms`](https://www.npmjs.com/package/pretty-ms) | [`itty-time`](https://www.npmjs.com/package/itty-time) |
| ----------------------------------------------- | ------------- | ---------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| Convert Milliseconds to Duration | β
| β
| β
| β
|
| Convert Milliseconds to Multiple Duration Units | β
| β | β | β |
| Convert Duration to Milliseconds | β
| β
| β | β
|
| Convert Multiple Duration Units to Milliseconds | β
| β | β | β |
| Localization Support | β
| β | β | β |
## π Languages
The currently supported languages include:
| Language | Key |
| ----------------- | --- |
| English (default) | en |
| German | de |
| Russian | ru |
| MΔori | mi |
| Spanish | es |
| Dutch | nl |
| Italian | it |
| French | fr |
You can help by adding support for more languages.
Make a pull request [here](https://github.com/apteryxxyz/enhanced-ms/tree/main/src/languages).
## π Usage
### Language and Default Options
The `createMs` function allows you to create a new instance of `ms` with a custom language and custom default options. This is useful if you want to use a different language or prefer different default options for parsing and formatting.
```ts
function createMs(options?: CreateMsOptions): typeof ms;
```
| Option | Type | Description | Default |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `language` | `Locale` \| `LanguageDefinition` | The language to use for parsing and formatting, if your preferred isn't supported, you can directly pass a language definition. | `en` |
| `formatOptions` | `FormatOptions` \| `FormatOptionsPreset` | The options to use for formatting. | see below |
### Formatting Milliseconds to Duration
The `ms` function allows you to format a number of milliseconds to a duration string. Passing a number of milliseconds will return a duration string, if the number is invalid, it will return `null`. The milliseconds overloads also allows you to pass a `FormatOptions` object or a `FormatOptionsPreset` to customise the formatting.
```ts
function ms(milliseconds: number): string | null;
function ms(milliseconds: number, options: FormatOptions): string | null;
function ms(milliseconds: number, preset: FormatOptionsPreset): string | null;
```
| Option | Type | Description | Default |
| ------------------ | --------------------- | ------------------------------------------------------------------ | --------------------------------------------- |
| `extends` | `FormatOptionsPreset` | Extends the preset with the given options. | none |
| `hideUnitNames` | `boolean` | Hide unit names from the output. | `false` |
| `useAbbreviations` | `boolean` | Use abbreviations for unit names. | `false` |
| `includeZero` | `boolean` | Include units with the value 0 in the output. | `false` |
| `includeMs` | `boolean` | Include milliseconds in the output. | `false` |
| `includeSubMs` | `boolean` | Include sub-millisecond units in the output. | `false` |
| `includedUnits` | `ParseUnit[]` | Which units should be included in the output. | `['year', 'day', 'hour', 'minute', 'second']` |
| `unitLimit` | `number` | The maximum number of units to include in the output. | `-1` |
| `unitSeparator` | `string` | The separator to use between units. | ` ` |
| `minimumDigits` | `number` | The minimum number of digits for a unit, aka will pad with zeroes. | `0` |
| Preset | Example |
| --------------- | -------------------------------------------------------------- |
| `short` | `1m 30s` |
| `fullPrecision` | `10 seconds 100 milliseconds 100 microseconds 100 nanoseconds` |
| `colonNotation` | `00:01:30` |
### Parsing Duration to Milliseconds
The `ms` function also allows you to parse a duration string (`1 day`, `3 weeks 4 days`, etc). Passing a duration string will return a number of milliseconds, if no valid duration units are found, it will return `0`.
```ts
function ms(duration: string): number;
```