Node.js 26.10 で util に debounce / throttle が標準搭載されました。lodash と何が違うのか、Promise の扱いやキャンセル時の挙動を Node.js 26.10.0 で実際に動かして確かめました。
lodashのdebounceを標準APIに替えたいが、Promiseとキャンセルの扱いが不安な人へ
- lodashのdebounceは戻り値が無く、Promiseと組み合わせるのが面倒
- キャンセルした呼び出しのPromiseがresolveされるのかrejectされるのか分からない
- throttleで「捨てられた」呼び出しが無くなるのか不安
対象読者: Node.jsでlodashなどのdebounce / throttleを使っている人です。
前提知識: PromiseとsetTimeoutの基本です。
結論
戻り値がPromiseになるのが最大の違いです。v26.10.0で追加されたutil.debounce()は、windowが閉じるときに最後の呼び出しだけ実行し、呼び出しごとのPromiseに結果を返します。
import { setTimeout as wait } from 'node:timers/promises';
import { debounce } from 'node:util';
const fn = debounce(async (value) => {
await wait(100);
return value;
}, 50);
const first = fn(1);
const second = fn(2);
// fn(2)だけが実行され、両方のPromiseがその結果を受け取る
console.log(await first); // 2
console.log(await second); // 2基本は「最後の1回だけ実行、全Promiseが同じ結果になる」
debounceはwindowと呼ぶ待機区間を作り、windowが閉じるタイミングで最後の呼び出しだけfnを実行します。打ち消された呼び出し側のPromiseも、最終的な実行結果でresolveされます。
import { debounce } from 'node:util';
const save = debounce((value) => `saved:${value}`, 30);
const first = save(1);
const second = save(2);
console.log('pending === second:', save.pending === second); // true
console.log('pendingCount:', save.pendingCount); // 2
console.log(await first); // saved:2 ← 1の呼び出しは実行されない
console.log(await second); // saved:2
// 実行結果
// node: v26.10.0
// pending === second: true
// pendingCount: 2
// await first : saved:2
// await second: saved:2window内の呼び出し数はpendingCount、最新のPromiseはpendingプロパティで参照できます。これらはlodashには無い観測ポイントです。
leading:trueでもtrailingは「window内に2回目があった場合だけ」
lodashとは違う設計で、標準にはtrailingオプション自体がありません。leading:trueで最初の呼び出しが即時実行されても、待機後の実行(trailing)はwindowの間に2回目以降の呼び出しがあった場合だけ発生します。
import { setTimeout as wait } from 'node:timers/promises';
import { debounce } from 'node:util';
const runs = [];
const fn = debounce((v) => { runs.push(v); return v; }, 50, { leading: true });
console.log('first :', await fn('a')); // 即時実行
const t = fn('b'); // window内2回目 → trailing保留
console.log('runs after 2nd call:', JSON.stringify(runs));
console.log('trailing:', await t);
await wait(80);
console.log('runs after wait:', JSON.stringify(runs));
const runs2 = [];
const f2 = debounce((v) => { runs2.push(v); return v; }, 40, { leading: true });
console.log('single:', await f2('only'));
await wait(80);
console.log('runs2:', JSON.stringify(runs2)); // trailingは走らない
// 実行結果
// first : a
// runs after 2nd call: ["a"]
// trailing: b
// runs after wait: ["a","b"]
// single: only
// runs2: ["only"]leading:trueの単発呼び出しではfnは1回しか走りません。lodashではleadingとtrailingが独立して有効になっていたので、移行時に最初に引っかかる点です。
キャンセルはrejectOnCancel / cancel / flush / signalの4通り
rejectOnCancel:trueを付けると、後続の呼び出しに打ち消されたPromiseはAbortErrorでrejectされます。既定では全Promiseが最終結果でresolveされるので、「キャンセルなのに成功扱い」にしたくない場合に付けます。
import { debounce } from 'node:util';
const withReject = debounce((v) => v, 30, { rejectOnCancel: true });
const p1 = withReject(1);
const p2 = withReject(2);
p1.catch((e) => console.log('p1:', e.name));
console.log('p2:', await p2);
const without = debounce((v) => v, 30);
console.log('q1:', await without(1), 'q2:', await without(2));
// 実行結果
// p1: AbortError
// p2: 2
// q1: 2 q2: 2 ← 既定では打ち消されても最終結果でresolvecancel()はrejectOnCancelの有無に関係なく保留中のPromiseをAbortErrorでrejectし、理由はcauseに入ります。flush()は待機を飛ばして即時実行します。signalは実行開始後のabortでも保留中と将来の呼び出しをrejectし、abort済みのsignalを渡すとdebounce()自体がAbortErrorを投げます。
import { debounce } from 'node:util';
const c = debounce((v) => v, 1000);
const r = c('x');
c.cancel(new Error('stopped'));
r.catch((e) => console.log('cancel:', e.name, '-', e.cause.message));
const f = debounce((v) => v, 1000);
const s = f('y');
f.flush();
console.log('flush:', await s);
const ac = new AbortController();
ac.abort();
try {
debounce(() => {}, 10, { signal: ac.signal });
} catch (e) {
console.log('aborted signal:', e.name);
}
// 実行結果
// cancel: AbortError - stopped
// flush: y
// aborted signal: AbortErrorwindowはfnを呼ぶ前に開始される
非同期fnが未解決の間に呼ばれた呼び出しや、fnからの再帰呼び出しも同じwindowに入ります。windowはfnの実行前に開始されるためです。
import { setTimeout as wait } from 'node:timers/promises';
let runs = 0;
const fn = debounce(async (v) => {
runs++;
await wait(60);
return v;
}, 40);
const p1 = fn(1);
await wait(10);
const p2 = fn(2); // 同じwindowに合流
console.log(await p1, await p2); // 2 2
console.log('runs total:', runs); // 1 ← 2回呼んでもfnは1回
// 実行結果
// 2 2
// runs total: 1加えてfnに渡されるthisはdebounced function自身で、nameとlengthも引き継がれます。実測ではnamed: original length: 2と出ていました。
util.throttleは「捨てない」設計
throttleはwindow内の上限(limit)を超えた呼び出しを、既定では捨てずにキューへ入れます。キューはFIFOで、windowが進むたびに最大limit件ずつ処理されます。
import { throttle } from 'node:util';
const t0 = Date.now();
const starts = [];
const fn = throttle(async (id) => {
starts.push(`${id}@${Date.now() - t0}ms`);
return id;
}, 2, 80); // 80msあたり最大2回
const results = await Promise.all([fn(1), fn(2), fn(3), fn(4)]);
console.log('results:', JSON.stringify(results));
console.log('starts:', JSON.stringify(starts));
// 実行結果
// results: [1,2,3,4]
// starts: ["1@0ms","2@0ms","3@95ms","4@95ms"] ← 3,4は次windowでまとめて開始window方式の注意点と、厳密に上限を守りたい場合の選択肢は次のとおりです。
- window方式は、境界付近で呼び出しが詰まることがある(公式の注意点)
- intervalあたりの回数を厳密に守りたいならstrict:true。開始時刻を個別に記録してrolling interval内の上限を保証する代わりに、管理コストが増える
捨てたい場合はoverflow: ‘drop’を付けます。拒否された呼び出しはERR_THROTTLEDでrejectされますが、handled印が付くためunhandledRejectionにはなりません。
import { throttle } from 'node:util';
const drop = throttle((id) => id, 1, 1000, { overflow: 'drop' });
const p1 = drop(1);
const p2 = drop(2); // 容量なし → 即時reject
p2.catch((e) => console.log('drop:', e.code));
console.log('p1:', await p1);
try {
throttle(() => {}, 0, 100); // limitは1以上
} catch (e) {
console.log('limit=0:', e.constructor.name);
}
// 実行結果
// drop: ERR_THROTTLED
// p1: 1
// limit=0: RangeErrormaxPendingでキューの長さも制限でき、あふれた分もERR_THROTTLEDになります。余裕の確認にはhasImmediateCapacity()が使えますが、予約はしないため呼ぶ直前に再チェックされます。
つまずきポイント
- leading:trueでもwindow内が1回だけならfnは1回しか走らない。lodash移行で「2回実行されない」と疑う場合はwindow内の呼び出し回数を確認する
- rejectOnCancelを付け忘れると、打ち消された呼び出しのPromiseも最終結果でresolveされる
- abort済みのsignalを渡すとdebounce() / throttle()がAbortErrorを投げる。呼び出し側でtry/catchが必要
- throttleのlimit=0はRangeError。validationは呼び出し時に行われる
- ERR_THROTTLEDはunhandledRejectionにならないが、awaitしないと結果を見逃す
検証環境
| OS | Windows 11 (build 10.0.26200) |
|---|---|
| CPU | AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics |
| メモリ | 28GB |
| 言語/ツール | Node.js 26.10.0(公式のポータブル配布を一時ディレクトリに展開) |
| 使用コマンド | ./node.exe exp1.mjs 〜 exp8.mjs(debounce/throttle の各挙動を実測) |
| 測定日 | 2026-10-30 |
上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

