@livestore/react 0.4.0-dev.21 → 0.4.0-dev.23

package/dist/useSyncStatus.js

@@ -0,0 +1,28 @@
+import React from 'react';
+/**
+ * React hook that subscribes to sync status changes.
+ *
+ * Returns the current synchronization status between the client session and
+ * the leader thread. The component re-renders whenever the sync status changes.
+ *
+ * @example
+ * ```tsx
+ * function SyncIndicator() {
+ *   const status = store.useSyncStatus()
+ *   return <span>{status.isSynced ? '✓ Synced' : `Syncing (${status.pendingCount} pending)...`}</span>
+ * }
+ * ```
+ *
+ * @param options - Options containing the store instance
+ * @returns The current sync status
+ */
+export const useSyncStatus = (options) => {
+    const { store } = options;
+    const [status, setStatus] = React.useState(() => store.syncStatus());
+    React.useEffect(() => {
+        return store.subscribeSyncStatus(setStatus);
+    }, [store]);
+    React.useDebugValue(`LiveStore:useSyncStatus:${status.isSynced === true ? 'synced' : 'pending'}`);
+    return status;
+};
+//# sourceMappingURL=useSyncStatus.js.map

package/dist/useSyncStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSyncStatus.js","sourceRoot":"","sources":["../src/useSyncStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAIzB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAA8B,EAAc,EAAE;IAC1E,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEzB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAa,GAAG,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAA;IAEhF,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,OAAO,KAAK,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAA;IAC7C,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IAEX,KAAK,CAAC,aAAa,CAAC,2BAA2B,MAAM,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA;IAEjG,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/package.json

@@ -1,45 +1,88 @@
 {
   "name": "@livestore/react",
-  "version": "0.4.0-dev.21",
+  "version": "0.4.0-dev.23",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livestorejs/livestore.git"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "src"
+  ],
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": "./dist/mod.js",
     "./experimental": "./dist/experimental/mod.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/common": "0.4.0-dev.21",
-    "@livestore/utils": "0.4.0-dev.21",
-    "@livestore/livestore": "0.4.0-dev.21"
+    "@livestore/common": "^0.4.0-dev.23",
+    "@livestore/framework-toolkit": "^0.4.0-dev.23",
+    "@livestore/livestore": "^0.4.0-dev.23",
+    "@livestore/utils": "^0.4.0-dev.23"
   },
   "devDependencies": {
-    "@opentelemetry/sdk-trace-base": "2.0.1",
-    "@testing-library/dom": "^10.4.1",
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "19.1.13",
-    "@types/react-dom": "19.1.9",
-    "jsdom": "^26.1.0",
-    "react": "19.1.0",
-    "react-dom": "19.1.0",
-    "react-window": "^1.8.11",
-    "typescript": "5.9.2",
-    "vite": "7.2.4",
+    "@opentelemetry/sdk-trace-base": "2.2.0",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.3.1",
+    "@types/react": "19.2.7",
+    "@types/react-dom": "19.2.3",
+    "@types/react-window": "1.8.8",
+    "jsdom": "26.1.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-window": "1.8.11",
+    "typescript": "5.9.3",
+    "vite": "7.3.1",
     "vitest": "3.2.4",
-    "@livestore/adapter-web": "0.4.0-dev.21",
-    "@livestore/utils-dev": "0.4.0-dev.21"
+    "@livestore/adapter-web": "^0.4.0-dev.23",
+    "@livestore/utils-dev": "^0.4.0-dev.23"
   },
