Lit Rate Limiting Guide

Rate limiting allows a configured number of executions within a time window. Calls run immediately while capacity remains. Once the limit is reached, later calls are rejected until capacity becomes available again.

TanStack Pacer provides an in-memory rate limiter intended primarily for client-side operations. It can run in server-side JavaScript, but it is not a distributed quota or enforcement system.

How rate limiting works

This example allows three executions per window:

plaintext

Rate Limiting (limit: 3 calls per window)
Timeline: [1 second per tick]
                                        Window 1                  | Window 2
Calls:        ⬇️     ⬇️     ⬇️     ⬇️     ⬇️                       ⬇️     ⬇️
Executed:     ✅     ✅     ✅     ❌     ❌                       ✅     ✅
             [=== 3 allowed ===][=== blocked until reset ===][=== new window ===]

Rate limiting permits bursts. It does not space accepted calls evenly.

When to use rate limiting

Choose rate limiting when:

A client operation should follow a fixed quota.
Calls may run immediately until the quota is exhausted.
Rejected calls may be discarded or handled separately.
You need to measure remaining capacity or time until capacity returns.

Choose another utility when:

Executions should be evenly spaced. Use throttling.
Only the final call matters. Use debouncing.
Every operation must eventually run. Use queuing.
Items should run together. Use batching.
You need Promise results, retries, or abort support. Use async rate limiting.

Window types

The windowType option controls when capacity returns.

Fixed window

A fixed window starts when its first execution is accepted. All accepted executions remain counted until that window ends. Capacity then resets together.

const limiter = createRateLimiter(this, sendEvent, {
  limit: 3,
  window: 1000,
  windowType: 'fixed',
})

Fixed windows can allow bursts near a boundary because a full quota becomes available when the window resets.

Sliding window

A sliding window tracks each accepted execution separately. Capacity returns one execution at a time as old timestamps leave the window.

plaintext

Sliding Window (limit: 3 calls per window)
Timeline: [1 second per tick]
Calls:        ⬇️     ⬇️     ⬇️     ⬇️           ⬇️
Executed:     ✅     ✅     ✅     ❌           ✅
             [=== full ===][oldest execution expires][=== one available ===]

const limiter = createRateLimiter(this, sendEvent, {
  limit: 3,
  window: 1000,
  windowType: 'sliding',
})

Use a sliding window when capacity should return gradually rather than all at once.

Choose an API

createRateLimitedState or createRateLimitedValue for Lit state
createRateLimiter for capacity helpers and selected state

Call maybeExecute() for quota-controlled operations. Use state or value helpers for UI updates, and the instance for capacity helpers and rejection state.

Lit example

Pass the owning Lit controller host as the first argument. Disconnecting the host runs cleanup; reconnecting restores its subscription. The example imports application operations from ./api.

import { LitElement, html } from 'lit'
import { createRateLimiter } from '@tanstack/lit-pacer'
import { sendEvent } from './api'

class Example extends LitElement {
  limiter = createRateLimiter(
    this,
    sendEvent,
    { limit: 3, window: 10_000 },
    (state) => ({
      rejectionCount: state.rejectionCount,
      executionCount: state.executionCount,
    }),
  )

  override render() {
    return html`
      <button @click=${() => void this.limiter.maybeExecute('clicked')}>
        Send
      </button>
      <output>${this.limiter.state.rejectionCount}</output>
    `
  }
}

customElements.define('pacer-example', Example)

The focused snippets below create utilities in a Lit component constructor, where this is the controller host. Call their control methods from event handlers.

Rate-limited callback

Use createRateLimiter(...).maybeExecute when an event should invoke a rate-limited side effect:

import { createRateLimiter } from '@tanstack/lit-pacer'

// Fields on a LitElement:
search = createRateLimiter(
  this,
  (query: string) => updateSearchResults(query),
  {
    limit: 3,
    window: 1000,
  },
).maybeExecute
onInput = (event: Event) => {
  this.search((event.target as HTMLInputElement).value)
}

The callback returns whether the call was accepted. It does not expose capacity helpers or reset(). Use createRateLimiter when the component needs that control.

Rate-limited state and values

Use createRateLimitedState when Pacer should own the rate-limited state, or createRateLimitedValue when a value already changes elsewhere:

import { createRateLimitedValue } from '@tanstack/lit-pacer'

// query is a reactive property on this LitElement.
delayed = createRateLimitedValue(this, () => this.query, {
  limit: 3,
  window: 1000,
})
// Read this.delayed[0]() in render().

Handling rejected calls

Rejected calls do not run later. Use the boolean return value or onReject to provide feedback, retry elsewhere, or place work into a queue.

const limiter = createRateLimiter(this, sendEvent, {
  limit: 2,
  window: 1000,
  onReject: (limiter) => {
    console.log('Rejected calls:', limiter.store.state.rejectionCount)
  },
})

If rejected operations must eventually run, a queuer is usually a better fit.

Inspecting capacity

The instance API provides two computed helpers:

limiter.getRemainingInWindow() // Accepted executions still available.
limiter.getMsUntilNextWindow() // Time until at least one execution is available.

Both helpers use the current limit, window, windowType, and execution history.

Resetting and configuring the limiter

reset() clears execution timestamps, counters, and cleanup timers. The next call starts with full capacity.

limiter.reset()

Use setOptions() to update the configuration:

limiter.setOptions({
  limit: 10,
  window: 30_000,
})

Changing options does not erase existing execution history. Call reset() when the new configuration should begin with a fresh window.

The enabled, limit, and window options may be functions that receive the limiter instance:

const limiter = createRateLimiter(this, sendEvent, {
  enabled: (limiter) => limiter.store.state.executionCount < 100,
  limit: (limiter) => (limiter.store.state.rejectionCount > 10 ? 2 : 5),
  window: 60_000,
})

Disabling the limiter prevents the wrapped function from executing. It does not delete existing execution history.

Observing executions

onExecute receives the executed arguments and limiter instance. onReject receives the limiter instance.

const limiter = createRateLimiter(this, sendEvent, {
  limit: 5,
  window: 1000,
  onExecute: (args, limiter) => {
    console.log('Sent:', args)
    console.log('Remaining:', limiter.getRemainingInWindow())
  },
  onReject: (limiter) => {
    console.log('Rejected:', limiter.store.state.rejectionCount)
  },
})

Lit lifecycle

The adapter has no default operation cleanup because a synchronous limiter has no pending or active work. Use onUnmount only when the component needs custom teardown related to the limiter.

Reactive state

The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility on its owning host and select the fields used by render(). Store changes request a host update:

const limiter = createRateLimiter(
  this,
  sendEvent,
  { limit: 5, window: 60_000 },
  (state) => ({
    isExceeded: state.isExceeded,
    rejectionCount: state.rejectionCount,
  }),
)

console.log(limiter.state.isExceeded, limiter.state.rejectionCount)

Use utility.subscribe(childHost, selector) for an independently subscribed child host. It returns a selected-state getter and cleans up when that child disconnects.

Option functions and lifecycle callbacks receive the underlying public utility instance. The .store.state reads inside those callbacks in the examples above are supported. Rendering code should read the selected adapter state shown here.

To restore selected state that your app has persisted, pass a partial snapshot through initialState. It is merged with the defaults. Restore only durable fields. Pending timers are not restored.

Commonly useful state includes: