tanstack-pacer

Overview

TanStack Pacer provides a unified, type-safe toolkit for controlling function execution timing. It offers class-based APIs, factory functions, and React hooks for debouncing, throttling, rate limiting, queuing, and batching.

Core: @tanstack/pacer

React: @tanstack/react-pacer

Status: Beta

Installation

npm install @tanstack/pacer

npm install @tanstack/react-pacer  # React hooks

Debouncing

Delays execution until after a period of inactivity.

Class API

import { Debouncer } from '@tanstack/pacer'

const debouncer = new Debouncer(

  (query: string) => fetchSearchResults(query),

  {

    wait: 300,            // ms of inactivity before execution

    leading: false,       // Execute on leading edge (default: false)

    trailing: true,       // Execute on trailing edge (default: true)

    maxWait: 1000,        // Force execution after 1s of continuous calls

    enabled: true,

    onExecute: (result) => console.log(result),

  }

)

debouncer.maybeExecute('search term')

debouncer.cancel()

debouncer.getExecutionCount()

debouncer.setOptions({ wait: 500 }) // Dynamic reconfiguration

Factory Function

import { debounce } from '@tanstack/pacer'

const debouncedSearch = debounce(

  (query: string) => fetchResults(query),

  { wait: 300 }

)

debouncedSearch('term')

debouncedSearch.cancel()

React Hooks

import {

  useDebouncer,

  useDebouncedCallback,

  useDebouncedState,

  useDebouncedValue,

} from '@tanstack/react-pacer'

// Full debouncer instance

const debouncer = useDebouncer(fn, { wait: 300 })

// Simple debounced function

const debouncedFn = useDebouncedCallback(fn, { wait: 300 })

// Debounced state management

const [debouncedValue, setValue] = useDebouncedState(initialValue, { wait: 300 })

// Debounced reactive value

const debouncedValue = useDebouncedValue(reactiveValue, { wait: 300 })

Throttling

Limits execution to at most once per interval.

Class API

import { Throttler } from '@tanstack/pacer'

const throttler = new Throttler(

  (position: { x: number; y: number }) => updatePosition(position),

  {

    wait: 100,            // Minimum interval between executions

    leading: true,        // Execute immediately on first call (default: true)

    trailing: true,       // Execute after interval with last args (default: true)

    enabled: true,

    onExecute: (result) => console.log(result),

  }

)

throttler.maybeExecute({ x: 100, y: 200 })

throttler.cancel()

React Hooks

import {

  useThrottler,

  useThrottledCallback,

  useThrottledState,

  useThrottledValue,

} from '@tanstack/react-pacer'

const throttledFn = useThrottledCallback(handleScroll, { wait: 100 })

const [throttledPos, setPos] = useThrottledState({ x: 0, y: 0 }, { wait: 100 })

Rate Limiting

Controls execution with a maximum count within a time window.

Class API

import { RateLimiter } from '@tanstack/pacer'

const limiter = new RateLimiter(

  async (endpoint: string) => fetch(endpoint).then(r => r.json()),

  {

    limit: 10,            // Max executions per window

    window: 60000,        // Time window in ms (60s)

    enabled: true,

    onExecute: (result) => console.log(result),

    onReject: (...args) => console.warn('Rate limited:', args),

  }

)

limiter.maybeExecute('/api/data')  // Rejected if limit exceeded

limiter.getExecutionCount()

limiter.getRejectionCount()

React Hooks

import {

  useRateLimiter,

  useRateLimitedCallback,

  useRateLimitedState,

  useRateLimitedValue,

} from '@tanstack/react-pacer'

const rateLimitedFn = useRateLimitedCallback(apiCall, { limit: 5, window: 1000 })

Queuing

Sequential execution with configurable concurrency.

import { Queue } from '@tanstack/pacer'

const queue = new Queue({

  concurrency: 1,         // Max concurrent tasks

  started: true,          // Start processing immediately

})

queue.add(() => uploadFile(file1))

queue.add(() => uploadFile(file2))

queue.start()

queue.pause()

queue.clear()

queue.getSize()           // Pending count

queue.getPending()        // Currently executing count

Batching

Groups calls for combined processing.

import { Batcher } from '@tanstack/pacer'

const batcher = new Batcher(

  (items: LogEntry[]) => sendBatchToServer(items),

  {

    maxSize: 50,          // Auto-flush at 50 items

    wait: 1000,           // Auto-flush after 1s

  }

)

batcher.add(logEntry)    // Accumulates

batcher.flush()          // Manual flush

batcher.getSize()        // Current batch size

batcher.clear()          // Discard batch

Async Variants

import { AsyncDebouncer, asyncDebounce, AsyncThrottler, asyncThrottle } from '@tanstack/pacer'

const asyncDebouncer = new AsyncDebouncer(

  async (query: string) => {

    const response = await fetch(`/api/search?q=${query}`)

    return response.json()

  },

  { wait: 300 }

)

// React async hooks

import { useAsyncDebouncer, useAsyncThrottler } from '@tanstack/react-pacer'

Choosing the Right Utility

Scenario

Utility

Why

Search input

Debouncer

Wait for user to stop typing

Scroll events

Throttler

Periodic updates during activity

API protection

RateLimiter

Hard limit on call frequency

File uploads

Queue

Sequential processing

Analytics events

Batcher

Group for efficiency

Network requests

AsyncDebouncer

Handle abort/retry

Leading vs Trailing Edge

• Leading (leading: true): Execute immediately, suppress until wait expires. Good for button clicks.

• Trailing (trailing: true): Execute after activity stops. Good for search inputs.

• Both: Execute immediately AND after final wait. Good for scroll throttling.

Best Practices

• **Use maxWait with debouncing** to guarantee execution during continuous activity

• Use async variants for network requests (handle abort/cancellation)

• React hooks handle cleanup automatically - no manual teardown needed

• **Use setOptions** for dynamic reconfiguration (e.g., reducing wait for power users)

• Compose utilities for complex scenarios (rate-limited queue)

• **Use onReject** on RateLimiter to inform users when they're rate limited

Common Pitfalls

• Using debounce when you need throttle (debounce waits for inactivity, throttle guarantees periodic execution)

• Not using maxWait with debounce for long-running continuous events

• Creating new instances on every render (use hooks or module-level)

• Forgetting cleanup in non-React environments (call cancel())