@livestore/react 0.3.0-dev.28 → 0.3.0-dev.29

package/src/{useRow.test.tsx → useClientDocument.test.tsx}

@@ -8,14 +8,14 @@ import * as ReactTesting from '@testing-library/react'
 import React from 'react'
 import { beforeEach, expect, it } from 'vitest'
 
-import { AppRouterSchema, makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
-import * as LiveStoreReact from './mod.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
+import type * as LiveStoreReact from './mod.js'
 import { __resetUseRcResourceCache } from './useRcResource.js'
 
 // const strictMode = process.env.REACT_STRICT_MODE !== undefined
 
 // NOTE running tests concurrently doesn't work with the default global db graph
-Vitest.describe('useRow', () => {
+Vitest.describe('useClientDocument', () => {
   beforeEach(() => {
     __resetUseRcResourceCache()
   })
@@ -28,22 +28,22 @@ Vitest.describe('useRow', () => {
         (userId: string) => {
           renderCount.inc()
 
-          const [state, setState] = LiveStoreReact.useRow(tables.userInfo, userId)
-          return { state, setState }
+          const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
+          return { state, setState, id }
         },
         { wrapper, initialProps: 'u1' },
       )
 
-      expect(result.current.state.id).toBe('u1')
+      expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
       expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
-      store.commit(tables.userInfo.insert({ id: 'u2', username: 'username_u2' }))
+      store.commit(tables.userInfo.set({ username: 'username_u2' }, 'u2'))
 
       rerender('u2')
 
       expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
-      expect(result.current.state.id).toBe('u2')
+      expect(result.current.id).toBe('u2')
       expect(result.current.state.username).toBe('username_u2')
       expect(renderCount.val).toBe(2)
     }),
@@ -53,31 +53,31 @@ Vitest.describe('useRow', () => {
 
   Vitest.scopedLive('should update the data reactively - via setState', () =>
     Effect.gen(function* () {
-      const { wrapper, renderCount } = yield* makeTodoMvcReact({})
+      const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
       const { result } = ReactTesting.renderHook(
         (userId: string) => {
           renderCount.inc()
 
-          const [state, setState] = LiveStoreReact.useRow(tables.userInfo, userId)
-          return { state, setState }
+          const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
+          return { state, setState, id }
         },
         { wrapper, initialProps: 'u1' },
       )
 
-      expect(result.current.state.id).toBe('u1')
+      expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
 
-      ReactTesting.act(() => result.current.setState.username('username_u1_hello'))
+      ReactTesting.act(() => result.current.setState({ username: 'username_u1_hello' }))
 
-      expect(result.current.state.id).toBe('u1')
+      expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('username_u1_hello')
       expect(renderCount.val).toBe(2)
     }),
   )
 
-  Vitest.scopedLive('should update the data reactively - via raw store mutation', () =>
+  Vitest.scopedLive('should update the data reactively - via raw store commit', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -85,21 +85,19 @@ Vitest.describe('useRow', () => {
         (userId: string) => {
           renderCount.inc()
 
-          const [state, setState] = LiveStoreReact.useRow(tables.userInfo, userId)
-          return { state, setState }
+          const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
+          return { state, setState, id }
         },
         { wrapper, initialProps: 'u1' },
       )
 
-      expect(result.current.state.id).toBe('u1')
+      expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
 
-      ReactTesting.act(() =>
-        store.commit(tables.userInfo.update({ where: { id: 'u1' }, values: { username: 'username_u1_hello' } })),
-      )
+      ReactTesting.act(() => store.commit(events.UserInfoSet({ username: 'username_u1_hello' }, 'u1')))
 
-      expect(result.current.state.id).toBe('u1')
+      expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('username_u1_hello')
       expect(renderCount.val).toBe(2)
     }),
@@ -110,21 +108,21 @@ Vitest.describe('useRow', () => {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
       const allTodos$ = LiveStore.queryDb(
-        { query: `select * from todos`, schema: Schema.Array(tables.todos.schema) },
+        { query: `select * from todos`, schema: Schema.Array(tables.todos.rowSchema) },
         { label: 'allTodos' },
       )
 
-      let globalSetState: LiveStoreReact.StateSetters<typeof AppRouterSchema> | undefined
+      let globalSetState: LiveStoreReact.StateSetters<typeof tables.AppRouterSchema> | undefined
       const AppRouter: React.FC = () => {
         renderCount.inc()
 
-        const [state, setState] = LiveStoreReact.useRow(AppRouterSchema)
+        const [state, setState] = store.useClientDocument(tables.AppRouterSchema, 'singleton')
 
         globalSetState = setState
 
         return (
           <div>
-            <TasksList setTaskId={setState.currentTaskId} />
+            <TasksList setTaskId={(taskId) => setState({ currentTaskId: taskId })} />
             <div role="current-id">Current Task Id: {state.currentTaskId ?? '-'}</div>
             {state.currentTaskId ? <TaskDetails id={state.currentTaskId} /> : <div>Click on a task to see details</div>}
           </div>
@@ -132,7 +130,7 @@ Vitest.describe('useRow', () => {
       }
 
       const TasksList: React.FC<{ setTaskId: (_: string) => void }> = ({ setTaskId }) => {
-        const allTodos = LiveStoreReact.useQuery(allTodos$)
+        const allTodos = store.useQuery(allTodos$)
 
         return (
           <div>
@@ -146,7 +144,7 @@ Vitest.describe('useRow', () => {
       }
 
       const TaskDetails: React.FC<{ id: string }> = ({ id }) => {
-        const [todo] = LiveStoreReact.useRow(todos, id)
+        const todo = store.useQuery(LiveStore.queryDb(tables.todos.where({ id }).first(), { deps: id }))
         return <div role="content">{JSON.stringify(todo)}</div>
       }
 
@@ -156,7 +154,7 @@ Vitest.describe('useRow', () => {
 
       ReactTesting.act(() =>
         store.commit(
-          LiveStore.rawSqlMutation({
+          LiveStore.rawSqlEvent({
             sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)`,
           }),
         ),
@@ -165,7 +163,7 @@ Vitest.describe('useRow', () => {
       expect(renderCount.val).toBe(1)
       expect(renderResult.getByRole('current-id').innerHTML).toMatchInlineSnapshot('"Current Task Id: -"')
 
-      ReactTesting.act(() => globalSetState!.currentTaskId('t1'))
+      ReactTesting.act(() => globalSetState!({ currentTaskId: 't1' }))
 
       expect(renderCount.val).toBe(2)
       expect(renderResult.getByRole('content').innerHTML).toMatchInlineSnapshot(
@@ -176,13 +174,9 @@ Vitest.describe('useRow', () => {
 
       ReactTesting.act(() =>
         store.commit(
-          LiveStore.rawSqlMutation({
-            sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t2', 'buy eggs', 0)`,
-          }),
-          AppRouterSchema.update({ where: { id: 'singleton' }, values: { currentTaskId: 't2' } }),
-          LiveStore.rawSqlMutation({
-            sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t3', 'buy bread', 0)`,
-          }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: false }),
+          events.AppRouterSet({ currentTaskId: 't2' }),
+          events.todoCreated({ id: 't3', text: 'buy bread', completed: false }),
         ),
       )
 
@@ -191,23 +185,23 @@ Vitest.describe('useRow', () => {
     }),
   )
 
-  Vitest.scopedLive('should work for a useRow query chained with a useTemporary query', () =>
+  Vitest.scopedLive('should work for a useClientDocument query chained with a useTemporary query', () =>
     Effect.gen(function* () {
       const { store, wrapper, renderCount } = yield* makeTodoMvcReact({})
 
       store.commit(
-        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
-        todos.insert({ id: 't2', text: 'buy bread', completed: false }),
+        events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+        events.todoCreated({ id: 't2', text: 'buy bread', completed: false }),
       )
 
       const { result, unmount, rerender } = ReactTesting.renderHook(
         (userId: string) => {
           renderCount.inc()
 
-          const [_row, _setRow, rowState$] = LiveStoreReact.useRow(tables.userInfo, userId)
-          const todos = LiveStoreReact.useQuery(
+          const [_row, _setRow, _id, rowState$] = store.useClientDocument(tables.userInfo, userId)
+          const todos = store.useQuery(
             LiveStore.queryDb(
-              (get) => tables.todos.query.where('text', 'LIKE', `%${get(rowState$).text}%`),
+              (get) => tables.todos.where('text', 'LIKE', `%${get(rowState$).text}%`),
               // TODO find a way where explicit `userId` is not needed here
               // possibly by automatically understanding the `get(rowState$)` dependency
               { label: 'todosFiltered', deps: userId },
@@ -220,7 +214,7 @@ Vitest.describe('useRow', () => {
         { wrapper, initialProps: 'u1' },
       )
 
-      ReactTesting.act(() => store.commit(tables.userInfo.insert({ id: 'u2', username: 'username_u2', text: 'milk' })))
+      ReactTesting.act(() => store.commit(events.UserInfoSet({ username: 'username_u2', text: 'milk' }, 'u2')))
 
       expect(result.current.todos.length).toBe(2)
       expect(renderCount.val).toBe(1)
@@ -235,18 +229,16 @@ Vitest.describe('useRow', () => {
   )
 
   Vitest.describe('otel', () => {
-    const provider = new BasicTracerProvider({})
-    provider.register()
-
     it.each([{ strictMode: true }, { strictMode: false }])(
       'should update the data based on component key strictMode=%s',
       async ({ strictMode }) => {
         const exporter = new InMemorySpanExporter()
 
-        // const provider = cachedProvider ?? new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
-        provider.addSpanProcessor(new SimpleSpanProcessor(exporter))
+        const provider = new BasicTracerProvider({
+          spanProcessors: [new SimpleSpanProcessor(exporter)],
+        })
 
-        const otelTracer = otel.trace.getTracer(`testing-${strictMode ? 'strict' : 'non-strict'}`)
+        const otelTracer = provider.getTracer(`testing-${strictMode ? 'strict' : 'non-strict'}`)
 
         const span = otelTracer.startSpan('test-root')
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
@@ -262,23 +254,23 @@ Vitest.describe('useRow', () => {
             (userId: string) => {
               renderCount.inc()
 
-              const [state, setState] = LiveStoreReact.useRow(tables.userInfo, userId)
-              return { state, setState }
+              const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
+              return { state, setState, id }
             },
             { wrapper, initialProps: 'u1' },
           )
 
-          expect(result.current.state.id).toBe('u1')
+          expect(result.current.id).toBe('u1')
           expect(result.current.state.username).toBe('')
           expect(renderCount.val).toBe(1)
 
           // For u2 we'll make sure that the row already exists,
           // so the lazy `insert` will be skipped
-          ReactTesting.act(() => store.commit(tables.userInfo.insert({ id: 'u2', username: 'username_u2' })))
+          ReactTesting.act(() => store.commit(events.UserInfoSet({ username: 'username_u2' }, 'u2')))
 
           rerender('u2')
 
-          expect(result.current.state.id).toBe('u2')
+          expect(result.current.id).toBe('u2')
           expect(result.current.state.username).toBe('username_u2')
           expect(renderCount.val).toBe(2)
 
@@ -286,6 +278,8 @@ Vitest.describe('useRow', () => {
           span.end()
         }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise)
 
+        await provider.forceFlush()
+
         const mapAttributes = (attributes: otel.Attributes) => {
           return ReadonlyRecord.map(attributes, (val, key) => {
             if (key === 'firstStackInfo') {
@@ -304,6 +298,8 @@ Vitest.describe('useRow', () => {
         }
 
         expect(getSimplifiedRootSpan(exporter, mapAttributes)).toMatchSnapshot()
+
+        await provider.shutdown()
       },
     )
   })

package/src/useClientDocument.ts

@@ -0,0 +1,157 @@
+import type { RowQuery } from '@livestore/common'
+import { SessionIdSymbol } from '@livestore/common'
+import { State } from '@livestore/common/schema'
+import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
+import { queryDb } from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
+import React from 'react'
+
+import { LiveStoreContext } from './LiveStoreContext.js'
+import { useQueryRef } from './useQuery.js'
+
+export type UseRowResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
+  row: TTableDef['Value'],
+  setRow: StateSetters<TTableDef>,
+  id: string,
+  query$: LiveQuery<TTableDef['Value']>,
+]
+
+/**
+ * Similar to `React.useState` but returns a tuple of `[state, setState, id, query$]` for a given table where ...
+ *
+ *   - `state` is the current value of the row (fully decoded according to the table schema)
+ *   - `setState` is a function that can be used to update the document
+ *   - `id` is the id of the document
+ *   - `query$` is a `LiveQuery` that e.g. can be used to subscribe to changes to the document
+ *
+ * `useClientDocument` only works for client-document tables:
+ *
+ * ```tsx
+ * const MyState = State.SQLite.clientDocument({
+ *   name: 'MyState',
+ *   schema: Schema.Struct({
+ *     showSidebar: Schema.Boolean,
+ *   }),
+ *   default: { id: SessionIdSymbol, value: { showSidebar: true } },
+ * })
+ *
+ * const MyComponent = () => {
+ *   const [{ showSidebar }, setState] = useClientDocument(MyState)
+ *   return (
+ *     <div onClick={() => setState({ showSidebar: !showSidebar })}>
+ *       {showSidebar ? 'Sidebar is open' : 'Sidebar is closed'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * If the table has a default id, `useClientDocument` can be called without an `id` argument. Otherwise, the `id` argument is required.
+ */
+export const useClientDocument: {
+  // case: with default id
+  <
+    TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+      any,
+      any,
+      any,
+      { partialSet: boolean; default: { id: string | SessionIdSymbol; value: any } }
+    >,
+  >(
+    table: TTableDef,
+    id?: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | SessionIdSymbol,
+    options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  ): UseRowResult<TTableDef>
+
+  // case: no default id → id arg is required
+  <
+    TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+      any,
+      any,
+      any,
+      { partialSet: boolean; default: { id: string | SessionIdSymbol | undefined; value: any } }
+    >,
+  >(
+    table: TTableDef,
+    // TODO adjust so it works with arbitrary primary keys or unique constraints
+    id: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | string | SessionIdSymbol,
+    options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  ): UseRowResult<TTableDef>
+} = <TTableDef extends State.SQLite.ClientDocumentTableDef.Any>(
+  table: TTableDef,
+  idOrOptions?: string | SessionIdSymbol,
+  options_?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  storeArg?: { store?: Store },
+): UseRowResult<TTableDef> => {
+  const id =
+    typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol
+      ? idOrOptions
+      : table[State.SQLite.ClientDocumentTableDefSymbol].options.default.id
+
+  const options: Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined =
+    typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? options_ : idOrOptions
+
+  const { default: defaultValues } = options ?? {}
+
+  React.useMemo(() => validateTableOptions(table), [table])
+
+  const tableName = table.sqliteDef.name
+
+  const store =
+    storeArg?.store ??
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useContext(LiveStoreContext)?.store ??
+    shouldNeverHappen(`No store provided to useClientDocument`)
+
+  // console.debug('useClientDocument', tableName, id)
+
+  const idStr: string = id === SessionIdSymbol ? store.clientSession.sessionId : id
+
+  type QueryDef = LiveQueryDef<TTableDef['Value']>
+  const queryDef: QueryDef = React.useMemo(
+    () =>
+      queryDb(table.get(id!, { default: defaultValues! }), {
+        deps: [idStr!, table.sqliteDef.name, JSON.stringify(defaultValues)],
+      }),
+    [table, id, defaultValues, idStr],
+  )
+
+  const queryRef = useQueryRef(queryDef, {
+    otelSpanName: `LiveStore:useClientDocument:${tableName}:${idStr}`,
+    store: storeArg?.store,
+  })
+
+  const setState = React.useMemo<StateSetters<TTableDef>>(
+    () => (newValueOrFn: TTableDef['Value']) => {
+      const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(queryRef.valueRef.current) : newValueOrFn
+      if (queryRef.valueRef.current === newValue) return
+
+      store.commit(table.set(removeUndefinedValues(newValue), id as any))
+    },
+    [id, queryRef.valueRef, store, table],
+  )
+
+  return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value]
+}
+
+export type Dispatch<A> = (action: A) => void
+export type SetStateAction<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+
+export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
+  SetStateAction<TTableDef['Value']>
+>
+
+const validateTableOptions = (table: State.SQLite.TableDef<any, any>) => {
+  if (State.SQLite.tableIsClientDocumentTable(table) === false) {
+    return shouldNeverHappen(
+      `useClientDocument called on table "${table.sqliteDef.name}" which is not a client document table`,
+    )
+  }
+}
+
+const removeUndefinedValues = (value: any) => {
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(Object.entries(value).filter(([_, v]) => v !== undefined))
+  }
+
+  return value
+}

package/src/useQuery.test.tsx

@@ -11,8 +11,7 @@ import React from 'react'
 import * as ReactWindow from 'react-window'
 import { expect } from 'vitest'
 
-import { makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
-import * as LiveStoreReact from './mod.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
 import { __resetUseRcResourceCache } from './useRcResource.js'
 
 Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
@@ -27,13 +26,13 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
       Effect.gen(function* () {
         const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
 
-        const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.schema) })
+        const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.rowSchema) })
 
         const { result } = ReactTesting.renderHook(
           () => {
             renderCount.inc()
 
-            return LiveStoreReact.useQuery(allTodos$)
+            return store.useQuery(allTodos$)
           },
           { wrapper },
         )
@@ -42,7 +41,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         expect(renderCount.val).toBe(1)
         expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
-        ReactTesting.act(() => store.commit(todos.insert({ id: 't1', text: 'buy milk', completed: false })))
+        ReactTesting.act(() => store.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false })))
 
         expect(result.current.length).toBe(1)
         expect(result.current[0]!.text).toBe('buy milk')
@@ -56,17 +55,17 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
 
         const todo1$ = queryDb(
-          { query: `select * from todos where id = 't1'`, schema: Schema.Array(tables.todos.schema) },
+          { query: `select * from todos where id = 't1'`, schema: Schema.Array(tables.todos.rowSchema) },
           { label: 'libraryTracksView1' },
         )
         const todo2$ = queryDb(
-          { query: `select * from todos where id = 't2'`, schema: Schema.Array(tables.todos.schema) },
+          { query: `select * from todos where id = 't2'`, schema: Schema.Array(tables.todos.rowSchema) },
           { label: 'libraryTracksView2' },
         )
 
         store.commit(
-          todos.insert({ id: 't1', text: 'buy milk', completed: false }),
-          todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: false }),
         )
 
         const { result, rerender } = ReactTesting.renderHook(
@@ -75,7 +74,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
             const query$ = React.useMemo(() => (todoId === 't1' ? todo1$ : todo2$), [todoId])
 
-            return LiveStoreReact.useQuery(query$)[0]!.text
+            return store.useQuery(query$)[0]!.text
           },
           { wrapper, initialProps: 't1' },
         )
@@ -84,11 +83,11 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         expect(renderCount.val).toBe(1)
         expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('1: after first render')
 
-        ReactTesting.act(() => store.commit(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+        ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('2: after first mutation')
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('2: after first commit')
 
         rerender('t2')
 
@@ -104,18 +103,18 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         const filter$ = makeRef('t1', { label: 'id-filter' })
 
-        const todo$ = queryDb((get) => tables.todos.query.where('id', get(filter$)), { label: 'todo' })
+        const todo$ = queryDb((get) => tables.todos.where('id', get(filter$)), { label: 'todo' })
 
         store.commit(
-          todos.insert({ id: 't1', text: 'buy milk', completed: false }),
-          todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: false }),
         )
 
         const { result } = ReactTesting.renderHook(
           () => {
             renderCount.inc()
 
-            return LiveStoreReact.useQuery(todo$)[0]!.text
+            return store.useQuery(todo$)[0]!.text
           },
           { wrapper },
         )
@@ -124,7 +123,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         expect(renderCount.val).toBe(1)
         expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
-        ReactTesting.act(() => store.commit(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+        ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
@@ -143,7 +142,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
     // To handle this properly we introduced the `_tag: 'destroyed'` state in the `spanAlreadyStartedCache`.
     Vitest.scopedLive('should work for a list with react-window', () =>
       Effect.gen(function* () {
-        const { wrapper } = yield* makeTodoMvcReact({ strictMode })
+        const { wrapper, store } = yield* makeTodoMvcReact({ strictMode })
 
         const ListWrapper: React.FC<{ numItems: number }> = ({ numItems }) => {
           return (
@@ -161,7 +160,7 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         const ListItem: React.FC<{ data: ReadonlyArray<number>; index: number }> = ({ data: ids, index }) => {
           const id = ids[index]!
-          const res = LiveStoreReact.useQuery(LiveStore.computed(() => id, { label: `ListItem.${id}`, deps: id }))
+          const res = store.useQuery(LiveStore.computed(() => id, { label: `ListItem.${id}`, deps: id }))
           return <div role="listitem">{res}</div>
         }
 

package/src/useQuery.ts

@@ -1,11 +1,11 @@
 import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
 import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
 import type { LiveQueries } from '@livestore/livestore/internal'
-import { deepEqual, indent } from '@livestore/utils'
+import { deepEqual, indent, shouldNeverHappen } from '@livestore/utils'
 import * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import { useStore } from './LiveStoreContext.js'
+import { LiveStoreContext } from './LiveStoreContext.js'
 import { useRcResource } from './useRcResource.js'
 import { originalStackLimit } from './utils/stack-info.js'
 import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
@@ -26,9 +26,6 @@ export const useQuery = <TQuery extends LiveQueryDef.Any>(
   options?: { store?: Store },
 ): LiveQueries.GetResult<TQuery> => useQueryRef(queryDef, options).valueRef.current
 
-type GetQueryInfo<TQuery extends LiveQueryDef.Any> =
-  TQuery extends LiveQueryDef<infer _1, infer TQueryInfo> ? TQueryInfo : never
-
 /**
  */
 export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
@@ -42,9 +39,13 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
   },
 ): {
   valueRef: React.RefObject<LiveQueries.GetResult<TQuery>>
-  queryRcRef: LiveQueries.RcRef<LiveQuery<LiveQueries.GetResult<TQuery>, GetQueryInfo<TQuery>>>
+  queryRcRef: LiveQueries.RcRef<LiveQuery<LiveQueries.GetResult<TQuery>>>
 } => {
-  const { store } = useStore({ store: options?.store })
+  const store =
+    options?.store ??
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useContext(LiveStoreContext)?.store ??
+    shouldNeverHappen(`No store provided to useQuery`)
 
   const rcRefKey = `${store.storeId}_${queryDef.hash}`
 
@@ -77,7 +78,7 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
     // which takes care of disposing the queryRcRef
     () => {},
   )
-  const query$ = queryRcRef.value as LiveQuery<LiveQueries.GetResult<TQuery>, GetQueryInfo<TQuery>>
+  const query$ = queryRcRef.value as LiveQuery<LiveQueries.GetResult<TQuery>>
 
   React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
   // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)

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) }
+}