use-queue

Create a typed reactive FIFO queue.


Package	`@vizejs/composable/use-queue`
Own the source	`vize lib pull composable:use-queue`
Runtime exports	`useQueue`
Gzip budget	1792 B

Usage

import { useQueue } from "@vizejs/composable/use-queue";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useQueue`	state	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`useQueue`

Create a typed reactive FIFO queue. Dequeueing is amortized O(1): the head advances through a backing buffer that is compacted only after enough slots have been consumed, so large queues never pay for Array.prototype.shift. Reactivity is driven by a single version counter; items, size, isEmpty, and peek all re-evaluate after each mutation. Purely synchronous state: safe during server rendering (no host globals, no timers) and nothing to dispose.

function useQueue<Item>( initial: Iterable<Item> = [], options: UseQueueOptions = {}, ): QueueControls<Item>

const jobs = useQueue<string>([], { capacity: 100, overflow: "reject" });
jobs.enqueue("a", "b");
jobs.dequeue(); // "a"

Types

`UseQueueOptions`

Options for useQueue.

Member	Type	Description
`capacity`?	`number`	Maximum number of queued items. A positive integer, or `Number.POSITIVE_INFINITY` for an unbounded queue.
`overflow`?	`QueueOverflowPolicy`	Policy applied when an item arrives at capacity: `"drop-oldest"` evicts the head to make room, `"reject"` refuses the new item.

`QueueControls`

Reactive first-in, first-out queue returned by useQueue.

Member	Type	Description
`items`	`ComputedRef<readonly Item[]>`	Snapshot of the queued items, head first. Recomputed after every change.
`size`	`ComputedRef<number>`	Number of queued items.
`isEmpty`	`ComputedRef<boolean>`	Whether the queue holds no items.
`peek`	`() => Item \| undefined`	Read the head without removing it. Reactive when read inside an effect.
`enqueue`	`(...items: Item[]) => number`	Append items at the tail in argument order, applying the overflow policy.
`dequeue`	`() => Item \| undefined`	Remove and return the head.
`drain`	`() => Item[]`	Remove and return every queued item, head first.
`clear`	`() => void`	Remove every item.