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

package/dist/store/store-types.test.js

@@ -1,6 +1,6 @@
+import { describe, expect, it } from 'vitest';
 import { QueryBuilderTypeId } from '@livestore/common';
 import { Schema } from '@livestore/utils/effect';
-import { describe, expect, it } from 'vitest';
 import { TypeId } from "../live-queries/base-class.js";
 import { queryDb, signal } from "../live-queries/mod.js";
 import { isQueryable } from "./store-types.js";

package/dist/store/store-types.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-types.test.js","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,MAAM,gBAAgB,GAAG,GAAgC,EAAE,CACzD,CAAC;IACC,CAAC,kBAAkB,CAAC,EAAE,kBAAkB;IACxC,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;IACnF,QAAQ,EAAE,GAAG,EAAE,CAAC,UAAU;CAC3B,CAA2C,CAAA;AAE9C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,EAAE,mBAAmB;YAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;SAC9D,CAAC,CAAA;QAEF,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;QAEzC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,aAAa,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAW,CAAA;QAEnD,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAA;QAE7B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1C,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}
+{"version":3,"file":"store-types.test.js","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,MAAM,gBAAgB,GAAG,GAAgC,EAAE,CACzD,CAAC;IACC,CAAC,kBAAkB,CAAC,EAAE,kBAAkB;IACxC,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;IACnF,QAAQ,EAAE,GAAG,EAAE,CAAC,UAAU;CAC3B,CAA2C,CAAA;AAE9C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,EAAE,mBAAmB;YAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;SAC9D,CAAC,CAAA;QAEF,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;QAEzC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,aAAa,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAW,CAAA;QAEnD,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAA;QAE7B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1C,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/store/store.d.ts

@@ -1,10 +1,10 @@
-import { type Bindable, type ClientSession, MaterializeError, UnknownError } from '@livestore/common';
+import { type Bindable, type ClientSession, MaterializeError, type StorageMode, type SyncState, UnknownError } from '@livestore/common';
 import type { LiveStoreSchema } from '@livestore/common/schema';
 import { LiveStoreEvent } from '@livestore/common/schema';
 import { Cause, Effect, Inspectable, Schema, Stream } from '@livestore/utils/effect';
 import * as otel from '@opentelemetry/api';
 import type { SignalDef } from '../live-queries/base-class.ts';
-import { type Queryable, type RefreshReason, type StoreCommitOptions, type StoreEventsOptions, type StoreInternals, StoreInternalsSymbol, type StoreOptions, type SubscribeOptions, type Unsubscribe } from './store-types.ts';
+import { type Queryable, type RefreshReason, type StoreCommitOptions, type StoreConstructorParams, type StoreEventsOptions, type StoreInternals, StoreInternalsSymbol, type SubscribeOptions, type SyncStatus, type Unsubscribe } from './store-types.ts';
 export type SubscribeFn = {
     <TResult>(query: Queryable<TResult>, onUpdate: (value: TResult) => void, options?: SubscribeOptions<TResult>): Unsubscribe;
     <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): AsyncIterable<TResult>;
@@ -26,8 +26,8 @@ export declare const STORE_DEFAULT_PARAMS: {
  * ## Creating a Store
  *
  * Use `createStore` (Effect-based) or `createStorePromise` to obtain a Store instance.
- * In React applications, use the `<LiveStoreProvider>` component which manages the Store lifecycle
- * and exposes it via React context.
+ * In React applications, use `StoreRegistry` with `<StoreRegistryProvider>` and the `useStore()` hook
+ * which manages the Store lifecycle.
  *
  * ## Querying Data
  *
@@ -69,7 +69,7 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
     /** User-defined context attached to this Store (e.g. for dependency injection). */
     readonly context: TContext;
     /** Options provided to the Store constructor. */
-    readonly params: StoreOptions<TSchema, TContext>['params'];
+    readonly params: StoreConstructorParams<TSchema, TContext>['params'];
     /**
      * Reactive connectivity updates emitted by the backing sync backend.
      *
@@ -88,11 +88,28 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
      * ```
      */
     readonly networkStatus: ClientSession['leaderThread']['networkStatus'];
+    /**
+     * Indicates how data is being stored.
+     *
+     * - `persisted`: Data is persisted to disk (e.g., via OPFS on web, SQLite file on native)
+     * - `in-memory`: Data is only stored in memory and will be lost on page refresh
+     *
+     * The store operates in `in-memory` mode when persistent storage is unavailable,
+     * such as in Safari/Firefox private browsing mode where OPFS is restricted.
+     *
+     * @example
+     * ```tsx
+     * if (store.storageMode === 'in-memory') {
+     *   showWarning('Data will not be persisted in private browsing mode')
+     * }
+     * ```
+     */
+    readonly storageMode: StorageMode;
     /**
      * Store internals. Not part of the public API — shapes and semantics may change without notice.
      */
     readonly [StoreInternalsSymbol]: StoreInternals;
-    constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }: StoreOptions<TSchema, TContext>);
+    constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }: StoreConstructorParams<TSchema, TContext>);
     /**
      * Current session identifier for this Store instance.
      *
@@ -272,6 +289,65 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
      * See `store.events` for details on options and behaviour.
      */
     eventsStream: (options?: StoreEventsOptions<TSchema>) => Stream.Stream<LiveStoreEvent.Client.ForSchema<TSchema>, UnknownError>;
