README.md

true-ms

true-ms is a JavaScript utility package to easily convert various time formats to a precise number of milliseconds.

---

• Features
• Installation
• Examples
  • Convert from Duration Object
  • Convert from a Date
  • Convert from Milliseconds
  • Time Format Written-Out
• Documentation
• Migrations
  • Migration from vercel/ms
• Contributing
• License

👀 Features

• Calculates leap years. (Read: Gregorian calendar and Common year)
• Compatible with Node.js, Edge Runtime and browsers.
• Compatible with vercel/ms package that has the worst accuracy.
• When a number is supplied to ms, a string formatted with a unit is returned.
• When a string containing a number is provided, it is converted and returned as a number (for example, '100' returns 100).
• When a string with a number and a valid unit is passed, the equivalent number of milliseconds is returned.

📦 Installation

npm install true-ms

📝 Examples

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

Convert from Duration Object

ms({ hours: 10 })          // 36000000
ms({ days: 2 })            // 172800000
ms({ minutes: 1 })         // 60000
ms({ seconds: 5 })         // 5000
ms({ years: 1 })           // 31536000000
ms({ months: 1, days: 1 }) // 2764800000

Convert from a Date

ms('1mon', { from: new Date('2016-01-01') }) // 2678400000 - 31 days in Jan 2016
ms('1mon', { from: new Date('2017-02-01') }) // 2419200000 - 28 days in Feb 2017
ms('1y', { from: new Date('2016-01-01') })   // 31622400000 - Leap year; 366 days
ms('1y', { from: new Date('2015-01-01') })   // 31536000000 - Non-leap year; 365 days

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"

📚 Documentation

For all configuration options, please see the API docs.

🚀 Migrations

Migration from vercel/ms

The true-ms package is fully compatible with vercel/ms. All you need to do is remove ms from your dependencies and replace it with true-ms.

- import ms from 'ms';
+ import ms from 'true-ms';

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Thanks again for your support, it is much appreciated! 🙏

License

MIT © Shahrad Elahi