@livestore/react 0.0.0-snapshot-2ef046b02334f52613d31dbe06af53487685edc0 → 0.0.0-snapshot-2c861249e50661661613204300b1fc0d902c2e46

package/src/__tests__/fixture.tsx

@@ -1,9 +1,9 @@
 import { makeInMemoryAdapter } from '@livestore/adapter-web'
 import { provideOtel } from '@livestore/common'
-import { DbSchema, makeSchema } from '@livestore/common/schema'
-import type { LiveStoreContextRunning } from '@livestore/livestore'
+import { Events, makeSchema, State } from '@livestore/common/schema'
+import type { Store } from '@livestore/livestore'
 import { createStore } from '@livestore/livestore'
-import { Effect } from '@livestore/utils/effect'
+import { Effect, Schema } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 import React from 'react'
 
@@ -22,45 +22,70 @@ export type AppState = {
   filter: Filter
 }
 
-export const todos = DbSchema.table(
-  'todos',
-  {
-    id: DbSchema.text({ primaryKey: true }),
-    text: DbSchema.text({ default: '', nullable: false }),
-    completed: DbSchema.boolean({ default: false, nullable: false }),
+const todos = State.SQLite.table({
+  name: 'todos',
+  columns: {
+    id: State.SQLite.text({ primaryKey: true }),
+    text: State.SQLite.text({ default: '', nullable: false }),
+    completed: State.SQLite.boolean({ default: false, nullable: false }),
   },
-  { deriveMutations: { clientOnly: true }, isSingleton: false },
-)
-
-export const app = DbSchema.table(
-  'app',
-  {
-    id: DbSchema.text({ primaryKey: true, default: 'static' }),
-    newTodoText: DbSchema.text({ default: '', nullable: true }),
-    filter: DbSchema.text({ default: 'all', nullable: false }),
+})
+
+const app = State.SQLite.table({
+  name: 'app',
+  columns: {
+    id: State.SQLite.text({ primaryKey: true, default: 'static' }),
+    newTodoText: State.SQLite.text({ default: '', nullable: true }),
+    filter: State.SQLite.text({ default: 'all', nullable: false }),
   },
-  { isSingleton: true },
-)
-
-export const userInfo = DbSchema.table(
-  'UserInfo',
-  {
-    username: DbSchema.text({ default: '' }),
-    text: DbSchema.text({ default: '' }),
+})
+
+const userInfo = State.SQLite.clientDocument({
+  name: 'UserInfo',
+  schema: Schema.Struct({
+    username: Schema.String,
+    text: Schema.String,
+  }),
+  default: { value: { username: '', text: '' } },
+})
+
+const AppRouterSchema = State.SQLite.clientDocument({
+  name: 'AppRouter',
+  schema: Schema.Struct({
+    currentTaskId: Schema.String.pipe(Schema.NullOr),
+  }),
+  default: {
+    value: { currentTaskId: null },
+    id: 'singleton',
   },
-  { deriveMutations: { clientOnly: true } },
-)
+})
+
+export const events = {
+  todoCreated: Events.synced({
+    name: 'todoCreated',
+    schema: Schema.Struct({ id: Schema.String, text: Schema.String, completed: Schema.Boolean }),
+  }),
+  todoUpdated: Events.synced({
+    name: 'todoUpdated',
+    schema: Schema.Struct({
+      id: Schema.String,
+      text: Schema.String.pipe(Schema.optional),
+      completed: Schema.Boolean.pipe(Schema.optional),
+    }),
+  }),
+  AppRouterSet: AppRouterSchema.set,
+  UserInfoSet: userInfo.set,
+}
 
-export const AppRouterSchema = DbSchema.table(
-  'AppRouter',
-  {
-    currentTaskId: DbSchema.text({ default: null, nullable: true }),
-  },
-  { isSingleton: true, deriveMutations: { clientOnly: true } },
-)
+const materializers = State.SQLite.materializers(events, {
+  todoCreated: ({ id, text, completed }) => todos.insert({ id, text, completed }),
+  todoUpdated: ({ id, text, completed }) => todos.update({ completed, text }).where({ id }),
+})
 
 export const tables = { todos, app, userInfo, AppRouterSchema }
-export const schema = makeSchema({ tables })
+
+const state = State.SQLite.makeState({ tables, materializers })
+export const schema = makeSchema({ state, events })
 
 export const makeTodoMvcReact = ({
   otelTracer,
@@ -87,15 +112,20 @@ export const makeTodoMvcReact = ({
       }
     }
 
-    const store = yield* createStore({
+    const store: Store<any> = yield* createStore({
       schema,
       storeId: 'default',
       adapter: makeInMemoryAdapter(),
       debug: { instanceId: 'test' },
     })
 
+    const storeWithReactApi = LiveStoreReact.withReactApi(store)
+
     // TODO improve typing of `LiveStoreContext`
-    const storeContext = { stage: 'running', store } as any as LiveStoreContextRunning
+    const storeContext = {
+      stage: 'running' as const,
+      store: storeWithReactApi,
+    }
 
     const MaybeStrictMode = strictMode ? React.StrictMode : React.Fragment
 
@@ -109,5 +139,5 @@ export const makeTodoMvcReact = ({
 
     const renderCount = makeRenderCount()
 
-    return { wrapper, store, renderCount }
+    return { wrapper, store: storeWithReactApi, renderCount }
   }).pipe(provideOtel({ parentSpanContext: otelContext, otelTracer }))

package/src/mod.ts

@@ -1,12 +1,12 @@
-export { LiveStoreContext, useStore } from './LiveStoreContext.js'
+export { LiveStoreContext, type ReactApi } from './LiveStoreContext.js'
+export { useStore, withReactApi } from './useStore.js'
 export { LiveStoreProvider } from './LiveStoreProvider.js'
-export { useQuery } from './useQuery.js'
 export { useStackInfo } from './utils/stack-info.js'
+export { useQuery, useQueryRef } from './useQuery.js'
 export {
-  useRow,
+  useClientDocument,
   type StateSetters,
   type SetStateAction,
   type Dispatch,
   type UseRowResult as UseStateResult,
-} from './useRow.js'
-export { useAtom } from './useAtom.js'
+} from './useClientDocument.js'

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)
@@ -262,23 +256,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)
 

package/src/useClientDocument.ts

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