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

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

@@ -1,5 +1,5 @@
 import { act, renderHook } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { useArray } from "../use-array";
 
 describe("useArray hook", () => {
@@ -76,16 +76,6 @@ describe("useArray hook", () => {
     expect(result.current[0]).toEqual(["First", "Second", "New"]);
   });
 
-  it("should update item based on predicate", () => {
-    const initialList = ["First", "Second", "Third"];
-    const { result } = renderHook(() => useArray(initialList));
-    const [, { update }] = result.current;
-
-    act(() => update((item) => item === "Second", "Updated"));
-
-    expect(result.current[0]).toEqual(["First", "Updated", "Third"]);
-  });
-
   it("pop removes last item", () => {
     const { result } = renderHook(() => useArray(["a", "b", "c"]));
     act(() => result.current[1].pop());
@@ -98,15 +88,408 @@ describe("useArray hook", () => {
     expect(result.current[0]).toEqual(["x", "y", "z"]);
   });
 
-  it("update with function callback transforms matched item", () => {
+  // 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].update((n) => n === 2, (n) => n * 10));
+    act(() =>
+      result.current[1].replace(
+        (n) => n === 2,
+        (n) => n * 10,
+      ),
+    );
     expect(result.current[0]).toEqual([1, 20, 3]);
   });
 
-  it("update does nothing when predicate matches nothing", () => {
+  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]));
-    act(() => result.current[1].update((n) => n === 99, 0));
+    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

@@ -1,74 +1,113 @@
-import { useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
 
-export function useArray<T>(defaultProp: T[]) {
-  const [list = [], setList] = useState(defaultProp);
-
-  const insertAt = (index: number, item: T) => {
-    setList((prevList = []) => {
-      const newList = [...prevList];
-      newList.splice(index, 0, item);
-      return newList;
-    });
-  };
-
-  const removeAt = (index: number) => {
-    setList((prevList = []) => {
-      const newList = [...prevList];
-      newList.splice(index, 1);
-      return newList;
-    });
-  };
-
-  const updateAt = (index: number, newItem: T) => {
-    setList((prevList = []) => {
-      const newList = [...prevList];
-      newList[index] = newItem;
-      return newList;
-    });
-  };
-
-  const clear = () => setList([]);
+export interface UseArrayOptions<T> {
+  /** Called after every list change. NOT called on initial mount. */
+  onChange?: (items: T[]) => void;
+}
 
-  const reset = () => setList(defaultProp);
+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;
+}
 
-  const push = (item: T) => setList((prevList = []) => [...prevList, item]);
+export function useArray<T>(
+  initialValue: T[],
+  options?: UseArrayOptions<T>,
+): readonly [T[], UseArrayActions<T>] {
+  const [list, setList] = useState<T[]>(initialValue);
 
-  const set = (newList: T[]) => setList(newList);
+  // 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);
 
-  const pop = () => {
-    setList((prevList = []) => {
-      const newList = [...prevList];
-      newList.pop();
-      return newList;
-    });
-  };
+  // 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 update = (
-    predicate: (item: T) => boolean,
-    newItem: T | ((item: T) => T),
-  ) => {
-    setList((prevList = []) => {
-      const newList = [...prevList];
-      const index = newList.findIndex(predicate);
-      if (index === -1) return newList;
-      newList[index] = typeof newItem === "function" ? (newItem as (item: T) => T)(newList[index]) : newItem;
-      return newList;
-    });
-  };
+  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,
-    {
-      insertAt,
-      removeAt,
-      updateAt,
-      clear,
-      reset,
-      push,
-      set,
-      pop,
-      update,
-    },
-  ] as const;
+  return [list, actions] as const;
 }
-