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

package/dist/store/StoreRegistry.js

@@ -0,0 +1,267 @@
+import { LogConfig, OtelLiveDummy, provideOtel, UnknownError } from '@livestore/common';
+import { omitUndefineds } from '@livestore/utils';
+import { Cause, Effect, Equal, Exit, Fiber, Hash, Layer, ManagedRuntime, RcMap, Runtime, } from '@livestore/utils/effect';
+import { createStore } from "./create-store.js";
+/**
+ * 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;
+/**
+ * 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 {
+    options;
+    constructor(options) {
+        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) {
+        return that instanceof StoreCacheKey && this.options.storeId === that.options.storeId;
+    }
+    [Hash.symbol]() {
+        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.
+     */
+    #rcMap;
+    /**
+     * Effect runtime providing Scope and OtelTracer for all registry operations.
+     * When the runtime's scope closes, all managed stores are automatically shut down.
+     */
+    #runtime;
+    /**
+     * Disposal callback for the runtime created by the registry.
+     * Undefined when caller provided their own runtime (caller owns cleanup in that case).
+     */
+    #disposeOwnedRuntime;
+    /**
+     * In-flight loading promises keyed by storeId.
+     * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
+     */
+    #loadingPromises = new Map();
+    /**
+     * Creates a new StoreRegistry instance.
+     *
+     * @example
+     * ```ts
+     * const registry = new StoreRegistry({
+     *   defaultOptions: {
+     *     batchUpdates,
+     *     unusedCacheTime: 30_000,
+     *   }
+     * })
+     * ```
+     */
+    constructor(config = {}) {
+        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 }) => {
+                // Merge registry defaults with call-site options (call-site takes precedence)
+                const mergedOptions = { ...config.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,
+                })));
+            },
+            idleTimeToLive: ({ options }) => options.unusedCacheTime ?? 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 = (options) => 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;
+    }).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 = (options) => {
+        const exit = this.getOrLoad(options).pipe(Effect.scoped, Runtime.runSyncExit(this.#runtime));
+        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') {
+            // Handle synchronous failure
+            throw Cause.squash(exit.cause);
+        }
+        if (Runtime.isAsyncFiberException(defect.value) === false) {
+            // Handle synchronous failure
+            throw Cause.squash(exit.cause);
+        }
+        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 !== undefined)
+            return cached;
+        // 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));
+        this.#loadingPromises.set(storeId, promise);
+        return promise;
+    };
+    /**
+     * 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 = (options) => {
+        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 (options) => {
+        try {
+            await this.getOrLoadPromise(options);
+        }
+        catch {
+            // 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 () => {
+        await this.#disposeOwnedRuntime?.();
+    };
+}
+/**
+ * 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 const storeOptions = (options) => options;
+//# sourceMappingURL=StoreRegistry.js.map

package/dist/store/StoreRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoreRegistry.js","sourceRoot":"","sources":["../../src/store/StoreRegistry.ts"],"names":[],"mappings":"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"}

package/dist/store/StoreRegistry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StoreRegistry.test.d.ts.map

package/dist/store/StoreRegistry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoreRegistry.test.d.ts","sourceRoot":"","sources":["../../src/store/StoreRegistry.test.ts"],"names":[],"mappings":""}

package/dist/store/StoreRegistry.test.js

@@ -0,0 +1,381 @@
+import { describe, expect, it } from '@effect/vitest';
+import { makeInMemoryAdapter } from '@livestore/adapter-web';
+import { OtelLiveDummy, UnknownError } from '@livestore/common';
+import { Effect, Fiber, TestClock } from '@livestore/utils/effect';
+import { schema } from "../utils/tests/fixture.js";
+import { StoreInternalsSymbol } from "./store-types.js";
+import { StoreRegistry, storeOptions } from "./StoreRegistry.js";
+describe('StoreRegistry', () => {
+    it('returns a promise when the store is loading', async () => {
+        const storeRegistry = new StoreRegistry();
+        const result = storeRegistry.getOrLoadPromise(testStoreOptions());
+        expect(result).toBeInstanceOf(Promise);
+        // Clean up
+        const store = await result;
+        await store.shutdownPromise();
+    });
+    it('returns cached store synchronously after first load resolves', async () => {
+        const storeRegistry = new StoreRegistry();
+        const initial = storeRegistry.getOrLoadPromise(testStoreOptions());
+        expect(initial).toBeInstanceOf(Promise);
+        const store = await initial;
+        const cached = storeRegistry.getOrLoadPromise(testStoreOptions());
+        expect(cached).toBe(store);
+        expect(cached).not.toBeInstanceOf(Promise);
+        // Clean up
+        await store.shutdownPromise();
+    });
+    it('reuses the same promise for concurrent getOrLoadPromise calls while loading', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        const first = storeRegistry.getOrLoadPromise(options);
+        const second = storeRegistry.getOrLoadPromise(options);
+        // Both should be the same promise
+        expect(first).toBe(second);
+        expect(first).toBeInstanceOf(Promise);
+        const store = await first;
+        // Both promises should resolve to the same store
+        expect(await second).toBe(store);
+        // Clean up
+        await store.shutdownPromise();
+    });
+    it('throws synchronously and rethrows on subsequent calls for sync failures', () => {
+        const storeRegistry = new StoreRegistry();
+        const badOptions = testStoreOptions({
+            // @ts-expect-error - intentionally passing invalid adapter to trigger error
+            adapter: null,
+        });
+        // First call throws synchronously
+        expect(() => storeRegistry.getOrLoadPromise(badOptions)).toThrow();
+        // Subsequent call should also throw synchronously (cached error)
+        expect(() => storeRegistry.getOrLoadPromise(badOptions)).toThrow();
+    });
+    it('caches and rethrows rejection on subsequent calls for async failures', async () => {
+        const storeRegistry = new StoreRegistry();
+        // Create an adapter that fails asynchronously (after yielding to the event loop)
+        const failingAdapter = () => Effect.gen(function* () {
+            yield* Effect.sleep(0); // Force async execution
+            return yield* UnknownError.make({ cause: new Error('Async failure') });
+        });
+        const badOptions = testStoreOptions({
+            adapter: failingAdapter,
+        });
+        // First call returns a promise that rejects
+        await expect(storeRegistry.getOrLoadPromise(badOptions)).rejects.toThrow();
+        // Subsequent call should throw the cached error synchronously (RcMap caches failures)
+        expect(() => storeRegistry.getOrLoadPromise(badOptions)).toThrow();
+    });
+    it('throws the same error instance on multiple calls after failure', async () => {
+        const storeRegistry = new StoreRegistry();
+        // Create an adapter that fails asynchronously
+        const failingAdapter = () => Effect.gen(function* () {
+            yield* Effect.sleep(0); // Force async execution
+            return yield* UnknownError.make({ cause: new Error('Async failure') });
+        });
+        const badOptions = testStoreOptions({
+            adapter: failingAdapter,
+        });
+        // Wait for the first failure
+        await expect(storeRegistry.getOrLoadPromise(badOptions)).rejects.toThrow();
+        // Capture the errors from subsequent calls
+        let error1;
+        let error2;
+        try {
+            storeRegistry.getOrLoadPromise(badOptions);
+        }
+        catch (err) {
+            error1 = err;
+        }
+        try {
+            storeRegistry.getOrLoadPromise(badOptions);
+        }
+        catch (err) {
+            error2 = err;
+        }
+        // Both should be the exact same error instance (cached)
+        expect(error1).toBeDefined();
+        expect(error1).toBe(error2);
+    });
+    it('preload does not throw', async () => {
+        const storeRegistry = new StoreRegistry();
+        // Create invalid options that would cause an error
+        const badOptions = testStoreOptions({
+            // @ts-expect-error - intentionally passing invalid adapter to trigger error
+            adapter: null,
+        });
+        // preload should not throw
+        await expect(storeRegistry.preload(badOptions)).resolves.toBeUndefined();
+        // But subsequent getOrLoadStore should throw the cached error
+        expect(() => storeRegistry.getOrLoadPromise(badOptions)).toThrow();
+    });
+    it('warms the cache so subsequent getOrLoadStore is synchronous after preload', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions();
+        // Preload the store
+        await storeRegistry.preload(options);
+        // Subsequent getOrLoadStore should return synchronously (not a Promise)
+        const store = storeRegistry.getOrLoadPromise(options);
+        expect(store).not.toBeInstanceOf(Promise);
+        // TypeScript doesn't narrow the type, so we need to assert
+        if (store instanceof Promise) {
+            throw new Error('Expected store, got Promise');
+        }
+        // Clean up
+        await store.shutdownPromise();
+    });
+    it.layer(OtelLiveDummy)('time-dependent (using TestClock)', (it) => {
+        it.scoped('disposes store after unusedCacheTime expires', () => Effect.gen(function* () {
+            const unusedCacheTime = 25;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Store should still be in cache
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+            // Let the idle timer fiber register its sleep with TestClock
+            yield* Effect.yieldNow();
+            // Advance time past unusedCacheTime → idle timer fires → entry evicted
+            yield* TestClock.adjust(unusedCacheTime);
+            // After eviction, a new load should produce a different store
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+            expect(nextStore[StoreInternalsSymbol].clientSession.debugInstanceId).toBeDefined();
+        }));
+        it.scoped('does not dispose when unusedCacheTime is Infinity', () => Effect.gen(function* () {
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime: Number.POSITIVE_INFINITY } });
+            const options = testStoreOptions();
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Advance a large amount of time — no idle timer was started for Infinity
+            yield* TestClock.adjust(100_000);
+            // Store should still be cached
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+        }));
+        it.scoped('schedules disposal if store becomes unused during loading', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            // Load without retaining — disposal is scheduled when scope closes
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // Store should be disposed
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+        it.scoped('allows call-site options to override default options', () => Effect.gen(function* () {
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime: 10_000 } }); // Long default
+            const unusedCacheTimeOverride = 25;
+            const options = testStoreOptions({ unusedCacheTime: unusedCacheTimeOverride });
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTimeOverride);
+            // Should be disposed according to the override time, not default
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+        it.scoped('disposes different stores according to their own unusedCacheTime', () => Effect.gen(function* () {
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime: 1000 } });
+            const shortOptions = testStoreOptions({ storeId: 'short-lived', unusedCacheTime: 25 });
+            const longOptions = testStoreOptions({ storeId: 'long-lived', unusedCacheTime: 10_000 });
+            const shortStore = yield* registry.getOrLoad(shortOptions).pipe(Effect.scoped);
+            const longStore = yield* registry.getOrLoad(longOptions).pipe(Effect.scoped);
+            yield* Effect.yieldNow();
+            // Advance past short store's unusedCacheTime only
+            yield* TestClock.adjust(25);
+            // Short store should be disposed, long store should still be cached
+            const nextShortStore = yield* registry.getOrLoad(shortOptions).pipe(Effect.scoped);
+            expect(nextShortStore).not.toBe(shortStore);
+            const cachedLongStore = yield* registry.getOrLoad(longOptions).pipe(Effect.scoped);
+            expect(cachedLongStore).toBe(longStore);
+        }));
+        // This test is skipped because we don't yet support dynamic `unusedCacheTime` updates for cached stores.
+        // See https://github.com/livestorejs/livestore/issues/918
+        it.scoped.skip('keeps the longest unusedCacheTime seen for a store when options vary across calls', () => Effect.gen(function* () {
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime });
+            const options = testStoreOptions({ unusedCacheTime: 10 });
+            const release = registry.retain(options);
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Call with longer unusedCacheTime
+            yield* registry.getOrLoad(testStoreOptions({ unusedCacheTime: 100 })).pipe(Effect.scoped);
+            release();
+            yield* Effect.yieldNow();
+            // After 99ms, store should still be alive (100ms unusedCacheTime used)
+            yield* TestClock.adjust(99);
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+            // After 1 more ms, store should be disposed
+            yield* TestClock.adjust(1);
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+        it.scoped('handles rapid retain/release cycles without errors', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Rapidly retain and release multiple times
+            for (let i = 0; i < 10; i++) {
+                const release = registry.retain(options);
+                release();
+            }
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // Store should be disposed after the last release
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+        it.scoped('cancels disposal when new retain', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            yield* Effect.yieldNow();
+            // Advance almost to disposal threshold
+            yield* TestClock.adjust(unusedCacheTime - 5);
+            // Add a new retain before disposal triggers
+            const release = registry.retain(options);
+            // Complete the original unusedCacheTime
+            yield* TestClock.adjust(5);
+            // Store should not have been disposed because retain keeps it alive
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+            // Release retain — new idle timer starts
+            release();
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // Now it should be disposed
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+        it.scoped('aborts loading when disposal fires while store is still loading', () => Effect.gen(function* () {
+            const unusedCacheTime = 10;
+            const loadDelay = 1000;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            // Adapter that takes time to load (controlled by TestClock)
+            const baseAdapter = makeInMemoryAdapter();
+            const options = testStoreOptions({
+                adapter: ((args) => Effect.gen(function* () {
+                    yield* Effect.sleep(loadDelay);
+                    return yield* baseAdapter(args);
+                })),
+            });
+            // Retain triggers loading (won't complete until clock advances past loadDelay)
+            const release = registry.retain(options);
+            yield* Effect.yieldNow();
+            // Release immediately — schedules disposal after unusedCacheTime
+            release();
+            yield* Effect.yieldNow();
+            // Advance past unusedCacheTime but NOT past loadDelay → disposal fires, interrupts loading
+            yield* TestClock.adjust(unusedCacheTime);
+            // Start a fresh load — since the first was aborted, this should be a new entry
+            const freshLoadFiber = yield* Effect.fork(registry.getOrLoad(options).pipe(Effect.scoped));
+            yield* Effect.yieldNow();
+            // Advance enough for the fresh load to complete
+            yield* TestClock.adjust(loadDelay);
+            const store = yield* Fiber.join(freshLoadFiber);
+            expect(store).toBeDefined();
+        }));
+        it.scoped('retain keeps store alive past unusedCacheTime', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            // Load the store
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Retain the store before disposal could fire
+            const release = registry.retain(options);
+            yield* Effect.yieldNow();
+            // Advance past unusedCacheTime — idle timer fires but refCount > 0, so no eviction
+            yield* TestClock.adjust(unusedCacheTime + 50);
+            // Store should still be cached because retain keeps it alive
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+            release();
+        }));
+        it.scoped('manages multiple stores with different IDs independently', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options1 = testStoreOptions({ storeId: 'store-1' });
+            const options2 = testStoreOptions({ storeId: 'store-2' });
+            const store1 = yield* registry.getOrLoad(options1).pipe(Effect.scoped);
+            const store2 = yield* registry.getOrLoad(options2).pipe(Effect.scoped);
+            // Should be different store instances
+            expect(store1).not.toBe(store2);
+            // Both should be cached independently
+            const cached1 = yield* registry.getOrLoad(options1).pipe(Effect.scoped);
+            const cached2 = yield* registry.getOrLoad(options2).pipe(Effect.scoped);
+            expect(cached1).toBe(store1);
+            expect(cached2).toBe(store2);
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // Both stores should be disposed
+            const newStore1 = yield* registry.getOrLoad(options1).pipe(Effect.scoped);
+            const newStore2 = yield* registry.getOrLoad(options2).pipe(Effect.scoped);
+            expect(newStore1).not.toBe(store1);
+            expect(newStore2).not.toBe(store2);
+        }));
+        it.scoped('applies default options from constructor', () => Effect.gen(function* () {
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime: 100 } });
+            const options = testStoreOptions();
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Verify the store loads successfully
+            expect(store).toBeDefined();
+            expect(store[StoreInternalsSymbol].clientSession.debugInstanceId).toBeDefined();
+            yield* Effect.yieldNow();
+            // After 50ms, store should still be cached (default is 100ms)
+            yield* TestClock.adjust(50);
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+        }));
+        it.scoped('does not serve a disposed store from cache', () => Effect.gen(function* () {
+            const unusedCacheTime = 25;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            const originalStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Verify store is cached
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(originalStore);
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // After disposal, calling getOrLoad should produce a fresh store
+            const freshStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(freshStore).not.toBe(originalStore);
+        }));
+        it.scoped('schedules disposal after preload if no retainers are added', () => Effect.gen(function* () {
+            const unusedCacheTime = 50;
+            const runtime = yield* Effect.runtime();
+            const registry = new StoreRegistry({ runtime, defaultOptions: { unusedCacheTime } });
+            const options = testStoreOptions();
+            // Preload without retaining (load + immediate release)
+            const store = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            // Verify it's cached
+            const cached = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(cached).toBe(store);
+            yield* Effect.yieldNow();
+            yield* TestClock.adjust(unusedCacheTime);
+            // Store should be disposed since no retainers were added
+            const nextStore = yield* registry.getOrLoad(options).pipe(Effect.scoped);
+            expect(nextStore).not.toBe(store);
+        }));
+    });
+});
+const testStoreOptions = (overrides = {}) => storeOptions({
+    storeId: 'test-store',
+    schema,
+    adapter: makeInMemoryAdapter(),
+    ...overrides,
+});
+//# sourceMappingURL=StoreRegistry.test.js.map