react-jitter 0.3.1 → 0.5.0

package/README.md

@@ -128,6 +128,44 @@ window.reactJitter.onRender = (render) => {
 
 Modern bundlers will tree-shake the `import` and the function call from your production build, so it will have zero performance impact.
 
+### Advanced: Custom Comparator Selection
+
+By default, React Jitter uses the `deepEqual` comparator to detect changes in hook values. However, you can customize which comparator is used on a per-hook basis using the `selectComparator` function. This is useful when dealing with circular data structures or when you need different comparison strategies for different hooks.
+
+```js
+// Set a custom comparator selector
+window.reactJitter.selectComparator = (hookAddress) => {
+  // Use circularDeepEqual for hooks that might return circular structures
+  if (hookAddress.hook === 'useSelector' || hookAddress.hook === 'useReduxState') {
+    return 'circularDeepEqual';
+  }
+  
+  // Use deepEqual for everything else (default)
+  return 'deepEqual';
+};
+```
+
+The `hookAddress` parameter contains information about the hook:
+
+```typescript
+{
+  hook: string;        // Hook name, e.g., "useState", "useContext"
+  file: string;        // File path where the hook is called
+  line: number;        // Line number
+  offset: number;      // Column offset
+  arguments?: string[]; // Hook arguments (if includeArguments is enabled)
+}
+```
+
+**Available Comparators:**
+
+- `deepEqual` (default): Fast deep equality check that handles most cases. Will throw an error if it encounters deeply nested or circular structures.
+- `circularDeepEqual`: Slower but handles circular references safely. Use this when your hooks return data with circular dependencies or extremely deep nesting.
+
+**When to Use `circularDeepEqual`:**
+
+If you see an error like "Maximum call stack size exceeded. Please use the 'circularDeepEqual' comparator", you should configure `selectComparator` to return `'circularDeepEqual'` for the specific hook mentioned in the error message.
+
 ## API and Configuration
 
 The `reactJitter` function accepts a configuration object with two callbacks: `onHookChange` and `onRender`.
@@ -218,6 +256,33 @@ Here is an example of the `change` object when `includeArguments` is enabled:
 
 In this example, the `arguments` field shows that the `UserContext` was used, and the `changedKeys` field shows that the `user` property has changed.
 
+### Detecting Unstable Hooks in Unit Tests
+
+React Jitter can also be a powerful tool for improving code quality within your unit tests.
+
+You can leverage this to write tests that fail if a hook becomes unstable, catching performance regressions early in the a testing setup where you might initialize React Jitter in a global setup file, you can easily override the `onHookChange` handler on a per-test basis.
+
+```javascript
+// Example of a Vitest/Jest test
+it('should not have unstable hooks', () => {
+  const unstableChanges = [];
+  // Initialize React Jitter in a global setup file (e.g., setupTests.js)
+  // Then, override the onHookChange handler for specific tests.
+  window.reactJitter.onHookChange = (change) => {
+    // You can ignore mocked hooks or handle them specifically
+    if (change.unstable && !change.isMocked) {
+      unstableChanges.push(change);
+    }
+  };
+
+  render(<MyComponent />);
+
+  // Assert that no unstable values were detected during the render
+  expect(unstableChanges).toHaveLength(0);
+});
+```
+
+The `onHookChange` callback's `change` object includes an `isMocked` boolean property. This is automatically set to `true` if React Jitter detects that the hook has been mocked (e.g., using `jest.fn()` or `vi.fn()`). This allows you to reliably identify and assert against unstable values in your test environment.
 
 ## How It Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-jitter",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "A developer tool for debugging React performance issues caused by hook changes and component re-renders.",
   "exports": {
     ".": {

package/runtime/dist/index.d.mts

@@ -40,7 +40,9 @@ type HookEndEvent = {
     line: number;
     offset: number;
     arguments?: string[];
+    isMocked?: boolean;
 };
+type HookAddress = Pick<HookEndEvent, 'hook' | 'file' | 'line' | 'offset' | 'arguments'>;
 type ReactJitterOptions = {
     enabled?: boolean;
     onHookChange?: (change: HookChange) => void;
@@ -51,6 +53,7 @@ type ReactJitterOptions = {
     }) => void;
 };
 type Scope = z.infer<typeof ScopeSchema>;
+type Comparator = 'deepEqual' | 'circularDeepEqual';
 
 type HookCall = HookChange & HookEndEvent & {
     scope: Scope;
@@ -62,6 +65,7 @@ declare global {
         reactJitter?: {
             enabled?: boolean;
             onHookChange?: (change: HookCall) => void;
+            selectComparator?: (hookAddress: HookAddress) => Comparator;
             onRender?: (scope: Scope & {
                 hookResults: Record<string, unknown>;
                 renderCount: number;
@@ -79,6 +83,7 @@ declare function useJitterScope(scope: Scope): {
     s: (id: string) => void;
     e: (hookResult: unknown, hookEndEvent: HookEndEvent) => unknown;
     re: <T>(renderResult: T) => T;
+    m: (value: unknown) => boolean;
 };
 declare function reactJitter(options: ReactJitterOptions): void;
 

package/runtime/dist/index.d.ts

@@ -40,7 +40,9 @@ type HookEndEvent = {
     line: number;
     offset: number;
     arguments?: string[];
+    isMocked?: boolean;
 };
+type HookAddress = Pick<HookEndEvent, 'hook' | 'file' | 'line' | 'offset' | 'arguments'>;
 type ReactJitterOptions = {
     enabled?: boolean;
     onHookChange?: (change: HookChange) => void;
@@ -51,6 +53,7 @@ type ReactJitterOptions = {
     }) => void;
 };
 type Scope = z.infer<typeof ScopeSchema>;
+type Comparator = 'deepEqual' | 'circularDeepEqual';
 
 type HookCall = HookChange & HookEndEvent & {
     scope: Scope;
@@ -62,6 +65,7 @@ declare global {
         reactJitter?: {
             enabled?: boolean;
             onHookChange?: (change: HookCall) => void;
+            selectComparator?: (hookAddress: HookAddress) => Comparator;
             onRender?: (scope: Scope & {
                 hookResults: Record<string, unknown>;
                 renderCount: number;
@@ -79,6 +83,7 @@ declare function useJitterScope(scope: Scope): {
     s: (id: string) => void;
     e: (hookResult: unknown, hookEndEvent: HookEndEvent) => unknown;
     re: <T>(renderResult: T) => T;
+    m: (value: unknown) => boolean;
 };
 declare function reactJitter(options: ReactJitterOptions): void;
 

package/runtime/dist/index.js

@@ -447,7 +447,8 @@ function createCustomEqual(options) {
 }
 
 // src/utils/getChanges.ts
-function getChanges(prev, next) {
+function getChanges(prev, next, comparator = "deepEqual") {
+  const equals = comparator === "circularDeepEqual" ? circularDeepEqual : deepEqual;
   const changedKeys = [];
   const unstableKeys = [];
   const isObject = (v) => v !== null && typeof v === "object";
@@ -466,7 +467,7 @@ function getChanges(prev, next) {
     }
     const max = Math.max(prev.length, next.length);
     for (let i = 0; i < max; i++) {
-      const deepEqItem = deepEqual(prev[i], next[i]);
+      const deepEqItem = equals(prev[i], next[i]);
       const refDiffItem = isObject(prev[i]) && isObject(next[i]) && prev[i] !== next[i];
       if (!deepEqItem || refDiffItem) {
         const key = String(i);
@@ -479,7 +480,7 @@ function getChanges(prev, next) {
   } else if (isObject(prev) && isObject(next)) {
     const allKeys = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
     for (const key of allKeys) {
-      const deepEqProp = deepEqual(prev[key], next[key]);
+      const deepEqProp = equals(prev[key], next[key]);
       const refDiffProp = isObject(prev[key]) && isObject(next[key]) && prev[key] !== next[key];
       if (!deepEqProp || refDiffProp) {
         changedKeys.push(key);
@@ -489,7 +490,7 @@ function getChanges(prev, next) {
       }
     }
   } else {
-    const deepEqRoot = deepEqual(prev, next);
+    const deepEqRoot = equals(prev, next);
     const refDiffRoot = isObject(prev) && isObject(next) && prev !== next;
     const unstable = refDiffRoot && deepEqRoot;
     const changed = !deepEqRoot || refDiffRoot;
@@ -500,7 +501,7 @@ function getChanges(prev, next) {
     };
   }
   const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && deepEqual(prev, next);
+  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && equals(prev, next);
   if (unstableRoot && changedKeys.length === 0) {
     changedKeys.push("");
     unstableKeys.push("");
@@ -512,6 +513,31 @@ function getChanges(prev, next) {
   };
 }
 
+// src/utils/compareChanges.ts
+function compareChanges(hookAddress, prev, current) {
+  var _a, _b, _c;
+  if (prev !== "undefined" && prev !== current) {
+    const comparator = (_c = (_b = (_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.selectComparator) == null ? void 0 : _b.call(_a, hookAddress)) != null ? _c : "deepEqual";
+    try {
+      return getChanges(prev, current, comparator);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isRecursionError = /(?:maximum call stack(?: size)? exceeded|too much recursion|stack overflow)/i.test(
+        errorMessage
+      );
+      if (isRecursionError && comparator !== "circularDeepEqual") {
+        throw new Error(
+          `Maximum call stack size exceeded. Please use the "circularDeepEqual" comparator with selectComparator option. 
+Hook address: ${JSON.stringify(hookAddress, null, 2)}.`,
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+  return null;
+}
+
 // src/index.ts
 var scopes = {};
 var hookStack = /* @__PURE__ */ new Map();
@@ -544,7 +570,13 @@ function useJitterScope(scope) {
         const hookId = `${scopeId}-${hookEndEvent.id}`;
         if (shouldReportChanges()) {
           const prevResult = currentScope.hookResults[hookId];
-          const changes = compareChanges(prevResult, hookResult);
+          const hookAddress = {
+            hook: hookEndEvent.hook,
+            file: hookEndEvent.file,
+            line: hookEndEvent.line,
+            offset: hookEndEvent.offset
+          };
+          const changes = compareChanges(hookAddress, prevResult, hookResult);
           if (changes) {
             const hookCall = {
               hook: hookEndEvent.hook,
@@ -560,6 +592,9 @@ function useJitterScope(scope) {
             if (hookEndEvent.arguments) {
               hookCall.arguments = hookEndEvent.arguments;
             }
+            if (hookEndEvent.isMocked) {
+              hookCall.isMocked = hookEndEvent.isMocked;
+            }
             scopes[scopeId].hookChanges.push(hookCall);
             callOnHookChange(hookCall);
           }
@@ -571,6 +606,12 @@ function useJitterScope(scope) {
       re: (renderResult) => {
         callOnRender(scopes[scopeId]);
         return renderResult;
+      },
+      m: (value) => {
+        if (typeof value !== "function") {
+          return false;
+        }
+        return "mockImplementation" in value || "mockReturnValue" in value;
       }
     };
   }
@@ -621,12 +662,6 @@ function getScopeCount(scope) {
   }
   return scopeCounter[scope.id]++;
 }
-function compareChanges(prev, current) {
-  if (prev !== "undefined" && prev !== current) {
-    return getChanges(prev, current);
-  }
-  return null;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   reactJitter,

package/runtime/dist/index.mjs

@@ -412,7 +412,8 @@ function createCustomEqual(options) {
 }
 
 // src/utils/getChanges.ts
-function getChanges(prev, next) {
+function getChanges(prev, next, comparator = "deepEqual") {
+  const equals = comparator === "circularDeepEqual" ? circularDeepEqual : deepEqual;
   const changedKeys = [];
   const unstableKeys = [];
   const isObject = (v) => v !== null && typeof v === "object";
@@ -431,7 +432,7 @@ function getChanges(prev, next) {
     }
     const max = Math.max(prev.length, next.length);
     for (let i = 0; i < max; i++) {
-      const deepEqItem = deepEqual(prev[i], next[i]);
+      const deepEqItem = equals(prev[i], next[i]);
       const refDiffItem = isObject(prev[i]) && isObject(next[i]) && prev[i] !== next[i];
       if (!deepEqItem || refDiffItem) {
         const key = String(i);
@@ -444,7 +445,7 @@ function getChanges(prev, next) {
   } else if (isObject(prev) && isObject(next)) {
     const allKeys = /* @__PURE__ */ new Set([...Object.keys(prev), ...Object.keys(next)]);
     for (const key of allKeys) {
-      const deepEqProp = deepEqual(prev[key], next[key]);
+      const deepEqProp = equals(prev[key], next[key]);
       const refDiffProp = isObject(prev[key]) && isObject(next[key]) && prev[key] !== next[key];
       if (!deepEqProp || refDiffProp) {
         changedKeys.push(key);
@@ -454,7 +455,7 @@ function getChanges(prev, next) {
       }
     }
   } else {
-    const deepEqRoot = deepEqual(prev, next);
+    const deepEqRoot = equals(prev, next);
     const refDiffRoot = isObject(prev) && isObject(next) && prev !== next;
     const unstable = refDiffRoot && deepEqRoot;
     const changed = !deepEqRoot || refDiffRoot;
@@ -465,7 +466,7 @@ function getChanges(prev, next) {
     };
   }
   const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && deepEqual(prev, next);
+  const unstableRoot = isPlainObject(prev) && isPlainObject(next) && prev !== next && equals(prev, next);
   if (unstableRoot && changedKeys.length === 0) {
     changedKeys.push("");
     unstableKeys.push("");
@@ -477,6 +478,31 @@ function getChanges(prev, next) {
   };
 }
 
+// src/utils/compareChanges.ts
+function compareChanges(hookAddress, prev, current) {
+  var _a, _b, _c;
+  if (prev !== "undefined" && prev !== current) {
+    const comparator = (_c = (_b = (_a = window == null ? void 0 : window.reactJitter) == null ? void 0 : _a.selectComparator) == null ? void 0 : _b.call(_a, hookAddress)) != null ? _c : "deepEqual";
+    try {
+      return getChanges(prev, current, comparator);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isRecursionError = /(?:maximum call stack(?: size)? exceeded|too much recursion|stack overflow)/i.test(
+        errorMessage
+      );
+      if (isRecursionError && comparator !== "circularDeepEqual") {
+        throw new Error(
+          `Maximum call stack size exceeded. Please use the "circularDeepEqual" comparator with selectComparator option. 
+Hook address: ${JSON.stringify(hookAddress, null, 2)}.`,
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+  return null;
+}
+
 // src/index.ts
 var scopes = {};
 var hookStack = /* @__PURE__ */ new Map();
@@ -509,7 +535,13 @@ function useJitterScope(scope) {
         const hookId = `${scopeId}-${hookEndEvent.id}`;
         if (shouldReportChanges()) {
           const prevResult = currentScope.hookResults[hookId];
-          const changes = compareChanges(prevResult, hookResult);
+          const hookAddress = {
+            hook: hookEndEvent.hook,
+            file: hookEndEvent.file,
+            line: hookEndEvent.line,
+            offset: hookEndEvent.offset
+          };
+          const changes = compareChanges(hookAddress, prevResult, hookResult);
           if (changes) {
             const hookCall = {
               hook: hookEndEvent.hook,
@@ -525,6 +557,9 @@ function useJitterScope(scope) {
             if (hookEndEvent.arguments) {
               hookCall.arguments = hookEndEvent.arguments;
             }
+            if (hookEndEvent.isMocked) {
+              hookCall.isMocked = hookEndEvent.isMocked;
+            }
             scopes[scopeId].hookChanges.push(hookCall);
             callOnHookChange(hookCall);
           }
@@ -536,6 +571,12 @@ function useJitterScope(scope) {
       re: (renderResult) => {
         callOnRender(scopes[scopeId]);
         return renderResult;
+      },
+      m: (value) => {
+        if (typeof value !== "function") {
+          return false;
+        }
+        return "mockImplementation" in value || "mockReturnValue" in value;
       }
     };
   }
@@ -586,12 +627,6 @@ function getScopeCount(scope) {
   }
   return scopeCounter[scope.id]++;
 }
-function compareChanges(prev, current) {
-  if (prev !== "undefined" && prev !== current) {
-    return getChanges(prev, current);
-  }
-  return null;
-}
 export {
   reactJitter,
   useJitterScope