p-debounce

p-debounce is a tiny, zero-dependency utility by Sindre Sorhus that debounces promise-returning and async functions. Instead of firing on every call, it waits until a configurable idle interval has elapsed, then runs the function once and resolves every pending promise from that burst with the same value.

It adds promise-aware behavior that a plain debounce cannot offer, including a leading-edge before option, an after mode via pDebounce.promise that coalesces concurrent calls into a single in-flight execution, and support for cancellation through an AbortSignal.

What You Get

• A debounced wrapper that resolves all queued promises from a burst with a single result
• A before option to execute on the leading edge instead of the trailing edge
• pDebounce.promise to coalesce overlapping async calls into one in-flight execution
• AbortSignal support to cancel pending calls and reject their promises
• A zero-dependency ES module with full TypeScript type definitions

Common Use Cases

• Rate-limiting expensive API requests triggered by rapid user input
• Debouncing async search or autocomplete handlers so only the final query runs
• Coalescing many concurrent async calls into a single network round-trip
• Guarding costly async validation or save operations behind an idle delay

Under The Hood

Architecture - The entire library is a single index.js exporting one factory, pDebounce, plus a pDebounce.promise variant. The factory closes over a timeout handle and an array of pending {resolve, reject} handlers; each call clears and resets a setTimeout, and when it finally fires it awaits the wrapped function once and fans the result (or error) out to every queued handler before clearing state for the next cycle. The before option resolves the leading-edge value immediately, while pDebounce.promise instead tracks a single in-flight promise and an optional queued call.

Tech Stack - Pure modern JavaScript published as a native ES module (“type”: “module”), with zero runtime dependencies. It ships hand-written TypeScript declarations (index.d.ts) and type tests (index.test-d.ts), targeting current Node.js versions and any bundler-based frontend.

Code Quality - The codebase is small, uses AbortSignal.throwIfAborted for cancellation, and carefully manages handler arrays so calls arriving during execution are queued into the next cycle. It includes a behavioral test suite (test.js) and dedicated type-definition tests, and error paths reject the correct pending promises rather than swallowing failures.

API Design - The public surface is minimal and ergonomic: pDebounce(fn, wait, options?) returns a drop-in replacement for the original function, and options (before, signal) and the pDebounce.promise helper cover the advanced cases without extra ceremony. The README documents every option with runnable examples, so adoption requires almost no boilerplate.