@warlock.js/cache 4.0.171 → 4.1.1

package/esm/types.d.mts.map

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

package/esm/types.mjs

@@ -0,0 +1,62 @@
+//#region ../../@warlock.js/cache/src/types.ts
+/**
+* Base error class for cache-related errors
+*/
+var CacheError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CacheError";
+	}
+};
+/**
+* Error thrown when cache connection fails
+*/
+var CacheConnectionError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConnectionError";
+	}
+};
+/**
+* Error thrown when cache driver configuration is invalid
+*/
+var CacheConfigurationError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConfigurationError";
+	}
+};
+/**
+* Error thrown when cache driver is not initialized
+*/
+var CacheDriverNotInitializedError = class extends CacheError {
+	constructor(message = "No cache driver initialized. Call cache.init() or cache.use() first.") {
+		super(message);
+		this.name = "CacheDriverNotInitializedError";
+	}
+};
+/**
+* Error thrown when a driver does not implement a requested operation.
+*
+* Raised when a caller invokes a method the driver cannot fulfill —
+* e.g. `update()` on the file driver before the file-lock primitive lands.
+*/
+var CacheUnsupportedError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheUnsupportedError";
+	}
+};
+/**
+* Error thrown when an optimistic-concurrency update exhausts its retry budget.
+*/
+var CacheConcurrencyError = class extends CacheError {
+	constructor(message) {
+		super(message);
+		this.name = "CacheConcurrencyError";
+	}
+};
+
+//#endregion
+export { CacheConcurrencyError, CacheConfigurationError, CacheConnectionError, CacheDriverNotInitializedError, CacheError, CacheUnsupportedError };
+//# sourceMappingURL=types.mjs.map

