@livestore/react 0.4.0-dev.9 → 0.5.0-dev.0

package/src/useRcResource.test.tsx

@@ -2,20 +2,24 @@ import * as ReactTesting from '@testing-library/react'
 import * as React from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { __resetUseRcResourceCache, useRcResource } from './useRcResource.js'
+import { __resetUseRcResourceCache, useRcResource } from './useRcResource.ts'
 
+/** Verifies: LS.SYS.INT.REACT-R03, LS.SYS.INT.REACT-R05 */
 describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (strictMode=%s)', ({ strictMode }) => {
   beforeEach(() => {
     __resetUseRcResourceCache()
   })
 
-  const wrapper = strictMode ? React.StrictMode : React.Fragment
+  const wrapper = strictMode === true ? React.StrictMode : React.Fragment
 
   it('should create a stateful entity using make and call cleanup on unmount', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    const { result, unmount } = ReactTesting.renderHook(() => useRcResource('key-1', makeSpy, cleanupSpy), { wrapper })
+    const { result, unmount } = ReactTesting.renderHook(() => useRcResource(scope, 'key-1', makeSpy, cleanupSpy), {
+      wrapper,
+    })
 
     expect(makeSpy).toHaveBeenCalledTimes(1)
     expect(result.current).toBeDefined()
@@ -26,11 +30,12 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should reuse the same entity when the key remains unchanged', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
     const { result, rerender, unmount } = ReactTesting.renderHook(
-      ({ key }) => useRcResource(key, makeSpy, cleanupSpy),
+      ({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy),
       { initialProps: { key: 'consistent-key' }, wrapper },
     )
 
@@ -48,11 +53,12 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should dispose the previous instance when the key changes', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
     const { result, rerender, unmount } = ReactTesting.renderHook(
-      ({ key }) => useRcResource(key, makeSpy, cleanupSpy),
+      ({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy),
       { initialProps: { key: 'a' }, wrapper },
     )
 
@@ -71,18 +77,18 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should not dispose the entity until all consumers unmount', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    // Simulate two consumers using the same key independently.
-    const { unmount: unmount1 } = ReactTesting.renderHook(() => useRcResource('shared-key', makeSpy, cleanupSpy), {
-      wrapper,
-    })
+    // Simulate two consumers using the same (scope, key) pair independently.
+    const { unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
     const { unmount: unmount2, result } = ReactTesting.renderHook(
-      () => useRcResource('shared-key', makeSpy, cleanupSpy),
-      {
-        wrapper,
-      },
+      () => useRcResource(scope, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
     )
 
     expect(result.current).toBeDefined()
@@ -98,10 +104,11 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
   })
 
   it('should handle rapid key changes correctly', () => {
+    const scope = {}
     const makeSpy = vi.fn(() => Symbol('statefulResource'))
     const cleanupSpy = vi.fn()
 
-    const { rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(key, makeSpy, cleanupSpy), {
+    const { rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(scope, key, makeSpy, cleanupSpy), {
       initialProps: { key: '1' },
       wrapper,
     })
@@ -119,49 +126,99 @@ describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (str
     // Unmounting the final consumer disposes the key '3' instance.
     expect(cleanupSpy).toHaveBeenCalledTimes(3)
   })
-})
 
-// This code was useful to better understand the hook behaviour with and without strict mode
-// describe('debug', () => {
-//  const useStrictTest = (key: string) => {
-//   const id = React.useId()
-//   console.log(key, 'id', id)
-
-//   const x = React.useMemo(() => {
-//     console.log('useMemo', key)
-//     return 'hi' + key
-//   }, [key])
-
-//   React.useEffect(() => {
-//     console.log('useEffect', key)
-//     return () => {
-//       console.log('unmount', key)
-//     }
-//   }, [])
-
-//   return x
-// }
-
-//   it('strict mode component', () => {
-//     console.log('strict mode component')
-//     const Root = () => {
-//       useStrictTest('a')
-//       return null
-//     }
-//     const { unmount } = ReactTesting.render(
-//       <React.StrictMode>
-//         <Root />
-//       </React.StrictMode>,
-//     )
-
-//     unmount()
-//   })
-
-//   it('strict mode hook', () => {
-//     console.log('strict mode hook')
-//     const wrapper: React.FC<{ children: React.ReactNode }> = React.StrictMode
-//     const { unmount } = ReactTesting.renderHook(() => useStrictTest('b'), { wrapper })
-
-//     unmount()
-//   })
-// })
+  it('should isolate entities created with the same key but different scopes', () => {
+    const scopeA = { tag: 'A' }
+    const scopeB = { tag: 'B' }
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result: resultA } = ReactTesting.renderHook(
+      () => useRcResource(scopeA, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const { result: resultB } = ReactTesting.renderHook(
+      () => useRcResource(scopeB, 'shared-key', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(resultA.current).not.toBe(resultB.current)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should dispose the previous entity when the scope changes (key unchanged)', () => {
+    const scopeA = { tag: 'A' }
+    const scopeB = { tag: 'B' }
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result, rerender, unmount } = ReactTesting.renderHook(
+      ({ scope }) => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { initialProps: { scope: scopeA }, wrapper },
+    )
+
+    const instanceA = result.current
+    expect(makeSpy).toHaveBeenCalledTimes(1)
+
+    rerender({ scope: scopeB })
+    const instanceB = result.current
+
+    expect(instanceA).not.toBe(instanceB)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+    // The scopeA entry's last consumer left when we switched scopes → cleaned up.
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+
+    unmount()
+    expect(cleanupSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should not reuse a cached entity after the scope is replaced', () => {
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const scope1 = {}
+    const { result: result1, unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope1, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const instance1 = result1.current
+    unmount1()
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+
+    // Fresh scope, same string key — must NOT reuse the (already-disposed) entry.
+    const scope2 = {}
+    const { result: result2, unmount: unmount2 } = ReactTesting.renderHook(
+      () => useRcResource(scope2, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(result2.current).not.toBe(instance1)
+    expect(makeSpy).toHaveBeenCalledTimes(2)
+
+    unmount2()
+    expect(cleanupSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('should share the entity across components within the same scope', () => {
+    const scope = {}
+    const makeSpy = vi.fn(() => Symbol('statefulResource'))
+    const cleanupSpy = vi.fn()
+
+    const { result: r1, unmount: unmount1 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+    const { result: r2, unmount: unmount2 } = ReactTesting.renderHook(
+      () => useRcResource(scope, 'k', makeSpy, cleanupSpy),
+      { wrapper },
+    )
+
+    expect(r1.current).toBe(r2.current)
+    expect(makeSpy).toHaveBeenCalledTimes(1)
+
+    unmount1()
+    expect(cleanupSpy).not.toHaveBeenCalled()
+    unmount2()
+    expect(cleanupSpy).toHaveBeenCalledTimes(1)
+  })
+})

package/src/useRcResource.ts

@@ -25,10 +25,10 @@ import * as React from 'react'
  * - Upon component unmount, the reference count is decremented, leading to disposal (via the `dispose` function)
  *   if the reference count drops to zero. An unmount is either detected via React's `useEffect` callback or
  *   in the useMemo hook when the key changes.
- * 
+ *
  * Why this is needed in LiveStore:
  * Let's first take a look at the "trivial implementation":
- * 
+ *
  * ```ts
  * const useSimpleResource = <T>(create: () => T, dispose: (resource: T) => void) => {
  *     const val = React.useMemo(() => create(), [create])
@@ -42,7 +42,7 @@ import * as React from 'react'
  *     return val
  * }
  * ```
- * 
+ *
  * LiveStore uses this hook to create LiveQuery instances which are stateful and must not be leaked.
  * The simple implementation above would leak the LiveQuery instance if the component is unmounted or props change.
  *
@@ -72,87 +72,87 @@ import * as React from 'react'
  * @returns The stateful entity corresponding to the provided key.
  */
 export const useRcResource = <T>(
+  scope: object,
   key: string,
   create: () => T,
   dispose: (resource: NoInfer<T>) => void,
   _options?: { debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<any> },
 ): T => {
   const keyRef = React.useRef<string | undefined>(undefined)
+  const scopeRef = React.useRef<object | undefined>(undefined)
   const didDisposeInMemo = React.useRef(false)
+  const createRef = React.useRef(create)
+  const disposeRef = React.useRef(dispose)
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: Dependency is deliberately limited to `key` to avoid unintended re-creations.
+  createRef.current = create
+  disposeRef.current = dispose
+
+  // oxlint-disable-next-line react/exhaustive-deps -- dependencies are deliberately limited to `scope` and `key` to avoid unintended re-creations
   const resource = React.useMemo(() => {
-    // console.debug('useMemo', key)
-    if (didDisposeInMemo.current) {
-      // console.debug('useMemo', key, 'skip')
-      const cachedItem = cache.get(key)
+    const bucket = getBucket(scope)
+
+    if (didDisposeInMemo.current === true) {
+      const cachedItem = bucket.get(key)
       if (cachedItem !== undefined && cachedItem._tag === 'active') {
         return cachedItem.resource
       }
     }
 
-    // Check if the key has changed (or is undefined)
-    if (keyRef.current !== undefined && keyRef.current !== key) {
-      // If the key has changed, decrement the reference on the previous key
+    // Check if the (scope, key) pair has changed (or is undefined)
+    if (keyRef.current !== undefined && (keyRef.current !== key || scopeRef.current !== scope)) {
       const previousKey = keyRef.current
-      const cachedItemForPreviousKey = cache.get(previousKey)
+      // scopeRef.current is set together with keyRef.current below, so it's defined here.
+      const previousBucket = getBucket(scopeRef.current!)
+      const cachedItemForPreviousKey = previousBucket.get(previousKey)
       if (cachedItemForPreviousKey !== undefined && cachedItemForPreviousKey._tag === 'active') {
-        // previousKeyRef.current = previousKey
         cachedItemForPreviousKey.rc--
 
-        // console.debug('useMemo', key, 'rc--', previousKey, cachedItemForPreviousKey.rc)
-
         if (cachedItemForPreviousKey.rc === 0) {
           // Clean up the stateful resource if no longer referenced
-          dispose(cachedItemForPreviousKey.resource)
-          cache.set(previousKey, { _tag: 'destroyed' })
+          disposeRef.current(cachedItemForPreviousKey.resource)
+          previousBucket.set(previousKey, { _tag: 'destroyed' })
           didDisposeInMemo.current = true
         }
       }
     }
 
-    const cachedItem = cache.get(key)
+    const cachedItem = bucket.get(key)
     if (cachedItem !== undefined && cachedItem._tag === 'active') {
       // In React Strict Mode, the `useMemo` hook is called multiple times,
       // so we only increment the reference from the first call for this component.
       cachedItem.rc++
-      // console.debug('rc++', cachedItem.rc, ...(_options?.debugPrint?.(cachedItem.resource) ?? []))
-
       return cachedItem.resource
     }
 
     // Create a new stateful resource if not cached
-    const resource = create()
-    cache.set(key, { _tag: 'active', rc: 1, resource })
+    const resource = createRef.current()
+    bucket.set(key, { _tag: 'active', rc: 1, resource })
     return resource
-  }, [key])
+  }, [scope, key])
 
-  // biome-ignore lint/correctness/useExhaustiveDependencies: We assume the `dispose` function is stable and won't change across renders
+  // oxlint-disable-next-line react/exhaustive-deps -- `disposeRef` keeps the latest dispose function without re-running cleanup
   React.useEffect(() => {
     return () => {
-      if (didDisposeInMemo.current) {
-        // console.debug('unmount', keyRef.current, 'skip')
+      if (didDisposeInMemo.current === true) {
         didDisposeInMemo.current = false
         return
       }
 
-      // console.debug('unmount', keyRef.current)
-      const cachedItem = cache.get(key)
-      // If the stateful resource is already cleaned up, do nothing.
+      const bucket = getBucket(scope)
+      const cachedItem = bucket.get(key)
       if (cachedItem === undefined || cachedItem._tag === 'destroyed') return
 
       cachedItem.rc--
 
-      // console.debug('rc--', cachedItem.rc, ...(_options?.debugPrint?.(cachedItem.resource) ?? []))
-
       if (cachedItem.rc === 0) {
-        dispose(cachedItem.resource)
-        cache.delete(key)
+        disposeRef.current(cachedItem.resource)
+        bucket.delete(key)
       }
     }
-  }, [key])
+  }, [scope, key])
 
   keyRef.current = key
+  scopeRef.current = scope
 
   return resource
 }
@@ -161,8 +161,7 @@ export const useRcResource = <T>(
 // we are using this cache to avoid starting multiple queries/spans for the same component.
 // This is somewhat against some recommended React best practices, but it should be fine in our case below.
 // Please definitely open an issue if you see or run into any problems with this approach!
-const cache = new Map<
-  string,
+type Entry =
   | {
       _tag: 'active'
       rc: number
@@ -171,8 +170,23 @@ const cache = new Map<
   | {
       _tag: 'destroyed'
     }
->()
+
+type Bucket = Map<string, Entry>
+
+// Per-scope buckets. Keying by the scope object (e.g. a Store instance) ensures that
+// when the scope is replaced (store dispose/recreate), the new scope gets a fresh bucket
+// and stale entries from the disposed scope become GC-eligible. See issue #1186.
+let scopedBuckets = new WeakMap<object, Bucket>()
+
+const getBucket = (scope: object): Bucket => {
+  let bucket = scopedBuckets.get(scope)
+  if (bucket === undefined) {
+    bucket = new Map()
+    scopedBuckets.set(scope, bucket)
+  }
+  return bucket
+}
 
 export const __resetUseRcResourceCache = () => {
-  cache.clear()
+  scopedBuckets = new WeakMap()
 }