@warlock.js/cache 4.0.171 → 4.1.1

package/esm/cached/cached.d.mts

@@ -0,0 +1,54 @@
+import { CacheTtl } from "../types.mjs";
+import { CachedOptions } from "./normalize-args.mjs";
+
+//#region ../../@warlock.js/cache/src/cached/cached.d.ts
+/**
+ * The shape returned by `cached()`. Callable like the wrapped function, plus
+ * helpers for manual invalidation.
+ */
+type CachedFn<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {
+  /**
+   * Drop the cache entry for a specific argument combination.
+   *
+   * @example
+   * const getUser = cached((id: number) => db.users.find(id), "user", "1h");
+   * await getUser.invalidate(42);   // drops "user.42"
+   */
+  invalidate(...args: Args): Promise<void>;
+};
+/**
+ * Wrap an async function so every invocation runs through the cache.
+ *
+ * Uses `cache.remember()` internally — inherits its stampede-protection
+ * guarantees. Three calling shapes, `fn` always first.
+ *
+ * @example
+ * // Shorthand — prefix auto-expands with the function's arguments.
+ * // getUser(42) caches under "user.42".
+ * const getUser = cached(
+ *   (id: number) => db.users.find(id),
+ *   "user",
+ *   "1h",
+ * );
+ *
+ * @example
+ * // Options form — custom key function, tags, per-call driver override.
+ * const searchProducts = cached(
+ *   (filters: ProductFilters) => db.products.search(filters),
+ *   {
+ *     key: (filters) => `products.search.${filters.category}.${filters.sort}`,
+ *     ttl: "15m",
+ *     tags: ["products"],
+ *   },
+ * );
+ *
+ * @example
+ * // Manual invalidation — uses the same key scheme the wrapper uses internally.
+ * await getUser.invalidate(42);
+ */
+declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string): CachedFn<Args, R>;
+declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, prefix: string, ttl: CacheTtl): CachedFn<Args, R>;
+declare function cached<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>, options: CachedOptions<Args>): CachedFn<Args, R>;
+//#endregion
+export { CachedFn, cached };
+//# sourceMappingURL=cached.d.mts.map

package/esm/cached/cached.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/cached.ts"],"mappings":";;;;;;AASA;;KAAY,QAAA,mCAA2C,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA;EAAjB;;;;;;;EAQ3D,UAAA,IAAc,IAAA,EAAM,IAAA,GAAO,OAAA;AAAA;;;;;;;;;;AAAO;AAiCpC;;;;;;;;;;;;;;;;;;;;iBAAgB,MAAA,2BAAA,CACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,MAAA,WACC,QAAA,CAAS,IAAA,EAAM,CAAA;AAAA,iBACF,MAAA,2BAAA,CACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,MAAA,UACA,GAAA,EAAK,QAAA,GACJ,QAAA,CAAS,IAAA,EAAM,CAAA;AAAA,iBACF,MAAA,2BAAA,CACd,EAAA,MAAQ,IAAA,EAAM,IAAA,KAAS,OAAA,CAAQ,CAAA,GAC/B,OAAA,EAAS,aAAA,CAAc,IAAA,IACtB,QAAA,CAAS,IAAA,EAAM,CAAA"}

package/esm/cached/cached.mjs

@@ -0,0 +1,25 @@
+import { cache } from "../cache-manager.mjs";
+import { normalizeCachedArgs } from "./normalize-args.mjs";
+
+//#region ../../@warlock.js/cache/src/cached/cached.ts
+function cached(fn, prefixOrOptions, maybeTtl) {
+	const config = normalizeCachedArgs(prefixOrOptions, maybeTtl);
+	const buildRememberOptions = () => ({
+		ttl: config.ttl,
+		tags: config.tags,
+		driver: config.driver
+	});
+	const wrapper = (async (...args) => {
+		const key = config.key(...args);
+		return cache.remember(key, buildRememberOptions(), () => fn(...args));
+	});
+	wrapper.invalidate = async (...args) => {
+		const key = config.key(...args);
+		await cache.remove(key);
+	};
+	return wrapper;
+}
+
+//#endregion
+export { cached };
+//# sourceMappingURL=cached.mjs.map

