ms

Tiny millisecond conversion utility

Showing:

Popularity

Downloads/wk

104M

GitHub Stars

3.7K

Maintenance

Last Commit

1mo ago

Contributors

30

Package

Dependencies

0

Size (min+gzip)

0.7KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Reviews

Average Rating

4.7/53
Read All Reviews
shafayet1404052
KamrulSh

Top Feedback

3Easy to Use
2Great Documentation

Readme

ms

CI

Use this package to easily convert various time formats to milliseconds.

Examples

ms('2 days')  // 172800000
ms('1d')      // 86400000
ms('10h')     // 36000000
ms('2.5 hrs') // 9000000
ms('2h')      // 7200000
ms('1m')      // 60000
ms('5s')      // 5000
ms('1y')      // 31557600000
ms('100')     // 100
ms('-3 days') // -259200000
ms('-1h')     // -3600000
ms('-200')    // -200

Convert from Milliseconds

ms(60000)             // "1m"
ms(2 * 60000)         // "2m"
ms(-3 * 60000)        // "-3m"
ms(ms('10 hours'))    // "10h"

Time Format Written-Out

ms(60000, { long: true })             // "1 minute"
ms(2 * 60000, { long: true })         // "2 minutes"
ms(-3 * 60000, { long: true })        // "-3 minutes"
ms(ms('10 hours'), { long: true })    // "10 hours"

Features

  • Works both in Node.js and in the browser
  • If a number is supplied to ms, a string with a unit is returned
  • If a string that contains the number is supplied, it returns it as a number (e.g.: it returns 100 for '100')
  • If you pass a string with a number and a valid unit, the number of equivalent milliseconds is returned

TypeScript support

As of v3.0, this package includes TypeScript definitions.

For added safety, we're using Template Literal Types (added in TypeScript 4.1). This ensures that you don't accidentally pass ms values that it can't process.

This won't require you to do anything special in most situations, but you can also import the StringValue type from ms if you need to use it.

import ms, { StringValue } from 'ms';

// Using the exported type.
function example(value: StringValue) {
  ms(value);
}

// This function will only accept a string compatible with `ms`.
example('1 h');

In this example, we use a Type Assertion to coerce a string.

import ms, { StringValue } from 'ms';

// Type assertion with the exported type.
function example(value: string) {
  try {
    // A string could be "wider" than the values accepted by `ms`, so we assert
    // that our `value` is a `StringValue`.
    //
    // It's important to note that this can be dangerous (see below).
    ms(value as StringValue);
  } catch (error: Error) {
    // Handle any errors from invalid vaues.
    console.error(error);
  }
}

// This function will accept any string, which may result in a bug.
example('any value');

You may also create a custom Template Literal Type.

import ms from 'ms';

type OnlyDaysAndWeeks = `${number} ${'days' | 'weeks'}`;

// Using a custom Template Literal Type.
function example(value: OnlyDaysAndWeeks) {
  // The type of `value` is narrower than the values `ms` accepts, which is
  // safe to use without coercion.
  ms(value);
}

// This function will accept "# days" or "# weeks" only.
example('5.2 days');
  • ms.macro - Run ms as a macro at build-time.

Caught a Bug?

  1. Fork this repository to your own GitHub account and then clone it to your local device
  2. Link the package to the global module directory: npm link
  3. Within the module you want to test your local development instance of ms, just link it to the dependencies: npm link ms. Instead of the default one from npm, Node.js will now use your clone of ms!

As always, you can run the tests using: npm test

Rate & Review

Great Documentation2
Easy to Use3
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
shafayet140405252 Ratings72 Reviews
10 months ago
Easy to Use
Great Documentation

Changing the time format from days, minutes, etc to milliseconds format, this is a lightweight tool. I have used it several times and it is very easy to use and also has great documentation.


2
vishnuprasad-95
aswanikv
Kamrul Islam ShahinChittagong, Bangladesh73 Ratings53 Reviews
B.Sc in Computer Science and Engineering @ CUET 🌱 Educator 💻 Programmer 🌐 Developer
10 months ago
Easy to Use

A handy tool for changing time format into milliseconds. But when it comes to converting ms into the human-readable format it only displays days. By the way, it is a great tool.


0
Prashik GawaiWashim Maharashtra20 Ratings40 Reviews
@ITEngineer@Influencer @softwaredeveloper @Full Stack Developer Beginner @Student.
7 months ago
Great Documentation
Easy to Use

Tutorials

No tutorials found
Add a tutorial