@livestore/livestore 0.4.0-dev.8 → 0.4.0

package/dist/store/store.js

@@ -1,6 +1,6 @@
-import { Devtools, getExecStatementsFromMaterializer, getResultSchema, hashMaterializerResults, IntentionalShutdownCause, isQueryBuilder, liveStoreVersion, MaterializeError, MaterializerHashMismatchError, makeClientSessionSyncProcessor, prepareBindValues, QueryBuilderAstSymbol, replaceSessionIdSymbol, UnexpectedError, } from '@livestore/common';
-import { getEventDef, LiveStoreEvent, SystemTables } from '@livestore/common/schema';
-import { assertNever, isDevEnv, notYetImplemented, omitUndefineds, shouldNeverHappen } from '@livestore/utils';
+import { Devtools, getExecStatementsFromMaterializer, getResultSchema, hashMaterializerResults, IntentionalShutdownCause, isQueryBuilder, liveStoreVersion, MaterializeError, MaterializerHashMismatchError, makeClientSessionSyncProcessor, prepareBindValues, QueryBuilderAstSymbol, replaceSessionIdSymbol, UnknownError, } from '@livestore/common';
+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';
@@ -10,57 +10,148 @@ import { queryDb } from "../live-queries/db-query.js";
 import { SqliteDbWrapper } from "../SqliteDbWrapper.js";
 import { ReferenceCountedSet } from "../utils/data-structures.js";
 import { downloadBlob, exposeDebugUtils } from "../utils/dev.js";
