TanStack Pacer

TanStack Pacer is a lightweight timing and scheduling library designed for managing the execution frequency and order of functions. It provides utilities for common scheduling patterns such as debouncing, throttling, rate limiting, queuing, and batching.

Key features include:

• Scheduling Utilities: Support for both synchronous and asynchronous versions of debounce, throttle, rate limiting, queuing, and batching.
• Advanced Control: Options for leading/trailing execution, concurrency limits, priority queues (FIFO, LIFO), and expiration durations.
• State Management: Built on top of TanStack Store for fine-grained reactivity, allowing for easy integration with existing state management libraries and persistence to local/session storage.
• Type Safety: Full TypeScript support with generics to ensure functions are called with correct arguments.
• Framework Support: Includes adapters for React, Solid, Preact, and Angular.
• Tree Shaking: Optimized for bundle size with support for deep imports to minimize impact when embedding in other libraries.

TanStack Pacer provides five primary utilities for controlling execution frequency and timing. Choosing the right one depends on your specific use case:

• useDebouncer: Delays execution until a specified period of inactivity has passed.
  • Best for: Search inputs (waits for the user to stop typing).
• useThrottler: Limits execution to once per specified time period, typically executing immediately and then blocking subsequent calls.
  • Best for: Scroll or resize events (provides immediate response with controlled frequency).
• useRateLimiter: Limits the maximum number of executions allowed within a specific time window.
  • Best for: API calls (prevents overwhelming external services).
• useQueuer: Processes items sequentially, often with optional delays between them.
  • Best for: Sequential operations (maintains order and prevents overlapping tasks).
• useBatcher: Collects multiple items and processes them together in groups (batches) based on a size limit or a time limit.
  • Best for: Bulk operations (efficiently processing multiple items at once).

Async queuing implements a 'task pool' or 'worker pool' pattern, allowing multiple asynchronous operations (like I/O or network requests) to be processed concurrently. This differs from standard queuing by enabling multiple items to be in an 'Active' state simultaneously while maintaining control over concurrency and timing.

Use Async Queuing when you need to:

• Process multiple asynchronous operations concurrently.
• Control the number of simultaneous operations.
• Handle Promise-based tasks with robust error handling.
• Maintain order while maximizing throughput.
• Process background tasks that can run in parallel.

Do NOT use Async Queuing if:

• You don't need concurrent processing (use Queuing instead).
• You don't need all queued executions to run (use Throttling instead).
• You want to group operations together (use Batching instead).

To optimize performance and prevent unnecessary re-renders, useDebouncedState requires an explicit selector to subscribe to debouncer state changes. Without a selector, the component only re-renders when the debounced value itself changes.

Use the selector to pick exactly which properties of the debouncer state should trigger a component update.

Common Selector Patterns

Track loading/pending state:

(state) => ({ isPending: state.isPending })

Track execution count:

(state) => ({ executionCount: state.executionCount })

Track debouncing status and leading edge capability:

(state) => ({
  status: state.status,
  canLeadingExecute: state.canLeadingExecute
})

// Example: Re-render only when status or leading edge capability changes
const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
  '',
  { wait: 500 },
  (state) => ({
    status: state.status,
    canLeadingExecute: state.canLeadingExecute
  })
);

By default, useAsyncRateLimiter does not trigger re-renders. You must opt-in to reactive state tracking to prevent unnecessary performance overhead. You can subscribe to state in two ways:

1. Using the selector parameter: Pass a selector function as the third argument to the hook. The component using the hook will only re-render when the selected slice of state changes. This is best for local component state (e.g., loading indicators or data display).
2. Using the Subscribe HOC: Use asyncRateLimiter.Subscribe to subscribe to state changes deep in your component tree. This avoids "prop drilling" the rate limiter instance and is ideal for child components.

Available State Properties

• errorCount: Number of executions resulting in errors.
• executionTimes: Array of timestamps of executions.
• isExecuting: Boolean indicating if the function is currently running.
• lastResult: The result of the most recent successful execution.
• rejectionCount: Number of executions rejected due to rate limiting.
• settleCount: Number of completed executions (success or error).
• successCount: Number of successful executions.

// 1. Hook-level subscription via selector
const asyncRateLimiter = useAsyncRateLimiter(
  async (id) => api.fetch(id),
  { limit: 5, window: 1000 },
  (state) => ({ isExecuting: state.isExecuting })
);

// 2. Deep subscription via Subscribe HOC
<asyncRateLimiter.Subscribe selector={(state) => ({ rejectionCount: state.rejectionCount })}>
  {({ rejectionCount }) => <div>Rejected: {rejectionCount}</div>}
</asyncRateLimiter.Subscribe>