JavaScriptのNumber.isSafeInteger()：数量の入力値と計算結果を検証する

目的：整数として扱える範囲を確認する

在庫数や累計件数を扱うとき、値が数値であるだけでは十分ではありません。小数が混ざっていないか、整数を正確に区別できる範囲に収まっているかも確認する必要があります。

Number.isSafeInteger()は、渡された値が「安全な整数」かを判定する静的メソッドです。数量を受け取る入口と、数量を計算した直後に置くと、扱える範囲を超えたデータを後続処理へ渡すことを防げます。

ここでいう「安全」は数値表現に関する用語です。アクセス権や業務ルールまで検証する意味ではありません。たとえば負数も安全な整数になり得るため、在庫数ならゼロ以上という条件を別に加えます。

動作環境とバージョン

2026年10月26日時点で、MDNはこのメソッドを広く利用できる機能に分類し、2015年9月以降のブラウザー間で利用可能と説明しています。現在のChrome、Edge、Firefox、Safariで使用できます。古いブラウザーや組み込みWebViewへ配布する場合は、機能の存在を確認してください。MDNの互換性と仕様

ブラウザー専用APIではなく、JavaScriptの標準組み込み機能です。Node.jsでも動作します。この記事の実行手順はNode.js 22以降を対象とし、これは本機能の導入バージョンを意味しません。追加パッケージやimportは不要です。

掲載コードは同期処理だけで構成しています。通信、DOM操作、ファイル読み込みを含まないため、同じコードをブラウザーのコンソールとNode.jsで実行できます。

引数と戻り値

呼び出し方は次のとおりです。

Number.isSafeInteger(value);

• 引数のvalueは判定対象の値です。文字列やnullなども渡せます。
• 戻り値は真偽値です。数値型で、安全な整数ならtrueを返します。
• 文字列を数値へ自動変換しません。"12"はfalseです。
• 引数を省略した場合はundefinedの判定になり、falseです。

安全な整数の範囲は、両端を含む-9007199254740991から9007199254740991です。境界はそれぞれNumber.MIN_SAFE_INTEGERとNumber.MAX_SAFE_INTEGERで参照できます。

JavaScriptの通常の数値型であるNumberは、IEEE 754の倍精度浮動小数点形式を使います。大きすぎる整数では、隣り合う整数を区別できなくなります。値の大きさの上限と、整数を安全に扱える上限は別です。MDNのNumberの説明

数値への変換は判定と分ける

フォーム入力は通常、文字列です。変換を許可する場合でも、どの表記を受け付けるかを先に決めてください。たとえばNumber("")は0になります。変換後の判定だけでは、空欄を数量ゼロとして受け入れる可能性があります。

今回の例では、関数が受け付ける値を最初から数値型に限定します。これにより、文字列からの変換規則を数量計算の中へ持ち込まずに済みます。

自己完結したコードで数量を加算する

次のコードは、現在の数量と追加数量を受け取り、合計を返します。入力の両方と計算結果を検証する点が中心です。外部データやライブラリーは必要ありません。

(() => {
  "use strict";

  if (typeof Number.isSafeInteger !== "function") {
    console.log("この環境はNumber.isSafeIntegerに未対応です");
    return;
  }

  function addQuantity(current, added) {
    if (
      !Number.isSafeInteger(current) ||
      !Number.isSafeInteger(added)
    ) {
      throw new TypeError("数量は安全な整数で指定してください");
    }

    if (current < 0 || added < 0) {
      throw new RangeError("数量はゼロ以上にしてください");
    }

    const total = current + added;

    if (!Number.isSafeInteger(total)) {
      throw new RangeError("合計が安全な整数の範囲を超えています");
    }

    return total;
  }

  const cases = [
    ["通常", 120, 30],
    ["ゼロ", 0, 0],
    ["文字列", "120", 30],
    ["小数", 120, 0.5],
    ["負数", 120, -1],
    ["上限超過", Number.MAX_SAFE_INTEGER, 1],
  ];

  for (const [label, current, added] of cases) {
    try {
      console.log(`${label}: ${addQuantity(current, added)}`);
    } catch (error) {
      if (!(error instanceof Error)) {
        throw error;
      }
      console.log(`${label}: ${error.name}: ${error.message}`);
    }
  }
})();

addQuantity()の引数は現在の数量currentと追加数量addedです。成功時は数値型の合計を返します。失敗時は例外を投げるため、呼び出し側で処理します。

