@gravito/stasis 3.0.1 → 3.1.1

package/dist/index.d.ts

@@ -1,10 +1,26 @@
-import { PlanetCore, GravitoOrbit } from '@gravito/core';
+import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
 /**
  * Error thrown when a lock cannot be acquired within the specified timeout.
  *
+ * This error indicates that the maximum waiting time for a distributed lock
+ * has been exceeded without successfully gaining ownership.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await cache.lock('resource', 10).block(5, async () => {
+ *     // ...
+ *   });
+ * } catch (error) {
+ *   if (error instanceof LockTimeoutError) {
+ *     console.error('Failed to acquire lock within 5 seconds');
+ *   }
+ * }
+ * ```
  */
 declare class LockTimeoutError extends Error {
     name: string;
@@ -12,212 +28,515 @@ declare class LockTimeoutError extends Error {
 /**
  * Interface for a cache-backed distributed lock.
  *
+ * A distributed lock ensures mutual exclusion across multiple processes or
+ * instances by using a shared cache as the synchronization primitive.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const lock = cache.lock('process', 60);
+ * const result = await lock.block(10, async () => {
+ *   // Exclusive work
+ *   return 42;
+ * });
+ * ```
  */
 interface CacheLock {
     /**
-     * Attempt to acquire the lock.
+     * Attempt to acquire the lock immediately.
+     *
+     * Uses an atomic "set if not exists" operation in the underlying cache
+     * to ensure only one owner can hold the lock at a time.
      *
-     * @returns `true` if acquired, `false` otherwise.
+     * @returns `true` if the lock was successfully acquired, `false` if it is already held.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const acquired = await lock.acquire();
+     * if (acquired) {
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
      */
     acquire(): Promise<boolean>;
     /**
      * Release the lock.
+     *
+     * Removes the lock entry from the cache, allowing other processes to acquire it.
+     * Should typically be called in a `finally` block to ensure the lock is not leaked.
+     *
+     * @returns A promise that resolves when the lock is released.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * await lock.release();
+     * ```
      */
     release(): Promise<void>;
     /**
-     * Attempt to acquire the lock and execute a callback.
-     * If the lock is held by someone else, it will wait (poll) until the timeout.
+     * Extend the lock's time-to-live (TTL).
+     *
+     * Increases the expiration time of the lock to prevent it from being
+     * automatically released while a long-running task is still in progress.
+     *
+     * @param seconds - Duration in seconds to add to the current TTL.
+     * @returns `true` if the lock was extended (still owned by this process), `false` otherwise.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const extended = await lock.extend(30);
+     * if (!extended) {
+     *   throw new Error('Lock lost or expired before extension');
+     * }
+     * ```
+     */
+    extend?(seconds: number): Promise<boolean>;
+    /**
+     * Get the remaining time-to-live for the lock.
      *
-     * @param seconds - Maximum time to wait for the lock in seconds.
-     * @param callback - Function to execute once the lock is acquired.
-     * @param options - Polling options.
-     * @returns The result of the callback.
-     * @throws {LockTimeoutError} If the lock could not be acquired within the timeout.
+     * Useful for monitoring or determining if a lock extension is necessary.
+     *
+     * @returns Remaining TTL in seconds. Returns -1 if the lock doesn't exist, or -2 if it has no TTL.
+     * @throws {Error} If the underlying cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const ttl = await lock.getRemainingTime();
+     * if (ttl > 0 && ttl < 5) {
+     *   await lock.extend(10);
+     * }
+     * ```
+     */
+    getRemainingTime?(): Promise<number>;
+    /**
+     * Attempt to acquire the lock and execute a callback with automatic retry.
+     *
+     * If the lock is currently held, this method will poll the cache at regular
+     * intervals until the lock is acquired or the timeout is reached.
+     *
+     * @param seconds - Maximum duration to wait for the lock in seconds.
+     * @param callback - Logic to execute once the lock is successfully acquired.
+     * @param options - Configuration for polling and retry behavior.
+     * @returns The value returned by the callback.
+     * @throws {LockTimeoutError} If the lock cannot be acquired within the specified timeout.
+     * @throws {Error} If the callback throws or the cache store fails.
+     *
+     * @example
+     * ```typescript
+     * const result = await lock.block(10, async () => {
+     *   return await performAtomicOperation();
+     * });
+     * ```
+     */
+    block<T>(seconds: number, callback: () => Promise<T> | T, options?: BlockOptions): Promise<T>;
+}
+/**
+ * Configuration for the `block()` method's retry logic.
+ *
+ * Defines how the lock acquisition should behave when the lock is already held,
+ * including polling intervals and cancellation support.
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const options: BlockOptions = {
+ *   retryInterval: 250,
+ *   maxRetries: 10
+ * };
+ * ```
+ */
+interface BlockOptions {
+    /**
+     * Delay between consecutive acquisition attempts.
+     * @defaultValue 100
+     */
+    retryInterval?: number;
+    /**
+     * Maximum number of times to attempt acquisition before failing.
+     * @defaultValue Infinity
+     */
+    maxRetries?: number;
+    /**
+     * Signal to allow external cancellation of the waiting process.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     * setTimeout(() => controller.abort(), 2000);
+     * await lock.block(10, task, { signal: controller.signal });
+     * ```
+     */
+    signal?: AbortSignal;
+    /**
+     * @deprecated Use `retryInterval` instead.
      */
-    block<T>(seconds: number, callback: () => Promise<T> | T, options?: {
-        sleepMillis?: number;
-    }): Promise<T>;
+    sleepMillis?: number;
 }
 /**
- * Pause execution for a specified number of milliseconds.
+ * Pause execution for a specified duration.
  *
- * @param ms - Milliseconds to sleep.
+ * Internal utility used for implementing polling delays in lock acquisition.
+ *
+ * @param ms - Duration to pause in milliseconds.
+ * @returns A promise that resolves after the delay.
  * @internal
  */
 declare function sleep(ms: number): Promise<void>;
 
 /**
- * Represents a unique identifier for a cached item.
+ * Unique identifier for a cached item.
+ *
+ * Used to reference and retrieve specific data entries within the cache storage.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const key: CacheKey = 'user:123:profile';
+ * ```
  */
 type CacheKey = string;
 /**
  * Time-to-live (TTL) configuration for cache entries.
  *
- * - `number`: Seconds from now.
- * - `Date`: Absolute expiry time.
- * - `null`: Cache forever.
- * - `undefined`: Use the store/repository default.
+ * Defines the duration or point in time when a cache entry becomes invalid.
+ * - `number`: Relative duration in seconds from the current time.
+ * - `Date`: Absolute point in time for expiration.
+ * - `null`: Persistent storage that never expires automatically.
+ * - `undefined`: Fallback to the default TTL configured in the store or repository.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const ttl: CacheTtl = 3600; // 1 hour
+ * const absoluteTtl: CacheTtl = new Date('2026-12-31');
+ * ```
  */
 type CacheTtl = number | Date | null | undefined;
 /**
- * Result of a cache retrieval.
- * Returns the value of type `T` or `null` if not found or expired.
+ * Result of a cache retrieval operation.
+ *
+ * Represents the cached data of type `T`, or `null` if the entry is missing or has expired.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const val: CacheValue<string> = 'cached content';
+ * const miss: CacheValue<number> = null;
+ * ```
  */
 type CacheValue<T = unknown> = T | null;
 /**
- * Normalize a cache key to ensure it is valid.
+ * Validates and prepares a cache key for storage operations.
+ *
+ * Ensures the key meets the minimum requirements for cache storage, such as being non-empty.
  *
- * @param key - The raw cache key.
- * @returns The normalized cache key.
- * @throws {Error} If the key is empty.
+ * @param key - The raw string to be used as a cache key.
+ * @returns The validated cache key.
+ * @throws {Error} Thrown if the provided key is an empty string or falsy.
+ *
+ * @example
+ * ```typescript
+ * const key = normalizeCacheKey('user_profile_123');
+ * ```
  *
  * @public
  * @since 3.0.0
  */
 declare function normalizeCacheKey(key: string): string;
 /**
- * Convert a CacheTtl value to an absolute epoch timestamp.
+ * Converts a flexible TTL definition into an absolute Unix epoch timestamp.
  *
- * @param ttl - The TTL value to convert.
- * @param now - Optional current timestamp in milliseconds.
- * @returns The expiration timestamp in milliseconds, null for forever, or undefined.
+ * Normalizes various TTL formats into a consistent millisecond-based timestamp
+ * used for expiration checks.
+ *
+ * @param ttl - The TTL configuration to convert.
+ * @param now - Reference timestamp in milliseconds for relative calculations. Defaults to current time.
+ * @returns The expiration timestamp in milliseconds, `null` for permanent storage, or `undefined` for default behavior.
+ *
+ * @example
+ * ```typescript
+ * // Relative TTL (60 seconds)
+ * const expiresAt = ttlToExpiresAt(60);
+ *
+ * // Absolute Date
+ * const expiresAtDate = ttlToExpiresAt(new Date('2026-12-31'));
+ * ```
  *
  * @public
  * @since 3.0.0
  */
 declare function ttlToExpiresAt(ttl: CacheTtl, now?: number): number | null | undefined;
 /**
- * Determine if a specific expiration timestamp has passed.
+ * Evaluates whether a cache entry has exceeded its expiration time.
+ *
+ * Compares the provided expiration timestamp against a reference time to determine
+ * if the cached data should be considered stale.
+ *
+ * @param expiresAt - The expiration timestamp in milliseconds, or `null`/`undefined` for non-expiring entries.
+ * @param now - Reference timestamp in milliseconds for the comparison. Defaults to current time.
+ * @returns `true` if the current time has passed the expiration point; otherwise `false`.
  *
- * @param expiresAt - The expiration timestamp in milliseconds (or null for forever).
- * @param now - Optional current timestamp in milliseconds.
- * @returns `true` if expired, `false` otherwise.
+ * @example
+ * ```typescript
+ * const expired = isExpired(Date.now() - 1000); // true
+ * const persistent = isExpired(null); // false
+ * ```
  *
  * @public
  * @since 3.0.0
  */
 declare function isExpired(expiresAt: number | null | undefined, now?: number): boolean;
+/**
+ * Options for data compression within the cache.
+ *
+ * Defines how and when data should be compressed before storage to save space
+ * and reduce I/O overhead.
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const options: CompressionOptions = {
+ *   enabled: true,
+ *   minSize: 2048,
+ *   level: 9
+ * };
+ * ```
+ */
+type CompressionOptions = {
+    /**
+     * Whether to enable compression for cached values.
+     *
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * Minimum size in bytes for the value to be compressed.
+     * Values smaller than this threshold will be stored uncompressed.
+     *
+     * @defaultValue 1024
+     */
+    minSize?: number;
+    /**
+     * Compression level for zlib (1-9).
+     * Higher levels provide better compression but require more CPU.
+     *
+     * @defaultValue 6
+     */
+    level?: number;
+};
 
 /**
- * Interface for a low-level cache storage backend.
+ * Low-level cache storage contract.
  *
- * All cache drivers (Memory, Redis, etc.) must implement this interface.
+ * Defines the essential operations for cache backends. Implementations of this interface
+ * (e.g., Memory, Redis, File) provide the actual persistence logic for the cache system.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * class MyStore implements CacheStore {
+ *   async get(key) { ... }
+ *   async put(key, value, ttl) { ... }
+ *   // ... other methods
+ * }
+ * ```
  */
 interface CacheStore {
     /**
-     * Retrieve an item from the cache by its key.
+     * Retrieve an item from the cache.
      *
-     * @param key - The unique cache key.
-     * @returns A promise that resolves to the cached value, or null if not found or expired.
+     * Fetches the value associated with the given key. If the item has expired or does not exist,
+     * the implementation should return null.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @returns The cached value or null if missing/expired.
+     * @throws {Error} If the storage backend is unreachable or encounters a read failure.
      */
     get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
     /**
-     * Store an item in the cache for a specific duration.
+     * Store an item in the cache.
      *
-     * @param key - The unique cache key.
-     * @param value - The value to store.
-     * @param ttl - Time-to-live.
+     * Persists a value with a specific expiration time. Overwrites any existing value for the same key.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @param value - Data to be persisted.
+     * @param ttl - Duration in seconds until the item expires.
+     * @returns Resolves when the write operation completes.
+     * @throws {Error} If the storage backend is full or encounters a write failure.
      */
     put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
     /**
-     * Store an item in the cache only if the key does not already exist.
+     * Store an item if it does not already exist.
      *
-     * @param key - The unique cache key.
-     * @param value - The value to store.
-     * @param ttl - Time-to-live.
-     * @returns A promise that resolves to true if the item was added, false otherwise.
+     * Atomic operation to ensure a value is only stored if the key is currently vacant.
+     *
+     * @param key - Unique identifier for the cached item.
+     * @param value - Data to be persisted.
+     * @param ttl - Duration in seconds until the item expires.
+     * @returns True if the item was successfully added, false if it already existed.
+     * @throws {Error} If the storage backend encounters a concurrency or write failure.
      */
     add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
     /**
-     * Remove an item from the cache by its key.
+     * Remove an item from the cache.
      *
-     * @param key - The cache key to remove.
-     * @returns A promise that resolves to true if the item existed and was removed.
+     * Deletes the entry associated with the specified key.
+     *
+     * @param key - Identifier of the item to be removed.
+     * @returns True if the item existed and was removed, false otherwise.
+     * @throws {Error} If the storage backend encounters a deletion failure.
      */
     forget(key: CacheKey): Promise<boolean>;
     /**
-     * Remove all items from the cache storage.
+     * Wipe all items from the cache storage.
+     *
+     * Clears the entire cache backend. Use with caution as this operation is destructive.
+     *
+     * @returns Resolves when the flush operation completes.
+     * @throws {Error} If the storage backend fails to clear the data.
      */
     flush(): Promise<void>;
     /**
-     * Increment the value of a numeric item in the cache.
+     * Increment a numeric value in the cache.
      *
-     * @param key - The cache key.
-     * @param value - The amount to increment by.
-     * @returns The new value.
+     * Atomically increases the value of a numeric item. If the key does not exist,
+     * it is typically initialized to zero before incrementing.
+     *
+     * @param key - Identifier of the numeric item.
+     * @param value - Amount to add to the current value.
+     * @returns The updated numeric value.
+     * @throws {TypeError} If the existing value is not numeric.
+     * @throws {Error} If the storage backend encounters an atomic update failure.
      */
     increment(key: CacheKey, value?: number): Promise<number>;
     /**
-     * Decrement the value of a numeric item in the cache.
+     * Decrement a numeric value in the cache.
      *
-     * @param key - The cache key.
-     * @param value - The amount to decrement by.
-     * @returns The new value.
+     * Atomically decreases the value of a numeric item. If the key does not exist,
+     * it is typically initialized to zero before decrementing.
+     *
+     * @param key - Identifier of the numeric item.
+     * @param value - Amount to subtract from the current value.
+     * @returns The updated numeric value.
+     * @throws {TypeError} If the existing value is not numeric.
+     * @throws {Error} If the storage backend encounters an atomic update failure.
      */
     decrement(key: CacheKey, value?: number): Promise<number>;
     /**
-     * Get a distributed lock instance for the given name.
+     * Create a distributed lock instance.
      *
-     * @param name - The lock name.
-     * @param seconds - Optional default duration for the lock.
-     * @returns A `CacheLock` instance if supported, otherwise undefined.
+     * Provides a mechanism for mutual exclusion across multiple processes or servers
+     * using the cache backend as the synchronization provider.
+     *
+     * @param name - Unique name for the lock.
+     * @param seconds - Default duration for which the lock should be held.
+     * @returns A lock instance if supported by the driver, otherwise undefined.
      */
     lock?(name: string, seconds?: number): CacheLock | undefined;
+    /**
+     * Get the remaining lifetime of a cached item.
+     *
+     * Calculates how many seconds are left before the item expires.
+     *
+     * @param key - Identifier of the cached item.
+     * @returns Seconds remaining until expiration, or null if the key has no TTL or does not exist.
+     * @throws {Error} If the storage backend encounters a read failure.
+     */
+    ttl?(key: CacheKey): Promise<number | null>;
 }
 /**
- * Interface for cache stores that support grouping entries by tags.
+ * Contract for cache stores supporting tag-based invalidation.
+ *
+ * Allows grouping cache entries under one or more tags, enabling bulk invalidation
+ * of related items without knowing their individual keys.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * if (isTaggableStore(store)) {
+ *   await store.flushTags(['users']);
+ * }
+ * ```
  */
 interface TaggableStore {
     /**
-     * Remove all items associated with the given tags.
+     * Invalidate all items associated with specific tags.
      *
-     * @param tags - An array of tag names.
+     * Effectively clears all cache entries that were stored with any of the provided tags.
+     *
+     * @param tags - List of tags to be flushed.
+     * @returns Resolves when the tag invalidation completes.
+     * @throws {Error} If the storage backend fails to process the tag flush.
      */
     flushTags(tags: readonly string[]): Promise<void>;
     /**
-     * Generate a tagged key for storage based on the provided tags.
+     * Compute a namespaced key based on tags.
      *
-     * @param key - The original cache key.
-     * @param tags - An array of tag names.
-     * @returns The tagged key string.
+     * Generates a unique internal key that incorporates tag versioning to ensure
+     * proper isolation and invalidation.
+     *
+     * @param key - Original user-provided cache key.
+     * @param tags - Tags to associate with the key.
+     * @returns A derived key string used for actual storage.
      */
     tagKey(key: string, tags: readonly string[]): string;
     /**
-     * Add a key to the index for specific tags.
+     * Register a key in the tag index.
      *
-     * @param tags - An array of tag names.
-     * @param taggedKey - The key to associate with the tags.
+     * Maintains the relationship between tags and their associated keys for tracking.
+     *
+     * @param tags - Tags to index the key under.
+     * @param taggedKey - The derived key to be indexed.
+     * @returns Resolves when the indexing completes.
      */
-    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void | Promise<void>;
     /**
-     * Remove a key from the tag index.
+     * Unregister a key from all tag indexes.
+     *
+     * Removes the tracking information for a specific derived key.
      *
-     * @param taggedKey - The key to remove from all tag indexes.
+     * @param taggedKey - The derived key to remove from indexes.
+     * @returns Resolves when the removal completes.
      */
-    tagIndexRemove(taggedKey: string): void;
+    tagIndexRemove(taggedKey: string): void | Promise<void>;
 }
 /**
- * Type guard to check if a cache store supports tagging.
+ * Validates if a cache store supports tagging operations.
+ *
+ * Performs a runtime check to determine if the provided store implements the `TaggableStore` interface.
  *
- * @param store - The cache store instance to check.
- * @returns `true` if the store implements `TaggableStore`.
+ * @param store - The cache store instance to evaluate.
+ * @returns True if the store supports tagging, false otherwise.
+ *
+ * @example
+ * ```typescript
+ * if (isTaggableStore(myStore)) {
+ *   await myStore.flushTags(['users', 'posts']);
+ * }
+ * ```
  *
  * @public
  * @since 3.0.0
@@ -227,15 +546,33 @@ declare function isTaggableStore(store: CacheStore): store is CacheStore & Tagga
 /**
  * Supported modes for emitting cache events.
  *
+ * Defines how lifecycle hooks (hit, miss, write, etc.) are dispatched to handlers.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const mode: CacheEventMode = 'async';
+ * ```
  */
 type CacheEventMode = 'sync' | 'async' | 'off';
 /**
  * Event handlers for cache lifecycle events.
  *
+ * Provides a contract for reacting to cache operations, enabling logging,
+ * monitoring, or custom side effects.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const events: CacheEvents = {
+ *   hit: (key) => console.log(`Cache hit: ${key}`),
+ *   miss: (key) => console.log(`Cache miss: ${key}`)
+ * };
+ * ```
  */
 type CacheEvents = {
     /** Triggered on a cache hit. */
@@ -252,8 +589,20 @@ type CacheEvents = {
 /**
  * Options for configuring the `CacheRepository`.
  *
+ * Controls behavior such as key prefixing, event emission, and background
+ * refresh strategies for flexible caching.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: CacheRepositoryOptions = {
+ *   prefix: 'v1:',
+ *   defaultTtl: 3600,
+ *   eventsMode: 'async'
+ * };
+ * ```
  */
 type CacheRepositoryOptions = {
     /** Optional prefix for all cache keys. */
@@ -262,24 +611,64 @@ type CacheRepositoryOptions = {
     defaultTtl?: CacheTtl;
     /** Event handlers for cache operations. */
     events?: CacheEvents;
-    /** Mode for emitting events (sync, async, or off). @default 'async' */
+    /** Mode for emitting events (sync, async, or off). */
     eventsMode?: CacheEventMode;
-    /** Whether to throw an error if an event handler fails. @default false */
+    /** Whether to throw an error if an event handler fails. @defaultValue false */
     throwOnEventError?: boolean;
     /** Callback triggered when an event handler encounters an error. */
     onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
         key?: string;
     }) => void;
+    /** Timeout for background flexible refresh in milliseconds. @defaultValue 30000 */
+    refreshTimeout?: number;
+    /**
+     * Maximum number of retries for the background flexible refresh callback.
+     * @defaultValue 0
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries for flexible refresh in milliseconds.
+     * @defaultValue 50
+     */
+    retryDelay?: number;
+    /**
+     * Compression settings for cached values.
+     *
+     * @since 3.1.0
+     */
+    compression?: CompressionOptions;
+};
+/**
+ * Statistics for flexible cache operations.
+ *
+ * Tracks the performance and reliability of background refresh operations
+ * used in stale-while-revalidate patterns.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const stats: FlexibleStats = {
+ *   refreshCount: 10,
+ *   refreshFailures: 0,
+ *   avgRefreshTime: 15.5
+ * };
+ * ```
+ */
+type FlexibleStats = {
+    /** Total number of successful background refreshes. */
+    refreshCount: number;
+    /** Total number of background refresh failures (after all retries). */
+    refreshFailures: number;
+    /** Average time taken for a successful refresh in milliseconds. */
+    avgRefreshTime: number;
 };
 /**
- * CacheRepository provides a high-level, developer-friendly API for cache operations.
+ * High-level API for cache operations.
  *
- * It wraps a low-level `CacheStore` and adds features like:
- * - Key prefixing.
- * - Event emission (hit, miss, write, etc.).
- * - Automatic serialization/deserialization.
- * - Higher-level helpers like `remember`, `flexible`, and `pull`.
- * - Support for tagged cache entries (if the store supports it).
+ * Wraps a low-level `CacheStore` to provide developer-friendly features like
+ * key prefixing, event emission, and advanced patterns like `remember` and `flexible`.
  *
  * @example
  * ```typescript
@@ -293,72 +682,463 @@ type CacheRepositoryOptions = {
 declare class CacheRepository {
     protected readonly store: CacheStore;
     protected readonly options: CacheRepositoryOptions;
+    private refreshSemaphore;
+    private coalesceSemaphore;
+    private flexibleStats;
     constructor(store: CacheStore, options?: CacheRepositoryOptions);
+    /**
+     * Retrieve statistics about flexible cache operations.
+     *
+     * Useful for monitoring the health and performance of background refreshes.
+     *
+     * @returns Current statistics for background refresh operations.
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getFlexibleStats();
+     * console.log(`Refreshed ${stats.refreshCount} times`);
+     * ```
+     */
+    getFlexibleStats(): FlexibleStats;
     private emit;
     protected key(key: CacheKey): string;
     protected flexibleFreshUntilKey(fullKey: string): string;
     protected putMetaKey(metaKey: string, value: unknown, ttl: CacheTtl): Promise<void>;
     protected forgetMetaKey(metaKey: string): Promise<void>;
+    /**
+     * Retrieve an item from the cache by its key.
+     *
+     * Fetches the value from the underlying store. If not found, returns the
+     * provided default value or executes the factory function.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - A default value or factory function to use if the key is not found.
+     * @returns The cached value, or the default value if not found.
+     * @throws {Error} If the underlying store fails to retrieve the value.
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.get('user:1', { name: 'Guest' });
+     * const settings = await cache.get('settings', () => fetchSettings());
+     * ```
+     */
     get<T = unknown>(key: CacheKey, defaultValue?: T | (() => T | Promise<T>)): Promise<T | null>;
-    has(key: CacheKey): Promise<boolean>;
-    missing(key: CacheKey): Promise<boolean>;
-    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
-    set(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<void>;
-    add(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<boolean>;
-    forever(key: CacheKey, value: unknown): Promise<void>;
-    remember<T = unknown>(key: CacheKey, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
-    rememberForever<T = unknown>(key: CacheKey, callback: () => Promise<T> | T): Promise<T>;
-    many<T = unknown>(keys: readonly CacheKey[]): Promise<Record<string, T | null>>;
-    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
     /**
-     * Laravel-like flexible cache (stale-while-revalidate).
+     * Determine if an item exists in the cache.
+     *
+     * Checks for the presence of a key without necessarily returning its value.
      *
-     * - `ttlSeconds`: how long the value is considered fresh
-     * - `staleSeconds`: how long the stale value may be served while a refresh happens
+     * @param key - The cache key.
+     * @returns True if the item exists, false otherwise.
+     * @throws {Error} If the underlying store fails to check existence.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.has('session:active')) {
+     *   // ...
+     * }
+     * ```
+     */
+    has(key: CacheKey): Promise<boolean>;
+    /**
+     * Determine if an item is missing from the cache.
+     *
+     * Inverse of `has()`, used for cleaner conditional logic.
+     *
+     * @param key - The cache key.
+     * @returns True if the item is missing, false otherwise.
+     * @throws {Error} If the underlying store fails to check existence.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.missing('config:loaded')) {
+     *   await loadConfig();
+     * }
+     * ```
+     */
+    missing(key: CacheKey): Promise<boolean>;
+    /**
+     * Store an item in the cache for a specific duration.
+     *
+     * Persists the value in the underlying store with the given TTL.
+     *
+     * @param key - Unique cache key.
+     * @param value - Value to store.
+     * @param ttl - Expiration duration.
+     * @throws {Error} If the underlying store fails to persist the value or serialization fails.
+     *
+     * @example
+     * ```typescript
+     * await cache.put('token', 'xyz123', 3600);
+     * ```
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache for a specific duration.
+     *
+     * Uses the repository's default TTL if none is provided.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Optional time-to-live.
+     * @throws {Error} If the underlying store fails to persist the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.set('theme', 'dark');
+     * ```
+     */
+    set(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the cache only if the key does not already exist.
+     *
+     * Atomic operation to prevent overwriting existing data.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @param ttl - Optional time-to-live.
+     * @returns True if the item was added, false otherwise.
+     * @throws {Error} If the underlying store fails the atomic operation.
+     *
+     * @example
+     * ```typescript
+     * const added = await cache.add('lock:process', true, 60);
+     * ```
+     */
+    add(key: CacheKey, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    /**
+     * Store an item in the cache indefinitely.
+     *
+     * Sets the TTL to null, indicating the value should not expire automatically.
+     *
+     * @param key - The unique cache key.
+     * @param value - The value to store.
+     * @throws {Error} If the underlying store fails to persist the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.forever('system:id', 'node-01');
+     * ```
+     */
+    forever(key: CacheKey, value: unknown): Promise<void>;
+    /**
+     * Get an item from the cache, or execute the given callback and store the result.
+     *
+     * Implements the "Cache-Aside" pattern, ensuring the callback is only executed
+     * on a cache miss.
+     *
+     * @param key - The unique cache key.
+     * @param ttl - Time-to-live.
+     * @param callback - The callback to execute if the key is not found.
+     * @returns The cached value or the result of the callback.
+     * @throws {Error} If the callback or the underlying store fails.
+     *
+     * @example
+     * ```typescript
+     * const data = await cache.remember('users:all', 300, () => db.users.findMany());
+     * ```
+     */
+    remember<T = unknown>(key: CacheKey, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Get an item from the cache, or execute the given callback and store the result indefinitely.
+     *
+     * Similar to `remember()`, but the value is stored without an expiration time.
+     *
+     * @param key - The unique cache key.
+     * @param callback - The callback to execute if the key is not found.
+     * @returns The cached value or the result of the callback.
+     * @throws {Error} If the callback or the underlying store fails.
+     *
+     * @example
+     * ```typescript
+     * const config = await cache.rememberForever('app:config', () => loadConfig());
+     * ```
+     */
+    rememberForever<T = unknown>(key: CacheKey, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve multiple items from the cache by their keys.
+     *
+     * Efficiently fetches multiple values, returning a map of keys to values.
+     *
+     * @param keys - An array of unique cache keys.
+     * @returns An object where keys are the original keys and values are the cached values.
+     * @throws {Error} If the underlying store fails to retrieve values.
+     *
+     * @example
+     * ```typescript
+     * const results = await cache.many(['user:1', 'user:2']);
+     * ```
+     */
+    many<T = unknown>(keys: readonly CacheKey[]): Promise<Record<string, T | null>>;
+    /**
+     * Store multiple items in the cache for a specific duration.
+     *
+     * Persists multiple key-value pairs in a single operation if supported by the store.
+     *
+     * @param values - An object where keys are the unique cache keys and values are the values to store.
+     * @param ttl - Time-to-live.
+     * @throws {Error} If the underlying store fails to persist values.
+     *
+     * @example
+     * ```typescript
+     * await cache.putMany({ 'a': 1, 'b': 2 }, 60);
+     * ```
+     */
+    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    /**
+     * Laravel-like flexible cache (stale-while-revalidate).
+     *
+     * Serves stale content while revalidating the cache in the background. This
+     * minimizes latency for users by avoiding synchronous revalidation.
+     *
+     * @param key - The unique cache key.
+     * @param ttlSeconds - How long the value is considered fresh.
+     * @param staleSeconds - How long the stale value may be served while a refresh happens.
+     * @param callback - The callback to execute to refresh the cache.
+     * @returns The fresh or stale cached value.
+     * @throws {Error} If the callback fails on a cache miss.
+     *
+     * @example
+     * ```typescript
+     * const value = await cache.flexible('stats', 60, 30, () => fetchStats());
+     * ```
+     */
+    flexible<T = unknown>(key: CacheKey, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
+    private refreshFlexible;
+    private doRefresh;
+    /**
+     * Retrieve an item from the cache and delete it.
+     *
+     * Atomic-like operation to fetch and immediately remove a value, often used
+     * for one-time tokens or flash messages.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - A default value to use if the key is not found.
+     * @returns The cached value, or the default value if not found.
+     * @throws {Error} If the underlying store fails to retrieve or forget the value.
+     *
+     * @example
+     * ```typescript
+     * const message = await cache.pull('flash:status');
+     * ```
+     */
+    pull<T = unknown>(key: CacheKey, defaultValue?: T): Promise<T | null>;
+    /**
+     * Remove an item from the cache by its key.
+     *
+     * Deletes the value and any associated metadata from the underlying store.
+     *
+     * @param key - The cache key to remove.
+     * @returns True if the item existed and was removed.
+     * @throws {Error} If the underlying store fails to remove the value.
+     *
+     * @example
+     * ```typescript
+     * const deleted = await cache.forget('user:session');
+     * ```
      */
-    flexible<T = unknown>(key: CacheKey, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
-    private refreshFlexible;
-    pull<T = unknown>(key: CacheKey, defaultValue?: T): Promise<T | null>;
     forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Alias for `forget`.
+     *
+     * Provides compatibility with standard `Map`-like or `Storage` APIs.
+     *
+     * @param key - The cache key to remove.
+     * @returns True if the item existed and was removed.
+     * @throws {Error} If the underlying store fails to remove the value.
+     *
+     * @example
+     * ```typescript
+     * await cache.delete('temp:data');
+     * ```
+     */
     delete(key: CacheKey): Promise<boolean>;
+    /**
+     * Remove all items from the cache storage.
+     *
+     * Clears the entire underlying store. Use with caution as this affects all
+     * keys regardless of prefix.
+     *
+     * @throws {Error} If the underlying store fails to flush.
+     *
+     * @example
+     * ```typescript
+     * await cache.flush();
+     * ```
+     */
     flush(): Promise<void>;
+    /**
+     * Alias for `flush`.
+     *
+     * Provides compatibility with standard `Map`-like or `Storage` APIs.
+     *
+     * @throws {Error} If the underlying store fails to clear.
+     *
+     * @example
+     * ```typescript
+     * await cache.clear();
+     * ```
+     */
     clear(): Promise<void>;
+    /**
+     * Increment the value of a numeric item in the cache.
+     *
+     * Atomically increases the value of a key. If the key does not exist, it is
+     * typically initialized to 0 before incrementing.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to increment by.
+     * @returns The new value.
+     * @throws {Error} If the underlying store fails the atomic increment.
+     *
+     * @example
+     * ```typescript
+     * const count = await cache.increment('page:views');
+     * ```
+     */
     increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement the value of a numeric item in the cache.
+     *
+     * Atomically decreases the value of a key.
+     *
+     * @param key - The cache key.
+     * @param value - The amount to decrement by.
+     * @returns The new value.
+     * @throws {Error} If the underlying store fails the atomic decrement.
+     *
+     * @example
+     * ```typescript
+     * const remaining = await cache.decrement('stock:count');
+     * ```
+     */
     decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Get a distributed lock instance for the given name.
+     *
+     * Provides a mechanism for exclusive access to resources across multiple
+     * processes or servers.
+     *
+     * @param name - The lock name.
+     * @param seconds - Optional default duration for the lock in seconds.
+     * @returns A `CacheLock` instance if supported, otherwise undefined.
+     *
+     * @example
+     * ```typescript
+     * const lock = cache.lock('process:heavy', 10);
+     * if (await lock.acquire()) {
+     *   try {
+     *     // ...
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
     lock(name: string, seconds?: number): CacheLock | undefined;
+    /**
+     * Create a new repository instance with the given tags.
+     *
+     * Enables grouping of cache entries for collective operations like flushing
+     * all keys associated with specific tags.
+     *
+     * @param tags - An array of tag names.
+     * @returns A new `CacheRepository` instance that uses the given tags.
+     * @throws {Error} If the underlying store does not support tagging.
+     *
+     * @example
+     * ```typescript
+     * await cache.tags(['users', 'profiles']).put('user:1', data, 3600);
+     * await cache.tags(['users']).flush();
+     * ```
+     */
     tags(tags: readonly string[]): CacheRepository;
     /**
-     * Get the underlying store
+     * Retrieve the underlying cache store.
+     *
+     * Provides direct access to the low-level store implementation for advanced
+     * use cases or debugging.
+     *
+     * @returns The low-level cache store instance.
+     *
+     * @example
+     * ```typescript
+     * const store = cache.getStore();
+     * ```
      */
     getStore(): CacheStore;
+    /**
+     * Compress a value before storage if compression is enabled and thresholds are met.
+     */
+    private compress;
+    /**
+     * Decompress a value after retrieval if it was previously compressed.
+     */
+    private decompress;
 }
 
 /**
  * Represents the response from a rate limiting attempt.
  *
+ * This interface provides the necessary metadata to determine if a request
+ * should be throttled and when the client can safely retry.
+ *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const res: RateLimiterResponse = { allowed: true, remaining: 4, reset: 1622548800 };
+ * ```
  */
 interface RateLimiterResponse {
-    /** Whether the request is allowed. */
+    /** Whether the request is allowed based on current usage and limits. */
     allowed: boolean;
-    /** Number of attempts remaining within the current window. */
+    /** Number of attempts remaining within the current time window. */
+    remaining: number;
+    /** Epoch timestamp in seconds when the rate limit window will reset. */
+    reset: number;
+    /** Seconds until the rate limit resets, typically used for the `Retry-After` header. */
+    retryAfter?: number;
+}
+/**
+ * Detailed information about the current rate limit status.
+ *
+ * Used for inspecting the state of a limiter without necessarily
+ * consuming an attempt or triggering a state change.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const info: RateLimitInfo = { limit: 10, remaining: 5, reset: 1622548800 };
+ * ```
+ */
+interface RateLimitInfo {
+    /** Maximum number of attempts allowed within the configured window. */
+    limit: number;
+    /** Number of attempts remaining before the limit is reached. */
     remaining: number;
-    /** Epoch timestamp in seconds when the rate limit will reset. */
+    /** Epoch timestamp in seconds when the rate limit window will reset. */
     reset: number;
+    /** Seconds until the rate limit resets, only present when the limit has been exceeded. */
+    retryAfter?: number;
 }
 /**
  * RateLimiter provides a simple mechanism for limiting request frequency.
  *
  * It uses a `CacheStore` backend to track attempt counts and handle
- * expiration (sliding or fixed window depending on store capability).
+ * expiration. This allows for distributed rate limiting when using
+ * shared stores like Redis, or local limiting with memory stores.
  *
  * @example
  * ```typescript
  * const limiter = new RateLimiter(cacheStore);
  * const status = await limiter.attempt('login:127.0.0.1', 5, 60);
+ *
  * if (!status.allowed) {
- *   throw new Error('Too many attempts');
+ *   console.log(`Too many attempts. Retry after ${status.retryAfter}s`);
  * }
  * ```
  *
@@ -367,25 +1147,101 @@ interface RateLimiterResponse {
  */
 declare class RateLimiter {
     private store;
+    /**
+     * Creates a new RateLimiter instance.
+     *
+     * @param store - Cache backend used to persist attempt counts.
+     *
+     * @example
+     * ```typescript
+     * const limiter = new RateLimiter(new MemoryStore());
+     * ```
+     */
     constructor(store: CacheStore);
     /**
-     * Attempt to acquire a lock
-     * @param key - The unique key (e.g., "ip:127.0.0.1")
-     * @param maxAttempts - Maximum number of attempts allowed
-     * @param decaySeconds - Time in seconds until the limit resets
+     * Attempt to consume a slot in the rate limit window.
+     *
+     * This method checks the current attempt count for the given key. If the
+     * count is below the limit, it increments the count and allows the request.
+     * Otherwise, it returns a rejected status with retry information.
+     *
+     * @param key - The unique identifier for the rate limit (e.g., IP address or user ID).
+     * @param maxAttempts - Maximum number of attempts allowed within the decay period.
+     * @param decaySeconds - Duration of the rate limit window in seconds.
+     * @returns A response indicating if the attempt was successful and the remaining capacity.
+     * @throws {Error} If the underlying cache store fails to read or write data.
+     *
+     * @example
+     * ```typescript
+     * const response = await limiter.attempt('api-client:123', 100, 3600);
+     * if (response.allowed) {
+     *   // Proceed with request
+     * }
+     * ```
      */
     attempt(key: string, maxAttempts: number, decaySeconds: number): Promise<RateLimiterResponse>;
     /**
-     * Clear the limiter for a key
+     * Calculate the number of seconds until the rate limit resets.
+     *
+     * This helper method attempts to retrieve the TTL from the store. If the
+     * store does not support TTL inspection, it falls back to the provided
+     * decay period.
+     *
+     * @param key - Unique identifier for the rate limit.
+     * @param decaySeconds - Default decay period to use as a fallback.
+     * @returns Number of seconds until the key expires.
+     * @throws {Error} If the store fails to retrieve TTL metadata.
      */
-    clear(key: string): Promise<void>;
-}
-
-/**
- * Configuration for a specific cache store.
- *
- * @public
- * @since 3.0.0
+    availableIn(key: string, decaySeconds: number): Promise<number>;
+    /**
+     * Get detailed information about the current rate limit status without consuming an attempt.
+     *
+     * Useful for returning rate limit headers (e.g., X-RateLimit-Limit) in
+     * middleware or for pre-flight checks.
+     *
+     * @param key - The unique identifier for the rate limit.
+     * @param maxAttempts - Maximum number of attempts allowed.
+     * @param decaySeconds - Duration of the rate limit window in seconds.
+     * @returns Current status including limit, remaining attempts, and reset time.
+     * @throws {Error} If the underlying cache store fails to retrieve data.
+     *
+     * @example
+     * ```typescript
+     * const info = await limiter.getInfo('user:42', 60, 60);
+     * console.log(`Remaining: ${info.remaining}/${info.limit}`);
+     * ```
+     */
+    getInfo(key: string, maxAttempts: number, decaySeconds: number): Promise<RateLimitInfo>;
+    /**
+     * Reset the rate limit counter for a specific key.
+     *
+     * Use this to manually clear a block, for example after a successful
+     * login or when an administrator manually unblocks a user.
+     *
+     * @param key - The unique identifier to clear.
+     * @throws {Error} If the store fails to delete the key.
+     *
+     * @example
+     * ```typescript
+     * await limiter.clear('login-attempts:user@example.com');
+     * ```
+     */
+    clear(key: string): Promise<void>;
+}
+
+/**
+ * Configuration for a specific cache store driver.
+ *
+ * Defines the connection parameters and behavior for different storage backends
+ * like in-memory, local filesystem, or Redis.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config: StoreConfig = { driver: 'redis', connection: 'default' };
+ * ```
  */
 type StoreConfig = {
     driver: 'memory';
@@ -401,31 +1257,63 @@ type StoreConfig = {
     driver: 'null';
 } | {
     driver: 'provider';
+} | {
+    driver: 'tiered';
+    local: string;
+    remote: string;
+} | {
+    driver: 'circuit-breaker';
+    primary: string;
+    maxFailures?: number;
+    resetTimeout?: number;
+    fallback?: string;
 };
 /**
- * Global cache configuration for multiple stores.
+ * Global cache configuration for managing multiple named stores.
+ *
+ * Provides a central manifest to define default behavior, global key prefixing,
+ * and the registry of available storage backends.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const config: CacheConfig = {
+ *   default: 'redis',
+ *   prefix: 'app:',
+ *   stores: {
+ *     redis: { driver: 'redis' }
+ *   }
+ * };
+ * ```
  */
 type CacheConfig = {
-    /** The name of the default store to use. @default 'memory' */
+    /**
+     * The name of the default store to use when no store is explicitly requested.
+     */
     default?: string;
-    /** Global prefix for all cache keys across all stores. */
+    /**
+     * Global prefix prepended to all cache keys across all stores to prevent collisions.
+     */
     prefix?: string;
-    /** Global default time-to-live for cache entries. */
+    /**
+     * Global default time-to-live for cache entries when not specified in write operations.
+     */
     defaultTtl?: CacheTtl;
-    /** Map of named store configurations. */
+    /**
+     * Map of named store configurations, optionally including pre-instantiated providers.
+     */
     stores?: Record<string, StoreConfig & {
         provider?: CacheStore;
     }>;
 };
 /**
- * CacheManager orchestrates multiple cache stores and provides a unified API.
+ * Orchestrates multiple cache stores and provides a unified API.
  *
- * It supports various drivers (Memory, File, Redis) and provides both
- * a multi-store API (`cache.store('redis').get(...)`) and a default store
- * proxy API (`cache.get(...)`).
+ * Acts as a central registry for cache repositories, supporting various drivers
+ * (Memory, File, Redis). It provides both a multi-store API for targeted operations
+ * and a proxy API that forwards calls to the default store.
  *
  * @example
  * ```typescript
@@ -448,7 +1336,18 @@ declare class CacheManager {
     private readonly config;
     private readonly events?;
     private readonly eventOptions?;
+    /**
+     * Internal registry of initialized cache repositories.
+     */
     private stores;
+    /**
+     * Initialize a new CacheManager instance.
+     *
+     * @param storeFactory - Factory function to create low-level store instances by name.
+     * @param config - Configuration manifest for stores and global defaults.
+     * @param events - Optional event handlers for cache lifecycle hooks.
+     * @param eventOptions - Configuration for how events are dispatched and handled.
+     */
     constructor(storeFactory: (name: string) => CacheStore, config?: CacheConfig, events?: CacheEvents | undefined, eventOptions?: {
         mode?: CacheEventMode;
         throwOnError?: boolean;
@@ -457,17 +1356,51 @@ declare class CacheManager {
         }) => void;
     } | undefined);
     /**
-     * Get a rate limiter instance for a store
-     * @param name - Store name (optional, defaults to default store)
+     * Get a rate limiter instance for a specific store.
+     *
+     * Provides a specialized interface for throttling actions based on cache keys,
+     * leveraging the underlying storage for persistence.
+     *
+     * @param name - Store name (defaults to the configured default store).
+     * @returns A RateLimiter instance bound to the requested store.
+     * @throws {Error} If the requested store cannot be initialized.
+     *
+     * @example
+     * ```typescript
+     * const limiter = cache.limiter('redis');
+     * if (await limiter.tooManyAttempts('login:1', 5)) {
+     *   throw new Error('Too many attempts');
+     * }
+     * ```
      */
     limiter(name?: string): RateLimiter;
+    /**
+     * Resolve a named cache repository.
+     *
+     * Lazily initializes and caches the repository instance for the given store name.
+     * If no name is provided, it falls back to the default store.
+     *
+     * @param name - Store name to retrieve.
+     * @returns Initialized CacheRepository instance.
+     * @throws {Error} If the store factory fails to create the underlying store or the driver is unsupported.
+     *
+     * @example
+     * ```typescript
+     * const redis = cache.store('redis');
+     * await redis.put('key', 'value', 60);
+     * ```
+     */
     store(name?: string): CacheRepository;
     /**
-     * Retrieve an item from the cache.
+     * Retrieve an item from the default cache store.
      *
-     * @param key - The unique cache key.
-     * @param defaultValue - The default value if the key is missing (can be a value or a closure).
-     * @returns The cached value or the default.
+     * If the key is missing, the provided default value or the result of the
+     * default value closure will be returned.
+     *
+     * @param key - Unique cache key.
+     * @param defaultValue - Fallback value or factory to execute on cache miss.
+     * @returns Cached value or the resolved default.
+     * @throws {Error} If the underlying store driver encounters a read error or connection failure.
      *
      * @example
      * ```typescript
@@ -476,183 +1409,1131 @@ declare class CacheManager {
      */
     get<T = unknown>(key: string, defaultValue?: T | (() => T | Promise<T>)): Promise<T | null>;
     /**
-     * Check if an item exists in the cache.
+     * Determine if an item exists in the default cache store.
+     *
+     * @param key - The unique cache key.
+     * @returns True if the key exists and has not expired.
+     * @throws {Error} If the underlying store driver encounters a connection error.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.has('session:active')) {
+     *   // ...
+     * }
+     * ```
      */
     has(key: string): Promise<boolean>;
     /**
-     * Check if an item is missing from the cache.
+     * Determine if an item is missing from the default cache store.
+     *
+     * @param key - The unique cache key.
+     * @returns True if the key does not exist or has expired.
+     * @throws {Error} If the underlying store driver encounters a connection error.
+     *
+     * @example
+     * ```typescript
+     * if (await cache.missing('config:loaded')) {
+     *   await loadConfig();
+     * }
+     * ```
+     */
+    missing(key: string): Promise<boolean>;
+    /**
+     * Store an item in the default cache store for a specific duration.
+     *
+     * @param key - The unique cache key.
+     * @param value - The data to be cached.
+     * @param ttl - Expiration time in seconds or a specific Date.
+     * @returns A promise that resolves when the write is complete.
+     * @throws {Error} If the value cannot be serialized or the store is read-only.
+     *
+     * @example
+     * ```typescript
+     * await cache.put('key', 'value', 60); // 60 seconds
+     * ```
+     */
+    put(key: string, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the default cache store (alias for put).
+     *
+     * @param key - The unique cache key.
+     * @param value - The data to be cached.
+     * @param ttl - Optional expiration time.
+     * @returns A promise that resolves when the write is complete.
+     * @throws {Error} If the underlying store driver encounters a write error.
+     *
+     * @example
+     * ```typescript
+     * await cache.set('theme', 'dark');
+     * ```
+     */
+    set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
+    /**
+     * Store an item in the default cache store only if it does not already exist.
+     *
+     * @param key - The unique cache key.
+     * @param value - The data to be cached.
+     * @param ttl - Optional expiration time.
+     * @returns True if the item was added, false if it already existed.
+     * @throws {Error} If the underlying store driver encounters a write error.
+     *
+     * @example
+     * ```typescript
+     * const added = await cache.add('lock:process', true, 30);
+     * ```
+     */
+    add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
+    /**
+     * Store an item in the default cache store indefinitely.
+     *
+     * @param key - The unique cache key.
+     * @param value - The data to be cached.
+     * @returns A promise that resolves when the write is complete.
+     * @throws {Error} If the underlying store driver encounters a write error.
+     *
+     * @example
+     * ```typescript
+     * await cache.forever('system:version', '1.0.0');
+     * ```
+     */
+    forever(key: string, value: unknown): Promise<void>;
+    /**
+     * Get an item from the cache, or execute the callback and store the result.
+     *
+     * Ensures the value is cached after the first miss. This provides an atomic-like
+     * "get or set" flow to prevent multiple concurrent fetches of the same data.
+     *
+     * @param key - Unique cache key.
+     * @param ttl - Duration to cache the result if a miss occurs.
+     * @param callback - Logic to execute to fetch fresh data.
+     * @returns Cached or freshly fetched value.
+     * @throws {Error} If the callback fails or the store write operation errors.
+     *
+     * @example
+     * ```typescript
+     * const user = await cache.remember('user:1', 60, async () => {
+     *   return await db.findUser(1);
+     * });
+     * ```
+     */
+    remember<T = unknown>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Get an item from the cache, or execute the callback and store the result forever.
+     *
+     * @param key - The unique cache key.
+     * @param callback - The closure to execute to fetch the fresh data.
+     * @returns The cached or freshly fetched value.
+     * @throws {Error} If the callback throws or the store write fails.
+     *
+     * @example
+     * ```typescript
+     * const settings = await cache.rememberForever('global:settings', () => {
+     *   return fetchSettingsFromApi();
+     * });
+     * ```
+     */
+    rememberForever<T = unknown>(key: string, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve multiple items from the default cache store by their keys.
+     *
+     * @param keys - An array of unique cache keys.
+     * @returns An object mapping keys to their cached values (or null if missing).
+     * @throws {Error} If the underlying store driver encounters a read error.
+     *
+     * @example
+     * ```typescript
+     * const values = await cache.many(['key1', 'key2']);
+     * ```
+     */
+    many<T = unknown>(keys: readonly string[]): Promise<Record<string, T | null>>;
+    /**
+     * Store multiple items in the default cache store for a specific duration.
+     *
+     * @param values - An object mapping keys to the values to be stored.
+     * @param ttl - Expiration time in seconds or a specific Date.
+     * @returns A promise that resolves when all writes are complete.
+     * @throws {Error} If the underlying store driver encounters a write error.
+     *
+     * @example
+     * ```typescript
+     * await cache.putMany({ a: 1, b: 2 }, 60);
+     * ```
+     */
+    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    /**
+     * Get an item from the cache, allowing stale data while refreshing in background.
+     *
+     * Implements the Stale-While-Revalidate pattern to minimize latency for
+     * frequently accessed but expensive data.
+     *
+     * @param key - The unique cache key.
+     * @param ttlSeconds - How long the value is considered fresh.
+     * @param staleSeconds - How long to serve stale data while refreshing.
+     * @param callback - The closure to execute to refresh the data.
+     * @returns The cached (possibly stale) or freshly fetched value.
+     * @throws {Error} If the callback throws during an initial fetch.
+     *
+     * @example
+     * ```typescript
+     * const data = await cache.flexible('stats', 60, 30, () => fetchStats());
+     * ```
+     */
+    flexible<T = unknown>(key: string, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
+    /**
+     * Retrieve an item from the default cache store and then delete it.
+     *
+     * Useful for one-time notifications or temporary tokens.
+     *
+     * @param key - The unique cache key.
+     * @param defaultValue - Fallback value if the key is missing.
+     * @returns The cached value before deletion, or the default.
+     * @throws {Error} If the underlying store driver encounters a read or delete error.
+     *
+     * @example
+     * ```typescript
+     * const token = await cache.pull('temp_token');
+     * ```
+     */
+    pull<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
+    /**
+     * Remove an item from the default cache store.
+     *
+     * @param key - The unique cache key.
+     * @returns True if the item was removed, false otherwise.
+     * @throws {Error} If the underlying store driver encounters a delete error.
+     *
+     * @example
+     * ```typescript
+     * await cache.forget('user:1');
+     * ```
+     */
+    forget(key: string): Promise<boolean>;
+    /**
+     * Remove an item from the default cache store (alias for forget).
+     *
+     * @param key - The unique cache key.
+     * @returns True if the item was removed, false otherwise.
+     * @throws {Error} If the underlying store driver encounters a delete error.
+     *
+     * @example
+     * ```typescript
+     * await cache.delete('old_key');
+     * ```
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Remove all items from the default cache store.
+     *
+     * @returns A promise that resolves when the flush is complete.
+     * @throws {Error} If the underlying store driver encounters a flush error.
+     *
+     * @example
+     * ```typescript
+     * await cache.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear the entire default cache store (alias for flush).
+     *
+     * @returns A promise that resolves when the clear is complete.
+     * @throws {Error} If the underlying store driver encounters a clear error.
+     *
+     * @example
+     * ```typescript
+     * await cache.clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Increment the value of an integer item in the default cache store.
+     *
+     * @param key - Unique cache key.
+     * @param value - Amount to add.
+     * @returns New value after incrementing.
+     * @throws {Error} If existing value is not a number or the store is read-only.
+     *
+     * @example
+     * ```typescript
+     * const count = await cache.increment('page_views');
+     * ```
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement the value of an integer item in the default cache store.
+     *
+     * @param key - Unique cache key.
+     * @param value - Amount to subtract.
+     * @returns New value after decrementing.
+     * @throws {Error} If existing value is not a number or the store is read-only.
+     *
+     * @example
+     * ```typescript
+     * const remaining = await cache.decrement('stock:1');
+     * ```
+     */
+    decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Get a distributed lock instance from the default cache store.
+     *
+     * @param name - The unique name of the lock.
+     * @param seconds - The duration the lock should be held for.
+     * @returns A CacheLock instance.
+     * @throws {Error} If the underlying store does not support locking.
+     *
+     * @example
+     * ```typescript
+     * const lock = cache.lock('process_data', 10);
+     * if (await lock.get()) {
+     *   // ...
+     *   await lock.release();
+     * }
+     * ```
+     */
+    lock(name: string, seconds?: number): CacheLock | undefined;
+    /**
+     * Access a tagged cache section for grouped operations.
+     *
+     * Tags allow you to clear groups of cache entries simultaneously.
+     * Note: This is only supported by specific drivers like 'memory'.
+     *
+     * @param tags - An array of tag names.
+     * @returns A tagged cache repository instance.
+     * @throws {Error} If the underlying store driver does not support tags.
+     *
+     * @example
+     * ```typescript
+     * await cache.tags(['users', 'profiles']).put('user:1', data, 60);
+     * await cache.tags(['users']).flush(); // Clears all 'users' tagged entries
+     * ```
+     */
+    tags(tags: readonly string[]): CacheRepository;
+}
+
+/**
+ * Contract for a mechanism that predicts future cache key accesses.
+ *
+ * Implementations observe sequential access patterns to predict which keys
+ * are likely to be requested next, enabling prefetching strategies.
+ *
+ * @public
+ * @since 3.2.0
+ */
+interface AccessPredictor {
+    /**
+     * Record a cache key access to learn temporal patterns.
+     *
+     * @param key - Cache key currently being accessed.
+     */
+    record(key: string): void;
+    /**
+     * Predict potential future keys based on learned access history.
+     *
+     * @param key - Current cache key acting as the trigger for prediction.
+     * @returns Array of predicted keys, ordered by likelihood.
+     */
+    predict(key: string): string[];
+    /**
+     * Reset all learned transition probabilities and state.
+     */
+    reset(): void;
+}
+/**
+ * A simple Markov Chain predictor (Order-1).
+ *
+ * Records transitions (A -> B) between sequential accesses and predicts
+ * B when A is next encountered. This is particularly effective for
+ * predictable resource loading sequences.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const predictor = new MarkovPredictor();
+ * predictor.record('user:1');
+ * predictor.record('user:1:profile');
+ * const next = predictor.predict('user:1'); // ['user:1:profile']
+ * ```
+ */
+declare class MarkovPredictor implements AccessPredictor {
+    private transitions;
+    private lastKey;
+    private readonly maxNodes;
+    private readonly maxEdgesPerNode;
+    /**
+     * Initialize a new MarkovPredictor.
+     *
+     * @param options - Limits for internal transition graph to manage memory.
+     */
+    constructor(options?: {
+        maxNodes?: number;
+        maxEdgesPerNode?: number;
+    });
+    record(key: string): void;
+    predict(key: string): string[];
+    reset(): void;
+}
+
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Options for the CircuitBreakerStore.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const options: CircuitBreakerOptions = {
+ *   maxFailures: 3,
+ *   resetTimeout: 30000,
+ *   fallback: new MemoryStore()
+ * };
+ * ```
+ */
+type CircuitBreakerOptions = {
+    /**
+     * Number of consecutive failures before opening the circuit.
+     * @defaultValue 5
+     */
+    maxFailures?: number;
+    /**
+     * Time in milliseconds to stay in OPEN state before transitioning to HALF_OPEN.
+     * @defaultValue 60000
+     */
+    resetTimeout?: number;
+    /**
+     * Optional fallback store to use when the primary store is unavailable.
+     */
+    fallback?: CacheStore;
+};
+/**
+ * A protective wrapper for cache stores that prevents cascading failures
+ * through circuit-breaking logic.
+ *
+ * When the primary store encounters repeated failures, the circuit opens,
+ * temporarily bypassing the primary store and optionally using a fallback.
+ *
+ * @public
+ * @since 3.2.0
+ */
+declare class CircuitBreakerStore implements CacheStore {
+    private readonly primary;
+    private state;
+    private failures;
+    private lastErrorTime;
+    private options;
+    constructor(primary: CacheStore, options?: CircuitBreakerOptions);
+    private execute;
+    private onSuccess;
+    private onFailure;
+    private handleFallback;
+    get<T = unknown>(key: CacheKey): Promise<T | null>;
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    forget(key: CacheKey): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: CacheKey, value?: number): Promise<number>;
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    ttl(key: CacheKey): Promise<number | null>;
+    /**
+     * Returns current state for monitoring.
+     *
+     * @returns Current state of the circuit breaker.
+     *
+     * @example
+     * ```typescript
+     * const state = store.getState();
+     * if (state === 'OPEN') {
+     *   console.warn('Primary cache is unavailable');
+     * }
+     * ```
+     */
+    getState(): CircuitState;
+}
+
+/**
+ * Configuration options for the `FileStore` implementation.
+ *
+ * Defines how the file-based cache behaves, including storage location,
+ * cleanup policies, and filesystem organization.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: FileStoreOptions = {
+ *   directory: './cache',
+ *   enableCleanup: true,
+ *   maxFiles: 1000,
+ *   useSubdirectories: true
+ * };
+ * ```
+ */
+type FileStoreOptions = {
+    /**
+     * The absolute or relative path to the directory where cache files are stored.
+     * The directory will be created automatically if it does not exist.
+     */
+    directory: string;
+    /**
+     * Whether to enable the background cleanup daemon for removing expired entries.
+     *
+     * @default true
+     */
+    enableCleanup?: boolean;
+    /**
+     * The frequency in milliseconds at which the cleanup daemon scans for expired files.
+     *
+     * @default 60000
+     */
+    cleanupInterval?: number;
+    /**
+     * The maximum number of cache files allowed in the storage directory.
+     *
+     * When this limit is exceeded, the store performs LRU (Least Recently Used)
+     * eviction based on file modification times.
+     */
+    maxFiles?: number;
+    /**
+     * Whether to distribute cache files across nested subdirectories.
+     *
+     * Enabling this prevents performance degradation on filesystems with limits
+     * on the number of files per single directory by using a 2-level hash-based structure.
+     *
+     * @default false
+     */
+    useSubdirectories?: boolean;
+};
+/**
+ * A persistent filesystem-based implementation of the `CacheStore` interface.
+ *
+ * `FileStore` manages cache entries as individual JSON files on the local disk.
+ * It is designed for scenarios requiring data persistence across application
+ * restarts without the overhead of external database dependencies like Redis.
+ *
+ * Key features:
+ * - Atomic writes using temporary files and renames.
+ * - Background cleanup daemon for expired entries.
+ * - LRU eviction when `maxFiles` limit is reached.
+ * - Optional subdirectory nesting for high-volume storage.
+ * - File-based distributed locking mechanism.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const store = new FileStore({
+ *   directory: './storage/cache',
+ *   useSubdirectories: true
+ * });
+ *
+ * await store.put('user:1', { name: 'John' }, 3600);
+ * const user = await store.get('user:1');
+ * ```
+ */
+declare class FileStore implements CacheStore {
+    private options;
+    private cleanupTimer;
+    /**
+     * Initializes a new instance of the FileStore.
+     *
+     * @param options - Configuration settings for the store.
+     */
+    constructor(options: FileStoreOptions);
+    /**
+     * Starts the background process for periodic cache maintenance.
+     *
+     * @param interval - Time between cleanup cycles in milliseconds.
+     * @internal
+     */
+    private startCleanupDaemon;
+    /**
+     * Scans the cache directory to remove expired files and enforce capacity limits.
+     *
+     * This method performs a recursive scan of the storage directory. It deletes
+     * files that have passed their expiration time and, if `maxFiles` is configured,
+     * evicts the oldest files to stay within the limit.
+     *
+     * @returns The total number of files removed during this operation.
+     * @throws {Error} If the directory cannot be read or files cannot be deleted.
+     *
+     * @example
+     * ```typescript
+     * const removedCount = await store.cleanExpiredFiles();
+     * console.log(`Cleaned up ${removedCount} files.`);
+     * ```
+     */
+    cleanExpiredFiles(): Promise<number>;
+    /**
+     * Stops the cleanup daemon and releases associated resources.
+     *
+     * Should be called when the store is no longer needed to prevent memory leaks
+     * and allow the process to exit gracefully.
+     *
+     * @example
+     * ```typescript
+     * await store.destroy();
+     * ```
+     */
+    destroy(): Promise<void>;
+    /**
+     * Ensures that the base storage directory exists.
+     *
+     * @throws {Error} If the directory cannot be created due to permissions or path conflicts.
+     * @internal
+     */
+    private ensureDir;
+    /**
+     * Resolves the filesystem path for a given cache key.
+     *
+     * @param key - Normalized cache key.
+     * @returns Absolute path to the JSON file representing the key.
+     * @internal
+     */
+    private filePathForKey;
+    /**
+     * Retrieves an item from the cache by its key.
+     *
+     * If the item exists but has expired, it will be deleted and `null` will be returned.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @returns The cached value, or `null` if not found or expired.
+     * @throws {Error} If the file exists but cannot be read or parsed.
+     *
+     * @example
+     * ```typescript
+     * const value = await store.get<string>('my-key');
+     * ```
+     */
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Stores an item in the cache with a specified expiration time.
+     *
+     * Uses an atomic write strategy (write to temp file then rename) to ensure
+     * data integrity even if the process crashes during the write operation.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @param value - The data to be cached.
+     * @param ttl - Time-to-live in seconds or a Date object for absolute expiration.
+     * @throws {Error} If the file system is not writable or disk is full.
+     *
+     * @example
+     * ```typescript
+     * await store.put('settings', { theme: 'dark' }, 86400);
+     * ```
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Stores an item in the cache only if it does not already exist.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @param value - The data to be cached.
+     * @param ttl - Time-to-live in seconds or a Date object.
+     * @returns `true` if the item was stored, `false` if it already existed.
+     *
+     * @example
+     * ```typescript
+     * const success = await store.add('unique-task', { status: 'pending' }, 60);
+     * ```
+     */
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Removes an item from the cache by its key.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @returns `true` if the file was deleted or didn't exist, `false` on failure.
+     *
+     * @example
+     * ```typescript
+     * await store.forget('my-key');
+     * ```
+     */
+    forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Removes all items from the cache directory.
+     *
+     * This operation deletes the entire cache directory and recreates it.
+     * Use with caution as it is destructive and non-reversible.
+     *
+     * @throws {Error} If the directory cannot be removed or recreated.
+     *
+     * @example
+     * ```typescript
+     * await store.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Increments the value of an integer item in the cache.
+     *
+     * If the key does not exist, it is initialized to 0 before incrementing.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @param value - The amount to increment by.
+     * @returns The new value after incrementing.
+     * @throws {Error} If the existing value is not a number.
+     *
+     * @example
+     * ```typescript
+     * const newCount = await store.increment('page-views');
+     * ```
+     */
+    increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrements the value of an integer item in the cache.
+     *
+     * If the key does not exist, it is initialized to 0 before decrementing.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @param value - The amount to decrement by.
+     * @returns The new value after decrementing.
+     * @throws {Error} If the existing value is not a number.
+     *
+     * @example
+     * ```typescript
+     * const newCount = await store.decrement('stock-level');
+     * ```
+     */
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Retrieves the remaining time-to-live for a cache item in seconds.
+     *
+     * @param key - The unique identifier for the cache item.
+     * @returns The seconds remaining until expiration, or `null` if it never expires or doesn't exist.
+     *
+     * @example
+     * ```typescript
+     * const secondsLeft = await store.ttl('session:123');
+     * ```
+     */
+    ttl(key: CacheKey): Promise<number | null>;
+    /**
+     * Creates a distributed lock instance based on the filesystem.
+     *
+     * Locks are implemented using atomic file creation (`wx` flag). They include
+     * protection against stale locks by checking process IDs and expiration times.
+     *
+     * @param name - The unique name of the lock.
+     * @param seconds - The duration in seconds for which the lock should be held.
+     * @returns A `CacheLock` instance for managing the lock lifecycle.
+     *
+     * @example
+     * ```typescript
+     * const lock = store.lock('process-report', 60);
+     * if (await lock.acquire()) {
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
+    lock(name: string, seconds?: number): CacheLock;
+}
+
+/**
+ * Configuration options for the `MemoryStore`.
+ *
+ * Used to define the behavior of the in-memory cache, such as eviction policies.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: MemoryStoreOptions = { maxItems: 500 };
+ * ```
+ */
+type MemoryStoreOptions = {
+    /**
+     * Maximum number of items to keep in memory.
+     *
+     * When the limit is reached, the Least Recently Used (LRU) item is evicted.
+     * Set to 0 or undefined for unlimited capacity (not recommended for production).
+     */
+    maxItems?: number;
+};
+/**
+ * Performance and usage statistics for the `MemoryStore`.
+ *
+ * Provides insights into cache efficiency and capacity management.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const stats: MemoryCacheStats = {
+ *   hits: 100,
+ *   misses: 20,
+ *   hitRate: 0.83,
+ *   size: 500,
+ *   evictions: 5
+ * };
+ * ```
+ */
+type MemoryCacheStats = {
+    /** Total number of successful cache lookups. */
+    hits: number;
+    /** Total number of failed cache lookups (key not found or expired). */
+    misses: number;
+    /**
+     * The efficiency ratio of the cache.
+     *
+     * Calculated as hits / (hits + misses). Ranges from 0.0 to 1.0.
+     */
+    hitRate: number;
+    /** Current number of active items stored in the cache. */
+    size: number;
+    /** Total number of items removed to make room for new entries. */
+    evictions: number;
+};
+/**
+ * Fast, non-persistent in-memory cache implementation.
+ *
+ * `MemoryStore` provides a high-performance backend for the `CacheStore` interface.
+ * It supports TTL-based expiration, LRU eviction, basic tagging for bulk invalidation,
+ * and local mutex locking for atomic operations.
+ *
+ * @public
+ * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryStore({ maxItems: 1000 });
+ * await store.put('user:1', { name: 'Alice' }, 3600);
+ * const user = await store.get('user:1');
+ * ```
+ */
+declare class MemoryStore implements CacheStore, TaggableStore {
+    private entries;
+    private locks;
+    private stats;
+    private tagToKeys;
+    private keyToTags;
+    /**
+     * Creates a new MemoryStore instance.
+     *
+     * @param options - Configuration for capacity and eviction.
+     */
+    constructor(options?: MemoryStoreOptions);
+    /**
+     * Retrieves current performance metrics.
+     *
+     * @returns A snapshot of hits, misses, size, and eviction counts.
+     *
+     * @example
+     * ```typescript
+     * const stats = store.getStats();
+     * console.log(`Cache hit rate: ${stats.hitRate * 100}%`);
+     * ```
+     */
+    getStats(): MemoryCacheStats;
+    private cleanupExpired;
+    /**
+     * Retrieves an item from the cache by its key.
+     *
+     * If the item is expired, it will be automatically removed and `null` will be returned.
+     *
+     * @param key - The unique identifier for the cached item.
+     * @returns The cached value, or `null` if not found or expired.
+     *
+     * @example
+     * ```typescript
+     * const value = await store.get('my-key');
+     * ```
+     */
+    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Stores an item in the cache with a specific TTL.
+     *
+     * If the key already exists, it will be overwritten.
+     *
+     * @param key - The unique identifier for the item.
+     * @param value - The data to store.
+     * @param ttl - Time-to-live in seconds, or a Date object for absolute expiration.
+     *
+     * @example
+     * ```typescript
+     * await store.put('settings', { theme: 'dark' }, 3600);
+     * ```
+     */
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    /**
+     * Stores an item only if it does not already exist in the cache.
+     *
+     * @param key - The unique identifier for the item.
+     * @param value - The data to store.
+     * @param ttl - Time-to-live in seconds or absolute expiration.
+     * @returns `true` if the item was added, `false` if it already existed.
+     *
+     * @example
+     * ```typescript
+     * const added = await store.add('unique-task', data, 60);
+     * ```
+     */
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    /**
+     * Removes an item from the cache.
+     *
+     * @param key - The unique identifier for the item to remove.
+     * @returns `true` if the item existed and was removed, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * await store.forget('user:session');
+     * ```
+     */
+    forget(key: CacheKey): Promise<boolean>;
+    /**
+     * Removes all items from the cache and resets all internal indexes.
+     *
+     * @example
+     * ```typescript
+     * await store.flush();
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Increments the value of an item in the cache.
+     *
+     * If the key does not exist, it starts from 0.
+     *
+     * @param key - The identifier for the numeric value.
+     * @param value - The amount to increment by (defaults to 1).
+     * @returns The new incremented value.
+     *
+     * @example
+     * ```typescript
+     * const count = await store.increment('page_views');
+     * ```
+     */
+    increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrements the value of an item in the cache.
+     *
+     * @param key - The identifier for the numeric value.
+     * @param value - The amount to decrement by (defaults to 1).
+     * @returns The new decremented value.
+     *
+     * @example
+     * ```typescript
+     * const remaining = await store.decrement('stock_count', 5);
+     * ```
+     */
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Gets the remaining time-to-live for a cached item.
+     *
+     * @param key - The identifier for the cached item.
+     * @returns Remaining seconds, or `null` if the item has no expiration or does not exist.
+     *
+     * @example
+     * ```typescript
+     * const secondsLeft = await store.ttl('token');
+     * ```
+     */
+    ttl(key: CacheKey): Promise<number | null>;
+    /**
+     * Creates a lock instance for managing exclusive access to a resource.
+     *
+     * @param name - The name of the lock.
+     * @param seconds - The duration the lock should be held (defaults to 10).
+     * @returns A `CacheLock` instance.
+     *
+     * @example
+     * ```typescript
+     * const lock = store.lock('process-report', 30);
+     * if (await lock.acquire()) {
+     *   try {
+     *     // Critical section
+     *   } finally {
+     *     await lock.release();
+     *   }
+     * }
+     * ```
+     */
+    lock(name: string, seconds?: number): CacheLock;
+    /**
+     * Generates a tagged key for storage.
+     *
+     * Used internally to prefix keys with their associated tags.
+     *
+     * @param key - The original cache key.
+     * @param tags - List of tags to associate with the key.
+     * @returns A formatted string containing tags and the key.
+     */
+    tagKey(key: string, tags: readonly string[]): string;
+    /**
+     * Indexes a tagged key for bulk invalidation.
+     *
+     * @param tags - The tags to index.
+     * @param taggedKey - The full key (including tag prefix) to store.
+     */
+    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
+    /**
+     * Removes a key from the tag indexes.
+     *
+     * @param taggedKey - The key to remove from all tag sets.
+     */
+    tagIndexRemove(taggedKey: string): void;
+    /**
+     * Invalidates all cache entries associated with any of the given tags.
+     *
+     * @param tags - The tags to flush.
+     *
+     * @example
+     * ```typescript
+     * await store.flushTags(['users', 'profiles']);
+     * ```
+     */
+    flushTags(tags: readonly string[]): Promise<void>;
+}
+
+/**
+ * A "black-hole" cache implementation that discards all data.
+ *
+ * NullStore implements the `CacheStore` interface but performs no actual storage
+ * or retrieval operations. It is primarily used to disable caching globally
+ * without changing application logic, or as a mock in testing environments.
+ *
+ * @example
+ * ```typescript
+ * const store = new NullStore();
+ * await store.put('key', 'value', 60);
+ * const value = await store.get('key'); // always returns null
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class NullStore implements CacheStore {
+    /**
+     * Simulates a cache miss for any given key.
+     *
+     * @param _key - Identifier for the cached item.
+     * @returns Always `null` regardless of requested key.
+     *
+     * @example
+     * ```typescript
+     * const value = await store.get('my-key');
+     * ```
      */
-    missing(key: string): Promise<boolean>;
+    get<T = unknown>(_key: CacheKey): Promise<CacheValue<T>>;
     /**
-     * Store an item in the cache.
+     * Discards the provided value instead of storing it.
      *
-     * @param key - The unique cache key.
-     * @param value - The value to store.
-     * @param ttl - Time to live in seconds (or Date).
+     * @param _key - The identifier for the item.
+     * @param _value - The data to be cached.
+     * @param _ttl - Time-to-live in seconds.
+     * @returns Resolves immediately after discarding the data.
      *
      * @example
      * ```typescript
-     * await cache.put('key', 'value', 60); // 60 seconds
+     * await store.put('user:1', { id: 1 }, 3600);
      * ```
      */
-    put(key: string, value: unknown, ttl: CacheTtl): Promise<void>;
-    /**
-     * Store an item in the cache (alias for put with optional TTL).
-     */
-    set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
+    put(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<void>;
     /**
-     * Store an item in the cache if it doesn't already exist.
+     * Simulates a failed attempt to add an item to the cache.
      *
-     * @returns True if added, false if it already existed.
-     */
-    add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
-    /**
-     * Store an item in the cache indefinitely.
-     */
-    forever(key: string, value: unknown): Promise<void>;
-    /**
-     * Get an item from the cache, or execute the callback and store the result.
+     * Since NullStore does not store data, this method always indicates that
+     * the item was not added.
      *
-     * @param key - The cache key.
-     * @param ttl - Time to live if the item is missing.
-     * @param callback - Closure to execute on miss.
-     * @returns The cached or fetched value.
+     * @param _key - The identifier for the item.
+     * @param _value - The data to be cached.
+     * @param _ttl - Time-to-live in seconds.
+     * @returns Always returns `false`.
      *
      * @example
      * ```typescript
-     * const user = await cache.remember('user:1', 60, async () => {
-     *   return await db.findUser(1);
-     * });
+     * const added = await store.add('key', 'value', 60); // false
      * ```
      */
-    remember<T = unknown>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
-    /**
-     * Get an item from the cache, or execute the callback and store the result forever.
-     */
-    rememberForever<T = unknown>(key: string, callback: () => Promise<T> | T): Promise<T>;
-    /**
-     * Retrieve multiple items from the cache.
-     */
-    many<T = unknown>(keys: readonly string[]): Promise<Record<string, T | null>>;
-    /**
-     * Store multiple items in the cache.
-     */
-    putMany(values: Record<string, unknown>, ttl: CacheTtl): Promise<void>;
+    add(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<boolean>;
     /**
-     * Get an item from the cache, allowing stale data while refreshing in background.
+     * Simulates a failed attempt to remove an item from the cache.
      *
-     * @param key - Cache key.
-     * @param ttlSeconds - How long the value is considered fresh.
-     * @param staleSeconds - How long to serve stale data while refreshing.
-     * @param callback - Closure to refresh the data.
-     */
-    flexible<T = unknown>(key: string, ttlSeconds: number, staleSeconds: number, callback: () => Promise<T> | T): Promise<T>;
-    /**
-     * Retrieve an item from the cache and delete it.
-     */
-    pull<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
-    /**
-     * Remove an item from the cache.
-     */
-    forget(key: string): Promise<boolean>;
-    /**
-     * Remove an item from the cache (alias for forget).
+     * Since no data is ever stored, there is nothing to remove.
+     *
+     * @param _key - The identifier for the item to remove.
+     * @returns Always returns `false`.
+     *
+     * @example
+     * ```typescript
+     * const forgotten = await store.forget('key'); // false
+     * ```
      */
-    delete(key: string): Promise<boolean>;
+    forget(_key: CacheKey): Promise<boolean>;
     /**
-     * Remove all items from the cache.
+     * Performs a no-op flush operation.
+     *
+     * @returns Resolves immediately as there is no data to clear.
+     *
+     * @example
+     * ```typescript
+     * await store.flush();
+     * ```
      */
     flush(): Promise<void>;
     /**
-     * Clear the entire cache (alias for flush).
-     */
-    clear(): Promise<void>;
-    /**
-     * Increment an integer item in the cache.
-     */
-    increment(key: string, value?: number): Promise<number>;
-    /**
-     * Decrement an integer item in the cache.
-     */
-    decrement(key: string, value?: number): Promise<number>;
-    /**
-     * Get a lock instance.
+     * Simulates an increment operation on a non-existent key.
+     *
+     * @param _key - The identifier for the numeric item.
+     * @param _value - The amount to increment by.
+     * @returns Always returns `0`.
      *
-     * @param name - Lock name.
-     * @param seconds - Lock duration.
-     * @returns CacheLock instance.
+     * @example
+     * ```typescript
+     * const newValue = await store.increment('counter', 1); // 0
+     * ```
      */
-    lock(name: string, seconds?: number): CacheLock | undefined;
+    increment(_key: CacheKey, _value?: number): Promise<number>;
     /**
-     * Access a tagged cache section (only supported by some stores).
+     * Simulates a decrement operation on a non-existent key.
+     *
+     * @param _key - The identifier for the numeric item.
+     * @param _value - The amount to decrement by.
+     * @returns Always returns `0`.
+     *
+     * @example
+     * ```typescript
+     * const newValue = await store.decrement('counter', 1); // 0
+     * ```
      */
-    tags(tags: readonly string[]): CacheRepository;
+    decrement(_key: CacheKey, _value?: number): Promise<number>;
 }
 
 /**
- * Options for configuring the `FileStore`.
- *
- * @public
- * @since 3.0.0
- */
-type FileStoreOptions = {
-    /** The directory where cache files will be stored. */
-    directory: string;
-};
-/**
- * FileStore implements the `CacheStore` interface using the local file system.
+ * A CacheStore wrapper that predicts usage patterns and prefetches data.
  *
- * It stores cache entries as individual JSON files in the specified directory.
- * While not as fast as memory or Redis, it provides persistent caching across
- * application restarts without external dependencies.
+ * This store observes access patterns (A -> B) and when A is requested,
+ * automatically attempts to 'touch' B in the underlying store.
  *
- * @public
- * @since 3.0.0
- */
-declare class FileStore implements CacheStore {
-    private options;
-    constructor(options: FileStoreOptions);
-    private ensureDir;
-    private filePathForKey;
-    get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
-    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
-    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
-    forget(key: CacheKey): Promise<boolean>;
-    flush(): Promise<void>;
-    increment(key: CacheKey, value?: number): Promise<number>;
-    decrement(key: CacheKey, value?: number): Promise<number>;
-    lock(name: string, seconds?: number): CacheLock;
-}
-
-/**
- * Options for configuring the `MemoryStore`.
+ * If the underlying store is a TieredStore, this effectively promotes B
+ * from the remote core (e.g. Redis) to the local cache (e.g. Memory)
+ * before it is explicitly requested, reducing latency.
  *
  * @public
- * @since 3.0.0
- */
-type MemoryStoreOptions = {
-    /** Maximum number of items to keep in memory. Uses LRU eviction. */
-    maxItems?: number;
-};
-/**
- * MemoryStore implements the `CacheStore` interface using a Map.
- *
- * It provides a fast, non-persistent cache backend with support for
- * TTL expiration, basic tagging, and local locking.
+ * @since 3.2.0
  *
- * @public
- * @since 3.0.0
+ * @example
+ * ```typescript
+ * const store = new PredictiveStore(new TieredStore(l1, l2));
+ * // Accessing 'a' will prefetch 'b' if a -> b pattern is detected
+ * await store.get('a');
+ * ```
  */
-declare class MemoryStore implements CacheStore, TaggableStore {
-    private options;
-    private entries;
-    private locks;
-    private tagToKeys;
-    private keyToTags;
-    constructor(options?: MemoryStoreOptions);
-    private touchLRU;
-    private pruneIfNeeded;
-    private cleanupExpired;
+declare class PredictiveStore implements CacheStore {
+    private store;
+    private predictor;
+    constructor(store: CacheStore, options?: {
+        predictor?: AccessPredictor;
+    });
     get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
     put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
     add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
@@ -660,31 +2541,8 @@ declare class MemoryStore implements CacheStore, TaggableStore {
     flush(): Promise<void>;
     increment(key: CacheKey, value?: number): Promise<number>;
     decrement(key: CacheKey, value?: number): Promise<number>;
-    lock(name: string, seconds?: number): CacheLock;
-    tagKey(key: string, tags: readonly string[]): string;
-    tagIndexAdd(tags: readonly string[], taggedKey: string): void;
-    tagIndexRemove(taggedKey: string): void;
-    flushTags(tags: readonly string[]): Promise<void>;
-}
-
-/**
- * NullStore is a black-hole cache implementation.
- *
- * It implements the `CacheStore` interface but does not actually store or
- * retrieve any data. This is useful for disabling caching entirely or for
- * testing.
- *
- * @public
- * @since 3.0.0
- */
-declare class NullStore implements CacheStore {
-    get<T = unknown>(_key: CacheKey): Promise<CacheValue<T>>;
-    put(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<void>;
-    add(_key: CacheKey, _value: unknown, _ttl: CacheTtl): Promise<boolean>;
-    forget(_key: CacheKey): Promise<boolean>;
-    flush(): Promise<void>;
-    increment(_key: CacheKey, _value?: number): Promise<number>;
-    decrement(_key: CacheKey, _value?: number): Promise<number>;
+    lock(name: string, seconds?: number): CacheLock | undefined;
+    ttl(key: CacheKey): Promise<number | null>;
 }
 
 /**
@@ -692,6 +2550,14 @@ declare class NullStore implements CacheStore {
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: RedisStoreOptions = {
+ *   connection: 'primary',
+ *   prefix: 'cache:'
+ * };
+ * ```
  */
 type RedisStoreOptions = {
     /** The name of the Redis connection to use. */
@@ -710,22 +2576,92 @@ type RedisStoreOptions = {
  */
 declare class RedisStore implements CacheStore, TaggableStore {
     private connectionName?;
+    /**
+     * Initialize a new RedisStore instance.
+     *
+     * @param options - Redis connection and prefix settings.
+     *
+     * @example
+     * ```typescript
+     * const store = new RedisStore({ prefix: 'app:' });
+     * ```
+     */
     constructor(options?: RedisStoreOptions);
     private get client();
+    /**
+     * Retrieve an item from Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @returns Parsed JSON value or null if missing/expired.
+     * @throws {Error} If Redis connection fails or read errors occur.
+     */
     get<T = unknown>(key: CacheKey): Promise<CacheValue<T>>;
+    /**
+     * Store an item in Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @param value - Value to serialize and store.
+     * @param ttl - Expiration duration.
+     * @throws {Error} If Redis connection fails or write errors occur.
+     */
     put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
     add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
     forget(key: CacheKey): Promise<boolean>;
     flush(): Promise<void>;
     increment(key: CacheKey, value?: number): Promise<number>;
+    /**
+     * Decrement a numeric value in Redis.
+     *
+     * @param key - Unique cache key identifier.
+     * @param value - Amount to subtract.
+     * @returns Updated numeric value.
+     * @throws {Error} If key is not numeric or Redis errors occur.
+     */
     decrement(key: CacheKey, value?: number): Promise<number>;
     tagKey(key: string, _tags: readonly string[]): string;
     tagIndexAdd(tags: readonly string[], taggedKey: string): Promise<void>;
-    tagIndexRemove(_taggedKey: string): Promise<void>;
+    tagIndexRemove(taggedKey: string): Promise<void>;
     flushTags(tags: readonly string[]): Promise<void>;
+    ttl(key: CacheKey): Promise<number | null>;
     lock(name: string, seconds?: number): CacheLock;
 }
 
+/**
+ * A multi-level cache store that coordinates access between a fast local L1 cache
+ * and a persistent remote L2 cache.
+ *
+ * It implements the read-through and write-through patterns to ensure that the
+ * most frequently accessed data remains in the fastest storage tier.
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * const store = new TieredStore(new MemoryStore(), new RedisStore());
+ * await store.put('key', 'value', 3600);
+ * ```
+ */
+declare class TieredStore implements CacheStore {
+    private readonly local;
+    private readonly remote;
+    /**
+     * Initializes a new TieredStore.
+     *
+     * @param local - The L1 cache store (usually MemoryStore).
+     * @param remote - The L2 cache store (usually RedisStore or FileStore).
+     */
+    constructor(local: CacheStore, remote: CacheStore);
+    get<T = unknown>(key: CacheKey): Promise<T | null>;
+    put(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<void>;
+    add(key: CacheKey, value: unknown, ttl: CacheTtl): Promise<boolean>;
+    forget(key: CacheKey): Promise<boolean>;
+    flush(): Promise<void>;
+    increment(key: CacheKey, value?: number): Promise<number>;
+    decrement(key: CacheKey, value?: number): Promise<number>;
+    ttl(key: CacheKey): Promise<number | null>;
+}
+
 /**
  * Interface for a low-level cache storage provider.
  *
@@ -733,6 +2669,16 @@ declare class RedisStore implements CacheStore, TaggableStore {
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * class MyProvider implements CacheStorageProvider {
+ *   async get(key) { ... }
+ *   async set(key, value, ttl) { ... }
+ *   async delete(key) { ... }
+ *   async clear() { ... }
+ * }
+ * ```
  */
 interface CacheStorageProvider {
     /**
@@ -774,70 +2720,107 @@ type CacheProvider = CacheStorageProvider;
  */
 interface CacheService {
     /**
-     * Retrieve an item from the cache.
+     * Retrieves an item from the cache.
      *
-     * @param key - The unique cache key.
-     * @returns The cached value, or null if not found or expired.
+     * @param key - The unique identifier for the cached item.
+     * @returns The cached value, or `null` if the item is missing or has expired.
+     *
+     * @example
+     * const user = await cache.get<User>('user:123');
      */
     get<T = unknown>(key: string): Promise<T | null>;
     /**
-     * Store an item in the cache with an optional TTL.
+     * Stores an item in the cache with an optional time-to-live.
      *
-     * @param key - The unique cache key.
-     * @param value - The value to store.
-     * @param ttl - Time-to-live in seconds or an absolute Date.
+     * @param key - The unique identifier for the item.
+     * @param value - The value to store (must be serializable).
+     * @param ttl - Time-to-live in seconds or as a `Date` object. If omitted, uses the default TTL.
+     *
+     * @example
+     * await cache.set('key', 'value', 60);
      */
     set(key: string, value: unknown, ttl?: CacheTtl): Promise<void>;
     /**
-     * Determine if an item exists in the cache and is not expired.
+     * Checks if an item exists in the cache and has not expired.
      *
      * @param key - The cache key to check.
-     * @returns True if the item exists and is valid.
+     * @returns `true` if the item exists and is valid, `false` otherwise.
+     *
+     * @example
+     * if (await cache.has('lock:processing')) {
+     *   return;
+     * }
      */
     has(key: string): Promise<boolean>;
     /**
-     * Store an item in the cache only if it doesn't already exist.
+     * Stores an item in the cache only if it does not already exist.
      *
-     * @param key - The unique cache key.
+     * @param key - The unique identifier for the item.
      * @param value - The value to store.
-     * @param ttl - Time-to-live.
-     * @returns True if the item was added, false otherwise.
+     * @param ttl - Time-to-live in seconds or as a `Date` object.
+     * @returns `true` if the item was added, `false` if it already existed.
+     *
+     * @example
+     * const acquired = await cache.add('lock:job:1', true, 60);
      */
     add(key: string, value: unknown, ttl?: CacheTtl): Promise<boolean>;
     /**
-     * Remove an item from the cache.
+     * Removes an item from the cache.
      *
      * @param key - The cache key to remove.
-     * @returns True if the item existed and was removed.
+     * @returns `true` if the item was successfully removed, `false` otherwise.
+     *
+     * @example
+     * await cache.delete('user:session:1');
      */
     delete(key: string): Promise<boolean>;
     /**
-     * Retrieve an item from the cache and then delete it.
+     * Retrieves an item from the cache and then removes it.
      *
-     * @param key - The cache key.
-     * @param defaultValue - Optional value to return if not found.
-     * @returns The cached value or the default.
+     * This operation is atomic depending on the underlying driver support.
+     *
+     * @param key - The cache key to pull.
+     * @param defaultValue - Optional value to return if the item is missing.
+     * @returns The cached value (before deletion) or the default value.
+     *
+     * @example
+     * const otp = await cache.pull('otp:user:1');
      */
     pull<T = unknown>(key: string, defaultValue?: T): Promise<T | null>;
     /**
-     * Get an item from the cache, or execute the given callback and store the result.
+     * Retrieves an item from the cache, or executes the callback and stores the result.
+     *
+     * This is a "read-through" cache pattern.
      *
      * @param key - The cache key.
-     * @param ttl - Time-to-live if the item needs to be fetched.
-     * @param callback - Closure to execute if the item is missing.
-     * @returns The cached or fetched value.
+     * @param ttl - Time-to-live to use if the item is fetched from the callback.
+     * @param callback - Function to retrieve the value if missing. Can be async.
+     * @returns The cached or newly fetched value.
+     *
+     * @example
+     * const user = await cache.remember('user:1', 300, async () => {
+     *   return await db.findUser(1);
+     * });
      */
     remember<T>(key: string, ttl: CacheTtl, callback: () => Promise<T> | T): Promise<T>;
     /**
-     * Store an item in the cache indefinitely.
+     * Stores an item in the cache indefinitely (or until manually removed).
      *
      * @param key - The unique cache key.
-     * @param callback - Closure to execute if the item is missing.
+     * @param callback - Function to retrieve the value if missing.
      * @returns The cached or fetched value.
+     *
+     * @example
+     * const settings = await cache.rememberForever('app:settings', () => loadSettings());
      */
     rememberForever<T>(key: string, callback: () => Promise<T> | T): Promise<T>;
     /**
-     * Clear the entire cache.
+     * Clears all items from the cache.
+     *
+     * @warning This will wipe the entire cache storage for the current context.
+     *
+     * @example
+     * await cache.clear();
      */
     clear(): Promise<void>;
 }
@@ -890,27 +2873,57 @@ type OrbitCacheStoreConfig =
  | {
     driver: 'provider';
     provider: CacheStorageProvider;
+}
+/** Multi-level cache. */
+ | {
+    driver: 'tiered';
+    local: string;
+    remote: string;
+}
+/** Predictive cache that prefetches keys based on usage patterns. */
+ | {
+    driver: 'predictive';
+    inner: string;
+    maxNodes?: number;
+}
+/** Fault tolerance layer. */
+ | {
+    driver: 'circuit-breaker';
+    primary: string;
+    maxFailures?: number;
+    resetTimeout?: number;
+    fallback?: string;
 };
 /**
  * Options for configuring the `OrbitStasis` cache orbit.
  *
  * @public
  * @since 3.0.0
+ *
+ * @example
+ * ```typescript
+ * const options: OrbitCacheOptions = {
+ *   default: 'redis',
+ *   stores: {
+ *     redis: { driver: 'redis', connection: 'default' }
+ *   }
+ * };
+ * ```
  */
 interface OrbitCacheOptions {
-    /** The key used to expose the cache manager in the request context. @default 'cache' */
+    /** The key used to expose the cache manager in the request context. @defaultValue 'cache' */
     exposeAs?: string;
-    /** The name of the default store to use for proxy methods. @default 'memory' */
+    /** The name of the default store to use for proxy methods. @defaultValue 'memory' */
     default?: string;
     /** Global prefix for all cache keys across all stores. */
     prefix?: string;
-    /** Default time-to-live for cache entries if not specified. @default 60 */
+    /** Default time-to-live for cache entries if not specified. @defaultValue 60 */
     defaultTtl?: CacheTtl;
     /** Map of named cache stores and their configurations. */
     stores?: Record<string, OrbitCacheStoreConfig>;
     /** How to handle cache events (hit/miss/etc) */
     eventsMode?: CacheEventMode;
-    /** Whether to throw if an event listener fails. @default false */
+    /** Whether to throw if an event listener fails. @defaultValue false */
     throwOnEventError?: boolean;
     /** Custom error handler for cache events. */
     onEventError?: (error: unknown, event: keyof CacheEvents, payload: {
@@ -951,6 +2964,18 @@ declare class OrbitStasis implements GravitoOrbit {
     install(core: PlanetCore): void;
     getCache(): CacheManager;
 }
+/**
+ * Helper function to create and install the OrbitStasis orbit.
+ *
+ * @param core - Gravito PlanetCore instance.
+ * @param options - Cache configuration options.
+ * @returns Initialized CacheManager.
+ *
+ * @example
+ * ```typescript
+ * const cache = orbitCache(core, { default: 'memory' });
+ * ```
+ */
 declare function orbitCache(core: PlanetCore, options?: OrbitCacheOptions): CacheManager;
 /** @deprecated Use OrbitStasis instead */
 declare const OrbitCache: typeof OrbitStasis;
@@ -961,4 +2986,4 @@ declare module '@gravito/core' {
     }
 }
 
-export { type CacheConfig, type CacheEventMode, type CacheEvents, type CacheKey, type CacheLock, CacheManager, type CacheProvider, CacheRepository, type CacheRepositoryOptions, type CacheService, type CacheStorageProvider, type CacheStore, type CacheTtl, type CacheValue, FileStore, type FileStoreOptions, LockTimeoutError, MemoryCacheProvider, MemoryStore, type MemoryStoreOptions, NullStore, OrbitCache, type OrbitCacheOptions, type OrbitCacheStoreConfig, OrbitStasis, RateLimiter, type RateLimiterResponse, RedisStore, type RedisStoreOptions, type StoreConfig, type TaggableStore, orbitCache as default, isExpired, isTaggableStore, normalizeCacheKey, sleep, ttlToExpiresAt };
+export { type AccessPredictor, type BlockOptions, type CacheConfig, type CacheEventMode, type CacheEvents, type CacheKey, type CacheLock, CacheManager, type CacheProvider, CacheRepository, type CacheRepositoryOptions, type CacheService, type CacheStorageProvider, type CacheStore, type CacheTtl, type CacheValue, type CircuitBreakerOptions, CircuitBreakerStore, type CircuitState, type CompressionOptions, FileStore, type FileStoreOptions, type FlexibleStats, LockTimeoutError, MarkovPredictor, MemoryCacheProvider, type MemoryCacheStats, MemoryStore, type MemoryStoreOptions, NullStore, OrbitCache, type OrbitCacheOptions, type OrbitCacheStoreConfig, OrbitStasis, PredictiveStore, type RateLimitInfo, RateLimiter, type RateLimiterResponse, RedisStore, type RedisStoreOptions, type StoreConfig, type TaggableStore, TieredStore, orbitCache as default, isExpired, isTaggableStore, normalizeCacheKey, sleep, ttlToExpiresAt };