@livestore/react 0.3.0-dev.9 → 0.3.1-dev.0

package/dist/useRcResource.js

@@ -0,0 +1,152 @@
+import * as React from 'react';
+/**
+ * Creates a reference-counted resource object that is "stable" across React lifecycles.
+ *
+ * The hook is primarily intended for creating stateful objects or entities where:
+ * 1) reference identity is crucial (e.g. stateful objects, references, ...)
+ *    and needed to persist across multiple component instances
+ * 2) the `create`/`dispose` functions might be effectful and can be called exactly once per key
+ *
+ * **Goals:**
+ * - Guarantee stable reference identity for stateful entities that are created via the `create` function.
+ * - Strong guarantees about the `create`/`dispose` calls (i.e. exactly one `create`/`dispose` call per key)
+ * - Ensure that such state is retained across component re-mounts, even in development environments like
+ *   React Strict Mode or during Fast Refresh.
+ * - Automatically handle resource disposal by decrementing a reference count and disposing of the resource
+ *   when no components are using it.
+ *
+ * **Behavior:**
+ * - On the first render with a specific key, the `create` function is invoked to create the stateful entity,
+ *   and the resource is stored in a cache with a reference count set to 1.
+ * - If another component renders with the same key, the cached entity is reused and its reference count is incremented.
+ * - When a component renders with a new key, the previous key's reference count is decremented and, if it reaches zero,
+ *   the `dispose` function is called for that resource.
+ * - 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])
+ *
+ *     React.useEffect(() => {
+ *       return () => {
+ *         dispose(val)
+ *       }
+ *     }, [dispose, val])
+
+ *     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.
+ *
+ * **Usage:**
+ * ```tsx
+ * // Create a stateful object instance for a unique key and share it between components.
+ * const statefulObject = useRcResource(
+ *   'stable-object-key',
+ *   () => createObjectInstance(),
+ *   (object) => object.dispose()
+ * );
+ * ```
+ *
+ * **Caveats:**
+ * - The `create` function is intentionally omitted from the dependency array in `useMemo` to prevent
+ *   unintended re-creations of the stateful entity. Avoid closing over changing values within `create`
+ *   or include them in the `key`.
+ * - Ensure that the `dispose` function is stable or properly memoized as its reference is used in a `useEffect`.
+ * - Although the caching mechanism prevents duplicate instance creation for the same key, the strategy
+ *   can interact in unexpected ways with React’s development patterns. Please report any issues if encountered.
+ *
+ * @template T The type of the stateful entity managed by the hook.
+ * @param key A unique identifier for the stateful entity. A change in this key triggers a disposal of the previous resource.
+ * @param create Function to create the stateful entity when it does not exist in the cache.
+ * @param dispose Function to dispose of the stateful entity when it’s no longer needed. Needs to be stable.
+ * @param _options Optional. Additional options such as a debug print callback for logging purposes.
+ * @returns The stateful entity corresponding to the provided key.
+ */
+export const useRcResource = (key, create, dispose, _options) => {
+    const keyRef = React.useRef(undefined);
+    const didDisposeInMemo = React.useRef(false);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
+    const resource = React.useMemo(() => {
+        // console.debug('useMemo', key)
+        if (didDisposeInMemo.current) {
+            // console.debug('useMemo', key, 'skip')
+            const cachedItem = cache.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
+            const previousKey = keyRef.current;
+            const cachedItemForPreviousKey = cache.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' });
+                    didDisposeInMemo.current = true;
+                }
+            }
+        }
+        const cachedItem = cache.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 });
+        return resource;
+        // Dependency is deliberately limited to `key` to avoid unintended re-creations.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
+    React.useEffect(() => {
+        return () => {
+            if (didDisposeInMemo.current) {
+                // console.debug('unmount', keyRef.current, 'skip')
+                didDisposeInMemo.current = false;
+                return;
+            }
+            // console.debug('unmount', keyRef.current)
+            const cachedItem = cache.get(key);
+            // If the stateful resource is already cleaned up, do nothing.
+            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);
+            }
+        };
+        // We assume the `dispose` function is stable and won't change across renders
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    keyRef.current = key;
+    return resource;
+};
+// NOTE Given `useMemo` will be called multiple times (e.g. when using React Strict mode or Fast Refresh),
+// 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();
+export const __resetUseRcResourceCache = () => {
+    cache.clear();
+};
+//# sourceMappingURL=useRcResource.js.map

package/dist/useRcResource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRcResource.js","sourceRoot":"","sources":["../src/useRcResource.ts"],"names":[],"mappings":"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"}

package/dist/useRcResource.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=useRcResource.test.d.ts.map