package/esm/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/types.ts"],"sourcesContent":["import type { GenericObject } from \"@mongez/reinforcements\";\r\nimport type { RedisClientOptions } from \"redis\";\r\nimport type {\r\n  BaseCacheDriver,\r\n  FileCacheDriver,\r\n  LRUMemoryCacheDriver,\r\n  MemoryCacheDriver,\r\n  MockCacheDriver,\r\n  MemoryExtendedCacheDriver,\r\n  NullCacheDriver,\r\n  PgCacheDriver,\r\n  RedisCacheDriver,\r\n} from \"./drivers\";\r\n\r\n/**\r\n * Base error class for cache-related errors\r\n */\r\nexport class CacheError extends Error {\r\n  public constructor(message: string) {\r\n    super(message);\r\n    this.name = \"CacheError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Error thrown when cache connection fails\r\n */\r\nexport class CacheConnectionError extends CacheError {\r\n  public constructor(message: string) {\r\n    super(message);\r\n    this.name = \"CacheConnectionError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Error thrown when cache driver configuration is invalid\r\n */\r\nexport class CacheConfigurationError extends CacheError {\r\n  public constructor(message: string) {\r\n    super(message);\r\n    this.name = \"CacheConfigurationError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Error thrown when cache driver is not initialized\r\n */\r\nexport class CacheDriverNotInitializedError extends CacheError {\r\n  public constructor(\r\n    message: string = \"No cache driver initialized. Call cache.init() or cache.use() first.\",\r\n  ) {\r\n    super(message);\r\n    this.name = \"CacheDriverNotInitializedError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Error thrown when a driver does not implement a requested operation.\r\n *\r\n * Raised when a caller invokes a method the driver cannot fulfill —\r\n * e.g. `update()` on the file driver before the file-lock primitive lands.\r\n */\r\nexport class CacheUnsupportedError extends CacheError {\r\n  public constructor(message: string) {\r\n    super(message);\r\n    this.name = \"CacheUnsupportedError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Error thrown when an optimistic-concurrency update exhausts its retry budget.\r\n */\r\nexport class CacheConcurrencyError extends CacheError {\r\n  public constructor(message: string) {\r\n    super(message);\r\n    this.name = \"CacheConcurrencyError\";\r\n  }\r\n}\r\n\r\n/**\r\n * TTL shape accepted by set/remember/config calls.\r\n *\r\n * - `number` — seconds\r\n * - `string` — human-readable duration parsed via `ms` (`\"1h\"`, `\"30m\"`, `\"7d\"`, `\"2 weeks\"`, …)\r\n * - `Infinity` — no expiration\r\n */\r\nexport type CacheTtl = number | string;\r\n\r\n/**\r\n * Conflict resolution policy for `set` operations.\r\n *\r\n * - `\"create\"` — set only if the key does not exist (Redis `NX`)\r\n * - `\"update\"` — set only if the key already exists (Redis `XX`)\r\n * - `\"upsert\"` — default; overwrite whether the key exists or not\r\n */\r\nexport type CacheConflictPolicy = \"create\" | \"update\" | \"upsert\";\r\n\r\n/**\r\n * Result of a conditional write (`onConflict: \"create\" | \"update\"`).\r\n */\r\nexport type CacheSetResult<T = any> = {\r\n  /**\r\n   * Whether the write actually took effect.\r\n   */\r\n  wasSet: boolean;\r\n  /**\r\n   * The existing value when the write was rejected. Undefined for successful writes\r\n   * and for unconditional `upsert` writes.\r\n   */\r\n  existing: T | null;\r\n};\r\n\r\n/**\r\n * Options for `lock()` — TTL is required (forgotten locks would stay forever),\r\n * `owner` identifies who holds the lock (handy for debugging), `driver` routes\r\n * the call through a non-default driver.\r\n *\r\n * @example\r\n * await cache.lock(\"lock.import\", { ttl: \"5m\", driver: \"redis\" }, async () => {\r\n *   await runImport();\r\n * });\r\n */\r\nexport type LockOptions = {\r\n  /**\r\n   * How long the lock lives before auto-release. Required — guards against\r\n   * forgotten locks if the process crashes between acquire and release.\r\n   */\r\n  ttl: CacheTtl;\r\n  /**\r\n   * Identifying value stored under the lock key. Defaults to `pid.<process.pid>`.\r\n   * Use a custom owner when you want a human-readable label (e.g. `\"worker.jobs-2\"`).\r\n   */\r\n  owner?: string;\r\n  /**\r\n   * Per-call driver override by registered name. Manager-level only.\r\n   */\r\n  driver?: string;\r\n};\r\n\r\n/**\r\n * Discriminated-union result of `lock()`. Unambiguous even when the wrapped\r\n * function legitimately returns `undefined` — the `acquired` flag tells you\r\n * whether `fn` ran at all.\r\n *\r\n * @example\r\n * const outcome = await cache.lock(\"lock.x\", \"1m\", async () => computeValue());\r\n * if (outcome.acquired) {\r\n *   console.log(\"ran, got\", outcome.value);\r\n * } else {\r\n *   console.log(\"skipped — someone else holds the lock\");\r\n * }\r\n */\r\nexport type LockOutcome<T> =\r\n  | { acquired: true; value: T }\r\n  | { acquired: false };\r\n\r\n/**\r\n * Options for `remember()` when you need more than just a TTL — e.g. attaching\r\n * tags to the cache-miss write, or routing the single call to a non-default driver.\r\n *\r\n * Passed in the TTL position: `cache.remember(key, { ttl: \"1h\", tags: [\"users\"] }, fn)`.\r\n *\r\n * @example\r\n * await cache.remember(\"user.1\", { ttl: \"1h\", tags: [\"users\"] }, () =>\r\n *   db.users.find(1),\r\n * );\r\n */\r\nexport type RememberOptions = {\r\n  /**\r\n   * TTL applied on cache miss. Accepts seconds (number) or duration string.\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Tags attached to the entry created on miss. Invalidate via `cache.tags([...]).invalidate()`.\r\n   */\r\n  tags?: string[];\r\n  /**\r\n   * Per-call driver override. Routes this remember call (both read and write)\r\n   * to the named driver without mutating `currentDriver`.\r\n   */\r\n  driver?: string;\r\n};\r\n\r\n/**\r\n * Rich options for the `set` call-site. Mutually exclusive with a positional TTL.\r\n *\r\n * @example\r\n * await cache.set(\"user:1\", user, {\r\n *   ttl: \"1h\",\r\n *   tags: [\"users\", \"active\"],\r\n *   onConflict: \"create\",\r\n * });\r\n */\r\nexport type CacheSetOptions = {\r\n  /**\r\n   * Relative TTL (seconds or duration string). Mutually exclusive with `expiresAt`.\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Absolute expiration as a Unix epoch in milliseconds or a Date. Mutually exclusive with `ttl`.\r\n   */\r\n  expiresAt?: number | Date;\r\n  /**\r\n   * Tags attached to this entry for tag-based invalidation. Inline equivalent of\r\n   * `cache.tags([...]).set(key, value)`.\r\n   */\r\n  tags?: string[];\r\n  /**\r\n   * Conflict resolution policy. Defaults to `\"upsert\"`.\r\n   */\r\n  onConflict?: CacheConflictPolicy;\r\n  /**\r\n   * Per-call namespace override. Applied ahead of `globalPrefix` for this write only.\r\n   */\r\n  namespace?: string;\r\n  /**\r\n   * Per-call driver override by registered name. Routes this write to a non-default driver\r\n   * without mutating `currentDriver`.\r\n   */\r\n  driver?: string;\r\n  /**\r\n   * Optional embedding vector indexed alongside the entry for similarity retrieval\r\n   * via `cache.similar(...)`. Drivers without similarity support throw\r\n   * {@link CacheUnsupportedError} when this option is supplied.\r\n   *\r\n   * Cache is embedding-agnostic — callers compute the vector with whichever embedder\r\n   * they like and pass the result here.\r\n   *\r\n   * @example\r\n   * await cache.set(\"doc.123\", doc, { vector: await embed(doc.text), ttl: \"1d\" });\r\n   */\r\n  vector?: number[];\r\n  /**\r\n   * Freshness deadline as a Unix epoch in milliseconds. Primarily set by\r\n   * {@link CacheSwrOptions} flow — entries with `staleAt` in the future are\r\n   * considered \"fresh\" by `cache.swr()`; entries past `staleAt` but before\r\n   * `expiresAt` are \"stale-but-revalidatable.\"\r\n   *\r\n   * Direct callers can pin this manually when bypassing `swr()`, but the\r\n   * common path is `cache.swr(key, { freshTtl, staleTtl }, fn)`.\r\n   */\r\n  staleAt?: number;\r\n};\r\n\r\n/**\r\n * Options for `cache.namespace(prefix, options)` — defaults applied to every\r\n * write produced through the returned scope.\r\n *\r\n * Per-call options always win over scope defaults. Tags merge additively\r\n * (scope tags + call tags, deduped). Nested scopes inherit from the parent;\r\n * the child's own values override.\r\n */\r\nexport type CacheNamespaceOptions = {\r\n  /**\r\n   * Default TTL for writes inside this scope. Same shape as everywhere else\r\n   * — number of seconds or a duration string (`\"1h\"`, `\"30d\"`, …).\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Tags auto-attached to every write inside this scope. Useful for cross-scope\r\n   * invalidation hooks (e.g. tag every entry with `user.<id>` so a single\r\n   * `cache.flushTag(\"user.42\")` wipes the user's footprint everywhere).\r\n   *\r\n   * Merged additively with per-call tags; scope tags are never replaced.\r\n   */\r\n  tags?: string[];\r\n};\r\n\r\n/**\r\n * Options for `cache.swr(key, options, callback)` — stale-while-revalidate.\r\n *\r\n * Two TTLs split the entry's lifecycle into three windows:\r\n * - `now < freshTtl` → fresh, return cached value, no upstream call.\r\n * - `freshTtl <= now < staleTtl` → stale-but-revalidatable, return cached\r\n *   value immediately, kick off `callback` in the background to refresh.\r\n * - `now >= staleTtl` → expired, block on `callback` like a normal miss.\r\n *\r\n * Concurrent SWR callers in the stale window all return the cached value;\r\n * the background refresh runs exactly once per key (deduped via the\r\n * driver's per-key lock map).\r\n *\r\n * If the background refresh fails, the stale entry is preserved and the\r\n * error is logged + emitted on the `error` event. Callers that received\r\n * the stale value never see the failure — they got their data.\r\n */\r\nexport type CacheSwrOptions = {\r\n  /**\r\n   * How long the value is considered fresh. Within this window, SWR returns\r\n   * the cached value with no upstream call. Accepts seconds or duration\r\n   * string (`\"1m\"`, `\"30s\"`).\r\n   */\r\n  freshTtl: CacheTtl;\r\n  /**\r\n   * Total lifetime of the entry (must be greater than `freshTtl`). Between\r\n   * `freshTtl` and `staleTtl`, SWR returns the stale value and triggers a\r\n   * background refresh. Past `staleTtl`, SWR blocks and refetches.\r\n   */\r\n  staleTtl: CacheTtl;\r\n  /**\r\n   * Optional tags applied on the first miss-fetch and on every successful\r\n   * background refresh. Same semantics as `CacheSetOptions.tags`.\r\n   */\r\n  tags?: string[];\r\n  /**\r\n   * Per-call driver override by registered name. Routes both the read and\r\n   * any write/refresh through the named driver without mutating\r\n   * `currentDriver`. Same semantics as `RememberOptions.driver`.\r\n   */\r\n  driver?: string;\r\n};\r\n\r\n/**\r\n * Options for `cache.similar(vector, options)` — similarity retrieval against\r\n * stored entries previously written with `set({ vector })`.\r\n */\r\nexport type CacheSimilarOptions = {\r\n  /**\r\n   * Maximum number of hits to return. Required — no implicit default keeps\r\n   * callers from accidentally pulling the entire candidate set.\r\n   */\r\n  topK: number;\r\n  /**\r\n   * Cosine similarity floor in `[0, 1]`. Hits scoring strictly below this are\r\n   * filtered out before `topK` truncation.\r\n   */\r\n  threshold?: number;\r\n  /**\r\n   * Optional tag filter. Only entries tagged with at least one of the given\r\n   * tags are considered (matches the union semantics elsewhere in the package).\r\n   */\r\n  tags?: string[];\r\n};\r\n\r\n/**\r\n * One result from a `similar()` query — the original key, its stored value,\r\n * and the cosine similarity to the query vector.\r\n */\r\nexport type CacheSimilarHit<T = unknown> = {\r\n  /**\r\n   * The original cache key, post-`parseKey` normalization.\r\n   */\r\n  key: string;\r\n  /**\r\n   * Stored value, deep-cloned to protect the cache from accidental mutation\r\n   * (same semantics as `get`).\r\n   */\r\n  value: T;\r\n  /**\r\n   * Cosine similarity in `[0, 1]`. Higher means more similar.\r\n   */\r\n  score: number;\r\n};\r\n\r\n/**\r\n * Cache key type - can be a string or an object\r\n */\r\nexport type CacheKey = string | GenericObject;\r\n\r\nexport type CacheOperationType =\r\n  | \"fetching\"\r\n  | \"fetched\"\r\n  | \"caching\"\r\n  | \"cached\"\r\n  | \"flushing\"\r\n  | \"flushed\"\r\n  | \"removing\"\r\n  | \"removed\"\r\n  | \"clearing\"\r\n  | \"cleared\"\r\n  | \"expired\"\r\n  | \"notFound\"\r\n  | \"connecting\"\r\n  | \"error\"\r\n  | \"connected\"\r\n  | \"disconnecting\"\r\n  | \"disconnected\";\r\n\r\n/**\r\n * Cache event types for observability\r\n */\r\nexport type CacheEventType =\r\n  | \"hit\"\r\n  | \"miss\"\r\n  | \"set\"\r\n  | \"removed\"\r\n  | \"flushed\"\r\n  | \"expired\"\r\n  | \"connected\"\r\n  | \"disconnected\"\r\n  | \"error\";\r\n\r\n/**\r\n * Cache event data structure\r\n */\r\nexport type CacheEventData = {\r\n  /**\r\n   * The cache key involved in the event\r\n   */\r\n  key?: string;\r\n  /**\r\n   * The value (for set/hit events)\r\n   */\r\n  value?: any;\r\n  /**\r\n   * TTL in seconds (for set events)\r\n   */\r\n  ttl?: number;\r\n  /**\r\n   * Driver name that emitted the event\r\n   */\r\n  driver: string;\r\n  /**\r\n   * Error object (for error events)\r\n   */\r\n  error?: any;\r\n  /**\r\n   * Namespace (for namespace operations)\r\n   */\r\n  namespace?: string;\r\n};\r\n\r\n/**\r\n * Event handler function type\r\n */\r\nexport type CacheEventHandler = (eventData: CacheEventData) => void | Promise<void>;\r\n\r\n/**\r\n * Per-operation latency + counter snapshot returned by `cache.metrics()`.\r\n *\r\n * The shape is a single recursive level — the top object covers all drivers\r\n * and each entry under `byDriver` repeats the same fields without nesting\r\n * further. Use this for ad-hoc dashboards, exporters to Prometheus / StatsD,\r\n * or just `console.log` during development.\r\n */\r\nexport type CacheMetricsSnapshot = {\r\n  /** Cumulative cache hits across the lifetime of the collector. */\r\n  hits: number;\r\n  /** Cumulative cache misses (lookups that returned null). */\r\n  misses: number;\r\n  /** Cumulative successful writes. */\r\n  sets: number;\r\n  /** Cumulative key removals. */\r\n  removed: number;\r\n  /** Cumulative cache errors emitted via the `error` event. */\r\n  errors: number;\r\n  /** `hits / (hits + misses)` — `0` when no read ops have happened yet. */\r\n  hitRate: number;\r\n  /** Latency percentiles in milliseconds, computed from a circular buffer. */\r\n  latencyMs: {\r\n    p50: number;\r\n    p95: number;\r\n    p99: number;\r\n    /** Size of the underlying buffer at snapshot time (capped at the configured max). */\r\n    samples: number;\r\n  };\r\n  /** Per-driver breakdowns keyed by driver name (`\"memory\"`, `\"redis\"`, …). */\r\n  byDriver: Record<string, Omit<CacheMetricsSnapshot, \"byDriver\">>;\r\n  /** Millisecond timestamp the collector last reset (or was instantiated). */\r\n  startedAt: number;\r\n};\r\n\r\n/**\r\n * Tagged cache interface for working with cache tags\r\n */\r\nexport interface TaggedCacheDriver {\r\n  /**\r\n   * Set a value in cache with tags\r\n   */\r\n  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;\r\n  /**\r\n   * Get a value from cache (checks tags)\r\n   */\r\n  get(key: CacheKey): Promise<any | null>;\r\n  /**\r\n   * Remove a specific key\r\n   */\r\n  remove(key: CacheKey): Promise<void>;\r\n  /**\r\n   * Invalidate (clear) all keys associated with the current tags\r\n   */\r\n  invalidate(): Promise<void>;\r\n  /**\r\n   * Flush all keys associated with the current tags\r\n   * @deprecated Use invalidate() instead\r\n   */\r\n  flush(): Promise<void>;\r\n  /**\r\n   * Check if a key exists\r\n   */\r\n  has(key: CacheKey): Promise<boolean>;\r\n  /**\r\n   * Remember pattern with tags\r\n   */\r\n  remember(key: CacheKey, ttl: number, callback: () => Promise<any>): Promise<any>;\r\n  /**\r\n   * Pull value with tags\r\n   */\r\n  pull(key: CacheKey): Promise<any | null>;\r\n  /**\r\n   * Forever with tags\r\n   */\r\n  forever(key: CacheKey, value: any): Promise<any>;\r\n  /**\r\n   * Increment with tags\r\n   */\r\n  increment(key: CacheKey, value?: number): Promise<number>;\r\n  /**\r\n   * Decrement with tags\r\n   */\r\n  decrement(key: CacheKey, value?: number): Promise<number>;\r\n}\r\n\r\nexport type MemoryCacheOptions = {\r\n  /**\r\n   * The global prefix for the cache key\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * The default TTL for the cache. Accepts a number of seconds or a human-readable\r\n   * duration string like `\"1h\"`, `\"30m\"`, `\"7d\"`.\r\n   *\r\n   * @default Infinity\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Maximum number of items in cache\r\n   * When exceeded, least recently used items will be evicted\r\n   *\r\n   * @default undefined (no limit)\r\n   */\r\n  maxSize?: number;\r\n};\r\n\r\nexport type MemoryExtendedCacheOptions = MemoryCacheOptions;\r\n\r\nexport type LRUMemoryCacheOptions = {\r\n  /**\r\n   * The maximum number of items in the cache\r\n   *\r\n   * @default 1000\r\n   */\r\n  capacity?: number;\r\n  /**\r\n   * The global prefix for the cache key. Applied via `parseCacheKey`, same\r\n   * semantics as the other drivers.\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * The default TTL for new entries. Accepts a number of seconds or a\r\n   * human-readable duration string like `\"1h\"`, `\"30m\"`, `\"7d\"`.\r\n   *\r\n   * @default Infinity\r\n   */\r\n  ttl?: CacheTtl;\r\n};\r\n\r\nexport type FileCacheOptions = {\r\n  /**\r\n   * The global prefix for the cache key\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * The default TTL for the cache. Accepts a number of seconds or a human-readable\r\n   * duration string like `\"1h\"`, `\"30m\"`, `\"7d\"`.\r\n   *\r\n   * @default 0\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Storage cache directory\r\n   *\r\n   * @default storagePath(\"cache\")\r\n   */\r\n  directory: string | (() => string);\r\n  /**\r\n   * File name\r\n   *\r\n   * @default cache.json\r\n   */\r\n  fileName?: string | (() => string);\r\n};\r\n\r\nexport type RedisOptions = {\r\n  /**\r\n   * Redis Port\r\n   *\r\n   * @default 6379\r\n   */\r\n  port?: number;\r\n  /**\r\n   * Redis Host\r\n   */\r\n  host?: string;\r\n  /**\r\n   * Redis Username\r\n   */\r\n  username?: string;\r\n  /**\r\n   * Redis Password\r\n   */\r\n  password?: string;\r\n  /**\r\n   * Redis URL\r\n   *\r\n   * If used, it will override the host and port options\r\n   */\r\n  url?: string;\r\n  /**\r\n   * Global prefix for the cache key\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * Default TTL. Accepts a number of seconds or a human-readable duration string\r\n   * like `\"1h\"`, `\"30m\"`, `\"7d\"`.\r\n   *\r\n   * @default Infinity\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Redis client options\r\n   */\r\n  clientOptions?: RedisClientOptions;\r\n};\r\n\r\nexport type NullCacheDriverOptions = GenericObject;\r\n\r\n/**\r\n * Options accepted by {@link MockCacheDriver}. Same shape as the memory\r\n * driver — only `globalPrefix` and `ttl` apply, since the mock's storage is\r\n * a plain `Map` with no eviction policy.\r\n */\r\nexport type MockCacheOptions = {\r\n  /**\r\n   * Global key prefix, applied via `parseKey` (matches the other drivers).\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * Default TTL for new entries. Accepts seconds or a duration string.\r\n   *\r\n   * @default Infinity\r\n   */\r\n  ttl?: CacheTtl;\r\n};\r\n\r\n/**\r\n * One row in {@link MockCacheDriver.callLog} — captures every public op\r\n * the driver received in arrival order. Useful for behavioral assertions\r\n * in downstream tests (\"did my service actually invalidate the cache?\").\r\n */\r\nexport type CacheCall = {\r\n  /**\r\n   * Operation name as it appears on the driver contract — `\"set\"`, `\"get\"`,\r\n   * `\"remove\"`, `\"flush\"`, `\"removeNamespace\"`, `\"has\"`, etc.\r\n   */\r\n  operation: string;\r\n  /**\r\n   * Post-`parseKey` cache key when the op is key-addressed; `undefined` for\r\n   * keyless ops (`flush`, `connect`, `disconnect`).\r\n   */\r\n  key?: string;\r\n  /**\r\n   * Raw arguments passed to the call site, in declaration order. Lets\r\n   * callers assert on TTLs, options objects, vector payloads, etc.\r\n   */\r\n  args: unknown[];\r\n  /**\r\n   * `Date.now()` when the call was recorded. Useful for timing-related\r\n   * assertions (e.g. \"the second invalidation came within 100ms\").\r\n   */\r\n  timestamp: number;\r\n};\r\n\r\n/**\r\n * Minimal `pg`-compatible client surface the cache driver depends on.\r\n *\r\n * Both `pg.Pool` and `pg.Client` from the `pg` package satisfy this — the\r\n * driver only ever calls `query(text, values)`. Typing it loosely keeps\r\n * `pg` strictly optional: consumers without the `pg` package installed\r\n * never hit a missing import.\r\n */\r\nexport type PgClientLike = {\r\n  query(text: string, values?: unknown[]): Promise<{ rows: any[]; rowCount?: number | null }>;\r\n};\r\n\r\nexport type PgCacheOptions = {\r\n  /**\r\n   * User-supplied `pg.Pool` or `pg.Client`. The driver does NOT own the\r\n   * connection lifecycle — `cache.disconnect()` will not close this client.\r\n   */\r\n  client: PgClientLike;\r\n  /**\r\n   * Database table name. Default: `\"warlock_cache\"`.\r\n   *\r\n   * Sanitized: only `[A-Za-z0-9_]` are allowed; anything else throws\r\n   * {@link CacheConfigurationError} at `setOptions` time.\r\n   */\r\n  table?: string;\r\n  /**\r\n   * Global key prefix, applied via `parseKey` (same semantics as the other drivers).\r\n   */\r\n  globalPrefix?: string | (() => string);\r\n  /**\r\n   * Default TTL for new entries. Accepts seconds or a duration string\r\n   * (`\"1h\"`, `\"7d\"`, …).\r\n   *\r\n   * @default Infinity\r\n   */\r\n  ttl?: CacheTtl;\r\n  /**\r\n   * Optional pgvector configuration. When present, the driver provisions an\r\n   * `embedding VECTOR(dimensions)` column + similarity index, and `similar()`\r\n   * queries via the `<=>` cosine-distance operator.\r\n   *\r\n   * Requires the pgvector extension (`CREATE EXTENSION vector;`) — the driver\r\n   * verifies its presence on the first vector operation and throws\r\n   * {@link CacheConfigurationError} if missing.\r\n   *\r\n   * Omit this block (or remove it) to run the driver in KV-only mode —\r\n   * `set({ vector })` and `similar()` then throw {@link CacheUnsupportedError}.\r\n   */\r\n  vector?: {\r\n    /**\r\n     * Vector dimension count. Must match the embedder you use throughout the\r\n     * lifetime of the table. Mixing dimensions on the same table is unsupported.\r\n     */\r\n    dimensions: number;\r\n    /**\r\n     * pgvector index strategy. `hnsw` (default) is faster to query and slightly\r\n     * slower to build; `ivfflat` is faster to build but typically slower to query.\r\n     *\r\n     * @default \"hnsw\"\r\n     */\r\n    index?: \"hnsw\" | \"ivfflat\";\r\n  };\r\n};\r\n\r\nexport interface CacheDriver<ClientType, Options> {\r\n  /**\r\n   * The cache driver options\r\n   */\r\n  options: Options;\r\n  /**\r\n   * Cache driver name\r\n   */\r\n  name: string;\r\n  /**\r\n   * Set logging state\r\n   */\r\n  setLoggingState(shouldLog: boolean): any;\r\n  /**\r\n   *  Remove all cached items by namespace\r\n   */\r\n  removeNamespace(namespace: string): Promise<any>;\r\n  /**\r\n   * Set the cache driver options\r\n   */\r\n  setOptions(options: Options): any;\r\n  /**\r\n   * Parse the key to be used in the cache\r\n   */\r\n  parseKey(key: CacheKey): string;\r\n  /**\r\n   * Set a value in the cache.\r\n   *\r\n   * @param key The cache key, could be an object or string\r\n   * @param value The value to be stored in the cache\r\n   * @param ttlOrOptions Either a TTL (seconds number, or duration string like `\"1h\"`),\r\n   *                     or a full {@link CacheSetOptions} object.\r\n   *\r\n   * @example\r\n   * // Positional TTL (back-compat)\r\n   * await cache.set(\"user:1\", user, 3600);\r\n   *\r\n   * @example\r\n   * // Human-readable duration\r\n   * await cache.set(\"user:1\", user, \"1h\");\r\n   *\r\n   * @example\r\n   * // Rich options\r\n   * await cache.set(\"user:1\", user, { ttl: \"1h\", tags: [\"users\"], onConflict: \"create\" });\r\n   */\r\n  set(\r\n    key: CacheKey,\r\n    value: any,\r\n    ttlOrOptions?: CacheTtl | CacheSetOptions,\r\n  ): Promise<any>;\r\n  /**\r\n   * Get a value from the cache\r\n   */\r\n  get<T = any>(key: CacheKey): Promise<T | null>;\r\n  /**\r\n   * Remove a value from the cache\r\n   */\r\n  remove(key: CacheKey): Promise<void>;\r\n  /**\r\n   * Flush the entire cache\r\n   */\r\n  flush(): Promise<void>;\r\n  /**\r\n   * Connect to the cache driver\r\n   */\r\n  connect(): Promise<any>;\r\n  /**\r\n   * The cache client\r\n   */\r\n  client?: ClientType;\r\n  /**\r\n   * Disconnect the cache driver\r\n   */\r\n  disconnect(): Promise<void>;\r\n  /**\r\n   * Check if a key exists in the cache without fetching its value\r\n   */\r\n  has(key: CacheKey): Promise<boolean>;\r\n  /**\r\n   * Get value from cache or execute callback and cache the result.\r\n   *\r\n   * The second argument accepts a TTL (number of seconds or duration string like `\"1h\"`)\r\n   * or a full {@link RememberOptions} object when you need to attach tags or route to\r\n   * a non-default driver.\r\n   *\r\n   * @example\r\n   * // Positional TTL — the common case\r\n   * const user = await cache.remember(\"user.1\", \"1h\", () => db.users.find(1));\r\n   *\r\n   * @example\r\n   * // Options form — tag the cache-miss write for bulk invalidation\r\n   * const user = await cache.remember(\"user.1\", { ttl: \"1h\", tags: [\"users\"] }, () =>\r\n   *   db.users.find(1),\r\n   * );\r\n   */\r\n  remember<T = any>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | RememberOptions,\r\n    callback: () => Promise<T>,\r\n  ): Promise<T>;\r\n  /**\r\n   * Stale-while-revalidate. Returns the cached value when fresh; returns\r\n   * the stale value + kicks off a background refresh when within the\r\n   * `freshTtl..staleTtl` window; blocks like a normal miss when past\r\n   * `staleTtl`. Concurrent stale-window callers share one in-flight\r\n   * refresh.\r\n   *\r\n   * Background refresh failures preserve the stale entry and emit an\r\n   * `error` event — the stale-returning caller never sees the failure.\r\n   *\r\n   * @example\r\n   * const product = await cache.swr(\r\n   *   \"product.42\",\r\n   *   { freshTtl: \"1m\", staleTtl: \"1h\" },\r\n   *   () => db.products.find(42),\r\n   * );\r\n   */\r\n  swr<T = any>(\r\n    key: CacheKey,\r\n    options: CacheSwrOptions,\r\n    callback: () => Promise<T>,\r\n  ): Promise<T>;\r\n  /**\r\n   * Get value and remove it from cache (atomic operation)\r\n   */\r\n  pull<T = any>(key: CacheKey): Promise<T | null>;\r\n  /**\r\n   * Set a value in cache permanently (no expiration)\r\n   */\r\n  forever<T = any>(key: CacheKey, value: T): Promise<T>;\r\n  /**\r\n   * Atomically read, transform, and write a cached value.\r\n   *\r\n   * The callback receives the current value (or `null` on miss) and returns the\r\n   * next value. Returning `null` removes the key. TTL is preserved unless\r\n   * explicitly overridden via options.\r\n   *\r\n   * @example\r\n   * await cache.update<User>(\"user:1\", (current) => {\r\n   *   if (!current) return null;\r\n   *   return { ...current, lastSeen: Date.now() };\r\n   * });\r\n   */\r\n  update<T = any>(\r\n    key: CacheKey,\r\n    fn: (current: T | null) => T | null | Promise<T | null>,\r\n    options?: { ttl?: CacheTtl },\r\n  ): Promise<T | null>;\r\n  /**\r\n   * Shallow-merge a partial object into a cached value.\r\n   *\r\n   * If the key is missing, treats the current value as `{}`. Preserves TTL by default.\r\n   *\r\n   * @example\r\n   * await cache.merge<User>(\"user:1\", { name: \"Jane\" });\r\n   */\r\n  merge<T extends Record<string, any> = Record<string, any>>(\r\n    key: CacheKey,\r\n    partial: Partial<T>,\r\n    options?: { ttl?: CacheTtl },\r\n  ): Promise<T>;\r\n  /**\r\n   * List sub-API factory — returns a {@link CacheListAccessor} bound to the given key.\r\n   *\r\n   * @example\r\n   * const recent = cache.list<Event>(\"recent-events\");\r\n   * await recent.push(event);\r\n   * const last10 = await recent.slice(0, 10);\r\n   */\r\n  list<T = any>(key: CacheKey): CacheListAccessor<T>;\r\n  /**\r\n   * Acquire a distributed lock, run `fn`, and auto-release. Returns a\r\n   * {@link LockOutcome} so callers can distinguish \"ran and produced this value\"\r\n   * from \"skipped because someone else holds the lock.\"\r\n   *\r\n   * Built on top of `set({ onConflict: \"create\" })` — Redis-native, emulated\r\n   * on other drivers (single-process semantics elsewhere).\r\n   *\r\n   * @example\r\n   * const outcome = await cache.lock(\"lock.import\", \"5m\", async () => {\r\n   *   await runImport();\r\n   *   return \"done\";\r\n   * });\r\n   */\r\n  lock<T>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\r\n    fn: () => Promise<T>,\r\n  ): Promise<LockOutcome<T>>;\r\n  /**\r\n   * Increment a numeric value in cache\r\n   *\r\n   * @param key The cache key\r\n   * @param value The value to increment by (default 1)\r\n   */\r\n  increment(key: CacheKey, value?: number): Promise<number>;\r\n  /**\r\n   * Decrement a numeric value in cache\r\n   *\r\n   * @param key The cache key\r\n   * @param value The value to decrement by (default 1)\r\n   */\r\n  decrement(key: CacheKey, value?: number): Promise<number>;\r\n  /**\r\n   * Get multiple values from cache at once\r\n   */\r\n  many(keys: CacheKey[]): Promise<any[]>;\r\n  /**\r\n   * Set multiple values in cache at once\r\n   */\r\n  setMany(items: Record<string, any>, ttl?: number): Promise<void>;\r\n  /**\r\n   * Register an event listener\r\n   */\r\n  on(event: CacheEventType, handler: CacheEventHandler): this;\r\n  /**\r\n   * Remove an event listener\r\n   */\r\n  off(event: CacheEventType, handler: CacheEventHandler): this;\r\n  /**\r\n   * Register a one-time event listener\r\n   */\r\n  once(event: CacheEventType, handler: CacheEventHandler): this;\r\n  /**\r\n   * Set if not exists (atomic operation)\r\n   * Returns true if key was set, false if key already existed\r\n   * Note: Not all drivers support this operation\r\n   */\r\n  setNX?(key: CacheKey, value: any, ttl?: number): Promise<boolean>;\r\n  /**\r\n   * Create a tagged cache instance for the given tags\r\n   */\r\n  tags(tags: string[]): TaggedCacheDriver;\r\n  /**\r\n   * Similarity retrieval. Returns the nearest stored entries to `vector` by\r\n   * cosine similarity, ordered by descending score.\r\n   *\r\n   * Drivers without a similarity index throw {@link CacheUnsupportedError}.\r\n   * Memory-family drivers brute-force scan in O(N) — suitable for development\r\n   * but not for production knowledge bases beyond a few thousand entries; use\r\n   * the `pg` driver (with pgvector) or `redis` driver (with RediSearch) instead.\r\n   *\r\n   * @example\r\n   * const hits = await cache.similar(await embed(query), { topK: 5, threshold: 0.7 });\r\n   */\r\n  similar<T = any>(\r\n    vector: number[],\r\n    options: CacheSimilarOptions,\r\n  ): Promise<CacheSimilarHit<T>[]>;\r\n}\r\n\r\n/**\r\n * Accessor for list-shaped cached values.\r\n *\r\n * Defaults to read-mutate-write semantics on non-native drivers (memory, file, LRU).\r\n * The Redis driver overrides this with native `LPUSH` / `RPUSH` / `LRANGE` / `LTRIM` for O(1) ops.\r\n */\r\nexport interface CacheListAccessor<T = any> {\r\n  /**\r\n   * Append one or more items to the tail of the list. Returns the new length.\r\n   */\r\n  push(...items: T[]): Promise<number>;\r\n  /**\r\n   * Prepend one or more items to the head of the list. Returns the new length.\r\n   */\r\n  unshift(...items: T[]): Promise<number>;\r\n  /**\r\n   * Remove and return the tail item, or `null` if the list is empty.\r\n   */\r\n  pop(): Promise<T | null>;\r\n  /**\r\n   * Remove and return the head item, or `null` if the list is empty.\r\n   */\r\n  shift(): Promise<T | null>;\r\n  /**\r\n   * Return a slice of the list. End is exclusive, mirroring `Array.prototype.slice`.\r\n   */\r\n  slice(start?: number, end?: number): Promise<T[]>;\r\n  /**\r\n   * Return the full list.\r\n   */\r\n  all(): Promise<T[]>;\r\n  /**\r\n   * Return the length of the list.\r\n   */\r\n  length(): Promise<number>;\r\n  /**\r\n   * Trim the list to the inclusive range `[start, end]`. Outside elements are dropped.\r\n   */\r\n  trim(start: number, end: number): Promise<void>;\r\n  /**\r\n   * Remove the entire list.\r\n   */\r\n  clear(): Promise<void>;\r\n}\r\n\r\n/**\r\n * One-shot tagged handle returned by `ScopedCacheContract.tags(...)`.\r\n *\r\n * Identical write surface to {@link TaggedCacheDriver}, except the underlying\r\n * scope's prefix is applied to every key and the scope's default TTL/tags\r\n * still flow through. Tags supplied here merge additively with scope-level\r\n * tags.\r\n */\r\nexport interface TaggedScopedCacheContract {\r\n  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;\r\n  get<T = any>(key: CacheKey): Promise<T | null>;\r\n  has(key: CacheKey): Promise<boolean>;\r\n  remove(key: CacheKey): Promise<void>;\r\n  pull<T = any>(key: CacheKey): Promise<T | null>;\r\n  forever<T = any>(key: CacheKey, value: T): Promise<T>;\r\n  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;\r\n  remember<T = any>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | RememberOptions,\r\n    callback: () => Promise<T>,\r\n  ): Promise<T>;\r\n  increment(key: CacheKey, value?: number): Promise<number>;\r\n  decrement(key: CacheKey, value?: number): Promise<number>;\r\n  /**\r\n   * Invalidate every entry tagged with the union of scope tags + handle tags.\r\n   * Forwarded to the underlying tag index — tags are global, scope-agnostic.\r\n   */\r\n  invalidate(): Promise<void>;\r\n}\r\n\r\n/**\r\n * Scoped view over the cache. Returned by `cache.namespace(prefix, options?)`.\r\n *\r\n * A scope prepends its `prefix` to every key, applies optional default TTL/tags\r\n * to every write, and forwards everything else to the underlying source. It\r\n * stores nothing of its own — purely a convenience wrapper.\r\n *\r\n * @example\r\n * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\r\n * await chat.set(\"messages.1\", msg);          // → \"chats.10.messages.1\", TTL 30d\r\n * await chat.set(\"draft\", d, { ttl: \"1h\" });  // per-call ttl wins\r\n * await chat.clear();                          // wipe the whole scope\r\n */\r\nexport interface ScopedCacheContract {\r\n  /** The fully-qualified prefix this scope prepends to every key. */\r\n  readonly prefix: string;\r\n\r\n  /**\r\n   * Nested scope. Inherits the parent's defaults; child's own options override.\r\n   *\r\n   * @example\r\n   * const chat = cache.namespace(\"chats.10\", { ttl: \"30d\" });\r\n   * const typing = chat.namespace(\"typing\", { ttl: \"5s\" });\r\n   * // typing.prefix === \"chats.10.typing\"\r\n   */\r\n  namespace(prefix: string, options?: CacheNamespaceOptions): ScopedCacheContract;\r\n\r\n  /**\r\n   * One-shot tagged write handle. Tags merge additively with scope defaults.\r\n   */\r\n  tags(tags: string[]): TaggedScopedCacheContract;\r\n\r\n  /** Wipe every entry under this scope's prefix. Sugar for `removeNamespace(prefix)`. */\r\n  clear(): Promise<void>;\r\n\r\n  // Reads\r\n  get<T = any>(key: CacheKey): Promise<T | null>;\r\n  has(key: CacheKey): Promise<boolean>;\r\n  many(keys: CacheKey[]): Promise<any[]>;\r\n  pull<T = any>(key: CacheKey): Promise<T | null>;\r\n\r\n  // Writes\r\n  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;\r\n  setMany(items: Record<string, any>, ttl?: number): Promise<void>;\r\n  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;\r\n  forever<T = any>(key: CacheKey, value: T): Promise<T>;\r\n  remove(key: CacheKey): Promise<void>;\r\n\r\n  // Read-or-compute\r\n  remember<T = any>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | RememberOptions,\r\n    callback: () => Promise<T>,\r\n  ): Promise<T>;\r\n  swr<T = any>(\r\n    key: CacheKey,\r\n    options: CacheSwrOptions,\r\n    callback: () => Promise<T>,\r\n  ): Promise<T>;\r\n\r\n  // Mutations\r\n  increment(key: CacheKey, value?: number): Promise<number>;\r\n  decrement(key: CacheKey, value?: number): Promise<number>;\r\n  update<T = any>(\r\n    key: CacheKey,\r\n    fn: (current: T | null) => T | null | Promise<T | null>,\r\n    options?: { ttl?: CacheTtl },\r\n  ): Promise<T | null>;\r\n  merge<T extends Record<string, any> = Record<string, any>>(\r\n    key: CacheKey,\r\n    partial: Partial<T>,\r\n    options?: { ttl?: CacheTtl },\r\n  ): Promise<T>;\r\n\r\n  // Structured accessors\r\n  list<T = any>(key: CacheKey): CacheListAccessor<T>;\r\n\r\n  // Coordination\r\n  lock<T>(\r\n    key: CacheKey,\r\n    ttlOrOptions: CacheTtl | Omit<LockOptions, \"driver\">,\r\n    fn: () => Promise<T>,\r\n  ): Promise<LockOutcome<T>>;\r\n\r\n  // Similarity (delegated; throws CacheUnsupportedError if the driver lacks it)\r\n  similar<T = any>(\r\n    vector: number[],\r\n    options: CacheSimilarOptions,\r\n  ): Promise<CacheSimilarHit<T>[]>;\r\n}\r\n\r\nexport type CacheData = {\r\n  /**\r\n   * Value stored in the cache\r\n   */\r\n  data: any;\r\n  /**\r\n   * The expiration date in milliseconds\r\n   */\r\n  expiresAt?: number;\r\n  /**\r\n   * Time to live in seconds\r\n   */\r\n  ttl?: number;\r\n  /**\r\n   * Freshness deadline as a millisecond timestamp. Used by `swr()` — entries\r\n   * with `staleAt` in the future are \"fresh\"; past `staleAt` but before\r\n   * `expiresAt` are \"stale-but-revalidatable\" and trigger a background\r\n   * refresh on the next read. Optional — entries written through plain\r\n   * `set()` skip this field entirely and `swr()` treats them as always-fresh.\r\n   */\r\n  staleAt?: number;\r\n};\r\n\r\nexport type DriverClass = new () => CacheDriver<any, any>;\r\n\r\ntype DefaultDrivers =\r\n  | \"redis\"\r\n  | \"file\"\r\n  | \"memory\"\r\n  | \"memoryExtended\"\r\n  | \"null\"\r\n  | \"lru\"\r\n  | \"pg\"\r\n  | \"mock\";\r\n\r\ntype MergeWithDefaultDrivers<T> = T extends undefined ? DefaultDrivers : DefaultDrivers | T;\r\n\r\nexport type CacheConfigurations<\r\n  T extends string | undefined = undefined,\r\n  DriverName = MergeWithDefaultDrivers<T>,\r\n> = {\r\n  /**\r\n   * The default cache driver name\r\n   */\r\n  default?: DriverName;\r\n  /**\r\n   * Determine whether to log or not\r\n   *\r\n   * @default true\r\n   */\r\n  logging?: boolean;\r\n  /**\r\n   * The cache drivers list\r\n   */\r\n  drivers: {\r\n    redis?: typeof RedisCacheDriver;\r\n    file?: typeof FileCacheDriver;\r\n    null?: typeof NullCacheDriver;\r\n    memory?: typeof MemoryCacheDriver;\r\n    memoryExtended?: typeof MemoryExtendedCacheDriver;\r\n    lru?: typeof LRUMemoryCacheDriver;\r\n    pg?: typeof PgCacheDriver;\r\n    mock?: typeof MockCacheDriver;\r\n  } & {\r\n    [key in Extract<T, string>]?: typeof BaseCacheDriver<any, any> | undefined;\r\n  };\r\n  /**\r\n   * The cache driver options\r\n   */\r\n  options: {\r\n    redis?: RedisOptions;\r\n    file?: FileCacheOptions;\r\n    memory?: MemoryCacheOptions;\r\n    memoryExtended?: MemoryExtendedCacheOptions;\r\n    null?: NullCacheDriverOptions;\r\n    lru?: LRUMemoryCacheOptions;\r\n    pg?: PgCacheOptions;\r\n    mock?: MockCacheOptions;\r\n  } & {\r\n    [key in Extract<T, string>]?: GenericObject;\r\n  };\r\n};\r\n"],"mappings":";;;;AAiBA,IAAa,aAAb,cAAgC,MAAM;CACpC,AAAO,YAAY,SAAiB;EAClC,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,uBAAb,cAA0C,WAAW;CACnD,AAAO,YAAY,SAAiB;EAClC,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,0BAAb,cAA6C,WAAW;CACtD,AAAO,YAAY,SAAiB;EAClC,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,iCAAb,cAAoD,WAAW;CAC7D,AAAO,YACL,UAAkB,wEAClB;EACA,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;;;;AAQA,IAAa,wBAAb,cAA2C,WAAW;CACpD,AAAO,YAAY,SAAiB;EAClC,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;;;;AAKA,IAAa,wBAAb,cAA2C,WAAW;CACpD,AAAO,YAAY,SAAiB;EAClC,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}

