@warlock.js/cache 4.0.171 → 4.1.1

package/esm/scoped-cache.mjs

@@ -0,0 +1,274 @@
+import { mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl } from "./utils.mjs";
+import { TaggedScopedCache } from "./tagged-scoped-cache.mjs";
+
+//#region ../../@warlock.js/cache/src/scoped-cache.ts
+/**
+* Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.
+*
+* **Role.** A `ScopedCache` is a stateless wrapper that prepends a fixed
+* prefix to every key and applies optional default `ttl` / `tags` to every
+* write. Stores nothing itself — every call forwards to the underlying
+* `source` (typically the `CacheManager`, but any `CacheDriver` works).
+*
+* **Responsibility.**
+* - Owns: prefix-prepending of keys, normalization of nested-scope prefixes,
+*   merging scope defaults into write options (`ttl`, `tags`), filtering
+*   `similar()` hits to its own scope, and exposing `.clear()` as a sugar
+*   for `removeNamespace(prefix)`.
+* - Does NOT own: actual storage, connection lifecycle, event listeners,
+*   driver selection, or tag-index bookkeeping (delegated to the source's
+*   tagged-cache machinery).
+*
+* Per-call options always win over scope defaults; tags merge additively
+* across (scope defaults + per-call) layers. Nested scopes inherit and may
+* override the parent's defaults — see {@link ScopedCache.namespace}.
+*
+* @example
+* const chat = cache.namespace(`chats.${id}`, { ttl: "30d" });
+*
+* await chat.set("messages.10", msg);          // 30d default
+* await chat.set("draft", d, { ttl: "1h" });   // per-call override
+* await chat.namespace("typing", { ttl: "5s" }).set("user.42", true);
+* await chat.clear();
+*/
+var ScopedCache = class ScopedCache {
+	/**
+	* Build a scope. Constructed via `cache.namespace(prefix, options)` —
+	* users never call this directly.
+	*/
+	constructor(source, prefix, defaults = {}) {
+		this.source = source;
+		this.prefix = parseCacheKey(prefix);
+		this.defaults = {
+			ttl: defaults.ttl,
+			tags: defaults.tags && defaults.tags.length > 0 ? [...defaults.tags] : void 0
+		};
+	}
+	/**
+	* Build a nested scope. The child's prefix is `parent.child`; child options
+	* override the parent's `ttl` and union into `tags`.
+	*
+	* @example
+	* const chat = cache.namespace("chats.10", { ttl: "30d" });
+	* const typing = chat.namespace("typing", { ttl: "5s" });
+	* // typing.prefix === "chats.10.typing"
+	*/
+	namespace(prefix, options = {}) {
+		const childPrefix = `${this.prefix}.${parseCacheKey(prefix)}`;
+		return new ScopedCache(this.source, childPrefix, {
+			ttl: options.ttl ?? this.defaults.ttl,
+			tags: mergeTagSets(this.defaults.tags, options.tags)
+		});
+	}
+	/**
+	* Return a one-shot tagged write handle. The handle's tags merge additively
+	* with scope-level defaults — final tag list per write is the union of
+	* (scope tags + handle tags + per-call tags), deduped.
+	*/
+	tags(tags) {
+		return new TaggedScopedCache(this, tags);
+	}
+	/**
+	* Wipe every entry under this scope's prefix. Sugar over
+	* `source.removeNamespace(prefix)` — siblings outside the scope are
+	* untouched.
+	*/
+	clear() {
+		return this.source.removeNamespace(this.prefix);
+	}
+	/**
+	* Read the value at the scoped key. Forwards to the source after prefixing.
+	*/
+	get(key) {
+		return this.source.get(this.scopedKey(key));
+	}
+	/**
+	* Check presence of the scoped key without fetching the value.
+	*/
+	has(key) {
+		return this.source.has(this.scopedKey(key));
+	}
+	/**
+	* Batch-read scoped keys. Each input key is prefixed before forwarding.
+	*/
+	many(keys) {
+		return this.source.many(keys.map((key) => this.scopedKey(key)));
+	}
+	/**
+	* Read-and-remove. Returns the value or `null`; the entry is gone after.
+	*/
+	pull(key) {
+		return this.source.pull(this.scopedKey(key));
+	}
+	/**
+	* Write the scoped key. Per-call `ttl`/`tags` win over scope defaults;
+	* `expiresAt` is preserved as-is (absolute deadlines are never overridden
+	* by the scope's relative-ttl default).
+	*/
+	set(key, value, ttlOrOptions) {
+		return this.source.set(this.scopedKey(key), value, this.mergeSetOptions(ttlOrOptions));
+	}
+	/**
+	* Batch-write under the scope. Caller's positional `ttl` wins; otherwise
+	* the scope default is parsed to seconds (since `setMany` accepts only a
+	* numeric ttl).
+	*/
+	setMany(items, ttl) {
+		const scoped = {};
+		for (const [key, value] of Object.entries(items)) scoped[this.scopedKey(key)] = value;
+		return this.source.setMany(scoped, ttl ?? this.scopeTtlSeconds());
+	}
+	/**
+	* Atomic create-or-skip on the scoped key. Throws when the underlying
+	* source has no `setNX` (driver-specific — Redis-only today).
+	*/
+	setNX(key, value, ttl) {
+		if (!this.source.setNX) throw new Error(`setNX is not supported by the underlying cache source: ${this.source.name}`);
+		return this.source.setNX(this.scopedKey(key), value, ttl ?? this.scopeTtlSeconds());
+	}
+	/**
+	* Permanent write (no expiration). Bypasses the scope's `ttl` default —
+	* `forever` always means forever, regardless of scope policy.
+	*/
+	forever(key, value) {
+		return this.source.forever(this.scopedKey(key), value);
+	}
+	/**
+	* Remove a single scoped key.
+	*/
+	remove(key) {
+		return this.source.remove(this.scopedKey(key));
+	}
+	/**
+	* Read-or-compute. Cache-miss writes pick up the scope's default `ttl`
+	* and `tags` unless the caller passed an options object that overrides.
+	*/
+	remember(key, ttlOrOptions, callback) {
+		return this.source.remember(this.scopedKey(key), this.mergeRememberOptions(ttlOrOptions), callback);
+	}
+	/**
+	* Stale-while-revalidate on the scoped key. Scope-level `tags` merge
+	* additively with `options.tags`; `freshTtl`/`staleTtl` always come from
+	* the caller (no scope-default precedence — the SWR shape is too
+	* specific to the call site to inherit).
+	*/
+	swr(key, options, callback) {
+		const merged = {
+			...options,
+			tags: mergeTagSets(this.defaults.tags, options.tags)
+		};
+		return this.source.swr(this.scopedKey(key), merged, callback);
+	}
+	/**
+	* Atomic counter increment on the scoped key. TTL is preserved by the
+	* underlying driver — scope ttl is only applied on first write via `set`.
+	*/
+	increment(key, value) {
+		return this.source.increment(this.scopedKey(key), value);
+	}
+	/**
+	* Atomic counter decrement on the scoped key. See {@link increment} for
+	* TTL semantics.
+	*/
+	decrement(key, value) {
+		return this.source.decrement(this.scopedKey(key), value);
+	}
+	/**
+	* Atomic read-modify-write. Falls back to the scope's `ttl` when the caller
+	* doesn't provide one; the source still keeps the existing entry's TTL on
+	* an update unless `options.ttl` is explicitly set.
+	*/
+	update(key, fn, options) {
+		return this.source.update(this.scopedKey(key), fn, { ttl: options?.ttl ?? this.defaults.ttl });
+	}
+	/**
+	* Shallow-merge a partial object into the scoped entry. Same TTL semantics
+	* as {@link update}.
+	*/
+	merge(key, partial, options) {
+		return this.source.merge(this.scopedKey(key), partial, { ttl: options?.ttl ?? this.defaults.ttl });
+	}
+	/**
+	* Return a list accessor bound to the scoped key. The accessor itself
+	* does its own read-mutate-write under the prefixed entry.
+	*/
+	list(key) {
+		return this.source.list(this.scopedKey(key));
+	}
+	/**
+	* Acquire a distributed lock on the scoped key. Caller's TTL wins; when
+	* the options form omits `ttl`, the scope default fills in.
+	*/
+	lock(key, ttlOrOptions, fn) {
+		if (typeof ttlOrOptions === "object" && ttlOrOptions !== null) {
+			const merged = {
+				...ttlOrOptions,
+				ttl: ttlOrOptions.ttl ?? this.defaults.ttl ?? ttlOrOptions.ttl
+			};
+			return this.source.lock(this.scopedKey(key), merged, fn);
+		}
+		return this.source.lock(this.scopedKey(key), ttlOrOptions, fn);
+	}
+	/**
+	* Similarity retrieval, scope-isolated. Hits whose keys fall outside this
+	* scope are filtered out before the result is returned. `topK` applies to
+	* the underlying retrieval — when the scope contains fewer than `topK`
+	* matches but other scopes do, the caller will see fewer hits than `topK`.
+	*/
+	async similar(vector, options) {
+		const hits = await this.source.similar(vector, options);
+		const parsedPrefix = this.source.parseKey(this.prefix);
+		return hits.filter((hit) => hit.key === parsedPrefix || hit.key.startsWith(parsedPrefix + "."));
+	}
+	/**
+	* Build the source-side key by prepending the scope prefix. Object keys
+	* are normalized via {@link parseCacheKey} first so they compose with the
+	* prefix as plain dot-strings.
+	*/
+	scopedKey(key) {
+		const keyString = typeof key === "string" ? key : parseCacheKey(key);
+		if (!keyString) return this.prefix;
+		return `${this.prefix}.${keyString}`;
+	}
+	/**
+	* Coerce the polymorphic 3rd `set` argument into a {@link CacheSetOptions}
+	* with scope defaults filled in. Per-call values always win; tags merge
+	* additively. `expiresAt` is preserved without injecting the scope's `ttl`
+	* default (absolute deadlines override relative ones).
+	*/
+	mergeSetOptions(input) {
+		const options = normalizeToOptions(input);
+		const ttl = options.ttl ?? (options.expiresAt === void 0 ? this.defaults.ttl : void 0);
+		const tags = mergeTagSets(this.defaults.tags, options.tags);
+		const merged = { ...options };
+		if (ttl !== void 0) merged.ttl = ttl;
+		if (tags !== void 0) merged.tags = tags;
+		return merged;
+	}
+	/**
+	* Same merge as {@link mergeSetOptions} but for the `remember()` shape
+	* ({@link RememberOptions} — no `expiresAt`).
+	*/
+	mergeRememberOptions(input) {
+		const options = normalizeToRememberOptions(input);
+		const ttl = options.ttl ?? this.defaults.ttl;
+		const tags = mergeTagSets(this.defaults.tags, options.tags);
+		const merged = { ...options };
+		if (ttl !== void 0) merged.ttl = ttl;
+		if (tags !== void 0) merged.tags = tags;
+		return merged;
+	}
+	/**
+	* Convert the scope's default `ttl` (which may be a duration string) into
+	* seconds, for the few methods (`setMany`, `setNX`) that accept only a
+	* numeric ttl.
+	*/
+	scopeTtlSeconds() {
+		if (this.defaults.ttl === void 0) return;
+		return parseTtl(this.defaults.ttl);
+	}
+};
+
+//#endregion
+export { ScopedCache };
+//# sourceMappingURL=scoped-cache.mjs.map

