@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/hooks/use-array/use-array.test.tsx

@@ -0,0 +1,495 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useArray } from "../use-array";
+
+describe("useArray hook", () => {
+  it("should initialize with default value", () => {
+    const defaultList = ["First", "Second", "Third"];
+    const { result } = renderHook(() => useArray(defaultList));
+    const [list] = result.current;
+
+    expect(list).toEqual(defaultList);
+  });
+
+  it("should insert item at specified index", () => {
+    const initialList = ["First", "Second", "Third"];
+    const { result } = renderHook(() => useArray(initialList));
+    const [, { insertAt }] = result.current;
+
+    act(() => insertAt(1, "Inserted"));
+
+    expect(result.current[0]).toEqual(["First", "Inserted", "Second", "Third"]);
+  });
+
+  it("should remove item at specified index", () => {
+    const initialList = ["First", "Second", "Third"];
+    const { result } = renderHook(() => useArray(initialList));
+    const [, { removeAt }] = result.current;
+
+    act(() => removeAt(1));
+
+    expect(result.current[0]).toEqual(["First", "Third"]);
+  });
+
+  it("should update item at specified index", () => {
+    const initialList = ["First", "Second", "Third"];
+    const { result } = renderHook(() => useArray(initialList));
+    const [, { updateAt }] = result.current;
+
+    act(() => updateAt(1, "Updated"));
+
+    expect(result.current[0]).toEqual(["First", "Updated", "Third"]);
+  });
+
+  it("should clear the list", () => {
+    const initialList = ["First", "Second", "Third"];
+    const { result } = renderHook(() => useArray(initialList));
+    const [, { clear }] = result.current;
+
+    act(() => clear());
+
+    expect(result.current[0]).toEqual([]);
+  });
+
+  it("should reset to default value", () => {
+    const defaultList = ["First", "Second", "Third"];
+    const newList = ["New", "List"];
+    const { result } = renderHook((props) => useArray(props), {
+      initialProps: defaultList,
+    });
+
+    const [, { reset, push }] = result.current;
+
+    act(() => push(newList[0]));
+    act(() => reset());
+
+    expect(result.current[0]).toEqual(defaultList);
+  });
+
+  it("should push item to end of list", () => {
+    const initialList = ["First", "Second"];
+    const { result } = renderHook(() => useArray(initialList));
+    const [, { push }] = result.current;
+
+    act(() => push("New"));
+
+    expect(result.current[0]).toEqual(["First", "Second", "New"]);
+  });
+
+  it("pop removes last item", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].pop());
+    expect(result.current[0]).toEqual(["a", "b"]);
+  });
+
+  it("set replaces entire list", () => {
+    const { result } = renderHook(() => useArray(["a", "b"]));
+    act(() => result.current[1].set(["x", "y", "z"]));
+    expect(result.current[0]).toEqual(["x", "y", "z"]);
+  });
+
+  // T-1.1: rename update → replace in existing update-based tests
+  it("replace with value updates first matching item", () => {
+    const { result } = renderHook(() => useArray(["First", "Second", "Third"]));
+    const [, { replace }] = result.current;
+
+    act(() => replace((item) => item === "Second", "Updated"));
+
+    expect(result.current[0]).toEqual(["First", "Updated", "Third"]);
+  });
+
+  it("replace with function callback transforms matched item", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() =>
+      result.current[1].replace(
+        (n) => n === 2,
+        (n) => n * 10,
+      ),
+    );
+    expect(result.current[0]).toEqual([1, 20, 3]);
+  });
+
+  it("replace does nothing when predicate matches nothing", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].replace((n) => n === 99, 0));
+    expect(result.current[0]).toEqual([1, 2, 3]);
+  });
+});
+
+// T-1.2: existing actions — immutability
+describe("existing actions — immutability", () => {
+  it("push does not mutate prior array ref", () => {
+    const { result } = renderHook(() => useArray([1, 2]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].push(3));
+    expect(prevRef).toEqual([1, 2]);
+    expect(result.current[0]).toEqual([1, 2, 3]);
+    expect(result.current[0]).not.toBe(prevRef);
+  });
+
+  it("pop on empty array is a no-op", () => {
+    const { result } = renderHook(() => useArray<number>([]));
+    act(() => result.current[1].pop());
+    expect(result.current[0]).toHaveLength(0);
+  });
+
+  it("sort does not mutate prior array ref", () => {
+    const { result } = renderHook(() => useArray([3, 1, 2]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].sort((a, b) => a - b));
+    expect(prevRef).toEqual([3, 1, 2]);
+    expect(result.current[0]).toEqual([1, 2, 3]);
+  });
+
+  it("reverse does not mutate prior array ref", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].reverse());
+    expect(prevRef).toEqual([1, 2, 3]);
+    expect(result.current[0]).toEqual([3, 2, 1]);
+  });
+});
+
+// T-1.3: new actions — replace
+describe("new actions — replace", () => {
+  it("replace by value replaces first matching element", () => {
+    const { result } = renderHook(() => useArray([{ id: 1 }, { id: 2 }]));
+    act(() => result.current[1].replace((x) => x.id === 2, { id: 99 }));
+    expect(result.current[0]).toEqual([{ id: 1 }, { id: 99 }]);
+  });
+
+  it("replace with updater function transforms matched item", () => {
+    const { result } = renderHook(() => useArray([{ id: 1, count: 5 }]));
+    act(() =>
+      result.current[1].replace(
+        (x) => x.id === 1,
+        (x) => ({ ...x, count: x.count + 1 }),
+      ),
+    );
+    expect(result.current[0]).toEqual([{ id: 1, count: 6 }]);
+  });
+
+  it("replace no-match returns same array ref — no re-render trigger", () => {
+    const { result } = renderHook(() => useArray([{ id: 1 }]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].replace((x) => x.id === 99, { id: 99 }));
+    expect(result.current[0]).toBe(prevRef);
+  });
+});
+
+// T-1.4: new actions — move/swap
+describe("new actions — move/swap", () => {
+  it("move(0, 2) on [a,b,c] produces [b,c,a]", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].move(0, 2));
+    expect(result.current[0]).toEqual(["b", "c", "a"]);
+  });
+
+  it("move(2, 0) on [a,b,c] produces [c,a,b]", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].move(2, 0));
+    expect(result.current[0]).toEqual(["c", "a", "b"]);
+  });
+
+  it("move same-index leaves list content unchanged", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].move(1, 1));
+    expect(result.current[0]).toEqual(["a", "b", "c"]);
+  });
+
+  it("move same-index returns same array ref (no re-render trigger)", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].move(1, 1));
+    expect(result.current[0]).toBe(prevRef);
+  });
+
+  it("swap(0, 2) on [a,b,c] produces [c,b,a]", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].swap(0, 2));
+    expect(result.current[0]).toEqual(["c", "b", "a"]);
+  });
+
+  it("swap same-index leaves list content unchanged", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].swap(1, 1));
+    expect(result.current[0]).toEqual([1, 2, 3]);
+  });
+
+  it("swap same-index returns same array ref (no re-render trigger)", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].swap(1, 1));
+    expect(result.current[0]).toBe(prevRef);
+  });
+});
+
+// T-1.5: new actions — filter/removeWhere
+describe("new actions — filter/removeWhere", () => {
+  it("filter retains matching items", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3, 4]));
+    act(() => result.current[1].filter((x) => x % 2 === 0));
+    expect(result.current[0]).toEqual([2, 4]);
+  });
+
+  it("filter returns empty array when nothing matches", () => {
+    const { result } = renderHook(() => useArray([1, 3, 5]));
+    act(() => result.current[1].filter((x) => x % 2 === 0));
+    expect(result.current[0]).toEqual([]);
+  });
+
+  it("removeWhere removes all matching elements", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3, 4]));
+    act(() => result.current[1].removeWhere((x) => x % 2 === 0));
+    expect(result.current[0]).toEqual([1, 3]);
+  });
+
+  it("removeWhere no-op when nothing matches", () => {
+    const { result } = renderHook(() => useArray([1, 3, 5]));
+    act(() => result.current[1].removeWhere((x) => x % 2 === 0));
+    expect(result.current[0]).toEqual([1, 3, 5]);
+  });
+});
+
+// T-1.6: new actions — sort/reverse
+describe("new actions — sort/reverse", () => {
+  it("sort without comparator sorts alphabetically", () => {
+    const { result } = renderHook(() =>
+      useArray(["banana", "apple", "cherry"]),
+    );
+    act(() => result.current[1].sort());
+    expect(result.current[0]).toEqual(["apple", "banana", "cherry"]);
+  });
+
+  it("sort with custom comparator sorts numerically", () => {
+    const { result } = renderHook(() => useArray([3, 1, 2]));
+    act(() => result.current[1].sort((a, b) => a - b));
+    expect(result.current[0]).toEqual([1, 2, 3]);
+  });
+
+  it("sort does NOT mutate the previous state array ref", () => {
+    const { result } = renderHook(() => useArray([3, 1, 2]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].sort((a, b) => a - b));
+    expect(prevRef).toEqual([3, 1, 2]);
+  });
+
+  it("reverse reverses order", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].reverse());
+    expect(result.current[0]).toEqual([3, 2, 1]);
+  });
+
+  it("reverse does NOT mutate the previous state array ref", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].reverse());
+    expect(prevRef).toEqual([1, 2, 3]);
+  });
+});
+
+// T-1.7: new actions — pushMany
+describe("new actions — pushMany", () => {
+  it("pushMany appends all items", () => {
+    const { result } = renderHook(() => useArray([1, 2]));
+    act(() => result.current[1].pushMany([3, 4, 5]));
+    expect(result.current[0]).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it("pushMany with empty array does not change length", () => {
+    const { result } = renderHook(() => useArray([1, 2]));
+    act(() => result.current[1].pushMany([]));
+    expect(result.current[0]).toEqual([1, 2]);
+  });
+
+  it("pushMany with empty array returns same array ref (no re-render trigger)", () => {
+    const { result } = renderHook(() => useArray([1, 2]));
+    const prevRef = result.current[0];
+    act(() => result.current[1].pushMany([]));
+    expect(result.current[0]).toBe(prevRef);
+  });
+});
+
+// T-1.8: new actions — find
+describe("new actions — find", () => {
+  it("find returns first matching item", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const found = result.current[1].find((x) => x > 1);
+    expect(found).toBe(2);
+  });
+
+  it("find returns undefined when no match", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const found = result.current[1].find((x) => x > 10);
+    expect(found).toBeUndefined();
+  });
+
+  it("find reflects state after a mutation", () => {
+    const { result } = renderHook(() => useArray([1, 2]));
+    act(() => result.current[1].push(3));
+    const found = result.current[1].find((x) => x === 3);
+    expect(found).toBe(3);
+  });
+});
+
+// T-1.9: action stability
+describe("action stability", () => {
+  it("all action refs are identical before and after a push", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+
+    const actionsBefore = result.current[1];
+    const {
+      push,
+      pop,
+      insertAt,
+      removeAt,
+      updateAt,
+      clear,
+      reset,
+      set,
+      move,
+      swap,
+      filter,
+      sort,
+      reverse,
+      replace,
+      removeWhere,
+      pushMany,
+      find,
+    } = actionsBefore;
+
+    act(() => result.current[1].push(4));
+
+    const actionsAfter = result.current[1];
+    expect(actionsAfter.push).toBe(push);
+    expect(actionsAfter.pop).toBe(pop);
+    expect(actionsAfter.insertAt).toBe(insertAt);
+    expect(actionsAfter.removeAt).toBe(removeAt);
+    expect(actionsAfter.updateAt).toBe(updateAt);
+    expect(actionsAfter.clear).toBe(clear);
+    expect(actionsAfter.reset).toBe(reset);
+    expect(actionsAfter.set).toBe(set);
+    expect(actionsAfter.move).toBe(move);
+    expect(actionsAfter.swap).toBe(swap);
+    expect(actionsAfter.filter).toBe(filter);
+    expect(actionsAfter.sort).toBe(sort);
+    expect(actionsAfter.reverse).toBe(reverse);
+    expect(actionsAfter.replace).toBe(replace);
+    expect(actionsAfter.removeWhere).toBe(removeWhere);
+    expect(actionsAfter.pushMany).toBe(pushMany);
+    expect(actionsAfter.find).toBe(find);
+  });
+
+  it("the actions object ref itself is stable", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    const actionsBefore = result.current[1];
+    act(() => result.current[1].push(4));
+    expect(result.current[1]).toBe(actionsBefore);
+  });
+});
+
+// T-1.10: onChange
+describe("onChange", () => {
+  it("onChange does NOT fire when replace finds no match", () => {
+    const spy = vi.fn();
+    const { result } = renderHook(() => useArray([1, 2, 3], { onChange: spy }));
+    act(() => result.current[1].replace((n) => n === 99, 0));
+    expect(spy).not.toHaveBeenCalled();
+  });
+  it("onChange fires after push with updated list", () => {
+    const spy = vi.fn();
+    const { result } = renderHook(() => useArray([1], { onChange: spy }));
+    act(() => result.current[1].push(2));
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith([1, 2]);
+  });
+
+  it("onChange fires after pop", () => {
+    const spy = vi.fn();
+    const { result } = renderHook(() => useArray([1, 2], { onChange: spy }));
+    act(() => result.current[1].pop());
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith([1]);
+  });
+
+  it("onChange does NOT fire on initial mount", () => {
+    const spy = vi.fn();
+    renderHook(() => useArray([1, 2, 3], { onChange: spy }));
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("changing the onChange function reference does not cause double-fires", () => {
+    const spy1 = vi.fn();
+    const spy2 = vi.fn();
+    let onChange = spy1;
+    const { result, rerender } = renderHook(() => useArray([1], { onChange }));
+    onChange = spy2;
+    rerender();
+    act(() => result.current[1].push(2));
+    expect(spy1).toHaveBeenCalledTimes(0);
+    expect(spy2).toHaveBeenCalledTimes(1);
+  });
+});
+
+// T-1.11: reset — frozen initial
+describe("reset — frozen initial", () => {
+  it("multiple mutations → reset restores mount-time value", () => {
+    const initial = ["a", "b", "c"];
+    const { result } = renderHook(() => useArray(initial));
+    act(() => result.current[1].push("d"));
+    act(() => result.current[1].push("e"));
+    act(() => result.current[1].pop());
+    act(() => result.current[1].reset());
+    expect(result.current[0]).toEqual(["a", "b", "c"]);
+  });
+
+  it("reset still restores original mount-time value when prop changes after mount", () => {
+    const initial = ["a", "b"];
+    const { result, rerender } = renderHook(
+      (props: string[]) => useArray(props),
+      {
+        initialProps: initial,
+      },
+    );
+    rerender(["x", "y", "z"]);
+    act(() => result.current[1].reset());
+    expect(result.current[0]).toEqual(["a", "b"]);
+  });
+});
+
+// T-1.12: edge cases
+describe("edge cases", () => {
+  it("insertAt(0, item) inserts at beginning", () => {
+    const { result } = renderHook(() => useArray(["b", "c"]));
+    act(() => result.current[1].insertAt(0, "a"));
+    expect(result.current[0]).toEqual(["a", "b", "c"]);
+  });
+
+  it("insertAt(list.length, item) inserts at end", () => {
+    const { result } = renderHook(() => useArray(["a", "b"]));
+    act(() => result.current[1].insertAt(2, "c"));
+    expect(result.current[0]).toEqual(["a", "b", "c"]);
+  });
+
+  it("removeAt out-of-bounds does not crash", () => {
+    const { result } = renderHook(() => useArray(["a", "b"]));
+    expect(() => act(() => result.current[1].removeAt(99))).not.toThrow();
+  });
+
+  it("updateAt out-of-bounds does not crash", () => {
+    const { result } = renderHook(() => useArray(["a", "b"]));
+    expect(() => act(() => result.current[1].updateAt(99, "x"))).not.toThrow();
+  });
+
+  it("sort on empty array does not crash", () => {
+    const { result } = renderHook(() => useArray<number>([]));
+    expect(() => act(() => result.current[1].sort())).not.toThrow();
+    expect(result.current[0]).toEqual([]);
+  });
+
+  it("filter-all returns a new empty array", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].filter(() => false));
+    expect(result.current[0]).toEqual([]);
+  });
+});