package/esm/utils.d.mts

@@ -0,0 +1,161 @@
+import { CacheKey, CacheSetOptions, CacheTtl, RememberOptions } from "./types.mjs";
+
+//#region ../../@warlock.js/cache/src/utils.d.ts
+/**
+ * Make a proper key for the cache
+ */
+declare function parseCacheKey(key: CacheKey, options?: {
+  globalPrefix?: string | (() => string);
+}): string;
+/**
+ * Parse a TTL value into seconds.
+ *
+ * Accepts:
+ * - a number (already in seconds) — returned unchanged
+ * - `Infinity` — no expiration, returned unchanged
+ * - a human-readable duration string (e.g. `"1h"`, `"30m"`, `"7d"`) — parsed via `ms` then converted to seconds
+ *
+ * Throws `CacheConfigurationError` on unparseable strings or negative numbers.
+ *
+ * @example
+ * parseTtl(3600);      // 3600
+ * parseTtl("1h");      // 3600
+ * parseTtl("7d");      // 604800
+ * parseTtl(Infinity);  // Infinity
+ */
+declare function parseTtl(input: CacheTtl): number;
+/**
+ * Convert an absolute `expiresAt` (Date or epoch milliseconds) into a
+ * relative TTL in seconds.
+ *
+ * Throws {@link CacheConfigurationError} when the deadline is in the past —
+ * the caller almost certainly has a bug (stale timestamp, wrong unit, etc.)
+ * and silently storing an already-expired entry would hide it.
+ *
+ * @example
+ * expiresAtToTtl(new Date(Date.now() + 60_000));   // ~60
+ * expiresAtToTtl(Date.now() + 30 * 60 * 1000);     // ~1800
+ */
+declare function expiresAtToTtl(expiresAt: number | Date): number;
+/**
+ * Coerce the polymorphic 3rd `set` argument into a uniform `CacheSetOptions`
+ * shape. Lets callers (and `BaseCacheDriver.resolveSetOptions`) skip per-shape
+ * branching.
+ *
+ * - `undefined` / `null` → `{}` (resolves to driver-level defaults later)
+ * - `number` / `string` (positional TTL) → `{ ttl }`
+ * - already an options object → returned as-is
+ */
+declare function normalizeToOptions(input?: CacheTtl | CacheSetOptions): CacheSetOptions;
+/**
+ * Sibling of {@link normalizeToOptions} for the `remember()` call site, where
+ * the polymorphic 2nd argument is `CacheTtl | RememberOptions` (no `expiresAt`,
+ * no `onConflict`). Returns the same shape so callers can `{ ...opts, ... }`
+ * without branching.
+ *
+ * @example
+ * normalizeToRememberOptions(60);             // { ttl: 60 }
+ * normalizeToRememberOptions("1h");           // { ttl: "1h" }
+ * normalizeToRememberOptions({ ttl: "1h", tags: ["x"] }); // returned as-is
+ */
+declare function normalizeToRememberOptions(input?: CacheTtl | RememberOptions): RememberOptions;
+/**
+ * Resolve the final TTL in seconds for a `set` call. Precedence:
+ *
+ * 1. Caller's `ttl` (number or duration string) wins.
+ * 2. Otherwise, caller's `expiresAt` is converted to relative seconds.
+ * 3. Otherwise, `fallback` is used (driver-level default — typically
+ *    `Infinity` when no default is configured, meaning "never expires").
+ *
+ * Throws {@link CacheConfigurationError} when `ttl` and `expiresAt` are
+ * supplied together (mutually exclusive).
+ */
+declare function resolveTtl(ttl: CacheTtl | undefined, expiresAt: number | Date | undefined, fallback: number): number;
+/**
+ * Combine any number of tag lists into a single deduped array, dropping
+ * `undefined`/empty entries. Returns `undefined` when no tags survive — lets
+ * callers skip emitting empty `tags: []` into option payloads.
+ *
+ * Used by scoped-cache merging where scope tags + handle tags + per-call tags
+ * must union additively without duplicates.
+ *
+ * @example
+ * mergeTagSets(["a", "b"], ["b", "c"]);          // ["a", "b", "c"]
+ * mergeTagSets(undefined, ["x"]);                // ["x"]
+ * mergeTagSets(undefined, undefined);            // undefined
+ * mergeTagSets([], []);                          // undefined
+ */
+declare function mergeTagSets(...lists: (string[] | undefined)[]): string[] | undefined;
+/**
+ * Add extra tags to any option-bag that already shapes `tags?: string[]`.
+ * Pure — clones the input shape, never mutates. Tags are appended (caller
+ * is responsible for de-duplication if needed; pair with {@link mergeTagSets}).
+ *
+ * @example
+ * injectTags({ ttl: "1h" }, ["unread"]);         // { ttl: "1h", tags: ["unread"] }
+ * injectTags({ tags: ["a"] }, ["b"]);            // { tags: ["a", "b"] }
+ */
+declare function injectTags<T extends {
+  tags?: string[];
+}>(options: T, extraTags: string[]): T;
+/**
+ * Cosine similarity between two equal-length numeric vectors.
+ *
+ * Returns a value in `[-1, 1]` where `1` means perfectly aligned, `0` means
+ * orthogonal, and `-1` means opposing. For typical embedding spaces (where
+ * vectors live in the positive cone) the practical range is `[0, 1]`.
+ *
+ * Throws {@link CacheConfigurationError} on dimension mismatch — fail loud at
+ * the call site rather than silently returning a misleading score. A zero-norm
+ * vector on either side returns `0` (no defined direction to compare).
+ *
+ * @example
+ * cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
+ * cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+declare enum CACHE_FOR {
+  /**
+   * Cache for 30 Minutes (in seconds)
+   */
+  HALF_HOUR = 1800,
+  /**
+   * Cache for 1 Hour (in seconds)
+   */
+  ONE_HOUR = 3600,
+  /**
+   * Cache for 12 Hours (in seconds)
+   */
+  HALF_DAY = 43200,
+  /**
+   * Cache for 24 Hours (in seconds)
+   */
+  ONE_DAY = 86400,
+  /**
+   * Cache for 7 Days (in seconds)
+   */
+  ONE_WEEK = 604800,
+  /**
+   * Cache for 15 Days (in seconds)
+   */
+  HALF_MONTH = 1296000,
+  /**
+   * Cache for 30 Days (in seconds)
+   */
+  ONE_MONTH = 2592000,
+  /**
+   * Cache for 60 Days (in seconds)
+   */
+  TWO_MONTHS = 5184000,
+  /**
+   * Cache for 180 Days (in seconds)
+   */
+  SIX_MONTHS = 15768000,
+  /**
+   * Cache for 365 Days (in seconds)
+   */
+  ONE_YEAR = 31536000
+}
+//#endregion
+export { CACHE_FOR, cosineSimilarity, expiresAtToTtl, injectTags, mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl };
+//# sourceMappingURL=utils.d.mts.map

