@warlock.js/cache 4.0.171 → 4.1.1

package/esm/metrics.d.mts

@@ -0,0 +1,118 @@
+import { CacheEventData, CacheMetricsSnapshot } from "./types.mjs";
+
+//#region ../../@warlock.js/cache/src/metrics.d.ts
+/**
+ * Per-driver counter row tracked inside {@link CacheMetricsCollector}.
+ *
+ * Same shape as the public {@link CacheMetricsSnapshot} except for the lack
+ * of `byDriver` (which is the breakdown itself) and the `latencySamples`
+ * array — the buffer that p50/p95/p99 are computed from at snapshot time.
+ */
+type DriverCounters = {
+  hits: number;
+  misses: number;
+  sets: number;
+  removed: number;
+  errors: number;
+  latencySamples: number[]; /** Pointer into `latencySamples` for the next write — circular buffer. */
+  latencyCursor: number;
+};
+/**
+ * Listens to `CacheManager` events and accumulates running counters + a
+ * circular latency buffer per driver. Returned to consumers via
+ * `cache.metrics()` as a {@link CacheMetricsSnapshot}.
+ *
+ * **Role.** Single-instance observability layer attached to the manager.
+ * Subscribes once at construction; survives `cache.use()` driver switches
+ * because the global event registry on the manager re-attaches handlers to
+ * every loaded driver.
+ *
+ * **Responsibility.**
+ * - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,
+ *   `removed`, `errors`), the latency circular buffer, and snapshot
+ *   computation including hit-rate + percentile calculation.
+ * - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),
+ *   timing instrumentation (done at the manager level via `recordLatency`),
+ *   or persistence — every metric resets on `resetMetrics()` and on process
+ *   restart.
+ *
+ * @example
+ * cache.metrics();
+ * // {
+ * //   hits: 9821, misses: 173, hitRate: 0.983,
+ * //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },
+ * //   byDriver: { memory: { ... }, redis: { ... } },
+ * //   startedAt: 1714185600000,
+ * // }
+ */
+declare class CacheMetricsCollector {
+  /**
+   * Maximum number of latency samples retained per driver. Older samples
+   * are overwritten in arrival order — quantile calc operates on whatever
+   * window is currently in the buffer.
+   */
+  protected readonly bufferSize: number;
+  /**
+   * Aggregate counters across every driver. Mirrors what one driver bucket
+   * holds — the snapshot reports both totals and per-driver breakdowns.
+   */
+  protected readonly aggregate: DriverCounters;
+  /**
+   * Per-driver buckets keyed by driver name (`"memory"`, `"redis"`, …).
+   * Lazy-allocated on first event.
+   */
+  protected readonly byDriver: Map<string, DriverCounters>;
+  /** Millisecond timestamp the collector last reset. */
+  protected startedAt: number;
+  constructor(bufferSize?: number);
+  /**
+   * Increment the appropriate counters for a cache event. Called from the
+   * manager's global listeners (one per event type).
+   */
+  recordEvent(event: "hit" | "miss" | "set" | "removed" | "error", data: CacheEventData): void;
+  /**
+   * Append a latency sample for `driver`. Called by the manager from its
+   * timed wrappers around `get` / `set` / `remove`. Uses circular-buffer
+   * semantics: oldest samples are overwritten once the buffer is full.
+   */
+  recordLatency(driver: string, durationMs: number): void;
+  /**
+   * Compute and return the current snapshot. Latency percentiles are
+   * derived from a sorted copy of the buffer at call time — O(N log N)
+   * on N=1000 is cheap enough that we don't bother caching.
+   */
+  snapshot(): CacheMetricsSnapshot;
+  /**
+   * Wipe every counter, drop every latency sample, and reset `startedAt`.
+   * The collector itself stays subscribed to events.
+   */
+  reset(): void;
+  /**
+   * Locate the per-driver bucket, creating it on first reference. Driver
+   * names are taken verbatim from `CacheEventData.driver`.
+   */
+  protected bucketFor(driverName: string): DriverCounters;
+  /**
+   * Convert raw counters into the public snapshot row shape. Computes
+   * `hitRate` and the latency percentiles on the fly.
+   */
+  protected toRow(bucket: DriverCounters): Omit<CacheMetricsSnapshot, "byDriver">;
+  /**
+   * Sort a copy of the buffer and pick the percentile entries directly.
+   * Empty buffers return zeroed percentiles so consumers can render
+   * dashboards without null-checking.
+   */
+  protected computeLatency(samples: number[]): CacheMetricsSnapshot["latencyMs"];
+  /**
+   * Append a latency sample using circular-buffer semantics — overwrite the
+   * oldest entry once the buffer is full instead of growing unbounded.
+   */
+  protected appendLatency(bucket: DriverCounters, durationMs: number): void;
+  /** Build a fresh counter row with zeroed totals and an empty buffer. */
+  protected createCounters(): DriverCounters;
+  /** Reset an existing counter row in place. Used by `reset()` for the aggregate. */
+  protected resetCounters(bucket: DriverCounters): void;
+}
+//#endregion
+export { CacheMetricsCollector };
+//# sourceMappingURL=metrics.d.mts.map