package/esm/cached/cached.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/cached.ts"],"sourcesContent":["import { cache } from \"../cache-manager\";\nimport type { CacheTtl, RememberOptions } from \"../types\";\nimport type { CachedOptions } from \"./normalize-args\";\nimport { normalizeCachedArgs } from \"./normalize-args\";\n\n/**\n * The shape returned by `cached()`. Callable like the wrapped function, plus\n * helpers for manual invalidation.\n */\nexport type CachedFn<Args extends unknown[], R> = ((...args: Args) => Promise<R>) & {\n  /**\n   * Drop the cache entry for a specific argument combination.\n   *\n   * @example\n   * const getUser = cached((id: number) => db.users.find(id), \"user\", \"1h\");\n   * await getUser.invalidate(42);   // drops \"user.42\"\n   */\n  invalidate(...args: Args): Promise<void>;\n};\n\n/**\n * Wrap an async function so every invocation runs through the cache.\n *\n * Uses `cache.remember()` internally — inherits its stampede-protection\n * guarantees. Three calling shapes, `fn` always first.\n *\n * @example\n * // Shorthand — prefix auto-expands with the function's arguments.\n * // getUser(42) caches under \"user.42\".\n * const getUser = cached(\n *   (id: number) => db.users.find(id),\n *   \"user\",\n *   \"1h\",\n * );\n *\n * @example\n * // Options form — custom key function, tags, per-call driver override.\n * const searchProducts = cached(\n *   (filters: ProductFilters) => db.products.search(filters),\n *   {\n *     key: (filters) => `products.search.${filters.category}.${filters.sort}`,\n *     ttl: \"15m\",\n *     tags: [\"products\"],\n *   },\n * );\n *\n * @example\n * // Manual invalidation — uses the same key scheme the wrapper uses internally.\n * await getUser.invalidate(42);\n */\nexport function cached<Args extends unknown[], R>(\n  fn: (...args: Args) => Promise<R>,\n  prefix: string,\n): CachedFn<Args, R>;\nexport function cached<Args extends unknown[], R>(\n  fn: (...args: Args) => Promise<R>,\n  prefix: string,\n  ttl: CacheTtl,\n): CachedFn<Args, R>;\nexport function cached<Args extends unknown[], R>(\n  fn: (...args: Args) => Promise<R>,\n  options: CachedOptions<Args>,\n): CachedFn<Args, R>;\nexport function cached<Args extends unknown[], R>(\n  fn: (...args: Args) => Promise<R>,\n  prefixOrOptions: string | CachedOptions<Args>,\n  maybeTtl?: CacheTtl,\n): CachedFn<Args, R> {\n  const config = normalizeCachedArgs<Args>(prefixOrOptions, maybeTtl);\n\n  // Build the RememberOptions payload once per call. `ttl` may still be undefined\n  // here — that's fine, `remember` falls back to the driver's default TTL.\n  const buildRememberOptions = (): RememberOptions => ({\n    ttl: config.ttl,\n    tags: config.tags,\n    driver: config.driver,\n  });\n\n  const wrapper = (async (...args: Args): Promise<R> => {\n    const key = config.key(...args);\n    return cache.remember<R>(key, buildRememberOptions(), () => fn(...args));\n  }) as CachedFn<Args, R>;\n\n  wrapper.invalidate = async (...args: Args): Promise<void> => {\n    const key = config.key(...args);\n    await cache.remove(key);\n  };\n\n  return wrapper;\n}\n"],"mappings":";;;;AA+DA,SAAgB,OACd,IACA,iBACA,UACmB;CACnB,MAAM,SAAS,oBAA0B,iBAAiB,QAAQ;CAIlE,MAAM,8BAA+C;EACnD,KAAK,OAAO;EACZ,MAAM,OAAO;EACb,QAAQ,OAAO;CACjB;CAEA,MAAM,WAAW,OAAO,GAAG,SAA2B;EACpD,MAAM,MAAM,OAAO,IAAI,GAAG,IAAI;EAC9B,OAAO,MAAM,SAAY,KAAK,qBAAqB,SAAS,GAAG,GAAG,IAAI,CAAC;CACzE;CAEA,QAAQ,aAAa,OAAO,GAAG,SAA8B;EAC3D,MAAM,MAAM,OAAO,IAAI,GAAG,IAAI;EAC9B,MAAM,MAAM,OAAO,GAAG;CACxB;CAEA,OAAO;AACT"}

