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

package/src/store/StoreRegistry.ts

@@ -16,7 +16,8 @@ import {
   type Schema,
   type Scope,
 } from '@livestore/utils/effect'
-import { type CreateStoreOptions, createStore } from './create-store.ts'
+
+import { createStore, type CreateStoreOptions } from './create-store.ts'
 import type { Store } from './store.ts'
 import type { OtelOptions } from './store-types.ts'
 
@@ -65,10 +66,10 @@ export interface RegistryStoreOptions<
    * 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.
+   * - Per-store values override the registry-level default (set via `StoreRegistry` constructor's
+   *   `defaultOptions.unusedCacheTime`)
+   * - The value is fixed when the store is first loaded into the registry. If the same `storeId` is
+   *   requested again with a different `unusedCacheTime`, the original value is kept.
    * - 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}
    *
@@ -155,15 +156,16 @@ export class StoreRegistry {
   readonly #runtime: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
 
   /**
-   * In-flight loading promises keyed by storeId.
-   * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
+   * Disposal callback for the runtime created by the registry.
+   * Undefined when caller provided their own runtime (caller owns cleanup in that case).
    */
-  readonly #loadingPromises: Map<string, Promise<Store<any, any>>> = new Map()
+  readonly #disposeOwnedRuntime: (() => Promise<void>) | undefined
 
   /**
-   * Default options merged into all store configurations at load time.
+   * In-flight loading promises keyed by storeId.
+   * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
    */
-  readonly #defaultOptions: StoreRegistryConfig['defaultOptions']
+  readonly #loadingPromises: Map<string, Promise<Store<any, any>>> = new Map()
 
   /**
    * Creates a new StoreRegistry instance.
@@ -179,15 +181,18 @@ export class StoreRegistry {
    * ```
    */
   constructor(config: StoreRegistryConfig = {}) {
-    this.#defaultOptions = config.defaultOptions
-    this.#runtime =
-      config.runtime ??
-      ManagedRuntime.make(Layer.mergeAll(Layer.scope, OtelLiveDummy)).runtimeEffect.pipe(Effect.runSync)
+    if (config.runtime !== undefined) {
+      this.#runtime = config.runtime
+    } else {
+      const ownedRuntime = ManagedRuntime.make(Layer.mergeAll(Layer.scope, OtelLiveDummy))
+      this.#runtime = ownedRuntime.runtimeEffect.pipe(Effect.runSync)
+      this.#disposeOwnedRuntime = () => ownedRuntime.dispose()
+    }
 
     this.#rcMap = RcMap.make({
       lookup: ({ options }: StoreCacheKey) => {
         // Merge registry defaults with call-site options (call-site takes precedence)
-        const mergedOptions = { ...this.#defaultOptions, ...options }
+        const mergedOptions = { ...config.defaultOptions, ...options }
         return createStore(mergedOptions).pipe(
           Effect.catchAllDefect((cause) => UnknownError.make({ cause })),
           Effect.withSpan(`StoreRegistry.lookup:${mergedOptions.storeId}`),
@@ -200,9 +205,7 @@ export class StoreRegistry {
           ),
         )
       },
-      // 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,
+      idleTimeToLive: ({ options }: StoreCacheKey) => options.unusedCacheTime ?? config.defaultOptions?.unusedCacheTime ?? DEFAULT_UNUSED_CACHE_TIME,
     }).pipe(Runtime.runSync(this.#runtime))
   }
 
@@ -260,29 +263,34 @@ export class StoreRegistry {
   ): 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
+    if (Exit.isSuccess(exit) === true) 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
+    if (defect._tag !== 'Some') {
+      // Handle synchronous failure
+      throw Cause.squash(exit.cause)
+    }
 
-      // 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>>
+    if (Runtime.isAsyncFiberException(defect.value) === false) {
+      // Handle synchronous failure
+      throw Cause.squash(exit.cause)
+    }
 
-      // 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>>
+    const { storeId } = options
 
-      this.#loadingPromises.set(storeId, promise)
-      return promise
-    }
+    // Return cached promise if one exists (ensures concurrent calls get the same Promise reference)
+    const cached = this.#loadingPromises.get(storeId)
+    if (cached !== undefined) return cached as Promise<Store<TSchema, TContext>>
 
-    // Handle synchronous failure
-    throw Cause.squash(exit.cause)
+    // Create and cache the promise
+    const fiber = defect.value.fiber as Fiber.RuntimeFiber<Store<TSchema, TContext>>
+    const promise = Fiber.join(fiber)
+      .pipe(Runtime.runPromise(this.#runtime))
+      .finally(() => this.#loadingPromises.delete(storeId))
+
+    this.#loadingPromises.set(storeId, promise)
+    return promise
   }
 
   /**
@@ -344,6 +352,25 @@ export class StoreRegistry {
       // Do nothing; preload is best-effort
     }
   }
+
+  /**
+   * Disposes the registry and all its managed stores, immediately releasing resources
+   * (database connections, WebSocket connections, web workers, etc.).
+   *
+   * Most applications should use a single `StoreRegistry` and don't need to call
+   * this method. It's only necessary when creating multiple short-lived registries to
+   * immediately release resources and avoid conflicts with subsequent registries.
+   *
+   * @returns A promise that resolves when disposal is complete
+   *
+   * @remarks
+   * - No-op if a custom `runtime` was provided to the constructor (caller owns cleanup)
+   * - Idempotent: safe to call multiple times
+   * - After disposal, the registry should not be used
+   */
+  dispose = async (): Promise<void> => {
+    await this.#disposeOwnedRuntime?.()
+  }
 }
 
 /**
@@ -382,12 +409,10 @@ export class StoreRegistry {
  * });
  * ```
  */
-export function storeOptions<
+export const storeOptions = <
   TSchema extends LiveStoreSchema,
   TContext = {},
   TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
 >(
   options: RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema>,
-): RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema> {
-  return options
-}
+): RegistryStoreOptions<TSchema, TContext, TSyncPayloadSchema> => options

package/src/store/create-store.ts

@@ -1,3 +1,5 @@
+import * as otel from '@opentelemetry/api'
+
 import {
   type Adapter,
   type BootStatus,
@@ -5,13 +7,12 @@ import {
   type ClientSessionDevtoolsChannel,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
-  type InvalidPullError,
-  type IsOfflineError,
   LogConfig,
   type MaterializeError,
+  type BackendIdMismatchError,
   type MigrationsReport,
   provideOtel,
-  type SyncError,
+  type ServerAheadError,
   UnknownError,
 } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
@@ -32,16 +33,20 @@ import {
   TaskTracing,
 } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
-import * as otel from '@opentelemetry/api'
 
 import { connectDevtoolsToStore } from './devtools.ts'
-import { STORE_DEFAULT_PARAMS, Store } from './store.ts'
 import type {
   LiveStoreContextRunning as LiveStoreContextRunning_,
   OtelOptions,
   ShutdownDeferred,
 } from './store-types.ts'
 import { StoreInternalsSymbol } from './store-types.ts'
+import { STORE_DEFAULT_PARAMS, Store } from './store.ts'
+
+declare global {
+  /** Store instances for console debugging */
+  var __debugLiveStore: Record<string, Store<any, any>> | undefined
+}
 
 /**
  * @deprecated Use `makeStoreContext()` from `@livestore/livestore/effect` instead.
@@ -320,7 +325,7 @@ export const createStore = <
       const shutdown = (
         exit: Exit.Exit<
           IntentionalShutdownCause,
-          UnknownError | MaterializeError | SyncError | InvalidPullError | IsOfflineError
+          UnknownError | MaterializeError | BackendIdMismatchError
         >,
       ) =>
         Effect.gen(function* () {
@@ -332,7 +337,7 @@ export const createStore = <
             ),
           )
 
-          if (shutdownDeferred) {
+          if (shutdownDeferred !== undefined) {
             yield* Deferred.done(shutdownDeferred, exit)
           }
 
@@ -364,7 +369,7 @@ export const createStore = <
         syncPayloadEncoded,
       }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
 
-      if (LS_DEV && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
+      if (LS_DEV === true && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {
         yield* Effect.logDebug(
           '[@livestore/livestore:createStore] migrationsReport',
           ...clientSession.leaderThread.initialState.migrationsReport.migrations.map((m) =>
@@ -383,7 +388,7 @@ export const createStore = <
         effectContext: { lifetimeScope, runtime },
         // TODO find a better way to detect if we're running LiveStore in the LiveStore devtools
         // But for now this is a good enough approximation with little downsides
-        __runningInDevtools: getDevtoolsEnabled(disableDevtools) === false,
+        __runningInDevtools: ! getDevtoolsEnabled(disableDevtools),
         confirmUnsavedChanges,
         // NOTE during boot we're not yet executing events in a batched context
         // but only set the provided `batchUpdates` function after boot
@@ -420,11 +425,21 @@ export const createStore = <
 
       yield* Deferred.succeed(storeDeferred, store as any as Store)
 
+      // Expose store on globalThis for console debugging
+      globalThis.__debugLiveStore ??= {}
+      globalThis.__debugLiveStore[storeId] = store
+
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          delete globalThis.__debugLiveStore?.[storeId]
+        }),
+      )
+
       return store
     }).pipe(
       Effect.withSpan('createStore', { attributes: { debugInstanceId, storeId } }),
       Effect.annotateLogs({ debugInstanceId, storeId }),
-      LS_DEV ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
+      LS_DEV === true ? TaskTracing.withAsyncTaggingTracing((name) => (console as any).createTask(name)) : identity,
       Scope.extend(lifetimeScope),
     )
   })
@@ -433,7 +448,7 @@ const validateStoreId = (storeId: string) =>
   Effect.gen(function* () {
     const validChars = /^[a-zA-Z0-9_-]+$/
 
-    if (!validChars.test(storeId)) {
+    if (validChars.test(storeId) === false) {
       return yield* UnknownError.make({
         cause: `Invalid storeId: ${storeId}. Only alphanumeric characters, underscores, and hyphens are allowed.`,
         payload: { storeId },

package/src/store/devtools.ts

@@ -7,8 +7,8 @@ import { nanoid } from '@livestore/utils/nanoid'
 
 import { NOT_REFRESHED_YET } from '../reactive.ts'
 import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.ts'
-import type { Store } from './store.ts'
 import { StoreInternalsSymbol } from './store-types.ts'
+import type { Store } from './store.ts'
 
 type Unsub = () => void
 type RequestId = string
@@ -23,7 +23,7 @@ const requestNextTick: (cb: () => void) => number =
 const cancelTick: (id: number) => void =
   globalThis.cancelAnimationFrame === undefined ? (id: number) => clearTimeout(id) : globalThis.cancelAnimationFrame
 
-export const connectDevtoolsToStore = ({
+export const connectDevtoolsToStore = Effect.fn('LSD.devtools.connectStoreToDevtools')(function* ({
   storeDevtoolsChannel,
   store,
 }: {
@@ -32,8 +32,7 @@ export const connectDevtoolsToStore = ({
     Devtools.ClientSession.MessageFromApp
   >
   store: Store
-}) =>
-  Effect.gen(function* () {
+}) {
     const reactivityGraphSubcriptions: SubMap = new Map()
     const liveQueriesSubscriptions: SubMap = new Map()
     const debugInfoHistorySubscriptions: SubMap = new Map()
@@ -88,7 +87,7 @@ export const connectDevtoolsToStore = ({
       // So far I could only observe this problem with webmesh proxy channels (e.g. for Expo)
       // Proof: https://share.cleanshot.com/V9G87B0B
       // Also see `leader-worker-devtools.ts` for same problem
-      if (handledRequestIds.has(requestId)) {
+      if (handledRequestIds.has(requestId) === true) {
         return
       }
 
@@ -347,4 +346,4 @@ export const connectDevtoolsToStore = ({
       Stream.runDrain,
       Effect.withSpan('LSD.devtools.onMessage'),
     )
-  }).pipe(UnknownError.mapToUnknownError, Effect.withSpan('LSD.devtools.connectStoreToDevtools'))
+}, UnknownError.mapToUnknownError)

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

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

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

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

package/src/store/store-types.ts

@@ -1,22 +1,22 @@
+import type * as otel from '@opentelemetry/api'
+
 import {
   type ClientSession,
   type ClientSessionSyncProcessor,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
-  type InvalidPullError,
-  type IsOfflineError,
   isQueryBuilder,
   type MaterializeError,
   type QueryBuilder,
   type StoreInterrupted,
-  type SyncError,
+  type BackendIdMismatchError,
   type UnknownError,
 } from '@livestore/common'
 import type { StreamEventsOptions } from '@livestore/common/leader-thread'
 import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
 import type { Effect, Runtime, Schema, Scope } from '@livestore/utils/effect'
 import { Deferred, Predicate } from '@livestore/utils/effect'
-import type * as otel from '@opentelemetry/api'
+
 import type {
   LiveQuery,
   LiveQueryDef,
@@ -45,20 +45,20 @@ export type LiveStoreContext<TSchema extends LiveStoreSchema = LiveStoreSchema.A
   | LiveStoreContextRunning<TSchema>
   | {
       stage: 'error'
-      error: UnknownError | unknown
+      error: unknown
     }
   | {
       stage: 'shutdown'
-      cause: IntentionalShutdownCause | StoreInterrupted | SyncError
+      cause: IntentionalShutdownCause | StoreInterrupted | UnknownError
     }
 
 export type ShutdownDeferred = Deferred.Deferred<
   IntentionalShutdownCause,
-  UnknownError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError
+  UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError
 >
 export const makeShutdownDeferred: Effect.Effect<ShutdownDeferred> = Deferred.make<
   IntentionalShutdownCause,
-  UnknownError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError
+  UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError
 >()
 
 /**
@@ -416,3 +416,42 @@ export const isLiveQueryInstance = (value: unknown): value is LiveQuery<any> =>
  */
 export const isQueryable = (value: unknown): value is Queryable<unknown> =>
   isQueryBuilder(value) || isLiveQueryInstance(value) || isLiveQueryDef(value)
+
+/**
+ * Represents the current synchronization status of the store.
+ *
+ * This provides visibility into the sync state between the client session
+ * and the leader thread, allowing applications to show sync indicators
+ * or determine backend health.
+ *
+ * @example
+ * ```ts
+ * const status = store.syncStatus()
+ * if (status.isSynced) {
+ *   console.log('All changes synced')
+ * } else {
+ *   console.log(`${status.pendingCount} events pending sync`)
+ * }
+ * ```
+ */
+export type SyncStatus = {
+  /**
+   * The local head sequence number (most recent event in the client session).
+   * Represented as a string in the format "e{global}.{client}" (e.g., "e5.2").
+   */
+  localHead: string
+  /**
+   * The upstream head sequence number (what the leader thread has confirmed).
+   * Represented as a string in the format "e{global}" (e.g., "e3").
+   */
+  upstreamHead: string
+  /**
+   * Number of events pending synchronization to the leader thread.
+   */
+  pendingCount: number
+  /**
+   * Whether the client session is fully synced with the leader thread.
+   * True when there are no pending events (pendingCount === 0).
+   */
+  isSynced: boolean
+}