@vercube/cache 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present - Vercube
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/vercube/vercube/refs/heads/main/.github/assets/cover.png" width="100%" alt="Vercube - Unleash your server development." />
+  <br>
+  <br>
+
+# @vercube/cache
+
+### Decorator driven caching for Vercube apps
+
+[![Ask DeepWiki](<https://img.shields.io/badge/ask-deepwiki-%20blue?style=for-the-badge&logo=bookstack&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)](https://deepwiki.com/vercube/vercube)
+![NPM Version](<https://img.shields.io/npm/v/%40vercube%2Fcache?style=for-the-badge&logo=npm&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232e2e2e&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40vercube%2Fcache>)
+![GitHub License](<https://img.shields.io/github/license/vercube/vercube?style=for-the-badge&logo=gitbook&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
+![Codecov](<https://img.shields.io/codecov/c/github/vercube/vercube?style=for-the-badge&logo=vitest&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
+
+**One decorator turns any method into a cached one - with TTL, stale-while-revalidate, call deduplication and precise invalidation. Every entry lives in a regular Vercube storage.**
+
+[Website](https://vercube.dev) • [Documentation](https://vercube.dev/docs/getting-started)
+
+</div>
+
+## ✨ Features
+
+- **`@Cache()` decorator** - cache any method, keyed by its arguments
+- **Backed by `@vercube/storage`** - memory, S3 or your own driver, no glue code
+- **Stale-while-revalidate** - serve instantly, refresh in the background
+- **Call deduplication** - concurrent calls for the same key share one execution
+- **Precise invalidation** - `invalidate()` and `expire()` right on the decorated method
+- **Self-invalidating** - entries are dropped when the method body or its options change
+- **Multi-tier** - read through a fast local storage into a shared one
+
+## 📦 Installation
+
+```bash
+pnpm add @vercube/cache @vercube/storage
+```
+
+## 📖 Usage
+
+```ts
+import { Cache } from '@vercube/cache';
+
+export class UsersService {
+  @Cache({ maxAge: 300, swr: true, staleMaxAge: 900 })
+  public async getUser(id: string): Promise<User> {
+    return this.database.findUser(id);
+  }
+}
+```
+
+Check out the full [documentation](https://vercube.dev/docs/modules/cache/overview)
+
+## 📜 License
+
+[MIT](https://github.com/vercube/vercube/blob/main/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,407 @@
+import { BaseDecorator, Container } from "@vercube/di";
+import { Logger } from "@vercube/logger";
+import { Storage, StorageManager } from "@vercube/storage";
+import { CacheEntry, CacheOptions, CacheStatus, StorageInterface } from "ocache";
+//#region src/Services/CacheStorageAdapter.d.ts
+/**
+ * Prefix every cache key starts with. The segment that follows it (when present)
+ * is the name of the storage mounted in {@link StorageManager} that backs the entry.
+ *
+ * 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";
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Bridges the caching engine onto the Vercube {@link StorageManager}.
+ *
+ * The cache module owns no storage of its own - every entry lives in a storage
+ * mounted in `@vercube/storage`, so a cache can be backed by memory, S3 or any
+ * other driver simply by mounting it, and the very same entries are visible
+ * through the regular storage API.
+ *
+ * Every cache key carries the name of the storage it belongs to in its base
+ * segment, so a single adapter instance serves cached functions that live in
+ * different storages - and even ones that span several of them at once.
+ *
+ * A cached function may point at a storage that has not been mounted; in that
+ * case a {@link MemoryStorage} is mounted under that name on first use so that
+ * 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 {
+  /** Storage manager holding every mounted storage */
+  protected gStorageManager: StorageManager | null;
+  /** Logger instance */
+  protected gLogger: Logger | null;
+  /** In-flight auto-mounts, keyed by storage name, so concurrent calls share one storage */
+  protected fMounting: Map<string, Promise<Storage>>;
+  /**
+   * Reads a cache entry from the storage its key points at.
+   *
+   * @template T - Type of the stored entry
+   * @param {string} key - Full cache key, including the storage base prefix
+   * @returns {Promise<T | null>} The stored entry, or null when it is absent
+   */
+  get<T = unknown>(key: string): Promise<T | null>;
+  /**
+   * Writes a cache entry to the storage its key points at.
+   *
+   * The caching engine signals a deletion by writing `null`, which is mapped onto
+   * the storage's delete operation so that no empty entries are left behind.
+   *
+   * @template T - Type of the value to store
+   * @param {string} key - Full cache key, including the storage base prefix
+   * @param {T} value - Entry to store, or null to remove it
+   * @param {{ ttl?: number }} [opts] - Storage hints, `ttl` in seconds
+   * @returns {Promise<void>} Resolves once the write is complete
+   */
+  set<T = unknown>(key: string, value: T, opts?: {
+    ttl?: number;
+  }): Promise<void>;
+  /**
+   * Resolves the mounted storage a cache key belongs to, mounting an in-memory
+   * one under that name when nothing has been mounted yet.
+   *
+   * @param {string} key - Full cache key, including the storage base prefix
+   * @returns {Promise<Storage>} The storage backing that key
+   * @protected
+   */
+  protected resolveStorage(key: string): Promise<Storage>;
+  /**
+   * Mounts an in-memory storage under the given name, so that a cached function
+   * pointing at a storage nobody mounted still works.
+   *
+   * @param {StorageManager} manager - Storage manager to mount into
+   * @param {string} name - Name of the storage to mount
+   * @returns {Promise<Storage>} The freshly mounted storage
+   * @protected
+   */
+  protected mountFallback(manager: StorageManager, name: string): Promise<Storage>;
+}
+//#endregion
+//#region src/Types/CacheTypes.d.ts
+declare namespace CacheTypes {
+  /**
+   * Name (or ordered list of names) of storages mounted in the {@link StorageManager}
+   * that should back a cached function.
+   *
+   * When an array is given, reads try each storage in order (multi-tier: hit the fast
+   * one first, fall back to the shared one) and writes go to all of them.
+   *
+   * When omitted, the `default` storage is used.
+   */
+  type StorageRef = string | string[];
+  /**
+   * How a cached value was served on a given call.
+   * - `hit` - a fresh cached value was returned without re-resolving
+   * - `stale` - a stale value was served while a background SWR refresh runs
+   * - `revalidated` - a prior value existed but was expired, so it was re-resolved in the foreground
+   * - `miss` - the value was resolved fresh on this call
+   */
+  type Status = CacheStatus;
+  /**
+   * A cache entry as it is stored, wrapping the cached value with its metadata.
+   */
+  type Entry<T = unknown> = CacheEntry<T>;
+  /**
+   * 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.
+   */
+  type Options<T = any, ArgsT extends unknown[] = any[]> = Omit<CacheOptions<T, ArgsT>, 'base'> & {
+    /** Storage (or storages, for multi-tier caching) mounted in StorageManager to keep entries in. */
+    storage?: StorageRef;
+  };
+  /**
+   * Application wide defaults applied to every cached function.
+   * Per-call options always win over these.
+   */
+  interface Defaults {
+    /** Number of seconds an entry stays fresh. @default 1 */
+    maxAge?: number;
+    /** Serve a stale entry while refreshing it in the background. @default false */
+    swr?: boolean;
+    /** Maximum number of seconds a stale entry may be served while revalidating. */
+    staleMaxAge?: number;
+    /** Cache key group prefix. @default 'functions' */
+    group?: string;
+    /** Default storage (or storages) to keep entries in. */
+    storage?: StorageRef;
+    /** Called for every cache related error (read, write, background refresh). */
+    onError?: (error: unknown) => void;
+  }
+  /**
+   * A function wrapped with caching, augmented with on-demand revalidation helpers.
+   */
+  type CachedFunction<T = unknown, ArgsT extends unknown[] = any[]> = {
+    (...args: ArgsT): Promise<T>;
+    /** Resolves every storage key (one per storage tier) the given arguments cache under. */
+    resolveKeys: (...args: ArgsT) => Promise<string[]>;
+    /** Removes cached entries for the given arguments from every storage tier. */
+    invalidate: (...args: ArgsT) => Promise<void>;
+    /** Marks cached entries as stale so the next access refreshes them. */
+    expire: (...args: ArgsT) => Promise<void>;
+  };
+  /**
+   * Options for the `@Cache()` decorator. Identical to {@link Options}, except that
+   * `name` defaults to `ClassName.methodName` when it is not given.
+   */
+  type DecoratorOptions<T = any, ArgsT extends unknown[] = any[]> = Options<T, ArgsT>;
+  /**
+   * A method wrapped by the `@Cache()` decorator, as seen from the outside.
+   * Use it to type a cached method so its `.invalidate()` / `.expire()` helpers are visible.
+   *
+   * @example
+   * ```ts
+   * class UsersService {
+   *   @Cache({ maxAge: 60 })
+   *   public getUser!: CacheTypes.CachedMethod<[id: string], User>;
+   * }
+   * ```
+   */
+  type CachedMethod<ArgsT extends unknown[] = any[], T = unknown> = CachedFunction<T, ArgsT>;
+}
+//#endregion
+//#region src/Services/CacheManager.d.ts
+/**
+ * Central entry point of the cache module.
+ *
+ * The CacheManager owns the wiring between the caching engine and the storages
+ * mounted in `@vercube/storage`, holds the application wide defaults and exposes
+ * the imperative API used both directly and by the `@Cache()` decorator.
+ *
+ * @example
+ * ```ts
+ * container.bind(CacheManager);
+ *
+ * const cache = container.get(CacheManager);
+ * cache.configure({ maxAge: 60, swr: true, staleMaxAge: 300, storage: 'cache' });
+ *
+ * const getUser = cache.cached((id: string) => db.users.find(id), { name: 'getUser' });
+ *
+ * await getUser('123');            // resolves and stores
+ * await getUser('123');            // served from cache
+ * await getUser.invalidate('123'); // drops the entry
+ * ```
+ */
+declare class CacheManager {
+  /** Container instance */
+  protected gContainer: Container;
+  /** Logger instance */
+  protected gLogger: Logger | null;
+  /** Application wide defaults applied to every cached function */
+  protected fDefaults: CacheTypes.Defaults;
+  /** 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 {CacheStorageAdapter | null} The adapter, or null before initialization
+   */
+  get adapter(): CacheStorageAdapter | null;
+  /**
+   * Returns the currently configured defaults.
+   *
+   * @returns {CacheTypes.Defaults} A copy of the active defaults
+   */
+  get defaults(): CacheTypes.Defaults;
+  /**
+   * Sets the application wide cache defaults. Values passed per cached function
+   * always win over these. Calling it repeatedly merges into the existing defaults.
+   *
+   * @param {CacheTypes.Defaults} defaults - Defaults to apply to every cached function
+   * @returns {void}
+   */
+  configure(defaults: CacheTypes.Defaults): void;
+  /**
+   * Wraps a function with caching.
+   *
+   * The returned function keeps the original signature and adds `resolveKeys()`,
+   * `invalidate()` and `expire()` helpers keyed exactly like the cached calls, so
+   * no cache key ever has to be rebuilt by hand.
+   *
+   * @template T - Return type of the wrapped function
+   * @template ArgsT - Argument tuple of the wrapped function
+   * @param {(...args: ArgsT) => T | Promise<T>} fn - The function to cache
+   * @param {CacheTypes.Options<T, ArgsT>} [options] - Per-function cache options
+   * @returns {CacheTypes.CachedFunction<T, ArgsT>} The cached function
+   */
+  cached<T, ArgsT extends unknown[] = any[]>(fn: (...args: ArgsT) => T | Promise<T>, options?: CacheTypes.Options<T, ArgsT>): CacheTypes.CachedFunction<T, ArgsT>;
+  /**
+   * Removes cached entries for the given arguments from every storage tier.
+   *
+   * Pass the same options (`name`, `group`, `storage`, `getKey`) the entry was
+   * cached with so the very same keys are resolved.
+   *
+   * @template ArgsT - Argument tuple the entry was cached under
+   * @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+   * @param {ArgsT} args - Arguments identifying the entry
+   * @returns {Promise<void>} Resolves once every tier has been cleared
+   */
+  invalidate<ArgsT extends unknown[] = any[]>(options: CacheTypes.Options<any, ArgsT>, ...args: ArgsT): Promise<void>;
+  /**
+   * Marks cached entries as stale without removing them.
+   *
+   * With `swr` enabled the stale value keeps being served (within `staleMaxAge`)
+   * while the next access refreshes it in the background; without it, the next
+   * call re-resolves before returning.
+   *
+   * @template ArgsT - Argument tuple the entry was cached under
+   * @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+   * @param {ArgsT} args - Arguments identifying the entry
+   * @returns {Promise<void>} Resolves once every tier has been marked
+   */
+  expire<ArgsT extends unknown[] = any[]>(options: CacheTypes.Options<any, ArgsT>, ...args: ArgsT): Promise<void>;
+  /**
+   * Resolves every storage key (one per storage tier) the given arguments cache under.
+   * Useful for debugging and for cache inspection tooling.
+   *
+   * @template ArgsT - Argument tuple the entry was cached under
+   * @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+   * @param {ArgsT} args - Arguments identifying the entry
+   * @returns {Promise<string[]>} The resolved storage keys
+   */
+  resolveKeys<ArgsT extends unknown[] = any[]>(options: CacheTypes.Options<any, ArgsT>, ...args: ArgsT): Promise<string[]>;
+  /**
+   * Merges the configured defaults into per-function options and translates the
+   * Vercube `storage` option into the key base the storage adapter routes on.
+   *
+   * @template T - Return type of the cached function
+   * @template ArgsT - Argument tuple of the cached function
+   * @param {CacheTypes.Options<T, ArgsT>} options - Per-function cache options
+   * @returns {CacheOptions<T, ArgsT>} Options understood by the caching engine
+   * @protected
+   */
+  protected resolveOptions<T, ArgsT extends unknown[]>(options: CacheTypes.Options<T, ArgsT>): CacheOptions<T, ArgsT>;
+  /**
+   * Drops keys whose value is `undefined`, so that an explicitly passed
+   * `undefined` never shadows a configured default with a missing value.
+   *
+   * @template T - Shape of the option object
+   * @param {T} options - Options to clean up
+   * @returns {Partial<T>} The options without undefined values
+   * @protected
+   */
+  protected stripUndefined<T extends object>(options: T): Partial<T>;
+  /**
+   * Installs the storage adapter into the caching engine.
+   * Called automatically with the `@Init()` decorator.
+   *
+   * @returns {void}
+   * @protected
+   */
+  protected init(): void;
+}
+//#endregion
+//#region src/Decorators/Cache.d.ts
+/**
+ * Decorator implementation that replaces the decorated method with a cached
+ * version of itself.
+ *
+ * The wrapper is built lazily on the first call so that storages mounted after
+ * the container has been flushed - and defaults configured during bootstrap -
+ * are still picked up.
+ */
+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 */
+  protected fOriginalMethod: ((...args: unknown[]) => unknown) | null;
+  /** Whether the method lived on the instance itself rather than on the prototype */
+  protected fOwnMethod: boolean;
+  /**
+   * Replaces the decorated method with its cached counterpart.
+   *
+   * @returns {void}
+   */
+  created(): void;
+  /**
+   * Drops the cached wrapper and puts the original method back in place.
+   *
+   * A method defined on the instance itself (a class field holding a function)
+   * is written back, while a prototype method is simply uncovered by removing
+   * the wrapper the decorator added to the instance.
+   *
+   * @returns {void}
+   */
+  destroyed(): void;
+}
+/**
+ * Caches the result of the decorated method.
+ *
+ * The cache key is derived from the method's arguments, so every distinct set of
+ * arguments gets its own entry. Concurrent calls for the same key are coalesced
+ * into a single execution, and entries are automatically dropped when the method
+ * body or its cache options change.
+ *
+ * The decorated method gains three helpers, keyed exactly like the cached calls:
+ * `resolveKeys(...args)`, `invalidate(...args)` and `expire(...args)`.
+ *
+ * @param {CacheTypes.DecoratorOptions} [options] - Cache options for this method
+ * @returns {Function} The method decorator
+ *
+ * @example
+ * ```ts
+ * class UsersService {
+ *   @Cache({ maxAge: 60, swr: true, staleMaxAge: 300, storage: 'redis' })
+ *   public async getUser(id: string): Promise<User> {
+ *     return this.database.findUser(id);
+ *   }
+ * }
+ *
+ * await usersService.getUser('123');
+ * await (usersService.getUser as CacheTypes.CachedMethod<[string], User>).invalidate('123');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // arguments that are not safely hashable (Request, streams, class instances)
+ * // should be projected into an explicit key
+ * class ReportsController {
+ *   @Cache({ maxAge: 300, getKey: (range: DateRange) => `${range.from}-${range.to}` })
+ *   public async report(range: DateRange): Promise<Report> {
+ *     return this.reports.build(range);
+ *   }
+ * }
+ * ```
+ */
+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 {
+  /**
+   * The original error that caused this cache error
+   */
+  readonly cause?: Error;
+  /**
+   * The cache operation that failed
+   */
+  readonly operation: string;
+  /**
+   * Additional metadata about the error (non-sensitive)
+   */
+  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 };

package/dist/index.mjs

@@ -0,0 +1,461 @@
+import { BaseDecorator, Container, Init, Inject, InjectOptional, createDecorator } from "@vercube/di";
+import { hash } from "ohash";
+import { Logger } from "@vercube/logger";
+import { StorageManager } from "@vercube/storage";
+import { defineCachedFunction, expireCache, invalidateCache, resolveCacheKeys, setStorage, useStorage } from "ocache";
+import { MemoryStorage } from "@vercube/storage/drivers/MemoryStorage";
+//#region src/Errors/CacheError.ts
+/**
+* Custom error class for cache-related errors.
+* Wraps underlying cache/storage errors with standardized error messages.
+*/
+var CacheError = class CacheError extends Error {
+	/**
+	* The original error that caused this cache error
+	*/
+	cause;
+	/**
+	* The cache operation that failed
+	*/
+	operation;
+	/**
+	* Additional metadata about the error (non-sensitive)
+	*/
+	metadata;
+	constructor(message, operation, cause, metadata) {
+		super(message);
+		this.name = "CacheError";
+		this.operation = operation;
+		this.cause = cause;
+		this.metadata = metadata;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, CacheError);
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.140.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);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/Services/CacheStorageAdapter.ts
+/**
+* Prefix every cache key starts with. The segment that follows it (when present)
+* is the name of the storage mounted in {@link StorageManager} that backs the entry.
+*
+* 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.
+*/
+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
+*/
+function cacheBaseForStorage(storage) {
+	if (storage?.includes(":")) throw new CacheError("Storage name used for caching must not contain a colon", "cacheBaseForStorage", void 0, { storage });
+	return storage && storage !== "default" ? `${CACHE_BASE_PREFIX}/${storage}` : CACHE_BASE_PREFIX;
+}
+/**
+* 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
+*/
+function storageNameFromCacheKey(key) {
+	const separatorIndex = key.indexOf(":");
+	const base = separatorIndex === -1 ? key : key.slice(0, separatorIndex);
+	if (!base.startsWith(`/cache/`)) return "default";
+	return base.slice(7) || "default";
+}
+/**
+* Bridges the caching engine onto the Vercube {@link StorageManager}.
+*
+* The cache module owns no storage of its own - every entry lives in a storage
+* mounted in `@vercube/storage`, so a cache can be backed by memory, S3 or any
+* other driver simply by mounting it, and the very same entries are visible
+* through the regular storage API.
+*
+* Every cache key carries the name of the storage it belongs to in its base
+* segment, so a single adapter instance serves cached functions that live in
+* different storages - and even ones that span several of them at once.
+*
+* A cached function may point at a storage that has not been mounted; in that
+* case a {@link MemoryStorage} is mounted under that name on first use so that
+* caching works with zero configuration. Mounting the name yourself - before or
+* after - is what swaps the backend for a real one.
+*/
+var CacheStorageAdapter = class {
+	/** Storage manager holding every mounted storage */
+	gStorageManager;
+	/** Logger instance */
+	gLogger;
+	/** In-flight auto-mounts, keyed by storage name, so concurrent calls share one storage */
+	fMounting = /* @__PURE__ */ new Map();
+	/**
+	* Reads a cache entry from the storage its key points at.
+	*
+	* @template T - Type of the stored entry
+	* @param {string} key - Full cache key, including the storage base prefix
+	* @returns {Promise<T | null>} The stored entry, or null when it is absent
+	*/
+	async get(key) {
+		return await (await this.resolveStorage(key)).getItem(key) ?? null;
+	}
+	/**
+	* Writes a cache entry to the storage its key points at.
+	*
+	* The caching engine signals a deletion by writing `null`, which is mapped onto
+	* the storage's delete operation so that no empty entries are left behind.
+	*
+	* @template T - Type of the value to store
+	* @param {string} key - Full cache key, including the storage base prefix
+	* @param {T} value - Entry to store, or null to remove it
+	* @param {{ ttl?: number }} [opts] - Storage hints, `ttl` in seconds
+	* @returns {Promise<void>} Resolves once the write is complete
+	*/
+	async set(key, value, opts) {
+		const storage = await this.resolveStorage(key);
+		if (value === null || value === void 0) {
+			await storage.deleteItem(key);
+			return;
+		}
+		await storage.setItem(key, value, opts);
+	}
+	/**
+	* Resolves the mounted storage a cache key belongs to, mounting an in-memory
+	* one under that name when nothing has been mounted yet.
+	*
+	* @param {string} key - Full cache key, including the storage base prefix
+	* @returns {Promise<Storage>} The storage backing that key
+	* @protected
+	*/
+	async resolveStorage(key) {
+		const manager = this.gStorageManager;
+		if (!manager) throw new CacheError("StorageManager is not registered in the container - bind it so cached entries have a storage to live in", "resolveStorage", void 0, { key });
+		const name = storageNameFromCacheKey(key);
+		return manager.getStorage(name) ?? await this.mountFallback(manager, name);
+	}
+	/**
+	* Mounts an in-memory storage under the given name, so that a cached function
+	* pointing at a storage nobody mounted still works.
+	*
+	* @param {StorageManager} manager - Storage manager to mount into
+	* @param {string} name - Name of the storage to mount
+	* @returns {Promise<Storage>} The freshly mounted storage
+	* @protected
+	*/
+	async mountFallback(manager, name) {
+		const pending = this.fMounting.get(name);
+		if (pending) return pending;
+		const mounting = (async () => {
+			await manager.mount({
+				name,
+				storage: MemoryStorage
+			});
+			const storage = manager.getStorage(name);
+			if (!storage) throw new CacheError("Unable to mount a fallback cache storage", "mountFallback", void 0, { storage: name });
+			await storage.initialize(void 0);
+			this.gLogger?.warn(`Vercube/CacheStorageAdapter::storage "${name}" was not mounted, an in-memory one has been mounted automatically`);
+			return storage;
+		})();
+		this.fMounting.set(name, mounting);
+		mounting.catch(() => void 0).finally(() => {
+			if (this.fMounting.get(name) === mounting) this.fMounting.delete(name);
+		});
+		return mounting;
+	}
+};
+__decorate([InjectOptional(StorageManager)], CacheStorageAdapter.prototype, "gStorageManager", void 0);
+__decorate([InjectOptional(Logger)], CacheStorageAdapter.prototype, "gLogger", void 0);
+//#endregion
+//#region src/Services/CacheManager.ts
+/**
+* Central entry point of the cache module.
+*
+* The CacheManager owns the wiring between the caching engine and the storages
+* mounted in `@vercube/storage`, holds the application wide defaults and exposes
+* the imperative API used both directly and by the `@Cache()` decorator.
+*
+* @example
+* ```ts
+* container.bind(CacheManager);
+*
+* const cache = container.get(CacheManager);
+* cache.configure({ maxAge: 60, swr: true, staleMaxAge: 300, storage: 'cache' });
+*
+* const getUser = cache.cached((id: string) => db.users.find(id), { name: 'getUser' });
+*
+* await getUser('123');            // resolves and stores
+* await getUser('123');            // served from cache
+* await getUser.invalidate('123'); // drops the entry
+* ```
+*/
+var CacheManager = class {
+	/** Container instance */
+	gContainer;
+	/** Logger instance */
+	gLogger;
+	/** Application wide defaults applied to every cached function */
+	fDefaults = {};
+	/** Storage adapter bridging the caching engine onto the mounted storages */
+	fAdapter = null;
+	/**
+	* Returns the storage adapter this manager installed into the caching engine.
+	*
+	* @returns {CacheStorageAdapter | null} The adapter, or null before initialization
+	*/
+	get adapter() {
+		return this.fAdapter;
+	}
+	/**
+	* Returns the currently configured defaults.
+	*
+	* @returns {CacheTypes.Defaults} A copy of the active defaults
+	*/
+	get defaults() {
+		return { ...this.fDefaults };
+	}
+	/**
+	* Sets the application wide cache defaults. Values passed per cached function
+	* always win over these. Calling it repeatedly merges into the existing defaults.
+	*
+	* @param {CacheTypes.Defaults} defaults - Defaults to apply to every cached function
+	* @returns {void}
+	*/
+	configure(defaults) {
+		this.fDefaults = {
+			...this.fDefaults,
+			...this.stripUndefined(defaults)
+		};
+	}
+	/**
+	* Wraps a function with caching.
+	*
+	* The returned function keeps the original signature and adds `resolveKeys()`,
+	* `invalidate()` and `expire()` helpers keyed exactly like the cached calls, so
+	* no cache key ever has to be rebuilt by hand.
+	*
+	* @template T - Return type of the wrapped function
+	* @template ArgsT - Argument tuple of the wrapped function
+	* @param {(...args: ArgsT) => T | Promise<T>} fn - The function to cache
+	* @param {CacheTypes.Options<T, ArgsT>} [options] - Per-function cache options
+	* @returns {CacheTypes.CachedFunction<T, ArgsT>} The cached function
+	*/
+	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));
+	}
+	/**
+	* Removes cached entries for the given arguments from every storage tier.
+	*
+	* Pass the same options (`name`, `group`, `storage`, `getKey`) the entry was
+	* cached with so the very same keys are resolved.
+	*
+	* @template ArgsT - Argument tuple the entry was cached under
+	* @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+	* @param {ArgsT} args - Arguments identifying the entry
+	* @returns {Promise<void>} Resolves once every tier has been cleared
+	*/
+	async invalidate(options, ...args) {
+		await invalidateCache({
+			options: this.resolveOptions(options),
+			args
+		});
+	}
+	/**
+	* Marks cached entries as stale without removing them.
+	*
+	* With `swr` enabled the stale value keeps being served (within `staleMaxAge`)
+	* while the next access refreshes it in the background; without it, the next
+	* call re-resolves before returning.
+	*
+	* @template ArgsT - Argument tuple the entry was cached under
+	* @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+	* @param {ArgsT} args - Arguments identifying the entry
+	* @returns {Promise<void>} Resolves once every tier has been marked
+	*/
+	async expire(options, ...args) {
+		await expireCache({
+			options: this.resolveOptions(options),
+			args
+		});
+	}
+	/**
+	* Resolves every storage key (one per storage tier) the given arguments cache under.
+	* Useful for debugging and for cache inspection tooling.
+	*
+	* @template ArgsT - Argument tuple the entry was cached under
+	* @param {CacheTypes.Options<any, ArgsT>} options - Options identifying the cached function
+	* @param {ArgsT} args - Arguments identifying the entry
+	* @returns {Promise<string[]>} The resolved storage keys
+	*/
+	async resolveKeys(options, ...args) {
+		return resolveCacheKeys({
+			options: this.resolveOptions(options),
+			args
+		});
+	}
+	/**
+	* Merges the configured defaults into per-function options and translates the
+	* Vercube `storage` option into the key base the storage adapter routes on.
+	*
+	* @template T - Return type of the cached function
+	* @template ArgsT - Argument tuple of the cached function
+	* @param {CacheTypes.Options<T, ArgsT>} options - Per-function cache options
+	* @returns {CacheOptions<T, ArgsT>} Options understood by the caching engine
+	* @protected
+	*/
+	resolveOptions(options) {
+		const { storage, ...rest } = {
+			...this.fDefaults,
+			...this.stripUndefined(options)
+		};
+		const storages = Array.isArray(storage) ? storage : [storage];
+		if (storages.length === 0) throw new CacheError("At least one storage must be given when caching", "resolveOptions", void 0, { name: rest.name });
+		const base = storages.map((name) => cacheBaseForStorage(name));
+		return {
+			...rest,
+			base: base.length === 1 ? base[0] : base
+		};
+	}
+	/**
+	* Drops keys whose value is `undefined`, so that an explicitly passed
+	* `undefined` never shadows a configured default with a missing value.
+	*
+	* @template T - Shape of the option object
+	* @param {T} options - Options to clean up
+	* @returns {Partial<T>} The options without undefined values
+	* @protected
+	*/
+	stripUndefined(options) {
+		return Object.fromEntries(Object.entries(options).filter(([, value]) => value !== void 0));
+	}
+	/**
+	* Installs the storage adapter into the caching engine.
+	* Called automatically with the `@Init()` decorator.
+	*
+	* @returns {void}
+	* @protected
+	*/
+	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);
+	}
+};
+__decorate([Inject(Container)], CacheManager.prototype, "gContainer", void 0);
+__decorate([InjectOptional(Logger)], CacheManager.prototype, "gLogger", void 0);
+__decorate([Init()], CacheManager.prototype, "init", null);
+//#endregion
+//#region src/Decorators/Cache.ts
+/**
+* Decorator implementation that replaces the decorated method with a cached
+* version of itself.
+*
+* The wrapper is built lazily on the first call so that storages mounted after
+* the container has been flushed - and defaults configured during bootstrap -
+* are still picked up.
+*/
+var CacheDecorator = class extends BaseDecorator {
+	/** Cache manager owning the caching engine wiring */
+	gCacheManager;
+	/** The untouched method, kept so it can be restored on destroy */
+	fOriginalMethod = null;
+	/** Whether the method lived on the instance itself rather than on the prototype */
+	fOwnMethod = false;
+	/**
+	* Replaces the decorated method with its cached counterpart.
+	*
+	* @returns {void}
+	*/
+	created() {
+		const original = this.instance[this.propertyName];
+		if (typeof original !== "function") throw new CacheError("@Cache() can only be applied to methods", "decorate", void 0, {
+			property: this.propertyName,
+			received: typeof original
+		});
+		this.fOriginalMethod = original;
+		this.fOwnMethod = Object.hasOwn(this.instance, this.propertyName);
+		const options = {
+			name: `${this.instance?.constructor?.name ?? "anonymous"}.${this.propertyName}`,
+			integrity: hash([original, this.options ?? {}]),
+			...this.options
+		};
+		let cached = null;
+		const resolveCached = () => {
+			cached ??= this.gCacheManager.cached((...args) => original.apply(this.instance, args), options);
+			return cached;
+		};
+		const wrapper = (...args) => resolveCached()(...args);
+		wrapper.resolveKeys = (...args) => resolveCached().resolveKeys(...args);
+		wrapper.invalidate = (...args) => resolveCached().invalidate(...args);
+		wrapper.expire = (...args) => resolveCached().expire(...args);
+		this.instance[this.propertyName] = wrapper;
+	}
+	/**
+	* Drops the cached wrapper and puts the original method back in place.
+	*
+	* A method defined on the instance itself (a class field holding a function)
+	* is written back, while a prototype method is simply uncovered by removing
+	* the wrapper the decorator added to the instance.
+	*
+	* @returns {void}
+	*/
+	destroyed() {
+		if (!this.fOriginalMethod) return;
+		if (this.fOwnMethod) this.instance[this.propertyName] = this.fOriginalMethod;
+		else delete this.instance[this.propertyName];
+		this.fOriginalMethod = null;
+		this.fOwnMethod = false;
+	}
+};
+__decorate([Inject(CacheManager)], CacheDecorator.prototype, "gCacheManager", void 0);
+/**
+* Caches the result of the decorated method.
+*
+* The cache key is derived from the method's arguments, so every distinct set of
+* arguments gets its own entry. Concurrent calls for the same key are coalesced
+* into a single execution, and entries are automatically dropped when the method
+* body or its cache options change.
+*
+* The decorated method gains three helpers, keyed exactly like the cached calls:
+* `resolveKeys(...args)`, `invalidate(...args)` and `expire(...args)`.
+*
+* @param {CacheTypes.DecoratorOptions} [options] - Cache options for this method
+* @returns {Function} The method decorator
+*
+* @example
+* ```ts
+* class UsersService {
+*   @Cache({ maxAge: 60, swr: true, staleMaxAge: 300, storage: 'redis' })
+*   public async getUser(id: string): Promise<User> {
+*     return this.database.findUser(id);
+*   }
+* }
+*
+* await usersService.getUser('123');
+* await (usersService.getUser as CacheTypes.CachedMethod<[string], User>).invalidate('123');
+* ```
+*
+* @example
+* ```ts
+* // arguments that are not safely hashable (Request, streams, class instances)
+* // should be projected into an explicit key
+* class ReportsController {
+*   @Cache({ maxAge: 300, getKey: (range: DateRange) => `${range.from}-${range.to}` })
+*   public async report(range: DateRange): Promise<Report> {
+*     return this.reports.build(range);
+*   }
+* }
+* ```
+*/
+function Cache(options = {}) {
+	return createDecorator(CacheDecorator, options);
+}
+//#endregion
+export { CACHE_BASE_PREFIX, Cache, CacheDecorator, CacheError, CacheManager, CacheStorageAdapter, cacheBaseForStorage, storageNameFromCacheKey };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vercube/cache",
+  "version": "1.2.0",
+  "description": "Cache module for Vercube framework",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercube/vercube.git",
+    "directory": "packages/cache"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@vercube/core": "1.2.0"
+  },
+  "dependencies": {
+    "ocache": "0.2.0",
+    "ohash": "2.0.12",
+    "@vercube/di": "1.2.0",
+    "@vercube/storage": "1.2.0",
+    "@vercube/logger": "1.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config ../../tsdown.config.ts --config-loader=unrun"
+  }
+}