package/esm/cached/index.d.mts

@@ -0,0 +1,3 @@
+import { deriveAutoKey } from "./auto-key.mjs";
+import { CachedOptions, NormalizedCachedConfig, normalizeCachedArgs } from "./normalize-args.mjs";
+import { CachedFn, cached } from "./cached.mjs";

package/esm/cached/index.mjs

@@ -0,0 +1,5 @@
+import { deriveAutoKey } from "./auto-key.mjs";
+import { normalizeCachedArgs } from "./normalize-args.mjs";
+import { cached } from "./cached.mjs";
+
+export {  };

package/esm/cached/normalize-args.d.mts

@@ -0,0 +1,51 @@
+import { CacheTtl } from "../types.mjs";
+
+//#region ../../@warlock.js/cache/src/cached/normalize-args.d.ts
+/**
+ * Options accepted by the `cached()` factory in its verbose form. `key` is the
+ * decisive escape hatch when the shorthand's auto-key rules don't fit.
+ *
+ * @see cached
+ */
+type CachedOptions<Args extends unknown[]> = {
+  /**
+   * Derive a cache key from the wrapped function's arguments. Must be pure and
+   * deterministic — every call with equivalent inputs should produce the same
+   * key.
+   */
+  key: (...args: Args) => string;
+  /**
+   * Optional TTL on cache miss. Falls back to the driver's default TTL when omitted.
+   */
+  ttl?: CacheTtl;
+  /**
+   * Optional tags attached to every cache-miss write this wrapper produces.
+   * Invalidate them the usual way via `cache.tags([...]).invalidate()`.
+   */
+  tags?: string[];
+  /**
+   * Per-call driver override. Routes every call produced by this wrapper to
+   * the named driver without mutating `currentDriver`.
+   */
+  driver?: string;
+};
+/**
+ * Normalized form of the factory arguments — a single shape every call path
+ * in `cached()` operates on. Users never see this type.
+ *
+ * @internal
+ */
+type NormalizedCachedConfig<Args extends unknown[]> = {
+  key: (...args: Args) => string;
+  ttl?: CacheTtl;
+  tags?: string[];
+  driver?: string;
+};
+/**
+ * Resolve the positional-or-options arguments of `cached()` into a single
+ * normalized config. Keeps the wrapper body free of shape-checks.
+ */
+declare function normalizeCachedArgs<Args extends unknown[]>(prefixOrOptions: string | CachedOptions<Args>, maybeTtl?: CacheTtl): NormalizedCachedConfig<Args>;
+//#endregion
+export { CachedOptions, NormalizedCachedConfig, normalizeCachedArgs };
+//# sourceMappingURL=normalize-args.d.mts.map

package/esm/cached/normalize-args.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-args.d.mts","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/normalize-args.ts"],"mappings":";;;;;AASA;;;;KAAY,aAAA;EAMV;;;;;EAAA,GAAA,MAAS,IAAA,EAAM,IAAA;EAcf;;AAAM;EAVN,GAAA,GAAM,QAAQ;EAmBkB;;;;EAdhC,IAAA;EAeS;;;;EAVT,MAAA;AAAA;;AAaM;AAOR;;;;KAXY,sBAAA;EACV,GAAA,MAAS,IAAA,EAAM,IAAA;EACf,GAAA,GAAM,QAAQ;EACd,IAAA;EACA,MAAA;AAAA;;;;;iBAOc,mBAAA,wBAAA,CACd,eAAA,WAA0B,aAAA,CAAc,IAAA,GACxC,QAAA,GAAW,QAAA,GACV,sBAAA,CAAuB,IAAA"}