package/esm/utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../../../../../@warlock.js/cache/src/utils.ts"],"mappings":";;;;;AAQA;iBAAgB,aAAA,CACd,GAAA,EAAK,QAAQ,EACb,OAAA;EAAW,YAAA;AAAA;;;;;;AAA6C;AA+B1D;;;;AAAwC;AAsCxC;;;;AAAuD;iBAtCvC,QAAA,CAAS,KAAe,EAAR,QAAQ;;;;;;;;;;;;;iBAsCxB,cAAA,CAAe,SAAwB,WAAJ,IAAI;AA+CvD;;;;;;;;;AAAA,iBAzBgB,kBAAA,CACd,KAAA,GAAQ,QAAA,GAAW,eAAA,GAClB,eAAA;;;;AAyBe;AAuBlB;;;;;;;iBAzBgB,0BAAA,CACd,KAAA,GAAQ,QAAA,GAAW,eAAA,GAClB,eAAA;;;AA0Be;AAiClB;;;;AACU;AA4BV;;;iBAjEgB,UAAA,CACd,GAAA,EAAK,QAAA,cACL,SAAA,WAAoB,IAAI,cACxB,QAAA;;;;;;;;AAiEE;AA0BJ;;;;AAAyD;AAgCzD;iBA1FgB,YAAA,CAAA,GACX,KAAK;;;;;;;;;;iBA4BM,UAAA;EAAuB,IAAA;AAAA,EAAA,CACrC,OAAA,EAAS,CAAA,EACT,SAAA,aACC,CAAC;;AAkGM;;;;;;;;;;;;;;iBAxEM,gBAAA,CAAiB,CAAA,YAAa,CAAW;AAAA,aAgC7C,SAAA;;;;EAIV,SAAA;;;;EAIA,QAAA;;;;EAIA,QAAA;;;;EAIA,OAAA;;;;EAIA,QAAA;;;;EAIA,UAAA;;;;EAIA,SAAA;;;;EAIA,UAAA;;;;EAIA,UAAA;;;;EAIA,QAAA;AAAA"}