まとめ
lodashからの置き換えで押さえておきたい違いは次のとおりです。
| 観点 | lodash | node:util |
|---|---|---|
| 戻り値 | なし | Promise(呼び出しごと) |
| leading / trailing | それぞれ独立に指定 | leadingのみ。trailingは「window内に2回目があれば」 |
| 打ち消された呼び出し | 結果を通知しない | 既定は最終結果でresolve / rejectOnCancelでAbortError |
| キャンセルAPI | cancel()(戻り値なし) | cancel / flush / pending / pendingCount |
| AbortSignal | 非対応 | signalオプション |
| throttleの過剰呼び出し | 捨てる | 既定はキュー(overflow: ‘drop’で捨てる) |
Promise中心で書ける分、async/awaitとの相性はnode:util版の方が良いです。lodashを削るなら今がちょうど良いタイミングですよ。
参考
- Node.js v26.10.0 リリースノート(公式)
- util.debounce() APIリファレンス(公式)
- util.throttle() APIリファレンス(公式)
- nodejs/node CHANGELOG(公式リポジトリ)
あわせて読みたい
- 【JS・フロントエンド】Node.js 26の新機能まとめ — TemporalやIterator.concatを今すぐ使う
- 【JS・フロントエンド】ERR_UNSUPPORTED_TYPESCRIPT_SYNTAXの直し方 — 型ストリッピング非対応構文の移行ログ
- 【JS・フロントエンド】.eslintrcからv10のflat configへ移行したログ — 実際に壊れた4箇所
この記事を書いた人: Kurosaki.Ren。記事のコードは隔離した環境で実行してから掲載しています。詳しいプロフィールは著者プロフィールページへどうぞ。
【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう!!![]()

コメント