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

package/src/store/StoreRegistry.ts

@@ -0,0 +1,393 @@
+import { LogConfig, OtelLiveDummy, provideOtel, UnknownError } from '@livestore/common'
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import { omitUndefineds } from '@livestore/utils'
+import {
+  Cause,
+  Effect,
+  Equal,
+  Exit,
+  Fiber,
+  Hash,
+  Layer,
+  ManagedRuntime,
+  type OtelTracer,
+  RcMap,
+  Runtime,
+  type Schema,
+  type Scope,
+} from '@livestore/utils/effect'
+import { type CreateStoreOptions, createStore } from './create-store.ts'
+import type { Store } from './store.ts'
+import type { OtelOptions } from './store-types.ts'
+
+/**
+ * Default time to keep unused stores in cache.
+ *
+ * - Browser: 60 seconds (60,000 ms)
+ * - SSR: Infinity (disables disposal to avoid disposing stores before server render completes)
+ *
+ * @internal Exported primarily for testing purposes.
+ */
+export const DEFAULT_UNUSED_CACHE_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
+
+/**
+ * Configuration options for stores managed by a {@link StoreRegistry}.
+ *
+ * Extends {@link CreateStoreOptions} with registry-specific settings for caching and observability.
+ * Use with {@link storeOptions} helper to get full type inference when defining reusable store configurations.
+ *
+ * @typeParam TSchema - The LiveStore schema type
+ * @typeParam TContext - User-defined context attached to the store
+ * @typeParam TSyncPayloadSchema - Schema for the sync payload sent to the backend
+ *
+ * @see {@link storeOptions} for defining reusable store configurations
+ * @see {@link StoreRegistry} for managing store lifecycles
+ */
+export interface RegistryStoreOptions<
+  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+> extends CreateStoreOptions<TSchema, TContext, TSyncPayloadSchema> {
+  /**
+   * OpenTelemetry configuration for tracing store operations.
+   *
+   * When provided, store operations (boot, queries, commits) will be traced
+   * under the given root span context using the specified tracer.
+   */
+  otelOptions?: Partial<OtelOptions>
+  /**
+   * The time in milliseconds that this store should remain
+   * in memory after becoming unused. When this store becomes
+   * unused (no active retentions), it will be disposed after this duration.
+   *
+   * Stores transition to the unused state as soon as they have no
+   * active retentions, so when all components which use that store
+   * have unmounted.
+   *
+   * @remarks
+   * - **Limitation:** Per-store values are not yet supported. Only the registry-level default
+   *   (via `StoreRegistry` constructor's `defaultOptions.unusedCacheTime`) is used.
+   *   See {@link https://github.com/livestorejs/livestore/issues/917 | #917} for per-store support
+   *   and {@link https://github.com/livestorejs/livestore/issues/918 | #918} for dynamic "longest wins" behavior.
+   * - If set to `Infinity`, will disable automatic disposal
+   * - The maximum allowed time is about {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#maximum_delay_value | 24 days}
+   *
+   * @defaultValue `60_000` (60 seconds) or `Infinity` during SSR to avoid
+   * disposing stores before server render completes.
+   */
+  unusedCacheTime?: number
+}
+
+type StoreRegistryConfig = {
+  /**
+   * Default options that are applied to all stores when they are loaded.
+   *
+   * @remarks
+   * These are options that typically don't depend on the specific store being loaded:
+   * - Framework integration (`batchUpdates`)
+   * - Environment settings (`disableDevtools`, `debug`, `otelOptions`)
+   * - Behavior defaults (`confirmUnsavedChanges`, `unusedCacheTime`)
+   *
+   * Store-specific fields like `schema`, `adapter`, `storeId`, and `boot` are intentionally
+   * excluded since they vary per store definition.
+   */
+  defaultOptions?: Partial<
+    Pick<
+      RegistryStoreOptions,
+      'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'debug' | 'otelOptions' | 'unusedCacheTime'
+    >
+  >
+  /**
+   * Custom Effect runtime for all registry operations (loading, caching, etc.).
+   * When the runtime's scope closes, all managed stores are automatically shut down.
+   */
+  runtime?: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
+}
+
+/**
+ * RcMap cache key that uses storeId for equality/hashing but carries full options.
+ * This allows RcMap to deduplicate by storeId while the lookup function has access to all options.
+ *
+ * @remarks
+ * Only `storeId` is used for equality and hashing. This means if `getOrLoadPromise` is called
+ * with different options (e.g., different `adapter`) but the same `storeId`, the cached store
+ * from the first call will be returned. This is intentional - a store's identity is determined
+ * solely by its `storeId`, and callers should not expect to get different stores by varying
+ * other options while keeping the same `storeId`.
+ */
+class StoreCacheKey implements Equal.Equal {
+  readonly options: RegistryStoreOptions<any, any, any>
+
+  constructor(options: RegistryStoreOptions<any, any, any>) {
+    this.options = options
+  }
+
+  /**
+   * Equality is based solely on `storeId`. Other options in `RegistryStoreOptions` are ignored
+   * for cache key comparison. The first options used for a given `storeId` determine the
+   * store's configuration.
+   */
+  [Equal.symbol](that: Equal.Equal): boolean {
+    return that instanceof StoreCacheKey && this.options.storeId === that.options.storeId
+  }
+
+  [Hash.symbol](): number {
+    return Hash.string(this.options.storeId)
+  }
+}
+
+/**
+ * Store Registry coordinating store loading, caching, and retention
+ *
+ * @public
+ */
+export class StoreRegistry {
+  /**
+   * Reference-counted cache mapping storeId to Store instances.
+   * Stores are created on first access and disposed after `unusedCacheTime` when all references are released.
+   */
+  readonly #rcMap: RcMap.RcMap<StoreCacheKey, Store<any, any>, UnknownError>
+
+  /**
+   * Effect runtime providing Scope and OtelTracer for all registry operations.
+   * When the runtime's scope closes, all managed stores are automatically shut down.
+   */
+  readonly #runtime: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
+
+  /**
+   * In-flight loading promises keyed by storeId.
+   * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
+   */
+  readonly #loadingPromises: Map<string, Promise<Store<any, any>>> = new Map()
+
+  /**
+   * Default options merged into all store configurations at load time.
+   */
+  readonly #defaultOptions: StoreRegistryConfig['defaultOptions']
+
+  /**
+   * Creates a new StoreRegistry instance.
+   *
+   * @example
+   * ```ts
+   * const registry = new StoreRegistry({
+   *   defaultOptions: {
+   *     batchUpdates,
+   *     unusedCacheTime: 30_000,
+   *   }
+   * })
+   * ```
+   */
+  constructor(config: StoreRegistryConfig = {}) {
+    this.#defaultOptions = config.defaultOptions
+    this.#runtime =
+      config.runtime ??
+      ManagedRuntime.make(Layer.mergeAll(Layer.scope, OtelLiveDummy)).runtimeEffect.pipe(Effect.runSync)
+
+    this.#rcMap = RcMap.make({
+      lookup: ({ options }: StoreCacheKey) => {
+        // Merge registry defaults with call-site options (call-site takes precedence)
+        const mergedOptions = { ...this.#defaultOptions, ...options }
+        return createStore(mergedOptions).pipe(
+          Effect.catchAllDefect((cause) => UnknownError.make({ cause })),
+          Effect.withSpan(`StoreRegistry.lookup:${mergedOptions.storeId}`),
+          LogConfig.withLoggerConfig(mergedOptions, { threadName: 'window' }),
+          provideOtel(
+            omitUndefineds({
+              parentSpanContext: mergedOptions.otelOptions?.rootSpanContext,
+              otelTracer: mergedOptions.otelOptions?.tracer,
+            }),
+          ),
+        )
+      },
+      // TODO: Make idleTimeToLive vary for each store when Effect supports per-resource TTL
+      // See https://github.com/livestorejs/livestore/issues/917
+      idleTimeToLive: config.defaultOptions?.unusedCacheTime ?? DEFAULT_UNUSED_CACHE_TIME,
+    }).pipe(Runtime.runSync(this.#runtime))
+  }
+
+  /**
+   * Gets a cached store or loads a new one, with the store lifetime scoped to the caller.
+   *
+   * @typeParam TSchema - The schema type for the store
+   * @typeParam TContext - The context type for the store
+   * @typeParam TSyncPayloadSchema - The sync payload schema type
+   * @returns An Effect that yields the store, scoped to the provided Scope
+   *
+   * @remarks
+   * - Stores are kept in cache and reused while any scope holds them
+   * - When the scope closes, the reference is released; the store is disposed after `unusedCacheTime`
+   *   if no other scopes retain it
+   * - Concurrent calls with the same storeId share the same store instance
+   */
+  getOrLoad = <
+    TSchema extends LiveStoreSchema,
+    TContext = {},
+    TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  >(
+    options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+  ): Effect.Effect<Store<TSchema, TContext>, UnknownError, Scope.Scope> =>
+    Effect.gen(this, function* () {
+      // Cast options to satisfy StoreCacheKey's wider type (type safety enforced at API boundary)
+      const key = new StoreCacheKey(options)
+      const store = yield* RcMap.get(this.#rcMap, key)
+
+      return store as Store<TSchema, TContext>
+    }).pipe(Effect.withSpan(`StoreRegistry.getOrLoad:${options.storeId}`))
+
+  /**
+   * Get or load a store, returning it directly if already loaded or a promise if loading.
+   *
+   * @typeParam TSchema - The schema type for the store
+   * @typeParam TContext - The context type for the store
+   * @typeParam TSyncPayloadSchema - The sync payload schema type
+   * @returns The loaded store if available, or a Promise that resolves to the loaded store
+   * @throws unknown - store loading error
+   *
+   * @remarks
+   * - Returns the store instance directly (synchronous) when already loaded
+   * - Returns a stable Promise reference when loading is in progress or needs to be initiated
+   * - Throws with the same error instance on subsequent calls after failure
+   * - Applies default options from registry config, with call-site options taking precedence
+   * - Concurrent calls with the same storeId share the same store instance
+   */
+  getOrLoadPromise = <
+    TSchema extends LiveStoreSchema,
+    TContext = {},
+    TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  >(
+    options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+  ): Store<TSchema, TContext> | Promise<Store<TSchema, TContext>> => {
+    const exit = this.getOrLoad(options).pipe(Effect.scoped, Runtime.runSyncExit(this.#runtime))
+
+    if (Exit.isSuccess(exit)) return exit.value
+
+    // Check if the failure is due to async work
+    const defect = Cause.dieOption(exit.cause)
+    if (defect._tag === 'Some' && Runtime.isAsyncFiberException(defect.value)) {
+      const { storeId } = options
+
+      // Return cached promise if one exists (ensures concurrent calls get the same Promise reference)
+      const cached = this.#loadingPromises.get(storeId)
+      if (cached) return cached as Promise<Store<TSchema, TContext>>
+
+      // Create and cache the promise
+      const fiber = defect.value.fiber
+      const promise = Fiber.join(fiber)
+        .pipe(Runtime.runPromise(this.#runtime))
+        .finally(() => this.#loadingPromises.delete(storeId)) as Promise<Store<TSchema, TContext>>
+
+      this.#loadingPromises.set(storeId, promise)
+      return promise
+    }
+
+    // Handle synchronous failure
+    throw Cause.squash(exit.cause)
+  }
+
+  /**
+   * Retains the store in cache.
+   *
+   * @typeParam TSchema - The schema type for the store
+   * @typeParam TContext - The context type for the store
+   * @typeParam TSyncPayloadSchema - The sync payload schema type
+   * @returns A release function that, when called, removes this retention hold
+   *
+   * @remarks
+   * - Multiple retains on the same store are independent; each must be released separately
+   * - If the store isn't cached yet, it will be loaded and then retained
+   * - The store will remain in cache until all retains are released and after `unusedCacheTime` expires
+   */
+  retain = <
+    TSchema extends LiveStoreSchema,
+    TContext = {},
+    TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  >(
+    options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+  ): (() => void) => {
+    const release = Effect.gen(this, function* () {
+      // Cast options to satisfy StoreCacheKey's wider type (type safety enforced at API boundary)
+      const key = new StoreCacheKey(options)
+      yield* RcMap.get(this.#rcMap, key)
+      // Effect.never suspends indefinitely, keeping the RcMap reference alive.
+      // When `release()` is called, the fiber is interrupted, closing the scope
+      // and releasing the RcMap entry (which may trigger disposal after idleTimeToLive).
+      yield* Effect.never
+    }).pipe(Effect.scoped, Runtime.runCallback(this.#runtime))
+
+    return () => release()
+  }
+
+  /**
+   * Loads a store (without suspending) to warm up the cache.
+   *
+   * @typeParam TSchema - The schema of the store to preload
+   * @typeParam TContext - The context type for the store
+   * @typeParam TSyncPayloadSchema - The sync payload schema type
+   * @returns A promise that resolves when the loading is complete (success or failure)
+   *
+   * @remarks
+   * - We don't return the store or throw as this is a fire-and-forget operation.
+   * - If the entry remains unused after preload resolves/rejects, it is scheduled for disposal.
+   * - Does not affect the retention of the store in cache.
+   */
+  preload = async <
+    TSchema extends LiveStoreSchema,
+    TContext = {},
+    TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+  >(
+    options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+  ): Promise<void> => {
+    try {
+      await this.getOrLoadPromise(options)
+    } catch {
+      // Do nothing; preload is best-effort
+    }
+  }
+}
+
+/**
+ * Helper for defining reusable store options with full type inference. Returns
+ * options that can be passed to `useStore()` or `storeRegistry.preload()`.
+ *
+ * @remarks
+ * At runtime this is an identity function that returns the input unchanged.
+ * Its value lies in enabling TypeScript's excess property checking to catch
+ * typos and configuration errors, while allowing options to be shared across
+ * `useStore()`, `storeRegistry.preload()`, `storeRegistry.getOrLoad()`, etc.
+ *
+ * @typeParam TSchema - The LiveStore schema type
+ * @typeParam TContext - User-defined context attached to the store
+ * @typeParam TSyncPayloadSchema - Schema for the sync payload sent to the backend
+ * @param options - The store configuration options
+ * @returns The same options object, unchanged
+ *
+ * @example
+ * ```ts
+ * export const issueStoreOptions = (issueId: string) =>
+ *   storeOptions({
+ *     storeId: `issue-${issueId}`,
+ *     schema,
+ *     adapter,
+ *     unusedCacheTime: 30_000,
+ *   })
+ *
+ * // In a component
+ * const issueStore = useStore(issueStoreOptions(issueId))
+ *
+ * // In a route loader or event handler
+ * storeRegistry.preload({
+ *   ...issueStoreOptions(issueId),
+ *   unusedCacheTime: 10_000,
+ * });
+ * ```
+ */
+export function storeOptions<
+  TSchema extends LiveStoreSchema,
+  TContext = {},
+  TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
+>(
+  options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
+): RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema> {
+  return options
+}

package/src/store/create-store.ts

@@ -35,7 +35,7 @@ import { nanoid } from '@livestore/utils/nanoid'
 import * as otel from '@opentelemetry/api'
 
 import { connectDevtoolsToStore } from './devtools.ts'
-import { Store } from './store.ts'
+import { STORE_DEFAULT_PARAMS, Store } from './store.ts'
 import type {
   LiveStoreContextRunning as LiveStoreContextRunning_,
   OtelOptions,
@@ -43,10 +43,22 @@ import type {
 } from './store-types.ts'
 import { StoreInternalsSymbol } from './store-types.ts'
 
-export const DEFAULT_PARAMS = {
-  leaderPushBatchSize: 100,
-}
-
+/**
+ * @deprecated Use `makeStoreContext()` from `@livestore/livestore/effect` instead.
+ * This service doesn't preserve schema types. See the Effect integration docs for migration.
+ *
+ * @example Migration
+ * ```ts
+ * // Before (untyped)
+ * import { LiveStoreContextRunning } from '@livestore/livestore/effect'
+ * const { store } = yield* LiveStoreContextRunning
+ *
+ * // After (typed)
+ * import { makeStoreContext } from '@livestore/livestore/effect'
+ * const AppStore = makeStoreContext<typeof schema>()('app')
+ * const { store } = yield* AppStore.Tag
+ * ```
+ */
 export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/effect/LiveStoreContextRunning')<
   LiveStoreContextRunning,
   LiveStoreContextRunning_
@@ -58,6 +70,9 @@ export class LiveStoreContextRunning extends Context.Tag('@livestore/livestore/e
   }).pipe(Layer.unwrapScoped)
 }
 
+/**
+ * @deprecated Use `StoreContext.DeferredTag` from `makeStoreContext()` instead.
+ */
 export class DeferredStoreContext extends Context.Tag('@livestore/livestore/effect/DeferredStoreContext')<
   DeferredStoreContext,
   Deferred.Deferred<LiveStoreContextRunning['Type'], UnknownError>
@@ -101,14 +116,14 @@ export type LiveStoreContextProps<
    */
   syncPayloadSchema?: TSyncPayloadSchema
   /**
-   * Payload that is sent to the sync backend during connection establishment.
+   * Payload that is sent to the sync backend when connecting
    *
    * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
    * - At runtime this value is encoded with `syncPayloadSchema` before being handed to the adapter.
    *
    * Example:
    *   const SyncPayload = Schema.Struct({ authToken: Schema.String })
-   *   <LiveStoreProvider syncPayloadSchema={SyncPayload} syncPayload={{ authToken: '...' }} />
+   *   useStore({ ..., syncPayloadSchema: SyncPayload, syncPayload: { authToken: '...' } })
    */
   syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
 }
@@ -118,9 +133,21 @@ export interface CreateStoreOptions<
   TContext = {},
   TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
 > extends LogConfig.WithLoggerOptions {
+  /** The LiveStore schema defining tables, events, and materializers. */
   schema: TSchema
+  /** Adapter used for data storage and synchronization. */
   adapter: Adapter
+  /**
+   * Unique identifier for the Store instance, stable for its lifetime.
+   *
+   * - **Valid characters**: Only alphanumeric characters, underscores (`_`), and hyphens (`-`)
+   *   are allowed. Must match `/^[a-zA-Z0-9_-]+$/`.
+   * - **Globally unique**: Use globally unique IDs (e.g., nanoid) to prevent collisions across stores.
+   * - **Use namespaces**: Prefix to avoid collisions and for easier identification when debugging
+   *   (e.g., `app-root`, `workspace-abc123`, `issue-456`)
+   */
   storeId: string
+  /** User-defined context that will be attached to the created Store (e.g. for dependency injection). */
   context?: TContext
   boot?: (
     store: Store<TSchema, TContext>,
@@ -129,6 +156,19 @@ export interface CreateStoreOptions<
       parentSpan: otel.Span
     },
   ) => Effect.SyncOrPromiseOrEffect<void, unknown, OtelTracer.OtelTracer | LiveStoreContextRunning>
+  onBootStatus?: (status: BootStatus) => void
+  /**
+   * Needed in React so LiveStore can apply multiple events in a single render.
+   *
+   * @example
+   * ```ts
+   * // With React DOM
+   * import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
+   *
+   * // With React Native
+   * import { unstable_batchedUpdates as batchUpdates } from 'react-native'
+   * ```
+   */
   batchUpdates?: (run: () => void) => void
   /**
    * Whether to disable devtools.
@@ -136,7 +176,6 @@ export interface CreateStoreOptions<
    * @default 'auto'
    */
   disableDevtools?: boolean | 'auto'
-  onBootStatus?: (status: BootStatus) => void
   shutdownDeferred?: ShutdownDeferred
   /**
    * Currently only used in the web adapter:
@@ -154,7 +193,7 @@ export interface CreateStoreOptions<
    */
   syncPayloadSchema?: TSyncPayloadSchema
   /**
-   * Payload that is sent to the sync backend during connection establishment.
+   * Payload that is sent to the sync backend when connecting
    *
    * - Its TypeScript type is inferred from `syncPayloadSchema` (i.e. `typeof SyncPayload.Type`).
    * - At runtime this value is encoded with `syncPayloadSchema` and carried through the adapter
@@ -163,8 +202,12 @@ export interface CreateStoreOptions<
    * @default undefined
    */
   syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
+  /** Options provided to the Store constructor. */
   params?: {
+    /** Max events pushed to the leader per write batch. */
     leaderPushBatchSize?: number
+    /** Chunk size used when the stream replays confirmed events. */
+    eventQueryBatchSize?: number
     simulation?: {
       clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type
     }
@@ -347,7 +390,8 @@ export const createStore = <
         batchUpdates: (run) => run(),
         storeId,
         params: {
-          leaderPushBatchSize: params?.leaderPushBatchSize ?? DEFAULT_PARAMS.leaderPushBatchSize,
+          leaderPushBatchSize: params?.leaderPushBatchSize ?? STORE_DEFAULT_PARAMS.leaderPushBatchSize,
+          eventQueryBatchSize: params?.eventQueryBatchSize ?? STORE_DEFAULT_PARAMS.eventQueryBatchSize,
           ...omitUndefineds({ simulation: params?.simulation }),
         },
       })

package/src/store/devtools.ts

@@ -235,6 +235,7 @@ export const connectDevtoolsToStore = ({
                 sendToDevtools(
                   Devtools.ClientSession.LiveQueriesRes.make({
                     liveQueries: [...store[StoreInternalsSymbol].activeQueries].map((q) => ({
+                      /** TODO: include schema metadata for schema-aware rendering in devtools (e.g., schema AST/hash/identifier or table+columns for QueryBuilder-derived queries). */
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
@@ -316,6 +317,20 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.Ping': {
+          // Check version mismatch and respond with VersionMismatch if versions don't match
+          if (decodedMessage.liveStoreVersion !== liveStoreVersion) {
+            sendToDevtools(
+              Devtools.ClientSession.VersionMismatch.make({
+                requestId,
+                clientId,
+                sessionId,
+                liveStoreVersion,
+                appVersion: liveStoreVersion,
+                receivedVersion: decodedMessage.liveStoreVersion,
+              }),
+            )
+            break
+          }
           sendToDevtools(Devtools.ClientSession.Pong.make({ requestId, clientId, sessionId, liveStoreVersion }))
           break
         }

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

@@ -0,0 +1,112 @@
+import { makeInMemoryAdapter } from '@livestore/adapter-web'
+import type { MockSyncBackend } from '@livestore/common'
+import { type ClientSessionLeaderThreadProxy, makeMockSyncBackend, type UnknownError } from '@livestore/common'
+import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
+import { EventFactory } from '@livestore/common/testing'
+import type { ShutdownDeferred, Store } from '@livestore/livestore'
+import { createStore, makeShutdownDeferred } from '@livestore/livestore'
+import { omitUndefineds } from '@livestore/utils'
+import type { OtelTracer, Scope } from '@livestore/utils/effect'
+import { Context, Effect, FetchHttpClient, Layer, Logger, LogLevel, Queue, Stream } from '@livestore/utils/effect'
+import { nanoid } from '@livestore/utils/nanoid'
+import { PlatformNode } from '@livestore/utils/node'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { expect } from 'vitest'
+import { events, schema } from '../utils/tests/fixture.ts'
+
+const withTestCtx = Vitest.makeWithTestCtx({
+  makeLayer: () =>
+    Layer.mergeAll(
+      TestContextLive,
+      PlatformNode.NodeFileSystem.layer,
+      FetchHttpClient.layer,
+      Logger.minimumLogLevel(LogLevel.Debug),
+    ),
+})
+
+/**
+ * The purpose of this test is a store integration test for event streaming.
+ * Main test covering event streaming logic itself is located in:
+ * tests/package-common/src/leader-thread/stream-events.test.ts
+ */
+Vitest.describe('Store events API', () => {
+  Vitest.scopedLive('should resume when reconnected to sync backend', (test) =>
+    Effect.gen(function* () {
+      const { makeStore, mockSyncBackend } = yield* TestContext
+      const store = yield* makeStore()
+      yield* mockSyncBackend.connect
+
+      const eventFactory = EventFactory.makeFactory(events)({
+        client: EventFactory.clientIdentity('other-client', 'static-session-id'),
+      })
+
+      // Queue is used in order to allow analyzing the stream in stages
+      const eventsQueue = yield* Queue.unbounded<LiveStoreEvent.Client.ForSchema<typeof schema>>()
+
+      yield* store.eventsStream().pipe(
+        Stream.tap((event) => Queue.offer(eventsQueue, event)),
+        Stream.runDrain,
+        Effect.forkScoped,
+      )
+
+      store.commit(eventFactory.todoCreated.next({ id: '1', text: 't1', completed: false }))
+      const initialEvent = yield* Queue.take(eventsQueue)
+      expect(initialEvent.name).toEqual('todo.created')
+      expect(initialEvent.args).toMatchObject({ id: '1' })
+
+      yield* mockSyncBackend.disconnect
+      store.commit(eventFactory.todoCreated.next({ id: '2', text: 't2', completed: false }))
+      const maybeWhileDisconnected = yield* Queue.take(eventsQueue).pipe(Effect.timeout('250 millis'), Effect.option)
+      expect(maybeWhileDisconnected._tag).toEqual('None')
+
+      yield* mockSyncBackend.connect
+      const resumedEvent = yield* Queue.take(eventsQueue)
+      expect(resumedEvent.name).toEqual('todo.created')
+      expect(resumedEvent.args).toMatchObject({ id: '2' })
+    }).pipe(withTestCtx(test)),
+  )
+})
+
+class TestContext extends Context.Tag('TestContext')<
+  TestContext,
+  {
+    makeStore: (args?: {
+      boot?: (store: Store) => void
+      testing?: {
+        overrides?: {
+          clientSession?: {
+            leaderThreadProxy?: (
+              original: ClientSessionLeaderThreadProxy.ClientSessionLeaderThreadProxy,
+            ) => Partial<ClientSessionLeaderThreadProxy.ClientSessionLeaderThreadProxy>
+          }
+        }
+      }
+    }) => Effect.Effect<Store, UnknownError, Scope.Scope | OtelTracer.OtelTracer>
+    mockSyncBackend: MockSyncBackend
+    shutdownDeferred: ShutdownDeferred
+  }
+>() {}
+
+const TestContextLive = Layer.scoped(
+  TestContext,
+  Effect.gen(function* () {
+    const mockSyncBackend = yield* makeMockSyncBackend()
+    const shutdownDeferred = yield* makeShutdownDeferred
+
+    const makeStore: typeof TestContext.Service.makeStore = (args) => {
+      const adapter = makeInMemoryAdapter({
+        sync: { backend: () => mockSyncBackend.makeSyncBackend, onSyncError: 'shutdown' },
+        ...omitUndefineds({ testing: args?.testing }),
+      })
+      return createStore({
+        schema: schema as LiveStoreSchema,
+        adapter,
+        storeId: nanoid(),
+        shutdownDeferred,
+        ...omitUndefineds({ boot: args?.boot }),
+      })
+    }
+
+    return { makeStore, mockSyncBackend, shutdownDeferred }
+  }),
+)