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

package/dist/store/StoreRegistry.js

@@ -0,0 +1,244 @@
+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;
+    /**
+     * In-flight loading promises keyed by storeId.
+     * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
+     */
+    #loadingPromises = new Map();
+    /**
+     * Default options merged into all store configurations at load time.
+     */
+    #defaultOptions;
+    /**
+     * Creates a new StoreRegistry instance.
+     *
+     * @example
+     * ```ts
+     * const registry = new StoreRegistry({
+     *   defaultOptions: {
+     *     batchUpdates,
+     *     unusedCacheTime: 30_000,
+     *   }
+     * })
+     * ```
+     */
+    constructor(config = {}) {
+        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 }) => {
+                // 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 = (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))
+            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;
+            // 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;
+        }
+        // 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 = (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
+        }
+    };
+}
+/**
+ * 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(options) {
+    return 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,380 @@
+import { makeInMemoryAdapter } from '@livestore/adapter-web';
+import { UnknownError } from '@livestore/common';
+import { sleep } from '@livestore/utils';
+import { Effect } from '@livestore/utils/effect';
+import { describe, expect, it } from 'vitest';
+import { schema } from "../utils/tests/fixture.js";
+import { StoreRegistry, storeOptions } from "./StoreRegistry.js";
+import { StoreInternalsSymbol } from "./store-types.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('disposes store after unusedCacheTime expires', async () => {
+        const unusedCacheTime = 25;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Store should be cached
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        // Wait for disposal
+        await sleep(unusedCacheTime + 50);
+        // After disposal, store should be removed
+        // The store is removed from cache, so next getOrLoadStore creates a new one
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        // Should be a different store instance
+        expect(nextStore).not.toBe(store);
+        expect(nextStore[StoreInternalsSymbol].clientSession.debugInstanceId).toBeDefined();
+        // Clean up the second store (first one was disposed)
+        await nextStore.shutdownPromise();
+    });
+    it('does not dispose when unusedCacheTime is Infinity', async () => {
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime: Number.POSITIVE_INFINITY } });
+        const options = testStoreOptions();
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Store should be cached
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        // Wait a reasonable duration to verify no disposal
+        await sleep(100);
+        // Store should still be cached (not disposed)
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        // Clean up manually
+        await store.shutdownPromise();
+    });
+    it('schedules disposal if store becomes unused during loading', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        // Start loading without any retain
+        const storePromise = storeRegistry.getOrLoadPromise(options);
+        // Wait for store to load (no retain registered)
+        const store = await storePromise;
+        // Since there were no retain when loading completed, disposal should be scheduled
+        await sleep(unusedCacheTime + 50);
+        // Store should be disposed
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        await nextStore.shutdownPromise();
+    });
+    // This test is skipped because Effect doesn't yet support different `idleTimeToLive` values for each resource in `RcMap`
+    // See https://github.com/livestorejs/livestore/issues/917
+    it.skip('allows call-site options to override default options', async () => {
+        const storeRegistry = new StoreRegistry({
+            defaultOptions: {
+                unusedCacheTime: 1000, // Default is long
+            },
+        });
+        const options = testStoreOptions({
+            unusedCacheTime: 10, // Override with shorter time
+        });
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Wait for the override time (10ms)
+        await sleep(10);
+        // Should be disposed according to the override time, not default
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        await nextStore.shutdownPromise();
+    });
+    // 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.skip('keeps the longest unusedCacheTime seen for a store when options vary across calls', async () => {
+        const storeRegistry = new StoreRegistry();
+        const options = testStoreOptions({ unusedCacheTime: 10 });
+        const release = storeRegistry.retain(options);
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Call with longer unusedCacheTime
+        await storeRegistry.getOrLoadPromise(testStoreOptions({ unusedCacheTime: 100 }));
+        release();
+        // After 99ms, store should still be alive (100ms unusedCacheTime used)
+        await sleep(99);
+        // Store should still be cached
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        // After the full 100ms, store should be disposed
+        await sleep(1);
+        // Next getOrLoadStore should create a new store
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        // Clean up the second store (first one was disposed)
+        await nextStore.shutdownPromise();
+    });
+    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('handles rapid retain/release cycles without errors', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Rapidly retain and release multiple times
+        for (let i = 0; i < 10; i++) {
+            const release = storeRegistry.retain(options);
+            release();
+        }
+        // Wait for disposal to trigger
+        await sleep(unusedCacheTime + 50);
+        // Store should be disposed after the last release
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        await nextStore.shutdownPromise();
+    });
+    it('cancels disposal when new retain', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Wait almost to disposal threshold
+        await sleep(unusedCacheTime - 5);
+        // Add a new retain before disposal triggers
+        const release = storeRegistry.retain(options);
+        // Complete the original unusedCacheTime
+        await sleep(5);
+        // Store should not have been disposed because we added a retain
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        // Clean up
+        release();
+        await sleep(unusedCacheTime + 50);
+        // Now it should be disposed
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        await nextStore.shutdownPromise();
+    });
+    it('aborts loading when disposal fires while store is still loading', async () => {
+        const unusedCacheTime = 10;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        // Retain briefly to trigger getOrLoadStore and then release
+        const release = storeRegistry.retain(options);
+        // Start loading
+        const loadPromise = storeRegistry.getOrLoadPromise(options);
+        // Attach a catch handler to prevent unhandled rejection when the load is aborted
+        const abortedPromise = loadPromise.catch(() => {
+            // Expected: load was aborted by disposal
+        });
+        // Release immediately, which schedules disposal
+        release();
+        // Wait for disposal to trigger
+        await sleep(unusedCacheTime + 50);
+        // Wait for the abort to complete
+        await abortedPromise;
+        // After abort, a new getOrLoadStore should start a fresh load
+        const freshLoadPromise = storeRegistry.getOrLoadPromise(options);
+        // This should be a new promise (not the aborted one)
+        expect(freshLoadPromise).toBeInstanceOf(Promise);
+        expect(freshLoadPromise).not.toBe(loadPromise);
+        // Wait for fresh load to complete
+        const store = await freshLoadPromise;
+        expect(store).toBeDefined();
+        await store.shutdownPromise();
+    });
+    it('retain keeps store alive past unusedCacheTime', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        // Load the store
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Retain the store before disposal could fire
+        const release = storeRegistry.retain(options);
+        // Wait past the unusedCacheTime
+        await sleep(unusedCacheTime + 50);
+        // Store should still be cached because retain keeps it alive
+        const cachedStore = storeRegistry.getOrLoadPromise(options);
+        expect(cachedStore).toBe(store);
+        release();
+        await store.shutdownPromise();
+    });
+    it('manages multiple stores with different IDs independently', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options1 = testStoreOptions({ storeId: 'store-1' });
+        const options2 = testStoreOptions({ storeId: 'store-2' });
+        const store1 = await storeRegistry.getOrLoadPromise(options1);
+        const store2 = await storeRegistry.getOrLoadPromise(options2);
+        // Should be different store instances
+        expect(store1).not.toBe(store2);
+        // Both should be cached independently
+        expect(storeRegistry.getOrLoadPromise(options1)).toBe(store1);
+        expect(storeRegistry.getOrLoadPromise(options2)).toBe(store2);
+        // Wait for both stores to be disposed
+        await sleep(unusedCacheTime + 50);
+        // Both stores should be disposed, so next getOrLoadStore creates new ones
+        const newStore1 = await storeRegistry.getOrLoadPromise(options1);
+        expect(newStore1).not.toBe(store1);
+        const newStore2 = await storeRegistry.getOrLoadPromise(options2);
+        expect(newStore2).not.toBe(store2);
+        // Clean up
+        await newStore1.shutdownPromise();
+        await newStore2.shutdownPromise();
+    });
+    it('applies default options from constructor', async () => {
+        const storeRegistry = new StoreRegistry({
+            defaultOptions: {
+                unusedCacheTime: 100,
+            },
+        });
+        const options = testStoreOptions();
+        const store = await storeRegistry.getOrLoadPromise(options);
+        // Verify the store loads successfully
+        expect(store).toBeDefined();
+        expect(store[StoreInternalsSymbol].clientSession.debugInstanceId).toBeDefined();
+        // Verify configured default unusedCacheTime is applied by checking disposal doesn't happen before it
+        await sleep(50);
+        // Store should still be cached after 50ms (default is 100ms)
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(store);
+        await store.shutdownPromise();
+    });
+    it('prevents getOrLoadStore from returning a dying store', async () => {
+        const unusedCacheTime = 25;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        // Load the store and wait for it to be ready
+        const originalStore = await storeRegistry.getOrLoadPromise(options);
+        // Verify store is cached
+        expect(storeRegistry.getOrLoadPromise(options)).toBe(originalStore);
+        // Wait for disposal to trigger
+        await sleep(unusedCacheTime + 50);
+        // After disposal, the cache should be cleared
+        // Calling getOrLoadStore should start a fresh load (return Promise)
+        const storeOrPromise = storeRegistry.getOrLoadPromise(options);
+        if (!(storeOrPromise instanceof Promise)) {
+            expect.fail('getOrLoadStore returned dying store synchronously instead of starting fresh load');
+        }
+        const freshStore = await storeOrPromise;
+        // A fresh load was triggered because cache was cleared
+        expect(freshStore).not.toBe(originalStore);
+        await freshStore.shutdownPromise();
+    });
+    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('schedules disposal after preload if no retainers are added', async () => {
+        const unusedCacheTime = 50;
+        const storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime } });
+        const options = testStoreOptions();
+        // Preload without retaining
+        await storeRegistry.preload(options);
+        // Get the store
+        const store = storeRegistry.getOrLoadPromise(options);
+        expect(store).not.toBeInstanceOf(Promise);
+        // Wait for disposal to trigger
+        await sleep(unusedCacheTime + 50);
+        // Store should be disposed since no retainers were added
+        const nextStore = await storeRegistry.getOrLoadPromise(options);
+        expect(nextStore).not.toBe(store);
+        await nextStore.shutdownPromise();
+    });
+});
+const testStoreOptions = (overrides = {}) => storeOptions({
+    storeId: 'test-store',
+    schema,
+    adapter: makeInMemoryAdapter(),
+    ...overrides,
+});
+//# sourceMappingURL=StoreRegistry.test.js.map