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

Queuer.md

442 lines9.0 KB

1---
2id: Queuer
3title: Queuer
4---
5​
6Defined in: [queuer.ts:269](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L269)
7​
8A flexible queue that processes items with configurable wait times, expiration, and priority.
9​
10This synchronous version is lighter weight and often all you need - upgrade to AsyncQueuer when you need promises, retry support, abort capabilities, concurrent execution, or advanced error handling.
11​
12Features:
13- Automatic or manual processing of items
14- FIFO (First In First Out), LIFO (Last In First Out), or double-ended queue behavior
15- Priority-based ordering when getPriority is provided
16- Item expiration and removal of stale items
17- Callbacks for queue state changes, execution, rejection, and expiration
18​
19Running behavior:
20- `start()`: Begins automatically processing items in the queue (defaults to isRunning)
21- `stop()`: Pauses processing but maintains queue state
22- `wait`: Configurable delay between processing items
23- `onItemsChange`/`onExecute`: Callbacks for monitoring queue state
24​
25Manual processing is also supported when automatic processing is disabled:
26- `execute()`: Processes the next item using the provided function
27- `getNextItem()`: Removes and returns the next item without processing
28​
29Queue behavior defaults to FIFO:
30- `addItem(item)`: Adds to the back of the queue
31- Items processed from the front of the queue
32​
33Priority queue:
34- Provide a `getPriority` function; higher values are processed first
35​
36Stack (LIFO):
37- `addItem(item, 'back')`: Adds to the back
38- `getNextItem('back')`: Removes from the back
39​
40Double-ended queue:
41- `addItem(item, position)`: Adds to specified position ('front'/'back')
42- `getNextItem(position)`: Removes from specified position
43​
44Item expiration:
45- `expirationDuration`: Maximum time items can stay in the queue
46- `getIsExpired`: Function to override default expiration
47- `onExpire`: Callback for expired items
48​
49State Management:
50- Uses TanStack Store for reactive state management
51- Use `initialState` to provide initial state values when creating the queuer
52- Use `onExecute` callback to react to item execution and implement custom logic
53- Use `onItemsChange` callback to react to items being added or removed from the queue
54- Use `onExpire` callback to react to items expiring and implement custom logic
55- Use `onReject` callback to react to items being rejected when the queue is full
56- The state includes execution count, expiration count, rejection count, and isRunning status
57- State can be accessed via `queuer.store.state` when using the class directly
58- When using framework adapters (React/Solid), state is accessed from `queuer.state`
59​
60Example usage:
61```ts
62// Auto-processing queue with wait time
63const autoQueue = new Queuer<number>((n) => console.log(n), {
64 started: true, // Begin processing immediately
65 wait: 1000, // Wait 1s between items
66 onExecute: (item, queuer) => console.log(`Processed ${item}`)
67});
68autoQueue.addItem(1); // Will process after 1s
69autoQueue.addItem(2); // Will process 1s after first item
70​
71// Manual processing queue
72const manualQueue = new Queuer<number>((n) => console.log(n), {
73 started: false
74});
75manualQueue.addItem(1); // [1]
76manualQueue.addItem(2); // [1, 2]
77manualQueue.execute(); // logs 1, queue is [2]
78manualQueue.getNextItem(); // returns 2, queue is empty
79```
80​
81## Type Parameters
82​
83### TValue
84​
85`TValue`
86​
87## Constructors
88​
89### Constructor
90​
91```ts
92new Queuer<TValue>(fn, initialOptions?): Queuer<TValue>;
93```
94​
95Defined in: [queuer.ts:277](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L277)
96​
97#### Parameters
98​
99##### fn
100​
101(`item`) => `void`
102​
103##### initialOptions?
104​
105[`QueuerOptions`](../interfaces/QueuerOptions.md)\<`TValue`\> = `{}`
106​
107#### Returns
108​
109`Queuer`\<`TValue`\>
110​
111## Properties
112​
113### fn
114​
115```ts
116fn: (item) => void;
117```
118​
119Defined in: [queuer.ts:278](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L278)
120​
121#### Parameters
122​
123##### item
124​
125`TValue`
126​
127#### Returns
128​
129`void`
130​
131***
132​
133### key
134​
135```ts
136key: string | undefined;
137```
138​
139Defined in: [queuer.ts:273](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L273)
140​
141***
142​
143### options
144​
145```ts
146options: QueuerOptions<TValue>;
147```
148​
149Defined in: [queuer.ts:274](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L274)
150​
151***
152​
153### store
154​
155```ts
156readonly store: Store<Readonly<QueuerState<TValue>>>;
157```
158​
159Defined in: [queuer.ts:270](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L270)
160​
161## Methods
162​
163### addItem()
164​
165```ts
166addItem(
167 item,
168 position?,
169 runOnItemsChange?): boolean;
170```
171​
172Defined in: [queuer.ts:404](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L404)
173​
174Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
175`undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
176Items can be inserted based on priority or at the front/back depending on configuration.
177​
178Returns true if the item was added, false if the queue is full.
179​
180Example usage:
181```ts
182queuer.addItem('task');
183queuer.addItem('task2', 'front');
184```
185​
186#### Parameters
187​
188##### item
189​
190`TValue`
191​
192##### position?
193​
194[`QueuePosition`](../type-aliases/QueuePosition.md) = `...`
195​
196##### runOnItemsChange?
197​
198`boolean` = `true`
199​
200#### Returns
201​
202`boolean`
203​
204***
205​
206### clear()
207​
208```ts
209clear(): void;
210```
211​
212Defined in: [queuer.ts:696](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L696)
213​
214Removes all pending items from the queue. Does not affect items being processed.
215​
216#### Returns
217​
218`void`
219​
220***
221​
222### execute()
223​
224```ts
225execute(position?): TValue | undefined;
226```
227​
228Defined in: [queuer.ts:550](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L550)
229​
230Removes and returns the next item from the queue and processes it using the provided function.
231​
232Example usage:
233```ts
234queuer.execute();
235// LIFO
236queuer.execute('back');
237```
238​
239#### Parameters
240​
241##### position?
242​
243[`QueuePosition`](../type-aliases/QueuePosition.md)
244​
245#### Returns
246​
247`TValue` \| `undefined`
248​
249***
250​
251### flush()
252​
253```ts
254flush(numberOfItems?, position?): void;
255```
256​
257Defined in: [queuer.ts:566](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L566)
258​
259Processes a specified number of items to execute immediately with no wait time
260If no numberOfItems is provided, all items will be processed
261​
262#### Parameters
263​
264##### numberOfItems?
265​
266`number` = `...`
267​
268##### position?
269​
270[`QueuePosition`](../type-aliases/QueuePosition.md)
271​
272#### Returns
273​
274`void`
275​
276***
277​
278### flushAsBatch()
279​
280```ts
281flushAsBatch(batchFunction): void;
282```
283​
284Defined in: [queuer.ts:581](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L581)
285​
286Processes all items in the queue as a batch using the provided function as an argument
287The queue is cleared after processing
288​
289#### Parameters
290​
291##### batchFunction
292​
293(`items`) => `void`
294​
295#### Returns
296​
297`void`
298​
299***
300​
301### getNextItem()
302​
303```ts
304getNextItem(position?): TValue | undefined;
305```
306​
307Defined in: [queuer.ts:498](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L498)
308​
309Removes and returns the next item from the queue without executing the function.
310Use for manual queue management. Normally, use execute() to process items.
311​
312Example usage:
313```ts
314// FIFO
315queuer.getNextItem();
316// LIFO
317queuer.getNextItem('back');
318```
319​
320#### Parameters
321​
322##### position?
323​
324[`QueuePosition`](../type-aliases/QueuePosition.md) = `...`
325​
326#### Returns
327​
328`TValue` \| `undefined`
329​
330***
331​
332### peekAllItems()
333​
334```ts
335peekAllItems(): TValue[];
336```
337​
338Defined in: [queuer.ts:664](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L664)
339​
340Returns a copy of all items in the queue.
341​
342#### Returns
343​
344`TValue`[]
345​
346***
347​
348### peekNextItem()
349​
350```ts
351peekNextItem(position?): TValue | undefined;
352```
353​
354Defined in: [queuer.ts:654](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L654)
355​
356Returns the next item in the queue without removing it.
357​
358Example usage:
359```ts
360queuer.peekNextItem(); // front
361queuer.peekNextItem('back'); // back
362```
363​
364#### Parameters
365​
366##### position?
367​
368[`QueuePosition`](../type-aliases/QueuePosition.md) = `'front'`
369​
370#### Returns
371​
372`TValue` \| `undefined`
373​
374***
375​
376### reset()
377​
378```ts
379reset(): void;
380```
381​
382Defined in: [queuer.ts:704](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L704)
383​
384Resets the queuer state to its default values
385​
386#### Returns
387​
388`void`
389​
390***
391​
392### setOptions()
393​
394```ts
395setOptions(newOptions): void;
396```
397​
398Defined in: [queuer.ts:319](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L319)
399​
400Updates the queuer options. New options are merged with existing options.
401​
402#### Parameters
403​
404##### newOptions
405​
406`Partial`\<[`QueuerOptions`](../interfaces/QueuerOptions.md)\<`TValue`\>\>
407​
408#### Returns
409​
410`void`
411​
412***
413​
414### start()
415​
416```ts
417start(): void;
418```
419​
420Defined in: [queuer.ts:671](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L671)
421​
422Starts processing items in the queue. If already isRunning, does nothing.
423​
424#### Returns
425​
426`void`
427​
428***
429​
430### stop()
431​
432```ts
433stop(): void;
434```
435​
436Defined in: [queuer.ts:681](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L681)
437​
438Stops processing items in the queue. Does not clear the queue.
439​
440#### Returns
441​
442`void`