package/esm/utils.mjs

@@ -0,0 +1,222 @@
+import { CacheConfigurationError } from "./types.mjs";
+import { rtrim } from "@mongez/reinforcements";
+import ms from "ms";
+
+//#region ../../@warlock.js/cache/src/utils.ts
+/**
+* Make a proper key for the cache
+*/
+function parseCacheKey(key, options = {}) {
+	if (typeof key === "object") key = JSON.stringify(key);
+	key = key.replace(/[{}"[\]]/g, "").replaceAll(/[:,]/g, ".");
+	const cachePrefix = typeof options.globalPrefix === "function" ? options.globalPrefix() : options.globalPrefix;
+	return rtrim(String(cachePrefix ? rtrim(cachePrefix, ".") + "." + key : key), ".");
+}
+/**
+* Parse a TTL value into seconds.
+*
+* Accepts:
+* - a number (already in seconds) — returned unchanged
+* - `Infinity` — no expiration, returned unchanged
+* - a human-readable duration string (e.g. `"1h"`, `"30m"`, `"7d"`) — parsed via `ms` then converted to seconds
+*
+* Throws `CacheConfigurationError` on unparseable strings or negative numbers.
+*
+* @example
+* parseTtl(3600);      // 3600
+* parseTtl("1h");      // 3600
+* parseTtl("7d");      // 604800
+* parseTtl(Infinity);  // Infinity
+*/
+function parseTtl(input) {
+	if (typeof input === "number") {
+		if (input < 0) throw new CacheConfigurationError(`Invalid TTL: negative number (${input}).`);
+		return input;
+	}
+	if (typeof input !== "string" || input.trim() === "") throw new CacheConfigurationError(`Invalid TTL: expected number or duration string, got ${typeof input}.`);
+	const milliseconds = ms(input);
+	if (milliseconds === void 0 || Number.isNaN(milliseconds)) throw new CacheConfigurationError(`Invalid TTL duration string: "${input}". Expected forms like "1h", "30m", "7d".`);
+	return Math.floor(milliseconds / 1e3);
+}
+/**
+* Convert an absolute `expiresAt` (Date or epoch milliseconds) into a
+* relative TTL in seconds.
+*
+* Throws {@link CacheConfigurationError} when the deadline is in the past —
+* the caller almost certainly has a bug (stale timestamp, wrong unit, etc.)
+* and silently storing an already-expired entry would hide it.
+*
+* @example
+* expiresAtToTtl(new Date(Date.now() + 60_000));   // ~60
+* expiresAtToTtl(Date.now() + 30 * 60 * 1000);     // ~1800
+*/
+function expiresAtToTtl(expiresAt) {
+	const deadline = expiresAt instanceof Date ? expiresAt.getTime() : expiresAt;
+	const relativeMs = deadline - Date.now();
+	if (relativeMs <= 0) throw new CacheConfigurationError(`\`expiresAt\` must be in the future; got ${new Date(deadline).toISOString()}.`);
+	return Math.ceil(relativeMs / 1e3);
+}
+/**
+* Coerce the polymorphic 3rd `set` argument into a uniform `CacheSetOptions`
+* shape. Lets callers (and `BaseCacheDriver.resolveSetOptions`) skip per-shape
+* branching.
+*
+* - `undefined` / `null` → `{}` (resolves to driver-level defaults later)
+* - `number` / `string` (positional TTL) → `{ ttl }`
+* - already an options object → returned as-is
+*/
+function normalizeToOptions(input) {
+	if (input === void 0 || input === null) return {};
+	if (typeof input === "number" || typeof input === "string") return { ttl: input };
+	return input;
+}
+/**
+* Sibling of {@link normalizeToOptions} for the `remember()` call site, where
+* the polymorphic 2nd argument is `CacheTtl | RememberOptions` (no `expiresAt`,
+* no `onConflict`). Returns the same shape so callers can `{ ...opts, ... }`
+* without branching.
+*
+* @example
+* normalizeToRememberOptions(60);             // { ttl: 60 }
+* normalizeToRememberOptions("1h");           // { ttl: "1h" }
+* normalizeToRememberOptions({ ttl: "1h", tags: ["x"] }); // returned as-is
+*/
+function normalizeToRememberOptions(input) {
+	if (input === void 0 || input === null) return {};
+	if (typeof input === "number" || typeof input === "string") return { ttl: input };
+	return input;
+}
+/**
+* Resolve the final TTL in seconds for a `set` call. Precedence:
+*
+* 1. Caller's `ttl` (number or duration string) wins.
+* 2. Otherwise, caller's `expiresAt` is converted to relative seconds.
+* 3. Otherwise, `fallback` is used (driver-level default — typically
+*    `Infinity` when no default is configured, meaning "never expires").
+*
+* Throws {@link CacheConfigurationError} when `ttl` and `expiresAt` are
+* supplied together (mutually exclusive).
+*/
+function resolveTtl(ttl, expiresAt, fallback) {
+	if (ttl !== void 0 && expiresAt !== void 0) throw new CacheConfigurationError("Cache set options cannot specify both `ttl` and `expiresAt` — choose one.");
+	if (ttl !== void 0) return parseTtl(ttl);
+	if (expiresAt !== void 0) return expiresAtToTtl(expiresAt);
+	return fallback;
+}
+/**
+* Combine any number of tag lists into a single deduped array, dropping
+* `undefined`/empty entries. Returns `undefined` when no tags survive — lets
+* callers skip emitting empty `tags: []` into option payloads.
+*
+* Used by scoped-cache merging where scope tags + handle tags + per-call tags
+* must union additively without duplicates.
+*
+* @example
+* mergeTagSets(["a", "b"], ["b", "c"]);          // ["a", "b", "c"]
+* mergeTagSets(undefined, ["x"]);                // ["x"]
+* mergeTagSets(undefined, undefined);            // undefined
+* mergeTagSets([], []);                          // undefined
+*/
+function mergeTagSets(...lists) {
+	const flat = [];
+	for (const list of lists) {
+		if (!list || list.length === 0) continue;
+		flat.push(...list);
+	}
+	if (flat.length === 0) return;
+	return Array.from(new Set(flat));
+}
+/**
+* Add extra tags to any option-bag that already shapes `tags?: string[]`.
+* Pure — clones the input shape, never mutates. Tags are appended (caller
+* is responsible for de-duplication if needed; pair with {@link mergeTagSets}).
+*
+* @example
+* injectTags({ ttl: "1h" }, ["unread"]);         // { ttl: "1h", tags: ["unread"] }
+* injectTags({ tags: ["a"] }, ["b"]);            // { tags: ["a", "b"] }
+*/
+function injectTags(options, extraTags) {
+	if (extraTags.length === 0) return options;
+	return {
+		...options,
+		tags: [...options.tags ?? [], ...extraTags]
+	};
+}
+/**
+* Cosine similarity between two equal-length numeric vectors.
+*
+* Returns a value in `[-1, 1]` where `1` means perfectly aligned, `0` means
+* orthogonal, and `-1` means opposing. For typical embedding spaces (where
+* vectors live in the positive cone) the practical range is `[0, 1]`.
+*
+* Throws {@link CacheConfigurationError} on dimension mismatch — fail loud at
+* the call site rather than silently returning a misleading score. A zero-norm
+* vector on either side returns `0` (no defined direction to compare).
+*
+* @example
+* cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1
+* cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0
+*/
+function cosineSimilarity(a, b) {
+	if (a.length !== b.length) throw new CacheConfigurationError(`Vector dimension mismatch: got ${a.length} and ${b.length}.`);
+	if (a.length === 0) throw new CacheConfigurationError("Vector dimension mismatch: empty vector cannot be compared.");
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i];
+		const y = b[i];
+		dot += x * y;
+		normA += x * x;
+		normB += y * y;
+	}
+	if (normA === 0 || normB === 0) return 0;
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+let CACHE_FOR = /* @__PURE__ */ function(CACHE_FOR) {
+	/**
+	* Cache for 30 Minutes (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_HOUR"] = 1800] = "HALF_HOUR";
+	/**
+	* Cache for 1 Hour (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_HOUR"] = 3600] = "ONE_HOUR";
+	/**
+	* Cache for 12 Hours (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_DAY"] = 43200] = "HALF_DAY";
+	/**
+	* Cache for 24 Hours (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_DAY"] = 86400] = "ONE_DAY";
+	/**
+	* Cache for 7 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_WEEK"] = 604800] = "ONE_WEEK";
+	/**
+	* Cache for 15 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["HALF_MONTH"] = 1296e3] = "HALF_MONTH";
+	/**
+	* Cache for 30 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_MONTH"] = 2592e3] = "ONE_MONTH";
+	/**
+	* Cache for 60 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["TWO_MONTHS"] = 5184e3] = "TWO_MONTHS";
+	/**
+	* Cache for 180 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["SIX_MONTHS"] = 15768e3] = "SIX_MONTHS";
+	/**
+	* Cache for 365 Days (in seconds)
+	*/
+	CACHE_FOR[CACHE_FOR["ONE_YEAR"] = 31536e3] = "ONE_YEAR";
+	return CACHE_FOR;
+}({});
+
+//#endregion
+export { CACHE_FOR, cosineSimilarity, expiresAtToTtl, injectTags, mergeTagSets, normalizeToOptions, normalizeToRememberOptions, parseCacheKey, parseTtl, resolveTtl };
+//# sourceMappingURL=utils.mjs.map

package/esm/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.mjs","names":[],"sources":["../../../../../@warlock.js/cache/src/utils.ts"],"sourcesContent":["import { rtrim } from \"@mongez/reinforcements\";\r\nimport ms, { StringValue } from \"ms\";\r\nimport type { CacheKey, CacheSetOptions, CacheTtl, RememberOptions } from \"./types\";\r\nimport { CacheConfigurationError } from \"./types\";\r\n\r\n/**\r\n * Make a proper key for the cache\r\n */\r\nexport function parseCacheKey(\r\n  key: CacheKey,\r\n  options: { globalPrefix?: string | (() => string) } = {},\r\n): string {\r\n  if (typeof key === \"object\") {\r\n    key = JSON.stringify(key);\r\n  }\r\n\r\n  // remove any curly braces and double quotes along with []\r\n  key = key.replace(/[{}\"[\\]]/g, \"\").replaceAll(/[:,]/g, \".\");\r\n\r\n  const cachePrefix =\r\n    typeof options.globalPrefix === \"function\" ? options.globalPrefix() : options.globalPrefix;\r\n\r\n  return rtrim(String(cachePrefix ? rtrim(cachePrefix, \".\") + \".\" + key : key), \".\");\r\n}\r\n\r\n/**\r\n * Parse a TTL value into seconds.\r\n *\r\n * Accepts:\r\n * - a number (already in seconds) — returned unchanged\r\n * - `Infinity` — no expiration, returned unchanged\r\n * - a human-readable duration string (e.g. `\"1h\"`, `\"30m\"`, `\"7d\"`) — parsed via `ms` then converted to seconds\r\n *\r\n * Throws `CacheConfigurationError` on unparseable strings or negative numbers.\r\n *\r\n * @example\r\n * parseTtl(3600);      // 3600\r\n * parseTtl(\"1h\");      // 3600\r\n * parseTtl(\"7d\");      // 604800\r\n * parseTtl(Infinity);  // Infinity\r\n */\r\nexport function parseTtl(input: CacheTtl): number {\r\n  if (typeof input === \"number\") {\r\n    if (input < 0) {\r\n      throw new CacheConfigurationError(`Invalid TTL: negative number (${input}).`);\r\n    }\r\n\r\n    return input;\r\n  }\r\n\r\n  if (typeof input !== \"string\" || input.trim() === \"\") {\r\n    throw new CacheConfigurationError(\r\n      `Invalid TTL: expected number or duration string, got ${typeof input}.`,\r\n    );\r\n  }\r\n\r\n  const milliseconds = ms(input as StringValue);\r\n\r\n  if (milliseconds === undefined || Number.isNaN(milliseconds)) {\r\n    throw new CacheConfigurationError(\r\n      `Invalid TTL duration string: \"${input}\". Expected forms like \"1h\", \"30m\", \"7d\".`,\r\n    );\r\n  }\r\n\r\n  return Math.floor(milliseconds / 1000);\r\n}\r\n\r\n/**\r\n * Convert an absolute `expiresAt` (Date or epoch milliseconds) into a\r\n * relative TTL in seconds.\r\n *\r\n * Throws {@link CacheConfigurationError} when the deadline is in the past —\r\n * the caller almost certainly has a bug (stale timestamp, wrong unit, etc.)\r\n * and silently storing an already-expired entry would hide it.\r\n *\r\n * @example\r\n * expiresAtToTtl(new Date(Date.now() + 60_000));   // ~60\r\n * expiresAtToTtl(Date.now() + 30 * 60 * 1000);     // ~1800\r\n */\r\nexport function expiresAtToTtl(expiresAt: number | Date): number {\r\n  const deadline = expiresAt instanceof Date ? expiresAt.getTime() : expiresAt;\r\n  const relativeMs = deadline - Date.now();\r\n\r\n  if (relativeMs <= 0) {\r\n    throw new CacheConfigurationError(\r\n      `\\`expiresAt\\` must be in the future; got ${new Date(deadline).toISOString()}.`,\r\n    );\r\n  }\r\n\r\n  return Math.ceil(relativeMs / 1000);\r\n}\r\n\r\n/**\r\n * Coerce the polymorphic 3rd `set` argument into a uniform `CacheSetOptions`\r\n * shape. Lets callers (and `BaseCacheDriver.resolveSetOptions`) skip per-shape\r\n * branching.\r\n *\r\n * - `undefined` / `null` → `{}` (resolves to driver-level defaults later)\r\n * - `number` / `string` (positional TTL) → `{ ttl }`\r\n * - already an options object → returned as-is\r\n */\r\nexport function normalizeToOptions(\r\n  input?: CacheTtl | CacheSetOptions,\r\n): CacheSetOptions {\r\n  if (input === undefined || input === null) {\r\n    return {};\r\n  }\r\n\r\n  if (typeof input === \"number\" || typeof input === \"string\") {\r\n    return { ttl: input };\r\n  }\r\n\r\n  return input;\r\n}\r\n\r\n/**\r\n * Sibling of {@link normalizeToOptions} for the `remember()` call site, where\r\n * the polymorphic 2nd argument is `CacheTtl | RememberOptions` (no `expiresAt`,\r\n * no `onConflict`). Returns the same shape so callers can `{ ...opts, ... }`\r\n * without branching.\r\n *\r\n * @example\r\n * normalizeToRememberOptions(60);             // { ttl: 60 }\r\n * normalizeToRememberOptions(\"1h\");           // { ttl: \"1h\" }\r\n * normalizeToRememberOptions({ ttl: \"1h\", tags: [\"x\"] }); // returned as-is\r\n */\r\nexport function normalizeToRememberOptions(\r\n  input?: CacheTtl | RememberOptions,\r\n): RememberOptions {\r\n  if (input === undefined || input === null) {\r\n    return {};\r\n  }\r\n\r\n  if (typeof input === \"number\" || typeof input === \"string\") {\r\n    return { ttl: input };\r\n  }\r\n\r\n  return input;\r\n}\r\n\r\n/**\r\n * Resolve the final TTL in seconds for a `set` call. Precedence:\r\n *\r\n * 1. Caller's `ttl` (number or duration string) wins.\r\n * 2. Otherwise, caller's `expiresAt` is converted to relative seconds.\r\n * 3. Otherwise, `fallback` is used (driver-level default — typically\r\n *    `Infinity` when no default is configured, meaning \"never expires\").\r\n *\r\n * Throws {@link CacheConfigurationError} when `ttl` and `expiresAt` are\r\n * supplied together (mutually exclusive).\r\n */\r\nexport function resolveTtl(\r\n  ttl: CacheTtl | undefined,\r\n  expiresAt: number | Date | undefined,\r\n  fallback: number,\r\n): number {\r\n  if (ttl !== undefined && expiresAt !== undefined) {\r\n    throw new CacheConfigurationError(\r\n      \"Cache set options cannot specify both `ttl` and `expiresAt` — choose one.\",\r\n    );\r\n  }\r\n\r\n  if (ttl !== undefined) {\r\n    return parseTtl(ttl);\r\n  }\r\n\r\n  if (expiresAt !== undefined) {\r\n    return expiresAtToTtl(expiresAt);\r\n  }\r\n\r\n  return fallback;\r\n}\r\n\r\n/**\r\n * Combine any number of tag lists into a single deduped array, dropping\r\n * `undefined`/empty entries. Returns `undefined` when no tags survive — lets\r\n * callers skip emitting empty `tags: []` into option payloads.\r\n *\r\n * Used by scoped-cache merging where scope tags + handle tags + per-call tags\r\n * must union additively without duplicates.\r\n *\r\n * @example\r\n * mergeTagSets([\"a\", \"b\"], [\"b\", \"c\"]);          // [\"a\", \"b\", \"c\"]\r\n * mergeTagSets(undefined, [\"x\"]);                // [\"x\"]\r\n * mergeTagSets(undefined, undefined);            // undefined\r\n * mergeTagSets([], []);                          // undefined\r\n */\r\nexport function mergeTagSets(\r\n  ...lists: (string[] | undefined)[]\r\n): string[] | undefined {\r\n  const flat: string[] = [];\r\n\r\n  for (const list of lists) {\r\n    if (!list || list.length === 0) {\r\n      continue;\r\n    }\r\n\r\n    flat.push(...list);\r\n  }\r\n\r\n  if (flat.length === 0) {\r\n    return undefined;\r\n  }\r\n\r\n  return Array.from(new Set(flat));\r\n}\r\n\r\n/**\r\n * Add extra tags to any option-bag that already shapes `tags?: string[]`.\r\n * Pure — clones the input shape, never mutates. Tags are appended (caller\r\n * is responsible for de-duplication if needed; pair with {@link mergeTagSets}).\r\n *\r\n * @example\r\n * injectTags({ ttl: \"1h\" }, [\"unread\"]);         // { ttl: \"1h\", tags: [\"unread\"] }\r\n * injectTags({ tags: [\"a\"] }, [\"b\"]);            // { tags: [\"a\", \"b\"] }\r\n */\r\nexport function injectTags<T extends { tags?: string[] }>(\r\n  options: T,\r\n  extraTags: string[],\r\n): T {\r\n  if (extraTags.length === 0) {\r\n    return options;\r\n  }\r\n\r\n  return {\r\n    ...options,\r\n    tags: [...(options.tags ?? []), ...extraTags],\r\n  };\r\n}\r\n\r\n/**\r\n * Cosine similarity between two equal-length numeric vectors.\r\n *\r\n * Returns a value in `[-1, 1]` where `1` means perfectly aligned, `0` means\r\n * orthogonal, and `-1` means opposing. For typical embedding spaces (where\r\n * vectors live in the positive cone) the practical range is `[0, 1]`.\r\n *\r\n * Throws {@link CacheConfigurationError} on dimension mismatch — fail loud at\r\n * the call site rather than silently returning a misleading score. A zero-norm\r\n * vector on either side returns `0` (no defined direction to compare).\r\n *\r\n * @example\r\n * cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1\r\n * cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0\r\n */\r\nexport function cosineSimilarity(a: number[], b: number[]): number {\r\n  if (a.length !== b.length) {\r\n    throw new CacheConfigurationError(\r\n      `Vector dimension mismatch: got ${a.length} and ${b.length}.`,\r\n    );\r\n  }\r\n\r\n  if (a.length === 0) {\r\n    throw new CacheConfigurationError(\r\n      \"Vector dimension mismatch: empty vector cannot be compared.\",\r\n    );\r\n  }\r\n\r\n  let dot = 0;\r\n  let normA = 0;\r\n  let normB = 0;\r\n\r\n  for (let i = 0; i < a.length; i++) {\r\n    const x = a[i];\r\n    const y = b[i];\r\n    dot += x * y;\r\n    normA += x * x;\r\n    normB += y * y;\r\n  }\r\n\r\n  if (normA === 0 || normB === 0) {\r\n    return 0;\r\n  }\r\n\r\n  return dot / (Math.sqrt(normA) * Math.sqrt(normB));\r\n}\r\n\r\nexport enum CACHE_FOR {\r\n  /**\r\n   * Cache for 30 Minutes (in seconds)\r\n   */\r\n  HALF_HOUR = 1800,\r\n  /**\r\n   * Cache for 1 Hour (in seconds)\r\n   */\r\n  ONE_HOUR = 3600,\r\n  /**\r\n   * Cache for 12 Hours (in seconds)\r\n   */\r\n  HALF_DAY = 43200,\r\n  /**\r\n   * Cache for 24 Hours (in seconds)\r\n   */\r\n  ONE_DAY = 86400,\r\n  /**\r\n   * Cache for 7 Days (in seconds)\r\n   */\r\n  ONE_WEEK = 604800,\r\n  /**\r\n   * Cache for 15 Days (in seconds)\r\n   */\r\n  HALF_MONTH = 1296000,\r\n  /**\r\n   * Cache for 30 Days (in seconds)\r\n   */\r\n  ONE_MONTH = 2592000,\r\n  /**\r\n   * Cache for 60 Days (in seconds)\r\n   */\r\n  TWO_MONTHS = 5184000,\r\n  /**\r\n   * Cache for 180 Days (in seconds)\r\n   */\r\n  SIX_MONTHS = 15768000,\r\n  /**\r\n   * Cache for 365 Days (in seconds)\r\n   */\r\n  ONE_YEAR = 31536000,\r\n}\r\n"],"mappings":"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"}