跪拜 Guibai
← Back to the summary

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:

  1. shouldRetry excludes 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 keeping shouldRetry for customization (e.g., only retry timeouts, only retry specific error codes).
  2. maxDelay cap: 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:

  1. leading / trailing options: leading controls whether the first invocation executes immediately (e.g., scroll gives immediate feedback), trailing controls whether to execute once after the stream stops.
  2. cancel / flush: cancel cancels pending tasks (e.g., when a component unmounts); flush executes pending tasks immediately.
  3. Preserve this and arguments: Uses function + apply so that calls on object methods do not lose this.

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.

Welcome stars, issues, and contributions.

Comments

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.

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.