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

package/src/useRcResource.test.tsx

@@ -0,0 +1,167 @@
+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()
+//   })
+// })

package/src/useRcResource.ts

@@ -0,0 +1,182 @@
+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 = <T>(
+  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 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<
+  string,
+  | {
+      _tag: 'active'
+      rc: number
+      resource: any
+    }
+  | {
+      _tag: 'destroyed'
+    }
+>()
+
+export const __resetUseRcResourceCache = () => {
+  cache.clear()
+}

package/src/useStore.ts

@@ -0,0 +1,36 @@
+import type { Store } from '@livestore/livestore'
+import React from 'react'
+
+import type { ReactApi } from './LiveStoreContext.js'
+import { LiveStoreContext } from './LiveStoreContext.js'
+import { useClientDocument } from './useClientDocument.js'
+import { useQuery } from './useQuery.js'
+
+export const withReactApi = (store: Store): Store & ReactApi => {
+  // @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 as Store & ReactApi
+}
+
+export const useStore = (options?: { store?: Store }): { store: Store & ReactApi } => {
+  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) }
+}

package/dist/useAtom.d.ts

@@ -1,5 +0,0 @@
-import type { QueryInfo } from '@livestore/common';
-import type { LiveQuery } from '@livestore/livestore';
-import type { Dispatch, SetStateAction } from './useRow.js';
-export declare const useAtom: <TQuery extends LiveQuery<any, QueryInfo.Row | QueryInfo.Col>>(query$: TQuery) => [value: TQuery["__result!"], setValue: Dispatch<SetStateAction<Partial<TQuery["__result!"]>>>];
-//# sourceMappingURL=useAtom.d.ts.map

package/dist/useAtom.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useAtom.d.ts","sourceRoot":"","sources":["../src/useAtom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAG5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAKrD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE3D,eAAO,MAAM,OAAO,GAElB,MAAM,SAAS,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,UAEpD,MAAM,KACb,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAoC/F,CAAA"}

package/dist/useAtom.js

@@ -1,38 +0,0 @@
-import React from 'react';
-import { useStore } from './LiveStoreContext.js';
-import { useQueryRef } from './useQuery.js';
-export const useAtom = (query$) => {
-    const query$Ref = useQueryRef(query$);
-    const { store } = useStore();
-    // TODO make API equivalent to useRow
-    const setValue = React.useMemo(() => {
-        return (newValueOrFn) => {
-            const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current) : newValueOrFn;
-            const table = query$.queryInfo.table;
-            if (query$.queryInfo._tag === 'Row') {
-                if (table.options.isSingleton && table.options.isSingleColumn) {
-                    store.mutate(table.update(newValue));
-                }
-                else if (table.options.isSingleColumn) {
-                    store.mutate(table.update({ where: { id: query$.queryInfo.id }, values: { value: newValue } }));
-                }
-                else {
-                    store.mutate(table.update({ where: { id: query$.queryInfo.id }, values: newValue }));
-                }
-            }
-            else {
-                if (table.options.isSingleton && table.options.isSingleColumn) {
-                    store.mutate(table.update({ [query$.queryInfo.column]: newValue }));
-                }
-                else {
-                    store.mutate(table.update({
-                        where: { id: query$.queryInfo.id },
-                        values: { [query$.queryInfo.column]: newValue },
-                    }));
-                }
-            }
-        };
-    }, [query$.queryInfo, query$Ref, store]);
-    return [query$Ref.current, setValue];
-};
-//# sourceMappingURL=useAtom.js.map

package/dist/useAtom.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useAtom.js","sourceRoot":"","sources":["../src/useAtom.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAG3C,MAAM,CAAC,MAAM,OAAO,GAAG,CAIrB,MAAc,EACkF,EAAE;IAClG,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;IAErC,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAA;IAE5B,qCAAqC;IACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAgD,GAAG,EAAE;QACjF,OAAO,CAAC,YAAiB,EAAE,EAAE;YAC3B,MAAM,QAAQ,GAAG,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAA;YACpG,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,KACqC,CAAA;YAEpE,IAAI,MAAM,CAAC,SAAS,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBACpC,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;oBAC9D,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;gBACtC,CAAC;qBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;oBACxC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAA;gBACjG,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAA;gBACtF,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;oBAC9D,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAA;gBACrE,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,MAAM,CACV,KAAK,CAAC,MAAM,CAAC;wBACX,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE;wBAClC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE;qBAChD,CAAC,CACH,CAAA;gBACH,CAAC;YACH,CAAC;QACH,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAA;IAExC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;AACtC,CAAC,CAAA"}

