@perspective-ai/sdk-react 1.3.0 → 1.4.0-pr-25-20260306102715

package/src/hooks/useStableValue.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useStableValue } from "./useStableValue";
+
+describe("useStableValue", () => {
+  it("returns the same reference for deeply equal objects", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      { initialProps: { value: { a: 1, b: "test" } } }
+    );
+
+    const first = result.current;
+
+    rerender({ value: { a: 1, b: "test" } });
+
+    expect(result.current).toBe(first);
+  });
+
+  it("returns new reference when value changes", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      { initialProps: { value: { a: 1 } } }
+    );
+
+    const first = result.current;
+
+    rerender({ value: { a: 2 } });
+
+    expect(result.current).not.toBe(first);
+    expect(result.current).toEqual({ a: 2 });
+  });
+
+  it("ignores object key order differences", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      {
+        initialProps: {
+          value: {
+            dark: { secondary: "#222", primary: "#111" },
+            light: { secondary: "#eee", primary: "#fff" },
+          },
+        },
+      }
+    );
+
+    const first = result.current;
+
+    rerender({
+      value: {
+        light: { primary: "#fff", secondary: "#eee" },
+        dark: { primary: "#111", secondary: "#222" },
+      },
+    });
+
+    expect(result.current).toBe(first);
+  });
+
+  it("handles undefined values", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      {
+        initialProps: {
+          value: undefined as Record<string, unknown> | undefined,
+        },
+      }
+    );
+
+    expect(result.current).toBeUndefined();
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBeUndefined();
+  });
+
+  it("handles primitive values", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      { initialProps: { value: "hello" } }
+    );
+
+    const first = result.current;
+
+    rerender({ value: "hello" });
+    expect(result.current).toBe(first);
+
+    rerender({ value: "world" });
+    expect(result.current).toBe("world");
+  });
+
+  it("handles arrays with nested objects", () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useStableValue(value),
+      {
+        initialProps: {
+          value: [{ b: 2, a: 1 }, { items: ["x", "y"] }],
+        },
+      }
+    );
+
+    const first = result.current;
+
+    rerender({
+      value: [{ a: 1, b: 2 }, { items: ["x", "y"] }],
+    });
+
+    expect(result.current).toBe(first);
+  });
+});

package/src/hooks/useStableValue.ts

@@ -0,0 +1,34 @@
+import { useRef } from "react";
+
+function sortObjectKeys(value: unknown): unknown {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return Object.keys(value as Record<string, unknown>)
+      .sort()
+      .reduce<Record<string, unknown>>((result, key) => {
+        result[key] = (value as Record<string, unknown>)[key];
+        return result;
+      }, {});
+  }
+
+  return value;
+}
+
+/**
+ * Returns a referentially stable version of a value.
+ * Uses JSON serialization to detect deep equality changes.
+ * Useful for object/array deps in useEffect that are recreated each render.
+ */
+export function useStableValue<T>(value: T): T {
+  const ref = useRef(value);
+  const serialized = JSON.stringify(value, (_key, currentValue) =>
+    sortObjectKeys(currentValue)
+  );
+  const prevSerialized = useRef(serialized);
+
+  if (prevSerialized.current !== serialized) {
+    prevSerialized.current = serialized;
+    ref.current = value;
+  }
+
+  return ref.current;
+}