@fluojs/cache-manager 1.0.4 → 2.0.0

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQhE,OAAO,KAAK,EAAE,kBAAkB,EAAuD,MAAM,YAAY,CAAC;AAqL1G;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU;CAU7D"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAShE,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AAkLpB;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU;IAc5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU;CAwBlE"}

package/dist/module.js

@@ -1,10 +1,11 @@
 import { defineModule } from '@fluojs/runtime';
 import { RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
 import { CacheInterceptor } from './interceptor.js';
+import { CacheService } from './service.js';
 import { MemoryStore } from './stores/memory-store.js';
 import { RedisStore } from './stores/redis-store.js';
-import { CacheService } from './service.js';
 import { CACHE_OPTIONS, CACHE_STORE } from './tokens.js';
+import { normalizeCacheTtlJitterOptions } from './ttl-jitter.js';
 const DEFAULT_MEMORY_STORE_TTL_SECONDS = 300;
 const REDIS_PEER_MODULE_SPECIFIER = '@fluojs/redis';
 const loadOptionalModule = async specifier => import(specifier);
@@ -46,8 +47,10 @@ function normalizeCacheModuleOptions(options = {}) {
     redis: options.redis,
     store,
     ttl: options.ttl ?? (store === 'memory' ? DEFAULT_MEMORY_STORE_TTL_SECONDS : 0),
+    ttlJitter: normalizeCacheTtlJitterOptions(options.ttlJitter),
     httpKeyStrategy: options.httpKeyStrategy ?? 'route',
-    principalScopeResolver: options.principalScopeResolver
+    principalScopeResolver: options.principalScopeResolver,
+    observer: options.observer
   };
 }
 function isNormalizedCacheModuleOptions(value) {
@@ -99,12 +102,8 @@ async function createStore(options, container) {
   }
   return new MemoryStore();
 }