package/esm/metrics.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.mts","names":[],"sources":["../../../../../@warlock.js/cache/src/metrics.ts"],"mappings":";;;;;AAGiB;;;;;KAgBZ,cAAA;EACH,IAAA;EACA,MAAA;EACA,IAAA;EACA,OAAA;EACA,MAAA;EACA,cAAA,YAEa;EAAb,aAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+BW,qBAAA;EAoEJ;;;;;EAAA,mBA9DY,UAAA;EAoGT;;;;EAAA,mBA9FS,SAAA,EAAW,cAAA;EA6Gd;;;;EAAA,mBAvGG,QAAA,EAAU,GAAA,SAAY,cAAA;EA6HI;EAAA,UA1HnC,SAAA;cAES,UAAA;EAgJK;;;;EAvIjB,WAAA,CACL,KAAA,gDACA,IAAA,EAAM,cAAA;EA8JwB;;;AAAc;;EA5HvC,aAAA,CAAc,MAAA,UAAgB,UAAA;;;;;;EAU9B,QAAA,CAAA,GAAY,oBAAA;;;;;EAkBZ,KAAA,CAAA;;;;;YAUG,SAAA,CAAU,UAAA,WAAqB,cAAA;;;;;YAe/B,KAAA,CAAM,MAAA,EAAQ,cAAA,GAAiB,IAAA,CAAK,oBAAA;;;;;;YAsBpC,cAAA,CAAe,OAAA,aAAoB,oBAAA;;;;;YAwBnC,aAAA,CAAc,MAAA,EAAQ,cAAA,EAAgB,UAAA;;YAYtC,cAAA,CAAA,GAAkB,cAAA;;YAalB,aAAA,CAAc,MAAA,EAAQ,cAAA;AAAA"}

package/esm/metrics.mjs