-  "files": [
-    "package.json",
-    "src",
-    "dist"
-  ],
-  "license": "Apache-2.0",
   "peerDependencies": {
-    "react": "^19.1.0"
+    "@effect/ai": "^0.35.0",
+    "@effect/cli": "^0.75.1",
+    "@effect/cluster": "^0.58.2",
+    "@effect/experimental": "^0.60.0",
+    "@effect/opentelemetry": "^0.63.0",
+    "@effect/platform": "^0.96.1",
+    "@effect/platform-browser": "^0.76.0",
+    "@effect/platform-bun": "^0.89.0",
+    "@effect/platform-node": "^0.106.0",
+    "@effect/printer": "^0.49.0",
+    "@effect/printer-ansi": "^0.49.0",
+    "@effect/rpc": "^0.75.1",
+    "@effect/sql": "^0.51.1",
+    "@effect/typeclass": "^0.40.0",
+    "@effect/vitest": "^0.29.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@standard-schema/spec": "^1.1.0",
+    "effect": "^3.21.2",
+    "react": "^19.0.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "$genie": {
+    "source": "package.json.genie.ts",
+    "warning": "DO NOT EDIT - changes will be overwritten",
+    "workspaceClosureDirs": [
+      "packages/@livestore/adapter-web",
+      "packages/@livestore/common",
+      "packages/@livestore/common-cf",
+      "packages/@livestore/devtools-web-common",
+      "packages/@livestore/framework-toolkit",
+      "packages/@livestore/livestore",
+      "packages/@livestore/react",
+      "packages/@livestore/sqlite-wasm",
+      "packages/@livestore/utils",
+      "packages/@livestore/utils-dev",
+      "packages/@livestore/wa-sqlite",
+      "packages/@livestore/webmesh"
+    ]
   },
   "scripts": {
     "build": "tsc",

package/src/StoreRegistryContext.tsx

@@ -0,0 +1,70 @@
+import * as React from 'react'
+
+import type { StoreRegistry } from '@livestore/livestore'
+
+export const StoreRegistryContext = React.createContext<StoreRegistry | undefined>(undefined)
+
+export type StoreRegistryProviderProps = {
+  storeRegistry: StoreRegistry
+  children: React.ReactNode
+}
+
+/**
+ * React context provider that makes a {@link StoreRegistry} available to descendant components.
+ *
+ * Wrap your application (or a subtree) with this provider to enable {@link useStore} and
+ * {@link useStoreRegistry} hooks within that tree.
+ *
+ * @example
+ * ```tsx
+ * import { StoreRegistry } from '@livestore/livestore'
+ * import { StoreRegistryProvider } from '@livestore/react'
+ * import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
+ *
+ * const storeRegistry = new StoreRegistry({
+ *   defaultOptions: { batchUpdates }
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <StoreRegistryProvider storeRegistry={storeRegistry}>
+ *       <MyComponent />
+ *     </StoreRegistryProvider>
+ *   )
+ * }
+ * ```
+ */
+export const StoreRegistryProvider = ({ storeRegistry, children }: StoreRegistryProviderProps): React.JSX.Element => {
+  return <StoreRegistryContext value={storeRegistry}>{children}</StoreRegistryContext>
+}
+
+/**
+ * Hook to access the {@link StoreRegistry} from context. Useful for advanced operations like preloading.
+ *
+ * @param override - Optional registry to use instead of the context value.
+ *   When provided, skips context lookup entirely.
+ * @returns The registry provided by the nearest {@link StoreRegistryProvider} ancestor, or the `override` if provided.
+ * @throws Error if called outside a {@link StoreRegistryProvider} and no override is provided
+ *
+ * @example
+ * ```tsx
+ * function PreloadButton({ issueId }: { issueId: string }) {
+ *   const storeRegistry = useStoreRegistry()
+ *
+ *   const handleMouseEnter = () => {
+ *     storeRegistry.preload(issueStoreOptions(issueId))
+ *   }
+ *
+ *   return <button onMouseEnter={handleMouseEnter}>View Issue</button>
+ * }
+ * ```
+ */
+export const useStoreRegistry = (override?: StoreRegistry) => {
+  if (override !== undefined) return override
+
+  const storeRegistry = React.use(StoreRegistryContext)
+
+  if (storeRegistry == null) throw new Error('useStoreRegistry() must be used within <StoreRegistryProvider>')
+
+  return storeRegistry
+}

package/src/__snapshots__/useClientDocument.test.tsx.snap

@@ -8,6 +8,9 @@ exports[`useClientDocument > otel > should update the data based on component ke
     "storeId": "default",
   },
   "children": [
+    {
+      "_name": "makeClientSessionSyncProcessor",
+    },
     {
       "_name": "livestore.in-memory-db:execute",
       "attributes": {
@@ -21,29 +24,31 @@ exports[`useClientDocument > otel > should update the data based on component ke
       },
     },
     {
-      "_name": "@livestore/common:LeaderSyncProcessor:push",
-      "attributes": {
-        "batch": "undefined",
-        "batchSize": 1,
-      },
-    },
-    {
-      "_name": "@livestore/common:LeaderSyncProcessor:push",
-      "attributes": {
-        "batch": "undefined",
-        "batchSize": 1,
-      },
-    },
-    {
-      "_name": "client-session-sync-processor:pull",
-      "attributes": {
-        "code.stacktrace": "<STACKTRACE>",
-        "span.label": "⚠︎ Interrupted",
-        "status.interrupted": true,
-      },
-    },
-    {
-      "_name": "LiveStore:sync",
+      "_name": "client-session-sync-processor:boot",
+      "children": [
+        {
+          "_name": "@livestore/common:LeaderSyncProcessor:push",
+          "attributes": {
+            "batch": "undefined",
+            "batchSize": 1,
+          },
+        },
+        {
+          "_name": "@livestore/common:LeaderSyncProcessor:push",
+          "attributes": {
+            "batch": "undefined",
+            "batchSize": 1,
+          },
+        },
+        {
+          "_name": "client-session-sync-processor:pull",
+          "attributes": {
+            "code.stacktrace": "<STACKTRACE>",
+            "span.label": "⚠︎ Interrupted",
+            "status.interrupted": true,
+          },
+        },
+      ],
     },
     {
       "_name": "LiveStore:commits",
@@ -194,14 +199,10 @@ exports[`useClientDocument > otel > should update the data based on component ke
     },
     "children": [
       {
-        "_name": "client-session-sync-processor:push",
-        "attributes": {
-          "batchSize": 1,
-          "eventCounts": "{
-  "UserInfoSet": 1
-}",
-          "mergeResultTag": "advance",
-        },
+        "_name": "client-session-sync-processor:encode-events",
+      },
+      {
+        "_name": "client-session-sync-processor:materialize-events",
         "children": [
           {
             "_name": "client-session-sync-processor:materialize-event",
@@ -220,6 +221,16 @@ exports[`useClientDocument > otel > should update the data based on component ke
           },
         ],
       },
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "UserInfoSet": 1
+}",
+          "mergeResultTag": "advance",
+        },
+      },
     ],
   },
   {
@@ -232,14 +243,10 @@ exports[`useClientDocument > otel > should update the data based on component ke
     },
     "children": [
       {
-        "_name": "client-session-sync-processor:push",
-        "attributes": {
-          "batchSize": 1,
-          "eventCounts": "{
-  "UserInfoSet": 1
-}",
-          "mergeResultTag": "advance",
-        },
+        "_name": "client-session-sync-processor:encode-events",
+      },
+      {
+        "_name": "client-session-sync-processor:materialize-events",
         "children": [
           {
             "_name": "client-session-sync-processor:materialize-event",
@@ -258,6 +265,16 @@ exports[`useClientDocument > otel > should update the data based on component ke
           },
         ],
       },
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "UserInfoSet": 1
+}",
+          "mergeResultTag": "advance",
+        },
+      },
     ],
   },
 ]
