Add unwrap method for proxy edge cases

Author: markerikson

src/exports.ts

@@ -9,7 +9,7 @@ import shallowEqual from './utils/shallowEqual'
 
 import Provider from './components/Provider'
 import { defaultNoopBatch } from './utils/batch'
-import { SignalProvider, useSignalSelector } from './signals'
+import { SignalProvider, useSignalSelector, unwrap } from './signals'
 
 export { ReactReduxContext } from './components/Context'
 export type { ReactReduxContextValue } from './components/Context'
@@ -56,5 +56,6 @@ export {
   legacy_connect,
   shallowEqual,
   SignalProvider,
+  unwrap,
   useSignalSelector,
 }

src/index-rsc.ts

@@ -31,6 +31,7 @@ export {
   throwNotSupportedError as useSelector,
   throwNotSupportedError as useStore,
   throwNotSupportedError as SignalProvider,
+  throwNotSupportedError as unwrap,
   throwNotSupportedError as useSignalSelector,
 }
 export const ReactReduxContext = {} as any

src/signals/arrayMethodOverrides.ts

@@ -1,4 +1,4 @@
-import { getProxyTarget } from './trackingProxy'
+import { unwrap } from './trackingProxy'
 
 /**
  * Non-mutating array methods that we override on the tracking proxy.
@@ -147,7 +147,7 @@ export function createArrayMethodInterceptor(
     // so the comparison works against raw array elements.
     if (m === 'includes' || m === 'indexOf' || m === 'lastIndexOf') {
       const unwrappedArgs = args.map((arg, i) =>
-        i === 0 ? getProxyTarget(arg) : arg,
+        i === 0 ? unwrap(arg) : arg,
       )
       return (target as any)[m](...unwrappedArgs)
     }

src/signals/index.ts

@@ -18,6 +18,6 @@ export type {
 export { createPathSignalRegistry } from './pathSignalRegistry'
 export type { PathSignalRegistry } from './pathSignalRegistry'
 
-export { createTrackingProxy } from './trackingProxy'
+export { createTrackingProxy, unwrap } from './trackingProxy'
 
 export { diffAndUpdateSignals, reconcileState } from './diff'

src/signals/trackingProxy.ts

@@ -60,13 +60,28 @@ export function getProxyPath(value: unknown): string | undefined {
 
 /**
  * Get the raw target object from a tracking proxy, or the value itself if not a proxy.
- * Used to unwrap proxy arguments in array methods like includes/indexOf.
- * @param value - The value to unwrap
- * @returns The raw target object, or the original value if not a proxy
+ *
+ * Use this when you need identity comparison between values that may be
+ * tracking proxies. Since `proxy === rawObject` is always `false` in JS,
+ * unwrapping both sides allows correct identity checks:
+ *
+ * ```ts
+ * import { unwrap } from 'react-redux/signals'
+ *
+ * const selector = (state) => {
+ *   const current = unwrap(state.current)
+ *   return state.items.find(item => item === current)
+ * }
+ * ```
+ *
+ * Safe to call on non-proxy values — returns them unchanged.
+ *
+ * @param value - The value to unwrap (proxy or raw)
+ * @returns The raw target object, or the original value if not a tracking proxy
  */
-export function getProxyTarget(value: unknown): unknown {
+export function unwrap<T>(value: T): T {
   if (value !== null && typeof value === 'object') {
-    return proxyTargetMap.get(value) ?? value
+    return (proxyTargetMap.get(value as object) as T) ?? value
   }
   return value
 }

test/signals/trackingProxy.spec.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest'
-import { createTrackingProxy, getProxyPath } from '../../src/signals/trackingProxy'
+import { createTrackingProxy, getProxyPath, unwrap } from '../../src/signals/trackingProxy'
 import { createPathSignalRegistry } from '../../src/signals/pathSignalRegistry'
 import { alienEngine } from '../../src/signals/engine'
 import type { PathSignalRegistry } from '../../src/signals/pathSignalRegistry'
@@ -707,3 +707,108 @@ describe('createTrackingProxy', () => {
     scope.stop()
   })
 })