package/esm/cached/normalize-args.mjs

@@ -0,0 +1,26 @@
+import { deriveAutoKey } from "./auto-key.mjs";
+
+//#region ../../@warlock.js/cache/src/cached/normalize-args.ts
+/**
+* Resolve the positional-or-options arguments of `cached()` into a single
+* normalized config. Keeps the wrapper body free of shape-checks.
+*/
+function normalizeCachedArgs(prefixOrOptions, maybeTtl) {
+	if (typeof prefixOrOptions === "string") {
+		const prefix = prefixOrOptions;
+		return {
+			key: (...args) => deriveAutoKey(prefix, args),
+			ttl: maybeTtl
+		};
+	}
+	return {
+		key: prefixOrOptions.key,
+		ttl: prefixOrOptions.ttl,
+		tags: prefixOrOptions.tags,
+		driver: prefixOrOptions.driver
+	};
+}
+
+//#endregion
+export { normalizeCachedArgs };
+//# sourceMappingURL=normalize-args.mjs.map

package/esm/cached/normalize-args.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-args.mjs","names":[],"sources":["../../../../../../@warlock.js/cache/src/cached/normalize-args.ts"],"sourcesContent":["import type { CacheTtl } from \"../types\";\nimport { deriveAutoKey } from \"./auto-key\";\n\n/**\n * Options accepted by the `cached()` factory in its verbose form. `key` is the\n * decisive escape hatch when the shorthand's auto-key rules don't fit.\n *\n * @see cached\n */\nexport type CachedOptions<Args extends unknown[]> = {\n  /**\n   * Derive a cache key from the wrapped function's arguments. Must be pure and\n   * deterministic — every call with equivalent inputs should produce the same\n   * key.\n   */\n  key: (...args: Args) => string;\n  /**\n   * Optional TTL on cache miss. Falls back to the driver's default TTL when omitted.\n   */\n  ttl?: CacheTtl;\n  /**\n   * Optional tags attached to every cache-miss write this wrapper produces.\n   * Invalidate them the usual way via `cache.tags([...]).invalidate()`.\n   */\n  tags?: string[];\n  /**\n   * Per-call driver override. Routes every call produced by this wrapper to\n   * the named driver without mutating `currentDriver`.\n   */\n  driver?: string;\n};\n\n/**\n * Normalized form of the factory arguments — a single shape every call path\n * in `cached()` operates on. Users never see this type.\n *\n * @internal\n */\nexport type NormalizedCachedConfig<Args extends unknown[]> = {\n  key: (...args: Args) => string;\n  ttl?: CacheTtl;\n  tags?: string[];\n  driver?: string;\n};\n\n/**\n * Resolve the positional-or-options arguments of `cached()` into a single\n * normalized config. Keeps the wrapper body free of shape-checks.\n */\nexport function normalizeCachedArgs<Args extends unknown[]>(\n  prefixOrOptions: string | CachedOptions<Args>,\n  maybeTtl?: CacheTtl,\n): NormalizedCachedConfig<Args> {\n  if (typeof prefixOrOptions === \"string\") {\n    const prefix = prefixOrOptions;\n    return {\n      key: (...args: Args) => deriveAutoKey(prefix, args),\n      ttl: maybeTtl,\n    };\n  }\n\n  return {\n    key: prefixOrOptions.key,\n    ttl: prefixOrOptions.ttl,\n    tags: prefixOrOptions.tags,\n    driver: prefixOrOptions.driver,\n  };\n}\n"],"mappings":";;;;;;;AAiDA,SAAgB,oBACd,iBACA,UAC8B;CAC9B,IAAI,OAAO,oBAAoB,UAAU;EACvC,MAAM,SAAS;EACf,OAAO;GACL,MAAM,GAAG,SAAe,cAAc,QAAQ,IAAI;GAClD,KAAK;EACP;CACF;CAEA,OAAO;EACL,KAAK,gBAAgB;EACrB,KAAK,gBAAgB;EACrB,MAAM,gBAAgB;EACtB,QAAQ,gBAAgB;CAC1B;AACF"}

