Skip to content
Source
Sign inSign up
TanStack/pacer
Open History to see the last commit

UseRateLimiter.md

149 lines4.3 KB

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```