@@ -0,0 +1,197 @@
+//#region ../../@warlock.js/cache/src/metrics.ts
+/**
+* Default size of the circular latency-sample buffer. 1000 samples covers
+* "tell me the current p95" for every realistic workload while keeping the
+* memory cost negligible (8KB at 8 bytes per number).
+*/
+const DEFAULT_LATENCY_BUFFER_SIZE = 1e3;
+/**
+* Listens to `CacheManager` events and accumulates running counters + a
+* circular latency buffer per driver. Returned to consumers via
+* `cache.metrics()` as a {@link CacheMetricsSnapshot}.
+*
+* **Role.** Single-instance observability layer attached to the manager.
+* Subscribes once at construction; survives `cache.use()` driver switches
+* because the global event registry on the manager re-attaches handlers to
+* every loaded driver.
+*
+* **Responsibility.**
+* - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,
+*   `removed`, `errors`), the latency circular buffer, and snapshot
+*   computation including hit-rate + percentile calculation.
+* - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),
+*   timing instrumentation (done at the manager level via `recordLatency`),
+*   or persistence — every metric resets on `resetMetrics()` and on process
+*   restart.
+*
+* @example
+* cache.metrics();
+* // {
+* //   hits: 9821, misses: 173, hitRate: 0.983,
+* //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },
+* //   byDriver: { memory: { ... }, redis: { ... } },
+* //   startedAt: 1714185600000,
+* // }
+*/
+var CacheMetricsCollector = class {
+	constructor(bufferSize = DEFAULT_LATENCY_BUFFER_SIZE) {
+		this.byDriver = /* @__PURE__ */ new Map();
+		this.startedAt = Date.now();
+		this.bufferSize = bufferSize;
+		this.aggregate = this.createCounters();
+	}
+	/**
+	* Increment the appropriate counters for a cache event. Called from the
+	* manager's global listeners (one per event type).
+	*/
+	recordEvent(event, data) {
+		const driverBucket = this.bucketFor(data.driver);
+		const aggregate = this.aggregate;
+		switch (event) {
+			case "hit":
+				aggregate.hits += 1;
+				driverBucket.hits += 1;
+				break;
+			case "miss":
+				aggregate.misses += 1;
+				driverBucket.misses += 1;
+				break;
+			case "set":
+				aggregate.sets += 1;
+				driverBucket.sets += 1;
+				break;
+			case "removed":
+				aggregate.removed += 1;
+				driverBucket.removed += 1;
+				break;
+			case "error":
+				aggregate.errors += 1;
+				driverBucket.errors += 1;
+				break;
+		}
+	}
+	/**
+	* Append a latency sample for `driver`. Called by the manager from its
+	* timed wrappers around `get` / `set` / `remove`. Uses circular-buffer
+	* semantics: oldest samples are overwritten once the buffer is full.
+	*/
+	recordLatency(driver, durationMs) {
+		this.appendLatency(this.aggregate, durationMs);
+		this.appendLatency(this.bucketFor(driver), durationMs);
+	}
+	/**
+	* Compute and return the current snapshot. Latency percentiles are
+	* derived from a sorted copy of the buffer at call time — O(N log N)
+	* on N=1000 is cheap enough that we don't bother caching.
+	*/
+	snapshot() {
+		const byDriver = {};
+		for (const [driverName, bucket] of this.byDriver) byDriver[driverName] = this.toRow(bucket);
+		return {
+			...this.toRow(this.aggregate),
+			byDriver,
+			startedAt: this.startedAt
+		};
+	}
+	/**
+	* Wipe every counter, drop every latency sample, and reset `startedAt`.
+	* The collector itself stays subscribed to events.
+	*/
+	reset() {
+		this.resetCounters(this.aggregate);
+		this.byDriver.clear();
+		this.startedAt = Date.now();
+	}
+	/**
+	* Locate the per-driver bucket, creating it on first reference. Driver
+	* names are taken verbatim from `CacheEventData.driver`.
+	*/
+	bucketFor(driverName) {
+		let bucket = this.byDriver.get(driverName);
+		if (!bucket) {
+			bucket = this.createCounters();
+			this.byDriver.set(driverName, bucket);
+		}
+		return bucket;
+	}
+	/**
+	* Convert raw counters into the public snapshot row shape. Computes
+	* `hitRate` and the latency percentiles on the fly.
+	*/
+	toRow(bucket) {
+		const totalReads = bucket.hits + bucket.misses;
+		const hitRate = totalReads === 0 ? 0 : bucket.hits / totalReads;
+		const latency = this.computeLatency(bucket.latencySamples);
+		return {
+			hits: bucket.hits,
+			misses: bucket.misses,
+			sets: bucket.sets,
+			removed: bucket.removed,
+			errors: bucket.errors,
+			hitRate,
+			latencyMs: latency,
+			startedAt: this.startedAt
+		};
+	}
+	/**
+	* Sort a copy of the buffer and pick the percentile entries directly.
+	* Empty buffers return zeroed percentiles so consumers can render
+	* dashboards without null-checking.
+	*/
+	computeLatency(samples) {
+		if (samples.length === 0) return {
+			p50: 0,
+			p95: 0,
+			p99: 0,
+			samples: 0
+		};
+		const sorted = [...samples].sort((a, b) => a - b);
+		const pick = (quantile) => {
+			return sorted[Math.min(sorted.length - 1, Math.floor(quantile * sorted.length))];
+		};
+		return {
+			p50: pick(.5),
+			p95: pick(.95),
+			p99: pick(.99),
+			samples: sorted.length
+		};
+	}
+	/**
+	* Append a latency sample using circular-buffer semantics — overwrite the
+	* oldest entry once the buffer is full instead of growing unbounded.
+	*/
+	appendLatency(bucket, durationMs) {
+		if (bucket.latencySamples.length < this.bufferSize) {
+			bucket.latencySamples.push(durationMs);
+			return;
+		}
+		bucket.latencySamples[bucket.latencyCursor] = durationMs;
+		bucket.latencyCursor = (bucket.latencyCursor + 1) % this.bufferSize;
+	}
+	/** Build a fresh counter row with zeroed totals and an empty buffer. */
+	createCounters() {
+		return {
+			hits: 0,
+			misses: 0,
+			sets: 0,
+			removed: 0,
+			errors: 0,
+			latencySamples: [],
+			latencyCursor: 0
+		};
+	}
+	/** Reset an existing counter row in place. Used by `reset()` for the aggregate. */
+	resetCounters(bucket) {
+		bucket.hits = 0;
+		bucket.misses = 0;
+		bucket.sets = 0;
+		bucket.removed = 0;
+		bucket.errors = 0;
+		bucket.latencySamples.length = 0;
+		bucket.latencyCursor = 0;
+	}
+};
+
+//#endregion
+export { CacheMetricsCollector };
+//# sourceMappingURL=metrics.mjs.map

