@livestore/react 0.4.0-dev.20 → 0.4.0-dev.21

package/src/experimental/multi-store/StoreRegistry.ts

@@ -1,13 +1,21 @@
+import { OtelLiveDummy, UnknownError } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
-import { createStorePromise, type Store, type Unsubscribe } from '@livestore/livestore'
-import type { CachedStoreOptions, StoreId } from './types.ts'
-
-type StoreEntryState<TSchema extends LiveStoreSchema> =
-  | { status: 'idle' }
-  | { status: 'loading'; promise: Promise<Store<TSchema>>; abortController: AbortController }
-  | { status: 'success'; store: Store<TSchema> }
-  | { status: 'error'; error: unknown }
-  | { status: 'shutting_down'; shutdownPromise: Promise<void> }
+import { createStore, type Store } from '@livestore/livestore'
+import {
+  Cause,
+  Effect,
+  Equal,
+  Exit,
+  Fiber,
+  Hash,
+  Layer,
+  ManagedRuntime,
+  type OtelTracer,
+  RcMap,
+  Runtime,
+  type Scope,
+} from '@livestore/utils/effect'
+import type { CachedStoreOptions } from './types.ts'
 
 /**
  * Default time to keep unused stores in cache.
@@ -19,310 +27,214 @@ type StoreEntryState<TSchema extends LiveStoreSchema> =
  */
 export const DEFAULT_UNUSED_CACHE_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
 
-/**
- * @typeParam TSchema - The schema for this entry's store.
- * @internal
- */
-class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
-  readonly #storeId: StoreId
-  readonly #cache: StoreCache
-
-  #state: StoreEntryState<TSchema> = { status: 'idle' }
-
-  #unusedCacheTime?: number
-  #disposalTimeout?: ReturnType<typeof setTimeout> | null
-
+type DefaultStoreOptions = Partial<
+  Pick<
+    CachedStoreOptions,
+    'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug' | 'otelOptions'
+  >
+> & {
+  /**
+   * The time in milliseconds that unused stores remain in memory.
+   * When a 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
+   * - If set to `Infinity`, will disable 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
   /**
-   * Set of subscriber callbacks to notify on state changes.
+   * Optionally, pass a custom runtime that will be used to run all operations (loading, caching, etc.).
    */
-  readonly #subscribers = new Set<() => void>()
-
-  constructor(storeId: StoreId, cache: StoreCache) {
-    this.#storeId = storeId
-    this.#cache = cache
-  }
-
-  #scheduleDisposal = (): void => {
-    this.#cancelDisposal()
-
-    const effectiveTime = this.#unusedCacheTime === undefined ? DEFAULT_UNUSED_CACHE_TIME : this.#unusedCacheTime
-
-    if (effectiveTime === Number.POSITIVE_INFINITY) return // Infinity disables disposal
-
-    this.#disposalTimeout = setTimeout(() => {
-      this.#disposalTimeout = null
-
-      // Re-check to avoid racing with a new subscription
-      if (this.#subscribers.size > 0) return
-
-      // Abort any in-progress loading to release resources early
-      this.#abortLoading()
-
-      // Transition to shutting_down state BEFORE starting async shutdown.
-      // This prevents new subscribers from receiving a store that's about to be disposed.
-      const shutdownPromise = this.#shutdown().finally(() => {
-        // Reset to idle so fresh loads can proceed, then remove from cache if still inactive
-        this.#setIdle()
-        if (this.#subscribers.size === 0) this.#cache.delete(this.#storeId)
-      })
+  runtime?: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
+}
 
-      this.#setShuttingDown(shutdownPromise)
-    }, effectiveTime)
-  }
+/**
+ * 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<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> implements Equal.Equal {
+  readonly options: CachedStoreOptions<TSchema>
 
-  #cancelDisposal = (): void => {
-    if (!this.#disposalTimeout) return
-    clearTimeout(this.#disposalTimeout)
-    this.#disposalTimeout = null
+  constructor(options: CachedStoreOptions<TSchema>) {
+    this.options = options
   }
 
   /**
-   * Transitions to the loading state.
+   * Equality is based solely on `storeId`. Other options in `CachedStoreOptions` are ignored
+   * for cache key comparison. The first options used for a given `storeId` determine the
+   * store's configuration.
    */
