@vercube/cache 1.2.1 → 1.3.1

package/dist/index.d.mts

@@ -10,21 +10,21 @@ import { CacheEntry, CacheOptions, CacheStatus, StorageInterface } from "ocache"
  * ocache builds keys as `<base>:<group>:<name>:<key>.json`, so the base is always
  * the first colon separated segment and can be parsed back out on read/write.
  */
-declare const CACHE_BASE_PREFIX = "/cache";
+export declare const CACHE_BASE_PREFIX = "/cache";
 /**
  * Builds the cache key base for a storage mounted in {@link StorageManager}.
  *
  * @param {string} [storage] - Name of the mounted storage, `default` when omitted
  * @returns {string} The base prefix cache keys for that storage start with
  */
-declare function cacheBaseForStorage(storage?: string): string;
+export declare function cacheBaseForStorage(storage?: string): string;
 /**
  * Extracts the mounted storage name back out of a full cache key.
  *
  * @param {string} key - A cache key produced by the caching engine
  * @returns {string} Name of the storage the key belongs to, `default` when the key carries no storage segment
  */
-declare function storageNameFromCacheKey(key: string): string;
+export declare function storageNameFromCacheKey(key: string): string;
 /**
  * Bridges the caching engine onto the Vercube {@link StorageManager}.
  *
@@ -42,7 +42,7 @@ declare function storageNameFromCacheKey(key: string): string;
  * caching works with zero configuration. Mounting the name yourself - before or
  * after - is what swaps the backend for a real one.
  */
