Ember 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.

import { RateLimiter } from '@tanstack/ember-pacer'

const limiter = new RateLimiter(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 ===]

import { RateLimiter } from '@tanstack/ember-pacer'

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

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

Choose an API

useRateLimitedState or useRateLimitedValue for Ember state
useRateLimiter 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.

Ember example

Invoke the helper in a template. Named arguments supply options, and the second positional argument selects state. Removing the helper invocation runs cleanup. The example imports application operations from ./api.

plaintext

import Component from '@glimmer/component'
import { on } from '@ember/modifier'
import { fn } from '@ember/helper'
import { useRateLimiter } from '@tanstack/ember-pacer'
import type { RateLimiterState } from '@tanstack/ember-pacer'
import { sendEvent } from './api'

const select = (state: RateLimiterState) => ({
  rejectionCount: state.rejectionCount,
  executionCount: state.executionCount,
})

export default class Example extends Component {
  <template>
    {{#let (useRateLimiter sendEvent select limit=3 window=10000) as |limiter|}}
      <button {{on 'click' (fn limiter.maybeExecute 'clicked')}}>Send</button>
      <output>{{limiter.state.rejectionCount}}</output>
    {{/let}}
  </template>
}

The focused TypeScript snippets below demonstrate the core RateLimiter class re-exported by the adapter. In a component, use useRateLimiter as above to own the instance, pass configuration as named arguments, and pass the yielded instance to event handlers. Core class instances require explicit cleanup.

Rate-limited callback

Use the yielded utility's maybeExecute method when an event should invoke a rate-limited side effect:

plaintext

import { on } from '@ember/modifier'
import { fn } from '@ember/helper'
import { useRateLimiter } from '@tanstack/ember-pacer'

// In a component template; this.search accepts a query string:
<template>
  {{#let (useRateLimiter this.search limit=3 window=1000) as |search|}}
    <button {{on 'click' (fn search.maybeExecute @query)}}>Search</button>
  {{/let}}
</template>

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

Rate-limited state and values

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

plaintext

import { useRateLimitedValue } from '@tanstack/ember-pacer'

<template>
  {{#let (useRateLimitedValue @query limit=3 window=1000) as |delayed|}}
    <SearchResults @query={{delayed.value}} />
  {{/let}}
</template>

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.

import { RateLimiter } from '@tanstack/ember-pacer'

const limiter = new RateLimiter(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:

import { RateLimiter } from '@tanstack/ember-pacer'

const limiter = new RateLimiter(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.

import { RateLimiter } from '@tanstack/ember-pacer'

const limiter = new RateLimiter(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)
  },
})

Ember 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. Use the helper's second positional argument to select fields, as shown above. Read those fields from the yielded instance's .state in the template.

plaintext

import Component from '@glimmer/component'
import { on } from '@ember/modifier'
import { fn } from '@ember/helper'
import { useRateLimiter } from '@tanstack/ember-pacer'
import type { RateLimiterState } from '@tanstack/ember-pacer'
import { sendEvent } from './api'

const select = (state: RateLimiterState) => ({
  rejectionCount: state.rejectionCount,
  executionCount: state.executionCount,
})

export default class Example extends Component {
  <template>
    {{#let (useRateLimiter sendEvent select limit=3 window=10000) as |limiter|}}
      <button {{on 'click' (fn limiter.maybeExecute 'clicked')}}>Send</button>
      <output>{{limiter.state.rejectionCount}}</output>
    {{/let}}
  </template>
}

The contextual utility.Subscribe helper selects state for a child template without subscribing the utility owner.

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: