use-stack

Create a typed reactive LIFO stack.


Package	`@vizejs/composable/use-stack`
Own the source	`vize lib pull composable:use-stack`
Runtime exports	`useStack`
Gzip budget	1536 B

Usage

import { useStack } from "@vizejs/composable/use-stack";

Runtime contract

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

API

`useStack`

Create a typed reactive LIFO stack. push and pop are O(1). A bounded stack either drops its bottom item or rejects new pushes when full. Reactivity is driven by a version counter, so items, size, isEmpty, and peek re-evaluate after every mutation. Purely synchronous state: safe during server rendering (no host globals, no timers) and nothing to dispose.

function useStack<Item>( initial: Iterable<Item> = [], options: UseStackOptions = {}, ): StackControls<Item>

const breadcrumbs = useStack<string>(["home"]);
breadcrumbs.push("settings");
breadcrumbs.pop(); // "settings"

Types

`UseStackOptions`

Options for useStack.

Member	Type	Description
`capacity`?	`number`	Maximum number of stacked items. A positive integer, or `Number.POSITIVE_INFINITY` for an unbounded stack.
`overflow`?	`StackOverflowPolicy`	Policy applied when an item is pushed at capacity: `"drop-oldest"` discards the bottom item to make room, `"reject"` refuses the new item.

`StackControls`

Reactive last-in, first-out stack returned by useStack.

Member	Type	Description
`items`	`ComputedRef<readonly Item[]>`	Snapshot of the stacked items, bottom first (the top is the last element).
`size`	`ComputedRef<number>`	Number of stacked items.
`isEmpty`	`ComputedRef<boolean>`	Whether the stack holds no items.
`peek`	`() => Item \| undefined`	Read the top without removing it. Reactive when read inside an effect.
`push`	`(...items: Item[]) => number`	Push items in argument order (the last argument ends on top), applying the overflow policy.
`pop`	`() => Item \| undefined`	Remove and return the top.
`clear`	`() => void`	Remove every item.