+    /**
+     * Returns the current synchronization status of the store.
+     *
+     * This is a synchronous operation that returns the sync state between the
+     * client session and the leader thread. Use this to display sync indicators
+     * or check if local changes have been pushed to the leader.
+     *
+     * @example
+     * ```ts
+     * const status = store.syncStatus()
+     * console.log(status.isSynced ? 'Synced' : `${status.pendingCount} pending`)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Health check for backend connectivity
+     * const status = store.syncStatus()
+     * if (!status.isSynced && status.pendingCount > 100) {
+     *   console.warn('Large backlog of unsynced events')
+     * }
+     * ```
+     */
+    syncStatus: () => SyncStatus;
+    /**
+     * Returns an Effect Stream of sync status updates.
+     *
+     * Emits the current status immediately and then whenever the sync state changes.
+     * Use this for Effect-based workflows or when you need more control over the stream.
+     *
+     * @example
+     * ```ts
+     * store.syncStatusStream().pipe(
+     *   Stream.tap((status) => Effect.log(`Sync status: ${status.isSynced}`)),
+     *   Stream.runDrain,
+     * )
+     * ```
+     */
+    syncStatusStream: () => Stream.Stream<SyncStatus>;
+    /**
+     * Subscribes to sync status changes.
+     *
+     * The callback is invoked immediately with the current status and then
+     * whenever the sync state changes (e.g., when events are pushed or confirmed).
+     *
+     * @param onUpdate - Callback invoked with the current sync status
+     * @returns Unsubscribe function to stop receiving updates
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = store.subscribeSyncStatus((status) => {
+     *   updateUI(status.isSynced ? 'Synced' : 'Syncing...')
+     * })
+     *
+     * // Later, stop listening
+     * unsubscribe()
+     * ```
+     */
+    subscribeSyncStatus: (onUpdate: (status: SyncStatus) => void) => Unsubscribe;
+    private makeSyncStatus;
     /**
      * This can be used in combination with `skipRefresh` when committing events.
      * We might need a better solution for this. Let's see.
@@ -291,6 +367,26 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
      * This is called automatically when the store was created using the React or Effect API.
      */
     shutdown: (cause?: Cause.Cause<UnknownError | MaterializeError>) => Effect.Effect<void>;
+    /**
+     * Helper methods useful during development
+     *
+     * @internal
+     */
+    _dev: {
+        downloadDb: (source?: "local" | "leader") => void;
+        downloadEventlogDb: () => void;
+        hardReset: (mode?: "all-data" | "only-app-db") => void;
+        overrideNetworkStatus: (status: "online" | "offline") => void;
+        syncStates: () => Promise<{
+            session: SyncState.SyncState;
+            leader: SyncState.SyncState;
+        }>;
+        printSyncStates: () => void;
+        version: string;
+        otel: {
+            rootSpanContext: () => otel.SpanContext | undefined;
+        };
+    };
     toJSON: () => {
         _tag: string;
         reactivityGraph: import("../reactive.ts").ReactiveGraphSnapshot;

package/dist/store/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}

package/dist/store/store.js

