@fluojs/cache-manager 1.0.0-beta.1

package/dist/interceptor.js

@@ -0,0 +1,216 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+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 { metadataSymbol } from '@fluojs/core/internal';
+import { SseResponse } from '@fluojs/http';
+import { cacheRouteMetadataKey, getCacheEvictMetadata, getCacheKeyMetadata, getCacheTtlMetadata } from './decorators.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 = Reflect.get(controllerToken, metadataSymbol);
+  if (!isMetadataBag(classBag)) {
+    return undefined;
+  }
+  const routeMap = classBag[cacheRouteMetadataKey];
+  if (!(routeMap instanceof Map)) {
+    return undefined;
+  }
+  const methodMetadata = routeMap.get(methodName);
+  return isMetadataBag(methodMetadata) ? methodMetadata : undefined;
+}
+function normalizeCacheMethod(method) {
+  return method.toUpperCase();
+}
+function buildSortedQueryString(query) {
+  const entries = Object.entries(query).filter(([, value]) => value !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => {
+    if (Array.isArray(value)) {
+      return value.map(v => `${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`).join('&');
+    }
+    return `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`;
+  });
+  return entries.join('&');
+}
+function appendPrincipalScope(key, context, resolver) {
+  if (resolver) {
+    const scope = resolver(context);
+    return scope !== undefined ? `${key}|principal:${scope}` : key;
+  }
+  const principal = context.requestContext.principal;
+  if (!principal) {
+    return key;
+  }
+  const issuer = encodeURIComponent(principal.issuer ?? 'unknown');
+  const subject = encodeURIComponent(principal.subject);
+  return `${key}|principal:${issuer}:${subject}`;
+}
+function defaultCacheKey(context, strategy, resolver) {
+  if (typeof strategy === 'function') {
+    return strategy(context);
+  }
+  const path = context.handler.metadata.effectivePath;
+  const query = context.requestContext.request.query;
+  if (strategy === 'route') {
+    return appendPrincipalScope(path, context, resolver);
+  }
+  const queryString = buildSortedQueryString(query);
+  if (!queryString) {
+    return appendPrincipalScope(path, context, resolver);
+  }
+  return appendPrincipalScope(`${path}?${queryString}`, context, resolver);
+}
+function normalizeTtl(ttlSeconds, fallback) {
+  const candidate = ttlSeconds ?? fallback;
+  if (!Number.isFinite(candidate) || candidate < 0) {
+    return undefined;
+  }
+  return candidate;
+}
+function normalizeEvictKeys(value) {
+  if (typeof value === 'string') {
+    return value.length > 0 ? [value] : [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(key => key.length > 0);
+  }
+  return [];
+}
+async function resolveCacheKeyValue(metadata, context, strategy, resolver) {
+  if (!metadata) {
+    return defaultCacheKey(context, strategy, resolver);
+  }
+  if (typeof metadata === 'string') {
+    return metadata;
+  }
+  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;
+  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(() => {
+    runEviction();
+    restore();
+  }, EVICTION_FALLBACK_TIMEOUT_MS);
+  response.send = async body => {
+    await originalSend(body);
+    runEviction();
+    restore();
+  };
+  return restore;
+}
+
+/**
+ * Caches GET responses and evicts related entries after successful write operations.
+ */
+let _CacheInterceptor;
+class CacheInterceptor {
+  static {
+    [_CacheInterceptor, _initClass] = _applyDecs(this, [Inject(CacheService, CACHE_OPTIONS)], []).c;
+  }
+  constructor(cache, options) {
+    this.cache = cache;
+    this.options = options;
+  }
+  async intercept(context, next) {
+    const method = normalizeCacheMethod(context.requestContext.request.method);
+    const metadataBag = getMethodMetadataBag(context.handler.controllerToken, context.handler.methodName);
+    if (method === 'GET') {
+      return this.interceptGet(context, next, metadataBag);
+    }
+    const result = await next.handle();
+    await this.evictAfterWrite(context, metadataBag, result);
+    return result;
+  }
+  async interceptGet(context, next, metadataBag) {
+    const keyMetadata = metadataBag ? getCacheKeyMetadata(metadataBag) : undefined;
+    const key = await resolveCacheKeyValue(keyMetadata, context, this.options.httpKeyStrategy, this.options.principalScopeResolver);
+    const ttl = normalizeTtl(metadataBag ? getCacheTtlMetadata(metadataBag) : undefined, this.options.ttl);
+    if (ttl !== undefined) {
+      const cached = await this.safeGet(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+    }
+    const value = await next.handle();
+    if (ttl !== undefined && this.shouldCacheValue(context, value)) {
+      await this.safeSet(key, value, ttl);
+    }
+    return value;
+  }
+  async evictAfterWrite(context, metadataBag, value) {
+    const evictMetadata = metadataBag ? getCacheEvictMetadata(metadataBag) : undefined;
+    if (!evictMetadata) {
+      return;
+    }
+    const runEviction = async () => {
+      const keys = await this.resolveEvictKeys(evictMetadata, context, value);
+      await Promise.all(Array.from(new Set(keys)).map(async key => {
+        await this.safeDel(key);
+      }));
+    };
+    if (context.requestContext.response.committed) {
+      await runEviction();
+      return;
+    }
+    installDeferredEviction(context.requestContext.response, runEviction);
+  }
+  async resolveEvictKeys(metadata, context, value) {
+    if (typeof metadata === 'function') {
+      return normalizeEvictKeys(await metadata(context, value));
+    }
+    return normalizeEvictKeys(metadata);
+  }
+  shouldCacheValue(context, value) {
+    if (value === undefined) {
+      return false;
+    }
+    if (value instanceof SseResponse) {
+      return false;
+    }
+    return context.requestContext.response.committed !== true;
+  }
+  async safeGet(key) {
+    try {
+      return await this.cache.get(key);
+    } catch {
+      return undefined;
+    }
+  }
+  async safeSet(key, value, ttl) {
+    try {
+      await this.cache.set(key, value, ttl);
+    } catch {}
+  }
+  async safeDel(key) {
+    try {
+      await this.cache.del(key);
+    } catch {}
+  }
+  static {
+    _initClass();
+  }
+}
+export { _CacheInterceptor as CacheInterceptor };

package/dist/module.d.ts

@@ -0,0 +1,32 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { CacheModuleOptions } from './types.js';
+/**
+ * Runtime module entrypoint for cache-manager services and interceptor wiring.
+ *
+ * @remarks
+ * This module only wires providers and store resolution. The documented cache
+ * semantics remain defined by the decorators, interceptor, and `CacheService`.
+ */
+export declare class CacheModule {
+    /**
+     * Register cache providers for the current application module graph.
+     *
+     * @remarks
+     * This is the primary package entrypoint, including custom
+     * `defineModule(...)` composition. Root-package consumers should treat
+     * low-level provider wiring as an internal implementation detail.
+     *
+     * @param options Cache module options.
+     * @returns A runtime module exporting `CacheService` and `CacheInterceptor`.
+     *
+     * @example
+     * ```ts
+     * CacheModule.forRoot({
+     *   store: 'redis',
+     *   ttl: 300,
+     * });
+     * ```
+     */
+    static forRoot(options?: CacheModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +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"}

package/dist/module.js

@@ -0,0 +1,166 @@
+import { defineModule } from '@fluojs/runtime';
+import { RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { CacheInterceptor } from './interceptor.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';
+const DEFAULT_MEMORY_STORE_TTL_SECONDS = 300;
+const REDIS_PEER_MODULE_SPECIFIER = '@fluojs/redis';
+const loadOptionalModule = async specifier => import(specifier);
+function isMissingRedisPeer(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = 'code' in error ? error.code : undefined;
+  return code === 'ERR_MODULE_NOT_FOUND' && error.message.includes(REDIS_PEER_MODULE_SPECIFIER);
+}
+function isRedisPeerModule(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return 'getRedisClientToken' in value && typeof value.getRedisClientToken === 'function';
+}
+function createRedisBootstrapError() {
+  return new Error(['@fluojs/cache-manager redis store requires a Redis client at bootstrap.', 'Install and import @fluojs/redis, configure options.redis.clientName, or provide options.redis.client directly.'].join(' '));
+}
+async function resolveRedisPeerModule() {
+  try {
+    const moduleNamespace = await loadOptionalModule(REDIS_PEER_MODULE_SPECIFIER);
+    if (!isRedisPeerModule(moduleNamespace)) {
+      throw new Error('@fluojs/cache-manager expected @fluojs/redis to export getRedisClientToken().');
+    }
+    return moduleNamespace;
+  } catch (error) {
+    if (isMissingRedisPeer(error)) {
+      throw createRedisBootstrapError();
+    }
+    throw error;
+  }
+}
+function normalizeCacheModuleOptions(options = {}) {
+  const store = options.store ?? 'memory';
+  return {
+    isGlobal: options.isGlobal ?? false,
+    keyPrefix: options.keyPrefix ?? 'fluo:cache:',
+    redis: options.redis,
+    store,
+    ttl: options.ttl ?? (store === 'memory' ? DEFAULT_MEMORY_STORE_TTL_SECONDS : 0),
+    httpKeyStrategy: options.httpKeyStrategy ?? 'route',
+    principalScopeResolver: options.principalScopeResolver
+  };
+}
+function isNormalizedCacheModuleOptions(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const candidate = value;
+  return 'store' in candidate && (typeof candidate.store === 'string' || typeof candidate.store === 'object') && typeof candidate.keyPrefix === 'string' && typeof candidate.ttl === 'number' && typeof candidate.isGlobal === 'boolean' && 'httpKeyStrategy' in candidate;
+}
+function isContainer(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return 'has' in value && 'resolve' in value;
+}
+async function resolveRedisClient(options, container) {
+  let resolvedClient = options.redis?.client;
+  if (!resolvedClient) {
+    let redisToken;
+    try {
+      const {
+        getRedisClientToken
+      } = await resolveRedisPeerModule();
+      redisToken = getRedisClientToken(options.redis?.clientName);
+    } catch (error) {
+      if (isMissingRedisPeer(error)) {
+        throw createRedisBootstrapError();
+      }
+      throw error;
+    }
+    if (container.has(redisToken)) {
+      resolvedClient = await container.resolve(redisToken);
+    }
+  }
+  if (!resolvedClient) {
+    throw createRedisBootstrapError();
+  }
+  return resolvedClient;
+}
+async function createStore(options, container) {
+  if (typeof options.store === 'object' && options.store !== null) {
+    return options.store;
+  }
+  if (options.store === 'redis') {
+    return new RedisStore(await resolveRedisClient(options, container), {
+      keyPrefix: options.keyPrefix,
+      scanCount: options.redis?.scanCount
+    });
+  }
+  return new MemoryStore();
+}
+function createCacheModuleProviders(options = {}) {
+  const normalized = normalizeCacheModuleOptions(options);
+  return [{
+    provide: CACHE_OPTIONS,
+    useValue: normalized
+  }, {
+    inject: [CACHE_OPTIONS, RUNTIME_CONTAINER],
+    provide: CACHE_STORE,
+    useFactory: (...deps) => {
+      const moduleOptions = deps[0];
+      const container = deps[1];
+      if (!isNormalizedCacheModuleOptions(moduleOptions)) {
+        throw new Error('Cache module options provider resolved an invalid configuration object.');
+      }
+      if (!isContainer(container)) {
+        throw new Error('Cache module requires runtime container access to resolve optional Redis client.');
+      }
+      return createStore(moduleOptions, container);
+    }
+  }, {
+    provide: CacheService,
+    useClass: CacheService
+  }, {
+    provide: CacheInterceptor,
+    useClass: CacheInterceptor
+  }];
+}
+
+/**
+ * Runtime module entrypoint for cache-manager services and interceptor wiring.
+ *
+ * @remarks
+ * This module only wires providers and store resolution. The documented cache
+ * semantics remain defined by the decorators, interceptor, and `CacheService`.
+ */
+export class CacheModule {
+  /**
+   * Register cache providers for the current application module graph.
+   *
+   * @remarks
+   * This is the primary package entrypoint, including custom
+   * `defineModule(...)` composition. Root-package consumers should treat
+   * low-level provider wiring as an internal implementation detail.
+   *
+   * @param options Cache module options.
+   * @returns A runtime module exporting `CacheService` and `CacheInterceptor`.
+   *
+   * @example
+   * ```ts
+   * CacheModule.forRoot({
+   *   store: 'redis',
+   *   ttl: 300,
+   * });
+   * ```
+   */
+  static forRoot(options = {}) {
+    const normalized = normalizeCacheModuleOptions(options);
+    class CacheRootModule extends CacheModule {}
+    return defineModule(CacheRootModule, {
+      exports: [CacheService, CacheInterceptor],
+      global: normalized.isGlobal,
+      providers: createCacheModuleProviders(options)
+    });
+  }
+}

package/dist/service.d.ts

@@ -0,0 +1,54 @@
+import type { CacheStore, NormalizedCacheModuleOptions } from './types.js';
+/**
+ * Application-level cache facade used for direct cache reads, writes, and read-through loading.
+ */
+export declare class CacheService {
+    private readonly store;
+    private readonly options;
+    private readonly inflight;
+    private readonly pendingLoads;
+    private readonly invalidatedInflight;
+    private resetVersion;
+    private beginPendingLoad;
+    private endPendingLoad;
+    constructor(store: CacheStore, options: NormalizedCacheModuleOptions);
+    /**
+     * Read a cached value by key.
+     *
+     * @param key Cache entry key.
+     * @returns The cached value, or `undefined` when the key is missing or expired.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store a value in the configured cache store.
+     *
+     * @param key Cache entry key.
+     * @param value Value to cache.
+     * @param ttlSeconds Optional per-call TTL override in seconds.
+     * @returns A promise that resolves after the write completes.
+     */
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Load a value through the cache, de-duplicating concurrent misses for the same key.
+     *
+     * @param key Cache entry key.
+     * @param loader Async loader invoked on cache miss.
+     * @param ttlSeconds Optional per-call TTL override in seconds.
+     * @returns The cached or freshly loaded value.
+     */
+    remember<T = unknown>(key: string, loader: () => Promise<T>, ttlSeconds?: number): Promise<T>;
+    /**
+     * Delete a single cache entry.
+     *
+     * @param key Cache entry key.
+     * @returns A promise that resolves after the entry is removed.
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Clear every cache entry owned by the configured store.
+     *
+     * @returns A promise that resolves after the store reset completes.
+     */
+    reset(): Promise<void>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +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;AAE3E;;GAEG;AACH,qBACa,YAAY;IAsBrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtB1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,cAAc;gBAYH,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;IAyCb;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

package/dist/service.js

@@ -0,0 +1,130 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+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 { CACHE_OPTIONS, CACHE_STORE } from './tokens.js';
+let _CacheService;
+/**
+ * Application-level cache facade used for direct cache reads, writes, and read-through loading.
+ */
+class CacheService {
+  static {
+    [_CacheService, _initClass] = _applyDecs(this, [Inject(CACHE_STORE, CACHE_OPTIONS)], []).c;
+  }
+  inflight = new Map();
+  pendingLoads = new Map();
+  invalidatedInflight = new Set();
+  resetVersion = 0;
+  beginPendingLoad(key) {
+    this.pendingLoads.set(key, (this.pendingLoads.get(key) ?? 0) + 1);
+  }
+  endPendingLoad(key) {
+    const remaining = (this.pendingLoads.get(key) ?? 0) - 1;
+    if (remaining > 0) {
+      this.pendingLoads.set(key, remaining);
+      return;
+    }
+    this.pendingLoads.delete(key);
+  }
+  constructor(store, options) {
+    this.store = store;
+    this.options = options;
+  }
+
+  /**
+   * Read a cached value by key.
+   *
+   * @param key Cache entry key.
+   * @returns The cached value, or `undefined` when the key is missing or expired.
+   */
+  get(key) {
+    return Promise.resolve(this.store.get(key));
+  }
+
+  /**
+   * Store a value in the configured cache store.
+   *
+   * @param key Cache entry key.
+   * @param value Value to cache.
+   * @param ttlSeconds Optional per-call TTL override in seconds.
+   * @returns A promise that resolves after the write completes.
+   */
+  async set(key, value, ttlSeconds) {
+    const resolvedTtl = ttlSeconds ?? this.options.ttl;
+    if (!Number.isFinite(resolvedTtl) || resolvedTtl < 0) {
+      return;
+    }
+    await this.store.set(key, value, resolvedTtl);
+  }
+
+  /**
+   * Load a value through the cache, de-duplicating concurrent misses for the same key.
+   *
+   * @param key Cache entry key.
+   * @param loader Async loader invoked on cache miss.
+   * @param ttlSeconds Optional per-call TTL override in seconds.
+   * @returns The cached or freshly loaded value.
+   */
+  async remember(key, loader, ttlSeconds) {
+    this.beginPendingLoad(key);
+    try {
+      const resetVersion = this.resetVersion;
+      const cached = await this.get(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const existing = this.inflight.get(key);
+      if (existing) {
+        return existing;
+      }
+      const promise = loader().then(async value => {
+        if (this.invalidatedInflight.has(key) || this.resetVersion !== resetVersion) {
+          return value;
+        }
+        await this.set(key, value, ttlSeconds);
+        if (this.invalidatedInflight.has(key) || this.resetVersion !== resetVersion) {
+          await this.store.del(key);
+        }
+        return value;
+      }).finally(() => {
+        this.inflight.delete(key);
+        this.invalidatedInflight.delete(key);
+      });
+      this.inflight.set(key, promise);
+      return promise;
+    } finally {
+      this.endPendingLoad(key);
+    }
+  }
+
+  /**
+   * Delete a single cache entry.
+   *
+   * @param key Cache entry key.
+   * @returns A promise that resolves after the entry is removed.
+   */
+  async del(key) {
+    if (this.pendingLoads.has(key) || this.inflight.has(key)) {
+      this.invalidatedInflight.add(key);
+    }
+    await this.store.del(key);
+  }
+
+  /**
+   * Clear every cache entry owned by the configured store.
+   *
+   * @returns A promise that resolves after the store reset completes.
+   */
+  async reset() {
+    this.resetVersion += 1;
+    this.invalidatedInflight.clear();
+    await this.store.reset();
+  }
+  static {
+    _initClass();
+  }
+}
+export { _CacheService as CacheService };

package/dist/status.d.ts

@@ -0,0 +1,45 @@
+import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Snapshot shape produced by the cache-manager platform status helpers.
+ */
+export interface CacheManagerPlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/**
+ * Backing store categories recognized by the cache-manager status adapter.
+ */
+export type CacheManagerStoreKind = 'memory' | 'redis' | 'custom';
+/**
+ * Ownership modes used to describe who is responsible for the backing store lifecycle.
+ */
+export type CacheManagerStoreOwnershipMode = 'framework' | 'external';
+/**
+ * Input consumed by cache-manager status and diagnostic helpers.
+ */
+export interface CacheManagerStatusAdapterInput {
+    componentId?: string;
+    storeKind: CacheManagerStoreKind;
+    storeOwnershipMode?: CacheManagerStoreOwnershipMode;
+    backingStoreReady?: boolean;
+    backingStoreReason?: string;
+    dependencyId?: string;
+    cacheCriticalPath?: boolean;
+}
+/**
+ * Create a platform status snapshot for cache-manager readiness, health, and telemetry.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns A cache-manager status snapshot suitable for platform diagnostics.
+ */
+export declare function createCacheManagerPlatformStatusSnapshot(input: CacheManagerStatusAdapterInput): CacheManagerPlatformStatusSnapshot;
+/**
+ * Translate cache-manager readiness input into platform diagnostic issues.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns Zero or more diagnostic issues describing degraded or unavailable cache backing stores.
+ */
+export declare function createCacheManagerPlatformDiagnosticIssues(input: CacheManagerStatusAdapterInput): PlatformDiagnosticIssue[];
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEhI;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG,WAAW,GAAG,UAAU,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,qBAAqB,CAAC;IACjC,kBAAkB,CAAC,EAAE,8BAA8B,CAAC;IACpD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAgDD;;;;;GAKG;AACH,wBAAgB,wCAAwC,CAAC,KAAK,EAAE,8BAA8B,GAAG,kCAAkC,CAgClI;AAED;;;;;GAKG;AACH,wBAAgB,0CAA0C,CAAC,KAAK,EAAE,8BAA8B,GAAG,uBAAuB,EAAE,CAuB3H"}