Open History to see the last commit
1---
2id: UseRateLimiter
3title: UseRateLimiter
4---
5
6Defined in: [packages/ember-pacer/src/rate-limiter/useRateLimiter.ts:89](https://github.com/TanStack/pacer/blob/main/packages/ember-pacer/src/rate-limiter/useRateLimiter.ts#L89)
7
8Creates and retains the RateLimiter for its Ember owner.
9
10Accepts at most a configured number of calls in a fixed or sliding window. Calls beyond the limit are rejected rather than queued. Use the state and timing methods to display capacity and retry timing.
11
12## State and subscriptions
13
14Pass a selector to track only the state consumed by the owner. The default selection is {},
15so utility state changes do not update the owner unless it opts in. Selection uses shallow
16comparison. The raw store remains available for additional subscriptions.
17The selector is the second positional argument. Read utility.state from the template.
18The contextual utility.Subscribe helper selects state for a child template.
19
20Available state fields:
21
22- `executionCount`: Number of function executions that have been completed
23- `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
24- `isExceeded`: Whether the rate limiter has exceeded the limit
25- `maybeExecuteCount`: Number of times maybeExecute has been called (for reduction calculations)
26- `rejectionCount`: Number of function executions that have been rejected due to rate limiting
27- `status`: Current execution status - 'disabled' when not active, 'executing' when executing, 'idle' when not executing, 'exceeded' when rate limit is exceeded
28
29## Options and ownership
30
31Tracked named arguments update options after rendering. createPacerScope supplies shared
32defaults through contextual helpers. Local named options override those defaults.
33The synchronous rate limiter has no pending timer to cancel during teardown.
34onUnmount replaces default cleanup and receives the same adapter instance. A custom callback
35must perform all required cleanup. Use flush() where supported to finish pending work.
36
37## Example
38
39```gts
40import { on } from '@ember/modifier'
41import { fn } from '@ember/helper'
42import { useRateLimiter } from '@tanstack/ember-pacer'
43import type { RateLimiterState } from '@tanstack/ember-pacer'
44
45const select = (state: RateLimiterState<(value: string) => void>) => ({ executionCount: state.executionCount })
46
47<template>
48 {{#let (useRateLimiter @process select limit=5 window=1000) as |utility|}}
49 <button {{on "click" (fn utility.maybeExecute "item")}}>Schedule</button>
50 <span>{{utility.state.executionCount}}</span>
51 {{/let}}
52</template>
53```
54
55## Extends
56
57- `default`\<\{
58 `Args`: \{
59 `Named`: [`EmberRateLimiterOptions`](../interfaces/EmberRateLimiterOptions.md)\<`TFn`, `TSelected`\>;
60 `Positional`: \[`TFn`\] \| \[`TFn`, (`state`) => `TSelected`\];
61 \};
62 `Return`: [`EmberRateLimiter`](../interfaces/EmberRateLimiter.md)\<`TFn`, `TSelected`\>;
63\}\>
64
65## Type Parameters
66
67### TFn
68
69`TFn` *extends* `AnyFunction`
70
71### TSelected
72
73`TSelected` = \{
74\}
75
76## Constructors
77
78### Constructor
79
80```ts
81new UseRateLimiter<TFn, TSelected>(owner?): UseRateLimiter;
82```
83
84Defined in: node\_modules/.pnpm/ember-source@7.3.0\_@glimmer+component@2.1.1\_supports-color@7.2.0\_\_supports-color@7.2.0/node\_modules/ember-source/types/stable/@ember/object/index.d.ts:28
85
86#### Parameters
87
88##### owner?
89
90`Owner`
91
92#### Returns
93
94`UseRateLimiter`
95
96#### Inherited from
97
98```ts
99Helper<{
100 Args: {
101 Positional:
102 [fn: TFn] | [fn: TFn, selector: (state: RateLimiterState) => TSelected]
103 Named: EmberRateLimiterOptions<TFn, TSelected>
104 }
105 Return: EmberRateLimiter<TFn, TSelected>
106}>.constructor
107```
108
109## Methods
110
111### compute()
112
113```ts
114compute(positional, options): EmberRateLimiter<TFn, TSelected>;
115```
116
117Defined in: [packages/ember-pacer/src/rate-limiter/useRateLimiter.ts:105](https://github.com/TanStack/pacer/blob/main/packages/ember-pacer/src/rate-limiter/useRateLimiter.ts#L105)
118
119Override this function when writing a class-based helper.
120
121#### Parameters
122
123##### positional
124
125\[`TFn`, (`state`) => `TSelected`\]
126
127The positional arguments to the helper
128
129##### options
130
131[`EmberRateLimiterOptions`](../interfaces/EmberRateLimiterOptions.md)\<`TFn`, `TSelected`\>
132
133#### Returns
134
135[`EmberRateLimiter`](../interfaces/EmberRateLimiter.md)\<`TFn`, `TSelected`\>
136
137#### Method
138
139compute
140
141#### Since
142
1431.13.0
144
145#### Overrides
146
147```ts
148Helper.compute
149```