package/esm/scoped-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-cache.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/scoped-cache.ts"],"sourcesContent":["import { TaggedScopedCache } from \"./tagged-scoped-cache\";\nimport type {\n  CacheDriver,\n  CacheKey,\n  CacheListAccessor,\n  CacheNamespaceOptions,\n  CacheSetOptions,\n  CacheSimilarHit,\n  CacheSimilarOptions,\n  CacheSwrOptions,\n  CacheTtl,\n  LockOptions,\n  LockOutcome,\n  RememberOptions,\n  ScopedCacheContract,\n  TaggedScopedCacheContract,\n} from \"./types\";\nimport {\n  mergeTagSets,\n  normalizeToOptions,\n  normalizeToRememberOptions,\n  parseCacheKey,\n  parseTtl,\n} from \"./utils\";\n\n/**\n * Scoped view over a cache source. Returned by `cache.namespace(prefix, options?)`.\n *\n * **Role.** A `ScopedCache` is a stateless wrapper that prepends a fixed\n * prefix to every key and applies optional default `ttl` / `tags` to every\n * write. Stores nothing itself — every call forwards to the underlying\n * `source` (typically the `CacheManager`, but any `CacheDriver` works).\n *\n * **Responsibility.**\n * - Owns: prefix-prepending of keys, normalization of nested-scope prefixes,\n *   merging scope defaults into write options (`ttl`, `tags`), filtering\n *   `similar()` hits to its own scope, and exposing `.clear()` as a sugar\n *   for `removeNamespace(prefix)`.\n * - Does NOT own: actual storage, connection lifecycle, event listeners,\n *   driver selection, or tag-index bookkeeping (delegated to the source's\n *   tagged-cache machinery).\n *\n * Per-call options always win over scope defaults; tags merge additively\n * across (scope defaults + per-call) layers. Nested scopes inherit and may\n * override the parent's defaults — see {@link ScopedCache.namespace}.\n *\n * @example\n * const chat = cache.namespace(`chats.${id}`, { ttl: \"30d\" });\n *\n * await chat.set(\"messages.10\", msg);          // 30d default\n * await chat.set(\"draft\", d, { ttl: \"1h\" });   // per-call override\n * await chat.namespace(\"typing\", { ttl: \"5s\" }).set(\"user.42\", true);\n * await chat.clear();\n */\nexport class ScopedCache implements ScopedCacheContract {\n  /**\n   * Fully-qualified prefix prepended to every key handled by this scope.\n   * Normalized through {@link parseCacheKey} on construction so colon-form\n   * input (`\"chats:10\"`) and trailing dots compose cleanly with nested scopes.\n   */\n  public readonly prefix: string;\n\n  /**\n   * Underlying cache source. Public-readonly so co-located helpers\n   * (`TaggedScopedCache`) can delegate without ceremony — not part of the\n   * stable consumer API.\n   *\n   * @internal\n   */\n  public readonly source: CacheDriver<any, any>;\n\n  /**\n   * Defaults applied to every write through this scope. Per-call options\n   * override `ttl`; `tags` merge additively across layers.\n   *\n   * @internal\n   */\n  public readonly defaults: CacheNamespaceOptions;\n\n  /**\n   * Build a scope. Constructed via `cache.namespace(prefix, options)` —\n   * users never call this directly.\n   */\n  public constructor(\n    source: CacheDriver<any, any>,\n    prefix: string,\n    defaults: CacheNamespaceOptions = {},\n  ) {\n    this.source = source;\n    this.prefix = parseCacheKey(prefix);\n    this.defaults = {\n      ttl: defaults.ttl,\n      tags: defaults.tags && defaults.tags.length > 0 ? [...defaults.tags] : undefined,\n    };\n  }\n\n  /**\n   * Build a nested scope. The child's prefix is `parent.child`; child options\n   * override the parent's `ttl` and union into `tags`.\n   *\n   * @example\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\n   * const typing = chat.namespace(\"typing\", { ttl: \"5s\" });\n   * // typing.prefix === \"chats.10.typing\"\n   */\n  public namespace(prefix: string, options: CacheNamespaceOptions = {}): ScopedCacheContract {\n    const childPrefix = `${this.prefix}.${parseCacheKey(prefix)}`;\n\n    return new ScopedCache(this.source, childPrefix, {\n      ttl: options.ttl ?? this.defaults.ttl,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    });\n  }\n\n  /**\n   * Return a one-shot tagged write handle. The handle's tags merge additively\n   * with scope-level defaults — final tag list per write is the union of\n   * (scope tags + handle tags + per-call tags), deduped.\n   */\n  public tags(tags: string[]): TaggedScopedCacheContract {\n    return new TaggedScopedCache(this, tags);\n  }\n\n  /**\n   * Wipe every entry under this scope's prefix. Sugar over\n   * `source.removeNamespace(prefix)` — siblings outside the scope are\n   * untouched.\n   */\n  public clear(): Promise<void> {\n    return this.source.removeNamespace(this.prefix);\n  }\n\n  /**\n   * Read the value at the scoped key. Forwards to the source after prefixing.\n   */\n  public get<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.get<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Check presence of the scoped key without fetching the value.\n   */\n  public has(key: CacheKey): Promise<boolean> {\n    return this.source.has(this.scopedKey(key));\n  }\n\n  /**\n   * Batch-read scoped keys. Each input key is prefixed before forwarding.\n   */\n  public many(keys: CacheKey[]): Promise<any[]> {\n    return this.source.many(keys.map((key) => this.scopedKey(key)));\n  }\n\n  /**\n   * Read-and-remove. Returns the value or `null`; the entry is gone after.\n   */\n  public pull<T = any>(key: CacheKey): Promise<T | null> {\n    return this.source.pull<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Write the scoped key. Per-call `ttl`/`tags` win over scope defaults;\n   * `expiresAt` is preserved as-is (absolute deadlines are never overridden\n   * by the scope's relative-ttl default).\n   */\n  public set(\n    key: CacheKey,\n    value: any,\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\n  ): Promise<any> {\n    return this.source.set(this.scopedKey(key), value, this.mergeSetOptions(ttlOrOptions));\n  }\n\n  /**\n   * Batch-write under the scope. Caller's positional `ttl` wins; otherwise\n   * the scope default is parsed to seconds (since `setMany` accepts only a\n   * numeric ttl).\n   */\n  public setMany(items: Record<string, any>, ttl?: number): Promise<void> {\n    const scoped: Record<string, any> = {};\n\n    for (const [key, value] of Object.entries(items)) {\n      scoped[this.scopedKey(key)] = value;\n    }\n\n    return this.source.setMany(scoped, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Atomic create-or-skip on the scoped key. Throws when the underlying\n   * source has no `setNX` (driver-specific — Redis-only today).\n   */\n  public setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean> {\n    if (!this.source.setNX) {\n      throw new Error(\n        `setNX is not supported by the underlying cache source: ${this.source.name}`,\n      );\n    }\n\n    return this.source.setNX(this.scopedKey(key), value, ttl ?? this.scopeTtlSeconds());\n  }\n\n  /**\n   * Permanent write (no expiration). Bypasses the scope's `ttl` default —\n   * `forever` always means forever, regardless of scope policy.\n   */\n  public forever<T = any>(key: CacheKey, value: T): Promise<T> {\n    return this.source.forever<T>(this.scopedKey(key), value);\n  }\n\n  /**\n   * Remove a single scoped key.\n   */\n  public remove(key: CacheKey): Promise<void> {\n    return this.source.remove(this.scopedKey(key));\n  }\n\n  /**\n   * Read-or-compute. Cache-miss writes pick up the scope's default `ttl`\n   * and `tags` unless the caller passed an options object that overrides.\n   */\n  public remember<T = any>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | RememberOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    return this.source.remember<T>(\n      this.scopedKey(key),\n      this.mergeRememberOptions(ttlOrOptions),\n      callback,\n    );\n  }\n\n  /**\n   * Stale-while-revalidate on the scoped key. Scope-level `tags` merge\n   * additively with `options.tags`; `freshTtl`/`staleTtl` always come from\n   * the caller (no scope-default precedence — the SWR shape is too\n   * specific to the call site to inherit).\n   */\n  public swr<T = any>(\n    key: CacheKey,\n    options: CacheSwrOptions,\n    callback: () => Promise<T>,\n  ): Promise<T> {\n    const merged: CacheSwrOptions = {\n      ...options,\n      tags: mergeTagSets(this.defaults.tags, options.tags),\n    };\n\n    return this.source.swr<T>(this.scopedKey(key), merged, callback);\n  }\n\n  /**\n   * Atomic counter increment on the scoped key. TTL is preserved by the\n   * underlying driver — scope ttl is only applied on first write via `set`.\n   */\n  public increment(key: CacheKey, value?: number): Promise<number> {\n    return this.source.increment(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic counter decrement on the scoped key. See {@link increment} for\n   * TTL semantics.\n   */\n  public decrement(key: CacheKey, value?: number): Promise<number> {\n    return this.source.decrement(this.scopedKey(key), value);\n  }\n\n  /**\n   * Atomic read-modify-write. Falls back to the scope's `ttl` when the caller\n   * doesn't provide one; the source still keeps the existing entry's TTL on\n   * an update unless `options.ttl` is explicitly set.\n   */\n  public update<T = any>(\n    key: CacheKey,\n    fn: (current: T | null) => T | null | Promise<T | null>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T | null> {\n    return this.source.update<T>(this.scopedKey(key), fn, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Shallow-merge a partial object into the scoped entry. Same TTL semantics\n   * as {@link update}.\n   */\n  public merge<T extends Record<string, any> = Record<string, any>>(\n    key: CacheKey,\n    partial: Partial<T>,\n    options?: { ttl?: CacheTtl },\n  ): Promise<T> {\n    return this.source.merge<T>(this.scopedKey(key), partial, {\n      ttl: options?.ttl ?? this.defaults.ttl,\n    });\n  }\n\n  /**\n   * Return a list accessor bound to the scoped key. The accessor itself\n   * does its own read-mutate-write under the prefixed entry.\n   */\n  public list<T = any>(key: CacheKey): CacheListAccessor<T> {\n    return this.source.list<T>(this.scopedKey(key));\n  }\n\n  /**\n   * Acquire a distributed lock on the scoped key. Caller's TTL wins; when\n   * the options form omits `ttl`, the scope default fills in.\n   */\n  public lock<T>(\n    key: CacheKey,\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\n    fn: () => Promise<T>,\n  ): Promise<LockOutcome<T>> {\n    if (typeof ttlOrOptions === \"object\" && ttlOrOptions !== null) {\n      const merged: Omit<LockOptions, \"driver\"> = {\n        ...ttlOrOptions,\n        ttl: ttlOrOptions.ttl ?? this.defaults.ttl ?? ttlOrOptions.ttl,\n      };\n\n      // The third coalesce is intentional — when both caller and scope omit\n      // the TTL, we still pass the original (undefined) through so the source\n      // raises its own validation error rather than us swallowing it silently.\n      return this.source.lock<T>(this.scopedKey(key), merged, fn);\n    }\n\n    return this.source.lock<T>(this.scopedKey(key), ttlOrOptions, fn);\n  }\n\n  /**\n   * Similarity retrieval, scope-isolated. Hits whose keys fall outside this\n   * scope are filtered out before the result is returned. `topK` applies to\n   * the underlying retrieval — when the scope contains fewer than `topK`\n   * matches but other scopes do, the caller will see fewer hits than `topK`.\n   */\n  public async similar<T = any>(\n    vector: number[],\n    options: CacheSimilarOptions,\n  ): Promise<CacheSimilarHit<T>[]> {\n    const hits = await this.source.similar<T>(vector, options);\n    const parsedPrefix = this.source.parseKey(this.prefix);\n\n    return hits.filter(\n      (hit) => hit.key === parsedPrefix || hit.key.startsWith(parsedPrefix + \".\"),\n    );\n  }\n\n  /**\n   * Build the source-side key by prepending the scope prefix. Object keys\n   * are normalized via {@link parseCacheKey} first so they compose with the\n   * prefix as plain dot-strings.\n   */\n  protected scopedKey(key: CacheKey): string {\n    const keyString = typeof key === \"string\" ? key : parseCacheKey(key);\n\n    if (!keyString) {\n      return this.prefix;\n    }\n\n    return `${this.prefix}.${keyString}`;\n  }\n\n  /**\n   * Coerce the polymorphic 3rd `set` argument into a {@link CacheSetOptions}\n   * with scope defaults filled in. Per-call values always win; tags merge\n   * additively. `expiresAt` is preserved without injecting the scope's `ttl`\n   * default (absolute deadlines override relative ones).\n   */\n  protected mergeSetOptions(\n    input?: CacheTtl | CacheSetOptions,\n  ): CacheSetOptions | undefined {\n    const options = normalizeToOptions(input);\n    const ttl =\n      options.ttl ?? (options.expiresAt === undefined ? this.defaults.ttl : undefined);\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: CacheSetOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Same merge as {@link mergeSetOptions} but for the `remember()` shape\n   * ({@link RememberOptions} — no `expiresAt`).\n   */\n  protected mergeRememberOptions(\n    input: CacheTtl | RememberOptions,\n  ): CacheTtl | RememberOptions {\n    const options = normalizeToRememberOptions(input);\n    const ttl = options.ttl ?? this.defaults.ttl;\n    const tags = mergeTagSets(this.defaults.tags, options.tags);\n\n    const merged: RememberOptions = { ...options };\n\n    if (ttl !== undefined) {\n      merged.ttl = ttl;\n    }\n\n    if (tags !== undefined) {\n      merged.tags = tags;\n    }\n\n    return merged;\n  }\n\n  /**\n   * Convert the scope's default `ttl` (which may be a duration string) into\n   * seconds, for the few methods (`setMany`, `setNX`) that accept only a\n   * numeric ttl.\n   */\n  protected scopeTtlSeconds(): number | undefined {\n    if (this.defaults.ttl === undefined) {\n      return undefined;\n    }\n\n    return parseTtl(this.defaults.ttl);\n  }\n}\n"],"mappings":"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"}

