@livestore/react 0.4.0-dev.9 → 0.5.0-dev.0

package/src/__tests__/fixture.tsx

@@ -1,131 +1,45 @@
-import { makeInMemoryAdapter } from '@livestore/adapter-web'
-import { provideOtel, type UnexpectedError } from '@livestore/common'
-import { Events, makeSchema, State } from '@livestore/common/schema'
-import type { LiveStoreSchema, SqliteDsl, Store } from '@livestore/livestore'
-import { createStore } from '@livestore/livestore'
-import { omitUndefineds } from '@livestore/utils'
-import { Effect, Schema, type Scope } from '@livestore/utils/effect'
-import type * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import * as LiveStoreReact from '../mod.js'
-
-export type Todo = {
-  id: string
-  text: string
-  completed: boolean
+import type { UnknownError } from '@livestore/common'
+import {
+  type AppState,
+  type CreateTodoMvcStoreOptions,
+  createTodoMvcStore,
+  events,
+  type Filter,
+  schema,
+  type Todo,
+  tables,
+} from '@livestore/framework-toolkit/testing'
+import type { Store } from '@livestore/livestore'
+import { Effect, type Scope } from '@livestore/utils/effect'
+
+import * as LiveStoreReact from '../mod.ts'
+
+export type { AppState, Filter, Todo }
+// Re-export shared types and schema
+export { events, schema, tables }
+
+export type MakeTodoMvcReactOptions = CreateTodoMvcStoreOptions & {
+  strictMode?: boolean | undefined
 }
 
-export type Filter = 'all' | 'active' | 'completed'
-
-export type AppState = {
-  newTodoText: string
-  filter: Filter
-}
-
-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 }),
-  },
-})
-
-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 }),
-  },
-})
-
-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',
-  },
-})
-
-const kv = State.SQLite.clientDocument({
-  name: 'Kv',
-  schema: Schema.Any,
-  default: { value: null },
-})
-
-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,
-  KvSet: kv.set,
-}
-
-const materializers = State.SQLite.materializers(events, {
-  todoCreated: ({ id, text, completed }) => todos.insert({ id, text, completed }),
-  todoUpdated: ({ id, text, completed }) => todos.update({ ...omitUndefineds({ completed, text }) }).where({ id }),
-})
-
-export const tables = { todos, app, userInfo, AppRouterSchema, kv }
-
-const state = State.SQLite.makeState({ tables, materializers })
-export const schema = makeSchema({ state, events })
-
-export const makeTodoMvcReact: ({
-  otelTracer,
-  otelContext,
-  strictMode,
-}?: {
-  otelTracer?: otel.Tracer
-  otelContext?: otel.Context
-  strictMode?: boolean
-}) => Effect.Effect<
+export const makeTodoMvcReact: (opts?: MakeTodoMvcReactOptions) => Effect.Effect<
   {
     wrapper: ({ children }: any) => React.JSX.Element
-    store: Store<LiveStoreSchema<SqliteDsl.DbSchema, State.SQLite.EventDefRecord>, {}> & LiveStoreReact.ReactApi
+    store: Store<typeof schema> & LiveStoreReact.ReactApi
     renderCount: { readonly val: number; inc: () => void }
   },
-  UnexpectedError,
+  UnknownError,
   Scope.Scope
-> = ({
-  otelTracer,
-  otelContext,
-  strictMode,
-}: {
-  otelTracer?: otel.Tracer
-  otelContext?: otel.Context
-  strictMode?: boolean
-} = {}) =>
+> = (opts: MakeTodoMvcReactOptions = {}) =>
   Effect.gen(function* () {
+    const { strictMode } = opts
     const makeRenderCount = () => {
       let val = 0
 
       const inc = () => {
-        val += strictMode ? 0.5 : 1
+        val += strictMode === true ? 0.5 : 1
       }
 
       return {
@@ -136,32 +50,15 @@ export const makeTodoMvcReact: ({
       }
     }
 
-    const store: Store<any> = yield* createStore({
-      schema,
-      storeId: 'default',
-      adapter: makeInMemoryAdapter(),
-      debug: { instanceId: 'test' },
-    })
+    const store = yield* createTodoMvcStore(opts)
 
     const storeWithReactApi = LiveStoreReact.withReactApi(store)
 
-    // TODO improve typing of `LiveStoreContext`
-    const storeContext = {
-      stage: 'running' as const,
-      store: storeWithReactApi,
-    }
-
-    const MaybeStrictMode = strictMode ? React.StrictMode : React.Fragment
+    const MaybeStrictMode = strictMode === true ? React.StrictMode : React.Fragment
 
-    const wrapper = ({ children }: any) => (
-      <MaybeStrictMode>
-        <LiveStoreReact.LiveStoreContext.Provider value={storeContext}>
-          {children}
-        </LiveStoreReact.LiveStoreContext.Provider>
-      </MaybeStrictMode>
-    )
+    const wrapper = ({ children }: any) => <MaybeStrictMode>{children}</MaybeStrictMode>
 
     const renderCount = makeRenderCount()
 
     return { wrapper, store: storeWithReactApi, renderCount }
-  }).pipe(provideOtel(omitUndefineds({ parentSpanContext: otelContext, otelTracer })))
+  })