package/esm/metrics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/metrics.ts"],"sourcesContent":["import type {\n  CacheEventData,\n  CacheMetricsSnapshot,\n} from \"./types\";\n\n/**\n * Default size of the circular latency-sample buffer. 1000 samples covers\n * \"tell me the current p95\" for every realistic workload while keeping the\n * memory cost negligible (8KB at 8 bytes per number).\n */\nconst DEFAULT_LATENCY_BUFFER_SIZE = 1000;\n\n/**\n * Per-driver counter row tracked inside {@link CacheMetricsCollector}.\n *\n * Same shape as the public {@link CacheMetricsSnapshot} except for the lack\n * of `byDriver` (which is the breakdown itself) and the `latencySamples`\n * array — the buffer that p50/p95/p99 are computed from at snapshot time.\n */\ntype DriverCounters = {\n  hits: number;\n  misses: number;\n  sets: number;\n  removed: number;\n  errors: number;\n  latencySamples: number[];\n  /** Pointer into `latencySamples` for the next write — circular buffer. */\n  latencyCursor: number;\n};\n\n/**\n * Listens to `CacheManager` events and accumulates running counters + a\n * circular latency buffer per driver. Returned to consumers via\n * `cache.metrics()` as a {@link CacheMetricsSnapshot}.\n *\n * **Role.** Single-instance observability layer attached to the manager.\n * Subscribes once at construction; survives `cache.use()` driver switches\n * because the global event registry on the manager re-attaches handlers to\n * every loaded driver.\n *\n * **Responsibility.**\n * - Owns: per-driver and aggregate counters (`hits`, `misses`, `sets`,\n *   `removed`, `errors`), the latency circular buffer, and snapshot\n *   computation including hit-rate + percentile calculation.\n * - Does NOT own: event emission (driven by drivers via `BaseCacheDriver.emit`),\n *   timing instrumentation (done at the manager level via `recordLatency`),\n *   or persistence — every metric resets on `resetMetrics()` and on process\n *   restart.\n *\n * @example\n * cache.metrics();\n * // {\n * //   hits: 9821, misses: 173, hitRate: 0.983,\n * //   latencyMs: { p50: 0.4, p95: 2.1, p99: 8.2, samples: 1000 },\n * //   byDriver: { memory: { ... }, redis: { ... } },\n * //   startedAt: 1714185600000,\n * // }\n */\nexport class CacheMetricsCollector {\n  /**\n   * Maximum number of latency samples retained per driver. Older samples\n   * are overwritten in arrival order — quantile calc operates on whatever\n   * window is currently in the buffer.\n   */\n  protected readonly bufferSize: number;\n\n  /**\n   * Aggregate counters across every driver. Mirrors what one driver bucket\n   * holds — the snapshot reports both totals and per-driver breakdowns.\n   */\n  protected readonly aggregate: DriverCounters;\n\n  /**\n   * Per-driver buckets keyed by driver name (`\"memory\"`, `\"redis\"`, …).\n   * Lazy-allocated on first event.\n   */\n  protected readonly byDriver: Map<string, DriverCounters> = new Map();\n\n  /** Millisecond timestamp the collector last reset. */\n  protected startedAt: number = Date.now();\n\n  public constructor(bufferSize: number = DEFAULT_LATENCY_BUFFER_SIZE) {\n    this.bufferSize = bufferSize;\n    this.aggregate = this.createCounters();\n  }\n\n  /**\n   * Increment the appropriate counters for a cache event. Called from the\n   * manager's global listeners (one per event type).\n   */\n  public recordEvent(\n    event: \"hit\" | \"miss\" | \"set\" | \"removed\" | \"error\",\n    data: CacheEventData,\n  ): void {\n    const driverBucket = this.bucketFor(data.driver);\n    const aggregate = this.aggregate;\n\n    switch (event) {\n      case \"hit\":\n        aggregate.hits += 1;\n        driverBucket.hits += 1;\n        break;\n      case \"miss\":\n        aggregate.misses += 1;\n        driverBucket.misses += 1;\n        break;\n      case \"set\":\n        aggregate.sets += 1;\n        driverBucket.sets += 1;\n        break;\n      case \"removed\":\n        aggregate.removed += 1;\n        driverBucket.removed += 1;\n        break;\n      case \"error\":\n        aggregate.errors += 1;\n        driverBucket.errors += 1;\n        break;\n    }\n  }\n\n  /**\n   * Append a latency sample for `driver`. Called by the manager from its\n   * timed wrappers around `get` / `set` / `remove`. Uses circular-buffer\n   * semantics: oldest samples are overwritten once the buffer is full.\n   */\n  public recordLatency(driver: string, durationMs: number): void {\n    this.appendLatency(this.aggregate, durationMs);\n    this.appendLatency(this.bucketFor(driver), durationMs);\n  }\n\n  /**\n   * Compute and return the current snapshot. Latency percentiles are\n   * derived from a sorted copy of the buffer at call time — O(N log N)\n   * on N=1000 is cheap enough that we don't bother caching.\n   */\n  public snapshot(): CacheMetricsSnapshot {\n    const byDriver: Record<string, Omit<CacheMetricsSnapshot, \"byDriver\">> = {};\n\n    for (const [driverName, bucket] of this.byDriver) {\n      byDriver[driverName] = this.toRow(bucket);\n    }\n\n    return {\n      ...this.toRow(this.aggregate),\n      byDriver,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Wipe every counter, drop every latency sample, and reset `startedAt`.\n   * The collector itself stays subscribed to events.\n   */\n  public reset(): void {\n    this.resetCounters(this.aggregate);\n    this.byDriver.clear();\n    this.startedAt = Date.now();\n  }\n\n  /**\n   * Locate the per-driver bucket, creating it on first reference. Driver\n   * names are taken verbatim from `CacheEventData.driver`.\n   */\n  protected bucketFor(driverName: string): DriverCounters {\n    let bucket = this.byDriver.get(driverName);\n\n    if (!bucket) {\n      bucket = this.createCounters();\n      this.byDriver.set(driverName, bucket);\n    }\n\n    return bucket;\n  }\n\n  /**\n   * Convert raw counters into the public snapshot row shape. Computes\n   * `hitRate` and the latency percentiles on the fly.\n   */\n  protected toRow(bucket: DriverCounters): Omit<CacheMetricsSnapshot, \"byDriver\"> {\n    const totalReads = bucket.hits + bucket.misses;\n    const hitRate = totalReads === 0 ? 0 : bucket.hits / totalReads;\n    const latency = this.computeLatency(bucket.latencySamples);\n\n    return {\n      hits: bucket.hits,\n      misses: bucket.misses,\n      sets: bucket.sets,\n      removed: bucket.removed,\n      errors: bucket.errors,\n      hitRate,\n      latencyMs: latency,\n      startedAt: this.startedAt,\n    };\n  }\n\n  /**\n   * Sort a copy of the buffer and pick the percentile entries directly.\n   * Empty buffers return zeroed percentiles so consumers can render\n   * dashboards without null-checking.\n   */\n  protected computeLatency(samples: number[]): CacheMetricsSnapshot[\"latencyMs\"] {\n    if (samples.length === 0) {\n      return { p50: 0, p95: 0, p99: 0, samples: 0 };\n    }\n\n    const sorted = [...samples].sort((a, b) => a - b);\n    const pick = (quantile: number): number => {\n      const index = Math.min(sorted.length - 1, Math.floor(quantile * sorted.length));\n\n      return sorted[index];\n    };\n\n    return {\n      p50: pick(0.5),\n      p95: pick(0.95),\n      p99: pick(0.99),\n      samples: sorted.length,\n    };\n  }\n\n  /**\n   * Append a latency sample using circular-buffer semantics — overwrite the\n   * oldest entry once the buffer is full instead of growing unbounded.\n   */\n  protected appendLatency(bucket: DriverCounters, durationMs: number): void {\n    if (bucket.latencySamples.length < this.bufferSize) {\n      bucket.latencySamples.push(durationMs);\n\n      return;\n    }\n\n    bucket.latencySamples[bucket.latencyCursor] = durationMs;\n    bucket.latencyCursor = (bucket.latencyCursor + 1) % this.bufferSize;\n  }\n\n  /** Build a fresh counter row with zeroed totals and an empty buffer. */\n  protected createCounters(): DriverCounters {\n    return {\n      hits: 0,\n      misses: 0,\n      sets: 0,\n      removed: 0,\n      errors: 0,\n      latencySamples: [],\n      latencyCursor: 0,\n    };\n  }\n\n  /** Reset an existing counter row in place. Used by `reset()` for the aggregate. */\n  protected resetCounters(bucket: DriverCounters): void {\n    bucket.hits = 0;\n    bucket.misses = 0;\n    bucket.sets = 0;\n    bucket.removed = 0;\n    bucket.errors = 0;\n    bucket.latencySamples.length = 0;\n    bucket.latencyCursor = 0;\n  }\n}\n"],"mappings":"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"}