package/esm/tagged-cache.d.mts

@@ -0,0 +1,89 @@
+import { CacheDriver, CacheKey, CacheSetOptions, CacheTtl, TaggedCacheDriver } from "./types.mjs";
+
+//#region ../../@warlock.js/cache/src/tagged-cache.d.ts
+/**
+ * Tagged Cache Wrapper
+ * Wraps a cache driver to automatically manage tag relationships
+ */
+declare class TaggedCache implements TaggedCacheDriver {
+  /**
+   * The tags associated with this tagged cache instance
+   */
+  protected cacheTags: string[];
+  /**
+   * The underlying cache driver
+   */
+  protected driver: CacheDriver<any, any>;
+  /**
+   * Constructor
+   */
+  constructor(tags: string[], driver: CacheDriver<any, any>);
+  /**
+   * Get the tag key prefix for storing tag-key relationships
+   */
+  protected tagKey(tag: string): string;
+  /**
+   * Store tag-key relationship
+   */
+  protected storeTaggedKey(key: string): Promise<void>;
+  /**
+   * Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`
+   * when tags are passed inline through `CacheSetOptions.tags`.
+   *
+   * @internal — public for cross-class use within this package; not part of the
+   * stable consumer API.
+   */
+  storeTagRelationship(parsedKey: string): Promise<void>;
+  /**
+   * Get all keys associated with tags
+   */
+  protected getTaggedKeys(): Promise<Set<string>>;
+  /**
+   * {@inheritdoc}
+   */
+  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  get(key: CacheKey): Promise<any | null>;
+  /**
+   * {@inheritdoc}
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * Invalidate (clear) all keys associated with the current tags
+   */
+  invalidate(): Promise<void>;
+  /**
+   * Flush all keys associated with the current tags
+   * @deprecated Use invalidate() instead for better semantics
+   */
+  flush(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  has(key: CacheKey): Promise<boolean>;
+  /**
+   * {@inheritdoc}
+   */
+  remember(key: CacheKey, ttl: number, callback: () => Promise<any>): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  pull(key: CacheKey): Promise<any | null>;
+  /**
+   * {@inheritdoc}
+   */
+  forever(key: CacheKey, value: any): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  increment(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  decrement(key: CacheKey, value?: number): Promise<number>;
+}
+//#endregion
+export { TaggedCache };
+//# sourceMappingURL=tagged-cache.d.mts.map

package/esm/tagged-cache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-cache.d.mts","names":[],"sources":["../../../../../@warlock.js/cache/src/tagged-cache.ts"],"mappings":";;;;;AAYA;;cAAa,WAAA,YAAuB,iBAAA;EAShB;;;EAAA,UALR,SAAA;EAmD+B;;;EAAA,UA9C/B,MAAA,EAAQ,WAAA;EAmEU;;;cA9DT,IAAA,YAAgB,MAAA,EAAQ,WAAA;EAmFlB;;;EAAA,UA3Ef,MAAA,CAAO,GAAA;EAsHK;;;EAAA,UA/GN,cAAA,CAAe,GAAA,WAAc,OAAA;EA0H1C;;;;;;;EA/GU,oBAAA,CAAqB,SAAA,WAAoB,OAAA;EAqKI;;;EAAA,UAtJ1C,aAAA,CAAA,GAAiB,OAAA,CAAQ,GAAA;EAvDP;;;EAyErB,GAAA,CACX,GAAA,EAAK,QAAA,EACL,KAAA,OACA,YAAA,GAAe,QAAA,GAAW,eAAA,GACzB,OAAA;;;;EAaU,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EApEvB;;;EA2EG,MAAA,CAAO,GAAA,EAAK,QAAA,GAAW,OAAA;EApES;;;EAsFhC,UAAA,CAAA,GAAc,OAAA;EA5DX;;;;EA8EH,KAAA,CAAA,GAAS,OAAA;EA3DpB;;;EAkEW,GAAA,CAAI,GAAA,EAAK,QAAA,GAAW,OAAA;EAhE/B;;;EAuEW,QAAA,CACX,GAAA,EAAK,QAAA,EACL,GAAA,UACA,QAAA,QAAgB,OAAA,QACf,OAAA;EA7Dc;;;EA6EJ,IAAA,CAAK,GAAA,EAAK,QAAA,GAAW,OAAA;EAtEd;;;EAmFP,OAAA,CAAQ,GAAA,EAAK,QAAA,EAAU,KAAA,QAAa,OAAA;EA/CpC;;;EAsDA,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;EA/CzC;;;EAiEJ,SAAA,CAAU,GAAA,EAAK,QAAA,EAAU,KAAA,YAAoB,OAAA;AAAA"}

package/esm/tagged-cache.mjs

@@ -0,0 +1,147 @@
+//#region ../../@warlock.js/cache/src/tagged-cache.ts
+/**
+* Tagged Cache Wrapper
+* Wraps a cache driver to automatically manage tag relationships
+*/
+var TaggedCache = class {
+	/**
+	* Constructor
+	*/
+	constructor(tags, driver) {
+		this.cacheTags = tags;
+		this.driver = driver;
+	}
+	/**
+	* Get the tag key prefix for storing tag-key relationships
+	*/
+	tagKey(tag) {
+		return `cache:tags:${tag}`;
+	}
+	/**
+	* Store tag-key relationship
+	*/
+	async storeTaggedKey(key) {
+		await this.storeTagRelationship(key);
+	}
+	/**
+	* Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`
+	* when tags are passed inline through `CacheSetOptions.tags`.
+	*
+	* @internal — public for cross-class use within this package; not part of the
+	* stable consumer API.
+	*/
+	async storeTagRelationship(parsedKey) {
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const keys = await this.driver.get(tagKey) || [];
+			if (!keys.includes(parsedKey)) {
+				keys.push(parsedKey);
+				await this.driver.set(tagKey, keys, Infinity);
+			}
+		}
+	}
+	/**
+	* Get all keys associated with tags
+	*/
+	async getTaggedKeys() {
+		const allKeys = /* @__PURE__ */ new Set();
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const keys = await this.driver.get(tagKey) || [];
+			for (const key of keys) allKeys.add(key);
+		}
+		return allKeys;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttlOrOptions) {
+		const parsedKey = this.driver.parseKey(key);
+		await this.driver.set(key, value, ttlOrOptions);
+		await this.storeTaggedKey(parsedKey);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		return this.driver.get(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.driver.parseKey(key);
+		await this.driver.remove(key);
+		for (const tag of this.cacheTags) {
+			const tagKey = this.tagKey(tag);
+			const updatedKeys = (await this.driver.get(tagKey) || []).filter((k) => k !== parsedKey);
+			await this.driver.set(tagKey, updatedKeys, Infinity);
+		}
+	}
+	/**
+	* Invalidate (clear) all keys associated with the current tags
+	*/
+	async invalidate() {
+		const keysToRemove = await this.getTaggedKeys();
+		for (const key of keysToRemove) await this.driver.remove(key);
+		for (const tag of this.cacheTags) await this.driver.remove(this.tagKey(tag));
+	}
+	/**
+	* Flush all keys associated with the current tags
+	* @deprecated Use invalidate() instead for better semantics
+	*/
+	async flush() {
+		return this.invalidate();
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async has(key) {
+		return this.driver.has(key);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remember(key, ttl, callback) {
+		const value = await this.get(key);
+		if (value !== null) return value;
+		const result = await callback();
+		await this.set(key, result, ttl);
+		return result;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async pull(key) {
+		const value = await this.get(key);
+		if (value !== null) await this.remove(key);
+		return value;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async forever(key, value) {
+		return this.set(key, value, Infinity);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async increment(key, value = 1) {
+		const current = await this.get(key) || 0;
+		if (typeof current !== "number") throw new Error(`Cannot increment non-numeric value for key: ${this.driver.parseKey(key)}`);
+		const newValue = current + value;
+		await this.set(key, newValue);
+		return newValue;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async decrement(key, value = 1) {
+		return this.increment(key, -value);
+	}
+};
+
+//#endregion
+export { TaggedCache };
+//# sourceMappingURL=tagged-cache.mjs.map

package/esm/tagged-cache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagged-cache.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/tagged-cache.ts"],"sourcesContent":["import type {\r\n  CacheDriver,\r\n  CacheKey,\r\n  CacheSetOptions,\r\n  CacheTtl,\r\n  TaggedCacheDriver,\r\n} from \"./types\";\r\n\r\n/**\r\n * Tagged Cache Wrapper\r\n * Wraps a cache driver to automatically manage tag relationships\r\n */\r\nexport class TaggedCache implements TaggedCacheDriver {\r\n  /**\r\n   * The tags associated with this tagged cache instance\r\n   */\r\n  protected cacheTags: string[];\r\n\r\n  /**\r\n   * The underlying cache driver\r\n   */\r\n  protected driver: CacheDriver<any, any>;\r\n\r\n  /**\r\n   * Constructor\r\n   */\r\n  public constructor(tags: string[], driver: CacheDriver<any, any>) {\r\n    this.cacheTags = tags;\r\n    this.driver = driver;\r\n  }\r\n\r\n  /**\r\n   * Get the tag key prefix for storing tag-key relationships\r\n   */\r\n  protected tagKey(tag: string): string {\r\n    return `cache:tags:${tag}`;\r\n  }\r\n\r\n  /**\r\n   * Store tag-key relationship\r\n   */\r\n  protected async storeTaggedKey(key: string): Promise<void> {\r\n    await this.storeTagRelationship(key);\r\n  }\r\n\r\n  /**\r\n   * Public alias of the tag-index writer. Called by `BaseCacheDriver.applyTags`\r\n   * when tags are passed inline through `CacheSetOptions.tags`.\r\n   *\r\n   * @internal — public for cross-class use within this package; not part of the\r\n   * stable consumer API.\r\n   */\r\n  public async storeTagRelationship(parsedKey: string): Promise<void> {\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      if (!keys.includes(parsedKey)) {\r\n        keys.push(parsedKey);\r\n        await this.driver.set(tagKey, keys, Infinity);\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all keys associated with tags\r\n   */\r\n  protected async getTaggedKeys(): Promise<Set<string>> {\r\n    const allKeys = new Set<string>();\r\n\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n\r\n      for (const key of keys) {\r\n        allKeys.add(key);\r\n      }\r\n    }\r\n\r\n    return allKeys;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    await this.driver.set(key, value, ttlOrOptions);\r\n\r\n    await this.storeTaggedKey(parsedKey);\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async get(key: CacheKey): Promise<any | null> {\r\n    return this.driver.get(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remove(key: CacheKey): Promise<void> {\r\n    const parsedKey = this.driver.parseKey(key);\r\n\r\n    // Remove the value\r\n    await this.driver.remove(key);\r\n\r\n    // Remove from all tag relationships\r\n    for (const tag of this.cacheTags) {\r\n      const tagKey = this.tagKey(tag);\r\n      const keys = (await this.driver.get(tagKey)) || [];\r\n      const updatedKeys = keys.filter((k: string) => k !== parsedKey);\r\n      await this.driver.set(tagKey, updatedKeys, Infinity);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Invalidate (clear) all keys associated with the current tags\r\n   */\r\n  public async invalidate(): Promise<void> {\r\n    const keysToRemove = await this.getTaggedKeys();\r\n\r\n    // Remove all tagged keys\r\n    for (const key of keysToRemove) {\r\n      await this.driver.remove(key);\r\n    }\r\n\r\n    // Clear tag relationship keys\r\n    for (const tag of this.cacheTags) {\r\n      await this.driver.remove(this.tagKey(tag));\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Flush all keys associated with the current tags\r\n   * @deprecated Use invalidate() instead for better semantics\r\n   */\r\n  public async flush(): Promise<void> {\r\n    return this.invalidate();\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async has(key: CacheKey): Promise<boolean> {\r\n    return this.driver.has(key);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async remember(\r\n    key: CacheKey,\r\n    ttl: number,\r\n    callback: () => Promise<any>,\r\n  ): Promise<any> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      return value;\r\n    }\r\n\r\n    const result = await callback();\r\n    await this.set(key, result, ttl);\r\n\r\n    return result;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async pull(key: CacheKey): Promise<any | null> {\r\n    const value = await this.get(key);\r\n\r\n    if (value !== null) {\r\n      await this.remove(key);\r\n    }\r\n\r\n    return value;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async forever(key: CacheKey, value: any): Promise<any> {\r\n    return this.set(key, value, Infinity);\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async increment(key: CacheKey, value: number = 1): Promise<number> {\r\n    const current = (await this.get(key)) || 0;\r\n\r\n    if (typeof current !== \"number\") {\r\n      throw new Error(\r\n        `Cannot increment non-numeric value for key: ${this.driver.parseKey(key)}`,\r\n      );\r\n    }\r\n\r\n    const newValue = current + value;\r\n    await this.set(key, newValue);\r\n\r\n    return newValue;\r\n  }\r\n\r\n  /**\r\n   * {@inheritdoc}\r\n   */\r\n  public async decrement(key: CacheKey, value: number = 1): Promise<number> {\r\n    return this.increment(key, -value);\r\n  }\r\n}\r\n"],"mappings":"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"}