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

package/src/store/devtools.ts

@@ -7,8 +7,8 @@ import { nanoid } from '@livestore/utils/nanoid'
 
 import { NOT_REFRESHED_YET } from '../reactive.ts'
 import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.ts'
-import type { Store } from './store.ts'
 import { StoreInternalsSymbol } from './store-types.ts'
+import type { Store } from './store.ts'
 
 type Unsub = () => void
 type RequestId = string
@@ -23,7 +23,7 @@ const requestNextTick: (cb: () => void) => number =
 const cancelTick: (id: number) => void =
   globalThis.cancelAnimationFrame === undefined ? (id: number) => clearTimeout(id) : globalThis.cancelAnimationFrame
 
-export const connectDevtoolsToStore = ({
+export const connectDevtoolsToStore = Effect.fn('LSD.devtools.connectStoreToDevtools')(function* ({
   storeDevtoolsChannel,
   store,
 }: {
@@ -32,8 +32,7 @@ export const connectDevtoolsToStore = ({
     Devtools.ClientSession.MessageFromApp
   >
   store: Store
-}) =>
-  Effect.gen(function* () {
+}) {
     const reactivityGraphSubcriptions: SubMap = new Map()
     const liveQueriesSubscriptions: SubMap = new Map()
     const debugInfoHistorySubscriptions: SubMap = new Map()
@@ -88,7 +87,7 @@ export const connectDevtoolsToStore = ({
       // So far I could only observe this problem with webmesh proxy channels (e.g. for Expo)
       // Proof: https://share.cleanshot.com/V9G87B0B
       // Also see `leader-worker-devtools.ts` for same problem
-      if (handledRequestIds.has(requestId)) {
+      if (handledRequestIds.has(requestId) === true) {
         return
       }
 
@@ -235,6 +234,7 @@ export const connectDevtoolsToStore = ({
                 sendToDevtools(
                   Devtools.ClientSession.LiveQueriesRes.make({
                     liveQueries: [...store[StoreInternalsSymbol].activeQueries].map((q) => ({
+                      /** TODO: include schema metadata for schema-aware rendering in devtools (e.g., schema AST/hash/identifier or table+columns for QueryBuilder-derived queries). */
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
@@ -316,6 +316,20 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.Ping': {
+          // Check version mismatch and respond with VersionMismatch if versions don't match
+          if (decodedMessage.liveStoreVersion !== liveStoreVersion) {
+            sendToDevtools(
+              Devtools.ClientSession.VersionMismatch.make({
+                requestId,
+                clientId,
+                sessionId,
+                liveStoreVersion,
+                appVersion: liveStoreVersion,
+                receivedVersion: decodedMessage.liveStoreVersion,
+              }),
+            )
+            break
+          }
           sendToDevtools(Devtools.ClientSession.Pong.make({ requestId, clientId, sessionId, liveStoreVersion }))
           break
         }
@@ -332,4 +346,4 @@ export const connectDevtoolsToStore = ({
       Stream.runDrain,
       Effect.withSpan('LSD.devtools.onMessage'),
     )
-  }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('LSD.devtools.connectStoreToDevtools'))
+}, UnknownError.mapToUnknownError)

package/src/store/store-eventstream.test.ts

@@ -1,3 +1,5 @@
+import { expect } from 'vitest'
+
 import { makeInMemoryAdapter } from '@livestore/adapter-web'
 import type { MockSyncBackend } from '@livestore/common'
 import { type ClientSessionLeaderThreadProxy, makeMockSyncBackend, type UnknownError } from '@livestore/common'
@@ -6,12 +8,12 @@ import { EventFactory } from '@livestore/common/testing'
 import type { ShutdownDeferred, Store } from '@livestore/livestore'
 import { createStore, makeShutdownDeferred } from '@livestore/livestore'
 import { omitUndefineds } from '@livestore/utils'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
 import type { OtelTracer, Scope } from '@livestore/utils/effect'
 import { Context, Effect, FetchHttpClient, Layer, Logger, LogLevel, Queue, Stream } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
 import { PlatformNode } from '@livestore/utils/node'
-import { Vitest } from '@livestore/utils-dev/node-vitest'
-import { expect } from 'vitest'
+
 import { events, schema } from '../utils/tests/fixture.ts'
 
 const withTestCtx = Vitest.makeWithTestCtx({

package/src/store/store-types.test.ts

@@ -1,7 +1,9 @@
+import { describe, expect, it } from 'vitest'
+
 import type { QueryBuilder } from '@livestore/common'
 import { QueryBuilderTypeId } from '@livestore/common'
 import { Schema } from '@livestore/utils/effect'
-import { describe, expect, it } from 'vitest'
+
 import { TypeId } from '../live-queries/base-class.ts'
 import { queryDb, signal } from '../live-queries/mod.ts'
 import { isQueryable } from './store-types.ts'

package/src/store/store-types.ts

@@ -1,22 +1,22 @@
+import type * as otel from '@opentelemetry/api'
+
 import {
   type ClientSession,
   type ClientSessionSyncProcessor,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
-  type InvalidPullError,
-  type IsOfflineError,
   isQueryBuilder,
   type MaterializeError,
   type QueryBuilder,
   type StoreInterrupted,
-  type SyncError,
+  type BackendIdMismatchError,
   type UnknownError,
 } from '@livestore/common'
 import type { StreamEventsOptions } from '@livestore/common/leader-thread'
 import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
 import type { Effect, Runtime, Schema, Scope } from '@livestore/utils/effect'
 import { Deferred, Predicate } from '@livestore/utils/effect'
-import type * as otel from '@opentelemetry/api'
+
 import type {
   LiveQuery,
   LiveQueryDef,
@@ -38,25 +38,27 @@ import type { Store } from './store.ts'
  * - `running`: Store is active and ready for queries/commits
  * - `error`: Store failed during boot or operation
  * - `shutdown`: Store was intentionally shut down or interrupted
+ *
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`.
  */
-export type LiveStoreContext =
-  | LiveStoreContextRunning
+export type LiveStoreContext<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> =
+  | LiveStoreContextRunning<TSchema>
   | {
       stage: 'error'
-      error: UnknownError | unknown
+      error: unknown
     }
   | {
       stage: 'shutdown'
-      cause: IntentionalShutdownCause | StoreInterrupted | SyncError
+      cause: IntentionalShutdownCause | StoreInterrupted | UnknownError
     }
 
 export type ShutdownDeferred = Deferred.Deferred<
   IntentionalShutdownCause,
-  UnknownError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError
+  UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError
 >
 export const makeShutdownDeferred: Effect.Effect<ShutdownDeferred> = Deferred.make<
   IntentionalShutdownCause,
-  UnknownError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError
+  UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError
 >()
 
 /**
@@ -64,10 +66,14 @@ export const makeShutdownDeferred: Effect.Effect<ShutdownDeferred> = Deferred.ma
  *
  * This is the normal operating state where you can query data, commit events,
  * and subscribe to changes.
+ *
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`
+ *   for backwards compatibility, but prefer providing the concrete schema type
+ *   for full type safety.
  */
-export type LiveStoreContextRunning = {
+export type LiveStoreContextRunning<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = {
   stage: 'running'
-  store: Store
+  store: Store<TSchema>
 }
 
 export type OtelOptions = {
@@ -170,7 +176,13 @@ export type StoreInternals = {
   isShutdown: boolean
 }
 
-export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
+/**
+ * Parameters for constructing a Store instance.
+ *
+ * @internal This type is used by the Store constructor and is not part of the public API.
+ * For creating stores, use `createStore()` or `StoreRegistry` instead.
+ */
+export type StoreConstructorParams<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
   clientSession: ClientSession
   schema: TSchema
   storeId: string
@@ -404,3 +416,42 @@ export const isLiveQueryInstance = (value: unknown): value is LiveQuery<any> =>
  */
 export const isQueryable = (value: unknown): value is Queryable<unknown> =>
   isQueryBuilder(value) || isLiveQueryInstance(value) || isLiveQueryDef(value)
+
+/**
+ * Represents the current synchronization status of the store.
+ *
+ * This provides visibility into the sync state between the client session
+ * and the leader thread, allowing applications to show sync indicators
+ * or determine backend health.
+ *
+ * @example
+ * ```ts
+ * const status = store.syncStatus()
+ * if (status.isSynced) {
+ *   console.log('All changes synced')
+ * } else {
+ *   console.log(`${status.pendingCount} events pending sync`)
+ * }
+ * ```
+ */
+export type SyncStatus = {
+  /**
+   * The local head sequence number (most recent event in the client session).
+   * Represented as a string in the format "e{global}.{client}" (e.g., "e5.2").
+   */
+  localHead: string
+  /**
+   * The upstream head sequence number (what the leader thread has confirmed).
+   * Represented as a string in the format "e{global}" (e.g., "e3").
+   */
+  upstreamHead: string
+  /**
+   * Number of events pending synchronization to the leader thread.
+   */
+  pendingCount: number
+  /**
+   * Whether the client session is fully synced with the leader thread.
+   * True when there are no pending events (pendingCount === 0).
+   */
+  isSynced: boolean
+}