package/dist/useRcResource.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRcResource.test.d.ts","sourceRoot":"","sources":["../src/useRcResource.test.tsx"],"names":[],"mappings":""}

package/dist/useRcResource.test.js

@@ -0,0 +1,122 @@
+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';
+describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (strictMode=%s)', ({ strictMode }) => {
+    beforeEach(() => {
+        __resetUseRcResourceCache();
+    });
+    const wrapper = strictMode ? React.StrictMode : React.Fragment;
+    it('should create a stateful entity using make and call cleanup on unmount', () => {
+        const makeSpy = vi.fn(() => Symbol('statefulResource'));
+        const cleanupSpy = vi.fn();
+        const { result, unmount } = ReactTesting.renderHook(() => useRcResource('key-1', makeSpy, cleanupSpy), { wrapper });
+        expect(makeSpy).toHaveBeenCalledTimes(1);
+        expect(result.current).toBeDefined();
+        expect(cleanupSpy).toHaveBeenCalledTimes(0);
+        unmount();
+        expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    });
+    it('should reuse the same entity when the key remains unchanged', () => {
+        const makeSpy = vi.fn(() => Symbol('statefulResource'));
+        const cleanupSpy = vi.fn();
+        const { result, rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(key, makeSpy, cleanupSpy), { initialProps: { key: 'consistent-key' }, wrapper });
+        const instance1 = result.current;
+        // Re-render with the same key
+        rerender({ key: 'consistent-key' });
+        const instance2 = result.current;
+        expect(instance1).toBe(instance2);
+        expect(makeSpy).toHaveBeenCalledTimes(1);
+        unmount();
+        expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    });
+    it('should dispose the previous instance when the key changes', () => {
+        const makeSpy = vi.fn(() => Symbol('statefulResource'));
+        const cleanupSpy = vi.fn();
+        const { result, rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(key, makeSpy, cleanupSpy), { initialProps: { key: 'a' }, wrapper });
+        const instanceA = result.current;
+        // Change the key; this should trigger the disposal of the 'a' instance
+        rerender({ key: 'b' });
+        const instanceB = result.current;
+        expect(instanceA).not.toBe(instanceB);
+        expect(makeSpy).toHaveBeenCalledTimes(2);
+        expect(cleanupSpy).toHaveBeenCalledTimes(1);
+        unmount();
+        expect(cleanupSpy).toHaveBeenCalledTimes(2);
+    });
+    it('should not dispose the entity until all consumers unmount', () => {
+        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,
+        });
+        const { unmount: unmount2, result } = ReactTesting.renderHook(() => useRcResource('shared-key', makeSpy, cleanupSpy), {
+            wrapper,
+        });
+        expect(result.current).toBeDefined();
+        expect(makeSpy).toHaveBeenCalledTimes(1);
+        // Unmount first consumer; the entity should remain active.
+        unmount1();
+        expect(cleanupSpy).not.toHaveBeenCalled();
+        // Unmount second consumer; now the entity is disposed.
+        unmount2();
+        expect(cleanupSpy).toHaveBeenCalledTimes(1);
+    });
+    it('should handle rapid key changes correctly', () => {
+        const makeSpy = vi.fn(() => Symbol('statefulResource'));
+        const cleanupSpy = vi.fn();
+        const { rerender, unmount } = ReactTesting.renderHook(({ key }) => useRcResource(key, makeSpy, cleanupSpy), {
+            initialProps: { key: '1' },
+            wrapper,
+        });
+        // Rapid sequence of key changes.
+        rerender({ key: '2' });
+        rerender({ key: '3' });
+        // Expect three creations: one each for keys '1', '2', '3'
+        expect(makeSpy).toHaveBeenCalledTimes(3);
+        // Cleanup should have been triggered for key '1' and key '2'
+        expect(cleanupSpy).toHaveBeenCalledTimes(2);
+        unmount();
+        // 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()
+//   })
+// })
+//# sourceMappingURL=useRcResource.test.js.map

package/dist/useRcResource.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRcResource.test.js","sourceRoot":"","sources":["../src/useRcResource.test.tsx"],"names":[],"mappings":"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"}

package/dist/useStore.d.ts

@@ -0,0 +1,9 @@
+import type { Store } from '@livestore/livestore';
+import type { ReactApi } from './LiveStoreContext.js';
+export declare const withReactApi: (store: Store) => Store & ReactApi;
+export declare const useStore: (options?: {
+    store?: Store;
+}) => {
+    store: Store & ReactApi;
+};
+//# sourceMappingURL=useStore.d.ts.map

package/dist/useStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.d.ts","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAKrD,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,KAAK,GAAG,QAQnD,CAAA;AAED,eAAO,MAAM,QAAQ,GAAI,UAAU;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,KAAG;IAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAA;CAiB/E,CAAA"}

package/dist/useStore.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import { LiveStoreContext } from './LiveStoreContext.js';
+import { useClientDocument } from './useClientDocument.js';
+import { useQuery } from './useQuery.js';
+export const withReactApi = (store) => {
+    // @ts-expect-error TODO properly implement this
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    store.useQuery = (queryDef) => useQuery(queryDef, { store });
+    // @ts-expect-error TODO properly implement this
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store });
+    return store;
+};
+export const useStore = (options) => {
+    if (options?.store !== undefined) {
+        return { store: withReactApi(options.store) };
+    }
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const storeContext = React.useContext(LiveStoreContext);
+    if (storeContext === undefined) {
+        throw new Error(`useStore can only be used inside StoreContext.Provider`);
+    }
+    if (storeContext.stage !== 'running') {
+        throw new Error(`useStore can only be used after the store is running`);
+    }
+    return { store: withReactApi(storeContext.store) };
+};
+//# sourceMappingURL=useStore.js.map