-  #setLoading(promise: Promise<Store<TSchema>>, abortController: AbortController): void {
-    if (this.#state.status === 'success' || this.#state.status === 'loading') return
-    this.#state = { status: 'loading', promise, abortController }
-    this.#notify()
+  [Equal.symbol](that: Equal.Equal): boolean {
+    return that instanceof StoreCacheKey && this.options.storeId === that.options.storeId
   }
 
-  /**
-   * Transitions to the success state.
-   */
-  #setStore = (store: Store<TSchema>): void => {
-    this.#state = { status: 'success', store }
-    this.#notify()
+  [Hash.symbol](): number {
+    return Hash.string(this.options.storeId)
   }
+}
 
+/**
+ * Store Registry coordinating store loading, caching, and retention
+ *
+ * @public
+ */
+export class StoreRegistry {
   /**
-   * Transitions to the error state.
+   * Reference-counted cache mapping storeId to Store instances.
+   * Stores are created on first access and disposed after `unusedCacheTime` when all references are released.
    */
-  #setError = (error: unknown): void => {
-    this.#state = { status: 'error', error }
-    this.#notify()
-  }
+  #rcMap: RcMap.RcMap<StoreCacheKey<any>, Store, UnknownError>
 
   /**
-   * Transitions to the shutting_down state.
+   * Effect runtime providing Scope and OtelTracer for all registry operations.
+   * When the runtime's scope closes, all managed stores are automatically shut down.
    */
-  #setShuttingDown = (shutdownPromise: Promise<void>): void => {
-    this.#state = { status: 'shutting_down', shutdownPromise }
-    this.#notify()
-  }
+  #runtime: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
 
   /**
-   * Transitions to the idle state.
+   * In-flight loading promises keyed by storeId.
+   * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
    */
-  #setIdle = (): void => {
-    this.#state = { status: 'idle' }
-    // No notify needed - getOrLoad will handle the fresh load
-  }
+  #loadingPromises: Map<string, Promise<Store<any>>> = new Map()
 
   /**
-   * Notifies all subscribers of state changes.
+   * Creates a new StoreRegistry instance.
    *
-   * @remarks
-   * This should be called after any meaningful state change.
-   */
-  #notify = (): void => {
-    for (const sub of this.#subscribers) {
-      try {
-        sub()
-      } catch {
-        // Swallow to protect other listeners
-      }
-    }
-  }
-
-  /**
-   * Subscribes to this entry's updates.
+   * @param params.defaultOptions - Default options applied to all stores managed by this registry when they are loaded.
    *
-   * @param listener - Callback invoked when the entry changes
-   * @returns Unsubscribe function
+   * @example
+   * ```ts
+   * const registry = new StoreRegistry({
+   *   defaultOptions: {
+   *     batchUpdates,
+   *     unusedCacheTime: 30_000,
+   *   }
+   * })
+   * ```
    */