@@ -271,6 +288,9 @@ exports[`useClientDocument > otel > should update the data based on component ke
     "storeId": "default",
   },
   "children": [
+    {
+      "_name": "makeClientSessionSyncProcessor",
+    },
     {
       "_name": "livestore.in-memory-db:execute",
       "attributes": {
@@ -284,29 +304,31 @@ exports[`useClientDocument > otel > should update the data based on component ke
       },
     },
     {
-      "_name": "@livestore/common:LeaderSyncProcessor:push",
-      "attributes": {
-        "batch": "undefined",
-        "batchSize": 1,
-      },
-    },
-    {
-      "_name": "@livestore/common:LeaderSyncProcessor:push",
-      "attributes": {
-        "batch": "undefined",
-        "batchSize": 1,
-      },
-    },
-    {
-      "_name": "client-session-sync-processor:pull",
-      "attributes": {
-        "code.stacktrace": "<STACKTRACE>",
-        "span.label": "⚠︎ Interrupted",
-        "status.interrupted": true,
-      },
-    },
-    {
-      "_name": "LiveStore:sync",
+      "_name": "client-session-sync-processor:boot",
+      "children": [
+        {
+          "_name": "@livestore/common:LeaderSyncProcessor:push",
+          "attributes": {
+            "batch": "undefined",
+            "batchSize": 1,
+          },
+        },
+        {
+          "_name": "@livestore/common:LeaderSyncProcessor:push",
+          "attributes": {
+            "batch": "undefined",
+            "batchSize": 1,
+          },
+        },
+        {
+          "_name": "client-session-sync-processor:pull",
+          "attributes": {
+            "code.stacktrace": "<STACKTRACE>",
+            "span.label": "⚠︎ Interrupted",
+            "status.interrupted": true,
+          },
+        },
+      ],
     },
     {
       "_name": "LiveStore:commits",
@@ -395,14 +417,10 @@ exports[`useClientDocument > otel > should update the data based on component ke
     },
     "children": [
       {
-        "_name": "client-session-sync-processor:push",
-        "attributes": {
-          "batchSize": 1,
-          "eventCounts": "{
-  "UserInfoSet": 1
-}",
-          "mergeResultTag": "advance",
-        },
+        "_name": "client-session-sync-processor:encode-events",
+      },
+      {
+        "_name": "client-session-sync-processor:materialize-events",
         "children": [
           {
             "_name": "client-session-sync-processor:materialize-event",
@@ -421,6 +439,16 @@ exports[`useClientDocument > otel > should update the data based on component ke
           },
         ],
       },
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "UserInfoSet": 1
+}",
+          "mergeResultTag": "advance",
+        },
+      },
     ],
   },
   {
@@ -433,14 +461,10 @@ exports[`useClientDocument > otel > should update the data based on component ke
     },
     "children": [
       {
-        "_name": "client-session-sync-processor:push",
-        "attributes": {
-          "batchSize": 1,
-          "eventCounts": "{
-  "UserInfoSet": 1
-}",
-          "mergeResultTag": "advance",
-        },
+        "_name": "client-session-sync-processor:encode-events",
+      },
+      {
+        "_name": "client-session-sync-processor:materialize-events",
         "children": [
           {
             "_name": "client-session-sync-processor:materialize-event",
@@ -459,6 +483,16 @@ exports[`useClientDocument > otel > should update the data based on component ke
           },
         ],
       },
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "UserInfoSet": 1
+}",
+          "mergeResultTag": "advance",
+        },
+      },
     ],
   },
 ]

