@usefy/use-stack 0.19.0

package/README.md

@@ -0,0 +1,284 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-stack</h1>
+
+<p align="center">
+  <strong>A React hook for managing LIFO stack state with immutable updates</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-stack">
+    <img src="https://img.shields.io/npm/v/@usefy/use-stack.svg?style=flat-square&color=007acc" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@usefy/use-stack">
+    <img src="https://img.shields.io/npm/dm/@usefy/use-stack.svg?style=flat-square&color=007acc" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@usefy/use-stack">
+    <img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-stack?style=flat-square&color=007acc" alt="bundle size" />
+  </a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE">
+    <img src="https://img.shields.io/npm/l/@usefy/use-stack.svg?style=flat-square&color=007acc" alt="license" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-usestack--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`@usefy/use-stack` manages a **LIFO** (last-in, first-out) stack as React state with immutable, ergonomic updates. It is the LIFO sibling of [`@usefy/use-queue`](https://www.npmjs.com/package/@usefy/use-queue) — identical in shape and conventions, but `push` and `pop` operate on the **same** end (the top). Items are pushed onto the top and popped from the top. Every mutation produces a brand-new array (so React re-renders correctly and the previous state is never mutated), and the returned stack is typed as `readonly T[]` to steer you toward the provided actions.
+
+**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
+
+### Why use-stack?
+
+- **Zero Dependencies** — Pure React implementation
+- **TypeScript First** — Full `<T>` generics with exported types
+- **Immutable Updates** — New array on every change; `readonly T[]` return type prevents accidental in-place mutation
+- **True LIFO** — `push` and `pop` both operate on the top; `pop` **returns the popped item**
+- **Peek** — Read the top item without mutating; stable and always current
+- **Stable Actions** — Action identities never change, so they're safe as `useEffect` dependencies
+- **No Wasted Renders** — No-op updates (empty `push`, `pop`/`clear` on an empty stack) are skipped
+- **Lazy Initialization** — Accepts an array, an iterable, or a factory — just like `useState`
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-stack
+
+# yarn
+yarn add @usefy/use-stack
+
+# pnpm
+pnpm add @usefy/use-stack
+```
+
+### Peer Dependencies
+
+This package requires React 18 or 19:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useStack } from "@usefy/use-stack";
+
+interface Snapshot {
+  id: number;
+  label: string;
+}
+
+function Editor() {
+  const [history, { push, pop, peek }] = useStack<Snapshot>([]);
+
+  const undo = () => {
+    const last = pop(); // remove + read the most recent change in one call
+    if (last) restore(last);
+  };
+
+  return (
+    <div>
+      <button onClick={() => push({ id: Date.now(), label: "Edit" })}>
+        Record change
+      </button>
+      <button onClick={undo} disabled={history.length === 0}>
+        Undo {peek()?.label}
+      </button>
+      <p>History depth: {history.length}</p>
+    </div>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `useStack<T>(initialState?)`
+
+Returns a tuple of the current read-only stack and a stable actions object.
+
+#### Parameters
+
+| Parameter      | Type                   | Default | Description                                                                    |
+| -------------- | ---------------------- | ------- | ------------------------------------------------------------------------------ |
+| `initialState` | `StackInitializer<T>`  | empty   | An array, an iterable of values, or a factory returning one (evaluated once). The last element becomes the top. |
+
+#### Returns `[stack, actions]`
+
+| Item      | Type                  | Description                                                            |
+| --------- | --------------------- | --------------------------------------------------------------------- |
+| `stack`   | `readonly T[]`        | Current stack. The **last** item is the top; `stack[0]` is the bottom |
+| `actions` | `UseStackActions<T>`  | Stable action handlers (see below)                                    |
+
+#### Actions
+
+| Action  | Signature                    | Description                                                                       |
+| ------- | ---------------------------- | --------------------------------------------------------------------------------- |
+| `push`  | `(...items: T[]) => void`    | Push one or more items onto the top (the last argument ends up on top). No items is a no-op |
+| `pop`   | `() => T \| undefined`       | Remove the top item and return it. Returns `undefined` (no-op) when empty         |
+| `peek`  | `() => T \| undefined`       | Read the top item without mutating (stable, always reflects latest state)         |
+| `clear` | `() => void`                 | Remove all items. Clearing an empty stack is a no-op                              |
+| `reset` | `() => void`                 | Restore the initial values (a fresh copy)                                         |
+
+#### Reading `top` / `bottom` / `size`
+
+The returned stack is a read-only array, so these derive directly from it — no extra state needed:
+
+```tsx
+const [stack] = useStack<number>([1, 2, 3]);
+
+const top = stack[stack.length - 1];       // 3  (next to pop)
+const bottom = stack[0];                    // 1  (oldest item)
+const size = stack.length;                  // 3
+```
+
+> The returned `stack` is a `readonly T[]`, so calling `stack.push(...)` directly is a TypeScript error. Use the actions — mutating the array in place would bypass React state and break re-renders.
+
+---
+
+## Examples
+
+### Undo history
+
+```tsx
+import { useStack } from "@usefy/use-stack";
+
+function Editor() {
+  const [history, { push, pop }] = useStack<Snapshot>([]);
+
+  const record = (snapshot: Snapshot) => push(snapshot);
+
+  const undo = () => {
+    const last = pop();
+    if (last) restore(last);
+  };
+
+  return (
+    <div>
+      <button onClick={() => record(snapshot())}>Record</button>
+      <button onClick={undo} disabled={history.length === 0}>
+        Undo ({history.length})
+      </button>
+    </div>
+  );
+}
+```
+
+### Push, pop from the top (LIFO)
+
+```tsx
+const [stack, { push, pop, reset }] = useStack<number>([1, 2]);
+
+push(3, 4);  // stack: [1, 2, 3, 4]  (4 is the top)
+pop();       // returns 4, stack: [1, 2, 3]
+pop();       // returns 3, stack: [1, 2]
+reset();     // back to [1, 2]
+```
+
+### Peek before popping
+
+```tsx
+const [stack, { peek, pop }] = useStack<Frame>([]);
+
+// Decide based on the top without removing it
+if (peek()?.type === "modal") {
+  const frame = pop();
+  close(frame!);
+}
+```
+
+### Stable actions as effect dependencies
+
+```tsx
+const [stack, actions] = useStack<Route>();
+
+useEffect(() => {
+  const unsub = router.onNavigate((route) => actions.push(route));
+  return unsub;
+}, [actions]); // actions never changes identity — effect runs once
+```
+
+---
+
+## TypeScript
+
+```tsx
+import {
+  useStack,
+  type StackInitializer,
+  type UseStackActions,
+  type UseStackReturn,
+} from "@usefy/use-stack";
+
+const [stack, actions]: UseStackReturn<number> = useStack<number>([1, 2, 3]);
+```
+
+---
+
+## Behavior Notes
+
+- **LIFO** — `push` appends to the top; `pop` and `peek` operate on the same end (the last element, `stack[stack.length - 1]`).
+- **`pop` returns the item** — It removes and returns the top element in one call, or `undefined` when the stack is empty.
+- **Batched `pop` caveat** — The value `pop` returns is the top at call time. If you call `pop` multiple times synchronously (before React re-renders), each call returns the same top snapshot, though the settled state shrinks correctly by that many items. Read the returned `stack` array after the render for the final state.
+- **Immutable** — Actions never mutate the current array; they replace it with a new one. Any snapshot you captured stays valid.
+- **Referentially stable actions** — The actions object and each function keep the same identity for the lifetime of the component.
+- **Initial value is copied** — The array/iterable you pass in is never mutated, and `reset` always yields a fresh copy of it.
+- **No-op skipping** — Updates that wouldn't change anything don't create a new array or trigger a re-render.
+
+---
+
+## Testing
+
+This package maintains comprehensive test coverage to ensure reliability and stability.
+
+### Test Coverage
+
+📊 <a href="https://mirunamu00.github.io/usefy/coverage/use-stack/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages)
+
+### Test Files
+
+- `useStack.test.ts` — 25 tests for hook behavior, LIFO semantics, and immutability
+
+**Total: 25 tests**
+
+---
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.
+
+---
+
+<p align="center">
+  <sub>Built with care by the usefy team</sub>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+/**
+ * Accepted initial value for {@link useStack}.
+ *
+ * Mirrors `useState`'s lazy-initializer support: pass an array, any iterable of
+ * values, or a function returning one of those (evaluated once on mount). The
+ * **last** element becomes the top of the stack (the next item to be popped).
+ *
+ * @template T - Element type.
+ *
+ * @example
+ * ```ts
+ * useStack<string>();                  // empty
+ * useStack<string>(["a", "b"]);        // "b" is the top
+ * useStack(new Set(["a", "b"]));       // any iterable works
+ * useStack(() => expensiveInit());     // lazy
+ * ```
+ */
+type StackInitializer<T> = Iterable<T> | (() => Iterable<T>);
+/**
+ * Stable action handlers returned by {@link useStack}. Every function keeps a
+ * stable identity across renders, so the actions object is safe to use as a
+ * `useEffect`/`useMemo` dependency.
+ *
+ * @template T - Element type.
+ */
+interface UseStackActions<T> {
+    /**
+     * Push one or more items onto the top of the stack. Items are pushed in
+     * argument order, so the **last** argument ends up on top. Calling with no
+     * arguments is a no-op and does not trigger a re-render.
+     */
+    push: (...items: T[]) => void;
+    /**
+     * Pop the top item: remove it from the stack and return it. Returns
+     * `undefined` when the stack is empty (in which case it is a no-op and does
+     * not trigger a re-render).
+     *
+     * The returned value reflects the top of the stack at call time. When `pop`
+     * is called multiple times synchronously within the same event (before React
+     * re-renders), each call returns the same top snapshot even though the
+     * underlying state correctly shrinks — read the returned `stack` array after
+     * the render for the settled state.
+     */
+    pop: () => T | undefined;
+    /**
+     * Peek at the top item (the next item that `pop` would return) without
+     * mutating the stack. Returns `undefined` when the stack is empty. Stable
+     * across renders and always reflects the latest state.
+     */
+    peek: () => T | undefined;
+    /**
+     * Remove every item. Clearing an already-empty stack is a no-op.
+     */
+    clear: () => void;
+    /**
+     * Reset the stack back to the initial value provided at mount (a fresh copy,
+     * so later mutations never affect the stored initial).
+     */
+    reset: () => void;
+}
+/**
+ * Return type of {@link useStack}: a tuple of the current (read-only) stack and
+ * the stable action handlers.
+ *
+ * The stack is typed as `readonly T[]` on purpose — mutating it directly (e.g.
+ * `stack.push(...)`) would bypass React state and break immutability, so the
+ * type steers callers to the actions instead. Read access works as usual:
+ * `stack[stack.length - 1]` is the top, `stack[0]` is the bottom, and
+ * `stack.length` is the size.
+ *
+ * @template T - Element type.
+ */
+type UseStackReturn<T> = [readonly T[], UseStackActions<T>];
+
+/**
+ * A React hook for managing a LIFO (last-in, first-out) stack as React state
+ * with immutable, ergonomic updates.
+ *
+ * The LIFO sibling of {@link https://npmjs.com/package/@usefy/use-queue | useQueue}
+ * — identical in shape and conventions, but pushes and pops from the same end.
+ *
+ * Returns a tuple of the current (read-only) stack and a stable set of actions.
+ * The **top** of the stack is the last element (`stack[stack.length - 1]`, the
+ * next item to be popped) and new items are pushed onto the end. Every mutation
+ * produces a brand-new array so React re-renders correctly and the previous
+ * state is never mutated in place. Updates that would not change anything
+ * (pushing nothing, popping from or clearing an empty stack) are skipped to
+ * avoid needless re-renders.
+ *
+ * Features:
+ * - Immutable updates (new array on every change) with a `readonly T[]` return type
+ * - LIFO semantics: `push` and `pop` both operate on the top (the array's end)
+ * - `pop` returns the popped item (or `undefined` when empty)
+ * - `peek` reads the top item without mutating; stable and always current
+ * - Stable action identities — safe to use as effect dependencies
+ * - `useState`-style lazy initialization; accepts an array, iterable, or factory
+ * - Full TypeScript generics for the element type
+ *
+ * Reading `top` / `bottom` / `size` is done directly on the returned stack:
+ * `stack[stack.length - 1]`, `stack[0]`, and `stack.length` respectively.
+ *
+ * @template T - Element type.
+ * @param initialState - Initial items, or a factory returning them. Defaults to empty.
+ * @returns `[stack, { push, pop, peek, clear, reset }]`
+ *
+ * @example
+ * ```tsx
+ * // An undo / navigation history stack
+ * interface Snapshot { id: number; label: string }
+ *
+ * function Editor() {
+ *   const [history, { push, pop, peek }] = useStack<Snapshot>([]);
+ *
+ *   const undo = () => {
+ *     const last = pop(); // remove + read the most recent change in one call
+ *     if (last) restore(last);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => push({ id: Date.now(), label: "Edit" })}>
+ *         Record change
+ *       </button>
+ *       <button onClick={undo} disabled={history.length === 0}>
+ *         Undo{peek() ? ` (${peek()!.label})` : ""}
+ *       </button>
+ *       <p>History depth: {history.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push, pop from the top (LIFO), reset
+ * const [s, { push, pop, reset }] = useStack<number>([1, 2]);
+ * push(3, 4);       // stack: [1, 2, 3, 4] (4 is the top)
+ * pop();            // returns 4, stack: [1, 2, 3]
+ * reset();          // back to [1, 2]
+ * ```
+ */
+declare function useStack<T>(initialState?: StackInitializer<T>): UseStackReturn<T>;
+
+export { type StackInitializer, type UseStackActions, type UseStackReturn, useStack };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Accepted initial value for {@link useStack}.
+ *
+ * Mirrors `useState`'s lazy-initializer support: pass an array, any iterable of
+ * values, or a function returning one of those (evaluated once on mount). The
+ * **last** element becomes the top of the stack (the next item to be popped).
+ *
+ * @template T - Element type.
+ *
+ * @example
+ * ```ts
+ * useStack<string>();                  // empty
+ * useStack<string>(["a", "b"]);        // "b" is the top
+ * useStack(new Set(["a", "b"]));       // any iterable works
+ * useStack(() => expensiveInit());     // lazy
+ * ```
+ */
+type StackInitializer<T> = Iterable<T> | (() => Iterable<T>);
+/**
+ * Stable action handlers returned by {@link useStack}. Every function keeps a
+ * stable identity across renders, so the actions object is safe to use as a
+ * `useEffect`/`useMemo` dependency.
+ *
+ * @template T - Element type.
+ */
+interface UseStackActions<T> {
+    /**
+     * Push one or more items onto the top of the stack. Items are pushed in
+     * argument order, so the **last** argument ends up on top. Calling with no
+     * arguments is a no-op and does not trigger a re-render.
+     */
+    push: (...items: T[]) => void;
+    /**
+     * Pop the top item: remove it from the stack and return it. Returns
+     * `undefined` when the stack is empty (in which case it is a no-op and does
+     * not trigger a re-render).
+     *
+     * The returned value reflects the top of the stack at call time. When `pop`
+     * is called multiple times synchronously within the same event (before React
+     * re-renders), each call returns the same top snapshot even though the
+     * underlying state correctly shrinks — read the returned `stack` array after
+     * the render for the settled state.
+     */
+    pop: () => T | undefined;
+    /**
+     * Peek at the top item (the next item that `pop` would return) without
+     * mutating the stack. Returns `undefined` when the stack is empty. Stable
+     * across renders and always reflects the latest state.
+     */
+    peek: () => T | undefined;
+    /**
+     * Remove every item. Clearing an already-empty stack is a no-op.
+     */
+    clear: () => void;
+    /**
+     * Reset the stack back to the initial value provided at mount (a fresh copy,
+     * so later mutations never affect the stored initial).
+     */
+    reset: () => void;
+}
+/**
+ * Return type of {@link useStack}: a tuple of the current (read-only) stack and
+ * the stable action handlers.
+ *
+ * The stack is typed as `readonly T[]` on purpose — mutating it directly (e.g.
+ * `stack.push(...)`) would bypass React state and break immutability, so the
+ * type steers callers to the actions instead. Read access works as usual:
+ * `stack[stack.length - 1]` is the top, `stack[0]` is the bottom, and
+ * `stack.length` is the size.
+ *
+ * @template T - Element type.
+ */
+type UseStackReturn<T> = [readonly T[], UseStackActions<T>];
+
+/**
+ * A React hook for managing a LIFO (last-in, first-out) stack as React state
+ * with immutable, ergonomic updates.
+ *
+ * The LIFO sibling of {@link https://npmjs.com/package/@usefy/use-queue | useQueue}
+ * — identical in shape and conventions, but pushes and pops from the same end.
+ *
+ * Returns a tuple of the current (read-only) stack and a stable set of actions.
+ * The **top** of the stack is the last element (`stack[stack.length - 1]`, the
+ * next item to be popped) and new items are pushed onto the end. Every mutation
+ * produces a brand-new array so React re-renders correctly and the previous
+ * state is never mutated in place. Updates that would not change anything
+ * (pushing nothing, popping from or clearing an empty stack) are skipped to
+ * avoid needless re-renders.
+ *
+ * Features:
+ * - Immutable updates (new array on every change) with a `readonly T[]` return type
+ * - LIFO semantics: `push` and `pop` both operate on the top (the array's end)
+ * - `pop` returns the popped item (or `undefined` when empty)
+ * - `peek` reads the top item without mutating; stable and always current
+ * - Stable action identities — safe to use as effect dependencies
+ * - `useState`-style lazy initialization; accepts an array, iterable, or factory
+ * - Full TypeScript generics for the element type
+ *
+ * Reading `top` / `bottom` / `size` is done directly on the returned stack:
+ * `stack[stack.length - 1]`, `stack[0]`, and `stack.length` respectively.
+ *
+ * @template T - Element type.
+ * @param initialState - Initial items, or a factory returning them. Defaults to empty.
+ * @returns `[stack, { push, pop, peek, clear, reset }]`
+ *
+ * @example
+ * ```tsx
+ * // An undo / navigation history stack
+ * interface Snapshot { id: number; label: string }
+ *
+ * function Editor() {
+ *   const [history, { push, pop, peek }] = useStack<Snapshot>([]);
+ *
+ *   const undo = () => {
+ *     const last = pop(); // remove + read the most recent change in one call
+ *     if (last) restore(last);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => push({ id: Date.now(), label: "Edit" })}>
+ *         Record change
+ *       </button>
+ *       <button onClick={undo} disabled={history.length === 0}>
+ *         Undo{peek() ? ` (${peek()!.label})` : ""}
+ *       </button>
+ *       <p>History depth: {history.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push, pop from the top (LIFO), reset
+ * const [s, { push, pop, reset }] = useStack<number>([1, 2]);
+ * push(3, 4);       // stack: [1, 2, 3, 4] (4 is the top)
+ * pop();            // returns 4, stack: [1, 2, 3]
+ * reset();          // back to [1, 2]
+ * ```
+ */
+declare function useStack<T>(initialState?: StackInitializer<T>): UseStackReturn<T>;
+
+export { type StackInitializer, type UseStackActions, type UseStackReturn, useStack };

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useStack: () => useStack
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useStack.ts
+var import_react = require("react");
+function resolveInitial(initial) {
+  const value = typeof initial === "function" ? initial() : initial;
+  return value ? [...value] : [];
+}
+function useStack(initialState) {
+  const initialRef = (0, import_react.useRef)(null);
+  if (initialRef.current === null) {
+    initialRef.current = resolveInitial(initialState);
+  }
+  const [stack, setStack] = (0, import_react.useState)(() => [
+    ...initialRef.current
+  ]);
+  const stackStateRef = (0, import_react.useRef)(stack);
+  stackStateRef.current = stack;
+  const push = (0, import_react.useCallback)((...items) => {
+    setStack((prev) => items.length === 0 ? prev : [...prev, ...items]);
+  }, []);
+  const pop = (0, import_react.useCallback)(() => {
+    const top = stackStateRef.current[stackStateRef.current.length - 1];
+    setStack((prev) => prev.length === 0 ? prev : prev.slice(0, -1));
+    return top;
+  }, []);
+  const peek = (0, import_react.useCallback)(
+    () => stackStateRef.current[stackStateRef.current.length - 1],
+    []
+  );
+  const clear = (0, import_react.useCallback)(() => {
+    setStack((prev) => prev.length === 0 ? prev : []);
+  }, []);
+  const reset = (0, import_react.useCallback)(() => {
+    setStack([...initialRef.current]);
+  }, []);
+  const actions = (0, import_react.useMemo)(
+    () => ({ push, pop, peek, clear, reset }),
+    [push, pop, peek, clear, reset]
+  );
+  return [stack, actions];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useStack
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useStack.ts"],"sourcesContent":["export { useStack } from \"./useStack\";\nexport type {\n  StackInitializer,\n  UseStackActions,\n  UseStackReturn,\n} from \"./types\";\n","import { useCallback, useMemo, useRef, useState } from \"react\";\nimport type {\n  StackInitializer,\n  UseStackActions,\n  UseStackReturn,\n} from \"./types\";\n\n/**\n * Resolve a {@link StackInitializer} to a concrete array. A function\n * initializer is invoked once; any iterable is copied into a fresh array so the\n * caller's original object is never mutated.\n */\nfunction resolveInitial<T>(initial?: StackInitializer<T>): T[] {\n  const value = typeof initial === \"function\" ? initial() : initial;\n  return value ? [...value] : [];\n}\n\n/**\n * A React hook for managing a LIFO (last-in, first-out) stack as React state\n * with immutable, ergonomic updates.\n *\n * The LIFO sibling of {@link https://npmjs.com/package/@usefy/use-queue | useQueue}\n * — identical in shape and conventions, but pushes and pops from the same end.\n *\n * Returns a tuple of the current (read-only) stack and a stable set of actions.\n * The **top** of the stack is the last element (`stack[stack.length - 1]`, the\n * next item to be popped) and new items are pushed onto the end. Every mutation\n * produces a brand-new array so React re-renders correctly and the previous\n * state is never mutated in place. Updates that would not change anything\n * (pushing nothing, popping from or clearing an empty stack) are skipped to\n * avoid needless re-renders.\n *\n * Features:\n * - Immutable updates (new array on every change) with a `readonly T[]` return type\n * - LIFO semantics: `push` and `pop` both operate on the top (the array's end)\n * - `pop` returns the popped item (or `undefined` when empty)\n * - `peek` reads the top item without mutating; stable and always current\n * - Stable action identities — safe to use as effect dependencies\n * - `useState`-style lazy initialization; accepts an array, iterable, or factory\n * - Full TypeScript generics for the element type\n *\n * Reading `top` / `bottom` / `size` is done directly on the returned stack:\n * `stack[stack.length - 1]`, `stack[0]`, and `stack.length` respectively.\n *\n * @template T - Element type.\n * @param initialState - Initial items, or a factory returning them. Defaults to empty.\n * @returns `[stack, { push, pop, peek, clear, reset }]`\n *\n * @example\n * ```tsx\n * // An undo / navigation history stack\n * interface Snapshot { id: number; label: string }\n *\n * function Editor() {\n *   const [history, { push, pop, peek }] = useStack<Snapshot>([]);\n *\n *   const undo = () => {\n *     const last = pop(); // remove + read the most recent change in one call\n *     if (last) restore(last);\n *   };\n *\n *   return (\n *     <div>\n *       <button onClick={() => push({ id: Date.now(), label: \"Edit\" })}>\n *         Record change\n *       </button>\n *       <button onClick={undo} disabled={history.length === 0}>\n *         Undo{peek() ? ` (${peek()!.label})` : \"\"}\n *       </button>\n *       <p>History depth: {history.length}</p>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Push, pop from the top (LIFO), reset\n * const [s, { push, pop, reset }] = useStack<number>([1, 2]);\n * push(3, 4);       // stack: [1, 2, 3, 4] (4 is the top)\n * pop();            // returns 4, stack: [1, 2, 3]\n * reset();          // back to [1, 2]\n * ```\n */\nexport function useStack<T>(\n  initialState?: StackInitializer<T>\n): UseStackReturn<T> {\n  // Resolve the initial stack exactly once and keep it for `reset`.\n  const initialRef = useRef<T[] | null>(null);\n  if (initialRef.current === null) {\n    initialRef.current = resolveInitial(initialState);\n  }\n\n  const [stack, setStack] = useState<T[]>(() => [\n    ...(initialRef.current as T[]),\n  ]);\n\n  // Mirror the latest stack so `pop`/`peek` can be stable callbacks that still\n  // read fresh state.\n  const stackStateRef = useRef(stack);\n  stackStateRef.current = stack;\n\n  const push = useCallback((...items: T[]) => {\n    setStack((prev) => (items.length === 0 ? prev : [...prev, ...items]));\n  }, []);\n\n  const pop = useCallback((): T | undefined => {\n    // Capture the top from the mirrored state so we can return it.\n    const top = stackStateRef.current[stackStateRef.current.length - 1];\n    setStack((prev) => (prev.length === 0 ? prev : prev.slice(0, -1)));\n    return top;\n  }, []);\n\n  const peek = useCallback(\n    (): T | undefined =>\n      stackStateRef.current[stackStateRef.current.length - 1],\n    []\n  );\n\n  const clear = useCallback(() => {\n    setStack((prev) => (prev.length === 0 ? prev : []));\n  }, []);\n\n  const reset = useCallback(() => {\n    setStack([...(initialRef.current as T[])]);\n  }, []);\n\n  const actions = useMemo<UseStackActions<T>>(\n    () => ({ push, pop, peek, clear, reset }),\n    [push, pop, peek, clear, reset]\n  );\n\n  return [stack, actions];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAuD;AAYvD,SAAS,eAAkB,SAAoC;AAC7D,QAAM,QAAQ,OAAO,YAAY,aAAa,QAAQ,IAAI;AAC1D,SAAO,QAAQ,CAAC,GAAG,KAAK,IAAI,CAAC;AAC/B;AAqEO,SAAS,SACd,cACmB;AAEnB,QAAM,iBAAa,qBAAmB,IAAI;AAC1C,MAAI,WAAW,YAAY,MAAM;AAC/B,eAAW,UAAU,eAAe,YAAY;AAAA,EAClD;AAEA,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAc,MAAM;AAAA,IAC5C,GAAI,WAAW;AAAA,EACjB,CAAC;AAID,QAAM,oBAAgB,qBAAO,KAAK;AAClC,gBAAc,UAAU;AAExB,QAAM,WAAO,0BAAY,IAAI,UAAe;AAC1C,aAAS,CAAC,SAAU,MAAM,WAAW,IAAI,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,CAAE;AAAA,EACtE,GAAG,CAAC,CAAC;AAEL,QAAM,UAAM,0BAAY,MAAqB;AAE3C,UAAM,MAAM,cAAc,QAAQ,cAAc,QAAQ,SAAS,CAAC;AAClE,aAAS,CAAC,SAAU,KAAK,WAAW,IAAI,OAAO,KAAK,MAAM,GAAG,EAAE,CAAE;AACjE,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEL,QAAM,WAAO;AAAA,IACX,MACE,cAAc,QAAQ,cAAc,QAAQ,SAAS,CAAC;AAAA,IACxD,CAAC;AAAA,EACH;AAEA,QAAM,YAAQ,0BAAY,MAAM;AAC9B,aAAS,CAAC,SAAU,KAAK,WAAW,IAAI,OAAO,CAAC,CAAE;AAAA,EACpD,GAAG,CAAC,CAAC;AAEL,QAAM,YAAQ,0BAAY,MAAM;AAC9B,aAAS,CAAC,GAAI,WAAW,OAAe,CAAC;AAAA,EAC3C,GAAG,CAAC,CAAC;AAEL,QAAM,cAAU;AAAA,IACd,OAAO,EAAE,MAAM,KAAK,MAAM,OAAO,MAAM;AAAA,IACvC,CAAC,MAAM,KAAK,MAAM,OAAO,KAAK;AAAA,EAChC;AAEA,SAAO,CAAC,OAAO,OAAO;AACxB;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,44 @@
+// src/useStack.ts
+import { useCallback, useMemo, useRef, useState } from "react";
+function resolveInitial(initial) {
+  const value = typeof initial === "function" ? initial() : initial;
+  return value ? [...value] : [];
+}
+function useStack(initialState) {
+  const initialRef = useRef(null);
+  if (initialRef.current === null) {
+    initialRef.current = resolveInitial(initialState);
+  }
+  const [stack, setStack] = useState(() => [
+    ...initialRef.current
+  ]);
+  const stackStateRef = useRef(stack);
+  stackStateRef.current = stack;
+  const push = useCallback((...items) => {
+    setStack((prev) => items.length === 0 ? prev : [...prev, ...items]);
+  }, []);
+  const pop = useCallback(() => {
+    const top = stackStateRef.current[stackStateRef.current.length - 1];
+    setStack((prev) => prev.length === 0 ? prev : prev.slice(0, -1));
+    return top;
+  }, []);
+  const peek = useCallback(
+    () => stackStateRef.current[stackStateRef.current.length - 1],
+    []
+  );
+  const clear = useCallback(() => {
+    setStack((prev) => prev.length === 0 ? prev : []);
+  }, []);
+  const reset = useCallback(() => {
+    setStack([...initialRef.current]);
+  }, []);
+  const actions = useMemo(
+    () => ({ push, pop, peek, clear, reset }),
+    [push, pop, peek, clear, reset]
+  );
+  return [stack, actions];
+}
+export {
+  useStack
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useStack.ts"],"sourcesContent":["import { useCallback, useMemo, useRef, useState } from \"react\";\nimport type {\n  StackInitializer,\n  UseStackActions,\n  UseStackReturn,\n} from \"./types\";\n\n/**\n * Resolve a {@link StackInitializer} to a concrete array. A function\n * initializer is invoked once; any iterable is copied into a fresh array so the\n * caller's original object is never mutated.\n */\nfunction resolveInitial<T>(initial?: StackInitializer<T>): T[] {\n  const value = typeof initial === \"function\" ? initial() : initial;\n  return value ? [...value] : [];\n}\n\n/**\n * A React hook for managing a LIFO (last-in, first-out) stack as React state\n * with immutable, ergonomic updates.\n *\n * The LIFO sibling of {@link https://npmjs.com/package/@usefy/use-queue | useQueue}\n * — identical in shape and conventions, but pushes and pops from the same end.\n *\n * Returns a tuple of the current (read-only) stack and a stable set of actions.\n * The **top** of the stack is the last element (`stack[stack.length - 1]`, the\n * next item to be popped) and new items are pushed onto the end. Every mutation\n * produces a brand-new array so React re-renders correctly and the previous\n * state is never mutated in place. Updates that would not change anything\n * (pushing nothing, popping from or clearing an empty stack) are skipped to\n * avoid needless re-renders.\n *\n * Features:\n * - Immutable updates (new array on every change) with a `readonly T[]` return type\n * - LIFO semantics: `push` and `pop` both operate on the top (the array's end)\n * - `pop` returns the popped item (or `undefined` when empty)\n * - `peek` reads the top item without mutating; stable and always current\n * - Stable action identities — safe to use as effect dependencies\n * - `useState`-style lazy initialization; accepts an array, iterable, or factory\n * - Full TypeScript generics for the element type\n *\n * Reading `top` / `bottom` / `size` is done directly on the returned stack:\n * `stack[stack.length - 1]`, `stack[0]`, and `stack.length` respectively.\n *\n * @template T - Element type.\n * @param initialState - Initial items, or a factory returning them. Defaults to empty.\n * @returns `[stack, { push, pop, peek, clear, reset }]`\n *\n * @example\n * ```tsx\n * // An undo / navigation history stack\n * interface Snapshot { id: number; label: string }\n *\n * function Editor() {\n *   const [history, { push, pop, peek }] = useStack<Snapshot>([]);\n *\n *   const undo = () => {\n *     const last = pop(); // remove + read the most recent change in one call\n *     if (last) restore(last);\n *   };\n *\n *   return (\n *     <div>\n *       <button onClick={() => push({ id: Date.now(), label: \"Edit\" })}>\n *         Record change\n *       </button>\n *       <button onClick={undo} disabled={history.length === 0}>\n *         Undo{peek() ? ` (${peek()!.label})` : \"\"}\n *       </button>\n *       <p>History depth: {history.length}</p>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Push, pop from the top (LIFO), reset\n * const [s, { push, pop, reset }] = useStack<number>([1, 2]);\n * push(3, 4);       // stack: [1, 2, 3, 4] (4 is the top)\n * pop();            // returns 4, stack: [1, 2, 3]\n * reset();          // back to [1, 2]\n * ```\n */\nexport function useStack<T>(\n  initialState?: StackInitializer<T>\n): UseStackReturn<T> {\n  // Resolve the initial stack exactly once and keep it for `reset`.\n  const initialRef = useRef<T[] | null>(null);\n  if (initialRef.current === null) {\n    initialRef.current = resolveInitial(initialState);\n  }\n\n  const [stack, setStack] = useState<T[]>(() => [\n    ...(initialRef.current as T[]),\n  ]);\n\n  // Mirror the latest stack so `pop`/`peek` can be stable callbacks that still\n  // read fresh state.\n  const stackStateRef = useRef(stack);\n  stackStateRef.current = stack;\n\n  const push = useCallback((...items: T[]) => {\n    setStack((prev) => (items.length === 0 ? prev : [...prev, ...items]));\n  }, []);\n\n  const pop = useCallback((): T | undefined => {\n    // Capture the top from the mirrored state so we can return it.\n    const top = stackStateRef.current[stackStateRef.current.length - 1];\n    setStack((prev) => (prev.length === 0 ? prev : prev.slice(0, -1)));\n    return top;\n  }, []);\n\n  const peek = useCallback(\n    (): T | undefined =>\n      stackStateRef.current[stackStateRef.current.length - 1],\n    []\n  );\n\n  const clear = useCallback(() => {\n    setStack((prev) => (prev.length === 0 ? prev : []));\n  }, []);\n\n  const reset = useCallback(() => {\n    setStack([...(initialRef.current as T[])]);\n  }, []);\n\n  const actions = useMemo<UseStackActions<T>>(\n    () => ({ push, pop, peek, clear, reset }),\n    [push, pop, peek, clear, reset]\n  );\n\n  return [stack, actions];\n}\n"],"mappings":";AAAA,SAAS,aAAa,SAAS,QAAQ,gBAAgB;AAYvD,SAAS,eAAkB,SAAoC;AAC7D,QAAM,QAAQ,OAAO,YAAY,aAAa,QAAQ,IAAI;AAC1D,SAAO,QAAQ,CAAC,GAAG,KAAK,IAAI,CAAC;AAC/B;AAqEO,SAAS,SACd,cACmB;AAEnB,QAAM,aAAa,OAAmB,IAAI;AAC1C,MAAI,WAAW,YAAY,MAAM;AAC/B,eAAW,UAAU,eAAe,YAAY;AAAA,EAClD;AAEA,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAc,MAAM;AAAA,IAC5C,GAAI,WAAW;AAAA,EACjB,CAAC;AAID,QAAM,gBAAgB,OAAO,KAAK;AAClC,gBAAc,UAAU;AAExB,QAAM,OAAO,YAAY,IAAI,UAAe;AAC1C,aAAS,CAAC,SAAU,MAAM,WAAW,IAAI,OAAO,CAAC,GAAG,MAAM,GAAG,KAAK,CAAE;AAAA,EACtE,GAAG,CAAC,CAAC;AAEL,QAAM,MAAM,YAAY,MAAqB;AAE3C,UAAM,MAAM,cAAc,QAAQ,cAAc,QAAQ,SAAS,CAAC;AAClE,aAAS,CAAC,SAAU,KAAK,WAAW,IAAI,OAAO,KAAK,MAAM,GAAG,EAAE,CAAE;AACjE,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEL,QAAM,OAAO;AAAA,IACX,MACE,cAAc,QAAQ,cAAc,QAAQ,SAAS,CAAC;AAAA,IACxD,CAAC;AAAA,EACH;AAEA,QAAM,QAAQ,YAAY,MAAM;AAC9B,aAAS,CAAC,SAAU,KAAK,WAAW,IAAI,OAAO,CAAC,CAAE;AAAA,EACpD,GAAG,CAAC,CAAC;AAEL,QAAM,QAAQ,YAAY,MAAM;AAC9B,aAAS,CAAC,GAAI,WAAW,OAAe,CAAC;AAAA,EAC3C,GAAG,CAAC,CAAC;AAEL,QAAM,UAAU;AAAA,IACd,OAAO,EAAE,MAAM,KAAK,MAAM,OAAO,MAAM;AAAA,IACvC,CAAC,MAAM,KAAK,MAAM,OAAO,KAAK;AAAA,EAChC;AAEA,SAAO,CAAC,OAAO,OAAO;AACxB;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@usefy/use-stack",
+  "version": "0.19.0",
+  "description": "A React hook for managing LIFO stack state with immutable updates",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/hooks/use-stack"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "stack",
+    "lifo",
+    "state",
+    "collection",
+    "data-structure",
+    "useStack"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}