-  subscribe = (listener: () => void): Unsubscribe => {
-    this.#cancelDisposal()
-    this.#subscribers.add(listener)
-    return () => {
-      this.#subscribers.delete(listener)
-      // If no more subscribers remain, schedule disposal
-      if (this.#subscribers.size === 0) this.#scheduleDisposal()
-    }
+  constructor(params: { defaultOptions?: DefaultStoreOptions } = {}) {
+    this.#runtime =
+      params.defaultOptions?.runtime ??
+      ManagedRuntime.make(Layer.mergeAll(Layer.scope, OtelLiveDummy)).runtimeEffect.pipe(Effect.runSync)
+
+    this.#rcMap = RcMap.make({
+      lookup: (key: StoreCacheKey) =>
+        Effect.gen(this, function* () {
+          const { options } = key
+
+          return yield* createStore(options).pipe(Effect.catchAllDefect((cause) => UnknownError.make({ cause })))
+        }).pipe(Effect.withSpan(`StoreRegistry.lookup:${key.options.storeId}`)),
+      // TODO: Make idleTimeToLive vary for each store when Effect supports per-resource TTL
+      // See https://github.com/livestorejs/livestore/issues/917
+      idleTimeToLive: params.defaultOptions?.unusedCacheTime ?? DEFAULT_UNUSED_CACHE_TIME,
+    }).pipe(Runtime.runSync(this.#runtime))
   }
 
   /**
-   * Gets the loaded store or initiates loading if not already in progress.
+   * Gets a cached store or loads a new one, with the store lifetime scoped to the caller.
    *
-   * @param options - Store creation options
-   * @returns The loaded store if available, or a Promise that resolves to the loaded store
+   * @typeParam TSchema - The schema type for the store
+   * @returns An Effect that yields the store, scoped to the provided Scope
    *
    * @remarks
-   * This method handles the complete lifecycle of loading a store:
-   * - Returns the store directly if already loaded (synchronous)
-   * - Returns a Promise if loading is in progress or needs to be initiated
-   * - Transitions through loading → success/error states
-   * - Schedules disposal when loading completes without active subscribers
+   * - 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 = (options: CachedStoreOptions<TSchema>): Store<TSchema> | Promise<Store<TSchema>> => {
-    if (options.unusedCacheTime !== undefined)
-      this.#unusedCacheTime = Math.max(this.#unusedCacheTime ?? 0, options.unusedCacheTime)
-
-    if (this.#state.status === 'success') return this.#state.store
-    if (this.#state.status === 'loading') return this.#state.promise
-    if (this.#state.status === 'error') throw this.#state.error
-
-    // Wait for shutdown to complete, then recursively call to load a fresh store
-    if (this.#state.status === 'shutting_down') {
-      return this.#state.shutdownPromise.then(() => this.getOrLoad(options))
-    }
-
-    const abortController = new AbortController()
-
-    const promise = createStorePromise({ ...options, signal: abortController.signal })
-      .then((store) => {
-        this.#setStore(store)
-        return store
-      })
-      .catch((error) => {
-        this.#setError(error)
-        throw error
-      })
-      .finally(() => {
-        // The store entry may have become unused (no subscribers) while loading the store
-        if (this.#subscribers.size === 0) this.#scheduleDisposal()
-      })
-
-    this.#setLoading(promise, abortController)
+  getOrLoad = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): Effect.Effect<Store<TSchema>, UnknownError, Scope.Scope> =>
+    Effect.gen(this, function* () {
+      const key = new StoreCacheKey(options)
+      const store = yield* RcMap.get(this.#rcMap, key)
 
-    return promise
-  }
+      return store as unknown as Store<TSchema>
+    }).pipe(Effect.withSpan(`StoreRegistry.getOrLoad:${options.storeId}`))
 
   /**
-   * Aborts an in-progress store load.
+   * Get or load a store, returning it directly if already loaded or a promise if loading.
    *
-   * This signals the createStorePromise to cancel, releasing resources like
-   * worker threads, SQLite connections, and network requests.
+   * @typeParam TSchema - The schema type for the store
+   * @returns The loaded store if available, or a Promise that resolves to the loaded store
+   * @throws unknown 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
    */
-  #abortLoading = (): void => {
-    if (this.#state.status !== 'loading') return
-    this.#state.abortController.abort()
-  }
+  getOrLoadPromise = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): Store<TSchema> | Promise<Store<TSchema>> => {
+    const exit = this.getOrLoad<TSchema>(options).pipe(Effect.scoped, Runtime.runSyncExit(this.#runtime))
 
-  #shutdown = async (): Promise<void> => {
-    if (this.#state.status !== 'success') return
-    await this.#state.store.shutdownPromise().catch((reason) => {
-      console.warn(`Store ${this.#storeId} failed to shutdown cleanly during disposal:`, reason)
-    })
-  }
-}
+    if (Exit.isSuccess(exit)) return exit.value as Store<TSchema>
 
-/**
- * In-memory map of {@link StoreEntry} instances keyed by {@link StoreId}.
- *
- * @privateRemarks
- * The cache is intentionally small; eviction and disposal timers are coordinated by the client.
- *
- * @internal
- */
-class StoreCache {
-  readonly #entries = new Map<StoreId, StoreEntry>()
+    // 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
 
-  get = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> | undefined => {
-    return this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
-  }
+      // 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>>
 
-  ensure = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> => {
-    let entry = this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
+      // 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>>
 
-    if (!entry) {
-      entry = new StoreEntry<TSchema>(storeId, this)
-      this.#entries.set(storeId, entry as unknown as StoreEntry)
+      this.#loadingPromises.set(storeId, promise)
+      return promise
     }
 
-    return entry
-  }
-
-  /**
-   * Removes an entry from the cache.
-   *
-   * @param storeId - The ID of the store to remove
-   */
-  delete = (storeId: StoreId): void => {
-    this.#entries.delete(storeId)
-  }
-}
-
-type DefaultStoreOptions = Partial<
-  Pick<
-    CachedStoreOptions<any>,
-    'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug' | 'otelOptions'
-  >
-> & {
-  /**
-   * The time in milliseconds that unused stores remain in memory.
-   * When a store becomes unused (no subscribers), it will be disposed
-   * after this duration.
-   *
-   * Stores transition to the unused state as soon as they have no
-   * subscriptions registered, so when all components which use that
-   * store have unmounted.
-   *
-   * @remarks
-   * - If set to `Infinity`, will disable 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 = {
-  defaultOptions?: DefaultStoreOptions
-}
-
-/**
- * Store Registry coordinating store loading, caching, and subscription
- *
- * @public
- */
-export class StoreRegistry {
-  readonly #cache = new StoreCache()
-  readonly #defaultOptions: DefaultStoreOptions
-
-  constructor({ defaultOptions = {} }: StoreRegistryConfig = {}) {
-    this.#defaultOptions = defaultOptions
+    // Handle synchronous failure
+    throw Cause.squash(exit.cause)
   }
 
-  #applyDefaultOptions = <TSchema extends LiveStoreSchema>(
-    options: CachedStoreOptions<TSchema>,
-  ): CachedStoreOptions<TSchema> => ({
-    ...this.#defaultOptions,
-    ...options,
-  })
-
   /**
-   * Get or load a store, returning it directly if loaded or a promise if loading.
+   * Retains the store in cache until the returned release function is called.
    *
-   * @typeParam TSchema - The schema of the store to load
-   * @returns The loaded store if available, or a Promise that resolves to the loaded store
-   * @throws unknown loading error
+   * @returns A release function that, when called, removes this retention hold
    *
    * @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
-   * - Applies default options from registry config, with call-site options taking precedence
+   * - 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
    */
-  getOrLoad = <TSchema extends LiveStoreSchema>(
-    options: CachedStoreOptions<TSchema>,
-  ): Store<TSchema> | Promise<Store<TSchema>> => {
-    const optionsWithDefaults = this.#applyDefaultOptions(options)
-    const storeEntry = this.#cache.ensure<TSchema>(optionsWithDefaults.storeId)
+  retain = (options: CachedStoreOptions<any>): (() => void) => {
+    const release = Effect.gen(this, function* () {
+      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 storeEntry.getOrLoad(optionsWithDefaults)
+    return () => release()
   }
 
   /**
-   * Warms the cache for a store without mounting a subscriber.
+   * Warms the cache for a store without adding a retention.
    *
    * @typeParam TSchema - The schema of the store to preload
    * @returns A promise that resolves when the loading is complete (success or failure)
@@ -333,15 +245,9 @@ export class StoreRegistry {
    */
   preload = async <TSchema extends LiveStoreSchema>(options: CachedStoreOptions<TSchema>): Promise<void> => {
     try {
-      await this.getOrLoad(options)
+      await this.getOrLoadPromise(options)
     } catch {
       // Do nothing; preload is best-effort
     }
   }
-
-  subscribe = <TSchema extends LiveStoreSchema>(storeId: StoreId, listener: () => void): Unsubscribe => {
-    const entry = this.#cache.ensure<TSchema>(storeId)
-
-    return entry.subscribe(listener)
-  }
 }

package/src/experimental/multi-store/types.ts

@@ -1,55 +1,37 @@
-import type { Adapter } from '@livestore/common'
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import type { CreateStoreOptions, OtelOptions } from '@livestore/livestore'
 
-export type StoreId = string
-
-/**
- * Minimum information required to create a store
- */
-export type StoreDescriptor<TSchema extends LiveStoreSchema> = {
-  /**
-   * Schema describing the data structure.
-   */
-  readonly schema: TSchema
-
+export type CachedStoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = Pick<
+  CreateStoreOptions<TSchema, TContext>,
+  | 'storeId'
+  | 'schema'
+  | 'adapter'
+  | 'boot'
+  | 'batchUpdates'
+  | 'disableDevtools'
+  | 'confirmUnsavedChanges'
+  | 'syncPayload'
+  | 'debug'
+  | 'shutdownDeferred'
+> & {
+  signal?: AbortSignal
+  otelOptions?: Partial<OtelOptions>
   /**
-   * Adapter for persistence and synchronization.
+   * 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
+   * - When different `unusedCacheTime` values are used for the same store, the longest one will be used.
+   * - 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.
    */
-  readonly adapter: Adapter
-
-  /**
-   * The ID of the store.
-   */
-  readonly storeId: StoreId
+  unusedCacheTime?: number
 }
-
-export type CachedStoreOptions<
-  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
-  TContext = {},
-> = StoreDescriptor<TSchema> &
-  Pick<
-    CreateStoreOptions<TSchema, TContext>,
-    'boot' | 'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug'
-  > & {
-    signal?: AbortSignal
-    otelOptions?: Partial<OtelOptions>
-    /**
-     * The time in milliseconds that this store should remain
-     * in memory after becoming unused. When this store becomes
-     * unused (no subscribers), it will be disposed after this duration.
-     *
-     * Stores transition to the unused state as soon as they have no
-     * subscriptions registered, so when all components which use that
-     * store have unmounted.
-     *
-     * @remarks
-     * - When different `unusedCacheTime` values are used for the same store, the longest one will be used.
-     * - 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
-  }