+
+describe('unwrap', () => {
+  function makeRegistry(): PathSignalRegistry {
+    return createPathSignalRegistry(alienEngine)
+  }
+
+  it('returns the raw target from a tracking proxy', () => {
+    const state = { name: 'Alice', nested: { x: 1 } }
+    const registry = makeRegistry()
+    const proxy = createTrackingProxy(state, '', registry, registry.proxyCache)
+
+    expect(unwrap(proxy)).toBe(state)
+  })
+
+  it('returns nested raw target from a child proxy', () => {
+    const state = { nested: { x: 1 } }
+    const registry = makeRegistry()
+    const proxy = createTrackingProxy(state, '', registry, registry.proxyCache)
+
+    const childProxy = proxy.nested
+    expect(childProxy).not.toBe(state.nested) // is a proxy
+    expect(unwrap(childProxy)).toBe(state.nested) // unwraps to raw
+  })
+
+  it('returns the value unchanged for non-proxy objects', () => {
+    const obj = { a: 1 }
+    expect(unwrap(obj)).toBe(obj)
+  })
+
+  it('returns primitives unchanged', () => {
+    expect(unwrap(42)).toBe(42)
+    expect(unwrap('hello')).toBe('hello')
+    expect(unwrap(true)).toBe(true)
+    expect(unwrap(null)).toBe(null)
+    expect(unwrap(undefined)).toBe(undefined)
+  })
+
+  it('enables identity comparison between unwrapped proxy and raw value', () => {
+    const item = { id: 1, name: 'first' }
+    const state = { items: [item], current: item }
+    const registry = makeRegistry()
+    const proxy = createTrackingProxy(state, '', registry, registry.proxyCache)
+
+    // Without unwrap: proxy !== raw
+    const proxiedCurrent = proxy.current
+    expect(proxiedCurrent === item).toBe(false)
+
+    // With unwrap: raw === raw
+    expect(unwrap(proxiedCurrent) === item).toBe(true)
+  })
+
+  it('indexOf/includes auto-unwrap proxy arguments', () => {
+    const state = {
+      items: [
+        { id: 1, name: 'a' },
+        { id: 2, name: 'b' },
+        { id: 3, name: 'c' },
+      ],
+    }
+    const registry = makeRegistry()
+    const proxy = createTrackingProxy(state, '', registry, registry.proxyCache)
+
+    // Access an item through the proxy — get back a proxy wrapper
+    const proxiedItem = proxy.items[1]
+    expect(proxiedItem).not.toBe(state.items[1]) // it's a proxy
+
+    // indexOf/includes auto-unwrap proxy args internally, so these just work
+    expect(proxy.items.indexOf(proxiedItem)).toBe(1)
+    expect(proxy.items.includes(proxiedItem)).toBe(true)
+
+    // Also works with manually unwrapped value
+    expect(proxy.items.indexOf(unwrap(proxiedItem))).toBe(1)
+  })
+
+  it('find() callback needs unwrap for identity comparison', () => {
+    const state = {
+      items: [
+        { id: 1, name: 'a' },
+        { id: 2, name: 'b' },
+        { id: 3, name: 'c' },
+      ],
+    }
+    const registry = makeRegistry()
+    const proxy = createTrackingProxy(state, '', registry, registry.proxyCache)
+
+    // Get a proxy-wrapped item
+    const proxiedItem = proxy.items[1]
+    const rawItem = unwrap(proxiedItem)
+
+    // find callback receives raw elements; unwrapped proxy === raw element
+    const found = proxy.items.find(
+      (item: { id: number; name: string }) => item === rawItem,
+    )
+
+    expect(found).toBeDefined()
+    // find() returns a proxied result (lazy signal registration)
+    expect(found).not.toBe(state.items[1])
+    expect(unwrap(found)).toBe(state.items[1])
+
+    // Accessing properties on the found proxy registers signals
+    const name = (found as { name: string }).name
+    expect(name).toBe('b')
+    expect(registry.has('items.{id:2}.name')).toBe(true)
+  })
+})