Open History to see the last commit
1---
2id: queue
3title: queue
4---
5
6```ts
7function queue<TValue>(fn, initialOptions): (item, position, runOnItemsChange) => boolean;
8```
9
10Defined in: [queuer.ts:745](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/queuer.ts#L745)
11
12Creates a queue that processes items immediately upon addition.
13Items are processed sequentially in FIFO order by default.
14
15This synchronous version is lighter weight and often all you need - upgrade to asyncQueue when you need promises, retry support, abort capabilities, concurrent execution, or advanced error handling.
16
17State Management:
18- Uses TanStack Store for reactive state management
19- Use `initialState` to provide initial state values when creating the queuer
20- Use `onExecute` callback to react to item execution and implement custom logic
21- Use `onItemsChange` callback to react to items being added or removed from the queue
22- Use `onExpire` callback to react to items expiring and implement custom logic
23- Use `onReject` callback to react to items being rejected when the queue is full
24- The state includes execution count, expiration count, rejection count, and isRunning status
25- State can be accessed via the underlying Queuer instance's `store.state` property
26- When using framework adapters (React/Solid), state is accessed from the hook's state property
27
28Example usage:
29```ts
30// Basic sequential processing
31const processItems = queue<number>((n) => console.log(n), {
32 wait: 1000,
33 onItemsChange: (queuer) => console.log(queuer.peekAllItems())
34});
35processItems(1); // Logs: 1
36processItems(2); // Logs: 2 after 1 completes
37
38// Priority queue
39const processPriority = queue<number>((n) => console.log(n), {
40 getPriority: n => n // Higher numbers processed first
41});
42processPriority(1);
43processPriority(3); // Processed before 1
44```
45
46## Type Parameters
47
48### TValue
49
50`TValue`
51
52## Parameters
53
54### fn
55
56(`item`) => `void`
57
58### initialOptions
59
60[`QueuerOptions`](../interfaces/QueuerOptions.md)\<`TValue`\>
61
62## Returns
63
64```ts
65(
66 item,
67 position?,
68 runOnItemsChange?): boolean;
69```
70
71Adds an item to the queue. If the queue is full, the item is rejected and onReject is called.
72`undefined` cannot be queued (it is the internal "no item" sentinel) and is always rejected.
73Items can be inserted based on priority or at the front/back depending on configuration.
74
75Returns true if the item was added, false if the queue is full.
76
77Example usage:
78```ts
79queuer.addItem('task');
80queuer.addItem('task2', 'front');
81```
82
83### Parameters
84
85#### item
86
87`TValue`
88
89#### position?
90
91[`QueuePosition`](../type-aliases/QueuePosition.md) = `...`
92
93#### runOnItemsChange?
94
95`boolean` = `true`
96
97### Returns
98
99`boolean`