-function createCacheModuleProviders(options = {}) {
-  const normalized = normalizeCacheModuleOptions(options);
-  return [{
-    provide: CACHE_OPTIONS,
-    useValue: normalized
-  }, {
+function createCacheRuntimeProviders(optionsProvider) {
+  return [optionsProvider, {
     inject: [CACHE_OPTIONS, RUNTIME_CONTAINER],
     provide: CACHE_STORE,
     useFactory: (...deps) => {
@@ -160,7 +159,54 @@ export class CacheModule {
     return defineModule(CacheRootModule, {
       exports: [CacheService, CacheInterceptor],
       global: normalized.global,
-      providers: createCacheModuleProviders(options)
+      providers: createCacheRuntimeProviders({
+        provide: CACHE_OPTIONS,
+        useValue: normalized
+      })
+    });
+  }
+
+  /**
+   * Register cache providers from an injected async factory.
+   *
+   * @remarks
+   * The factory runs once per module registration through the application container,
+   * and its resolved options are normalized with the same defaults as
+   * {@link CacheModule.forRoot}. Module visibility comes from the `global` option on this
+   * call because module metadata is fixed before the factory runs; a `global` value in the
+   * factory result is ignored. A rejected factory fails bootstrap.
+   *
+   * @param options Injected factory registration options.
+   * @returns A runtime module exporting `CacheService` and `CacheInterceptor`.
+   *
+   * @example
+   * ```ts
+   * CacheModule.forRootAsync({
+   *   inject: [ConfigService],
+   *   useFactory: (config) => ({
+   *     store: 'redis',
+   *     ttl: config.cacheTtlSeconds,
+   *   }),
+   * });
+   * ```
+   */
+  static forRootAsync(options) {
+    class CacheRootAsyncModule extends CacheModule {}
+    return defineModule(CacheRootAsyncModule, {
+      exports: [CacheService, CacheInterceptor],
+      global: options.global ?? false,
+      providers: createCacheRuntimeProviders({
+        inject: options.inject,
+        provide: CACHE_OPTIONS,
+        scope: 'singleton',
+        useFactory: (...deps) => {
+          const factoryOptions = Reflect.apply(options.useFactory, options, deps);
+          return Promise.resolve(factoryOptions).then(resolved => normalizeCacheModuleOptions({
+            ...resolved,
+            global: options.global ?? false
+          }));
+        }
+      })
     });
   }
 }

package/dist/operation-observer.d.ts

@@ -0,0 +1,16 @@
+import type { CacheObserver } from './types.js';
+interface MonotonicClock {
+    now(): number;
+}
+/**
+ * Internal operation wrapper that times cache work and contains observer failures.
+ */
+export declare class CacheOperationObserver {
+    private readonly observer;
+    private readonly clock;
+    constructor(observer: CacheObserver | undefined, clock: MonotonicClock);
+    observeRead<T>(operation: 'get' | 'remember', run: () => Promise<T>, classify: (value: T) => 'hit' | 'miss'): Promise<T>;
+    observeWrite<T>(operation: 'set' | 'del' | 'reset' | 'close', run: () => Promise<T>): Promise<T>;
+}
+export {};
+//# sourceMappingURL=operation-observer.d.ts.map

package/dist/operation-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-observer.d.ts","sourceRoot":"","sources":["../src/operation-observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,YAAY,CAAC;AAElE,UAAU,cAAc;IACtB,GAAG,IAAI,MAAM,CAAC;CACf;AAUD;;GAEG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,KAAK,EAAE,cAAc;IAGlC,WAAW,CAAC,CAAC,EACjB,SAAS,EAAE,KAAK,GAAG,UAAU,EAC7B,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,KAAK,GAAG,MAAM,GACrC,OAAO,CAAC,CAAC,CAAC;IAyBP,YAAY,CAAC,CAAC,EAClB,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,EAC5C,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC;CAwBd"}

package/dist/operation-observer.js

@@ -0,0 +1,61 @@
+function reportObservation(observer, observation) {
+  try {
+    void Promise.resolve(observer.onCacheOperation(observation)).catch(() => undefined);
+  } catch {
+    return;
+  }
+}
+
+/**
+ * Internal operation wrapper that times cache work and contains observer failures.
+ */
+export class CacheOperationObserver {
+  constructor(observer, clock) {
+    this.observer = observer;
+    this.clock = clock;
+  }
+  async observeRead(operation, run, classify) {
+    if (!this.observer) {
+      return run();
+    }
+    const startedAt = this.clock.now();
+    try {
+      const value = await run();
+      reportObservation(this.observer, {
+        durationMs: this.clock.now() - startedAt,
+        operation,
+        outcome: classify(value)
+      });
+      return value;
+    } catch (error) {
+      reportObservation(this.observer, {
+        durationMs: this.clock.now() - startedAt,
+        operation,
+        outcome: 'error'
+      });
+      throw error;
+    }
+  }
+  async observeWrite(operation, run) {
+    if (!this.observer) {
+      return run();
+    }
+    const startedAt = this.clock.now();
+    try {
+      const value = await run();
+      reportObservation(this.observer, {
+        durationMs: this.clock.now() - startedAt,
+        operation,
+        outcome: 'success'
+      });
+      return value;
+    } catch (error) {
+      reportObservation(this.observer, {
+        durationMs: this.clock.now() - startedAt,
+        operation,
+        outcome: 'error'
+      });
+      throw error;
+    }
+  }
+}

package/dist/service.d.ts

@@ -1,4 +1,7 @@
 import type { CacheStore, NormalizedCacheModuleOptions } from './types.js';
+interface MonotonicClock {
+    now(): number;
+}
 /**
  * Application-level cache facade used for direct cache reads, writes, and read-through loading.
  */
@@ -10,10 +13,13 @@ export declare class CacheService {
     private readonly pendingInvalidations;
     private readonly invalidatedInflight;
     private closed;
+    private closePromise;
     private resetVersion;
+    private readonly storeOperations;
     private beginPendingLoad;
     private endPendingLoad;
-    constructor(store: CacheStore, options: NormalizedCacheModuleOptions);
+    private readonly operationObserver;
+    constructor(store: CacheStore, options: NormalizedCacheModuleOptions, clock?: MonotonicClock);
     /**
      * Read a cached value by key.
      *
@@ -21,6 +27,7 @@ export declare class CacheService {
      * @returns The cached value, or `undefined` when the key is missing or expired.
      */
     get<T = unknown>(key: string): Promise<T | undefined>;
+    private readFromStore;
     /**
      * Store a value in the configured cache store.
      *
@@ -28,8 +35,14 @@ export declare class CacheService {
      * @param value Value to cache.
      * @param ttlSeconds Optional per-call TTL override in seconds.
      * @returns A promise that resolves after the write completes.
+     *
+     * @remarks
+     * When `ttlJitter` is configured, a positive resolved TTL is jittered once here, before store handoff,
+     * so every store observes the same effective expiry. `ttl: 0` stays a no-expiry write and invalid TTL
+     * values still skip the write entirely.
      */
     set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    private writeToStore;
     /**
      * Load a value through the cache, de-duplicating concurrent misses for the same key.
      *
@@ -39,6 +52,7 @@ export declare class CacheService {
      * @returns The cached or freshly loaded value.
      */
     remember<T = unknown>(key: string, loader: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+    private rememberThroughStore;
     /**
      * Delete a single cache entry.
      *
@@ -46,18 +60,24 @@ export declare class CacheService {
      * @returns A promise that resolves after the entry is removed.
      */
     del(key: string): Promise<void>;
+    private invalidateKey;
     /**
      * Clear every cache entry owned by the configured store.
      *
      * @returns A promise that resolves after the store reset completes.
      */
     reset(): Promise<void>;
+    private resetStore;
     /**
      * Close the configured store when it exposes an optional teardown hook.
      *
+     * Concurrent and repeated calls share the first teardown completion and failure.
+     *
      * @returns A promise that resolves after store teardown completes.
      */
     close(): Promise<void>;
+    private closeStore;
+    private deleteFromStore;
     /**
      * Runtime shutdown hook that releases resource-owning stores during application close.
      *
@@ -65,4 +85,5 @@ export declare class CacheService {
      */
     onModuleDestroy(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAQ3E;;GAEG;AACH,qBACa,YAAY;IAqCrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IArC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0C;IACvE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,cAAc;gBAsBH,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,4BAA4B;IAGxD;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAIrD;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUjF;;;;;;;OAOG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;IAsDb;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAS3E,UAAU,cAAc;IACtB,GAAG,IAAI,MAAM,CAAC;CACf;AAID;;GAEG;AACH,qBACa,YAAY;IAyCrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAzC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0C;IACvE,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAClE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiC;IAEjE,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,cAAc;IAqBtB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;gBAGxC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,4BAA4B,EACtD,KAAK,GAAE,cAAiC;IAK1C;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAQrD,OAAO,CAAC,aAAa;IAcrB;;;;;;;;;;;;OAYG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAInE,YAAY;IAkB1B;;;;;;;OAOG;IACG,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC;YAUC,oBAAoB;IAsElC;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAIvB,aAAa;IAkB3B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAId,UAAU;IAmBxB;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,OAAO,CAAC,UAAU;YAoBJ,eAAe;IAU7B;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC"}

package/dist/service.js

@@ -5,11 +5,19 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Inject } from '@fluojs/core';
+import { CacheOperationObserver } from './operation-observer.js';
+import { StoreOperationScheduler } from './store-operation-scheduler.js';
 import { CACHE_OPTIONS, CACHE_STORE } from './tokens.js';
-let _CacheService;
+import { applyCacheTtlJitter } from './ttl-jitter.js';
+
+// allow: SIZE_OK — cache lifecycle and in-flight invalidation form one indivisible state machine.
+
+const systemCacheClock = globalThis.performance;
+
 /**
  * Application-level cache facade used for direct cache reads, writes, and read-through loading.
  */
+let _CacheService;
 class CacheService {
   static {
     [_CacheService, _initClass] = _applyDecs(this, [Inject(CACHE_STORE, CACHE_OPTIONS)], []).c;
@@ -19,7 +27,9 @@ class CacheService {
   pendingInvalidations = new Map();
   invalidatedInflight = new Set();
   closed = false;
+  closePromise;
   resetVersion = 0;
+  storeOperations = new StoreOperationScheduler();
   beginPendingLoad(key, generation) {
     const generations = this.pendingLoads.get(key) ?? new Map();
     generations.set(generation, (generations.get(generation) ?? 0) + 1);
@@ -40,9 +50,11 @@ class CacheService {
       this.pendingLoads.delete(key);
     }
   }
-  constructor(store, options) {
+  operationObserver;
+  constructor(store, options, clock = systemCacheClock) {
     this.store = store;
     this.options = options;
+    this.operationObserver = new CacheOperationObserver(options.observer, clock);
   }
 
   /**
@@ -52,7 +64,18 @@ class CacheService {
    * @returns The cached value, or `undefined` when the key is missing or expired.
    */
   get(key) {
-    return Promise.resolve(this.store.get(key));
+    return this.operationObserver.observeRead('get', () => this.readFromStore(key), value => value === undefined ? 'miss' : 'hit');
+  }
+  readFromStore(key) {
+    if (this.closed) {
+      return Promise.resolve(undefined);
+    }
+    return this.storeOperations.run(() => {
+      if (this.closed) {
+        return undefined;
+      }
+      return this.store.get(key);
+    });
   }
 
   /**
@@ -62,13 +85,27 @@ class CacheService {
    * @param value Value to cache.
    * @param ttlSeconds Optional per-call TTL override in seconds.
    * @returns A promise that resolves after the write completes.
+   *
+   * @remarks
+   * When `ttlJitter` is configured, a positive resolved TTL is jittered once here, before store handoff,
+   * so every store observes the same effective expiry. `ttl: 0` stays a no-expiry write and invalid TTL
+   * values still skip the write entirely.
    */
   async set(key, value, ttlSeconds) {
+    await this.operationObserver.observeWrite('set', () => this.writeToStore(key, value, ttlSeconds));
+  }
+  async writeToStore(key, value, ttlSeconds) {
     const resolvedTtl = ttlSeconds ?? this.options.ttl;
-    if (!Number.isFinite(resolvedTtl) || resolvedTtl < 0) {
+    if (this.closed || !Number.isFinite(resolvedTtl) || resolvedTtl < 0) {
       return;
     }
-    await this.store.set(key, value, resolvedTtl);
+    const effectiveTtl = applyCacheTtlJitter(resolvedTtl, this.options.ttlJitter);
+    await this.storeOperations.run(async () => {
+      if (this.closed) {
+        return;
+      }
+      await this.store.set(key, value, effectiveTtl);
+    });
   }
 
   /**
@@ -80,16 +117,29 @@ class CacheService {
    * @returns The cached or freshly loaded value.
    */
   async remember(key, loader, ttlSeconds) {
+    const [value] = await this.operationObserver.observeRead('remember', () => this.rememberThroughStore(key, loader, ttlSeconds), ([, outcome]) => outcome);
+    return value;
+  }
+  async rememberThroughStore(key, loader, ttlSeconds) {
+    if (this.closed) {
+      return [await loader(), 'miss'];
+    }
     const resetVersion = this.resetVersion;
     this.beginPendingLoad(key, resetVersion);
     try {
-      const cached = await this.get(key);
+      const cached = await this.readFromStore(key);
       if (cached !== undefined) {
-        return cached;
+        return [cached, 'hit'];
+      }
+      if (this.closed || this.resetVersion !== resetVersion) {
+        return [await loader(), 'miss'];
       }
       const existing = this.inflight.get(key);
+      if (existing && existing.generation === resetVersion) {
+        return [await existing.promise, 'miss'];
+      }
       if (existing) {
-        return existing.promise;
+        this.inflight.delete(key);
       }
       const entry = {
         generation: resetVersion,
@@ -97,12 +147,12 @@ class CacheService {
         promise: Promise.resolve(undefined)
       };
       const promise = loader().then(async value => {
-        if (entry.invalidated || this.resetVersion !== resetVersion) {
+        if (this.closed || entry.invalidated || this.resetVersion !== resetVersion) {
           return value;
         }
-        await this.set(key, value, ttlSeconds);
-        if (entry.invalidated || this.resetVersion !== resetVersion) {
-          await this.store.del(key);
+        await this.writeToStore(key, value, ttlSeconds);
+        if (!this.closed && (entry.invalidated || this.resetVersion !== resetVersion)) {
+          await this.deleteFromStore(key);
         }
         return value;
       }).finally(() => {
@@ -116,7 +166,7 @@ class CacheService {
       });
       entry.promise = promise;
       this.inflight.set(key, entry);
-      return promise;
+      return [await promise, 'miss'];
     } finally {
       this.endPendingLoad(key, resetVersion);
     }
@@ -129,6 +179,12 @@ class CacheService {
    * @returns A promise that resolves after the entry is removed.
    */
   async del(key) {
+    await this.operationObserver.observeWrite('del', () => this.invalidateKey(key));
+  }
+  async invalidateKey(key) {
+    if (this.closed) {
+      return;
+    }
     const entry = this.inflight.get(key);
     if (entry) {
       entry.invalidated = true;
@@ -137,7 +193,7 @@ class CacheService {
       this.pendingInvalidations.set(key, this.resetVersion);
       this.invalidatedInflight.add(key);
     }
-    await this.store.del(key);
+    await this.deleteFromStore(key);
   }
 
   /**
@@ -146,35 +202,63 @@ class CacheService {
    * @returns A promise that resolves after the store reset completes.
    */
   async reset() {
+    await this.operationObserver.observeWrite('reset', () => this.resetStore());
+  }
+  async resetStore() {
+    if (this.closed) {
+      return;
+    }
     this.resetVersion += 1;
     this.inflight.clear();
     this.pendingLoads.clear();
     this.pendingInvalidations.clear();
     this.invalidatedInflight.clear();
-    await this.store.reset();
+    await this.storeOperations.runExclusive(async () => {
+      if (this.closed) {
+        return;
+      }
+      await this.store.reset();
+    });
   }
 
   /**
    * Close the configured store when it exposes an optional teardown hook.
    *
+   * Concurrent and repeated calls share the first teardown completion and failure.
+   *
    * @returns A promise that resolves after store teardown completes.
    */
-  async close() {
-    if (this.closed) {
-      return;
+  close() {
+    if (this.closePromise) {
+      return this.closePromise;
     }
+    this.closePromise = this.operationObserver.observeWrite('close', () => this.closeStore());
+    return this.closePromise;
+  }
+  closeStore() {
     this.closed = true;
+    this.resetVersion += 1;
     this.inflight.clear();
     this.pendingLoads.clear();
     this.pendingInvalidations.clear();
     this.invalidatedInflight.clear();
-    if (this.store.close) {
-      await this.store.close();
-      return;
-    }
-    if (this.store.dispose) {
-      await this.store.dispose();
-    }
+    return this.storeOperations.runExclusive(async () => {
+      if (this.store.close) {
+        await this.store.close();
+        return;
+      }
+      if (this.store.dispose) {
+        await this.store.dispose();
+      }
+    });
+  }
+  async deleteFromStore(key) {
+    await this.storeOperations.run(async () => {
+      if (this.closed) {
+        return;
+      }
+      await this.store.del(key);
+    });
   }
 
   /**

package/dist/status.js

@@ -18,7 +18,7 @@ function resolveStoreOwnershipMode(input) {
   if (input.storeOwnershipMode) {
     return input.storeOwnershipMode;
   }
-  return input.storeKind === 'memory' ? 'framework' : 'external';
+  return input.storeKind === 'redis' ? 'external' : 'framework';
 }
 function isBackingStoreReady(input) {
   if (input.backingStoreReady !== undefined) {

package/dist/store-operation-scheduler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ordering policy for cache store operations.
+ *
+ * Ordinary operations run concurrently with each other, so a slow operation for one key
+ * cannot block unrelated keys. Exclusive operations, such as reset and store teardown,
+ * close admission for later operations, drain already-started operations, and then run alone.
+ */
+export declare class StoreOperationScheduler {
+    private exclusiveTail;
+    private readonly activeOperations;
+    /**
+     * Run an ordinary store operation once any pending exclusive operation has completed.
+     *
+     * @param operation Store operation to run concurrently with other ordinary operations.
+     * @returns The operation result, including its rejection.
+     */
+    run<T>(operation: () => Promise<T> | T): Promise<T>;
+    /**
+     * Run a store operation exclusively after every already-started operation has settled.
+     *
+     * Operations submitted after this call wait for the exclusive operation to complete.
+     *
+     * @param operation Store operation that requires exclusive store access.
+     * @returns The operation result, including its rejection.
+     */
+    runExclusive(operation: () => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=store-operation-scheduler.d.ts.map

package/dist/store-operation-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-operation-scheduler.d.ts","sourceRoot":"","sources":["../src/store-operation-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4B;IAE7D;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBnD;;;;;;;OAOG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAgB5D"}

package/dist/store-operation-scheduler.js

@@ -0,0 +1,49 @@
+/**
+ * Ordering policy for cache store operations.
+ *
+ * Ordinary operations run concurrently with each other, so a slow operation for one key
+ * cannot block unrelated keys. Exclusive operations, such as reset and store teardown,
+ * close admission for later operations, drain already-started operations, and then run alone.
+ */
+export class StoreOperationScheduler {
+  exclusiveTail = Promise.resolve();
+  activeOperations = new Set();
+
+  /**
+   * Run an ordinary store operation once any pending exclusive operation has completed.
+   *
+   * @param operation Store operation to run concurrently with other ordinary operations.
+   * @returns The operation result, including its rejection.
+   */
+  run(operation) {
+    const start = () => {
+      const result = Promise.resolve(operation());
+      const settled = result.then(() => undefined, () => undefined);
+      this.activeOperations.add(settled);
+      void settled.then(() => {
+        this.activeOperations.delete(settled);
+      });
+      return result;
+    };
+    return this.exclusiveTail.then(start, start);
+  }
+
+  /**
+   * Run a store operation exclusively after every already-started operation has settled.
+   *
+   * Operations submitted after this call wait for the exclusive operation to complete.
+   *
+   * @param operation Store operation that requires exclusive store access.
+   * @returns The operation result, including its rejection.
+   */
+  runExclusive(operation) {
+    const result = this.exclusiveTail.then(async () => {
+      while (this.activeOperations.size > 0) {
+        await Promise.all(this.activeOperations);
+      }
+      await operation();
+    });
+    this.exclusiveTail = result.then(() => undefined, () => undefined);
+    return result;
+  }
+}

package/dist/stores/memory-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/stores/memory-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAyC9C;;GAEG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,WAAW,CAAK;IAElB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAsBrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}
+{"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/stores/memory-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4C9C;;GAEG;AACH,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,WAAW,CAAK;IAElB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAsBrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/stores/memory-store.js

@@ -23,6 +23,9 @@ function enforceEntryLimit(entries) {
     entries.delete(oldestKey);
   }
 }
+function normalizePositiveTtlMilliseconds(ttlSeconds, maximumTtlMilliseconds) {
+  return Math.min(maximumTtlMilliseconds, Math.max(1, Math.floor(ttlSeconds * 1000)));
+}
 
 /**
  * Represents the memory store.
@@ -55,7 +58,8 @@ export class MemoryStore {
       value: cloneCacheValue(value)
     };
     if (ttlSeconds > 0) {
-      const ttlMilliseconds = Math.max(1, Math.floor(ttlSeconds * 1000));
+      const maximumTtlMilliseconds = Number.MAX_SAFE_INTEGER - now;
+      const ttlMilliseconds = normalizePositiveTtlMilliseconds(ttlSeconds, maximumTtlMilliseconds);
       entry.expiresAt = now + ttlMilliseconds;
     }
     this.entries.delete(key);

package/dist/stores/redis-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../../src/stores/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgDD;;GAEG;AACH,qBAAa,UAAW,YAAW,UAAU;IAMzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,MAAM,EAAE,qBAAqB,EAC9C,OAAO,GAAE,iBAAsB;IAMjC,OAAO,CAAC,UAAU;IAIZ,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAqBrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5E,OAAO,CAAC,aAAa;IAMf,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAoC7B"}
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../../src/stores/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoDD;;GAEG;AACH,qBAAa,UAAW,YAAW,UAAU;IAMzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,MAAM,EAAE,qBAAqB,EAC9C,OAAO,GAAE,iBAAsB;IAMjC,OAAO,CAAC,UAAU;IAIZ,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAqBrD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB5E,OAAO,CAAC,aAAa;IAMf,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAoC7B"}