@livestore/react 0.2.0 → 0.3.0-dev.11

package/dist/useRcRef.js

@@ -0,0 +1,146 @@
+import * as React from 'react';
+/**
+ * Creates a reference-counted ref that is "stable" across React lifecycles.
+ *
+ * The hook is primarily intended for creating stateful objects or entities where
+ * reference identity is crucial (e.g. stateful objects, references, ...)
+ * needed to persist across multiple component instances. Instead of focusing on the cost of execution,
+ * its main goal is to ensure that the same instance is reused while there is at least one consumer,
+ * and properly disposed of only when no longer referenced.
+ *
+ * **Goals:**
+ * - Guarantee stable reference identity for stateful entities that are created via the `make` function.
+ * - Ensure that such state persists 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 `make` 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>(make: () => T, dispose: (resource: T) => void) => {
+ *         const val = React.useMemo(() => make(), [make])
+ *
+ *         React.useEffect(() => {
+ *           return () => {
+ *             dispose(val)
+ *           }
+ *         }, [dispose, val])
+
+ *         return val
+ *     }
+ *     ```
+ *
+ * **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 `make` 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 `make`
+ *   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 make 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, make, dispose, _options) => {
+    const keyRef = React.useRef(undefined);
+    const didDisposeInMemo = React.useRef(false);
+    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 = make();
+        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]);
+    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 __resetUseRcRefCache = () => {
+    cache.clear();
+};
+//# sourceMappingURL=useRcRef.js.map

package/dist/useRcRef.js.map

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

package/dist/useRcRef.test.d.ts

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

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

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

package/dist/useRcRef.test.js

@@ -0,0 +1,128 @@
+import * as ReactTesting from '@testing-library/react';
+import * as React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { __resetUseRcRefCache, useRcRef } from './useRcResource.js';
+describe.each([{ strictMode: true }, { strictMode: false }])('useRcRef (strictMode=%s)', ({ strictMode }) => {
+    beforeEach(() => {
+        __resetUseRcRefCache();
+    });
+    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(() => useRcRef('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 }) => useRcRef(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 }) => useRcRef(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(() => useRcRef('shared-key', makeSpy, cleanupSpy), {
+            wrapper,
+        });
+        const { unmount: unmount2, result } = ReactTesting.renderHook(() => useRcRef('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 }) => useRcRef(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=useRcRef.test.js.map

package/dist/useRcRef.test.js.map

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

package/dist/useRcResource.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 declare const useRcResource: <T>(key: string, create: () => T, dispose: (resource: NoInfer<T>) => void, _options?: {
+    debugPrint?: (resource: NoInfer<T>) => ReadonlyArray<any>;
+}) => any;
+export declare const __resetUseRcResourceCache: () => void;
+//# sourceMappingURL=useRcResource.d.ts.map

package/dist/useRcResource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRcResource.d.ts","sourceRoot":"","sources":["../src/useRcResource.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,OACxB,MAAM,UACH,MAAM,CAAC,WACN,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,aAC5B;IAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,GAAG,CAAC,CAAA;CAAE,QAkFzE,CAAA;AAkBD,eAAO,MAAM,yBAAyB,YAErC,CAAA"}

package/dist/useRcResource.js

@@ -0,0 +1,150 @@
+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);
+    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]);
+    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":""}