@@ -1,6 +1,6 @@
 import { Devtools, getExecStatementsFromMaterializer, getResultSchema, hashMaterializerResults, IntentionalShutdownCause, isQueryBuilder, liveStoreVersion, MaterializeError, MaterializerHashMismatchError, makeClientSessionSyncProcessor, prepareBindValues, QueryBuilderAstSymbol, replaceSessionIdSymbol, UnknownError, } from '@livestore/common';
-import { LiveStoreEvent, resolveEventDef, SystemTables } from '@livestore/common/schema';
-import { assertNever, isDevEnv, omitUndefineds, shouldNeverHappen } from '@livestore/utils';
+import { EventSequenceNumber, LiveStoreEvent, resolveEventDef, SystemTables } from '@livestore/common/schema';
+import { assertNever, isDevEnv, objectToString, omitUndefineds, shouldNeverHappen } from '@livestore/utils';
 import { Cause, Effect, Exit, Fiber, Inspectable, Option, OtelTracer, Runtime, Schema, Stream, } from '@livestore/utils/effect';
 import { nanoid } from '@livestore/utils/nanoid';
 import * as otel from '@opentelemetry/api';
@@ -11,7 +11,7 @@ import { SqliteDbWrapper } from "../SqliteDbWrapper.js";
 import { ReferenceCountedSet } from "../utils/data-structures.js";
 import { downloadBlob, exposeDebugUtils } from "../utils/dev.js";
 import { StoreInternalsSymbol, } from "./store-types.js";