-declare class CacheStorageAdapter implements StorageInterface {
+export declare class CacheStorageAdapter implements StorageInterface {
   /** Storage manager holding every mounted storage */
   protected gStorageManager: StorageManager | null;
   /** Logger instance */
@@ -94,7 +94,7 @@ declare class CacheStorageAdapter implements StorageInterface {
 }
 //#endregion
 //#region src/Types/CacheTypes.d.ts
-declare namespace CacheTypes {
+export declare namespace CacheTypes {
   /**
    * Name (or ordered list of names) of storages mounted in the {@link StorageManager}
    * that should back a cached function.
@@ -120,11 +120,12 @@ declare namespace CacheTypes {
   /**
    * Options accepted by {@link CacheManager.cached} and the `@Cache()` decorator.
    *
-   * This is the ocache option set with the low level `base` option replaced by the
-   * Vercube native `storage` option - `base` is derived from it so that cache keys
-   * can be routed to the right mounted storage.
+   * This is the ocache option set with the low level `base` and `storage` options
+   * replaced by the Vercube native `storage` option - `base` is derived from it so
+   * that cache keys can be routed to the right mounted storage, and the backend is
+   * always the {@link CacheStorageAdapter} the CacheManager owns.
    */
-  type Options<T = any, ArgsT extends unknown[] = any[]> = Omit<CacheOptions<T, ArgsT>, 'base'> & {
+  type Options<T = any, ArgsT extends unknown[] = any[]> = Omit<CacheOptions<T, ArgsT>, 'base' | 'storage'> & {
     /** Storage (or storages, for multi-tier caching) mounted in StorageManager to keep entries in. */
     storage?: StorageRef;
   };
@@ -200,7 +201,7 @@ declare namespace CacheTypes {
  * await getUser.invalidate('123'); // drops the entry
  * ```
  */
-declare class CacheManager {
+export declare class CacheManager {
   /** Container instance */
   protected gContainer: Container;
   /** Logger instance */
@@ -210,7 +211,7 @@ declare class CacheManager {
   /** Storage adapter bridging the caching engine onto the mounted storages */
   protected fAdapter: CacheStorageAdapter | null;
   /**
-   * Returns the storage adapter this manager installed into the caching engine.
+   * Returns the storage adapter this manager binds every cached function to.
    *
    * @returns {CacheStorageAdapter | null} The adapter, or null before initialization
    */
@@ -289,6 +290,14 @@ declare class CacheManager {
    * @protected
    */
   protected resolveOptions<T, ArgsT extends unknown[]>(options: CacheTypes.Options<T, ArgsT>): CacheOptions<T, ArgsT>;
+  /**
+   * Returns the storage adapter every cached function of this manager is bound to,
+   * resolving it on first use so that options can be built before `@Init()` ran.
+   *
+   * @returns {CacheStorageAdapter} The adapter backing this manager
+   * @protected
+   */
+  protected resolveAdapter(): CacheStorageAdapter;
   /**
    * Drops keys whose value is `undefined`, so that an explicitly passed
    * `undefined` never shadows a configured default with a missing value.
@@ -300,7 +309,7 @@ declare class CacheManager {
    */
   protected stripUndefined<T extends object>(options: T): Partial<T>;
   /**
-   * Installs the storage adapter into the caching engine.
+   * Creates the storage adapter every cached function of this manager routes through.
    * Called automatically with the `@Init()` decorator.
    *
    * @returns {void}
@@ -318,7 +327,7 @@ declare class CacheManager {
  * the container has been flushed - and defaults configured during bootstrap -
  * are still picked up.
  */
-declare class CacheDecorator extends BaseDecorator<CacheTypes.DecoratorOptions> {
+export declare class CacheDecorator extends BaseDecorator<CacheTypes.DecoratorOptions> {
   /** Cache manager owning the caching engine wiring */
   protected gCacheManager: CacheManager;
   /** The untouched method, kept so it can be restored on destroy */
@@ -381,14 +390,14 @@ declare class CacheDecorator extends BaseDecorator<CacheTypes.DecoratorOptions>
  * }
  * ```
  */
-declare function Cache(options?: CacheTypes.DecoratorOptions): Function;
+export declare function Cache(options?: CacheTypes.DecoratorOptions): Function;
 //#endregion
 //#region src/Errors/CacheError.d.ts
 /**
  * Custom error class for cache-related errors.
  * Wraps underlying cache/storage errors with standardized error messages.
  */
-declare class CacheError extends Error {
+export declare class CacheError extends Error {
   /**
    * The original error that caused this cache error
    */
@@ -403,5 +412,4 @@ declare class CacheError extends Error {
   readonly metadata?: Record<string, unknown>;
   constructor(message: string, operation: string, cause?: Error, metadata?: Record<string, unknown>);
 }
-//#endregion
-export { CACHE_BASE_PREFIX, Cache, CacheDecorator, CacheError, CacheManager, CacheStorageAdapter, CacheTypes, cacheBaseForStorage, storageNameFromCacheKey };
+//#endregion

package/dist/index.mjs

@@ -2,7 +2,8 @@ import { BaseDecorator, Container, Init, Inject, InjectOptional, createDecorator
 import { hash } from "ohash";
 import { Logger } from "@vercube/logger";
 import { StorageManager } from "@vercube/storage";
-import { defineCachedFunction, expireCache, invalidateCache, resolveCacheKeys, setStorage, useStorage } from "ocache";
+import { defineCachedFunction, expireCache, invalidateCache, resolveCacheKeys } from "ocache";
+import { SpanKind, ValueType, createInstrument } from "@vercube/telemetry/instrument";
 import { MemoryStorage } from "@vercube/storage/drivers/MemoryStorage";
 //#region src/Errors/CacheError.ts
 /**
@@ -32,7 +33,71 @@ var CacheError = class CacheError extends Error {
 	}
 };
 //#endregion
-//#region \0@oxc-project+runtime@0.140.0/helpers/esm/decorate.js
+//#region src/Common/Instrument.ts
+/**
+* Traces and counts cache activity.
+*
+* The toolkit comes from `@vercube/telemetry/instrument`, which is the only
+* place in the framework that speaks to OpenTelemetry directly, and it creates
+* no instrument until one is actually used.
+*/
+const instrument = createInstrument("@vercube/cache");
+/** Attribute marking whether a lookup was served from the cache. */
+const CACHE_HIT = "vercube.cache.hit";
+/** Attribute carrying the cached function's name. */
+const CACHE_NAME = "vercube.cache.name";
+/**
+* Counts one cache lookup.
+*
+* Hits are not counted directly: a hit is the absence of a resolve, and
+* deriving it from `lookups - misses` avoids having to decide, at the moment a
+* value comes back, whether the engine actually consulted the origin. Two
+* monotonic counters also survive being scraped at any interval, which a
+* hit/miss ratio computed in-process does not.
+*
+* @param name - The cached function's name
+*/
+function countLookup(name) {
+	instrument.counter("vercube.cache.lookups", {
+		description: "Calls to a cached function.",
+		unit: "{lookup}",
+		valueType: ValueType.INT
+	}).add(1, { [CACHE_NAME]: name });
+}
+/**
+* Counts one cache miss and marks the active span as a miss.
+*
+* Called from inside the cached function itself, so it runs in the span opened
+* for that lookup and needs no per-call bookkeeping of its own.
+*
+* @param name - The cached function's name
+*/
+function countMiss(name) {
+	instrument.counter("vercube.cache.misses", {
+		description: "Cached function calls that had to resolve the value.",
+		unit: "{miss}",
+		valueType: ValueType.INT
+	}).add(1, { [CACHE_NAME]: name });
+	instrument.activeSpan()?.setAttribute(CACHE_HIT, false);
+}
+/**
+* Traces one cache lookup.
+*
+* @param name - The cached function's name
+* @param fn - The lookup
+* @returns Whatever the lookup returned
+*/
+function traceLookup(name, fn) {
+	return instrument.span(`cache.${name}`, {
+		kind: SpanKind.CLIENT,
+		attributes: {
+			[CACHE_NAME]: name,
+			[CACHE_HIT]: true
+		}
+	}, fn);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.150.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -204,7 +269,7 @@ var CacheManager = class {
 	/** Storage adapter bridging the caching engine onto the mounted storages */
 	fAdapter = null;
 	/**
-	* Returns the storage adapter this manager installed into the caching engine.
+	* Returns the storage adapter this manager binds every cached function to.
 	*
 	* @returns {CacheStorageAdapter | null} The adapter, or null before initialization
 	*/
@@ -247,7 +312,18 @@ var CacheManager = class {
 	*/
 	cached(fn, options = {}) {
 		if (typeof fn !== "function") throw new CacheError("Cached target must be a function", "cached", void 0, { received: typeof fn });
-		return defineCachedFunction(fn, this.resolveOptions(options));
+		const resolved = this.resolveOptions(options);
+		const name = resolved.name ?? fn.name ?? "anonymous";
+		const instrumented = (...args) => {
+			countMiss(name);
+			return fn(...args);
+		};
+		const cached = defineCachedFunction(instrumented, resolved);
+		const wrapper = ((...args) => {
+			countLookup(name);
+			return traceLookup(name, () => Promise.resolve(cached(...args)));
+		});
+		return Object.assign(wrapper, cached);
 	}
 	/**
 	* Removes cached entries for the given arguments from every storage tier.
@@ -319,10 +395,22 @@ var CacheManager = class {
 		const base = storages.map((name) => cacheBaseForStorage(name));
 		return {
 			...rest,
-			base: base.length === 1 ? base[0] : base
+			base: base.length === 1 ? base[0] : base,
+			storage: this.resolveAdapter()
 		};
 	}
 	/**
+	* Returns the storage adapter every cached function of this manager is bound to,
+	* resolving it on first use so that options can be built before `@Init()` ran.
+	*
+	* @returns {CacheStorageAdapter} The adapter backing this manager
+	* @protected
+	*/
+	resolveAdapter() {
+		this.fAdapter ??= this.gContainer.resolve(CacheStorageAdapter);
+		return this.fAdapter;
+	}
+	/**
 	* Drops keys whose value is `undefined`, so that an explicitly passed
 	* `undefined` never shadows a configured default with a missing value.
 	*
@@ -335,7 +423,7 @@ var CacheManager = class {
 		return Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0));
 	}
 	/**
-	* Installs the storage adapter into the caching engine.
+	* Creates the storage adapter every cached function of this manager routes through.
 	* Called automatically with the `@Init()` decorator.
 	*
 	* @returns {void}
@@ -343,9 +431,7 @@ var CacheManager = class {
 	*/
 	init() {
 		if (!this.gContainer.getOptional(StorageManager)) this.gLogger?.warn("Vercube/CacheManager::StorageManager is not registered - bind it so cached entries have a storage to live in");
-		if (useStorage() instanceof CacheStorageAdapter) this.gLogger?.warn("Vercube/CacheManager::another CacheManager is already installed in this process - cached functions from every container will now route through this one");
-		this.fAdapter = this.gContainer.resolve(CacheStorageAdapter);
-		setStorage(this.fAdapter);
+		this.resolveAdapter();
 	}
 };
 __decorate([Inject(Container)], CacheManager.prototype, "gContainer", void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercube/cache",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Cache module for Vercube framework",
   "repository": {
     "type": "git",
@@ -22,14 +22,15 @@
     "README.md"
   ],
   "devDependencies": {
-    "@vercube/core": "1.2.1"
+    "@vercube/core": "1.3.1"
   },
   "dependencies": {
-    "ocache": "0.2.0",
-    "ohash": "2.0.12",
-    "@vercube/di": "1.2.1",
-    "@vercube/logger": "1.2.1",
-    "@vercube/storage": "1.2.1"
+    "@vercube/di": "1.3.1",
+    "@vercube/logger": "1.3.1",
+    "@vercube/storage": "1.3.1",
+    "@vercube/telemetry": "1.3.1",
+    "ocache": "0.3.0",
+    "ohash": "2.0.12"
   },
   "publishConfig": {
     "access": "public"