package/esm/scoped-cache.d.mts

@@ -0,0 +1,205 @@
+import { CacheDriver, CacheKey, CacheListAccessor, CacheNamespaceOptions, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, LockOptions, LockOutcome, RememberOptions, ScopedCacheContract, TaggedScopedCacheContract } from "./types.mjs";
+
+//#region ../../@warlock.js/cache/src/scoped-cache.d.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();
+ */
+declare class ScopedCache implements ScopedCacheContract {
+  /**
+   * Fully-qualified prefix prepended to every key handled by this scope.
+   * Normalized through {@link parseCacheKey} on construction so colon-form
+   * input (`"chats:10"`) and trailing dots compose cleanly with nested scopes.
+   */
+  readonly prefix: string;
+  /**
+   * Underlying cache source. Public-readonly so co-located helpers
+   * (`TaggedScopedCache`) can delegate without ceremony — not part of the
+   * stable consumer API.
+   *
+   * @internal
+   */
+  readonly source: CacheDriver<any, any>;
+  /**
+   * Defaults applied to every write through this scope. Per-call options
+   * override `ttl`; `tags` merge additively across layers.
+   *
+   * @internal
+   */
+  readonly defaults: CacheNamespaceOptions;
+  /**
+   * Build a scope. Constructed via `cache.namespace(prefix, options)` —
+   * users never call this directly.
+   */
+  constructor(source: CacheDriver<any, any>, prefix: string, defaults?: CacheNamespaceOptions);
+  /**
+   * 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: string, options?: CacheNamespaceOptions): ScopedCacheContract;
+  /**
+   * 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: string[]): TaggedScopedCacheContract;
+  /**
+   * Wipe every entry under this scope's prefix. Sugar over
+   * `source.removeNamespace(prefix)` — siblings outside the scope are
+   * untouched.
+   */
+  clear(): Promise<void>;
+  /**
+   * Read the value at the scoped key. Forwards to the source after prefixing.
+   */
+  get<T = any>(key: CacheKey): Promise<T | null>;
+  /**
+   * Check presence of the scoped key without fetching the value.
+   */
+  has(key: CacheKey): Promise<boolean>;
+  /**
+   * Batch-read scoped keys. Each input key is prefixed before forwarding.
+   */
+  many(keys: CacheKey[]): Promise<any[]>;
+  /**
+   * Read-and-remove. Returns the value or `null`; the entry is gone after.
+   */
+  pull<T = any>(key: CacheKey): Promise<T | null>;
+  /**
+   * 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: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * 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: Record<string, any>, ttl?: number): Promise<void>;
+  /**
+   * Atomic create-or-skip on the scoped key. Throws when the underlying
+   * source has no `setNX` (driver-specific — Redis-only today).
+   */
+  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;
+  /**
+   * Permanent write (no expiration). Bypasses the scope's `ttl` default —
+   * `forever` always means forever, regardless of scope policy.
+   */
+  forever<T = any>(key: CacheKey, value: T): Promise<T>;
+  /**
+   * Remove a single scoped key.
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * 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<T = any>(key: CacheKey, ttlOrOptions: CacheTtl | RememberOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * 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<T = any>(key: CacheKey, options: CacheSwrOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * 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: CacheKey, value?: number): Promise<number>;
+  /**
+   * Atomic counter decrement on the scoped key. See {@link increment} for
+   * TTL semantics.
+   */
+  decrement(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * 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<T = any>(key: CacheKey, fn: (current: T | null) => T | null | Promise<T | null>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T | null>;
+  /**
+   * Shallow-merge a partial object into the scoped entry. Same TTL semantics
+   * as {@link update}.
+   */
+  merge<T extends Record<string, any> = Record<string, any>>(key: CacheKey, partial: Partial<T>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T>;
+  /**
+   * Return a list accessor bound to the scoped key. The accessor itself
+   * does its own read-mutate-write under the prefixed entry.
+   */
+  list<T = any>(key: CacheKey): CacheListAccessor<T>;
+  /**
+   * Acquire a distributed lock on the scoped key. Caller's TTL wins; when
+   * the options form omits `ttl`, the scope default fills in.
+   */
+  lock<T>(key: CacheKey, ttlOrOptions: CacheTtl | Omit<LockOptions, "driver">, fn: () => Promise<T>): Promise<LockOutcome<T>>;
+  /**
+   * 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`.
+   */
+  similar<T = any>(vector: number[], options: CacheSimilarOptions): Promise<CacheSimilarHit<T>[]>;
+  /**
+   * 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.
+   */
+  protected scopedKey(key: CacheKey): string;
+  /**
+   * 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).
+   */
+  protected mergeSetOptions(input?: CacheTtl | CacheSetOptions): CacheSetOptions | undefined;
+  /**
+   * Same merge as {@link mergeSetOptions} but for the `remember()` shape
+   * ({@link RememberOptions} — no `expiresAt`).
+   */
+  protected mergeRememberOptions(input: CacheTtl | RememberOptions): CacheTtl | RememberOptions;
+  /**
+   * 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.
+   */
+  protected scopeTtlSeconds(): number | undefined;
+}
+//#endregion
+export { ScopedCache };
+//# sourceMappingURL=scoped-cache.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-cache.d.mts","names":[],"sources":["../../../../../@warlock.js/cache/src/scoped-cache.ts"],"mappings":"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"}