package/dist/useRow.d.ts

@@ -1,50 +0,0 @@
-import type { QueryInfo, RowQuery } from '@livestore/common';
-import { SessionIdSymbol } from '@livestore/common';
-import { DbSchema } from '@livestore/common/schema';
-import type { LiveQuery, ReactivityGraph } from '@livestore/livestore';
-export type UseRowResult<TTableDef extends DbSchema.TableDefBase> = [
-    row: RowQuery.Result<TTableDef>,
-    setRow: StateSetters<TTableDef>,
-    query$: LiveQuery<RowQuery.Result<TTableDef>, QueryInfo>
-];
-export type UseRowOptionsBase = {
-    reactivityGraph?: ReactivityGraph;
-};
-/**
- * Similar to `React.useState` but returns a tuple of `[row, setRow, query$]` for a given table where ...
- *
- *   - `row` is the current value of the row (fully decoded according to the table schema)
- *   - `setRow` is a function that can be used to update the row (values will be encoded according to the table schema)
- *   - `query$` is a `LiveQuery` that e.g. can be used to subscribe to changes to the row
- *
- * If the table is a singleton table, `useRow` can be called without an `id` argument. Otherwise, the `id` argument is required.
- */
-export declare const useRow: {
-    <TTableDef extends DbSchema.TableDef<DbSchema.DefaultSqliteTableDef, DbSchema.TableOptions & {
-        isSingleton: true;
-        deriveMutations: {
-            enabled: true;
-        };
-    }>>(table: TTableDef, options?: UseRowOptionsBase): UseRowResult<TTableDef>;
-    <TTableDef extends DbSchema.TableDef<DbSchema.DefaultSqliteTableDef, DbSchema.TableOptions & {
-        isSingleton: false;
-        requiredInsertColumnNames: 'id';
-        deriveMutations: {
-            enabled: true;
-        };
-    }>>(table: TTableDef, id: string | SessionIdSymbol, options?: UseRowOptionsBase & Partial<RowQuery.RequiredColumnsOptions<TTableDef>>): UseRowResult<TTableDef>;
-    <TTableDef extends DbSchema.TableDef<DbSchema.DefaultSqliteTableDef, DbSchema.TableOptions & {
-        isSingleton: false;
-        deriveMutations: {
-            enabled: true;
-        };
-    }>>(table: TTableDef, id: string | SessionIdSymbol, options: UseRowOptionsBase & RowQuery.RequiredColumnsOptions<TTableDef>): UseRowResult<TTableDef>;
-};
-export type Dispatch<A> = (action: A) => void;
-export type SetStateAction<S> = S | ((previousValue: S) => S);
-export type StateSetters<TTableDef extends DbSchema.TableDefBase> = TTableDef['options']['isSingleColumn'] extends true ? Dispatch<SetStateAction<RowQuery.Result<TTableDef>>> : {
-    [K in keyof RowQuery.Result<TTableDef>]: Dispatch<SetStateAction<RowQuery.Result<TTableDef>[K]>>;
-} & {
-    setMany: Dispatch<SetStateAction<Partial<RowQuery.Result<TTableDef>>>>;
-};
-//# sourceMappingURL=useRow.d.ts.map

package/dist/useRow.d.ts.map

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

package/dist/useRow.js

