本文へ移動
技術を、自社の仕事に。
判断と実行を助けるメディア

記事を検索

Node.js標準のthrottleでAPIの呼び出しを絞る

目次 · 7項目

社内のデータを外部の API へ一括で書き込むバッチを作ると、相手の API の「1秒あたり何回まで」「同時に何本まで」といった制限に当たらないよう、呼び出しの間隔を空ける処理が必要になります。これまで Node.js の標準モジュールには、この用途の専用の関数はなく、自分で書くか npm のライブラリを使う必要がありました。

Node.js の標準モジュール node:util に、この用途の関数 util.throttle() と、続けて起きる呼び出しを1回にまとめる util.debounce() が加わりました。あわせて node:crypto には、.p12・.pfx の形式の証明書と秘密鍵を読む crypto.parsePKCS12() が加わっています。

いずれも Node.js 26.10.0(nodejs.org の配布一覧では2026年9月21日、CHANGELOG の見出しでは9月22日)で入り、LTS の 24.22.0(10月14日)にも取り込まれました。本記事では、公式ドキュメントの記述をもとに、業務のバッチや連携で使うときの設定の選び方と、導入前に確かめる点を整理します。

使える版

公式ドキュメントの各関数の「Added in」と、リリースの変更履歴に基づきます。

  • 26.x:26.10.0 から。11月20日時点の最新は 26.13.1(LTS)です
  • 24.x(LTS):24.22.0 から。CHANGELOG_V24.md の 24.22.0 の Notable Changes に util.throttle・debounce・crypto.parsePKCS12() が SEMVER-MINOR として載っています。11月20日時点の 24 系の最新は 24.22.3 です
  • 22.x(LTS):v22 系のドキュメント(11月20日時点の最新の 22.23.5 の版)には載っていません。編集部の Linux の環境の Node.js 22.23.4 でも、typeof util.debounce・typeof util.throttle・typeof crypto.parsePKCS12 はいずれも undefined でした

社内のサーバーや CI が 22 系のままなら、標準の関数に置き換えたコードは動きません。使う場合は、package.json の engines に "node": ">=24.22.0" のように書き、実行環境の版をそろえてから切り替えます。

util.throttle:回数と同時実行数を絞る

util.throttle(fn, limit, interval[, options]) は、interval ミリ秒の間に fn を limit 回まで呼ぶ関数を返します。返された関数は fn の戻り値の Promise を返します。ドキュメントの例は次のとおりです。

import { throttle } from 'node:util';

const request = throttle(async (id) => {
  const response = await fetch(`https://example.com/items/${id}`);
  return response.json();
}, 2, 1_000);

// 1秒の区間に始まるリクエストは最大2つ。残りは引数を保ったまま待つ
const results = await Promise.all([request(1), request(2), request(3), request(4)]);

既定では、上限を超えた呼び出しは捨てられずに、受けた順に待ち行列に入ります。業務で使うときに効いてくる選択肢は次のとおりです。

オプション既定決めること
concurrencyInfinity戻り値が決着していない呼び出しを同時に何本まで許すか。応答の遅い API で、同時接続の上限がある場合に使う
strictfalse既定は「最初の呼び出しから区間が始まる」窓の数え方で、ドキュメントは区間の境目で呼び出しが近接しうるとしている。true にすると、どの連続した区間でも limit を超えないよう呼び出しごとの時刻を記録する
overflow'queue''drop' にすると、すぐに呼べない呼び出しを待たせずに ERR_THROTTLED で拒否する
maxPendingInfinity'queue' のとき、待ち行列に入れる数の上限。超えた呼び出しは ERR_THROTTLED で拒否される

相手の API の制限が「どの1秒を切り出しても N 回まで」と読める場合は、境目での近接を避けるため strict: true を選ぶのが安全です。数万件を一気に投入するバッチでは、maxPending を決めないと、待ち行列の引数がすべてメモリに残ります。

返された関数には、待ち行列を空にする cancel()、今呼べばすぐ実行されるかを返す hasImmediateCapacity()、待っている数の pendingCount、実行中の数の activeCount があります。options.signal に AbortSignal を渡すと、中止したときに待っている呼び出しと以降の呼び出しが AbortError で拒否されます。すでに始まった呼び出しは止まりません。

util.debounce:続けて起きる呼び出しを1回にまとめる