package/src/hooks/use-array/use-array.ts

@@ -0,0 +1,113 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface UseArrayOptions<T> {
+  /** Called after every list change. NOT called on initial mount. */
+  onChange?: (items: T[]) => void;
+}
+
+export interface UseArrayActions<T> {
+  push(item: T): void;
+  pop(): void;
+  insertAt(index: number, item: T): void;
+  removeAt(index: number): void;
+  updateAt(index: number, item: T): void;
+  clear(): void;
+  reset(): void;
+  set(items: T[]): void;
+  move(from: number, to: number): void;
+  swap(indexA: number, indexB: number): void;
+  filter(predicate: (item: T, index: number, array: T[]) => boolean): void;
+  sort(compareFn?: (a: T, b: T) => number): void;
+  reverse(): void;
+  replace(predicate: (item: T) => boolean, newItem: T | ((item: T) => T)): void;
+  removeWhere(predicate: (item: T) => boolean): void;
+  pushMany(items: T[]): void;
+  find(
+    predicate: (item: T, index: number, array: T[]) => boolean,
+  ): T | undefined;
+}
+
+export function useArray<T>(
+  initialValue: T[],
+  options?: UseArrayOptions<T>,
+): readonly [T[], UseArrayActions<T>] {
+  const [list, setList] = useState<T[]>(initialValue);
+
+  // Frozen on mount — reset always restores the original value.
+  const initialRef = useRef(initialValue);
+  // Always current — find reads this without invalidating the memo.
+  const listRef = useLatestRef(list);
+  // Always the latest handler — never a memo/effect dep.
+  const onChangeRef = useLatestRef(options?.onChange);
+
+  // Fire onChange on every change EXCEPT the initial mount.
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    onChangeRef.current?.(list);
+  }, [list]);
+
+  const actions = useMemo<UseArrayActions<T>>(
+    () => ({
+      push: (item) => setList((prev) => [...prev, item]),
+      pop: () => setList((prev) => prev.slice(0, -1)),
+      insertAt: (index, item) =>
+        setList((prev) => [
+          ...prev.slice(0, index),
+          item,
+          ...prev.slice(index),
+        ]),
+      removeAt: (index) =>
+        setList((prev) => prev.filter((_, idx) => idx !== index)),
+      updateAt: (index, item) =>
+        setList((prev) => prev.map((x, idx) => (idx === index ? item : x))),
+      clear: () => setList([]),
+      reset: () => setList(initialRef.current),
+      set: (items) => setList(items),
+      move: (from, to) =>
+        setList((prev) => {
+          if (from === to) return prev;
+          const next = [...prev];
+          const [moved] = next.splice(from, 1);
+          next.splice(to, 0, moved);
+          return next;
+        }),
+      swap: (a, b) =>
+        setList((prev) => {
+          if (a === b) return prev;
+          const next = [...prev];
+          [next[a], next[b]] = [next[b], next[a]];
+          return next;
+        }),
+      filter: (predicate) => setList((prev) => prev.filter(predicate)),
+      sort: (compareFn) => setList((prev) => [...prev].sort(compareFn)),
+      reverse: () => setList((prev) => [...prev].reverse()),
+      replace: (predicate, newItem) =>
+        setList((prev) => {
+          const index = prev.findIndex(predicate);
+          if (index === -1) return prev;
+          return prev.map((x, idx) =>
+            idx === index
+              ? typeof newItem === "function"
+                ? (newItem as (item: T) => T)(x)
+                : newItem
+              : x,
+          );
+        }),
+      removeWhere: (predicate) =>
+        setList((prev) => prev.filter((v) => !predicate(v))),
+      pushMany: (items) => {
+        if (items.length === 0) return;
+        setList((prev) => [...prev, ...items]);
+      },
+      find: (predicate) => listRef.current.find(predicate),
+    }),
+    [setList], // setList is stable for component lifetime → memo computes once
+  );
+
+  return [list, actions] as const;
+}

package/src/hooks/use-async/index.ts

@@ -0,0 +1 @@
+export * from "./use-async";