-if (isDevEnv()) {
+import { StoreInternalsSymbol, } from "./store-types.js";
+if (isDevEnv() === true) {
     exposeDebugUtils();
 }
+/**
+ * Default parameters for the Store. Also used in `create-store.ts`
+ */
+export const STORE_DEFAULT_PARAMS = {
+    leaderPushBatchSize: 100,
+    eventQueryBatchSize: 100,
+};
+//
+/**
+ * Central interface to a LiveStore database providing reactive queries, event commits, and sync.
+ *
+ * A `Store` instance wraps a local SQLite database that is kept in sync with other clients via
+ * an event log. Instead of mutating state directly, you commit events that get materialized
+ * into database rows. Queries automatically re-run when their underlying tables change.
+ *
+ * ## Creating a Store
+ *
+ * Use `createStore` (Effect-based) or `createStorePromise` to obtain a Store instance.
+ * In React applications, use `StoreRegistry` with `<StoreRegistryProvider>` and the `useStore()` hook
+ * which manages the Store lifecycle.
+ *
+ * ## Querying Data
+ *
+ * Use {@link Store.query} for one-shot reads or {@link Store.subscribe} for reactive subscriptions.
+ * Both accept query builders (e.g. `tables.todo.where({ complete: true })`) or custom `LiveQueryDef`s.
+ *
+ * ## Committing Events
+ *
+ * Use {@link Store.commit} to persist events. Events are immediately materialized locally and
+ * asynchronously synced to other clients. Multiple events can be committed atomically.
+ *
+ * ## Lifecycle
+ *
+ * The Store must be shut down when no longer needed via {@link Store.shutdown} or
+ * {@link Store.shutdownPromise}. Framework integrations (React, Effect) handle this automatically.
+ *
+ * @typeParam TSchema - The LiveStore schema defining tables and events
+ * @typeParam TContext - Optional user-defined context attached to the Store (e.g. for dependency injection)
+ *
+ * @example
+ * ```ts
+ * // Query data
+ * const todos = store.query(tables.todo.where({ complete: false }))
+ *
+ * // Subscribe to changes
+ * const unsubscribe = store.subscribe(tables.todo.all(), (todos) => {
+ *   console.log('Todos updated:', todos)
+ * })
+ *
+ * // Commit an event
+ * store.commit(events.todoCreated({ id: nanoid(), text: 'Buy milk' }))
+ * ```
+ */
 export class Store extends Inspectable.Class {
+    /** Unique identifier for this Store instance, stable for its lifetime. */
     storeId;
-    reactivityGraph;
-    sqliteDbWrapper;
-    clientSession;
+    /** The LiveStore schema defining tables, events, and materializers. */
     schema;
+    /** User-defined context attached to this Store (e.g. for dependency injection). */
     context;
-    otel;
+    /** Options provided to the Store constructor. */
+    params;
     /**
-     * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
-     * This only works in combination with `equal: () => false` which will always trigger a refresh.
+     * Reactive connectivity updates emitted by the backing sync backend.
+     *
+     * @example
+     * ```ts
+     * import { Effect, Stream } from 'effect'
+     *
+     * const status = await store.networkStatus.pipe(Effect.runPromise)
+     *
+     * await store.networkStatus.changes.pipe(
+     *   Stream.tap((next) => console.log('network status update', next)),
+     *   Stream.runDrain,
+     *   Effect.scoped,
+     *   Effect.runPromise,
+     * )
+     * ```
      */
-    tableRefs;
-    /** Tracks whether the store has been shut down */
-    isShutdown = false;
-    effectContext;
-    /** RC-based set to see which queries are currently subscribed to */
-    activeQueries;
-    // NOTE this is currently exposed for the Devtools databrowser to commit events
-    __eventSchema;
-    syncProcessor;
-    boot;
-    // #region constructor
+    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
     constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }) {
         super();
         this.storeId = storeId;
-        this.sqliteDbWrapper = new SqliteDbWrapper({ otel: otelOptions, db: clientSession.sqliteDb });
-        this.clientSession = clientSession;
         this.schema = schema;
         this.context = context;
-        this.effectContext = effectContext;
+        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);
-        this.syncProcessor = makeClientSessionSyncProcessor({
+        const syncProcessor = makeClientSessionSyncProcessor({
             schema,
             clientSession,
-            runtime: effectContext.runtime,
-            materializeEvent: Effect.fn('client-session-sync-processor:materialize-event')((eventDecoded, { withChangeset, materializerHashLeader }) => 
+            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* () {
-                const { eventDef, materializer } = getEventDef(schema, eventDecoded.name);
+                const resolution = yield* resolveEventDef(schema, {
+                    operation: '@livestore/livestore:store:materializeEvent',
+                    event: eventEncoded,
+                });
+                if (resolution._tag === 'unknown') {
+                    // Runtime schema doesn't know this event yet; skip materialization but
+                    // keep the log entry so upgraded clients can replay it later.
+                    return {
+                        writeTables: new Set(),
+                        sessionChangeset: { _tag: 'no-op' },
+                        materializerHash: Option.none(),
+                    };
+                }
+                const { eventDef, materializer } = resolution;
                 const execArgsArr = getExecStatementsFromMaterializer({
                     eventDef,
                     materializer,
-                    dbState: this.sqliteDbWrapper,
-                    event: { decoded: eventDecoded, encoded: undefined },
+                    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,
@@ -68,33 +159,36 @@ export class Store extends Inspectable.Class {
                 if (materializerHashLeader._tag === 'Some' &&
                     materializerHash._tag === 'Some' &&
                     materializerHashLeader.value !== materializerHash.value) {
-                    return yield* MaterializerHashMismatchError.make({ eventName: eventDecoded.name });
+                    return yield* MaterializerHashMismatchError.make({ eventName: eventEncoded.name });
                 }
                 const span = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie);
                 const otelContext = otel.trace.setSpan(otel.context.active(), span);
                 const writeTablesForEvent = new Set();
                 const exec = () => {
-                    for (const { statementSql, bindValues, writeTables = this.sqliteDbWrapper.getTablesUsed(statementSql), } of execArgsArr) {
+                    for (const { statementSql, bindValues, writeTables = this[StoreInternalsSymbol].sqliteDbWrapper.getTablesUsed(statementSql), } of execArgsArr) {
                         try {
-                            this.sqliteDbWrapper.cachedExecute(statementSql, bindValues, { otelContext, writeTables });
+                            this[StoreInternalsSymbol].sqliteDbWrapper.cachedExecute(statementSql, bindValues, {
+                                otelContext,
+                                writeTables,
+                            });
                         }
                         catch (cause) {
                             // TOOD refactor with `SqliteError`
-                            throw UnexpectedError.make({
+                            throw UnknownError.make({
                                 cause,
-                                note: `Error executing materializer for event "${eventDecoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
+                                note: `Error executing materializer for event "${eventEncoded.name}".\nStatement: ${statementSql}\nBind values: ${JSON.stringify(bindValues)}`,
                             });
                         }
                         // durationMsTotal += durationMs
                         for (const table of writeTables) {
                             writeTablesForEvent.add(table);
                         }
-                        this.sqliteDbWrapper.debug.head = eventDecoded.seqNum;
+                        this[StoreInternalsSymbol].sqliteDbWrapper.debug.head = eventEncoded.seqNum;
                     }
                 };
                 let sessionChangeset = { _tag: 'unset' };
                 if (withChangeset === true) {
-                    sessionChangeset = this.sqliteDbWrapper.withChangeset(exec).changeset;
+                    sessionChangeset = this[StoreInternalsSymbol].sqliteDbWrapper.withChangeset(exec).changeset;
                 }
                 else {
                     exec();
@@ -102,18 +196,17 @@ export class Store extends Inspectable.Class {
                 return { writeTables: writeTablesForEvent, sessionChangeset, materializerHash };
             }).pipe(Effect.mapError((cause) => MaterializeError.make({ cause })))),
             rollback: (changeset) => {
-                this.sqliteDbWrapper.rollback(changeset);
+                this[StoreInternalsSymbol].sqliteDbWrapper.rollback(changeset);
             },
             refreshTables: (tables) => {
                 const tablesToUpdate = [];
                 for (const tableName of tables) {
-                    const tableRef = this.tableRefs[tableName];
+                    const tableRef = this[StoreInternalsSymbol].tableRefs[tableName];
                     assertNever(tableRef !== undefined, `No table ref found for ${tableName}`);
                     tablesToUpdate.push([tableRef, null]);
                 }
                 reactivityGraph.setRefs(tablesToUpdate);
             },
-            span: syncSpan,
             params: {
                 ...omitUndefineds({
                     leaderPushBatchSize: params.leaderPushBatchSize,
@@ -123,17 +216,15 @@ export class Store extends Inspectable.Class {
                     : {}),
             },
             confirmUnsavedChanges,
-        });
-        this.__eventSchema = LiveStoreEvent.makeEventDefSchemaMemo(schema);
+        }).pipe(Runtime.runSync(effectContext.runtime));
         // TODO generalize the `tableRefs` concept to allow finer-grained refs
-        this.tableRefs = {};
-        this.activeQueries = new ReferenceCountedSet();
+        const tableRefs = {};
+        const activeQueries = new ReferenceCountedSet();
         const commitsSpan = otelOptions.tracer.startSpan('LiveStore:commits', {}, otelOptions.rootSpanContext);
         const otelMuationsSpanContext = otel.trace.setSpan(otel.context.active(), commitsSpan);
         const queriesSpan = otelOptions.tracer.startSpan('LiveStore:queries', {}, otelOptions.rootSpanContext);
         const otelQueriesSpanContext = otel.trace.setSpan(otel.context.active(), queriesSpan);
-        this.reactivityGraph = reactivityGraph;
-        this.reactivityGraph.context = {
+        reactivityGraph.context = {
             store: this,
             defRcMap: new Map(),
             reactivityGraph: new WeakRef(reactivityGraph),
@@ -141,7 +232,7 @@ export class Store extends Inspectable.Class {
             rootOtelContext: otelQueriesSpanContext,
             effectsWrapper: batchUpdates,
         };
-        this.otel = {
+        const otelObj = {
             tracer: otelOptions.tracer,
             rootSpanContext: otelOptions.rootSpanContext,
             commitsSpanContext: otelMuationsSpanContext,
@@ -151,92 +242,159 @@ 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(this.reactivityGraph.atoms.values())
+        const existingTableRefs = new Map(Array.from(reactivityGraph.atoms.values())
             .filter((_) => _._tag === 'ref' && _.label?.startsWith('tableRef:') === true)
             .map((_) => [_.label.slice('tableRef:'.length), _]));
         for (const tableName of allTableNames) {
-            this.tableRefs[tableName] =
+            tableRefs[tableName] =
                 existingTableRefs.get(tableName) ??
-                    this.reactivityGraph.makeRef(null, {
+                    reactivityGraph.makeRef(null, {
                         equal: () => false,
-                        label: `tableRef:${tableName}`,
+                        label: `tableRef:${String(tableName)}`,
                         meta: { liveStoreRefType: 'table' },
                     });
         }
-        this.boot = Effect.gen(this, function* () {
+        const boot = Effect.gen(this, function* () {
             yield* Effect.addFinalizer(() => Effect.sync(() => {
                 // Remove all table refs from the reactivity graph
-                for (const tableRef of Object.values(this.tableRefs)) {
+                for (const tableRef of Object.values(tableRefs)) {
                     for (const superComp of tableRef.super) {
-                        this.reactivityGraph.removeEdge(superComp, tableRef);
+                        this[StoreInternalsSymbol].reactivityGraph.removeEdge(superComp, tableRef);
                     }
                 }
                 // End the otel spans
-                syncSpan.end();
                 commitsSpan.end();
                 queriesSpan.end();
             }));
-            yield* this.syncProcessor.boot;
+            yield* syncProcessor.boot;
         });
+        // Build Sqlite wrapper last to avoid using getters before internals are set
+        const sqliteDbWrapper = new SqliteDbWrapper({ otel: otelOptions, db: clientSession.sqliteDb });
+        // Initialize internals bag
+        this[StoreInternalsSymbol] = {
+            eventSchema: LiveStoreEvent.Client.makeSchemaMemo(schema),
+            clientSession,
+            sqliteDbWrapper,
+            effectContext,
+            otel: otelObj,
+            reactivityGraph,
+            tableRefs,
+            activeQueries,
+            syncProcessor,
+            boot,
+            isShutdown: false,
+        };
+        // Initialize stable network status property from client session
+        this.networkStatus = clientSession.leaderThread.networkStatus;
     }
-    // #endregion constructor
+    //#endregion constructor
+    /**
+     * Current session identifier for this Store instance.
+     *
+     * - Stable for the lifetime of the Store
+     * - Useful for correlating events or scoping per-session data
+     */
     get sessionId() {
-        return this.clientSession.sessionId;
+        return this[StoreInternalsSymbol].clientSession.sessionId;
     }
+    /**
+     * Stable client identifier for the process/device using this Store.
+     *
+     * - Shared across Store instances created by the same client
+     * - Useful for diagnostics and multi-client correlation
+     */
     get clientId() {
-        return this.clientSession.clientId;
+        return this[StoreInternalsSymbol].clientSession.clientId;
     }
     checkShutdown = (operation) => {
-        if (this.isShutdown) {
-            throw new UnexpectedError({
+        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.`,
             });
         }
     };
     /**
-     * Subscribe to the results of a query
-     * Returns a function to cancel the subscription.
+     * Subscribe to the results of a query.
+     *
+     * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
+     * - Without a callback it returns an {@link AsyncIterable} that yields query results.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
+     * ```
      *
      * @example
      * ```ts
-     * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+     * for await (const result of store.subscribe(query$)) {
+     *   console.log(result)
+     * }
      * ```
      */
-    subscribe = (query, options) => {
+    subscribe = ((query, onUpdateOrOptions, maybeOptions) => {
+        if (typeof onUpdateOrOptions === 'function') {
+            return this.subscribeWithCallback(query, onUpdateOrOptions, maybeOptions);
+        }
+        return this.subscribeAsAsyncIterable(query, onUpdateOrOptions);
+    });
+    subscribeWithCallback = (query, onUpdate, options) => {
         this.checkShutdown('subscribe');
-        return this.otel.tracer.startActiveSpan(`LiveStore.subscribe`, { attributes: { label: options?.label, queryLabel: isQueryBuilder(query) ? query.toString() : query.label } }, options?.otelContext ?? this.otel.queriesSpanContext, (span) => {
-            // console.debug('store sub', query$.id, query$.label)
+        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)
-                ? queryDb(query).make(this.reactivityGraph.context)
+            const queryRcRef = isQueryBuilder(query) === true
+                ? queryDb(query).make(this[StoreInternalsSymbol].reactivityGraph.context)
                 : query._tag === 'def' || query._tag === 'signal-def'
-                    ? query.make(this.reactivityGraph.context)
+                    ? query.make(this[StoreInternalsSymbol].reactivityGraph.context)
                     : {
                         value: query,
                         deref: () => { },
                     };
             const query$ = queryRcRef.value;
             const label = `subscribe:${options?.label}`;
-            const effect = this.reactivityGraph.makeEffect((get, _otelContext, debugRefreshReason) => options.onUpdate(get(query$.results$, otelContext, debugRefreshReason)), { label });
-            if (options?.stackInfo) {
+            let suppressCallback = options?.skipInitialRun === true;
+            const effect = this[StoreInternalsSymbol].reactivityGraph.makeEffect((get, _otelContext, debugRefreshReason) => {
+                const result = get(query$.results$, otelContext, debugRefreshReason);
+                if (suppressCallback === true) {
+                    return;
+                }
+                onUpdate(result);
+            }, { label });
+            const runInitialEffect = () => {
+                effect.doEffect(otelContext, {
+                    _tag: 'subscribe.initial',
+                    label: `subscribe-initial-run:${options?.label}`,
+                });
+            };
+            if (options?.stackInfo !== undefined) {
                 query$.activeSubscriptions.add(options.stackInfo);
             }
             options?.onSubscribe?.(query$);
-            this.activeQueries.add(query$);
-            // Running effect right away to get initial value (unless `skipInitialRun` is set)
-            if (options?.skipInitialRun !== true && !query$.isDestroyed) {
-                effect.doEffect(otelContext, { _tag: 'subscribe.initial', label: `subscribe-initial-run:${options?.label}` });
+            this[StoreInternalsSymbol].activeQueries.add(query$);
+            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();
+                    suppressCallback = false;
+                }
+                else {
+                    runInitialEffect();
+                }
             }
             const unsubscribe = () => {
-                // console.debug('store unsub', query$.id, query$.label)
                 try {
-                    this.reactivityGraph.destroyNode(effect);
-                    this.activeQueries.remove(query$);
-                    if (options?.stackInfo) {
+                    this[StoreInternalsSymbol].reactivityGraph.destroyNode(effect);
+                    this[StoreInternalsSymbol].activeQueries.remove(query$);
+                    if (options?.stackInfo !== undefined) {
                         query$.activeSubscriptions.delete(options.stackInfo);
                     }
                     queryRcRef.deref();
@@ -249,12 +407,16 @@ export class Store extends Inspectable.Class {
             return unsubscribe;
         });
     };
-    subscribeStream = (query$, options) => Stream.asyncPush((emit) => Effect.gen(this, function* () {
+    subscribeAsAsyncIterable = (query, options) => {
+        this.checkShutdown('subscribe');
+        return Stream.toAsyncIterable(this.subscribeStream(query, options));
+    };
+    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();
-        yield* Effect.acquireRelease(Effect.sync(() => this.subscribe(query$, {
-            onUpdate: (result) => emit.single(result),
-            ...omitUndefineds({ otelContext, label: options?.label }),
+        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,
+            otelContext,
         })), (unsub) => Effect.sync(() => unsub()));
     }));
     /**
@@ -274,15 +436,15 @@ export class Store extends Inspectable.Class {
     query = (query, options) => {
         this.checkShutdown('query');
         if (typeof query === 'object' && 'query' in query && 'bindValues' in query) {
-            const res = this.sqliteDbWrapper.cachedSelect(query.query, prepareBindValues(query.bindValues, query.query), {
+            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({
@@ -290,15 +452,15 @@ export class Store extends Inspectable.Class {
                     id: ast.id,
                     explicitDefaultValues: ast.explicitDefaultValues,
                     otelContext: options?.otelContext,
-                })(this.reactivityGraph.context);
+                })(this[StoreInternalsSymbol].reactivityGraph.context);
             }
             const sqlRes = query.asSql();
             const schema = getResultSchema(query);
             // Replace SessionIdSymbol in bind values before executing the query
-            if (sqlRes.bindValues) {
-                replaceSessionIdSymbol(sqlRes.bindValues, this.clientSession.sessionId);
+            if (sqlRes.bindValues !== undefined) {
+                replaceSessionIdSymbol(sqlRes.bindValues, this[StoreInternalsSymbol].clientSession.sessionId);
             }
-            const rawRes = this.sqliteDbWrapper.cachedSelect(sqlRes.query, sqlRes.bindValues, {
+            const rawRes = this[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(sqlRes.query, sqlRes.bindValues, {
                 ...omitUndefineds({ otelContext: options?.otelContext }),
                 queriedTables: new Set([query[QueryBuilderAstSymbol].tableDef.sqliteDef.name]),
             });
@@ -307,17 +469,17 @@ 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') {
-            const query$ = query.make(this.reactivityGraph.context);
+            const query$ = query.make(this[StoreInternalsSymbol].reactivityGraph.context);
             const result = this.query(query$.value, options);
             query$.deref();
             return result;
         }
         else if (query._tag === 'signal-def') {
-            const signal$ = query.make(this.reactivityGraph.context);
+            const signal$ = query.make(this[StoreInternalsSymbol].reactivityGraph.context);
             return signal$.value.get();
         }
         else {
@@ -343,7 +505,7 @@ export class Store extends Inspectable.Class {
      */
     setSignal = (signalDef, value) => {
         this.checkShutdown('setSignal');
-        const signalRef = signalDef.make(this.reactivityGraph.context);
+        const signalRef = signalDef.make(this[StoreInternalsSymbol].reactivityGraph.context);
         const newValue = typeof value === 'function' ? value(signalRef.value.get()) : value;
         signalRef.value.set(newValue);
         // The current implementation of signals i.e. the separation into `signal-def` and `signal`
@@ -355,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`).
@@ -411,35 +573,30 @@ export class Store extends Inspectable.Class {
         this.checkShutdown('commit');
         const { events, options } = this.getCommitArgs(firstEventOrTxnFnOrOptions, restEvents);
         Effect.gen(this, function* () {
-            const commitsSpan = otel.trace.getSpan(this.otel.commitsSpanContext);
+            const commitsSpan = otel.trace.getSpan(this[StoreInternalsSymbol].otel.commitsSpanContext);
             commitsSpan?.addEvent('commit');
             const currentSpan = yield* OtelTracer.currentOtelSpan.pipe(Effect.orDie);
             commitsSpan?.addLink({ context: currentSpan.spanContext() });
             for (const event of events) {
-                replaceSessionIdSymbol(event.args, this.clientSession.sessionId);
+                replaceSessionIdSymbol(event.args, this[StoreInternalsSymbol].clientSession.sessionId);
             }
             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.syncProcessor.push(events).pipe(Runtime.runSync(localRuntime));
-                    };
-                    if (events.length > 1) {
-                        return this.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) => UnexpectedError.make({ cause }),
+                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.tableRefs[tableName];
+                const tableRef = this[StoreInternalsSymbol].tableRefs[tableName];
                 assertNever(tableRef !== undefined, `No table ref found for ${tableName}`);
                 tablesToUpdate.push([tableRef, null]);
             }
@@ -450,7 +607,7 @@ export class Store extends Inspectable.Class {
             };
             const skipRefresh = options?.skipRefresh ?? false;
             // Update all table refs together in a batch, to only trigger one reactive update
-            this.reactivityGraph.setRefs(tablesToUpdate, {
+            this[StoreInternalsSymbol].reactivityGraph.setRefs(tablesToUpdate, {
                 debugRefreshReason,
                 skipRefresh,
                 otelContext: otel.trace.setSpan(otel.context.active(), currentSpan),
@@ -464,38 +621,167 @@ export class Store extends Inspectable.Class {
             },
             links: [
                 // Span link to LiveStore:commits
-                OtelTracer.makeSpanLink({ context: otel.trace.getSpanContext(this.otel.commitsSpanContext) }),
+                OtelTracer.makeSpanLink({
+                    context: otel.trace.getSpanContext(this[StoreInternalsSymbol].otel.commitsSpanContext),
+                }),
                 // User-provided span links
                 ...(options?.spanLinks?.map(OtelTracer.makeSpanLink) ?? []),
             ],
-        }), Effect.tapErrorCause(Effect.logError), Effect.catchAllCause((cause) => Effect.fork(this.shutdown(cause))), Runtime.runSync(this.effectContext.runtime));
+        }), 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.
+     * Returns an async iterable of events from the eventlog.
+     * Currently only events confirmed by the sync backend is supported.
+     *
+     * Defaults to tracking upstreamHead as it advances. If an `until` event is
+     * supplied the stream finalizes upon reaching it.
+     *
+     * To start streaming from a specific point in the eventlog
+     * you can provide a `since` event.
+     *
+     * Allows filtering by:
+     *  - `filter`: event types
+     *  - `clientIds`: client identifiers
+     *  - `sessionIds`: session identifiers
+     *
+     * The batchSize option controls the maximum amount of events that are fetched
+     * from the eventlog in each query. Defaults to 100 and has a max allowed
+     * value of 1000.
+     *
+     * TODO:
+     * - Support streaming unconfirmed events
+     *  - Leader level
+     *  - Session level
+     * - Support streaming client-only events
      *
      * @example
      * ```ts
-     * for await (const event of store.events()) {
+     * // Stream todoCompleted events from the start
+     * for await (const event of store.events(filter: ['todoCompleted'])) {
      *   console.log(event)
      * }
      * ```
      *
      * @example
      * ```ts
-     * // Get all events from the beginning of time
-     * for await (const event of store.events({ cursor: EventSequenceNumber.ROOT })) {
+     * // Start streaming from a specific event
+     * for await (const event of store.events({ since: EventSequenceNumber.Client.fromString('e3') })) {
      *   console.log(event)
      * }
      * ```
      */
-    events = (_options) => {
-        this.checkShutdown('events');
-        return notYetImplemented(`store.events() is not yet implemented but planned soon`);
+    events = (options) => {
+        const stream = this.eventsStream(options);
+        return {
+            async *[Symbol.asyncIterator]() {
+                const iterator = Stream.toAsyncIterable(stream);
+                for await (const event of iterator) {
+                    yield event;
+                }
+            },
+        };
     };
-    eventsStream = (_options) => {
-        this.checkShutdown('eventsStream');
-        return notYetImplemented(`store.eventsStream() is not yet implemented but planned soon`);
+    /**
+     * Returns an Effect Stream of events from the eventlog.
+     * See `store.events` for details on options and behaviour.
+     */
+    eventsStream = (options) => {
+        const { clientSession } = this[StoreInternalsSymbol];
+        const eventSchema = LiveStoreEvent.Client.makeSchema(this.schema);
+        const preferredBatchSize = options?.batchSize ?? this.params.eventQueryBatchSize ?? STORE_DEFAULT_PARAMS.eventQueryBatchSize;
+        const baseOptions = {
+            ...options,
+            filter: options?.filter,
+            batchSize: preferredBatchSize,
+        };
+        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.
@@ -504,9 +790,9 @@ export class Store extends Inspectable.Class {
     manualRefresh = (options) => {
         this.checkShutdown('manualRefresh');
         const { label } = options ?? {};
-        this.otel.tracer.startActiveSpan('LiveStore:manualRefresh', { attributes: { 'livestore.manualRefreshLabel': label } }, this.otel.commitsSpanContext, (span) => {
+        this[StoreInternalsSymbol].otel.tracer.startActiveSpan('LiveStore:manualRefresh', { attributes: { 'livestore.manualRefreshLabel': label } }, this[StoreInternalsSymbol].otel.commitsSpanContext, (span) => {
             const otelContext = otel.trace.setSpan(otel.context.active(), span);
-            this.reactivityGraph.runDeferredEffects({ otelContext });
+            this[StoreInternalsSymbol].reactivityGraph.runDeferredEffects({ otelContext });
             span.end();
         });
     };
@@ -517,8 +803,8 @@ export class Store extends Inspectable.Class {
      */
     shutdownPromise = async (cause) => {
         this.checkShutdown('shutdownPromise');
-        this.isShutdown = true;
-        await this.shutdown(cause ? Cause.fail(cause) : undefined).pipe(this.runEffectFork, Fiber.join, Effect.runPromise);
+        this[StoreInternalsSymbol].isShutdown = true;
+        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.
@@ -526,8 +812,8 @@ export class Store extends Inspectable.Class {
      * This is called automatically when the store was created using the React or Effect API.
      */
     shutdown = (cause) => {
-        this.isShutdown = true;
-        return this.clientSession.shutdown(cause ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })));
+        this[StoreInternalsSymbol].isShutdown = true;
+        return this[StoreInternalsSymbol].clientSession.shutdown(cause !== undefined ? Exit.failCause(cause) : Exit.succeed(IntentionalShutdownCause.make({ reason: 'manual' })));
     };
     /**
      * Helper methods useful during development
@@ -537,25 +823,27 @@ export class Store extends Inspectable.Class {
     _dev = {
         downloadDb: (source = 'local') => {
             Effect.gen(this, function* () {
-                const data = source === 'local' ? this.sqliteDbWrapper.export() : yield* this.clientSession.leaderThread.export;
+                const data = source === 'local'
+                    ? this[StoreInternalsSymbol].sqliteDbWrapper.export()
+                    : yield* this[StoreInternalsSymbol].clientSession.leaderThread.export;
                 downloadBlob(data, `livestore-${Date.now()}.db`);
             }).pipe(this.runEffectFork);
         },
         downloadEventlogDb: () => {
             Effect.gen(this, function* () {
-                const data = yield* this.clientSession.leaderThread.getEventlogData;
+                const data = yield* this[StoreInternalsSymbol].clientSession.leaderThread.getEventlogData;
                 downloadBlob(data, `livestore-eventlog-${Date.now()}.db`);
             }).pipe(this.runEffectFork);
         },
         hardReset: (mode = 'all-data') => {
             Effect.gen(this, function* () {
-                const clientId = this.clientSession.clientId;
-                yield* this.clientSession.leaderThread.sendDevtoolsMessage(Devtools.Leader.ResetAllData.Request.make({ liveStoreVersion, mode, requestId: nanoid(), clientId }));
+                const clientId = this[StoreInternalsSymbol].clientSession.clientId;
+                yield* this[StoreInternalsSymbol].clientSession.leaderThread.sendDevtoolsMessage(Devtools.Leader.ResetAllData.Request.make({ liveStoreVersion, mode, requestId: nanoid(), clientId }));
             }).pipe(this.runEffectFork);
         },
         overrideNetworkStatus: (status) => {
-            const clientId = this.clientSession.clientId;
-            this.clientSession.leaderThread
+            const clientId = this[StoreInternalsSymbol].clientSession.clientId;
+            this[StoreInternalsSymbol].clientSession.leaderThread
                 .sendDevtoolsMessage(Devtools.Leader.SetSyncLatch.Request.make({
                 clientId,
                 closeLatch: status === 'offline',
@@ -564,31 +852,32 @@ 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.syncProcessor.syncState;
-            const leader = yield* this.clientSession.leaderThread.getSyncState;
+            const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState;
+            const leader = yield* this[StoreInternalsSymbol].clientSession.leaderThread.syncState;
             return { session, leader };
         }).pipe(this.runEffectPromise),
         printSyncStates: () => {
             Effect.gen(this, function* () {
-                const session = yield* this.syncProcessor.syncState;
-                yield* Effect.log(`Session sync state: ${session.localHead} (upstream: ${session.upstreamHead})`, session.toJSON());
-                const leader = yield* this.clientSession.leaderThread.getSyncState;
-                yield* Effect.log(`Leader sync state: ${leader.localHead} (upstream: ${leader.upstreamHead})`, leader.toJSON());
+                const session = yield* this[StoreInternalsSymbol].syncProcessor.syncState;
+                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: ${objectToString(leader.localHead)} (upstream: ${objectToString(leader.upstreamHead)})`, leader.toJSON());
             }).pipe(this.runEffectFork);
         },
         version: liveStoreVersion,
         otel: {
-            rootSpanContext: () => otel.trace.getSpan(this.otel.rootSpanContext)?.spanContext(),
+            rootSpanContext: () => otel.trace.getSpan(this[StoreInternalsSymbol].otel.rootSpanContext)?.spanContext(),
         },
     };
     // NOTE This is needed because when booting a Store via Effect it seems to call `toJSON` in the error path
     toJSON = () => ({
         _tag: 'livestore.Store',
-        reactivityGraph: this.reactivityGraph.getSnapshot({ includeResults: true }),
+        reactivityGraph: this[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true }),
     });
-    runEffectFork = (effect) => effect.pipe(Effect.forkIn(this.effectContext.lifetimeScope), Effect.tapCauseLogPretty, Runtime.runFork(this.effectContext.runtime));
-    runEffectPromise = (effect) => effect.pipe(Effect.tapCauseLogPretty, Runtime.runPromise(this.effectContext.runtime));
+    runEffectFork = (effect) => effect.pipe(Effect.forkIn(this[StoreInternalsSymbol].effectContext.lifetimeScope), Effect.tapCauseLogPretty, Runtime.runFork(this[StoreInternalsSymbol].effectContext.runtime));
+    runEffectPromise = (effect) => effect.pipe(Effect.tapCauseLogPretty, Runtime.runPromise(this[StoreInternalsSymbol].effectContext.runtime));
     getCommitArgs = (firstEventOrTxnFnOrOptions, restEvents) => {
         let events;
         let options;
@@ -612,7 +901,7 @@ export class Store extends Inspectable.Class {
         }
         // for (const event of events) {
         //   if (event.args.id === SessionIdSymbol) {
-        //     event.args.id = this.clientSession.sessionId
+        //     event.args.id = this.sessionId
         //   }
         // }
         return { events, options };