@@ -1,93 +0,0 @@
-import { SessionIdSymbol } from '@livestore/common';
-import { DbSchema } from '@livestore/common/schema';
-import { queryDb } from '@livestore/livestore';
-import { shouldNeverHappen } from '@livestore/utils';
-import { ReadonlyRecord } from '@livestore/utils/effect';
-import React from 'react';
-import { useStore } from './LiveStoreContext.js';
-import { useQueryRef } from './useQuery.js';
-import { useMakeScopedQuery } from './useScopedQuery.js';
-/**
- * Similar to `React.useState` but returns a tuple of `[row, setRow, query$]` for a given table where ...
- *
- *   - `row` is the current value of the row (fully decoded according to the table schema)
- *   - `setRow` is a function that can be used to update the row (values will be encoded according to the table schema)
- *   - `query$` is a `LiveQuery` that e.g. can be used to subscribe to changes to the row
- *
- * If the table is a singleton table, `useRow` can be called without an `id` argument. Otherwise, the `id` argument is required.
- */
-export const useRow = (table, idOrOptions, options_) => {
-    const sqliteTableDef = table.sqliteDef;
-    const id = typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? idOrOptions : undefined;
-    const options = typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? options_ : idOrOptions;
-    const { insertValues, reactivityGraph } = options ?? {};
-    const tableName = table.sqliteDef.name;
-    if (DbSchema.tableHasDerivedMutations(table) === false) {
-        shouldNeverHappen(`useRow called on table "${tableName}" which does not have 'deriveMutations: true' set`);
-    }
-    const { store } = useStore();
-    if (store.schema.tables.has(table.sqliteDef.name) === false &&
-        table.sqliteDef.name.startsWith('__livestore') === false) {
-        shouldNeverHappen(`Table "${table.sqliteDef.name}" not found in schema`);
-    }
-    // console.debug('useRow', tableName, id)
-    const idStr = id === SessionIdSymbol ? 'session' : id;
-    const rowQuery = table.query.row;
-    const { query$, otelContext } = useMakeScopedQuery((otelContext) => DbSchema.tableIsSingleton(table)
-        ? queryDb(rowQuery(), { reactivityGraph, otelContext })
-        : queryDb(rowQuery(id, { insertValues: insertValues }), { reactivityGraph, otelContext }), [idStr, tableName], {
-        otel: {
-            spanName: `LiveStore:useRow:${tableName}${idStr === undefined ? '' : `:${idStr}`}`,
-            attributes: { id: idStr },
-        },
-    });
-    const query$Ref = useQueryRef(query$, otelContext);
-    const setState = React.useMemo(() => {
-        if (table.options.isSingleColumn) {
-            return (newValueOrFn) => {
-                const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current) : newValueOrFn;
-                if (query$Ref.current === newValue)
-                    return;
-                // NOTE we need to account for the short-hand syntax for single-column+singleton tables
-                if (table.options.isSingleton) {
-                    store.mutate(table.update(newValue));
-                }
-                else {
-                    store.mutate(table.update({ where: { id }, values: { value: newValue } }));
-                }
-                // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, { value: newValue }))
-            };
-        }
-        else {
-            const setState = // TODO: do we have a better type for the values that can go in SQLite?
-             ReadonlyRecord.map(sqliteTableDef.columns, (column, columnName) => (newValueOrFn) => {
-                const newValue = 
-                // @ts-expect-error TODO fix typing
-                typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current[columnName]) : newValueOrFn;
-                // Don't update the state if it's the same as the value already seen in the component
-                // @ts-expect-error TODO fix typing
-                if (query$Ref.current[columnName] === newValue)
-                    return;
-                store.mutate(table.update({ where: { id: id ?? 'singleton' }, values: { [columnName]: newValue } }));
-                // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, { [columnName]: newValue }))
-            });
-            setState.setMany = (columnValuesOrFn) => {
-                const columnValues = 
-                // @ts-expect-error TODO fix typing
-                typeof columnValuesOrFn === 'function' ? columnValuesOrFn(query$Ref.current) : columnValuesOrFn;
-                // TODO use hashing instead
-                // Don't update the state if it's the same as the value already seen in the component
-                if (
-                // @ts-expect-error TODO fix typing
-                Object.entries(columnValues).every(([columnName, value]) => query$Ref.current[columnName] === value)) {
-                    return;
-                }
-                store.mutate(table.update({ where: { id: id ?? 'singleton' }, values: columnValues }));
-                // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, columnValues))
-            };
-            return setState;
-        }
-    }, [id, query$Ref, sqliteTableDef.columns, store, table]);
-    return [query$Ref.current, setState, query$];
-};
-//# sourceMappingURL=useRow.js.map

package/dist/useRow.js.map

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

package/dist/useRow.test.d.ts

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

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

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