@livestore/livestore 0.4.0-dev.20 → 0.4.0-dev.22

package/dist/store/store-types.d.ts

@@ -1,5 +1,6 @@
-import { type ClientSession, type ClientSessionSyncProcessor, type ClientSessionSyncProcessorSimulationParams, type IntentionalShutdownCause, type InvalidPullError, type IsOfflineError, type MaterializeError, type QueryBuilder, type StoreInterrupted, type SyncError, type UnknownError } from '@livestore/common';
-import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema';
+import { type ClientSession, type ClientSessionSyncProcessor, type IntentionalShutdownCause, type InvalidPullError, type IsOfflineError, type MaterializeError, type QueryBuilder, type StoreInterrupted, type SyncError, 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 } from '@livestore/utils/effect';
 import type * as otel from '@opentelemetry/api';
@@ -9,7 +10,17 @@ import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts';
 import type { ReferenceCountedSet } from '../utils/data-structures.ts';
 import type { StackInfo } from '../utils/stack-info.ts';
 import type { Store } from './store.ts';
-export type LiveStoreContext = LiveStoreContextRunning | {
+/**
+ * Union type representing the possible states of a LiveStore context.
+ *
+ * Used by framework integrations (React, Solid, etc.) to track Store lifecycle:
+ * - `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<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = LiveStoreContextRunning<TSchema> | {
     stage: 'error';
     error: UnknownError | unknown;
 } | {
@@ -18,9 +29,19 @@ export type LiveStoreContext = LiveStoreContextRunning | {
 };
 export type ShutdownDeferred = Deferred.Deferred<IntentionalShutdownCause, UnknownError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError>;
 export declare const makeShutdownDeferred: Effect.Effect<ShutdownDeferred>;
-export type LiveStoreContextRunning = {
+/**
+ * Context state when the Store is active and ready for use.
+ *
+ * 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<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = {
     stage: 'running';
-    store: Store;
+    store: Store<TSchema>;
 };
 export type OtelOptions = {
     tracer: otel.Tracer;
@@ -109,26 +130,12 @@ export type StoreInternals = {
      */
     isShutdown: boolean;
 };