package/esm/drivers/base-cache-driver.d.mts

@@ -0,0 +1,322 @@
+import { CacheConflictPolicy, CacheData, CacheDriver, CacheEventData, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheOperationType, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, LockOptions, LockOutcome, RememberOptions } from "../types.mjs";
+
+//#region ../../@warlock.js/cache/src/drivers/base-cache-driver.d.ts
+/**
+ * Normalized form of the 3rd `set` argument.
+ *
+ * All drivers operate on this shape internally regardless of whether the caller
+ * passed a positional TTL, a duration string, or a rich options object.
+ */
+type NormalizedSetOptions = {
+  /**
+   * Final TTL in seconds — already merged with the driver-level default
+   * (`this.options.ttl`). `Infinity` means "no expiration".
+   *
+   * Always populated. Drivers do NOT need to fall back to `this.ttl`
+   * themselves — `resolveSetOptions` does the merge centrally so that
+   * every driver respects the configured default without ceremony.
+   */
+  ttl: number;
+  /**
+   * Inline tag list, or undefined when none were provided.
+   */
+  tags?: string[];
+  /**
+   * Conflict policy. Defaults to `"upsert"`.
+   */
+  onConflict: CacheConflictPolicy;
+  /**
+   * Optional embedding vector for similarity retrieval. Drivers that do not
+   * support similarity must throw {@link CacheUnsupportedError} when this is
+   * present (rather than silently dropping it).
+   */
+  vector?: number[];
+  /**
+   * Optional freshness deadline as a millisecond timestamp. Set by `swr()`
+   * to mark when the entry stops being "fresh" and becomes
+   * "stale-but-revalidatable." Drivers route this through
+   * `prepareDataForStorage` so it persists in the wrapper.
+   */
+  staleAt?: number;
+};
+declare abstract class BaseCacheDriver<ClientType, Options extends Record<string, any>> implements CacheDriver<ClientType, Options> {
+  /**
+   * CLient driver
+   */
+  protected clientDriver: ClientType;
+  /**
+   * Determine whether to log or not
+   */
+  protected shouldLog: boolean;
+  /**
+   * {@inheritdoc}
+   */
+  get client(): ClientType;
+  /**
+   * Set logging state
+   */
+  setLoggingState(shouldLog: boolean): this;
+  /**
+   * Set client driver
+   */
+  set client(client: ClientType);
+  /**
+   * Get the cache driver name
+   */
+  abstract name: string;
+  /**
+   * Options list
+   */
+  options: Options;
+  /**
+   * Event listeners storage
+   */
+  protected eventListeners: Map<CacheEventType, Set<CacheEventHandler>>;
+  /**
+   * {@inheritdoc}
+   */
+  parseKey(key: CacheKey): string;
+  /**
+   * {@inheritdoc}
+   */
+  setOptions(options: Options): this;
+  /**
+   * Register an event listener
+   */
+  on(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Remove an event listener
+   */
+  off(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Register a one-time event listener
+   */
+  once(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Emit an event to all registered listeners
+   */
+  protected emit(event: CacheEventType, data?: Partial<CacheEventData>): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  abstract removeNamespace(namespace: string): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  abstract set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * Normalize the 3rd argument of a `set` call into a single shape every driver
+   * can act on. Handles TTL parsing (number | string | Infinity), `expiresAt` →
+   * relative TTL conversion, and mutual-exclusion validation.
+   *
+   * @throws {CacheConfigurationError} when `ttl` and `expiresAt` are passed together
+   * or an unparseable duration string is supplied.
+   */
+  protected resolveSetOptions(ttlOrOptions?: CacheTtl | CacheSetOptions): NormalizedSetOptions;
+  /**
+   * Resolve the union of cache keys associated with any of the given tags.
+   * Used by `similar()` to narrow the candidate pool before similarity ranking.
+   *
+   * Returns `null` when no tags are passed (callers should treat that as "no filter").
+   */
+  protected getKeysForTags(tags: string[] | undefined): Promise<Set<string> | null>;
+  /**
+   * Apply tag relationships after a successful write. Called by drivers once
+   * the value is in storage.
+   */
+  protected applyTags(parsedKey: string, tags: string[]): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  abstract get(key: CacheKey): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  abstract remove(key: CacheKey): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  abstract flush(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  has(key: CacheKey): Promise<boolean>;
+  /**
+   * Lock storage for preventing cache stampede
+   */
+  protected locks: Map<string, Promise<any>>;
+  /**
+   * {@inheritdoc}
+   */
+  remember(key: CacheKey, ttlOrOptions: CacheTtl | RememberOptions, callback: () => Promise<any>): Promise<any>;
+  /**
+   * Resolve the TTL-or-options arg of `remember` into a `CacheSetOptions` object
+   * that can be passed straight to `set()`. Keeps the implementation unbranched.
+   */
+  protected normalizeRememberOptions(ttlOrOptions: CacheTtl | RememberOptions): CacheSetOptions;
+  /**
+   * {@inheritdoc}
+   *
+   * Default implementation: read raw entry, branch on freshness/staleness,
+   * trigger background refresh in the stale window, fall through to
+   * `callback` on miss/expiry. Concurrent stale-window callers share a
+   * single in-flight refresh via {@link locks}.
+   *
+   * Drivers without a real {@link getEntry} override degrade gracefully —
+   * the synthetic entry has no `staleAt`, which the freshness check treats
+   * as "always fresh," so SWR behaves like a TTL-only cached read on those
+   * drivers (no background refresh, but no double-fetch either).
+   */
+  swr<T = any>(key: CacheKey, options: CacheSwrOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * Read the raw {@link CacheData} wrapper for a key, including any
+   * `expiresAt` / `staleAt` metadata. Default implementation falls back to
+   * `get()` and synthesizes a metadata-less wrapper — drivers that store
+   * the wrapper directly (memory, lru, file, redis, pg, mock) override
+   * this to return real metadata so SWR can branch on freshness.
+   */
+  protected getEntry(key: CacheKey): Promise<CacheData | null>;
+  /**
+   * Remaining lifetime of an existing entry, in seconds — used by TTL-preserving
+   * writes such as `update()` / `merge()` when the caller passes no explicit
+   * `ttl`.
+   *
+   * - `Infinity` — the entry exists with no expiry (preserve "never expires").
+   * - positive number — seconds left before the entry expires.
+   * - `undefined` — the key is missing or already past its deadline; the caller
+   *   should fall back to the driver default TTL.
+   *
+   * Default reads `expiresAt` from {@link getEntry}, which the metadata-aware
+   * drivers (memory, lru, mock, pg) populate. Drivers that track TTL natively
+   * and don't carry `expiresAt` in their payload (Redis) override this.
+   */
+  protected getRemainingTtl(key: CacheKey): Promise<number | undefined>;
+  /**
+   * Block-and-fetch path of `swr()`: invoked on miss or past-`staleTtl`
+   * expiry. Writes through `set()` with the SWR options translated into
+   * standard `CacheSetOptions` (ttl = staleTtl, staleAt = now + freshTtl).
+   */
+  protected swrFetchAndStore<T>(key: CacheKey, options: CacheSwrOptions, callback: () => Promise<T>, freshSeconds: number, staleSeconds: number): Promise<T>;
+  /**
+   * Stale-window background refresh. Registers a single in-flight promise
+   * per parsed key so concurrent SWR callers share one refresh. Failed
+   * refreshes preserve the stale entry, log via `logError`, and emit on
+   * `error` — the stale-returning caller never sees the failure.
+   */
+  protected scheduleSwrRefresh<T>(parsedKey: string, key: CacheKey, options: CacheSwrOptions, callback: () => Promise<T>, freshSeconds: number, staleSeconds: number): void;
+  /**
+   * {@inheritdoc}
+   */
+  pull(key: CacheKey): Promise<any | null>;
+  /**
+   * {@inheritdoc}
+   */
+  forever(key: CacheKey, value: any): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  increment(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  decrement(key: CacheKey, value?: number): Promise<number>;
+  /**
+   * {@inheritdoc}
+   */
+  many(keys: CacheKey[]): Promise<any[]>;
+  /**
+   * {@inheritdoc}
+   */
+  setMany(items: Record<string, any>, ttl?: number): Promise<void>;
+  /**
+   * Log the operation
+   */
+  protected log(operation: CacheOperationType, key?: string): Promise<import("@warlock.js/logger").Logger> | undefined;
+  /**
+   * Log error message
+   */
+  protected logError(message: string, error?: any): void;
+  /**
+   * Get the default TTL in seconds. Parses human-readable strings (`"1h"`, `"30m"`)
+   * from driver options if present; falls back to `Infinity` when no default is set.
+   */
+  get ttl(): number;
+  /**
+   * Get time to live value in milliseconds
+   */
+  getExpiresAt(ttl?: number): number | undefined;
+  /**
+   * Wrap a value with TTL and optional freshness metadata for backend
+   * storage. `staleAt` persists alongside `expiresAt` when supplied — used
+   * by the SWR flow to mark when the entry stops being fresh.
+   */
+  protected prepareDataForStorage(data: any, ttl?: number, staleAt?: number): CacheData;
+  /**
+   * Parse fetched data from cache
+   */
+  protected parseCachedData(key: string, data: CacheData): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  connect(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Create a tagged cache instance for the given tags
+   */
+  tags(tags: string[]): any;
+  /**
+   * {@inheritdoc}
+   *
+   * Default implementation: read → transform → write under a per-key in-process
+   * lock. Drivers that can offer stronger semantics (Redis via `WATCH`/`MULTI`)
+   * should override.
+   */
+  update<T = any>(key: CacheKey, fn: (current: T | null) => T | null | Promise<T | null>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T | null>;
+  /**
+   * {@inheritdoc}
+   */
+  merge<T extends Record<string, any> = Record<string, any>>(key: CacheKey, partial: Partial<T>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T>;
+  /**
+   * {@inheritdoc}
+   *
+   * Default implementation: read-mutate-write array backed by the underlying
+   * cache entry. Concrete drivers (e.g. Redis) override with native commands.
+   */
+  list<T = any>(key: CacheKey): CacheListAccessor<T>;
+  /**
+   * {@inheritdoc}
+   *
+   * Built on top of `set({ onConflict: "create" })` — Redis-native `SET … NX EX`
+   * under the hood on Redis, emulated via key-existence check on other drivers.
+   * The lock value is the resolved `owner` (defaults to `pid.<process.pid>`).
+   *
+   * Always releases in `finally`, even if `fn` throws — the thrown error
+   * propagates to the caller unchanged.
+   */
+  lock<T>(key: CacheKey, ttlOrOptions: CacheTtl | Omit<LockOptions, "driver">, fn: () => Promise<T>): Promise<LockOutcome<T>>;
+  /**
+   * {@inheritdoc}
+   *
+   * Default implementation throws {@link CacheUnsupportedError}. Drivers that
+   * support similarity retrieval (memory family, `pg`, `redis` w/ RediSearch)
+   * override this with a real impl.
+   */
+  similar<T = any>(_vector: number[], _options: CacheSimilarOptions): Promise<CacheSimilarHit<T>[]>;
+  /**
+   * Resolve the TTL-or-options arg of `lock` into a uniform shape.
+   */
+  protected normalizeLockOptions(ttlOrOptions: CacheTtl | Omit<LockOptions, "driver">): {
+    ttl: CacheTtl;
+    owner?: string;
+  };
+}
+//#endregion
+export { BaseCacheDriver, NormalizedSetOptions };
+//# sourceMappingURL=base-cache-driver.d.mts.map

package/esm/drivers/base-cache-driver.d.mts.map

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