Build-Time MS Converter Macro

2.0.0 · active · verified Tue Apr 21

ms.macro is a Babel macro designed to convert human-readable time strings (e.g., "1 day", "2 hours") into their corresponding millisecond values directly at build time. This package, currently at version 2.0.0, aims to eliminate runtime dependencies and shift potential conversion errors from runtime to build time. It is a stable package that typically sees updates driven by changes in Babel's macro API or the underlying `ms` package's parsing logic. Its primary differentiator is its build-time execution, which means that the original `ms` package does not need to be shipped with your production code for these specific conversions, resulting in smaller bundle sizes and improved reliability by catching invalid time strings during compilation rather than during execution. Unlike the original `ms` package, `ms.macro` exclusively supports the string-to-number conversion; it does not offer the reverse conversion from milliseconds to a human-readable string.

Common errors

```
Error: Invalid time string: '1 da'
```
cause An incorrectly formatted time string was passed to ms.macro, which is caught during the Babel build process.

fix Correct the time string to a valid format understood by the `ms` library (e.g., '1 day', '2h', '30m').
```
TypeError: ms is not a function
```
cause This error often occurs when `babel-plugin-macros` is not correctly configured, or `ms.macro` is being used in a CommonJS context without proper transpilation, causing the import to not resolve or the macro transformation to fail.

fix Verify that `babel-plugin-macros` is installed and properly configured in your Babel setup. Ensure you are using `import ms from 'ms.macro';` in an environment where Babel is processing your files.

Warnings

gotcha ms.macro only supports converting time strings to milliseconds. It does NOT support converting milliseconds back into human-readable strings, which is a feature of the original `ms` package. Attempting this will result in a build-time error or unexpected behavior.
Fix: For converting milliseconds back to a string, you must use the original `ms` package directly (e.g., `import ms from 'ms';`). You can alias `ms.macro` if both are needed.
breaking This macro requires `babel-plugin-macros` to be correctly configured in your Babel setup. Without it, the `ms.macro` import will not be processed, leading to a runtime error or an unresolved import.
Fix: Ensure `babel-plugin-macros` is installed (`npm install babel-plugin-macros`) and added to your Babel configuration (e.g., in `.babelrc` or `babel.config.js`).
gotcha The macro only supports the single string-argument signature. Passing non-string arguments or multiple arguments will result in a build-time error as the macro expects a parseable time string.
Fix: Always pass a single string representing the time duration to `ms.macro`, e.g., `ms('1 day')` or `ms`1 hour`.

Install

npm install ms.macro npm
yarn add ms.macro yarn
pnpm add ms.macro pnpm

Imports

ms
wrong:
```
const ms = require('ms.macro');
```
correct:
```
import ms from 'ms.macro';
```
Primarily designed for ESM usage with Babel and `babel-plugin-macros`. CommonJS `require` is not the intended usage due to its build-time nature.
ms (tagged template)
```
import ms from 'ms.macro';
const ONE_DAY = ms`1 day`;
```
The macro also supports tagged template literal syntax for convenience, processing at build time identically to the function call.
ms (aliased)
wrong:
```
import { ms } from 'ms.macro';
```
correct:
```
import msm from 'ms.macro';
import ms from 'ms';
const value = msm('1h');
```
If you need both the build-time conversion (ms.macro) and the runtime conversion (original ms package), alias one of the imports. ms.macro uses a default import.

Quickstart

Demonstrates `ms.macro` converting various human-readable time strings into millisecond values at build time, using both function call and tagged template literal syntax.

import ms from 'ms.macro';

// Basic function call usage
const ONE_HOUR = ms('1 hour');
const TWO_DAYS = ms('2 days');
const THIRTY_MINUTES = ms('30m');

// Tagged template literal usage
const ONE_WEEK = ms`1 week`;
const HALF_DAY = ms`0.5d`;

console.log(`One hour in milliseconds: ${ONE_HOUR}`); // -> 3600000
console.log(`Two days in milliseconds: ${TWO_DAYS}`); // -> 172800000
console.log(`Thirty minutes in milliseconds: ${THIRTY_MINUTES}`); // -> 1800000
console.log(`One week in milliseconds: ${ONE_WEEK}`); // -> 604800000
console.log(`Half day in milliseconds: ${HALF_DAY}`); // -> 43200000

view raw JSON →