-export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
-    clientSession: ClientSession;
-    schema: TSchema;
-    storeId: string;
-    context: TContext;
-    otelOptions: OtelOptions;
-    effectContext: {
-        runtime: Runtime.Runtime<Scope.Scope>;
-        lifetimeScope: Scope.Scope;
-    };
-    confirmUnsavedChanges: boolean;
-    batchUpdates: (runUpdates: () => void) => void;
-    params: {
-        leaderPushBatchSize: number;
-        simulation?: {
-            clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type;
-        };
-    };
-    __runningInDevtools: boolean;
-};
+/**
+ * Tagged union describing why a reactive refresh occurred.
+ *
+ * Used internally for debugging and devtools to trace the cause of query re-evaluations.
+ * Each variant includes context about what triggered the refresh.
+ */
 export type RefreshReason = DebugRefreshReasonBase | {
     _tag: 'commit';
     /** The events that were applied */
@@ -150,10 +157,19 @@ export type RefreshReason = DebugRefreshReasonBase | {
     _tag: 'manual';
     label?: string;
 };
+/**
+ * Debug information captured for each query execution.
+ *
+ * Used by devtools and performance monitoring to track query behavior.
+ */
 export type QueryDebugInfo = {
+    /** Query type discriminator ('db', 'computed', etc.) */
     _tag: string;
+    /** Human-readable query label */
     label: string;
+    /** SQL query string or computed function representation */
     query: string;
+    /** Execution time in milliseconds */
     durationMs: number;
 };
 export type StoreOtel = {
@@ -168,35 +184,47 @@ export type StoreCommitOptions = {
     spanLinks?: otel.Link[];
     otelContext?: otel.Context;
 };
-export type StoreEventsOptions<TSchema extends LiveStoreSchema> = {
-    /**
-     * By default only new events are returned.
-     * Use this to get all events from a specific point in time.
-     */
-    cursor?: EventSequenceNumber.Client.Composite;
+/**
+ * filter: Narrowed to the store's event types
+ * includeClientOnly: Omitted from public API until supported
+ */
+export type StoreEventsOptions<TSchema extends LiveStoreSchema> = Omit<StreamEventsOptions, 'filter' | 'includeClientOnly'> & {
     /**
-     * Only include events of the given names
+     * Only include events of the given names.
      * @default undefined (include all)
      */
     filter?: ReadonlyArray<keyof TSchema['_EventDefMapType']>;
-    /**
-     * Whether to include client-only events or only return synced events
-     * @default true
-     */
-    includeClientOnly?: boolean;
-    /**
-     * Exclude own events that have not been pushed to the sync backend yet
-     * @default false
-     */
-    excludeUnpushed?: boolean;
 };
+/**
+ * Function returned by `store.subscribe()` to stop receiving updates.
+ *
+ * Call this to unsubscribe from a query and release the associated resources.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = store.subscribe(todos$, (todos) => console.log(todos))
+ * // Later...
+ * unsubscribe()
+ * ```
+ */
 export type Unsubscribe = () => void;
+/**
+ * Options for `store.subscribe()`.
+ *
+ * @typeParam TResult - The result type of the subscribed query
+ */
 export type SubscribeOptions<TResult> = {
+    /** Callback invoked when the subscription is established (receives the live query instance) */
     onSubscribe?: (query$: LiveQuery<TResult>) => void;
+    /** Callback invoked when the subscription is terminated */
     onUnsubsubscribe?: () => void;
+    /** Label for debugging and devtools */
     label?: string;
+    /** If true, skips invoking the callback for the initial value */
     skipInitialRun?: boolean;
+    /** OpenTelemetry context for tracing */
     otelContext?: otel.Context;
+    /** Stack trace info for debugging subscription origins */
     stackInfo?: StackInfo;
 };
 /** All query definitions or instances the store can execute or subscribe to. */
@@ -218,7 +246,56 @@ export declare namespace Queryable {
      */
     type Result<TQueryable extends Queryable<any>> = TQueryable extends Queryable<infer TResult> ? TResult : never;
 }
+/**
+ * Type guard that checks if a value is a query or signal definition.
+ *
+ * Use this to distinguish between definitions (blueprints) and instances (live queries).
+ * Definitions are created by `queryDb()`, `computed()`, and `signal()`.
+ *
+ * @example
+ * ```ts
+ * const todos$ = queryDb(tables.todos.all())
+ *
+ * if (isLiveQueryDef(todos$)) {
+ *   console.log('This is a definition:', todos$.label)
+ * }
+ * ```
+ */
 export declare const isLiveQueryDef: (value: unknown) => value is LiveQueryDef<any> | SignalDef<any>;
+/**
+ * Type guard that checks if a value is a live query instance.
+ *
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
+ *
+ * @example
+ * ```ts
+ * const [, , , query$] = useClientDocument(tables.uiState)
+ *
+ * if (isLiveQueryInstance(query$)) {
+ *   console.log('Execution count:', query$.runs)
+ * }
+ * ```
+ */
 export declare const isLiveQueryInstance: (value: unknown) => value is LiveQuery<any>;
+/**
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
+ *
+ * Queryable values include:
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
+ * - Signal definitions (`SignalDef` from `signal()`)
+ * - Live query instances (`LiveQuery`)
+ * - Query builders (e.g., `tables.todos.where(...)`)
+ *
+ * @example
+ * ```ts
+ * const handleQuery = (input: unknown) => {
+ *   if (isQueryable(input)) {
+ *     return store.query(input)
+ *   }
+ *   throw new Error('Not a valid query')
+ * }
+ * ```
+ */
 export declare const isQueryable: (value: unknown) => value is Queryable<unknown>;
 //# sourceMappingURL=store-types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store-types.d.ts","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store-types.d.ts","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,0BAA0B,EAE/B,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEnB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAa,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,KAAK,IAAI,MAAM,oBAAoB,CAAA;AAC/C,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,SAAS,EACV,MAAM,+BAA+B,CAAA;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,eAAe,GAAG,eAAe,CAAC,GAAG,IAC9E,uBAAuB,CAAC,OAAO,CAAC,GAChC;IACE,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,YAAY,GAAG,OAAO,CAAA;CAC9B,GACD;IACE,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,EAAE,wBAAwB,GAAG,gBAAgB,GAAG,SAAS,CAAA;CAC/D,CAAA;AAEL,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,QAAQ,CAC9C,wBAAwB,EACxB,YAAY,GAAG,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,cAAc,CACnG,CAAA;AACD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAG9D,CAAA;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,CAAC,OAAO,SAAS,eAAe,GAAG,eAAe,CAAC,GAAG,IAAI;IAC3F,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAA;IACnB,eAAe,EAAE,IAAI,CAAC,OAAO,CAAA;CAC9B,CAAA;AAED,eAAO,MAAM,oBAAoB,eAAyC,CAAA;AAC1E,MAAM,MAAM,oBAAoB,GAAG,OAAO,oBAAoB,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAEjG;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;IAErC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE;QACtB,mEAAmE;QACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC9C,kEAAkE;QAClE,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAA;KACpC,CAAA;IAED;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IAExB;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,sBAAsB,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAE9F;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAA;IAE3D;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,0BAA0B,CAAA;IAElD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAE7D;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AA8BD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,sBAAsB,GACtB;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,mCAAmC;IACnC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAEnF,mDAAmD;IACnD,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACnC,GACD;IAEE,IAAI,EAAE,OAAO,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,GACD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAA;IACnB,eAAe,EAAE,IAAI,CAAC,OAAO,CAAA;IAC7B,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAA;IAChC,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,EAAE,CAAA;IACvB,WAAW,CAAC,EAAE,IAAI,CAAC,OAAO,CAAA;CAC3B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,CAAC,OAAO,SAAS,eAAe,IAAI,IAAI,CACpE,mBAAmB,EACnB,QAAQ,GAAG,mBAAmB,CAC/B,GAAG;IACF;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAA;CAC1D,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,IAAI;IACtC,+FAA+F;IAC/F,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;IAClD,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAA;IAC7B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,wCAAwC;IACxC,WAAW,CAAC,EAAE,IAAI,CAAC,OAAO,CAAA;IAC1B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB,CAAA;AAED,gFAAgF;AAChF,MAAM,MAAM,SAAS,CAAC,OAAO,IACzB,YAAY,CAAC,OAAO,CAAC,GACrB,SAAS,CAAC,OAAO,CAAC,GAClB,SAAS,CAAC,OAAO,CAAC,GAClB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEnC;;;;GAIG;AACH,yBAAiB,SAAS,CAAC;IACzB;;;;;;;;OAQG;IACH,KAAY,MAAM,CAAC,UAAU,SAAS,SAAS,CAAC,GAAG,CAAC,IAAI,UAAU,SAAS,SAAS,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAA;CACtH;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CA0BzF,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,SAAS,CAAC,GAAG,CAAyC,CAAA;AAEpH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,SAAS,CAAC,OAAO,CACO,CAAA"}

package/dist/store/store-types.js

@@ -3,6 +3,21 @@ import { Deferred, Predicate } from '@livestore/utils/effect';
 import { TypeId } from "../live-queries/base-class.js";
 export const makeShutdownDeferred = Deferred.make();
 export const StoreInternalsSymbol = Symbol.for('livestore.StoreInternals');
+/**
+ * Type guard that checks if a value is a query or signal definition.
+ *
+ * Use this to distinguish between definitions (blueprints) and instances (live queries).
+ * Definitions are created by `queryDb()`, `computed()`, and `signal()`.
+ *
+ * @example
+ * ```ts
+ * const todos$ = queryDb(tables.todos.all())
+ *
+ * if (isLiveQueryDef(todos$)) {
+ *   console.log('This is a definition:', todos$.label)
+ * }
+ * ```
+ */
 export const isLiveQueryDef = (value) => {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -25,6 +40,40 @@ export const isLiveQueryDef = (value) => {
     }
     return true;
 };
+/**
+ * Type guard that checks if a value is a live query instance.
+ *
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
+ *
+ * @example
+ * ```ts
+ * const [, , , query$] = useClientDocument(tables.uiState)
+ *
+ * if (isLiveQueryInstance(query$)) {
+ *   console.log('Execution count:', query$.runs)
+ * }
+ * ```
+ */
 export const isLiveQueryInstance = (value) => Predicate.hasProperty(value, TypeId);
+/**
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
+ *
+ * Queryable values include:
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
+ * - Signal definitions (`SignalDef` from `signal()`)
+ * - Live query instances (`LiveQuery`)
+ * - Query builders (e.g., `tables.todos.where(...)`)
+ *
+ * @example
+ * ```ts
+ * const handleQuery = (input: unknown) => {
+ *   if (isQueryable(input)) {
+ *     return store.query(input)
+ *   }
+ *   throw new Error('Not a valid query')
+ * }
+ * ```
+ */
 export const isQueryable = (value) => isQueryBuilder(value) || isLiveQueryInstance(value) || isLiveQueryDef(value);
 //# sourceMappingURL=store-types.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,cAAc,GAMf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAS7D,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAsBtD,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA;AAYH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;AAyN1E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAA+C,EAAE;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,GAAG,GAAI,KAA4C,CAAC,IAAI,CAAA;IAC9D,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,SAAS,GAAG,KAA0B,CAAA;IAC5C,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACzC,4EAA4E;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,6EAA6E;QAC7E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEpH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAA+B,EAAE,CACzE,cAAc,CAAC,KAAK,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA"}
+{"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,cAAc,GAMf,MAAM,mBAAmB,CAAA;AAI1B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAS7D,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAgCtD,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA;AAsBH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;AA8P1E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAA+C,EAAE;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,GAAG,GAAI,KAA4C,CAAC,IAAI,CAAA;IAC9D,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,SAAS,GAAG,KAA0B,CAAA;IAC5C,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACzC,4EAA4E;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,6EAA6E;QAC7E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEpH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAA+B,EAAE,CACzE,cAAc,CAAC,KAAK,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA"}

package/dist/store/store.d.ts

@@ -1,14 +1,21 @@
-import { type Bindable, type ClientSession, MaterializeError, UnknownError } from '@livestore/common';
+import { type Bindable, type ClientSession, MaterializeError, type StorageMode, 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 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>;
 };
+/**
+ * Default parameters for the Store. Also used in `create-store.ts`
+ */
+export declare const STORE_DEFAULT_PARAMS: {
+    leaderPushBatchSize: number;
+    eventQueryBatchSize: number;
+};
 /**
  * Central interface to a LiveStore database providing reactive queries, event commits, and sync.
  *
@@ -19,8 +26,8 @@ export type SubscribeFn = {
  * ## 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
  *
@@ -61,6 +68,8 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
     readonly schema: LiveStoreSchema;
     /** User-defined context attached to this Store (e.g. for dependency injection). */
     readonly context: TContext;
+    /** Options provided to the Store constructor. */
+    readonly params: StoreConstructorParams<TSchema, TContext>['params'];
     /**
      * Reactive connectivity updates emitted by the backing sync backend.
      *
@@ -79,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.
      *
@@ -217,25 +243,52 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
         (options: StoreCommitOptions, txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(...list: TCommitArg) => void): void;
     };
     /**
-     * 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?: StoreEventsOptions<TSchema>) => AsyncIterable<LiveStoreEvent.Client.ForSchema<TSchema>>;
-    eventsStream: (_options?: StoreEventsOptions<TSchema>) => Stream.Stream<LiveStoreEvent.Client.ForSchema<TSchema>>;
+    events: (options?: StoreEventsOptions<TSchema>) => AsyncIterable<LiveStoreEvent.Client.ForSchema<TSchema>>;
+    /**
+     * Returns an Effect Stream of events from the eventlog.
+     * See `store.events` for details on options and behaviour.
+     */
+    eventsStream: (options?: StoreEventsOptions<TSchema>) => Stream.Stream<LiveStoreEvent.Client.ForSchema<TSchema>, UnknownError>;
     /**
      * This can be used in combination with `skipRefresh` when committing events.
      * We might need a better solution for this. Let's see.

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, notYetImplemented, omitUndefineds, shouldNeverHappen } from '@livestore/utils';
+import { assertNever, isDevEnv, 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';
@@ -14,6 +14,14 @@ import { StoreInternalsSymbol, } from "./store-types.js";
 if (isDevEnv()) {
     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.
  *
@@ -24,8 +32,8 @@ if (isDevEnv()) {
  * ## 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
  *
@@ -66,6 +74,8 @@ export class Store extends Inspectable.Class {
     schema;
     /** User-defined context attached to this Store (e.g. for dependency injection). */
     context;
+    /** Options provided to the Store constructor. */
+    params;
     /**
      * Reactive connectivity updates emitted by the backing sync backend.
      *
@@ -84,6 +94,23 @@ 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.
      */
@@ -94,6 +121,9 @@ export class Store extends Inspectable.Class {
         this.storeId = storeId;
         this.schema = schema;
         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({
@@ -605,30 +635,71 @@ export class Store extends Inspectable.Class {
     };
     // #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)));
     };
     /**
      * This can be used in combination with `skipRefresh` when committing events.