@warlock.js/cache 4.0.174 → 4.1.1

package/esm/cache-manager.d.mts

@@ -0,0 +1,314 @@
+import { CacheConfigurations, CacheDriver, CacheEventHandler, CacheEventType, CacheKey, CacheListAccessor, CacheMetricsSnapshot, CacheNamespaceOptions, CacheSetOptions, CacheSimilarHit, CacheSimilarOptions, CacheSwrOptions, CacheTtl, DriverClass, LockOptions, LockOutcome, RememberOptions, ScopedCacheContract, TaggedCacheDriver } from "./types.mjs";
+import { CacheMetricsCollector } from "./metrics.mjs";
+
+//#region ../../@warlock.js/cache/src/cache-manager.d.ts
+declare class CacheManager implements CacheDriver<any, any> {
+  /**
+   * Cache Driver
+   */
+  currentDriver?: CacheDriver<any, any>;
+  /**
+   * Loaded drivers
+   */
+  loadedDrivers: Record<string, CacheDriver<any, any>>;
+  /**
+   * Configurations list
+   */
+  protected configurations: CacheConfigurations;
+  /**
+   * Global event listeners
+   */
+  protected globalEventListeners: Map<CacheEventType, Set<CacheEventHandler>>;
+  /**
+   * Metrics collector — lazy on first {@link metrics} call so apps that
+   * never read metrics pay zero cost. Once instantiated, it stays
+   * subscribed to events for the manager's lifetime.
+   */
+  protected metricsCollector?: CacheMetricsCollector;
+  /**
+   * {@inheritdoc}
+   */
+  name: string;
+  /**
+   * {@inheritdoc}
+   */
+  get client(): any;
+  /**
+   * Set the cache configurations
+   */
+  setCacheConfigurations(configurations: CacheConfigurations): void;
+  /**
+   * Set logging state
+   */
+  setLoggingState(loggingState: boolean): void;
+  /**
+   * Switch the manager to a registered driver, optionally injecting runtime
+   * options that merge over the static config.
+   *
+   * The string form looks the driver up in `setCacheConfigurations({ drivers })`,
+   * loads it (or returns the cached instance), and sets it as `currentDriver`.
+   * The instance form takes a pre-built driver and bypasses the registry; the
+   * `runtimeOptions` argument is silently ignored in that case because the
+   * instance was constructed externally.
+   *
+   * Runtime options merge over `config.options[name]` per-key — runtime wins.
+   * Use this for constructor-only knobs that can't live in static config
+   * (e.g. `pg`'s `client: pg.Pool`).
+   *
+   * @example
+   * const pool = new Pool({ connectionString });
+   * await cache.use("pg", { client: pool });
+   */
+  use(driver: string | CacheDriver<any, any>, runtimeOptions?: Record<string, any>): Promise<this>;
+  /**
+   * Ensure driver is initialized before operations
+   */
+  protected ensureDriverInitialized(): void;
+  /**
+   * Return the running metrics snapshot — counters, hit-rate, latency
+   * percentiles, per-driver breakdowns. Lazy-attaches the collector on
+   * first call so apps that never read metrics pay zero cost.
+   *
+   * @example
+   * const m = cache.metrics();
+   * console.log(`hit rate: ${(m.hitRate * 100).toFixed(1)}%`);
+   * console.log(`p95: ${m.latencyMs.p95.toFixed(2)}ms`);
+   */
+  metrics(): CacheMetricsSnapshot;
+  /**
+   * Wipe every counter + latency sample and reset `startedAt` to now.
+   * The collector itself stays subscribed to events.
+   */
+  resetMetrics(): void;
+  /**
+   * Lazy-construct the metrics collector and wire it to the global event
+   * bus. Subsequent calls return the same instance — survives `cache.use()`
+   * driver switches because handlers attach via `on()` and re-bind to every
+   * loaded driver.
+   */
+  protected ensureMetricsCollector(): CacheMetricsCollector;
+  /**
+   * Time the body, record the elapsed milliseconds against the metrics
+   * collector for the given driver (defaults to the current driver's name).
+   * Pass-through if the collector hasn't been instantiated yet — apps that
+   * don't read metrics never pay for sample collection.
+   */
+  protected timed<T>(body: () => Promise<T>, driverName?: string): Promise<T>;
+  /**
+   * {@inheritdoc}
+   */
+  get<T = any>(key: CacheKey): Promise<T | null>;
+  /**
+   * Set a value in the cache.
+   *
+   * Accepts a positional TTL (number of seconds or duration string like `"1h"`)
+   * or a rich {@link CacheSetOptions} object supporting `ttl`, `expiresAt`,
+   * `tags`, `onConflict`, `namespace`, and per-call `driver` overrides.
+   */
+  set(key: CacheKey, value: any, ttlOrOptions?: CacheTtl | CacheSetOptions): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  removeNamespace(namespace: string): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  flush(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  connect(): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  parseKey(key: CacheKey): string;
+  /**
+   * {@inheritdoc}
+   */
+  get options(): any;
+  /**
+   * {@inheritdoc}
+   */
+  setOptions(options: Record<string, any>): any;
+  /**
+   * Return the loaded driver instance for `driverName`, loading it on first
+   * call. Optional `runtimeOptions` follow the same merge-over-config rules
+   * as {@link load}; passing options after the driver has already been
+   * loaded throws to avoid silent swallowing.
+   */
+  driver(driverName: string, runtimeOptions?: Record<string, any>): Promise<CacheDriver<any, any>>;
+  /**
+   * Initialize the cache manager and pick the default driver
+   */
+  init(): Promise<void>;
+  /**
+   * Load and connect the registered driver named `driver`. First-call wins —
+   * subsequent calls without `runtimeOptions` return the cached instance, and
+   * subsequent calls *with* `runtimeOptions` throw {@link CacheConfigurationError}
+   * to avoid silently dropping the new options.
+   *
+   * `runtimeOptions` merge over `config.options[driver]` per-key (runtime wins),
+   * letting consumers split static knobs (table, ttl, globalPrefix) from
+   * constructor-only ones (pg's `client`, custom adapters, etc.).
+   *
+   * @example
+   * const pool = new Pool({ connectionString });
+   * const pg = await cache.load("pg", { client: pool });
+   */
+  load(driver: string, runtimeOptions?: Record<string, any>): Promise<CacheDriver<any, any>>;
+  /**
+   * Guard against silently dropping runtime options on a re-load. Once a
+   * driver has been instantiated, its options are frozen — calling `load` /
+   * `driver` / `use` again with a non-empty `runtimeOptions` would otherwise
+   * appear to work but actually use the original options. We throw instead
+   * so the misuse surfaces at the call site.
+   */
+  protected assertNoConflictingReload(driverName: string, runtimeOptions: Record<string, any> | undefined): void;
+  /**
+   * Register and bind a driver
+   */
+  registerDriver(driverName: string, driverClass: DriverClass): void;
+  /**
+   * Disconnect the cache manager
+   */
+  disconnect(): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  has(key: CacheKey): Promise<boolean>;
+  /**
+   * {@inheritdoc}
+   */
+  remember<T = any>(key: CacheKey, ttlOrOptions: CacheTtl | RememberOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * Stale-while-revalidate. Returns cached when fresh, returns the stale
+   * value plus a background refresh when within `freshTtl..staleTtl`,
+   * blocks like a normal miss past `staleTtl`. Honors per-call `driver`
+   * override the same way `remember()` does.
+   *
+   * @example
+   * const product = await cache.swr(
+   *   "product.42",
+   *   { freshTtl: "1m", staleTtl: "1h" },
+   *   () => db.products.find(42),
+   * );
+   */
+  swr<T = any>(key: CacheKey, options: CacheSwrOptions, callback: () => Promise<T>): Promise<T>;
+  /**
+   * {@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>;
+  /**
+   * Register a global event listener (applies to all drivers)
+   */
+  on(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Remove a global event listener
+   */
+  off(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Register a one-time global event listener
+   */
+  once(event: CacheEventType, handler: CacheEventHandler): this;
+  /**
+   * Attach global listeners to a driver
+   */
+  protected attachGlobalListeners(driver: CacheDriver<any, any>): void;
+  /**
+   * Set if not exists (atomic operation)
+   * Returns true if key was set, false if key already existed
+   * Note: Only supported by drivers that implement setNX (e.g., Redis)
+   */
+  setNX(key: CacheKey, value: any, ttl?: number): Promise<boolean>;
+  /**
+   * Create a tagged cache instance for the given tags
+   */
+  tags(tags: string[]): TaggedCacheDriver;
+  /**
+   * Atomically read, transform, and write a cached value. Delegates to the current driver.
+   */
+  update<T = any>(key: CacheKey, fn: (current: T | null) => T | null | Promise<T | null>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T | null>;
+  /**
+   * Shallow-merge a partial object into a cached value.
+   */
+  merge<T extends Record<string, any> = Record<string, any>>(key: CacheKey, partial: Partial<T>, options?: {
+    ttl?: CacheTtl;
+  }): Promise<T>;
+  /**
+   * Obtain a list accessor bound to the current driver.
+   */
+  list<T = any>(key: CacheKey): CacheListAccessor<T>;
+  /**
+   * Acquire a distributed lock, run `fn`, and auto-release. Returns a
+   * {@link LockOutcome} discriminated union so callers can distinguish
+   * "ran and got this value" from "skipped because someone else holds it".
+   *
+   * Honors the `driver` option for per-call driver override, same as `set`
+   * and `remember`.
+   *
+   * @example
+   * const outcome = await cache.lock("lock.import", "5m", async () => {
+   *   await runImport();
+   *   return "done";
+   * });
+   * if (!outcome.acquired) {
+   *   console.log("another worker is already importing");
+   * }
+   */
+  lock<T>(key: CacheKey, ttlOrOptions: CacheTtl | LockOptions, fn: () => Promise<T>): Promise<LockOutcome<T>>;
+  /**
+   * Similarity retrieval. Delegates to the current driver's `similar()` impl.
+   *
+   * Drivers that lack a similarity index throw {@link CacheUnsupportedError}.
+   *
+   * @example
+   * const hits = await cache.similar(await embed(query), { topK: 5, threshold: 0.7 });
+   */
+  /**
+   * Create a scoped view over the cache. Every key written through the
+   * returned scope is automatically prefixed with `prefix`; optional defaults
+   * (`ttl`, `tags`) flow through every write inside the scope.
+   *
+   * Per-call options always win over scope defaults. Scope tags merge
+   * additively with per-call tags. Nested scopes inherit from the parent.
+   *
+   * @example
+   * const chat = cache.namespace("chats.10", { ttl: "30d" });
+   * await chat.set("messages.1", msg);          // → "chats.10.messages.1", 30d
+   * await chat.set("draft", d, { ttl: "1h" });  // per-call ttl wins
+   * await chat.namespace("typing", { ttl: "5s" }).set("user.42", true);
+   * await chat.clear();                          // wipe the whole scope
+   */
+  namespace(prefix: string, options?: CacheNamespaceOptions): ScopedCacheContract;
+  similar<T = any>(vector: number[], options: CacheSimilarOptions): Promise<CacheSimilarHit<T>[]>;
+}
+declare const cache: CacheManager;
+//#endregion
+export { CacheManager, cache };
+//# sourceMappingURL=cache-manager.d.mts.map

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

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