util.debounce(fn, wait[, options]) は、最後の呼び出しから wait ミリ秒たってから fn を1回呼ぶ関数を返します。ファイルの変更を監視して再処理する、設定の変更が続く間は保存を待つ、といった用途です。

ドキュメントによると、待っている間に何度呼んでも fn が受け取るのは最後の呼び出しの引数で、既定では、まとめられたすべての呼び出しの Promise が同じ結果で決着します。rejectOnCancel: true にすると、後の呼び出しに置き換えられた呼び出しは AbortError で拒否されます。leading: true は、区間の最初の呼び出しをすぐに実行します。待たずにすぐ実行する flush() と、取りやめる cancel() もあります。

戻り値が Promise である点に注意が必要です。既存のコードで別の debounce の実装を使っている場合は、置き換える前に、戻り値を使っている箇所があるかを探します。

crypto.parsePKCS12:.p12・.pfxを読む

crypto.parsePKCS12(bundle[, options]) は、DER 形式の PKCS#12 のデータ(.p12・.pfx)を受け取り、privateKey(最初の秘密鍵、なければ null)、certificate(その鍵に対応する証明書、なければ null)、additionalCertificates(それ以外の証明書)を返します。パスフレーズは options.passphrase に渡し、省略すると空文字列を渡したのと同じ扱いです。

import { parsePKCS12 } from 'node:crypto';
import { readFileSync } from 'node:fs';

const { privateKey, certificate, additionalCertificates } = parsePKCS12(
  readFileSync('bundle.p12'),
  { passphrase: process.env.P12_PASSPHRASE },
);

TLS の接続の設定には以前から pfx の指定で PKCS#12 を渡せますが、parsePKCS12() は中の秘密鍵を KeyObject、証明書を X509Certificate として取り出せる点が違います。クライアント証明書で認証する連携で、配られた .pfx の証明書の有効期限(X509Certificate の validTo)をバッチで確かめる、といった使い方ができます。パスフレーズはコードに書かず、環境変数や秘密情報の管理の仕組みから渡します。

導入するときの順番(編集部の提案)

ここからは編集部の提案です。

  1. 実行環境の版をそろえる。 本番・検証・CI・開発者の端末で node -v を確かめ、24.22.0 以上(26 系なら 26.10.0 以上)にそろえる。Cloudflare Workers Builds のようにビルド環境の Node.js の版が別に決まる場合は、その設定も確かめる
  2. 相手の API の制限を書き出す。 回数の上限の単位(秒・分)、同時接続の上限、超えたときの応答(429 など)を、相手のドキュメントで確かめてから limit・interval・concurrency を決める
  3. 待ち行列の上限を決める。 maxPending を決め、超えたときの ERR_THROTTLED をどう扱うか(あとで再実行する、ログに残す)を書く
  4. 置き換えは1か所ずつ。 既存のライブラリから置き換える場合は、戻り値と例外の扱いの違いを1か所で確かめてから広げる

Node.js の版の上げ方は、Node.js 26.11の記事やWorkers Buildsの既定のNode.jsの記事でも扱いました。

確認した範囲

2026年11月17日に、Node.js の公式ドキュメント(nodejs.org の util・crypto の v26 と v24 の版、JSON 形式を含む)、nodejs/node のリポジトリ(doc/api/util.md・errors.md、CHANGELOG_V24.md)、nodejs.org のリリースの一覧を確認しました(資料調査)。編集部の Linux の環境の Node.js 22.23.4 で3つの関数が存在しないことを確かめました。11月20日に、公式ドキュメントと CHANGELOG、リリースの一覧を確認し直しました。24.22 以降・26.10 以降での動作の確認は行っていません。

社内のバッチや外部 API との連携の作り直し、Node.js の版の更新は、グリームハブの開発・AI・自動化のご相談で承っています。構成によって進め方が変わるため、お問い合わせからご相談ください。

参考資料

この記事を共有XFacebook
鈴木 翔

技術の可能性に魅了され、学生時代からプログラミングとデジタルアートの分野に深い関心を持つ

この記事のテーマを、自社の次の一歩へ

自社での進め方を、具体的に。

つくりたい仕組み、既存システム、運用の条件を整理し、実現に向けた次の一歩を考えます。

  • 実現したい仕組み
  • 既存環境との接続
  • 運用の条件
開発・運用の構想を相談する

構想段階からご相談いただけます。この記事の情報を相談フォームに引き継ぎます。

最新記事をメールで受け取る