package/dist/useStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAY,EAAoB,EAAE;IAC7D,gDAAgD;IAChD,sDAAsD;IACtD,KAAK,CAAC,QAAQ,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5D,gDAAgD;IAChD,sDAAsD;IACtD,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACpH,OAAO,KAAyB,CAAA;AAClC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAA2B,EAA+B,EAAE;IACnF,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,sDAAsD;IACtD,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAEvD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,YAAY,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAA;AACpD,CAAC,CAAA"}

package/dist/utils/useStateRefWithReactiveInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStateRefWithReactiveInput.d.ts","sourceRoot":"","sources":["../../src/utils/useStateRefWithReactiveInput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,cAChC,CAAC,KACZ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAwB/D,CAAA"}
+{"version":3,"file":"useStateRefWithReactiveInput.d.ts","sourceRoot":"","sources":["../../src/utils/useStateRefWithReactiveInput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,EAC5C,YAAY,CAAC,KACZ,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAwB/D,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/react",
-  "version": "0.3.0-dev.9",
+  "version": "0.3.1-dev.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -23,25 +23,32 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/db-schema": "0.3.0-dev.9",
-    "@livestore/livestore": "0.3.0-dev.9",
-    "@livestore/utils": "0.3.0-dev.9",
-    "@livestore/common": "0.3.0-dev.9"
+    "@livestore/common": "0.3.1-dev.0",
+    "@livestore/utils": "0.3.1-dev.0",
+    "@livestore/livestore": "0.3.1-dev.0"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "^1.30.1",
-    "@testing-library/react": "^16.0.1",
-    "@types/react": "^19.0.8",
-    "@types/react-dom": "^19.0.3",
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.2.0",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.0.4",
     "jsdom": "^26.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-window": "^1.8.11",
-    "typescript": "^5.7.2",
-    "vite": "^6.0.11",
-    "vitest": "^2.1.4",
-    "@livestore/web": "0.3.0-dev.9"
+    "typescript": "^5.8.3",
+    "vite": "^6.3.4",
+    "vitest": "^3.1.2",
+    "@livestore/utils-dev": "0.3.1-dev.0",
+    "@livestore/adapter-web": "0.3.1-dev.0"
   },
+  "files": [
+    "package.json",
+    "src",
+    "dist"
+  ],
+  "license": "Apache-2.0",
   "peerDependencies": {
     "react": "~19.0.0"
   },

package/src/LiveStoreContext.ts

@@ -1,19 +1,14 @@
-import type { Store } from '@livestore/livestore'
-import type { LiveStoreContextRunning as LiveStoreContext_ } from '@livestore/livestore/effect'
-import React, { useContext } from 'react'
+import type { LiveStoreContextRunning } from '@livestore/livestore'
+import React from 'react'
 
-export const LiveStoreContext = React.createContext<LiveStoreContext_ | undefined>(undefined)
+import type { useClientDocument } from './useClientDocument.js'
+import type { useQuery } from './useQuery.js'
 
-export const useStore = (): { store: Store } => {
-  const storeContext = useContext(LiveStoreContext)
-
-  if (storeContext === undefined) {
-    throw new Error(`useStore can only be used inside StoreContext.Provider`)
-  }
-
-  if (storeContext.stage !== 'running') {
-    throw new Error(`useStore can only be used after the store is running`)
-  }
-
-  return storeContext
+export type ReactApi = {
+  useQuery: typeof useQuery
+  useClientDocument: typeof useClientDocument
 }
+
+export const LiveStoreContext = React.createContext<
+  { stage: 'running'; store: LiveStoreContextRunning['store'] & ReactApi } | undefined
+>(undefined)