async-concurrency-kit: one zero-dep TypeScript library for debounce, throttle, concurrency limits, and retry with exponential backoff
Debounce and throttle, concurrency control, exponential backoff retry. I collected them all into a library, async-concurrency-kit.
Author: lcy_24 Tags: Frontend
Frontend interviews almost always ask for hand-written implementations: debounce, throttle, concurrency limiting, Promise retry. At work these appear daily: batch uploads need concurrency control, flaky interfaces need retries, input search needs debouncing.
But these functions are scattered in each project's
utils/directory, and every new project means rewriting them from scratch. I collected them into a zero-dependency TS library async-concurrency-kit, and also wanted to discuss the implementation ideas behind each hand-written problem.
1. One library covers 6 high-frequency scenarios
import { pLimit, pMap, retry, timeout, debounce, throttle } from 'async-concurrency-kit'
// 1. Concurrency control: batch upload, max 3 concurrent
const limit = pLimit(3)
await Promise.all(urls.map((url) => limit(() => upload(url))))
// 2. Concurrent map: 100 data items, max 5 concurrent, result order unchanged
const results = await pMap(items, (item) => process(item), 5)
// 3. Exponential backoff retry: max 3 times, each delay doubles
const data = await retry(() => fetchData(), { retries: 3, delay: 300, backoff: 2 })
// 4. Timeout: throw if no return in 3 seconds
const res = await timeout(fetch('/api'), 3000)
// 5. Debounce: request only after input stops for 300ms
const onSearch = debounce((kw) => search(kw), 300)
// 6. Throttle: scroll triggers at most once every 100ms
const onScroll = throttle(() => handleScroll(), 100)
2. pLimit: classic implementation of concurrency control
The core of concurrency limiting is "counter + queue": tasks exceeding the limit wait in a queue, and when a previous task completes, one is released.
export function pLimit(concurrency: number): LimitFn {
let active = 0
const queue: (() => void)[] = []
const next = () => {
active--
queue.shift()?.()
}
const run = async <T>(fn: () => Promise<T>): Promise<T> => {
active++
try {
return await fn()
} finally {
next()
}
}
return <T>(fn: () => Promise<T>): Promise<T> => {
if (active < concurrency) {
return run(fn)
}
return new Promise((resolve, reject) => {
queue.push(() => run(fn).then(resolve, reject))
})
}
}
Key point: use an active counter instead of Promise.all. When tasks are queued, fn cannot be called directly, otherwise the "rate limiting" is lost. Tasks start executing only when they are shifted out.
pMap on this basis guarantees that the result order matches the input order, not by which finishes first but by the original array index:
export function pMap<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency: number): Promise<R[]> {
const limit = pLimit(concurrency)
return Promise.all(items.map((item, i) => limit(() => mapper(item, i))))
}
Promise.all already preserves order, so pMap only needs to wrap limit around Promise.all, clean and simple.
3. retry: exponential backoff is not "fixed interval"
Many people implement retry as "sleep for 1 second after a failure, then try again". A better approach is exponential backoff: first wait 300ms, second wait 600ms, third wait 1200ms, etc., to avoid a request storm and give the server time to recover.
export async function retry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {
const {
retries = 3, delay = 300, backoff = 2, maxDelay = Infinity,
shouldRetry = defaultShouldRetry, // default excludes 4xx
onRetry,
} = options
let attempt = 0
let wait = delay
while (true) {
try {
return await fn()
} catch (err) {
attempt++
if (attempt > retries || !shouldRetry(err)) throw err
onRetry?.(err, attempt)
await sleep(wait)
wait = Math.min(wait * backoff, maxDelay) // backoff capped, avoid infinite growth
}
}
}
// Default strategy: do not retry 4xx (client errors), only network errors / 5xx / normal exceptions
function defaultShouldRetry(error: unknown): boolean {
const status = getErrorStatus(error) // compatible with axios's response.status and fetch's status
if (status === undefined) return true // no status (network error / normal exception) -> retry
return status < 400 || status >= 500 // exclude 4xx
}
Two easily overlooked points:
shouldRetryexcludes 4xx by default: Not all errors should be retried. 4xx are client errors (bad parameters, no permission, insufficient balance); retrying a hundred times is useless. Only network flakiness and 5xx deserve retry. So the library's default policy is "exclude 4xx", while keepingshouldRetryfor customization (e.g., only retry timeouts, only retry specific error codes).maxDelaycap: Without a cap, exponential backoff can cause the wait time to explode exponentially when there are many retries.Math.min(wait * backoff, maxDelay)provides a ceiling.
4. debounce / throttle: unavoidable classic hand-written problems
The difference between debounce and throttle in one sentence: debounce executes after triggering stops; throttle executes at most once per fixed interval.
export function debounce<T extends (...args: any[]) => void>(fn: T, wait: number, options: DebounceOptions = {}): DebouncedFunction<T> {
const { leading = false, trailing = true } = options
let timer: ReturnType<typeof setTimeout> | null = null
let lastArgs: Parameters<T> | null = null
const debounced = function (this: any, ...args: Parameters<T>) {
lastArgs = args
if (leading && !timer) fn.apply(this, args) // execute immediately on first call
if (timer) clearTimeout(timer)
timer = setTimeout(() => {
if (trailing && lastArgs) fn.apply(this, lastArgs)
timer = null
lastArgs = null
}, wait)
}
debounced.cancel = () => { if (timer) clearTimeout(timer); timer = null }
debounced.flush = () => { if (timer) { clearTimeout(timer); timer = null; if (lastArgs) fn.apply(undefined, lastArgs) } }
return debounced
}
Here, several enhancements go beyond "interview-level" completeness:
leading/trailingoptions:leadingcontrols whether the first invocation executes immediately (e.g., scroll gives immediate feedback),trailingcontrols whether to execute once after the stream stops.cancel/flush:cancelcancels pending tasks (e.g., when a component unmounts);flushexecutes pending tasks immediately.- Preserve
thisand arguments: Usesfunction+applyso that calls on object methods do not losethis.
throttle is similar, using a timestamp to record the last execution time and leading to decide whether the first call executes immediately:
export function throttle<T extends (...args: any[]) => void>(fn: T, wait: number, options: ThrottleOptions = {}): ThrottledFunction<T> {
const { leading = true, trailing = true } = options
let last = 0
let timer: ReturnType<typeof setTimeout> | null = null
const throttled = function (this: any, ...args: Parameters<T>) {
const now = Date.now()
const remaining = wait - (now - last)
if (remaining <= 0) {
if (timer) { clearTimeout(timer); timer = null }
last = now
fn.apply(this, args)
} else if (trailing && !timer) {
timer = setTimeout(() => { last = Date.now(); timer = null; fn.apply(this, args) }, remaining)
}
}
// ... cancel / flush omitted
return throttled
}
5. timeout: add an insurance policy to any Promise
export function timeout<T>(promise: Promise<T>, ms: number, message = 'Timeout'): Promise<T> {
return new Promise((resolve, reject) => {
const timer = setTimeout(() => reject(new Error(message)), ms)
promise.then(
(v) => { clearTimeout(timer); resolve(v) },
(e) => { clearTimeout(timer); reject(e) }
)
})
}
Two points to note: both success and failure must call clearTimeout (otherwise the timer lingers and never releases); the original Promise's rejection must be passed through as-is, not swallowed.
Afterword
Each of these functions is trivial alone, but the hard part is making them a library that is type-safe, edge-case-complete, and ready to use out of the box. Being able to explain the principles in an interview and then directly npm install them at work: this library covers both.
- Source: https://github.com/lcy-24/async-concurrency-kit
- npm:
npm install async-concurrency-kit - Online demo: https://lcy-24.github.io/async-concurrency-kit/
Welcome stars, issues, and contributions.
Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.
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.
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.