atomirx 0.0.1

package/src/react/useStable.ts

@@ -0,0 +1,288 @@
+import { useRef } from "react";
+import { resolveEquality, tryStabilize, StableFn } from "../core/equality";
+import type { AnyFunc, Equality } from "../core/types";
+
+/**
+ * Extracts non-function keys from an object type.
+ */
+type NonFunctionKeys<T> = {
+  [K in keyof T]: T[K] extends AnyFunc ? never : K;
+}[keyof T];
+
+/**
+ * Equals options for useStable - only non-function properties can have custom equality.
+ */
+export type UseStableEquals<T> = {
+  [K in NonFunctionKeys<T>]?: Equality<T[K]>;
+};
+
+/**
+ * Result type for useStable - functions are wrapped in StableFn.
+ */
+export type UseStableResult<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? StableFn<A, R>
+    : T[K];
+};
+
+/**
+ * Storage for each property's previous value.
+ */
+type PropertyStorage<T> = {
+  [K in keyof T]?: { value: T[K] };
+};
+
+/**
+ * Determines the default equality strategy based on value type.
+ *
+ * - Array → 'shallow' (compare items by reference)
+ * - Date → handled specially in tryStabilize (timestamp comparison)
+ * - Object → 'shallow' (compare keys by reference)
+ * - Primitives → 'strict' (reference equality)
+ */
+function getDefaultEquality<T>(value: T): Equality<T> {
+  if (value === null || value === undefined) {
+    return "strict";
+  }
+
+  if (Array.isArray(value)) {
+    return "shallow";
+  }
+
+  if (value instanceof Date) {
+    // Date is handled specially in tryStabilize, but we return deep
+    // to ensure proper comparison if tryStabilize doesn't catch it
+    return "deep";
+  }
+
+  if (typeof value === "object") {
+    return "shallow";
+  }
+
+  return "strict";
+}
+
+/**
+ * React hook that provides stable references for objects, arrays, and callbacks.
+ *
+ * `useStable` solves the common React problem of unstable references causing
+ * unnecessary re-renders, useEffect re-runs, and useCallback/useMemo invalidations.
+ *
+ * ## Why Use `useStable`?
+ *
+ * In React, inline objects, arrays, and callbacks create new references on every render:
+ *
+ * ```tsx
+ * // ❌ Problem: new reference every render
+ * function Parent() {
+ *   const config = { theme: 'dark' };  // New object every render!
+ *   const onClick = () => doSomething(); // New function every render!
+ *   return <Child config={config} onClick={onClick} />;
+ * }
+ *
+ * // ✅ Solution: stable references
+ * function Parent() {
+ *   const stable = useStable({
+ *     config: { theme: 'dark' },
+ *     onClick: () => doSomething(),
+ *   });
+ *   return <Child config={stable.config} onClick={stable.onClick} />;
+ * }
+ * ```
+ *
+ * ## How It Works
+ *
+ * Each property is independently stabilized based on its type:
+ *
+ * | Type | Default Equality | Behavior |
+ * |------|------------------|----------|
+ * | **Functions** | N/A (always wrapped) | Reference never changes, calls latest implementation |
+ * | **Arrays** | shallow | Stable if items are reference-equal |
+ * | **Dates** | timestamp | Stable if same time value |
+ * | **Objects** | shallow | Stable if keys have reference-equal values |
+ * | **Primitives** | strict | Stable if same value |
+ *
+ * ## Key Benefits
+ *
+ * 1. **Stable callbacks**: Functions maintain reference identity while always calling latest implementation
+ * 2. **Stable objects/arrays**: Prevent unnecessary child re-renders
+ * 3. **Safe for deps arrays**: Use in useEffect, useMemo, useCallback deps
+ * 4. **Per-property equality**: Customize comparison strategy for each property
+ * 5. **No wrapper overhead**: Returns the same result object reference
+ *
+ * @template T - The type of the input object
+ * @param input - Object with properties to stabilize
+ * @param equals - Optional custom equality strategies per property (except functions)
+ * @returns Stable object with same properties (functions wrapped in StableFn)
+ *
+ * @example Basic usage - stable callbacks and objects
+ * ```tsx
+ * function MyComponent({ userId }) {
+ *   const stable = useStable({
+ *     // Object - stable if shallow equal
+ *     config: { theme: 'dark', userId },
+ *     // Array - stable if items are reference-equal
+ *     items: [1, 2, 3],
+ *     // Function - reference never changes
+ *     onClick: () => console.log('clicked', userId),
+ *   });
+ *
+ *   // Safe to use in deps - won't cause infinite loops
+ *   useEffect(() => {
+ *     console.log(stable.config);
+ *   }, [stable.config]);
+ *
+ *   // stable.onClick is always the same reference
+ *   return <button onClick={stable.onClick}>Click</button>;
+ * }
+ * ```
+ *
+ * @example Preventing child re-renders
+ * ```tsx
+ * function Parent() {
+ *   const [count, setCount] = useState(0);
+ *
+ *   const stable = useStable({
+ *     // These won't cause Child to re-render when count changes
+ *     user: { id: 1, name: 'John' },
+ *     onSave: () => saveUser(),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ *       <MemoizedChild user={stable.user} onSave={stable.onSave} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Custom equality per property
+ * ```tsx
+ * const stable = useStable(
+ *   {
+ *     user: { id: 1, profile: { name: "John", avatar: "..." } },
+ *     tags: ["react", "typescript"],
+ *     settings: { theme: "dark" },
+ *   },
+ *   {
+ *     user: "deep",              // Deep compare nested objects
+ *     tags: "strict",            // Override default shallow for arrays
+ *     settings: "shallow",       // Explicit shallow (same as default)
+ *   }
+ * );
+ * ```
+ *
+ * @example Custom equality function
+ * ```tsx
+ * const stable = useStable(
+ *   { user: { id: 1, name: "John", updatedAt: new Date() } },
+ *   {
+ *     // Only compare by id - ignore name and updatedAt changes
+ *     user: (a, b) => a?.id === b?.id
+ *   }
+ * );
+ * // stable.user reference only changes when id changes
+ * ```
+ *
+ * @example With useEffect deps
+ * ```tsx
+ * function DataFetcher({ filters }) {
+ *   const stable = useStable({
+ *     filters: { ...filters, timestamp: Date.now() },
+ *     onSuccess: (data) => processData(data),
+ *   });
+ *
+ *   useEffect(() => {
+ *     // Only re-runs when filters actually change (shallow comparison)
+ *     fetchData(stable.filters).then(stable.onSuccess);
+ *   }, [stable.filters, stable.onSuccess]);
+ * }
+ * ```
+ *
+ * @example Stable event handlers for lists
+ * ```tsx
+ * function TodoList({ todos }) {
+ *   const stable = useStable({
+ *     onDelete: (id) => deleteTodo(id),
+ *     onToggle: (id) => toggleTodo(id),
+ *   });
+ *
+ *   return (
+ *     <ul>
+ *       {todos.map(todo => (
+ *         <TodoItem
+ *           key={todo.id}
+ *           todo={todo}
+ *           onDelete={stable.onDelete}  // Same reference for all items
+ *           onToggle={stable.onToggle}  // Prevents unnecessary re-renders
+ *         />
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useStable<T extends Record<string, unknown>>(
+  input: T,
+  equals?: UseStableEquals<T>
+): UseStableResult<T> {
+  // Store previous values for each property
+  const storageRef = useRef<PropertyStorage<T>>({});
+
+  // Store the stable result object (reference never changes)
+  const resultRef = useRef<UseStableResult<T> | null>(null);
+
+  // Initialize result object on first render
+  if (resultRef.current === null) {
+    resultRef.current = {} as UseStableResult<T>;
+  }
+
+  const storage = storageRef.current;
+  const result = resultRef.current;
+
+  // Process each property
+  for (const key of Object.keys(input) as (keyof T)[]) {
+    const nextValue = input[key];
+    const prevStorage = storage[key];
+
+    // Functions are always stabilized, ignore equality option
+    if (typeof nextValue === "function") {
+      const [stabilized] = tryStabilize(
+        prevStorage as { value: AnyFunc } | undefined,
+        nextValue as AnyFunc,
+        () => false // Equality doesn't matter for functions
+      );
+
+      storage[key] = { value: stabilized as T[typeof key] };
+      (result as Record<keyof T, unknown>)[key] = stabilized;
+      continue;
+    }
+
+    // Get equality function for this property
+    const customEquals = equals?.[key as NonFunctionKeys<T>];
+    const equalityFn = customEquals
+      ? resolveEquality(customEquals as Equality<T[typeof key]>)
+      : resolveEquality(getDefaultEquality(nextValue));
+
+    // Stabilize the value
+    const [stabilized] = tryStabilize(
+      prevStorage,
+      nextValue,
+      equalityFn as (a: T[typeof key], b: T[typeof key]) => boolean
+    );
+
+    storage[key] = { value: stabilized };
+    (result as Record<keyof T, unknown>)[key] = stabilized;
+  }
+
+  // Handle removed properties (set to undefined)
+  for (const key of Object.keys(storage) as (keyof T)[]) {
+    if (!(key in input)) {
+      delete storage[key];
+      delete (result as Record<keyof T, unknown>)[key];
+    }
+  }
+
+  return result;
+}

package/src/react/useValue.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { atom } from "../core/atom";
+import { useValue } from "./useValue";
+
+describe("useValue", () => {
+  describe("basic functionality", () => {
+    it("should read value from sync atom", () => {
+      const count$ = atom(5);
+      const { result } = renderHook(() => useValue(count$));
+      expect(result.current).toBe(5);
+    });
+
+    it("should update when atom value changes", async () => {
+      const count$ = atom(0);
+      const { result } = renderHook(() => useValue(count$));
+
+      expect(result.current).toBe(0);
+
+      act(() => {
+        count$.set(10);
+      });
+
+      await waitFor(() => {
+        expect(result.current).toBe(10);
+      });
+    });
+
+    it("should work with object values", () => {
+      const user$ = atom({ name: "John", age: 30 });
+      const { result } = renderHook(() => useValue(user$));
+
+      expect(result.current).toEqual({ name: "John", age: 30 });
+    });
+  });
+
+  describe("selector function", () => {
+    it("should support selector function", () => {
+      const count$ = atom(5);
+      const { result } = renderHook(() =>
+        useValue(({ get }) => get(count$) * 2)
+      );
+
+      expect(result.current).toBe(10);
+    });
+
+    it("should derive from multiple atoms", () => {
+      const a$ = atom(2);
+      const b$ = atom(3);
+      const { result } = renderHook(() =>
+        useValue(({ get }) => get(a$) + get(b$))
+      );
+
+      expect(result.current).toBe(5);
+    });
+
+    it("should update when any source atom changes", async () => {
+      const a$ = atom(2);
+      const b$ = atom(3);
+      const { result } = renderHook(() =>
+        useValue(({ get }) => get(a$) * get(b$))
+      );
+
+      expect(result.current).toBe(6);
+
+      act(() => {
+        a$.set(5);
+      });
+
+      await waitFor(() => {
+        expect(result.current).toBe(15);
+      });
+    });
+  });
+
+  describe("conditional dependencies", () => {
+    it("should track conditional dependencies", async () => {
+      const showDetails$ = atom(false);
+      const summary$ = atom("Brief");
+      const details$ = atom("Detailed");
+
+      const { result } = renderHook(() =>
+        useValue(({ get }) =>
+          get(showDetails$) ? get(details$) : get(summary$)
+        )
+      );
+
+      expect(result.current).toBe("Brief");
+
+      act(() => {
+        showDetails$.set(true);
+      });
+
+      await waitFor(() => {
+        expect(result.current).toBe("Detailed");
+      });
+    });
+  });
+
+  describe("equality checks", () => {
+    it("should use shallow equality by default", async () => {
+      const renderCount = vi.fn();
+      const source$ = atom({ a: 1 });
+
+      const { result } = renderHook(() => {
+        renderCount();
+        return useValue(source$);
+      });
+
+      expect(result.current).toEqual({ a: 1 });
+
+      act(() => {
+        source$.set({ a: 1 }); // Same content, different reference
+      });
+
+      // With shallow equality, same content should not cause re-render
+      // (depends on implementation)
+    });
+
+    it("should support custom equality", async () => {
+      const source$ = atom({ id: 1, name: "John" });
+      const { result } = renderHook(() =>
+        useValue(source$, (a, b) => a.id === b.id)
+      );
+
+      expect(result.current.name).toBe("John");
+
+      act(() => {
+        source$.set({ id: 1, name: "Jane" }); // Same id
+      });
+
+      // Custom equality by id - should not re-render
+    });
+  });
+
+  describe("context utilities", () => {
+    it("should support all() in selector", () => {
+      const a$ = atom(1);
+      const b$ = atom(2);
+      const c$ = atom(3);
+
+      const { result } = renderHook(() =>
+        useValue(({ all }) => {
+          const [a, b, c] = all(a$, b$, c$);
+          return a + b + c;
+        })
+      );
+
+      expect(result.current).toBe(6);
+    });
+  });
+
+  describe("cleanup", () => {
+    it("should unsubscribe on unmount", async () => {
+      const count$ = atom(0);
+      const { unmount } = renderHook(() => useValue(count$));
+
+      unmount();
+
+      // After unmount, setting the atom should not cause issues
+      act(() => {
+        count$.set(100);
+      });
+
+      // No error should be thrown
+    });
+  });
+
+  // Note: Async/Suspense tests require proper Suspense boundary setup
+  // which is more complex to test. The following are placeholder tests.
+
+  describe("async atoms", () => {
+    it("should throw promise for pending atom (Suspense)", () => {
+      // When an atom's value is a pending Promise, useValue should throw
+      // the Promise to trigger Suspense. This is hard to test without
+      // proper Suspense boundary setup.
+      // The hook will throw the Promise which is caught by Suspense
+      // Testing this properly requires a Suspense wrapper
+      expect(true).toBe(true); // Placeholder
+    });
+  });
+});