>
);
}
render(() => , document.getElementById("app")!);
```
Creates a reactive FIFO queue. All accessor properties establish reactive dependencies when read inside a tracking scope (JSX, `createMemo`, `createEffect`, etc.).
Mutations (`add`, `remove`, `clear`) are batched by Solid's scheduler and applied on the next microtask. In tests, call `flush()` after mutations before reading reactive values.
```ts
import { createQueue } from "@solid-primitives/queue";
const { queue, first, last, size, isEmpty, add, remove, clear } = createQueue(["a", "b", "c"]);
// Read reactive state
size(); // 3
first(); // "a"
isEmpty(); // false
// Mutate
add("d", "e");
remove(); // "a" — returned synchronously
// In JSX — updates automatically
{item =>
{item}
}
Next: {first()}
Remaining: {size()}
```
### Type
```ts
type ReactiveQueue = {
readonly queue: Accessor;
readonly first: Accessor;
readonly last: Accessor;
readonly size: Accessor;
readonly isEmpty: Accessor;
add: (...items: T[]) => void;
push: (comparator: (a: T, b: T) => number, ...items: T[]) => void;
remove: () => T | undefined;
clear: () => void;
};
function createQueue(initialValues?: T[]): ReactiveQueue;
```
### Notes
- `remove()` returns the dequeued item **synchronously**, even though the reactive signal update is batched.
- Initial values are **copied** — the source array is never mutated.
- Calling `add` or `remove` inside a Solid reactive computation (memo, effect compute phase) will throw in development. Call mutations from event handlers or effect **apply** phases.
## `makePriorityQueue`
Modifies an existing queue in place so that every `add` call maintains comparator-sorted order. Returns the same queue object with its `add` method patched; `remove()` always returns the highest-priority item (smallest by the comparator).
```tsx repl
import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { makePriorityQueue, makeQueue } from "@solid-primitives/queue";
function Demo() {
const cmp = (a: number, b: number) => a - b;
const q = makePriorityQueue(makeQueue(), cmp);
// non-reactive queue — snapshot it into a signal after each mutation
const [state, setState] = createSignal("empty");
const update = () =>
setState(q.isEmpty ? "empty" : `min: ${q.first}, max: ${q.last}, size: ${q.size}`);
const addRandom = () => {
q.add(Math.floor(Math.random() * 100));
update();
};
const removeMin = () => {
q.remove();
update();
};
return (
<>
{state()}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
import { makeQueue, makePriorityQueue } from "@solid-primitives/queue";
const cmp = (a: number, b: number) => a - b;
const q = makePriorityQueue(makeQueue([3, 1, 2].sort(cmp)), cmp);
q.first; // 1
q.last; // 3
q.remove(); // 1
q.first; // 2
q.add(0);
q.first; // 0
```
### Type
```ts
function makePriorityQueue>(q: Q, comparator: (a: T, b: T) => number): Q;
```
## `createPriorityQueue`
Creates a reactive priority queue. All accessor properties establish reactive dependencies. Mutations are batched; call `flush()` in tests before reading reactive values.
```tsx repl
import { render } from "@solidjs/web";
import { createPriorityQueue } from "@solid-primitives/queue";
function Demo() {
const { queue, first, isEmpty, add, remove } = createPriorityQueue(
(a, b) => a - b,
[5, 2, 8],
);
return (
<>
queue: {queue().join(", ")}
next: {first() ?? "—"}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
import { createPriorityQueue } from "@solid-primitives/queue";
const { queue, first, size, add, remove } = createPriorityQueue(
(a, b) => a.priority - b.priority,
initialItems,
);
first(); // highest-priority item
add({ priority: 0, label: "urgent" });
// In JSX
{item => }
```
### Type
```ts
function createPriorityQueue(
comparator: (a: T, b: T) => number,
initialValues?: T[],
): ReactiveQueue;
```
### Notes
- `remove()` returns the dequeued item **synchronously**, even though the reactive signal update is batched.
- Initial values are **copied** — the source array is never mutated.
- `queue()` returns items in priority order (lowest comparator value first).
## `createTaskQueue`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createTaskQueue } from "@solid-primitives/queue";
function Demo() {
const { enqueue, size, active } = createTaskQueue();
const [done, setDone] = createSignal([]);
let id = 0;
const addTask = () => {
const label = `task-${++id}`;
enqueue(() => new Promise(r => setTimeout(() => r(label), 1000))).then(result =>
setDone(prev => [...prev, result]),
);
};
return (
<>
active: {String(active())} · waiting: {size()}
done: {done().join(", ")}
>
);
}
render(() => , document.getElementById("app")!);
```
Creates a reactive queue that runs async tasks one at a time in FIFO order.
Each task is a zero-argument function returning a plain value or a Promise. Tasks execute sequentially: the next task starts only after the current one resolves or rejects. `enqueue` returns a `Promise` that settles with the task's result.
`size` counts tasks **waiting** (not including the one currently executing).
`active` is `true` while any task is running.
```ts
import { createTaskQueue } from "@solid-primitives/queue";
const { enqueue, size, active } = createTaskQueue();
// Each call runs after the previous one finishes
const [alice, bob] = await Promise.all([
enqueue(() => fetchUser("alice")),
enqueue(() => fetchUser("bob")),
]);
// In JSX
Processing… ({size()} remaining)
```
### Type
```ts
type Task = () => Promise | T;
type ReactiveTaskQueue = {
/** Number of tasks waiting to start (excludes the task currently executing). */
readonly size: Accessor;
/** `true` while a task is executing. */
readonly active: Accessor;
/** Adds a task to the back of the queue; resolves/rejects with its result. */
enqueue: (task: Task) => Promise;
/**
* Removes all waiting tasks and rejects their Promises with `"Queue cleared"`.
* The currently-executing task (if any) runs to completion unaffected.
*/
clear: () => void;
};
function createTaskQueue(): ReactiveTaskQueue;
```
### Notes
- Tasks added while the queue is draining are picked up automatically — `enqueue` never restarts the drain.
- `clear()` does **not** cancel the active task; only unstarted tasks are rejected.
- All tasks share the same return type `T`. For heterogeneous task types use `createTaskQueue()`.
## `createConcurrentTaskQueue`
```tsx repl
import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createConcurrentTaskQueue } from "@solid-primitives/queue";
function Demo() {
const { enqueue, size, active } = createConcurrentTaskQueue(2);
const [done, setDone] = createSignal([]);
let id = 0;
const addBatch = () => {
for (let i = 0; i < 5; i++) {
const label = `task-${++id}`;
enqueue(() => new Promise(r => setTimeout(() => r(label), 1000))).then(result =>
setDone(prev => [...prev, result]),
);
}
};
return (
<>
active: {active()} · waiting: {size()}
done: {done().join(", ")}
>
);
}
render(() => , document.getElementById("app")!);
```
Creates a reactive task queue that runs up to `concurrency` tasks at a time. Tasks beyond the limit wait until a slot opens.
`size` counts tasks **waiting** (not including those executing).
`active` is the **number** of tasks currently executing (0 when idle).
```ts
import { createConcurrentTaskQueue } from "@solid-primitives/queue";
const { enqueue, active, size } = createConcurrentTaskQueue(3);
// Up to 3 fetches run at once; the rest wait
urls.forEach(url => enqueue(() => fetch(url)));
// In JSX
0}>
Fetching… ({active()} active, {size()} waiting)
```
### Type
```ts
type ReactiveConcurrentTaskQueue = {
/** Number of tasks waiting to start (excludes tasks currently executing). */
readonly size: Accessor;
/** Number of tasks currently executing (0 when idle). */
readonly active: Accessor;
enqueue: (task: Task) => Promise;
clear: () => void;
};
function createConcurrentTaskQueue(concurrency: number): ReactiveConcurrentTaskQueue;
```
### Notes
- `active` is a **count** (`Accessor`), unlike `createTaskQueue` where it is a boolean.
- `clear()` rejects all **waiting** tasks; tasks currently executing run to completion.
- For heterogeneous task types use `createConcurrentTaskQueue()`.
## Changelog
See [CHANGELOG.md](./CHANGELOG.md)