package/src/__tests__/fixture.tsx

@@ -1,110 +1,32 @@
-import { makeInMemoryAdapter } from '@livestore/adapter-web'
-import { provideOtel, type UnknownError } 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 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 React from 'react'
 
 import * as LiveStoreReact from '../mod.ts'
 
-export type Todo = {
-  id: string
-  text: string
-  completed: boolean
-}
-
-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 }),
-  },
-})
+// Re-export shared types and schema
+export { events, schema, tables }
+export type { AppState, Filter, Todo }
 
-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 type MakeTodoMvcReactOptions = {
-  otelTracer?: otel.Tracer | undefined
-  otelContext?: otel.Context | undefined
+export type MakeTodoMvcReactOptions = CreateTodoMvcStoreOptions & {
   strictMode?: boolean | undefined
 }
 
 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 }
   },
   UnknownError,
@@ -116,7 +38,7 @@ export const makeTodoMvcReact: (opts?: MakeTodoMvcReactOptions) => Effect.Effect
       let val = 0
 
       const inc = () => {
-        val += strictMode ? 0.5 : 1
+        val += strictMode === true ? 0.5 : 1
       }
 
       return {
@@ -127,32 +49,15 @@ export const makeTodoMvcReact: (opts?: MakeTodoMvcReactOptions) => Effect.Effect
       }
     }
 
-    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: opts.otelContext, otelTracer: opts.otelTracer })))
+  })