cachimbo 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,762 @@
+import { LRUCache } from "lru-cache";
+import { TTLCache } from "@isaacs/ttlcache";
+import { Redis } from "ioredis";
+import { Redis as Redis$1 } from "iovalkey";
+import { RedisClientPoolType, RedisClientType, RedisClusterType, RedisSentinelType } from "@redis/client";
+import { BaseClient, GlideClient, GlideClusterClient } from "@valkey/valkey-glide";
+import Memcache from "memcache";
+import { Client } from "memjs";
+import { KVNamespace } from "@cloudflare/workers-types";
+import Keyv from "keyv";
+
+//#region src/types/logger.d.ts
+interface Logger {
+  /**
+   * Sends a debug log
+   * @param name The cache name
+   * @param message The log message
+   */
+  debug: (name?: string, ...message: any[]) => void;
+}
+//#endregion
+//#region src/types/cache.d.ts
+interface SetCacheOptions {
+  /**
+   * Time to Live in seconds
+   */
+  ttl?: number;
+}
+interface BaseCacheOptions {
+  /**
+   * The name of this strategy. Used for logging
+   */
+  name?: string;
+
+  /**
+   * A logger that is useful for debugging the cache chain
+   */
+  logger?: Logger;
+}
+interface ICache {
+  /**
+   * Reads the cached resource from a key.
+   * Returns `null` when the resource is not found.
+   *
+   * @param key The cache key
+   */
+  get<T>(key: string): Promise<T | null>;
+
+  /**
+   * Reads the cached resource from a key.
+   * If the cached resource is not found, fetches it by calling the `load` function and then saves it into cache.
+   *
+   * @param key The cache key
+   * @param load The function which should fetch the fresh data from origin
+   * @param options The options used to save the cache
+   */
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+
+  /**
+   * Writes a resource into cache.
+   *
+   * The value **must** be JSON stringifiable.
+   *
+   * @param key The cache key
+   * @param value The resource value
+   * @param options The options to save the cache
+   */
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+
+  /**
+   * Deletes a cached resource by a key.
+   *
+   * @param key The cache key to delete
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Reads cached resources in batch.
+   *
+   * @param keys The list of cache keys.
+   */
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+
+  /**
+   * Writes cache resources in batch.
+   *
+   * The values **must** be JSON stringifiable.
+   *
+   * @param data The cache keys and values
+   * @param options The options to save the cache
+   */
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+
+  /**
+   * Deletes cached resources by their keys in batch.
+   *
+   * @param keys The list of keys to delete
+   */
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/base/index.d.ts
+/**
+ * The base implementation of a cache.
+ *
+ * This class only requires subclasses to implement {@link ICache#get}, {@link ICache#set} and {@link ICache#delete}.
+ * All other methods fall back into these three.
+ */
+declare abstract class BaseCache implements ICache {
+  protected readonly name?: string;
+  protected readonly logger?: Logger;
+  protected constructor(options: BaseCacheOptions);
+  abstract get<T>(key: string): Promise<T | null>;
+  abstract set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  abstract delete(key: string): Promise<void>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/local/lru/index.d.ts
+interface ExistingLRUCacheOptions extends BaseCacheOptions {
+  /**
+   * The existing instance of a LRUCache.
+   */
+  cache: LRUCache<string, any, () => Promise<any>>;
+  /**
+   * Whether it should call {@link LRUCache#fetch} when `getOrLoad` is called.
+   *
+   * For that, {@link LRUCache#fetchMethod} needs to call the context function:
+   * ```ts
+   * new LRUCache<string, any, () => Promise<any>>({
+   *   fetchMethod: (_key, _staleValue, options) => options.context(),
+   * });
+   * ```
+   */
+  shouldUseFetch?: boolean;
+}
+interface LocalLRUCacheOptions extends BaseCacheOptions {
+  /**
+   * The default Time to Live (in seconds)
+   */
+  ttl?: number;
+  /**
+   * The maximum amount of items stored
+   */
+  max?: number;
+}
+/**
+ * An in-memory cache implementation of a Least-Recently-Used cache eviction algorithm.
+ *
+ * It allows setting an expiration time and a limit of cached items.
+ *
+ * Once the limit of items is reached, the least recently used items will be purged.
+ */
+declare class LocalLRUCache extends BaseCache {
+  protected readonly cache: LRUCache<string, any, () => Promise<any>>;
+  protected shouldUseFetch?: boolean;
+  constructor(options?: LocalLRUCacheOptions | ExistingLRUCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+//#region src/local/ttl/index.d.ts
+interface ExistingTTLCacheOptions extends BaseCacheOptions {
+  /**
+   * Existing instance of a TTLCache
+   */
+  cache: TTLCache<string, any>;
+}
+interface LocalTTLCacheOptions extends BaseCacheOptions {
+  /**
+   * The default Time to Live (in seconds)
+   */
+  ttl?: number;
+  /**
+   * The maximum amount of items stored
+   */
+  max?: number;
+}
+/**
+ * An in-memory cache implementation that allows setting an expiration time and a limit of cached items.
+ *
+ * Once the limit of items is reached, the soonest expiring items will be purged.
+ */
+declare class LocalTTLCache extends BaseCache {
+  protected readonly cache: TTLCache<string, any>;
+  constructor(options?: LocalTTLCacheOptions | ExistingTTLCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+//#region src/local/map/index.d.ts
+interface LocalMapCacheOptions extends BaseCacheOptions {
+  /**
+   * The underlying map.
+   */
+  cache?: MapLike<string, any>;
+  /**
+   * The maximum size of the cache.
+   * When not set, the cache can grow indefinitely.
+   */
+  max?: number;
+}
+interface MapLike<K, V> {
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  delete(key: K): void;
+  has(key: K): boolean;
+  keys(): IterableIterator<K>;
+  size: number;
+  clear(): void;
+}
+/**
+ * A simple in-memory cache implementation based on {@link Map}.
+ *
+ * It ignores expiration times, but a limit of cached items can be set.
+ *
+ * Once the limit of items is reached, the first inserted keys will be purged.
+ */
+declare class LocalMapCache extends BaseCache {
+  protected readonly cache: MapLike<string, any>;
+  protected max: number;
+  constructor(options?: LocalMapCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  setMany(data: Record<string, any>, options?: SetCacheOptions): Promise<void>;
+  clear(): void;
+  protected evict(length: number): void;
+}
+//#endregion
+//#region src/local/noop/index.d.ts
+/**
+ * A cache implementation that does nothing.
+ * It's useful for disabling cache.
+ *
+ * @example
+ * ```ts
+ * const cache = isCacheEnabled ? new LocalTTLCache() : new NoOpCache();
+ * ```
+ */
+declare class NoOpCache implements ICache {
+  constructor();
+  get<T>(key: string): Promise<T | null>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/remote/ioredis/index.d.ts
+interface IORedisCacheOptions extends BaseCacheOptions {
+  /**
+   * The ioredis or iovalkey client
+   */
+  client: Redis | Redis$1;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL?: number;
+  /**
+   * Indicates whether the Redis server supports the MSETEX command.
+   *
+   * {@link IORedisCache#setMany} will use MSETEX if this option is set to `true`.
+   *
+   * This option should be set to `true` if the server runs Redis OSS 8.4.0 or above.
+   * Valkey does not support this yet. (see https://github.com/valkey-io/valkey/issues/2592)
+   */
+  isMSETEXSupported?: boolean;
+}
+/**
+ * A Redis cache implementation using ioredis
+ */
+declare class IORedisCache extends BaseCache {
+  protected readonly client: Redis | Redis$1;
+  protected defaultTTL?: number;
+  protected isMSETEXSupported?: boolean;
+  constructor(options: IORedisCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany(data: Record<string, any>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/remote/redis/index.d.ts
+type Redis$2 = RedisClientType | RedisClientPoolType | RedisClusterType | RedisSentinelType;
+interface RedisCacheOptions extends BaseCacheOptions {
+  /**
+   * The Redis client
+   */
+  client: RedisClientType | RedisClientPoolType | RedisClusterType | RedisSentinelType;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL?: number;
+  /**
+   * Indicates whether the Redis server supports MSETEX command.
+   *
+   * {@link RedisCache#setMany} will use MSETEX if this option is set to `true`.
+   *
+   * This option should be set to `true` if the server runs Redis OSS 8.4.0 or above.
+   * Valkey does not support this yet. (see https://github.com/valkey-io/valkey/issues/2592)
+   */
+  isMSETEXSupported?: boolean;
+}
+/**
+ * A Redis cache implementation using node-redis
+ */
+declare class RedisCache extends BaseCache {
+  protected readonly client: Redis$2;
+  protected defaultTTL?: number;
+  protected isMSETEXSupported?: boolean;
+  constructor(options: RedisCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany(data: Record<string, any>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/remote/valkey-glide/index.d.ts
+interface ValkeyGlideCacheOptions extends BaseCacheOptions {
+  /**
+   * The GLIDE client instance
+   */
+  client: GlideClient | GlideClusterClient | BaseClient;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL?: number;
+}
+/**
+ * A Valkey cache implementation using @valkey/valkey-glide
+ */
+declare class ValkeyGlideCache extends BaseCache {
+  protected readonly client: BaseClient;
+  protected defaultTTL?: number;
+  constructor(options: ValkeyGlideCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/remote/memcache/index.d.ts
+interface MemcacheCacheOptions extends BaseCacheOptions {
+  /**
+   * The Memcache client
+   */
+  client: Memcache;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL?: number;
+}
+/**
+ * A Memcached cache implementation using Memcache
+ */
+declare class MemcacheCache extends BaseCache {
+  protected readonly client: Memcache;
+  protected defaultTTL?: number;
+  constructor(options: MemcacheCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+}
+//#endregion
+//#region src/remote/memjs/index.d.ts
+interface MemJSCacheOptions extends BaseCacheOptions {
+  /**
+   * The memjs client
+   */
+  client: Client;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL?: number;
+}
+/**
+ * A Memcached cache implementation using MemJS
+ */
+declare class MemJSCache extends BaseCache {
+  protected readonly client: Client;
+  protected defaultTTL?: number;
+  constructor(options: MemJSCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+//#endregion
+//#region src/remote/workers-kv/index.d.ts
+interface WorkersKVCacheOptions extends BaseCacheOptions {
+  /**
+   * The KV namespace (`env.NAMESPACE`)
+   */
+  kv: KVNamespace;
+  /**
+   * The amount of time in seconds that a KV result is cached in the global network location it is accessed from.
+   *
+   * Increasing this value can improve read performance at the cost of data being stale.
+   *
+   * @see https://developers.cloudflare.com/kv/api/read-key-value-pairs/#cachettl-parameter
+   */
+  edgeCacheTTL?: number;
+}
+/**
+ * A Cloudflare Workers KV cache implementation.
+ */
+declare class WorkersKVCache extends BaseCache {
+  protected readonly kv: KVNamespace;
+  protected edgeCacheTTL?: number;
+  constructor(options: WorkersKVCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+}
+//#endregion
+//#region src/remote/keyv/index.d.ts
+interface KeyvCacheOptions extends BaseCacheOptions {
+  /**
+   * The underlying key-value store
+   */
+  keyv: Keyv;
+}
+declare class KeyvCache extends BaseCache {
+  protected readonly keyv: Keyv;
+  constructor(options: KeyvCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/layers/async-lazy/index.d.ts
+interface AsyncLazyCacheOptions {
+  /**
+   * A factory function that will be called to create the underlying cache when needed.
+   */
+  factory: () => Promise<ICache> | ICache;
+  /**
+   * Whether it should initialize only when needed.
+   *
+   * - When set to `true`, it will initialize the cache only when a method is called.
+   * - When set to `false`, it will initialize the cache upon construction.
+   *
+   * @default `false`
+   */
+  lazy?: boolean;
+}
+/**
+ * A cache layer that initializes the underlying cache asynchronously.
+ *
+ * This layer can be used to connect to an external cache with the cache methods already available.
+ *
+ * This layer can also be used to lazily initialize the cache only when it's actually needed.
+ *
+ * @example
+ * ```ts
+ * const cache = new AsyncCache({
+ *   factory: async () => {
+ *     const redisClient = await createClient({
+ *       url: "redis://user:password@localhost:6380",
+ *     });
+ *
+ *     return new RedisCache({ client: redisClient });
+ *   },
+ *   lazy: true,
+ * });
+ *
+ * cache.get("key")
+ *   .then(result => console.log('redis was connected and read the key:', value));
+ * ```
+ */
+declare class AsyncLazyCache implements ICache {
+  protected readonly factory: () => Promise<ICache> | ICache;
+  protected cache: Promise<ICache> | null;
+  constructor(options: AsyncLazyCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+  /**
+   * Gets the underlying cache, initializing it if not already initialized.
+   */
+  resolveCache(): Promise<ICache>;
+}
+//#endregion
+//#region src/layers/coalescing/index.d.ts
+/**
+ * The options to construct the {@link CoalescingCache}
+ */
+interface CoalescingCacheOptions extends BaseCacheOptions {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+}
+interface OngoingRequest {
+  promise: Promise<any | null>;
+  type: 'get' | 'getOrLoad';
+}
+/**
+ * A cache strategy layer that deduplicates parallel requests into a single request.
+ *
+ * This strategy can prevent the Thundering Herd problem as all parallel requests will be coalesced into one.
+ */
+declare class CoalescingCache implements ICache {
+  protected readonly ongoingRequests: Map<string, OngoingRequest>;
+  protected readonly cache: ICache;
+  protected readonly name?: string;
+  protected readonly logger?: Logger;
+  constructor(options: CoalescingCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/layers/jittering/index.d.ts
+interface JitteringCacheOptions {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL: number;
+  /**
+   * The maximum jitter (in seconds) to add to the TTL of cached items.
+   */
+  maxJitterTTL: number;
+}
+/**
+ * A cache layer that adds a random jitter to the TTL of cached items to prevent cache stampedes.
+ *
+ * This layer is useful in scenarios where many cached items expire simultaneously, causing a sudden surge of requests to the underlying data source.
+ */
+declare class JitteringCache implements ICache {
+  protected readonly cache: ICache;
+  protected defaultTTL: number;
+  protected maxJitterTTL: number;
+  constructor(options: JitteringCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+  protected jitterTTL(options?: SetCacheOptions): SetCacheOptions;
+}
+//#endregion
+//#region src/layers/key-transforming/index.d.ts
+interface BaseKeyTransformingCacheOptions {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+}
+interface KeyTransformerFnCacheOptions extends BaseKeyTransformingCacheOptions {
+  /**
+   * The function that will be called with each key to transform it.
+   * @param key The original key
+   * @return The transformed key
+   */
+  transform: (key: string) => string;
+  prefix?: never;
+  suffix?: never;
+}
+interface KeyAffixCacheOptions extends BaseKeyTransformingCacheOptions {
+  /**
+   * The prefix to add to keys
+   */
+  prefix?: string;
+  /**
+   * The suffix to add to keys
+   */
+  suffix?: string;
+}
+type KeyTransformingCacheOptions = KeyAffixCacheOptions | KeyTransformerFnCacheOptions;
+/**
+ * A cache layer that changes keys before passing them to the underlying cache.
+ *
+ * This layer can be used to:
+ * - Create namespaced caches, avoiding conflicts with shared cache servers.
+ * - Add a version number, allowing schema changes without causing incompatibility.
+ * - Implement any other key transformations, such as normalizing or hashing.
+ */
+declare class KeyTransformingCache implements ICache {
+  protected readonly cache: ICache;
+  protected transform: (key: string) => string;
+  constructor(options: KeyTransformingCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/layers/swr/index.d.ts
+/**
+ * The options to create the {@link SWRCache}
+ */
+interface SWRCacheOptions extends BaseCacheOptions {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+  /**
+   * The default Time To Live in seconds
+   */
+  defaultTTL: number;
+  /**
+   * The additional time in seconds to keep the resource stored, but consider it as stale
+   */
+  staleTTL: number;
+}
+/**
+ * A cache strategy that returns stale resources immediately while it refreshes the cache in background.
+ *
+ * This is an implementation of the Stale-While-Revalidate algorithm.
+ *
+ * This strategy is only effective when calling {@link ICache#getOrLoad}.
+ */
+declare class SWRCache implements ICache {
+  protected readonly revalidating: Map<string, Promise<any>>;
+  protected readonly cache: ICache;
+  protected readonly name?: string;
+  protected readonly logger?: Logger;
+  protected defaultTTL: number;
+  protected staleTTL: number;
+  constructor(options: SWRCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/layers/tiered/index.d.ts
+interface TieredCacheOptions extends BaseCacheOptions {
+  /**
+   * The list of tiers in order of priority.
+   *
+   * The first item represents the "hot" cache while the last one represents a "cold" cache.
+   */
+  tiers: CacheTier[];
+}
+interface CacheTier {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+  /**
+   * The options that will be passed to {@link ICache#getOrLoad}, {@link ICache#set} and {@link ICache#setMany}.
+   */
+  options?: SetCacheOptions;
+}
+/**
+ * A cache strategy layer that implements multi-level caching
+ *
+ * The objective of a tiered cache is to minimize latency while still having the benefits of a larger, shared cache.
+ * This is done by having the first tier being an in-memory cache (such as {@link LocalTTLCache}) that stores a small amount of items with a short TTL,
+ * and the second tier being an external cache (such as {@link RedisCache}) that stores a lot more items and may have a longer TTL.
+ *
+ * This strategy is similarly known as Cache Hierarchy, CPU cache or L1/L2/L3 cache.
+ */
+declare class TieredCache extends BaseCache {
+  protected readonly tiers: CacheTier[];
+  constructor(options: TieredCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+}
+//#endregion
+//#region src/layers/metrics/index.d.ts
+interface MetricsCollectingCacheOptions extends BaseCacheOptions {
+  /**
+   * The underlying cache
+   */
+  cache: ICache;
+}
+interface CacheCountMetrics {
+  /** Amount of times the cache didn't have the requested resource */
+  missCount: number;
+  /** The amount of times the cache returned the requested resource */
+  hitCount: number;
+  /** The amount of times the cache was refreshed (the `load` function was called in {@link ICache#getOrLoad}) */
+  loadCount: number;
+  /** The amount of times the cache was updated */
+  setCount: number;
+  /** The amount of times a cached resource was invalidated */
+  deleteCount: number;
+}
+interface CacheTimeMetrics {
+  /** Average time taken to verify that the cache didn't have a single requested resource (in milliseconds) */
+  missTime: number;
+  /** Average time taken to return a single requested resource from cache (in milliseconds) */
+  hitTime: number;
+  /** Average time taken to load a single resource from source (in milliseconds) */
+  loadTime: number;
+  /** Average time taken to update a single resource from cache (in milliseconds) */
+  setTime: number;
+  /** Average time taken to invalidate a single resource from cache (in milliseconds) */
+  deleteTime: number;
+}
+type CacheMetrics = CacheCountMetrics & CacheTimeMetrics;
+/**
+ * A cache layer that collects metrics from each cache call.
+ *
+ * This can be useful to measure the cache effectiveness
+ */
+declare class MetricsCollectingCache implements ICache {
+  protected readonly cache: ICache;
+  protected readonly logger?: Logger;
+  protected name?: string;
+  protected countMetrics: CacheCountMetrics;
+  protected totalTimeMetrics: CacheTimeMetrics;
+  constructor(options: MetricsCollectingCacheOptions);
+  get<T>(key: string): Promise<T | null>;
+  getOrLoad<T>(key: string, load: () => Promise<T>, options?: SetCacheOptions): Promise<T>;
+  set<T>(key: string, value: T, options?: SetCacheOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  getMany<T>(keys: string[]): Promise<Record<string, T | null>>;
+  setMany<T>(data: Record<string, T>, options?: SetCacheOptions): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+  getMetrics(): CacheMetrics;
+  resetMetrics(): void;
+}
+//#endregion
+export { AsyncLazyCache, AsyncLazyCacheOptions, BaseCache, BaseCacheOptions, CacheMetrics, CacheTier, CoalescingCache, CoalescingCacheOptions, ExistingLRUCacheOptions, ExistingTTLCacheOptions, ICache, IORedisCache, IORedisCacheOptions, JitteringCache, JitteringCacheOptions, KeyTransformingCache, KeyTransformingCacheOptions, KeyvCache, KeyvCacheOptions, LocalLRUCache, LocalLRUCacheOptions, LocalMapCache, LocalMapCacheOptions, LocalTTLCache, LocalTTLCacheOptions, Logger, MapLike, MemJSCache, MemJSCacheOptions, MemcacheCache, MemcacheCacheOptions, MetricsCollectingCache, MetricsCollectingCacheOptions, NoOpCache, RedisCache, RedisCacheOptions, SWRCache, SWRCacheOptions, SetCacheOptions, TieredCache, TieredCacheOptions, ValkeyGlideCache, ValkeyGlideCacheOptions, WorkersKVCache, WorkersKVCacheOptions };
+//# sourceMappingURL=index.d.cts.map