package/src/experimental/components/LiveList.tsx

@@ -1,8 +1,9 @@
-import type { LiveQueryDef } from '@livestore/livestore'
-import { computed } from '@livestore/livestore'
 import React from 'react'
 
-import { useQuery } from '../../useQuery.js'
+import type { LiveQueryDef, Store } from '@livestore/livestore'
+import { computed } from '@livestore/livestore'
+
+import { useQuery } from '../../useQuery.ts'
 
 /*
 TODO:
@@ -16,6 +17,8 @@ export type LiveListProps<TItem> = {
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
   /** Needs to be unique across all list items */
   getKey: (item: TItem, index: number) => string | number
+  /** The store instance to use for queries */
+  store: Store<any, any>
 }
 
 /**
@@ -26,12 +29,15 @@ export type LiveListProps<TItem> = {
  * In the future we want to make this component even more efficient by using incremental rendering (https://github.com/livestorejs/livestore/pull/55)
  * e.g. when an item is added/removed/moved to only re-render the affected DOM nodes.
  */
-export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<TItem>): React.ReactNode => {
+export const LiveList = <TItem,>({ items$, renderItem, getKey, store }: LiveListProps<TItem>): React.ReactNode => {
   const [hasMounted, setHasMounted] = React.useState(false)
 
   React.useEffect(() => setHasMounted(true), [])
 
-  const keys = useQuery(computed((get) => get(items$).map(getKey)))
+  const keys = useQuery(
+    computed((get) => get(items$).map(getKey)),
+    { store },
+  )
   const arr = React.useMemo(
     () =>
       keys.map(
@@ -54,7 +60,9 @@ export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<T
           key={key}
           itemKey={key}
           item$={item$}
-          opts={{ isInitialListRender: !hasMounted, index }}
+          store={store}
+          index={index}
+          isInitialListRender={!hasMounted}
           renderItem={renderItem}
         />
       ))}
@@ -64,15 +72,20 @@ export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<T
 
 const ItemWrapper = <TItem,>({
   item$,
-  opts,
+  index,
+  isInitialListRender,
   renderItem,
+  store,
 }: {
   itemKey: string | number
   item$: LiveQueryDef<TItem>
-  opts: { index: number; isInitialListRender: boolean }
+  index: number
+  isInitialListRender: boolean
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
+  store: Store<any, any>
 }) => {
-  const item = useQuery(item$)
+  const item = useQuery(item$, { store })
+  const opts = React.useMemo(() => ({ index, isInitialListRender }), [index, isInitialListRender])
 
   return <>{renderItem(item, opts)}</>
 }
@@ -82,6 +95,7 @@ const ItemWrapperMemo = React.memo(
   (prev, next) =>
     prev.itemKey === next.itemKey &&
     prev.renderItem === next.renderItem &&
-    prev.opts.index === next.opts.index &&
-    prev.opts.isInitialListRender === next.opts.isInitialListRender,
+    prev.store === next.store &&
+    prev.index === next.index &&
+    prev.isInitialListRender === next.isInitialListRender,
 ) as typeof ItemWrapper

package/src/mod.ts

@@ -1,13 +1,9 @@
-export { LiveStoreContext, type ReactApi } from './LiveStoreContext.ts'
-export { LiveStoreProvider } from './LiveStoreProvider.tsx'
-export {
-  type Dispatch,
-  type SetStateAction,
-  type SetStateActionPartial,
-  type StateSetters,
-  type UseClientDocumentResult,
-  useClientDocument,
-} from './useClientDocument.ts'
+export type { Dispatch, SetStateAction, SetStateActionPartial, StateSetters } from '@livestore/framework-toolkit'
+export { captureStackInfo } from '@livestore/framework-toolkit'
+export { StoreRegistry, storeOptions } from '@livestore/livestore'
+export { LiveList, type LiveListProps } from './experimental/components/LiveList.tsx'
+export * from './StoreRegistryContext.tsx'
+export { type UseClientDocumentResult, useClientDocument } from './useClientDocument.ts'
 export { useQuery, useQueryRef } from './useQuery.ts'
-export { useStore, withReactApi } from './useStore.ts'
-export { useStackInfo } from './utils/stack-info.ts'
+export { type ReactApi, useStore, withReactApi } from './useStore.ts'
+export { useSyncStatus } from './useSyncStatus.ts'

package/src/useClientDocument.test.tsx

@@ -1,28 +1,29 @@
-/** biome-ignore-all lint/a11y/useValidAriaRole: not needed for testing */
-/** biome-ignore-all lint/a11y/noStaticElementInteractions: not needed for testing */
-import * as LiveStore from '@livestore/livestore'
-import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
-import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
-import { Vitest } from '@livestore/utils-dev/node-vitest'
 import * as otel from '@opentelemetry/api'
 import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
 import * as ReactTesting from '@testing-library/react'
-import type React from 'react'
+import * as React from 'react'
 import { beforeEach, expect, it } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import type * as LiveStoreReact from './mod.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import * as LiveStore from '@livestore/livestore'
+import { StoreInternalsSymbol } from '@livestore/livestore'
+import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
+
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.tsx'
+import type * as LiveStoreReact from './mod.ts'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
 
 // const strictMode = process.env.REACT_STRICT_MODE !== undefined
 
 // NOTE running tests concurrently doesn't work with the default global db graph
+/** Verifies: LS.SYS.INT.REACT-R01, LS.SYS.STATE.SQLITE-R07 */
 Vitest.describe('useClientDocument', () => {
   beforeEach(() => {
     __resetUseRcResourceCache()
   })
 
-  Vitest.scopedLive('should update the data based on component key', () =>
+  Vitest.live('should update the data based on component key', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -39,12 +40,12 @@ Vitest.describe('useClientDocument', () => {
       expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       store.commit(tables.userInfo.set({ username: 'username_u2' }, 'u2'))
 
       rerender('u2')
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       expect(result.current.id).toBe('u2')
       expect(result.current.state.username).toBe('username_u2')
       expect(renderCount.val).toBe(2)
@@ -53,7 +54,7 @@ Vitest.describe('useClientDocument', () => {
 
   // TODO add a test that makes sure React doesn't re-render when a setter is used to set the same value
 
-  Vitest.scopedLive('should update the data reactively - via setState', () =>
+  Vitest.live('should update the data reactively - via setState', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -79,7 +80,7 @@ Vitest.describe('useClientDocument', () => {
     }),
   )
 
-  Vitest.scopedLive('should update the data reactively - via raw store commit', () =>
+  Vitest.live('should update the data reactively - via raw store commit', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -105,7 +106,7 @@ Vitest.describe('useClientDocument', () => {
     }),
   )
 
-  Vitest.scopedLive('should work for a larger app', () =>
+  Vitest.live('should work for a larger app', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -119,25 +120,39 @@ Vitest.describe('useClientDocument', () => {
         renderCount.inc()
 
         const [state, setState] = store.useClientDocument(tables.AppRouterSchema, 'singleton')
+        const setCurrentTaskId = React.useCallback((taskId: string) => setState({ currentTaskId: taskId }), [setState])
 
         globalSetState = setState
 
         return (
           <div>
-            <TasksList setTaskId={(taskId) => setState({ currentTaskId: taskId })} />
+            <TasksList setTaskId={setCurrentTaskId} />
             <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>}
+            {state.currentTaskId !== null ? (
+              <TaskDetails id={state.currentTaskId} />
+            ) : (
+              <div>Click on a task to see details</div>
+            )}
           </div>
         )
       }
 
       const TasksList: React.FC<{ setTaskId: (_: string) => void }> = ({ setTaskId }) => {
         const allTodos = store.useQuery(allTodos$)
+        const handleTaskClick = React.useCallback(
+          (event: React.MouseEvent<HTMLDivElement>) => {
+            const taskId = event.currentTarget.dataset.taskId
+            if (taskId !== undefined) {
+              setTaskId(taskId)
+            }
+          },
+          [setTaskId],
+        )
 
         return (
           <div>
             {allTodos.map((_) => (
-              <div key={_.id} onClick={() => setTaskId(_.id)}>
+              <div key={_.id} data-task-id={_.id} onClick={handleTaskClick}>
                 {_.id}
               </div>
             ))}
@@ -181,7 +196,7 @@ Vitest.describe('useClientDocument', () => {
     }),
   )
 
-  Vitest.scopedLive('should work for a useClientDocument query chained with a useTemporary query', () =>
+  Vitest.live('should work for a useClientDocument query chained with a useTemporary query', () =>
     Effect.gen(function* () {
       const { store, wrapper, renderCount } = yield* makeTodoMvcReact({})
 
@@ -224,7 +239,7 @@ Vitest.describe('useClientDocument', () => {
     }),
   )
 
-  Vitest.scopedLive('kv client document overwrites value (Schema.Any, no partial merge)', () =>
+  Vitest.live('kv client document overwrites value (Schema.Any, no partial merge)', () =>
     Effect.gen(function* () {
       const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
@@ -262,7 +277,7 @@ Vitest.describe('useClientDocument', () => {
           spanProcessors: [new SimpleSpanProcessor(exporter)],
         })
 
-        const otelTracer = provider.getTracer(`testing-${strictMode ? 'strict' : 'non-strict'}`)
+        const otelTracer = provider.getTracer(`testing-${strictMode !== undefined ? 'strict' : 'non-strict'}`)
 
         const span = otelTracer.startSpan('test-root')
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
@@ -312,7 +327,7 @@ Vitest.describe('useClientDocument', () => {
               const stackInfo = JSON.parse(val as string) as LiveStore.StackInfo
               // stackInfo.frames.shift() // Removes `renderHook.wrapper` from the stack
               stackInfo.frames.forEach((_) => {
-                if (_.name.includes('renderHook.wrapper')) {
+                if (_.name.includes('renderHook.wrapper') === true) {
                   _.name = 'renderHook.wrapper'
                 }
                 _.filePath = '__REPLACED_FOR_SNAPSHOT__'

package/src/useClientDocument.ts

@@ -1,14 +1,26 @@
+import React from 'react'
+
 import type { RowQuery } from '@livestore/common'
 import { SessionIdSymbol } from '@livestore/common'
 import { State } from '@livestore/common/schema'
+import { removeUndefinedValues, type StateSetters, validateTableOptions } from '@livestore/framework-toolkit'
 import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
 import { queryDb } from '@livestore/livestore'
 import { omitUndefineds, shouldNeverHappen } from '@livestore/utils'
-import React from 'react'
 
-import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useQueryRef } from './useQuery.ts'
 
+/**
+ * Return type of `useClientDocument` hook.
+ *
+ * A tuple providing React-style state access to a client-document table row:
+ * - `[0]` row: The current value (decoded according to the table schema)
+ * - `[1]` setRow: Setter function to update the document
+ * - `[2]` id: The document's ID (resolved from `SessionIdSymbol` if applicable)
+ * - `[3]` query$: The underlying `LiveQuery` for advanced use cases
+ *
+ * @typeParam TTableDef - The client-document table definition type
+ */
 export type UseClientDocumentResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
   row: TTableDef['Value'],
   setRow: StateSetters<TTableDef>,
@@ -104,20 +116,15 @@ export const useClientDocument: {
 
   const tableName = table.sqliteDef.name
 
-  const store =
-    storeArg?.store ?? // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
-    React.useContext(LiveStoreContext)?.store ??
-    shouldNeverHappen(`No store provided to useClientDocument`)
+  const store = storeArg?.store ?? shouldNeverHappen(`No store provided to useClientDocument`)
 
-  // console.debug('useClientDocument', tableName, id)
-
-  const idStr: string = id === SessionIdSymbol ? store.clientSession.sessionId : id
+  const idStr: string = id === SessionIdSymbol ? store.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)],
+      queryDb(table.get(id, { default: defaultValues! }), {
+        deps: [idStr, table.sqliteDef.name, JSON.stringify(defaultValues)],
       }),
     [table, id, defaultValues, idStr],
   )
@@ -132,36 +139,10 @@ export const useClientDocument: {
       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))
+      store.commit(table.set(removeUndefinedValues(newValue), id))
     },
     [id, queryRef.valueRef, store, table],
   )
 
   return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value]
 }
-
-export type Dispatch<A> = (action: A) => void
-export type SetStateActionPartial<S> = Partial<S> | ((previousValue: S) => Partial<S>)
-export type SetStateAction<S> = S | ((previousValue: S) => S)
-
-export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
-  TTableDef[State.SQLite.ClientDocumentTableDefSymbol]['options']['partialSet'] extends false
-    ? SetStateAction<TTableDef['Value']>
-    : SetStateActionPartial<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
-}