@gravito/stasis 3.0.1 → 3.1.1

package/dist/index.js

@@ -1,3 +1,11 @@
+// src/locks.ts
+var LockTimeoutError = class extends Error {
+  name = "LockTimeoutError";
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/store.ts
 function isTaggableStore(store) {
   return typeof store.flushTags === "function" && typeof store.tagKey === "function" && typeof store.tagIndexAdd === "function" && typeof store.tagIndexRemove === "function";
@@ -35,7 +43,7 @@ function isExpired(expiresAt, now = Date.now()) {
   if (expiresAt === void 0) {
     return false;
   }
-  return now > expiresAt;
+  return now >= expiresAt;
 }
 
 // src/CacheRepository.ts
@@ -44,6 +52,29 @@ var CacheRepository = class _CacheRepository {
     this.store = store;
     this.options = options;
   }
+  refreshSemaphore = /* @__PURE__ */ new Map();
+  coalesceSemaphore = /* @__PURE__ */ new Map();
+  flexibleStats = { refreshCount: 0, refreshFailures: 0, totalTime: 0 };
+  /**
+   * 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() {
+    return {
+      refreshCount: this.flexibleStats.refreshCount,
+      refreshFailures: this.flexibleStats.refreshFailures,
+      avgRefreshTime: this.flexibleStats.refreshCount > 0 ? this.flexibleStats.totalTime / this.flexibleStats.refreshCount : 0
+    };
+  }
   emit(event, payload = {}) {
     const mode = this.options.eventsMode ?? "async";
     if (mode === "off") {
@@ -107,15 +138,32 @@ var CacheRepository = class _CacheRepository {
   async forgetMetaKey(metaKey) {
     await this.store.forget(metaKey);
   }
+  /**
+   * 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());
+   * ```
+   */
   async get(key, defaultValue) {
     const fullKey = this.key(key);
-    const value = await this.store.get(fullKey);
-    if (value !== null) {
+    const raw = await this.store.get(fullKey);
+    if (raw !== null) {
       const e2 = this.emit("hit", { key: fullKey });
       if (e2) {
         await e2;
       }
-      return value;
+      return this.decompress(raw);
     }
     const e = this.emit("miss", { key: fullKey });
     if (e) {
@@ -129,24 +177,103 @@ var CacheRepository = class _CacheRepository {
     }
     return defaultValue;
   }
+  /**
+   * Determine if an item exists in the cache.
+   *
+   * Checks for the presence of a key without necessarily returning its value.
+   *
+   * @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')) {
+   *   // ...
+   * }
+   * ```
+   */
   async has(key) {
     return await this.get(key) !== null;
   }
+  /**
+   * 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();
+   * }
+   * ```
+   */
   async missing(key) {
     return !await this.has(key);
   }
+  /**
+   * 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);
+   * ```
+   */
   async put(key, value, ttl) {
     const fullKey = this.key(key);
-    await this.store.put(fullKey, value, ttl);
+    const data = await this.compress(value);
+    await this.store.put(fullKey, data, ttl);
     const e = this.emit("write", { key: fullKey });
     if (e) {
       await e;
     }
   }
+  /**
+   * 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');
+   * ```
+   */
   async set(key, value, ttl) {
     const resolved = ttl ?? this.options.defaultTtl;
     await this.put(key, value, resolved);
   }
+  /**
+   * 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);
+   * ```
+   */
   async add(key, value, ttl) {
     const fullKey = this.key(key);
     const resolved = ttl ?? this.options.defaultTtl;
@@ -159,21 +286,93 @@ var CacheRepository = class _CacheRepository {
     }
     return ok;
   }
+  /**
+   * 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');
+   * ```
+   */
   async forever(key, value) {
     await this.put(key, value, null);
   }
+  /**
+   * 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());
+   * ```
+   */
   async remember(key, ttl, callback) {
-    const existing = await this.get(key);
-    if (existing !== null) {
-      return existing;
+    const fullKey = this.key(key);
+    if (this.coalesceSemaphore.has(fullKey)) {
+      return this.coalesceSemaphore.get(fullKey);
     }
-    const value = await callback();
-    await this.put(key, value, ttl);
-    return value;
+    const promise = (async () => {
+      try {
+        const existing = await this.get(key);
+        if (existing !== null) {
+          return existing;
+        }
+        const value = await callback();
+        await this.put(key, value, ttl);
+        return value;
+      } finally {
+        this.coalesceSemaphore.delete(fullKey);
+      }
+    })();
+    this.coalesceSemaphore.set(fullKey, promise);
+    return promise;
   }
+  /**
+   * 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());
+   * ```
+   */
   async rememberForever(key, callback) {
     return this.remember(key, null, callback);
   }
+  /**
+   * 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']);
+   * ```
+   */
   async many(keys) {
     const out = {};
     for (const key of keys) {
@@ -181,14 +380,40 @@ var CacheRepository = class _CacheRepository {
     }
     return out;
   }
+  /**
+   * 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);
+   * ```
+   */
   async putMany(values, ttl) {
     await Promise.all(Object.entries(values).map(([k, v]) => this.put(k, v, ttl)));
   }
   /**
    * Laravel-like flexible cache (stale-while-revalidate).
    *
-   * - `ttlSeconds`: how long the value is considered fresh
-   * - `staleSeconds`: how long the stale value may be served while a refresh happens
+   * 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());
+   * ```
    */
   async flexible(key, ttlSeconds, staleSeconds, callback) {
     const fullKey = this.key(key);
@@ -223,17 +448,23 @@ var CacheRepository = class _CacheRepository {
     }
     const value = await callback();
     const totalTtl = ttlSeconds + staleSeconds;
-    await this.store.put(fullKey, value, totalTtl);
+    await this.put(fullKey, value, totalTtl);
     await this.putMetaKey(metaKey, now + ttlMillis, totalTtl);
-    {
-      const e2 = this.emit("write", { key: fullKey });
-      if (e2) {
-        await e2;
-      }
-    }
     return value;
   }
   async refreshFlexible(fullKey, metaKey, ttlSeconds, staleSeconds, callback) {
+    if (this.refreshSemaphore.has(fullKey)) {
+      return;
+    }
+    const refreshPromise = this.doRefresh(fullKey, metaKey, ttlSeconds, staleSeconds, callback);
+    this.refreshSemaphore.set(fullKey, refreshPromise);
+    try {
+      await refreshPromise;
+    } finally {
+      this.refreshSemaphore.delete(fullKey);
+    }
+  }
+  async doRefresh(fullKey, metaKey, ttlSeconds, staleSeconds, callback) {
     if (!this.store.lock) {
       return;
     }
@@ -241,25 +472,79 @@ var CacheRepository = class _CacheRepository {
     if (!lock || !await lock.acquire()) {
       return;
     }
+    const startTime = Date.now();
     try {
-      const value = await callback();
+      const timeoutMillis = this.options.refreshTimeout ?? 3e4;
+      const maxRetries = this.options.maxRetries ?? 0;
+      const retryDelay = this.options.retryDelay ?? 50;
+      let lastError;
+      let value;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          value = await Promise.race([
+            Promise.resolve(callback()),
+            new Promise(
+              (_, reject) => setTimeout(() => reject(new Error("Refresh timeout")), timeoutMillis)
+            )
+          ]);
+          break;
+        } catch (err) {
+          lastError = err;
+          if (attempt < maxRetries) {
+            await sleep(retryDelay);
+          }
+        }
+      }
+      if (value === void 0 && lastError) {
+        throw lastError;
+      }
       const totalTtl = ttlSeconds + staleSeconds;
       const now = Date.now();
-      await this.store.put(fullKey, value, totalTtl);
+      await this.put(fullKey, value, totalTtl);
       await this.putMetaKey(metaKey, now + Math.max(0, ttlSeconds) * 1e3, totalTtl);
-      const e = this.emit("write", { key: fullKey });
-      if (e) {
-        await e;
-      }
+      this.flexibleStats.refreshCount++;
+      this.flexibleStats.totalTime += Date.now() - startTime;
+    } catch {
+      this.flexibleStats.refreshFailures++;
     } finally {
       await lock.release();
     }
   }
+  /**
+   * 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');
+   * ```
+   */
   async pull(key, defaultValue) {
     const value = await this.get(key, defaultValue);
     await this.forget(key);
     return value;
   }
+  /**
+   * 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');
+   * ```
+   */
   async forget(key) {
     const fullKey = this.key(key);
     const metaKey = this.flexibleFreshUntilKey(fullKey);
@@ -273,9 +558,36 @@ var CacheRepository = class _CacheRepository {
     }
     return ok;
   }
+  /**
+   * 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');
+   * ```
+   */
   async delete(key) {
     return this.forget(key);
   }
+  /**
+   * 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();
+   * ```
+   */
   async flush() {
     await this.store.flush();
     const e = this.emit("flush");
@@ -283,18 +595,99 @@ var CacheRepository = class _CacheRepository {
       await e;
     }
   }
+  /**
+   * 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();
+   * ```
+   */
   async clear() {
     return this.flush();
   }
+  /**
+   * 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, value) {
     return this.store.increment(this.key(key), value);
   }
+  /**
+   * 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, value) {
     return this.store.decrement(this.key(key), value);
   }
+  /**
+   * 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, seconds) {
     return this.store.lock ? this.store.lock(this.key(name), seconds) : void 0;
   }
+  /**
+   * 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) {
     if (!isTaggableStore(this.store)) {
       throw new Error("This cache store does not support tags.");
@@ -302,11 +695,56 @@ var CacheRepository = class _CacheRepository {
     return new _CacheRepository(new TaggedStore(this.store, tags), this.options);
   }
   /**
-   * 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() {
     return this.store;
   }
+  /**
+   * Compress a value before storage if compression is enabled and thresholds are met.
+   */
+  async compress(value) {
+    const opts = this.options.compression;
+    if (!opts?.enabled || value === null || value === void 0) {
+      return value;
+    }
+    const json = JSON.stringify(value);
+    if (json.length < (opts.minSize ?? 1024)) {
+      return value;
+    }
+    const { gzipSync } = await import("zlib");
+    const compressed = gzipSync(Buffer.from(json), { level: opts.level ?? 6 });
+    return {
+      __gravito_compressed: true,
+      data: compressed.toString("base64")
+    };
+  }
+  /**
+   * Decompress a value after retrieval if it was previously compressed.
+   */
+  async decompress(value) {
+    if (value !== null && typeof value === "object" && "__gravito_compressed" in value && value.__gravito_compressed === true) {
+      const { gunzipSync } = await import("zlib");
+      const buffer = Buffer.from(value.data, "base64");
+      const decompressed = gunzipSync(buffer).toString();
+      try {
+        return JSON.parse(decompressed);
+      } catch {
+        return decompressed;
+      }
+    }
+    return value;
+  }
 };
 var TaggedStore = class {
   constructor(store, tags) {
@@ -357,14 +795,39 @@ var TaggedStore = class {
 
 // src/RateLimiter.ts
 var RateLimiter = class {
-  constructor(store) {
-    this.store = 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) {
+    this.store = store;
   }
   /**
-   * 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
+   * }
+   * ```
    */
   async attempt(key, maxAttempts, decaySeconds) {
     const current = await this.store.get(key);
@@ -378,11 +841,12 @@ var RateLimiter = class {
       };
     }
     if (current >= maxAttempts) {
+      const retryAfter = await this.availableIn(key, decaySeconds);
       return {
         allowed: false,
         remaining: 0,
-        reset: now + decaySeconds
-        // Approximation if we can't read TTL
+        reset: now + retryAfter,
+        retryAfter
       };
     }
     const next = await this.store.increment(key);
@@ -393,7 +857,76 @@ var RateLimiter = class {
     };
   }
   /**
-   * 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.
+   */
+  async availableIn(key, decaySeconds) {
+    if (typeof this.store.ttl === "function") {
+      const remaining = await this.store.ttl(key);
+      if (remaining !== null) {
+        return remaining;
+      }
+    }
+    return decaySeconds;
+  }
+  /**
+   * 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}`);
+   * ```
+   */
+  async getInfo(key, maxAttempts, decaySeconds) {
+    const current = await this.store.get(key);
+    const now = Math.floor(Date.now() / 1e3);
+    if (current === null) {
+      return {
+        limit: maxAttempts,
+        remaining: maxAttempts,
+        reset: now + decaySeconds
+      };
+    }
+    const remaining = Math.max(0, maxAttempts - current);
+    const retryAfter = remaining === 0 ? await this.availableIn(key, decaySeconds) : void 0;
+    return {
+      limit: maxAttempts,
+      remaining,
+      reset: now + (retryAfter ?? decaySeconds),
+      retryAfter
+    };
+  }
+  /**
+   * 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');
+   * ```
    */
   async clear(key) {
     await this.store.forget(key);
@@ -402,20 +935,61 @@ var RateLimiter = class {
 
 // src/CacheManager.ts
 var CacheManager = class {
+  /**
+   * 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, config = {}, events, eventOptions) {
     this.storeFactory = storeFactory;
     this.config = config;
     this.events = events;
     this.eventOptions = eventOptions;
   }
+  /**
+   * Internal registry of initialized cache repositories.
+   */
   stores = /* @__PURE__ */ new Map();
   /**
-   * 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) {
     return new RateLimiter(this.store(name).getStore());
   }
+  /**
+   * 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) {
     const storeName = name ?? this.config.default ?? "memory";
     const existing = this.stores.get(storeName);
@@ -435,11 +1009,15 @@ var CacheManager = class {
   }
   // Laravel-like proxy methods (default store)
   /**
-   * 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
@@ -450,23 +1028,47 @@ var CacheManager = class {
     return this.store().get(key, defaultValue);
   }
   /**
-   * 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) {
     return this.store().has(key);
   }
   /**
-   * 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) {
     return this.store().missing(key);
   }
   /**
-   * Store an item in the cache.
+   * Store an item in the default cache store for a specific duration.
    *
    * @param key - The unique cache key.
-   * @param value - The value to store.
-   * @param ttl - Time to live in seconds (or Date).
+   * @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
@@ -477,21 +1079,51 @@ var CacheManager = class {
     return this.store().put(key, value, ttl);
   }
   /**
-   * Store an item in the cache (alias for put with optional TTL).
+   * 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, value, ttl) {
     return this.store().set(key, value, ttl);
   }
   /**
-   * Store an item in the cache if it doesn't already exist.
+   * 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.
    *
-   * @returns True if added, false if it already existed.
+   * @example
+   * ```typescript
+   * const added = await cache.add('lock:process', true, 30);
+   * ```
    */
   add(key, value, ttl) {
     return this.store().add(key, value, ttl);
   }
   /**
-   * Store an item in the cache indefinitely.
+   * 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, value) {
     return this.store().forever(key, value);
@@ -499,10 +1131,14 @@ var CacheManager = class {
   /**
    * Get an item from the cache, or execute the callback and store the result.
    *
-   * @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.
+   * 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
@@ -516,18 +1152,49 @@ var CacheManager = class {
   }
   /**
    * 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(key, callback) {
     return this.store().rememberForever(key, callback);
   }
   /**
-   * Retrieve multiple items from the cache.
+   * 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(keys) {
     return this.store().many(keys);
   }
   /**
-   * Store multiple items in the cache.
+   * 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, ttl) {
     return this.store().putMany(values, ttl);
@@ -535,99 +1202,474 @@ var CacheManager = class {
   /**
    * Get an item from the cache, allowing stale data while refreshing in background.
    *
-   * @param key - Cache key.
+   * 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 - Closure to refresh the data.
+   * @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(key, ttlSeconds, staleSeconds, callback) {
     return this.store().flexible(key, ttlSeconds, staleSeconds, callback);
   }
   /**
-   * Retrieve an item from the cache and delete it.
+   * 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(key, defaultValue) {
     return this.store().pull(key, defaultValue);
   }
   /**
-   * Remove an item from the cache.
+   * 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) {
     return this.store().forget(key);
   }
   /**
-   * Remove an item from the cache (alias for forget).
+   * 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) {
     return this.store().delete(key);
   }
   /**
-   * Remove all items from the cache.
+   * 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() {
     return this.store().flush();
   }
   /**
-   * Clear the entire cache (alias for flush).
+   * 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() {
     return this.store().clear();
   }
   /**
-   * Increment an integer item in the cache.
+   * 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, value) {
     return this.store().increment(key, value);
   }
   /**
-   * Decrement an integer item in the cache.
+   * 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, value) {
     return this.store().decrement(key, value);
   }
   /**
-   * Get a lock instance.
+   * Get a distributed lock instance from the default cache store.
    *
-   * @param name - Lock name.
-   * @param seconds - Lock duration.
-   * @returns CacheLock instance.
+   * @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, seconds) {
     return this.store().lock(name, seconds);
   }
   /**
-   * Access a tagged cache section (only supported by some stores).
+   * 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) {
     return this.store().tags(tags);
   }
 };
 
-// src/stores/FileStore.ts
-import { createHash, randomUUID } from "crypto";
-import { mkdir, open, readdir, readFile, rm, writeFile } from "fs/promises";
-import { join } from "path";
+// src/prediction/AccessPredictor.ts
+var MarkovPredictor = class {
+  transitions = /* @__PURE__ */ new Map();
+  lastKey = null;
+  maxNodes;
+  maxEdgesPerNode;
+  /**
+   * Initialize a new MarkovPredictor.
+   *
+   * @param options - Limits for internal transition graph to manage memory.
+   */
+  constructor(options = {}) {
+    this.maxNodes = options.maxNodes ?? 1e3;
+    this.maxEdgesPerNode = options.maxEdgesPerNode ?? 10;
+  }
+  record(key) {
+    if (this.lastKey && this.lastKey !== key) {
+      if (!this.transitions.has(this.lastKey)) {
+        if (this.transitions.size >= this.maxNodes) {
+          this.transitions.clear();
+        }
+        this.transitions.set(this.lastKey, /* @__PURE__ */ new Map());
+      }
+      const edges = this.transitions.get(this.lastKey);
+      const count = edges.get(key) ?? 0;
+      edges.set(key, count + 1);
+      if (edges.size > this.maxEdgesPerNode) {
+        let minKey = "";
+        let minCount = Infinity;
+        for (const [k, c] of edges) {
+          if (c < minCount) {
+            minCount = c;
+            minKey = k;
+          }
+        }
+        if (minKey) {
+          edges.delete(minKey);
+        }
+      }
+    }
+    this.lastKey = key;
+  }
+  predict(key) {
+    const edges = this.transitions.get(key);
+    if (!edges) {
+      return [];
+    }
+    return Array.from(edges.entries()).sort((a, b) => b[1] - a[1]).map((entry) => entry[0]);
+  }
+  reset() {
+    this.transitions.clear();
+    this.lastKey = null;
+  }
+};
 
-// src/locks.ts
-var LockTimeoutError = class extends Error {
-  name = "LockTimeoutError";
+// src/stores/CircuitBreakerStore.ts
+var CircuitBreakerStore = class {
+  constructor(primary, options = {}) {
+    this.primary = primary;
+    this.options = {
+      maxFailures: options.maxFailures ?? 5,
+      resetTimeout: options.resetTimeout ?? 6e4,
+      fallback: options.fallback
+    };
+  }
+  state = "CLOSED";
+  failures = 0;
+  lastErrorTime = 0;
+  options;
+  async execute(operation, fallbackResult = null) {
+    if (this.state === "OPEN") {
+      if (Date.now() - this.lastErrorTime > this.options.resetTimeout) {
+        this.state = "HALF_OPEN";
+      } else {
+        return this.handleFallback(operation, fallbackResult);
+      }
+    }
+    try {
+      const result = await operation(this.primary);
+      this.onSuccess();
+      return result;
+    } catch (_error) {
+      this.onFailure();
+      return this.handleFallback(operation, fallbackResult);
+    }
+  }
+  onSuccess() {
+    this.failures = 0;
+    this.state = "CLOSED";
+  }
+  onFailure() {
+    this.failures++;
+    this.lastErrorTime = Date.now();
+    if (this.failures >= this.options.maxFailures) {
+      this.state = "OPEN";
+    }
+  }
+  async handleFallback(operation, fallbackResult) {
+    if (this.options.fallback) {
+      try {
+        return await operation(this.options.fallback);
+      } catch {
+      }
+    }
+    return fallbackResult;
+  }
+  async get(key) {
+    return this.execute((s) => s.get(key));
+  }
+  async put(key, value, ttl) {
+    return this.execute((s) => s.put(key, value, ttl));
+  }
+  async add(key, value, ttl) {
+    return this.execute((s) => s.add(key, value, ttl), false);
+  }
+  async forget(key) {
+    return this.execute((s) => s.forget(key), false);
+  }
+  async flush() {
+    return this.execute((s) => s.flush());
+  }
+  async increment(key, value) {
+    return this.execute((s) => s.increment(key, value), 0);
+  }
+  async decrement(key, value) {
+    return this.execute((s) => s.decrement(key, value), 0);
+  }
+  async ttl(key) {
+    return this.execute(async (s) => s.ttl ? s.ttl(key) : 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() {
+    return this.state;
+  }
 };
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/stores/FileStore.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { dirname, join } from "path";
 var FileStore = class {
+  /**
+   * Initializes a new instance of the FileStore.
+   *
+   * @param options - Configuration settings for the store.
+   */
   constructor(options) {
     this.options = options;
+    if (options.enableCleanup !== false) {
+      this.startCleanupDaemon(options.cleanupInterval ?? 6e4);
+    }
   }
+  cleanupTimer = null;
+  /**
+   * Starts the background process for periodic cache maintenance.
+   *
+   * @param interval - Time between cleanup cycles in milliseconds.
+   * @internal
+   */
+  startCleanupDaemon(interval) {
+    this.cleanupTimer = setInterval(() => {
+      this.cleanExpiredFiles().catch(() => {
+      });
+    }, interval);
+    if (this.cleanupTimer.unref) {
+      this.cleanupTimer.unref();
+    }
+  }
+  /**
+   * 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.`);
+   * ```
+   */
+  async cleanExpiredFiles() {
+    await this.ensureDir();
+    let cleaned = 0;
+    const validFiles = [];
+    const scanDir = async (dir) => {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await scanDir(fullPath);
+          try {
+            await rm(fullPath, { recursive: false });
+          } catch {
+          }
+        } else if (entry.isFile()) {
+          if (!entry.name.endsWith(".json") || entry.name.startsWith(".lock-")) {
+            continue;
+          }
+          try {
+            const raw = await readFile(fullPath, "utf8");
+            const data = JSON.parse(raw);
+            if (isExpired(data.expiresAt)) {
+              await rm(fullPath, { force: true });
+              cleaned++;
+            } else if (this.options.maxFiles) {
+              const stats = await stat(fullPath);
+              validFiles.push({ path: fullPath, mtime: stats.mtimeMs });
+            }
+          } catch {
+          }
+        }
+      }
+    };
+    await scanDir(this.options.directory);
+    if (this.options.maxFiles && validFiles.length > this.options.maxFiles) {
+      validFiles.sort((a, b) => a.mtime - b.mtime);
+      const toRemove = validFiles.slice(0, validFiles.length - this.options.maxFiles);
+      await Promise.all(
+        toRemove.map(async (f) => {
+          try {
+            await rm(f.path, { force: true });
+            cleaned++;
+          } catch {
+          }
+        })
+      );
+    }
+    return cleaned;
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  /**
+   * Ensures that the base storage directory exists.
+   *
+   * @throws {Error} If the directory cannot be created due to permissions or path conflicts.
+   * @internal
+   */
   async ensureDir() {
     await mkdir(this.options.directory, { recursive: true });
   }
+  /**
+   * 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
+   */
   filePathForKey(key) {
     const hashed = hashKey(key);
+    if (this.options.useSubdirectories) {
+      const d1 = hashed.substring(0, 2);
+      const d2 = hashed.substring(2, 4);
+      return join(this.options.directory, d1, d2, `${hashed}.json`);
+    }
     return join(this.options.directory, `${hashed}.json`);
   }
+  /**
+   * 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');
+   * ```
+   */
   async get(key) {
     const normalized = normalizeCacheKey(key);
     await this.ensureDir();
@@ -644,6 +1686,22 @@ var FileStore = class {
       return null;
     }
   }
+  /**
+   * 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);
+   * ```
+   */
   async put(key, value, ttl) {
     const normalized = normalizeCacheKey(key);
     await this.ensureDir();
@@ -653,9 +1711,33 @@ var FileStore = class {
       return;
     }
     const file = this.filePathForKey(normalized);
+    if (this.options.useSubdirectories) {
+      await mkdir(dirname(file), { recursive: true });
+    }
+    const tempFile = `${file}.tmp.${Date.now()}.${randomUUID()}`;
     const payload = { expiresAt: expiresAt ?? null, value };
-    await writeFile(file, JSON.stringify(payload), "utf8");
+    try {
+      await writeFile(tempFile, JSON.stringify(payload), "utf8");
+      await rename(tempFile, file);
+    } catch (error) {
+      await rm(tempFile, { force: true }).catch(() => {
+      });
+      throw error;
+    }
   }
+  /**
+   * 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);
+   * ```
+   */
   async add(key, value, ttl) {
     const normalized = normalizeCacheKey(key);
     const existing = await this.get(normalized);
@@ -665,6 +1747,17 @@ var FileStore = class {
     await this.put(normalized, value, ttl);
     return true;
   }
+  /**
+   * 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');
+   * ```
+   */
   async forget(key) {
     const normalized = normalizeCacheKey(key);
     await this.ensureDir();
@@ -676,13 +1769,39 @@ var FileStore = class {
       return false;
     }
   }
+  /**
+   * 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();
+   * ```
+   */
   async flush() {
     await this.ensureDir();
-    const files = await readdir(this.options.directory);
-    await Promise.all(
-      files.filter((f) => f.endsWith(".json")).map((f) => rm(join(this.options.directory, f), { force: true }))
-    );
+    await rm(this.options.directory, { recursive: true, force: true });
+    await this.ensureDir();
   }
+  /**
+   * 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');
+   * ```
+   */
   async increment(key, value = 1) {
     const normalized = normalizeCacheKey(key);
     const current = await this.get(normalized);
@@ -690,28 +1809,105 @@ var FileStore = class {
     await this.put(normalized, next, null);
     return next;
   }
+  /**
+   * 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');
+   * ```
+   */
   async decrement(key, value = 1) {
     return this.increment(key, -value);
   }
+  /**
+   * 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');
+   * ```
+   */
+  async ttl(key) {
+    const normalized = normalizeCacheKey(key);
+    const file = this.filePathForKey(normalized);
+    try {
+      const raw = await readFile(file, "utf8");
+      const data = JSON.parse(raw);
+      if (data.expiresAt === null) {
+        return null;
+      }
+      const remaining = Math.ceil((data.expiresAt - Date.now()) / 1e3);
+      return remaining > 0 ? remaining : null;
+    } catch {
+      return 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, seconds = 10) {
     const normalizedName = normalizeCacheKey(name);
     const lockFile = join(this.options.directory, `.lock-${hashKey(normalizedName)}`);
     const ttlMillis = Math.max(1, seconds) * 1e3;
     const owner = randomUUID();
+    const isProcessAlive = (pid) => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch {
+        return false;
+      }
+    };
     const tryAcquire = async () => {
       await this.ensureDir();
       try {
         const handle = await open(lockFile, "wx");
-        await handle.writeFile(JSON.stringify({ owner, expiresAt: Date.now() + ttlMillis }), "utf8");
+        const lockData = {
+          owner,
+          expiresAt: Date.now() + ttlMillis,
+          pid: process.pid
+        };
+        await handle.writeFile(JSON.stringify(lockData), "utf8");
         await handle.close();
         return true;
       } catch {
         try {
           const raw = await readFile(lockFile, "utf8");
           const data = JSON.parse(raw);
-          if (!data.expiresAt || Date.now() > data.expiresAt) {
+          const isExpired2 = !data.expiresAt || Date.now() > data.expiresAt;
+          const isProcessDead = data.pid && !isProcessAlive(data.pid);
+          if (isExpired2 || isProcessDead) {
             await rm(lockFile, { force: true });
-            return false;
           }
         } catch {
         }
@@ -719,9 +1915,17 @@ var FileStore = class {
       }
     };
     return {
+      /**
+       * Attempts to acquire the lock immediately.
+       *
+       * @returns `true` if the lock was successfully acquired, `false` otherwise.
+       */
       async acquire() {
         return tryAcquire();
       },
+      /**
+       * Releases the lock if it is owned by the current instance.
+       */
       async release() {
         try {
           const raw = await readFile(lockFile, "utf8");
@@ -732,6 +1936,15 @@ var FileStore = class {
         } catch {
         }
       },
+      /**
+       * Executes a callback within the lock, waiting if necessary.
+       *
+       * @param secondsToWait - Maximum time to wait for the lock in seconds.
+       * @param callback - The function to execute once the lock is acquired.
+       * @param options - Polling configuration.
+       * @returns The result of the callback.
+       * @throws {LockTimeoutError} If the lock cannot be acquired within the wait time.
+       */
       async block(secondsToWait, callback, options) {
         const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
         const sleepMillis = options?.sleepMillis ?? 150;
@@ -752,43 +1965,238 @@ var FileStore = class {
     };
   }
 };
-function hashKey(key) {
-  return createHash("sha256").update(key).digest("hex");
-}
+function hashKey(key) {
+  return createHash("sha256").update(key).digest("hex");
+}
+
+// src/stores/MemoryStore.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/utils/LRUCache.ts
+var LRUCache = class {
+  /**
+   * Creates a new LRU cache instance.
+   *
+   * @param maxSize - The maximum number of items allowed in the cache. Set to 0 for unlimited.
+   * @param onEvict - Optional callback triggered when an item is evicted due to capacity limits.
+   */
+  constructor(maxSize, onEvict) {
+    this.maxSize = maxSize;
+    this.onEvict = onEvict;
+  }
+  map = /* @__PURE__ */ new Map();
+  head = null;
+  tail = null;
+  /**
+   * The current number of items stored in the cache.
+   */
+  get size() {
+    return this.map.size;
+  }
+  /**
+   * Checks if a key exists in the cache without updating its access order.
+   *
+   * @param key - The identifier to look for.
+   * @returns True if the key exists, false otherwise.
+   */
+  has(key) {
+    return this.map.has(key);
+  }
+  /**
+   * Retrieves an item from the cache and marks it as most recently used.
+   *
+   * @param key - The identifier of the item to retrieve.
+   * @returns The cached value, or undefined if not found.
+   *
+   * @example
+   * ```typescript
+   * const value = cache.get('my-key');
+   * ```
+   */
+  get(key) {
+    const node = this.map.get(key);
+    if (!node) {
+      return void 0;
+    }
+    this.moveToHead(node);
+    return node.value;
+  }
+  /**
+   * Retrieves an item from the cache without updating its access order.
+   *
+   * Useful for inspecting the cache without affecting eviction priority.
+   *
+   * @param key - The identifier of the item to peek.
+   * @returns The cached value, or undefined if not found.
+   */
+  peek(key) {
+    const node = this.map.get(key);
+    return node?.value;
+  }
+  /**
+   * Adds or updates an item in the cache, marking it as most recently used.
+   *
+   * If the cache is at capacity, the least recently used item will be evicted.
+   *
+   * @param key - The identifier for the item.
+   * @param value - The data to store.
+   *
+   * @example
+   * ```typescript
+   * cache.set('user:1', { name: 'Alice' });
+   * ```
+   */
+  set(key, value) {
+    const existingNode = this.map.get(key);
+    if (existingNode) {
+      existingNode.value = value;
+      this.moveToHead(existingNode);
+      return;
+    }
+    if (this.maxSize > 0 && this.map.size >= this.maxSize) {
+      this.evict();
+    }
+    const newNode = {
+      key,
+      value,
+      prev: null,
+      next: this.head
+    };
+    if (this.head) {
+      this.head.prev = newNode;
+    }
+    this.head = newNode;
+    if (!this.tail) {
+      this.tail = newNode;
+    }
+    this.map.set(key, newNode);
+  }
+  /**
+   * Removes an item from the cache.
+   *
+   * @param key - The identifier of the item to remove.
+   * @returns True if the item was found and removed, false otherwise.
+   */
+  delete(key) {
+    const node = this.map.get(key);
+    if (!node) {
+      return false;
+    }
+    this.removeNode(node);
+    this.map.delete(key);
+    return true;
+  }
+  /**
+   * Removes all items from the cache.
+   */
+  clear() {
+    this.map.clear();
+    this.head = null;
+    this.tail = null;
+  }
+  /**
+   * Moves a node to the head of the linked list (most recently used).
+   *
+   * @param node - The node to promote.
+   */
+  moveToHead(node) {
+    if (node === this.head) {
+      return;
+    }
+    if (node.prev) {
+      node.prev.next = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    }
+    if (node === this.tail) {
+      this.tail = node.prev;
+    }
+    node.prev = null;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+  }
+  /**
+   * Removes a node from the linked list.
+   *
+   * @param node - The node to remove.
+   */
+  removeNode(node) {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+    node.prev = null;
+    node.next = null;
+  }
+  /**
+   * Evicts the least recently used item (the tail of the list).
+   *
+   * Triggers the `onEvict` callback if provided.
+   */
+  evict() {
+    if (!this.tail) {
+      return;
+    }
+    const node = this.tail;
+    if (this.onEvict) {
+      this.onEvict(node.key, node.value);
+    }
+    this.removeNode(node);
+    this.map.delete(node.key);
+  }
+};
 
 // src/stores/MemoryStore.ts
-import { randomUUID as randomUUID2 } from "crypto";
 var MemoryStore = class {
-  constructor(options = {}) {
-    this.options = options;
-  }
-  entries = /* @__PURE__ */ new Map();
+  entries;
   locks = /* @__PURE__ */ new Map();
+  stats = { hits: 0, misses: 0, evictions: 0 };
   tagToKeys = /* @__PURE__ */ new Map();
   keyToTags = /* @__PURE__ */ new Map();
-  touchLRU(key) {
-    const entry = this.entries.get(key);
-    if (!entry) {
-      return;
-    }
-    this.entries.delete(key);
-    this.entries.set(key, entry);
+  /**
+   * Creates a new MemoryStore instance.
+   *
+   * @param options - Configuration for capacity and eviction.
+   */
+  constructor(options = {}) {
+    this.entries = new LRUCache(options.maxItems ?? 0, (key) => {
+      this.tagIndexRemove(key);
+      this.stats.evictions++;
+    });
   }
-  pruneIfNeeded() {
-    const maxItems = this.options.maxItems;
-    if (!maxItems || maxItems <= 0) {
-      return;
-    }
-    while (this.entries.size > maxItems) {
-      const oldest = this.entries.keys().next().value;
-      if (!oldest) {
-        return;
-      }
-      void this.forget(oldest);
-    }
+  /**
+   * 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() {
+    const total = this.stats.hits + this.stats.misses;
+    return {
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      hitRate: total > 0 ? this.stats.hits / total : 0,
+      size: this.entries.size,
+      evictions: this.stats.evictions
+    };
   }
   cleanupExpired(key, now = Date.now()) {
-    const entry = this.entries.get(key);
+    const entry = this.entries.peek(key);
     if (!entry) {
       return;
     }
@@ -796,19 +2204,48 @@ var MemoryStore = class {
       void this.forget(key);
     }
   }
+  /**
+   * 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');
+   * ```
+   */
   async get(key) {
     const normalized = normalizeCacheKey(key);
     const entry = this.entries.get(normalized);
     if (!entry) {
+      this.stats.misses++;
       return null;
     }
     if (isExpired(entry.expiresAt)) {
       await this.forget(normalized);
+      this.stats.misses++;
       return null;
     }
-    this.touchLRU(normalized);
+    this.stats.hits++;
     return entry.value;
   }
+  /**
+   * 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);
+   * ```
+   */
   async put(key, value, ttl) {
     const normalized = normalizeCacheKey(key);
     const expiresAt = ttlToExpiresAt(ttl);
@@ -817,8 +2254,20 @@ var MemoryStore = class {
       return;
     }
     this.entries.set(normalized, { value, expiresAt: expiresAt ?? null });
-    this.pruneIfNeeded();
   }
+  /**
+   * 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);
+   * ```
+   */
   async add(key, value, ttl) {
     const normalized = normalizeCacheKey(key);
     this.cleanupExpired(normalized);
@@ -828,17 +2277,50 @@ var MemoryStore = class {
     await this.put(normalized, value, ttl);
     return true;
   }
+  /**
+   * 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');
+   * ```
+   */
   async forget(key) {
     const normalized = normalizeCacheKey(key);
     const existed = this.entries.delete(normalized);
     this.tagIndexRemove(normalized);
     return existed;
   }
+  /**
+   * Removes all items from the cache and resets all internal indexes.
+   *
+   * @example
+   * ```typescript
+   * await store.flush();
+   * ```
+   */
   async flush() {
     this.entries.clear();
     this.tagToKeys.clear();
     this.keyToTags.clear();
   }
+  /**
+   * 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');
+   * ```
+   */
   async increment(key, value = 1) {
     const normalized = normalizeCacheKey(key);
     const current = await this.get(normalized);
@@ -846,9 +2328,64 @@ var MemoryStore = class {
     await this.put(normalized, next, null);
     return next;
   }
+  /**
+   * 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);
+   * ```
+   */
   async decrement(key, value = 1) {
     return this.increment(key, -value);
   }
+  /**
+   * 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');
+   * ```
+   */
+  async ttl(key) {
+    const normalized = normalizeCacheKey(key);
+    const entry = this.entries.peek(normalized);
+    if (!entry || entry.expiresAt === null) {
+      return null;
+    }
+    const now = Date.now();
+    if (isExpired(entry.expiresAt, now)) {
+      await this.forget(normalized);
+      return null;
+    }
+    return Math.max(0, Math.ceil((entry.expiresAt - now) / 1e3));
+  }
+  /**
+   * 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, seconds = 10) {
     const lockKey = `lock:${normalizeCacheKey(name)}`;
     const ttlMillis = Math.max(1, seconds) * 1e3;
@@ -865,6 +2402,11 @@ var MemoryStore = class {
     };
     let owner;
     return {
+      /**
+       * Attempts to acquire the lock.
+       *
+       * @returns `true` if acquired, `false` if already held by another process.
+       */
       async acquire() {
         const result = await acquire();
         if (!result.ok) {
@@ -873,6 +2415,9 @@ var MemoryStore = class {
         owner = result.owner;
         return true;
       },
+      /**
+       * Releases the lock if it is held by the current owner.
+       */
       async release() {
         if (!owner) {
           return;
@@ -883,6 +2428,22 @@ var MemoryStore = class {
         }
         owner = void 0;
       },
+      /**
+       * Attempts to acquire the lock and execute a callback, waiting if necessary.
+       *
+       * @param secondsToWait - How long to wait for the lock before timing out.
+       * @param callback - The logic to execute while holding the lock.
+       * @param options - Polling configuration.
+       * @returns The result of the callback.
+       * @throws {LockTimeoutError} If the lock cannot be acquired within the wait time.
+       *
+       * @example
+       * ```typescript
+       * await lock.block(5, async () => {
+       *   // This code runs exclusively
+       * });
+       * ```
+       */
       async block(secondsToWait, callback, options) {
         const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
         const sleepMillis = options?.sleepMillis ?? 150;
@@ -902,6 +2463,15 @@ var MemoryStore = class {
       }
     };
   }
+  /**
+   * 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, tags) {
     const normalizedKey = normalizeCacheKey(key);
     const normalizedTags = [...tags].map(String).filter(Boolean).sort();
@@ -910,6 +2480,12 @@ var MemoryStore = class {
     }
     return `tags:${normalizedTags.join("|")}:${normalizedKey}`;
   }
+  /**
+   * 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, taggedKey) {
     const normalizedTags = [...tags].map(String).filter(Boolean);
     if (normalizedTags.length === 0) {
@@ -932,6 +2508,11 @@ var MemoryStore = class {
       tagSet.add(tag);
     }
   }
+  /**
+   * Removes a key from the tag indexes.
+   *
+   * @param taggedKey - The key to remove from all tag sets.
+   */
   tagIndexRemove(taggedKey) {
     const tags = this.keyToTags.get(taggedKey);
     if (!tags) {
@@ -949,6 +2530,16 @@ var MemoryStore = class {
     }
     this.keyToTags.delete(taggedKey);
   }
+  /**
+   * Invalidates all cache entries associated with any of the given tags.
+   *
+   * @param tags - The tags to flush.
+   *
+   * @example
+   * ```typescript
+   * await store.flushTags(['users', 'profiles']);
+   * ```
+   */
   async flushTags(tags) {
     const normalizedTags = [...tags].map(String).filter(Boolean);
     if (normalizedTags.length === 0) {
@@ -972,38 +2563,187 @@ var MemoryStore = class {
 
 // src/stores/NullStore.ts
 var NullStore = class {
+  /**
+   * 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');
+   * ```
+   */
   async get(_key) {
     return null;
   }
+  /**
+   * Discards the provided value instead of storing it.
+   *
+   * @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 store.put('user:1', { id: 1 }, 3600);
+   * ```
+   */
   async put(_key, _value, _ttl) {
   }
+  /**
+   * Simulates a failed attempt to add an item to the cache.
+   *
+   * Since NullStore does not store data, this method always indicates that
+   * the item was not added.
+   *
+   * @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 added = await store.add('key', 'value', 60); // false
+   * ```
+   */
   async add(_key, _value, _ttl) {
     return false;
   }
+  /**
+   * Simulates a failed attempt to remove an item from the cache.
+   *
+   * 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
+   * ```
+   */
   async forget(_key) {
     return false;
   }
+  /**
+   * Performs a no-op flush operation.
+   *
+   * @returns Resolves immediately as there is no data to clear.
+   *
+   * @example
+   * ```typescript
+   * await store.flush();
+   * ```
+   */
   async flush() {
   }
+  /**
+   * 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`.
+   *
+   * @example
+   * ```typescript
+   * const newValue = await store.increment('counter', 1); // 0
+   * ```
+   */
   async increment(_key, _value = 1) {
     return 0;
   }
+  /**
+   * 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
+   * ```
+   */
   async decrement(_key, _value = 1) {
     return 0;
   }
 };
 
+// src/stores/PredictiveStore.ts
+var PredictiveStore = class {
+  constructor(store, options = {}) {
+    this.store = store;
+    this.predictor = options.predictor ?? new MarkovPredictor();
+  }
+  predictor;
+  async get(key) {
+    this.predictor.record(key);
+    const candidates = this.predictor.predict(key);
+    if (candidates.length > 0) {
+      void Promise.all(candidates.map((k) => this.store.get(k).catch(() => {
+      })));
+    }
+    return this.store.get(key);
+  }
+  async put(key, value, ttl) {
+    return this.store.put(key, value, ttl);
+  }
+  async add(key, value, ttl) {
+    return this.store.add(key, value, ttl);
+  }
+  async forget(key) {
+    return this.store.forget(key);
+  }
+  async flush() {
+    if (typeof this.predictor.reset === "function") {
+      this.predictor.reset();
+    }
+    return this.store.flush();
+  }
+  async increment(key, value) {
+    return this.store.increment(key, value);
+  }
+  async decrement(key, value) {
+    return this.store.decrement(key, value);
+  }
+  lock(name, seconds) {
+    return this.store.lock ? this.store.lock(name, seconds) : void 0;
+  }
+  async ttl(key) {
+    return this.store.ttl ? this.store.ttl(key) : null;
+  }
+};
+
 // src/stores/RedisStore.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import { Redis } from "@gravito/plasma";
 var RedisStore = class {
   connectionName;
+  /**
+   * Initialize a new RedisStore instance.
+   *
+   * @param options - Redis connection and prefix settings.
+   *
+   * @example
+   * ```typescript
+   * const store = new RedisStore({ prefix: 'app:' });
+   * ```
+   */
   constructor(options = {}) {
     this.connectionName = options.connection;
   }
   get client() {
     return Redis.connection(this.connectionName);
   }
+  /**
+   * 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.
+   */
   async get(key) {
     const normalized = normalizeCacheKey(key);
     const value = await this.client.get(normalized);
@@ -1016,6 +2756,14 @@ var RedisStore = class {
       return value;
     }
   }
+  /**
+   * 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.
+   */
   async put(key, value, ttl) {
     const normalized = normalizeCacheKey(key);
     const serialized = JSON.stringify(value);
@@ -1041,8 +2789,20 @@ var RedisStore = class {
   }
   async forget(key) {
     const normalized = normalizeCacheKey(key);
-    const count = await this.client.del(normalized);
-    return count > 0;
+    const luaScript = `
+      local key = KEYS[1]
+      local tag_prefix = ARGV[1]
+      local tags = redis.call('SMEMBERS', key .. ':tags')
+      local del_result = redis.call('DEL', key)
+      for _, tag in ipairs(tags) do
+        redis.call('SREM', tag_prefix .. tag, key)
+      end
+      redis.call('DEL', key .. ':tags')
+      return del_result
+    `;
+    const client = this.client;
+    const result = await client.eval(luaScript, 1, normalized, "tag:");
+    return result > 0;
   }
   async flush() {
     await this.client.flushdb();
@@ -1054,6 +2814,14 @@ var RedisStore = class {
     }
     return await this.client.incrby(normalized, value);
   }
+  /**
+   * 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.
+   */
   async decrement(key, value = 1) {
     const normalized = normalizeCacheKey(key);
     if (value === 1) {
@@ -1072,13 +2840,25 @@ var RedisStore = class {
       return;
     }
     const pipeline = this.client.pipeline();
+    pipeline.sadd(`${taggedKey}:tags`, ...tags);
     for (const tag of tags) {
       const tagSetKey = `tag:${tag}`;
       pipeline.sadd(tagSetKey, taggedKey);
     }
     await pipeline.exec();
   }
-  async tagIndexRemove(_taggedKey) {
+  async tagIndexRemove(taggedKey) {
+    const luaScript = `
+      local key = KEYS[1]
+      local tag_prefix = ARGV[1]
+      local tags = redis.call('SMEMBERS', key .. ':tags')
+      for _, tag in ipairs(tags) do
+        redis.call('SREM', tag_prefix .. tag, key)
+      end
+      redis.call('DEL', key .. ':tags')
+    `;
+    const client = this.client;
+    await client.eval(luaScript, 1, taggedKey, "tag:");
   }
   async flushTags(tags) {
     if (tags.length === 0) {
@@ -1106,6 +2886,11 @@ var RedisStore = class {
   // ============================================================================
   // Locks
   // ============================================================================
+  async ttl(key) {
+    const normalized = normalizeCacheKey(key);
+    const result = await this.client.ttl(normalized);
+    return result < 0 ? null : result;
+  }
   lock(name, seconds = 10) {
     const lockKey = `lock:${normalizeCacheKey(name)}`;
     const owner = randomUUID3();
@@ -1117,15 +2902,49 @@ var RedisStore = class {
         return result === "OK";
       },
       async release() {
-        const current = await client.get(lockKey);
-        if (current === owner) {
-          await client.del(lockKey);
-        }
+        const luaScript = `
+          local current = redis.call('GET', KEYS[1])
+          if current == ARGV[1] then
+            return redis.call('DEL', KEYS[1])
+          else
+            return 0
+          end
+        `;
+        const evalClient = client;
+        await evalClient.eval(luaScript, 1, lockKey, owner);
+      },
+      async extend(extensionSeconds) {
+        const luaScript = `
+          local current = redis.call('GET', KEYS[1])
+          if current == ARGV[1] then
+            return redis.call('EXPIRE', KEYS[1], ARGV[2])
+          else
+            return 0
+          end
+        `;
+        const evalClient = client;
+        const result = await evalClient.eval(
+          luaScript,
+          1,
+          lockKey,
+          owner,
+          extensionSeconds.toString()
+        );
+        return result === 1;
+      },
+      async getRemainingTime() {
+        return await client.ttl(lockKey);
       },
       async block(secondsToWait, callback, options) {
+        const retryInterval = options?.retryInterval ?? options?.sleepMillis ?? 100;
+        const maxRetries = options?.maxRetries ?? Number.POSITIVE_INFINITY;
+        const signal = options?.signal;
         const deadline = Date.now() + Math.max(0, secondsToWait) * 1e3;
-        const sleepMillis = options?.sleepMillis ?? 150;
-        while (Date.now() <= deadline) {
+        let attempt = 0;
+        while (Date.now() <= deadline && attempt < maxRetries) {
+          if (signal?.aborted) {
+            throw new Error(`Lock acquisition for '${name}' was aborted`);
+          }
           if (await this.acquire()) {
             try {
               return await callback();
@@ -1133,7 +2952,9 @@ var RedisStore = class {
               await this.release();
             }
           }
-          await sleep(sleepMillis);
+          attempt++;
+          const delay = Math.min(retryInterval * 1.5 ** Math.min(attempt, 10), 1e3);
+          await sleep(delay);
         }
         throw new LockTimeoutError(
           `Failed to acquire lock '${name}' within ${secondsToWait} seconds.`
@@ -1143,6 +2964,64 @@ var RedisStore = class {
   }
 };
 
+// src/stores/TieredStore.ts
+var TieredStore = class {
+  /**
+   * Initializes a new TieredStore.
+   *
+   * @param local - The L1 cache store (usually MemoryStore).
+   * @param remote - The L2 cache store (usually RedisStore or FileStore).
+   */
+  constructor(local, remote) {
+    this.local = local;
+    this.remote = remote;
+  }
+  async get(key) {
+    const localValue = await this.local.get(key);
+    if (localValue !== null) {
+      return localValue;
+    }
+    const remoteValue = await this.remote.get(key);
+    if (remoteValue !== null) {
+      const ttl = this.remote.ttl ? await this.remote.ttl(key) : null;
+      await this.local.put(key, remoteValue, ttl);
+    }
+    return remoteValue;
+  }
+  async put(key, value, ttl) {
+    await Promise.all([this.local.put(key, value, ttl), this.remote.put(key, value, ttl)]);
+  }
+  async add(key, value, ttl) {
+    const ok = await this.remote.add(key, value, ttl);
+    if (ok) {
+      await this.local.put(key, value, ttl);
+    }
+    return ok;
+  }
+  async forget(key) {
+    const [localOk, remoteOk] = await Promise.all([this.local.forget(key), this.remote.forget(key)]);
+    return localOk || remoteOk;
+  }
+  async flush() {
+    await Promise.all([this.local.flush(), this.remote.flush()]);
+  }
+  async increment(key, value = 1) {
+    const next = await this.remote.increment(key, value);
+    const ttl = this.remote.ttl ? await this.remote.ttl(key) : null;
+    await this.local.put(key, next, ttl);
+    return next;
+  }
+  async decrement(key, value = 1) {
+    return this.increment(key, -value);
+  }
+  async ttl(key) {
+    if (this.remote.ttl) {
+      return this.remote.ttl(key);
+    }
+    return this.local.ttl ? this.local.ttl(key) : null;
+  }
+};
+
 // src/index.ts
 var MemoryCacheProvider = class {
   store = new MemoryStore();
@@ -1236,6 +3115,26 @@ function createStoreFactory(config) {
         }
       };
     }
+    if (storeConfig.driver === "tiered") {
+      const factory = createStoreFactory(config);
+      return new TieredStore(factory(storeConfig.local), factory(storeConfig.remote));
+    }
+    if (storeConfig.driver === "predictive") {
+      const factory = createStoreFactory(config);
+      return new PredictiveStore(factory(storeConfig.inner), {
+        predictor: new MarkovPredictor({ maxNodes: storeConfig.maxNodes })
+      });
+    }
+    if (storeConfig.driver === "circuit-breaker") {
+      const factory = createStoreFactory(config);
+      const primary = factory(storeConfig.primary);
+      const fallback = storeConfig.fallback ? factory(storeConfig.fallback) : void 0;
+      return new CircuitBreakerStore(primary, {
+        maxFailures: storeConfig.maxFailures,
+        resetTimeout: storeConfig.resetTimeout,
+        fallback
+      });
+    }
     throw new Error(`Unsupported cache driver '${storeConfig.driver}'.`);
   };
 }
@@ -1302,15 +3201,19 @@ var OrbitCache = OrbitStasis;
 export {
   CacheManager,
   CacheRepository,
+  CircuitBreakerStore,
   FileStore,
   LockTimeoutError,
+  MarkovPredictor,
   MemoryCacheProvider,
   MemoryStore,
   NullStore,
   OrbitCache,
   OrbitStasis,
+  PredictiveStore,
   RateLimiter,
   RedisStore,
+  TieredStore,
   orbitCache as default,
   isExpired,
   isTaggableStore,