ここでは、整数としての入力条件を満たさない場合にTypeError、ゼロ以上という条件や合計の範囲に違反した場合にRangeErrorを使っています。この例外の分類はサンプル関数の設計です。Number.isSafeInteger()自体は、不適切な型の値を受け取っても型変換せずfalseを返します。

ブラウザーでの実行方法

ブラウザーで空のタブを開き、開発者ツールのConsoleを表示します。上のJavaScriptコード全体を貼り付けて実行してください。貼り付けが制限されている場合は、ブラウザーの案内を確認します。

コードを即時実行関数で囲んでいるため、コンソールで繰り返し実行しても、同名のconst宣言が衝突しにくい構成です。コンソールによっては最後にundefinedも表示されますが、これはコード全体の評価結果です。

Node.jsでの実行方法

Node.js 22以降を用意し、コード全体をUTF-8のsafe-integer-demo.jsとして保存します。ターミナルで保存先のフォルダーを開き、次を実行します。

node --version
node safe-integer-demo.js

最初のコマンドでバージョンを確認し、次のコマンドでファイルを実行します。Node.js公式も、nodeにファイル名を渡す実行方法を説明しています。Node.jsのスクリプト実行手順

期待出力と判定の流れ

対応環境では次の6行が出力される想定です。これは仕様とコードを照合して導いた期待値であり、実機検証結果ではありません。

通常: 150
ゼロ: 0
文字列: TypeError: 数量は安全な整数で指定してください
小数: TypeError: 数量は安全な整数で指定してください
負数: RangeError: 数量はゼロ以上にしてください
上限超過: RangeError: 合計が安全な整数の範囲を超えています

"120"は数値型ではないため拒否します。0.5は整数ではありません。-1は安全な整数の条件を満たしますが、この関数の数量ルールに違反します。

最後のケースでは、入力値は両方とも安全な整数です。それでも合計は範囲外になります。入力検証だけで計算結果まで保証できるわけではないため、加算後にも確認しています。

例外をケースごとに捕捉しているので、失敗例があっても次のケースへ進みます。非同期処理ではないため、awaitやPromiseの拒否処理は必要ありません。

失敗例と制約：元の値の正しさまでは復元できない

整数らしく見えても区別できない場合がある

次のコードも、ブラウザーとNode.jsの両方で試せます。

console.log(9007199254740992 === 9007199254740993);
console.log(Number.isSafeInteger(9007199254740992));
console.log(Number.isSafeInteger(3.0));
console.log(Number.isSafeInteger(NaN));
console.log(Number.isSafeInteger(Infinity));

期待出力は次のとおりです。

true
false
true
false
false

最初の比較では、右辺の整数リテラルを正確に表現できず、左辺と同じ数値になります。また、3.0は数値として3と同じなのでtrueです。小数点を含む表記かどうかを調べる機能ではありません。

すでに起きた丸めは検出できない

console.log(Number.isSafeInteger(5.0000000000000001));

期待出力はtrueです。このリテラルは数値になる段階で5に丸められます。メソッドが受け取るのは丸めた後の値なので、元の表記に小数部分があったことは判断できません。

そのため、外部データの正確さを保証するには受け渡し形式も設計します。大きな識別子は文字列のまま保持し、大きな整数の計算が必要ならBigIntなどの採用を検討してください。Numberに変換してから判定しても、失われた情報は戻りません。

活用事例と実装を改善するポイント

在庫の加算、処理済み件数の集計、整数単位の使用量管理など、通常の数値型で数量を扱う境界に適しています。フロントエンドで確認すると入力ミスを早く伝えられますが、受信側でも同じ条件を検証してください。

実務では、安全な整数の上限に加えて業務上の最大値を設けると、エラーを理解しやすくできます。たとえば1回の追加数量を1000以下に制限するなら、その条件も計算前に確認します。数値表現として有効でも、業務上は受け入れられない値があるためです。

次の行動は、数量を受け取る箇所を1つ選び、型・整数範囲・業務範囲・計算結果の確認がそろっているかを点検することです。まずこの境界を明確にすると、画面とサーバーで検証方針を共有しやすくなります。

公式参考資料

• MDN：Number.isSafeInteger()の引数・戻り値・互換性
• MDN：Numberの数値表現と型変換
• Node.js：コマンドラインからスクリプトを実行する