-if (isDevEnv()) {
+if (isDevEnv() === true) {
     exposeDebugUtils();
 }
 /**
@@ -32,8 +32,8 @@ export const STORE_DEFAULT_PARAMS = {
  * ## Creating a Store
  *
  * Use `createStore` (Effect-based) or `createStorePromise` to obtain a Store instance.
- * In React applications, use the `<LiveStoreProvider>` component which manages the Store lifecycle
- * and exposes it via React context.
+ * In React applications, use `StoreRegistry` with `<StoreRegistryProvider>` and the `useStore()` hook
+ * which manages the Store lifecycle.
  *
  * ## Querying Data
  *
@@ -94,11 +94,28 @@ export class Store extends Inspectable.Class {
      * ```
      */
     networkStatus;
+    /**
+     * Indicates how data is being stored.
+     *
+     * - `persisted`: Data is persisted to disk (e.g., via OPFS on web, SQLite file on native)
+     * - `in-memory`: Data is only stored in memory and will be lost on page refresh
+     *
+     * The store operates in `in-memory` mode when persistent storage is unavailable,
+     * such as in Safari/Firefox private browsing mode where OPFS is restricted.
+     *
+     * @example
+     * ```tsx
+     * if (store.storageMode === 'in-memory') {
+     *   showWarning('Data will not be persisted in private browsing mode')
+     * }
+     * ```
+     */
+    storageMode;
     /**
      * Store internals. Not part of the public API — shapes and semantics may change without notice.
      */
     [StoreInternalsSymbol];
-    // #region constructor
+    //#region constructor
     constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }) {
         super();
         this.storeId = storeId;
@@ -106,12 +123,11 @@ export class Store extends Inspectable.Class {
         this.context = context;
         this.params = params;
         this.networkStatus = clientSession.leaderThread.networkStatus;
+        this.storageMode = clientSession.leaderThread.initialState.storageMode;
         const reactivityGraph = makeReactivityGraph();
-        const syncSpan = otelOptions.tracer.startSpan('LiveStore:sync', {}, otelOptions.rootSpanContext);
         const syncProcessor = makeClientSessionSyncProcessor({
             schema,
             clientSession,
-            runtime: effectContext.runtime,
             materializeEvent: Effect.fn('client-session-sync-processor:materialize-event')((eventEncoded, { withChangeset, materializerHashLeader }) => 
             // We need to use `Effect.gen` (even though we're using `Effect.fn`) so that we can pass `this` to the function
             Effect.gen(this, function* () {
@@ -135,7 +151,7 @@ export class Store extends Inspectable.Class {
                     dbState: this[StoreInternalsSymbol].sqliteDbWrapper,
                     event: { decoded: undefined, encoded: eventEncoded },
                 });
-                const materializerHash = isDevEnv() ? Option.some(hashMaterializerResults(execArgsArr)) : Option.none();
+                const materializerHash = isDevEnv() === true ? Option.some(hashMaterializerResults(execArgsArr)) : Option.none();
                 // Hash mismatch detection only occurs during the pull path (when receiving events from the leader).
                 // During push path (local commits), materializerHashLeader is always Option.none(), so this condition
                 // will never be met. The check happens when the same event comes back from the leader during sync,
@@ -191,7 +207,6 @@ export class Store extends Inspectable.Class {
                 }
                 reactivityGraph.setRefs(tablesToUpdate);
             },
-            span: syncSpan,
             params: {
                 ...omitUndefineds({
                     leaderPushBatchSize: params.leaderPushBatchSize,
@@ -201,7 +216,7 @@ export class Store extends Inspectable.Class {
                     : {}),
             },
             confirmUnsavedChanges,
-        });
+        }).pipe(Runtime.runSync(effectContext.runtime));
         // TODO generalize the `tableRefs` concept to allow finer-grained refs
         const tableRefs = {};
         const activeQueries = new ReferenceCountedSet();
@@ -227,7 +242,7 @@ export class Store extends Inspectable.Class {
         const allTableNames = new Set(
         // NOTE we're excluding the LiveStore schema and events tables as they are not user-facing
         // unless LiveStore is running in the devtools
-        __runningInDevtools
+        __runningInDevtools === true
             ? this.schema.state.sqlite.tables.keys()
             : Array.from(this.schema.state.sqlite.tables.keys()).filter((_) => !SystemTables.isStateSystemTable(_)));
         const existingTableRefs = new Map(Array.from(reactivityGraph.atoms.values())
@@ -238,7 +253,7 @@ export class Store extends Inspectable.Class {
                 existingTableRefs.get(tableName) ??
                     reactivityGraph.makeRef(null, {
                         equal: () => false,
-                        label: `tableRef:${tableName}`,
+                        label: `tableRef:${String(tableName)}`,
                         meta: { liveStoreRefType: 'table' },
                     });
         }
@@ -251,7 +266,6 @@ export class Store extends Inspectable.Class {
                     }
                 }
                 // End the otel spans
-                syncSpan.end();
                 commitsSpan.end();
                 queriesSpan.end();
             }));
@@ -276,7 +290,7 @@ export class Store extends Inspectable.Class {
         // Initialize stable network status property from client session
         this.networkStatus = clientSession.leaderThread.networkStatus;
     }
-    // #endregion constructor
+    //#endregion constructor
     /**
      * Current session identifier for this Store instance.
      *
@@ -296,7 +310,7 @@ export class Store extends Inspectable.Class {
         return this[StoreInternalsSymbol].clientSession.clientId;
     }
     checkShutdown = (operation) => {
-        if (this[StoreInternalsSymbol].isShutdown) {
+        if (this[StoreInternalsSymbol].isShutdown === true) {
             throw new UnknownError({
                 cause: `Store has been shut down (while performing "${operation}").`,
                 note: `You cannot perform this operation after the store has been shut down.`,
@@ -329,9 +343,14 @@ export class Store extends Inspectable.Class {
     });
     subscribeWithCallback = (query, onUpdate, options) => {
         this.checkShutdown('subscribe');
-        return this[StoreInternalsSymbol].otel.tracer.startActiveSpan(`LiveStore.subscribe`, { attributes: { label: options?.label, queryLabel: isQueryBuilder(query) ? query.toString() : query.label } }, options?.otelContext ?? this[StoreInternalsSymbol].otel.queriesSpanContext, (span) => {
+        return this[StoreInternalsSymbol].otel.tracer.startActiveSpan(`LiveStore.subscribe`, {
+            attributes: {
+                label: options?.label,
+                queryLabel: isQueryBuilder(query) === true ? query.toString() : query.label,
+            },
+        }, options?.otelContext ?? this[StoreInternalsSymbol].otel.queriesSpanContext, (span) => {
             const otelContext = otel.trace.setSpan(otel.context.active(), span);
-            const queryRcRef = isQueryBuilder(query)
+            const queryRcRef = isQueryBuilder(query) === true
                 ? queryDb(query).make(this[StoreInternalsSymbol].reactivityGraph.context)
                 : query._tag === 'def' || query._tag === 'signal-def'
                     ? query.make(this[StoreInternalsSymbol].reactivityGraph.context)
@@ -344,7 +363,7 @@ export class Store extends Inspectable.Class {
             let suppressCallback = options?.skipInitialRun === true;
             const effect = this[StoreInternalsSymbol].reactivityGraph.makeEffect((get, _otelContext, debugRefreshReason) => {
                 const result = get(query$.results$, otelContext, debugRefreshReason);
-                if (suppressCallback) {
+                if (suppressCallback === true) {
                     return;
                 }
                 onUpdate(result);
@@ -355,13 +374,13 @@ export class Store extends Inspectable.Class {
                     label: `subscribe-initial-run:${options?.label}`,
                 });
             };
-            if (options?.stackInfo) {
+            if (options?.stackInfo !== undefined) {
                 query$.activeSubscriptions.add(options.stackInfo);
             }
             options?.onSubscribe?.(query$);
             this[StoreInternalsSymbol].activeQueries.add(query$);
-            if (!query$.isDestroyed) {
-                if (suppressCallback) {
+            if (query$.isDestroyed === false) {
+                if (suppressCallback === true) {
                     // We still run once to register dependencies in the reactive graph, but suppress the initial callback so the
                     // caller truly skips the first emission; subsequent runs (after commits) will call the callback.
                     runInitialEffect();
@@ -375,7 +394,7 @@ export class Store extends Inspectable.Class {
                 try {
                     this[StoreInternalsSymbol].reactivityGraph.destroyNode(effect);
                     this[StoreInternalsSymbol].activeQueries.remove(query$);
-                    if (options?.stackInfo) {
+                    if (options?.stackInfo !== undefined) {
                         query$.activeSubscriptions.delete(options.stackInfo);
                     }
                     queryRcRef.deref();
@@ -394,9 +413,9 @@ export class Store extends Inspectable.Class {
     };
     subscribeStream = (query, options) => Stream.asyncPush((emit) => Effect.gen(this, function* () {
         const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.catchTag('NoSuchElementException', () => Effect.succeed(undefined)));
-        const otelContext = otelSpan ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active();
+        const otelContext = otelSpan !== undefined ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active();
         yield* Effect.acquireRelease(Effect.sync(() => this.subscribe(query, (result) => emit.single(result), {
-            ...(options ?? {}),
+            ...options,
             otelContext,
         })), (unsub) => Effect.sync(() => unsub()));
     }));
@@ -420,12 +439,12 @@ export class Store extends Inspectable.Class {
             const res = this[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(query.query, prepareBindValues(query.bindValues, query.query), {
                 ...omitUndefineds({ otelContext: options?.otelContext }),
             });
-            if (query.schema) {
+            if (query.schema !== undefined) {
                 return Schema.decodeSync(query.schema)(res);
             }
             return res;
         }
-        else if (isQueryBuilder(query)) {
+        else if (isQueryBuilder(query) === true) {
             const ast = query[QueryBuilderAstSymbol];
             if (ast._tag === 'RowQuery') {
                 makeExecBeforeFirstRun({
@@ -438,7 +457,7 @@ export class Store extends Inspectable.Class {
             const sqlRes = query.asSql();
             const schema = getResultSchema(query);
             // Replace SessionIdSymbol in bind values before executing the query
-            if (sqlRes.bindValues) {
+            if (sqlRes.bindValues !== undefined) {
                 replaceSessionIdSymbol(sqlRes.bindValues, this[StoreInternalsSymbol].clientSession.sessionId);
             }
             const rawRes = this[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(sqlRes.query, sqlRes.bindValues, {
@@ -450,7 +469,7 @@ export class Store extends Inspectable.Class {
                 return decodeResult.right;
             }
             else {
-                return shouldNeverHappen(`Failed to decode query result with for schema:`, schema.toString(), 'raw result:', rawRes, 'decode error:', decodeResult.left);
+                return shouldNeverHappen('Failed to decode query result with for schema:', objectToString(schema), 'raw result:', rawRes, 'decode error:', decodeResult.left);
             }
         }
         else if (query._tag === 'def') {
@@ -498,7 +517,7 @@ export class Store extends Inspectable.Class {
             signalRef.deref();
         }
     };
-    // #region commit
+    //#region commit
     /**
      * Commit a list of events to the store which will immediately update the local database
      * and sync the events across other clients (similar to a `git commit`).
@@ -564,22 +583,17 @@ export class Store extends Inspectable.Class {
             if (events.length === 0)
                 return;
             const localRuntime = yield* Effect.runtime();
-            const materializeEventsTx = Effect.try({
+            const encodedEvents = yield* this[StoreInternalsSymbol].syncProcessor.encodeEvents(events);
+            const { writeTables } = yield* Effect.try({
                 try: () => {
-                    const runMaterializeEvents = () => {
-                        return this[StoreInternalsSymbol].syncProcessor.push(events).pipe(Runtime.runSync(localRuntime));
-                    };
-                    if (events.length > 1) {
-                        return this[StoreInternalsSymbol].sqliteDbWrapper.txn(runMaterializeEvents);
-                    }
-                    else {
-                        return runMaterializeEvents();
-                    }
+                    const materialize = () => this[StoreInternalsSymbol].syncProcessor.materializeEvents(encodedEvents).pipe(Runtime.runSync(localRuntime));
+                    return events.length > 1
+                        ? this[StoreInternalsSymbol].sqliteDbWrapper.txn(materialize)
+                        : materialize();
                 },
                 catch: (cause) => UnknownError.make({ cause }),
             });
-            // Materialize events to state
-            const { writeTables } = yield* materializeEventsTx;
+            yield* this[StoreInternalsSymbol].syncProcessor.push(encodedEvents);
             const tablesToUpdate = [];
             for (const tableName of writeTables) {
                 const tableRef = this[StoreInternalsSymbol].tableRefs[tableName];
@@ -615,7 +629,7 @@ export class Store extends Inspectable.Class {
             ],
         }), Effect.tapErrorCause(Effect.logError), Effect.catchAllCause((cause) => Effect.fork(this.shutdown(cause))), Runtime.runSync(this[StoreInternalsSymbol].effectContext.runtime));
     };
-    // #endregion commit
+    //#endregion commit
     /**
      * Returns an async iterable of events from the eventlog.
      * Currently only events confirmed by the sync backend is supported.
@@ -683,6 +697,92 @@ export class Store extends Inspectable.Class {
         };
         return clientSession.leaderThread.events.stream(baseOptions).pipe(Stream.mapChunksEffect(Schema.decode(Schema.ChunkFromSelf(eventSchema))), Stream.catchTag('ParseError', (cause) => Stream.fail(UnknownError.make({ cause }))), Stream.tapError((error) => Effect.logError('Error in eventsStream', error)));
     };
+    /**
+     * Returns the current synchronization status of the store.
+     *
+     * This is a synchronous operation that returns the sync state between the
+     * client session and the leader thread. Use this to display sync indicators
+     * or check if local changes have been pushed to the leader.
+     *
+     * @example
+     * ```ts
+     * const status = store.syncStatus()
+     * console.log(status.isSynced ? 'Synced' : `${status.pendingCount} pending`)
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Health check for backend connectivity
+     * const status = store.syncStatus()
+     * if (!status.isSynced && status.pendingCount > 100) {
+     *   console.warn('Large backlog of unsynced events')
+     * }
+     * ```
+     */
+    syncStatus = () => {
+        this.checkShutdown('syncStatus');
+        const syncState = this[StoreInternalsSymbol].syncProcessor.syncState.pipe(Effect.runSync);
+        const pendingCount = syncState.pending.length;
+        return {
+            localHead: EventSequenceNumber.Client.toString(syncState.localHead),
+            upstreamHead: EventSequenceNumber.Client.toString(syncState.upstreamHead),
+            pendingCount,
+            isSynced: pendingCount === 0,
+        };
+    };
+    /**
+     * Returns an Effect Stream of sync status updates.
+     *
+     * Emits the current status immediately and then whenever the sync state changes.
+     * Use this for Effect-based workflows or when you need more control over the stream.
+     *
+     * @example
+     * ```ts
+     * store.syncStatusStream().pipe(
+     *   Stream.tap((status) => Effect.log(`Sync status: ${status.isSynced}`)),
+     *   Stream.runDrain,
+     * )
+     * ```
+     */
+    syncStatusStream = () => {
+        const syncStateSubscribable = this[StoreInternalsSymbol].syncProcessor.syncState;
+        return Stream.concat(Stream.fromEffect(syncStateSubscribable.pipe(Effect.map(this.makeSyncStatus))), syncStateSubscribable.changes.pipe(Stream.map(this.makeSyncStatus)));
+    };
+    /**
+     * Subscribes to sync status changes.
+     *
+     * The callback is invoked immediately with the current status and then
+     * whenever the sync state changes (e.g., when events are pushed or confirmed).
+     *
+     * @param onUpdate - Callback invoked with the current sync status
+     * @returns Unsubscribe function to stop receiving updates
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = store.subscribeSyncStatus((status) => {
+     *   updateUI(status.isSynced ? 'Synced' : 'Syncing...')
+     * })
+     *
+     * // Later, stop listening
+     * unsubscribe()
+     * ```
+     */
+    subscribeSyncStatus = (onUpdate) => {
+        this.checkShutdown('subscribeSyncStatus');
+        const fiber = this.syncStatusStream().pipe(Stream.tap((status) => Effect.sync(() => onUpdate(status))), Stream.runDrain, this.runEffectFork);
+        return () => {
+            Fiber.interrupt(fiber).pipe(Runtime.runFork(this[StoreInternalsSymbol].effectContext.runtime));
+        };
+    };
+    makeSyncStatus = (syncState) => {
+        const pendingCount = syncState.pending.length;
+        return {
+            localHead: EventSequenceNumber.Client.toString(syncState.localHead),
+            upstreamHead: EventSequenceNumber.Client.toString(syncState.upstreamHead),
+            pendingCount,
+            isSynced: pendingCount === 0,
+        };
+    };
     /**
      * This can be used in combination with `skipRefresh` when committing events.
      * We might need a better solution for this. Let's see.
@@ -704,7 +804,7 @@ export class Store extends Inspectable.Class {
     shutdownPromise = async (cause) => {
         this.checkShutdown('shutdownPromise');
         this[StoreInternalsSymbol].isShutdown = true;
-        await this.shutdown(cause ? Cause.fail(cause) : undefined).pipe(this.runEffectFork, Fiber.join, Effect.runPromise);
+        await this.shutdown(cause !== undefined ? Cause.fail(cause) : undefined).pipe(this.runEffectFork, Fiber.join, Effect.runPromise);
     };
     /**
      * Shuts down the store and closes the client session.
@@ -713,7 +813,7 @@ export class Store extends Inspectable.Class {
      */
     shutdown = (cause) => {
         this[StoreInternalsSymbol].isShutdown = true;
-        return this[StoreInternalsSymbol].clientSession.shutdown(cause ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })));
+        return this[StoreInternalsSymbol].clientSession.shutdown(cause !== undefined ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })));
     };
     /**
      * Helper methods useful during development
@@ -752,6 +852,7 @@ export class Store extends Inspectable.Class {
             }))
                 .pipe(this.runEffectFork);
         },
+        // NOTE: Explicit return type needed to avoid TS2742 (inferred type references internal path)
         syncStates: () => Effect.gen(this, function* () {
             const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState;
             const leader = yield* this[StoreInternalsSymbol].clientSession.leaderThread.syncState;
@@ -760,9 +861,9 @@ export class Store extends Inspectable.Class {
         printSyncStates: () => {
             Effect.gen(this, function* () {
                 const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState;
-                yield* Effect.log(`Session sync state: ${session.localHead} (upstream: ${session.upstreamHead})`, session.toJSON());
+                yield* Effect.log(`Session sync state: ${objectToString(session.localHead)} (upstream: ${objectToString(session.upstreamHead)})`, session.toJSON());
                 const leader = yield* this[StoreInternalsSymbol].clientSession.leaderThread.syncState;
-                yield* Effect.log(`Leader sync state: ${leader.localHead} (upstream: ${leader.upstreamHead})`, leader.toJSON());
+                yield* Effect.log(`Leader sync state: ${objectToString(leader.localHead)} (upstream: ${objectToString(leader.upstreamHead)})`, leader.toJSON());
             }).pipe(this.runEffectFork);
         },
         version: liveStoreVersion,