跪拜 Guibai
← All articles
Frontend

async-concurrency-kit: one zero-dep TypeScript library for debounce, throttle, concurrency limits, and retry with exponential backoff

By lcy_24 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Frontend teams that have been copying these utility functions into every project's utils folder now have a single, tested dependency that also doubles as a reference implementation for interview study. By handling edge cases like 4xx exclusions and timer cleanup, the library eliminates subtle bugs that hand-rolled versions often ignore.

Summary

Frontend interviews routinely ask for hand-written versions of debounce, throttle, concurrency limiting, and Promise retry, but production code also needs these utilities every day. The newly released async-concurrency-kit collects them into a single zero-dependency TypeScript package, covering six common scenarios: concurrent batch uploads, ordered concurrent mapping, exponential backoff retries, timeouts, debounced search, and throttled scroll handlers.

The library's implementation choices reflect practical production concerns. pLimit uses an active counter and a queue rather than relying on Promise.all, which would not impose a true limit. retry defaults to skipping 4xx client errors and applies an exponential backoff with a maxDelay cap to avoid request storms and exponential wait growth. debounce and throttle both support leading and trailing options, plus cancel and flush methods, while preserving the caller's this context. timeout clears its timer on both success and failure and passes through the original rejection.

The author provides the full source on GitHub, an npm package, and an online demo, positioning it as a drop-in solution that also demonstrates the principles interviewers expect candidates to explain.

Takeaways
— async-concurrency-kit is a zero-dependency TypeScript library, installable via npm as async-concurrency-kit.
— pLimit enforces a concurrency cap using an active counter and a queue, not Promise.all, so queued tasks do not start until capacity frees up.
— pMap preserves input order by wrapping Promise.all with pLimit; Promise.all's order guarantee makes this clean.
— retry uses exponential backoff (delay * backoff each attempt) and caps the wait with maxDelay to prevent exponential explosion.
— The default shouldRetry excludes 4xx status codes, retrying only network errors, 5xx, and status-less exceptions.
— debounce and throttle support leading and trailing execution modes, plus cancel and flush methods, and preserve this context.
— timeout clears its timer on both fulfillment and rejection and passes the original error through without swallowing it.
— The library includes source code, an npm package, and an online demo at lcy-24.github.io/async-concurrency-kit/.
Conclusions

The default retry policy of excluding 4xx is a pragmatic decision: client errors cannot be fixed by retrying, so this avoids wasting network calls on failures like 400 or 403.

The debounce implementation goes beyond interview-level answers by adding leading/trailing options and cancel/flush, which are the parts that actually matter in real component lifecycles.

Using an active counter instead of Promise.all for concurrency limiting is the key distinction: Promise.all would start all tasks immediately, so the queue and shift pattern is what enforce the actual upper bound.

Exposing the library with both source and an online demo makes it a learning tool as much as a dependency; you can read the full implementation before installing it.

Concepts & terms
exponential backoff
A retry strategy where the wait time between attempts increases by a fixed multiplier (e.g., doubling) each time, giving servers time to recover while avoiding request storms. A maxDelay cap prevents the wait from growing without bound.
debounce vs throttle
Debounce waits until input stops for a given interval before executing, whereas throttle guarantees execution at most once per fixed interval. Debounce is useful for search inputs; throttle is used for scroll or resize event handlers.
concurrency limit
A mechanism to bound the number of simultaneously running asynchronous operations, often implemented with a counter and a queue. Tasks exceeding the limit wait until a previous task completes and releases a slot.
From the discussion
Featured comments
组合搭配函数

The point that shouldRetry only retries on 5xx is well thought out; retrying 100 times on a 4xx is useless. Without the maxDelay cap detail spelled out, newcomers can easily blow up the wait time.

lcy_24

Thanks, these two points were indeed pitfalls I specifically handled after stepping on them. I made shouldRetry the default policy—by default it excludes 4xx (client errors aren't worth retrying) and only retries network errors and 5xx, while keeping a callback for customization; maxDelay serves as a safety net for exponential backoff, otherwise the wait time explodes exponentially with more retries. The latest version has implemented this default behavior; check the source if interested.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