@fluojs/cache-manager 1.0.6 → 2.0.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,0CAA0C,EAC1C,wCAAwC,GACzC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,UAAU,EACV,4BAA4B,EAC5B,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,kCAAkC,EAClC,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EACV,kCAAkC,EAClC,8BAA8B,EAC9B,qBAAqB,EACrB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0CAA0C,EAC1C,wCAAwC,GACzC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,+BAA+B,EAC/B,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { CacheEvict, CacheKey, cacheRouteMetadataKey, CacheTTL, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
+export { CacheEvict, CacheKey, CacheTTL, cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
 export { CacheInterceptor } from './interceptor.js';
 export { CacheModule } from './module.js';
 export { CacheService } from './service.js';

package/dist/interceptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAe,MAAM,cAAc,CAAC;AAGxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAsE,4BAA4B,EAA0B,MAAM,YAAY,CAAC;AAsM3J;;GAEG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B;IAGlD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;YAanE,YAAY;YA2BZ,eAAe;YA2Bf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;YAkBV,OAAO;YAQP,OAAO;YAOP,OAAO;CAMtB"}
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAe,MAAM,cAAc,CAAC;AAIxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAsE,4BAA4B,EAA0B,MAAM,YAAY,CAAC;AA2I3J;;GAEG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,4BAA4B;IAGlD,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;YAanE,YAAY;YA2BZ,eAAe;YAoCf,gBAAgB;IAY9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;YAkBV,OAAO;YAQP,OAAO;YAOP,OAAO;CAMtB"}

package/dist/interceptor.js

@@ -5,16 +5,17 @@ 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 { getStandardMetadataBag } from '@fluojs/core/internal';
+import { getRequestPipelineMetadataBag } from '@fluojs/core/request-pipeline';
 import { SseResponse } from '@fluojs/http';
 import { cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.js';
+import { installDeferredEviction } from './deferred-eviction.js';
 import { CacheService } from './service.js';
 import { CACHE_OPTIONS } from './tokens.js';
 function isMetadataBag(value) {
   return typeof value === 'object' && value !== null;
 }
 function getMethodMetadataBag(controllerToken, methodName) {
-  const classBag = getStandardMetadataBag(controllerToken);
+  const classBag = getRequestPipelineMetadataBag(controllerToken);
   if (!isMetadataBag(classBag)) {
     return undefined;
   }
@@ -85,7 +86,7 @@ function isSuccessStatusCode(statusCode) {
   return statusCode >= 200 && statusCode < 300;
 }
 async function resolveCacheKeyValue(metadata, context, strategy, resolver) {
-  if (!metadata) {
+  if (metadata === undefined) {
     return defaultCacheKey(context, strategy, resolver);
   }
   if (typeof metadata === 'string') {
@@ -93,51 +94,6 @@ async function resolveCacheKeyValue(metadata, context, strategy, resolver) {
   }
   return metadata(context);
 }
-const EVICTION_FALLBACK_TIMEOUT_MS = 5_000;
-function installDeferredEviction(response, evict) {
-  const originalSend = response.send.bind(response);
-  let restored = false;
-  let completed = false;
-  let sendInvoked = false;
-  const runEviction = () => {
-    if (completed) {
-      return;
-    }
-    completed = true;
-    void evict().catch(() => {});
-  };
-  const restore = () => {
-    if (restored) {
-      return;
-    }
-    clearTimeout(fallbackTimer);
-    response.send = originalSend;
-    restored = true;
-  };
-  const fallbackTimer = setTimeout(() => {
-    // Run fallback eviction only when no response commit path was invoked.
-    // If response.send(...) is still pending or already completed, the send
-    // path owns eviction (on success) or cancellation (on failure), so the
-    // fallback timer must not evict under a pending send.
-    if (!sendInvoked) {
-      runEviction();
-    }
-    restore();
-  }, EVICTION_FALLBACK_TIMEOUT_MS);
-  response.send = async body => {
-    sendInvoked = true;
-    try {
-      await originalSend(body);
-      runEviction();
-    } catch (error) {
-      completed = true;
-      throw error;
-    } finally {
-      restore();
-    }
-  };
-  return restore;
-}
 
 /**
  * Caches GET responses and evicts related entries after successful write operations.
@@ -190,10 +146,14 @@ class CacheInterceptor {
       }));
     };
     if (context.requestContext.response.committed) {
+      const request = context.requestContext.request;
+      if (request.signal?.aborted === true || request.isAborted?.() === true) {
+        return;
+      }
       await runEviction();
       return;
     }
-    installDeferredEviction(context.requestContext.response, runEviction);
+    installDeferredEviction(context.requestContext.response, context.requestContext.request, runEviction);
   }
   async resolveEvictKeys(metadata, context, value) {
     if (typeof metadata === 'function') {

package/dist/module.d.ts

@@ -1,5 +1,5 @@
 import { type ModuleType } from '@fluojs/runtime';
-import type { CacheModuleOptions } from './types.js';
+import type { CacheAsyncModuleOptions, CacheModuleOptions } from './types.js';
 /**
  * Runtime module entrypoint for cache-manager services and interceptor wiring.
  *
@@ -28,5 +28,30 @@ export declare class CacheModule {
      * ```
      */
     static forRoot(options?: CacheModuleOptions): ModuleType;
+    /**
+     * 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: CacheAsyncModuleOptions): ModuleType;
 }
 //# sourceMappingURL=module.d.ts.map

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,12 +13,13 @@ export declare class CacheService {
     private readonly pendingInvalidations;
     private readonly invalidatedInflight;
     private closed;
+    private closePromise;
     private resetVersion;
-    private storeOperationTail;
-    private runStoreOperation;
+    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.
      *
@@ -23,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.
      *
@@ -30,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.
      *
@@ -41,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.
      *
@@ -48,18 +60,23 @@ 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.
@@ -68,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;IAiDrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjD1B,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;IACzB,OAAO,CAAC,kBAAkB,CAAoC;YAEhD,iBAAiB;IAW/B,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;IAcrD;;;;;;;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;IAgBjF;;;;;;;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;IAkEb;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBrC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAwBd,eAAe;IAU7B;;;;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,13 +27,9 @@ class CacheService {
   pendingInvalidations = new Map();
   invalidatedInflight = new Set();
   closed = false;
+  closePromise;
   resetVersion = 0;
-  storeOperationTail = Promise.resolve();
-  async runStoreOperation(operation) {
-    const result = this.storeOperationTail.then(operation, operation);
-    this.storeOperationTail = result.then(() => undefined, () => undefined);
-    return result;
-  }
+  storeOperations = new StoreOperationScheduler();
   beginPendingLoad(key, generation) {
     const generations = this.pendingLoads.get(key) ?? new Map();
     generations.set(generation, (generations.get(generation) ?? 0) + 1);
@@ -46,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);
   }
 
   /**
@@ -58,10 +64,13 @@ class CacheService {
    * @returns The cached value, or `undefined` when the key is missing or expired.
    */
   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.runStoreOperation(() => {
+    return this.storeOperations.run(() => {
       if (this.closed) {
         return undefined;
       }
@@ -76,17 +85,26 @@ 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 (this.closed || !Number.isFinite(resolvedTtl) || resolvedTtl < 0) {
       return;
     }
-    await this.runStoreOperation(async () => {
+    const effectiveTtl = applyCacheTtlJitter(resolvedTtl, this.options.ttlJitter);
+    await this.storeOperations.run(async () => {
       if (this.closed) {
         return;
       }
-      await this.store.set(key, value, resolvedTtl);
+      await this.store.set(key, value, effectiveTtl);
     });
   }
 
@@ -99,22 +117,26 @@ 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 loader();
+      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 loader();
+        return [await loader(), 'miss'];
       }
       const existing = this.inflight.get(key);
       if (existing && existing.generation === resetVersion) {
-        return existing.promise;
+        return [await existing.promise, 'miss'];
       }
       if (existing) {
         this.inflight.delete(key);
@@ -128,7 +150,7 @@ class CacheService {
         if (this.closed || entry.invalidated || this.resetVersion !== resetVersion) {
           return value;
         }
-        await this.set(key, value, ttlSeconds);
+        await this.writeToStore(key, value, ttlSeconds);
         if (!this.closed && (entry.invalidated || this.resetVersion !== resetVersion)) {
           await this.deleteFromStore(key);
         }
@@ -144,7 +166,7 @@ class CacheService {
       });
       entry.promise = promise;
       this.inflight.set(key, entry);
-      return promise;
+      return [await promise, 'miss'];
     } finally {
       this.endPendingLoad(key, resetVersion);
     }
@@ -157,6 +179,9 @@ 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;
     }
@@ -177,6 +202,9 @@ 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;
     }
@@ -185,7 +213,7 @@ class CacheService {
     this.pendingLoads.clear();
     this.pendingInvalidations.clear();
     this.invalidatedInflight.clear();
-    await this.runStoreOperation(async () => {
+    await this.storeOperations.runExclusive(async () => {
       if (this.closed) {
         return;
       }
@@ -196,19 +224,25 @@ class CacheService {
   /**
    * 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();
-    await this.runStoreOperation(async () => {
+    return this.storeOperations.runExclusive(async () => {
       if (this.store.close) {
         await this.store.close();
         return;
@@ -219,7 +253,7 @@ class CacheService {
     });
   }
   async deleteFromStore(key) {
-    await this.runStoreOperation(async () => {
+    await this.storeOperations.run(async () => {
       if (this.closed) {
         return;
       }

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) {