ms の使い方 — ミリ秒変換ユーティリティの決定版

一言でいうと

ms は、人間が読みやすい時間表現（"2 days", "1h" など）とミリ秒を相互変換する超軽量ユーティリティです。Express や debug など多くの有名パッケージが内部で利用しており、npm エコシステムで最も依存されているパッケージの一つです。

どんな時に使う？

• JWT やキャッシュの有効期限を設定するとき — 1000 * 60 * 60 * 24 * 7 のような計算を "7d" と書ける
• タイムアウトやリトライ間隔を設定ファイルで管理するとき — 設定値を人間が読める形式で記述できる
• ログやデバッグ出力でミリ秒を読みやすく表示したいとき — 60000 を "1m" に変換できる

インストール

# npm
npm install ms

# yarn
yarn add ms

# pnpm
pnpm add ms

TypeScript の型定義は本体に含まれていないため、別途インストールします。

npm install -D @types/ms

基本的な使い方

import ms from 'ms';

// 文字列 → ミリ秒
ms('2 days');   // 172800000
ms('1h');       // 3600000
ms('30m');      // 1800000

// ミリ秒 → 文字列（短縮形）
ms(60000);      // "1m"
ms(172800000);  // "2d"

// ミリ秒 → 文字列（長い形式）
ms(60000, { long: true });      // "1 minute"
ms(172800000, { long: true });  // "2 days"

実用例：JWT の有効期限設定

import ms from 'ms';

const TOKEN_EXPIRY = ms('7d'); // 604800000

// setTimeout やライブラリの設定にそのまま渡せる
setTimeout(() => {
  console.log('トークンが期限切れになりました');
}, TOKEN_EXPIRY);

よく使う API

ms は単一の関数ですが、引数の型によって動作が変わります。主要なパターンを紹介します。

1. 文字列 → ミリ秒変換

import ms from 'ms';

ms('100');      // 100       （単位なしは数値としてパース）
ms('10ms');     // 10
ms('5s');       // 5000
ms('30m');      // 1800000
ms('2h');       // 7200000
ms('1d');       // 86400000
ms('1w');       // 604800000
ms('1y');       // 31557600000

対応する単位一覧：

2. スペースありの長い形式でも変換可能

import ms from 'ms';

ms('2 days');       // 172800000
ms('1.5 hours');    // 5400000
ms('100 milliseconds'); // 100

3. ミリ秒 → 短縮文字列

import ms from 'ms';

ms(500);        // "500ms"
ms(1000);       // "1s"
ms(60000);      // "1m"
ms(3600000);    // "1h"
ms(86400000);   // "1d"

4. ミリ秒 → 長い形式の文字列（{ long: true }）

import ms from 'ms';

ms(500, { long: true });        // "500 ms"
ms(1000, { long: true });       // "1 second"
ms(1500, { long: true });       // "1.5 seconds"
ms(60000, { long: true });      // "1 minute"
ms(86400000, { long: true });   // "1 day"
ms(172800000, { long: true });  // "2 days"

5. 無効な入力のハンドリング

import ms from 'ms';

ms('');           // undefined
ms('abc');        // undefined
ms(undefined!);   // undefined
ms(NaN);          // undefined
ms(Infinity);     // undefined

無効な値が渡された場合は undefined を返します。例外はスローされません。

類似パッケージとの比較

使い分けの指針：

• シンプルな変換だけでいい → ms
• 1h 30m 15s のような複合表示が必要 → pretty-ms
• 多言語対応が必要 → humanize-duration

注意点・Tips

1. 月（month）は非対応

ms('1 month') は undefined を返します。月は日数が一定でないため、意図的にサポートされていません。年（y）は365.25日として計算されます。

2. 複合表現は使えない

// ❌ これは動かない
ms('1h30m');    // undefined
ms('1h 30m');   // undefined

// ✅ 自分で足し算する
const duration = ms('1h')! + ms('30m')!; // 5400000

3. 戻り値の型に注意

ms の戻り値は number | undefined（文字列入力時）または string（数値入力時）です。TypeScript で使う場合は undefined チェックを忘れずに。

import ms from 'ms';

const value = ms('1h');
if (value === undefined) {
  throw new Error('Invalid duration format');
}
// ここでは value は number 型として安全に使える
setTimeout(callback, value);

4. 負の値も扱える

import ms from 'ms';

ms('-3 days');   // -259200000
ms(-259200000);  // "-3d"

5. 小数も使える

import ms from 'ms';

ms('1.5h');      // 5400000
ms('0.5d');      // 43200000

まとめ

ms は「時間のミリ秒変換」というシンプルな課題を、わずか数百バイトで解決する定番パッケージです。マジックナンバーとしてミリ秒をハードコードする代わりに ms('7d') と書くだけで、コードの可読性が大幅に向上します。Express、debug、jsonwebtoken など主要パッケージの内部でも使われており、信頼性は折り紙付きです。