@devbro/neko-cache 0.1.3 → 0.1.5

package/dist/index.js

@@ -43,24 +43,67 @@ module.exports = __toCommonJS(index_exports);
 // src/cache.mts
 var import_crypto = require("crypto");
 var Cache = class {
+  /**
+   * Creates a new Cache instance.
+   * @param provider - The cache provider implementation to use
+   */
   constructor(provider) {
     this.provider = provider;
   }
   static {
     __name(this, "Cache");
   }
+  /**
+   * Retrieves a value from the cache.
+   * @template T - The expected type of the cached value
+   * @param key - The cache key (can be string, number, object, or array)
+   * @returns The cached value or undefined if not found or expired
+   */
   async get(key) {
     return this.provider.get(this.generateKey(key));
   }
+  /**
+   * Stores a value in the cache.
+   * @param key - The cache key (can be string, number, object, or array)
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional)
+   */
   async put(key, value, ttl) {
     return this.provider.put(this.generateKey(key), value, ttl);
   }
+  /**
+   * Deletes a value from the cache.
+   * @param key - The cache key to delete
+   */
   async delete(key) {
     return this.provider.delete(this.generateKey(key));
   }
+  /**
+   * Checks if a key exists in the cache.
+   * @param key - The cache key to check
+   * @returns True if the key exists and has not expired, false otherwise
+   */
   async has(key) {
     return this.provider.has(this.generateKey(key));
   }
+  /**
+   * Increments a numeric value in the cache atomically.
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The new value after incrementing
+   */
+  async increment(key, amount = 1) {
+    return this.provider.increment(this.generateKey(key), amount);
+  }
+  /**
+   * Gets a value from cache or executes callback and caches the result.
+   * This is useful for caching expensive operations.
+   * @template T - The expected type of the value
+   * @param key - The cache key
+   * @param callback - Function to execute if cache miss occurs
+   * @param options - Cache options including TTL (default: 3600 seconds)
+   * @returns The cached value or the result of the callback
+   */
   async remember(key, callback, options = {}) {
     options.ttl = options.ttl ?? 3600;
     const cached = await this.get(key);
@@ -72,11 +115,16 @@ var Cache = class {
     return result;
   }
   /**
-   * Generates a cache key by serializing and concatenating the provided parts.
-   * @param parts
-   * @returns
+   * Generates a cache key by serializing and hashing complex keys.
+   * Simple string keys under 250 characters are returned as-is.
+   * Complex keys (objects, arrays, long strings) are MD5 hashed.
+   * @param key - The key to generate a cache key from
+   * @returns A string suitable for use as a cache key
    */
   generateKey(key) {
+    if (typeof key === "string" && key.length <= 250) {
+      return key;
+    }
     return (0, import_crypto.createHash)("md5").update(JSON.stringify(key)).digest("hex");
   }
 };
@@ -85,6 +133,10 @@ var Cache = class {
 var import_redis = require("redis");
 var RedisCacheProvider = class {
   // default TTL in seconds
+  /**
+   * Creates a new RedisCacheProvider instance.
+   * @param config - Redis client configuration options
+   */
   constructor(config) {
     this.config = config;
     this.client = this.createRedisClient();
@@ -95,15 +147,27 @@ var RedisCacheProvider = class {
   }
   client;
   defaultTTL = 3600;
+  /**
+   * Creates a Redis client with the provided configuration.
+   * @returns A Redis client instance
+   */
   createRedisClient() {
     let rc = (0, import_redis.createClient)(this.config);
     return rc;
   }
+  /**
+   * Ensures the Redis client is connected before performing operations.
+   */
   async ensureConnection() {
     if (!this.client.isOpen) {
       await this.client.connect();
     }
   }
+  /**
+   * Retrieves a value from the cache.
+   * @param key - The cache key
+   * @returns The cached value or undefined if not found
+   */
   async get(key) {
     await this.ensureConnection();
     let rc = this.client.get(key);
@@ -114,6 +178,12 @@ var RedisCacheProvider = class {
       return JSON.parse(value);
     });
   }
+  /**
+   * Stores a value in the cache.
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional)
+   */
   async put(key, value, ttl) {
     await this.ensureConnection();
     const serializedValue = JSON.stringify(value);
@@ -124,15 +194,34 @@ var RedisCacheProvider = class {
       await this.client.set(key, serializedValue);
     }
   }
+  /**
+   * Deletes a value from the cache.
+   * @param key - The cache key to delete
+   */
   async delete(key) {
     await this.ensureConnection();
     await this.client.del(key);
   }
+  /**
+   * Checks if a key exists in the cache.
+   * @param key - The cache key to check
+   * @returns True if the key exists, false otherwise
+   */
   async has(key) {
     await this.ensureConnection();
     const result = await this.client.exists(key);
     return result === 1;
   }
+  /**
+   * Increments a numeric value in the cache atomically using Redis INCRBY.
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The new value after incrementing
+   */
+  async increment(key, amount = 1) {
+    await this.ensureConnection();
+    return await this.client.incrBy(key, amount);
+  }
 };
 
 // src/providers/FileCacheProvider.mts
@@ -148,11 +237,18 @@ var FileCacheProvider = class {
     cleanupInterval: 300 * 1e3
   };
   cleanupTimer;
+  /**
+   * Creates a new FileCacheProvider instance.
+   * @param config - Configuration options for the cache
+   */
   constructor(config = {}) {
     this.config = { ...this.config, ...config };
     this.ensureCacheDirectory();
     this.startCleanupTimer();
   }
+  /**
+   * Ensures the cache directory exists, creating it if necessary.
+   */
   async ensureCacheDirectory() {
     try {
       await fs.access(this.config.cacheDirectory);
@@ -160,6 +256,9 @@ var FileCacheProvider = class {
       await fs.mkdir(this.config.cacheDirectory, { recursive: true });
     }
   }
+  /**
+   * Starts the automatic cleanup timer for expired entries.
+   */
   startCleanupTimer() {
     if (this.config.cleanupInterval > 0) {
       this.cleanupTimer = setInterval(() => {
@@ -167,16 +266,27 @@ var FileCacheProvider = class {
       }, this.config.cleanupInterval);
     }
   }
+  /**
+   * Stops the automatic cleanup timer.
+   */
   stopCleanupTimer() {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * Generates a safe file path for the given cache key.
+   * @param key - The cache key
+   * @returns The full file path for the cache entry
+   */
   getFilePath(key) {
     const safeKey = key.replace(/[^a-z0-9]/gi, "_");
     return path.join(this.config.cacheDirectory, `${safeKey}.json`);
   }
+  /**
+   * Removes all expired cache entries from the cache directory.
+   */
   async cleanupExpiredEntries() {
     try {
       const files = await fs.readdir(this.config.cacheDirectory);
@@ -199,6 +309,11 @@ var FileCacheProvider = class {
     } catch (error) {
     }
   }
+  /**
+   * Retrieves a value from the cache.
+   * @param key - The cache key
+   * @returns The cached value or undefined if not found or expired
+   */
   async get(key) {
     const filePath = this.getFilePath(key);
     try {
@@ -214,6 +329,12 @@ var FileCacheProvider = class {
       return void 0;
     }
   }
+  /**
+   * Stores a value in the cache.
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional)
+   */
   async put(key, value, ttl) {
     const filePath = this.getFilePath(key);
     const now = Date.now();
@@ -226,6 +347,10 @@ var FileCacheProvider = class {
     this.ensureCacheDirectory();
     await fs.writeFile(filePath, JSON.stringify(item), "utf-8");
   }
+  /**
+   * Deletes a value from the cache.
+   * @param key - The cache key to delete
+   */
   async delete(key) {
     const filePath = this.getFilePath(key);
     try {
@@ -233,10 +358,71 @@ var FileCacheProvider = class {
     } catch {
     }
   }
+  /**
+   * Checks if a key exists in the cache and has not expired.
+   * @param key - The cache key to check
+   * @returns True if the key exists and is not expired, false otherwise
+   */
   async has(key) {
     const value = await this.get(key);
     return value !== void 0;
   }
+  /**
+   * Increments a numeric value in the cache atomically using file-based locking.
+   * If the key doesn't exist or is expired, it starts from 0.
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The new value after incrementing
+   * @throws Error if lock cannot be acquired after maximum retries
+   */
+  async increment(key, amount = 1) {
+    const filePath = this.getFilePath(key);
+    const lockPath = `${filePath}.lock`;
+    let lockAcquired = false;
+    let retries = 0;
+    const maxRetries = 50;
+    while (!lockAcquired && retries < maxRetries) {
+      try {
+        await fs.writeFile(lockPath, "", { flag: "wx" });
+        lockAcquired = true;
+      } catch {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        retries++;
+      }
+    }
+    if (!lockAcquired) {
+      throw new Error("Failed to acquire lock for increment operation");
+    }
+    try {
+      let currentValue = 0;
+      let item;
+      try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const parsedItem = JSON.parse(content);
+        if (parsedItem.expiresAt && parsedItem.expiresAt < Date.now()) {
+          item = void 0;
+        } else {
+          item = parsedItem;
+          currentValue = typeof parsedItem.value === "number" ? parsedItem.value : 0;
+        }
+      } catch {
+      }
+      const newValue = currentValue + amount;
+      const now = Date.now();
+      const newItem = {
+        value: newValue,
+        createdAt: item?.createdAt ?? now,
+        expiresAt: item?.expiresAt
+      };
+      await fs.writeFile(filePath, JSON.stringify(newItem), "utf-8");
+      return newValue;
+    } finally {
+      try {
+        await fs.unlink(lockPath);
+      } catch {
+      }
+    }
+  }
 };
 
 // src/providers/MemoryCacheProvider.mts
@@ -252,10 +438,17 @@ var MemoryCacheProvider = class {
     // 10 minutes
   };
   cleanupTimer;
+  /**
+   * Creates a new MemoryCacheProvider instance.
+   * @param config - Configuration options for the cache
+   */
   constructor(config = {}) {
     this.config = { ...this.config, ...config };
     this.startCleanupTimer();
   }
+  /**
+   * Starts the automatic cleanup timer for expired entries.
+   */
   startCleanupTimer() {
     if (this.config.cleanupInterval > 0) {
       this.cleanupTimer = setInterval(() => {
@@ -263,12 +456,18 @@ var MemoryCacheProvider = class {
       }, this.config.cleanupInterval * 1e3);
     }
   }
+  /**
+   * Stops the automatic cleanup timer.
+   */
   stopCleanupTimer() {
     if (this.cleanupTimer) {
       clearInterval(this.cleanupTimer);
       this.cleanupTimer = void 0;
     }
   }
+  /**
+   * Removes all expired entries from the cache.
+   */
   cleanupExpiredEntries() {
     const now = Date.now();
     for (const [key, item] of this.cache.entries()) {
@@ -277,6 +476,9 @@ var MemoryCacheProvider = class {
       }
     }
   }
+  /**
+   * Evicts the least recently used item if cache size exceeds maximum.
+   */
   evictLRU() {
     if (this.cache.size <= this.config.maxSize) {
       return;
@@ -293,6 +495,11 @@ var MemoryCacheProvider = class {
       this.cache.delete(oldestKey);
     }
   }
+  /**
+   * Retrieves a value from the cache.
+   * @param key - The cache key
+   * @returns The cached value or undefined if not found or expired
+   */
   async get(key) {
     const item = this.cache.get(key);
     if (!item) {
@@ -305,6 +512,12 @@ var MemoryCacheProvider = class {
     item.lastAccessed = Date.now();
     return item.value;
   }
+  /**
+   * Stores a value in the cache.
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional)
+   */
   async put(key, value, ttl) {
     const now = Date.now();
     const effectiveTTL = ttl ?? this.config.defaultTTL;
@@ -317,9 +530,18 @@ var MemoryCacheProvider = class {
     this.cache.set(key, item);
     this.evictLRU();
   }
+  /**
+   * Deletes a value from the cache.
+   * @param key - The cache key to delete
+   */
   async delete(key) {
     this.cache.delete(key);
   }
+  /**
+   * Checks if a key exists in the cache and has not expired.
+   * @param key - The cache key to check
+   * @returns True if the key exists and is not expired, false otherwise
+   */
   async has(key) {
     const item = this.cache.get(key);
     if (!item) {
@@ -331,12 +553,44 @@ var MemoryCacheProvider = class {
     }
     return true;
   }
+  /**
+   * Increments a numeric value in the cache atomically.
+   * If the key doesn't exist or is expired, it starts from 0.
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The new value after incrementing
+   */
+  async increment(key, amount = 1) {
+    const item = this.cache.get(key);
+    const now = Date.now();
+    let currentValue = 0;
+    if (item) {
+      if (item.expiresAt && item.expiresAt < now) {
+        this.cache.delete(key);
+      } else {
+        currentValue = typeof item.value === "number" ? item.value : 0;
+      }
+    }
+    const newValue = currentValue + amount;
+    const newItem = {
+      value: newValue,
+      createdAt: item?.createdAt ?? now,
+      lastAccessed: now,
+      expiresAt: item?.expiresAt
+    };
+    this.cache.set(key, newItem);
+    return newValue;
+  }
 };
 
 // src/providers/MemcacheCacheProvider.mts
 var import_memcached = __toESM(require("memcached"), 1);
 var MemcacheCacheProvider = class {
   // default TTL in seconds
+  /**
+   * Creates a new MemcacheCacheProvider instance.
+   * @param config - Memcached configuration options
+   */
   constructor(config = {}) {
     this.config = config;
     this.client = new import_memcached.default(config.location || "localhost:11211", config.options || {});
@@ -346,6 +600,11 @@ var MemcacheCacheProvider = class {
   }
   client;
   defaultTTL = 3600;
+  /**
+   * Retrieves a value from the cache.
+   * @param key - The cache key
+   * @returns The cached value or undefined if not found
+   */
   async get(key) {
     return new Promise((resolve, reject) => {
       this.client.get(key, (err, data) => {
@@ -365,6 +624,12 @@ var MemcacheCacheProvider = class {
       });
     });
   }
+  /**
+   * Stores a value in the cache.
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds (optional)
+   */
   async put(key, value, ttl) {
     return new Promise((resolve, reject) => {
       const serializedValue = JSON.stringify(value);
@@ -378,6 +643,10 @@ var MemcacheCacheProvider = class {
       });
     });
   }
+  /**
+   * Deletes a value from the cache.
+   * @param key - The cache key to delete
+   */
   async delete(key) {
     return new Promise((resolve, reject) => {
       this.client.del(key, (err) => {
@@ -389,6 +658,11 @@ var MemcacheCacheProvider = class {
       });
     });
   }
+  /**
+   * Checks if a key exists in the cache.
+   * @param key - The cache key to check
+   * @returns True if the key exists, false otherwise
+   */
   async has(key) {
     return new Promise((resolve, reject) => {
       this.client.get(key, (err, data) => {
@@ -400,26 +674,87 @@ var MemcacheCacheProvider = class {
       });
     });
   }
+  /**
+   * Increments a numeric value in the cache atomically using Memcached's native increment.
+   * If the key doesn't exist, it is initialized with the increment amount.
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The new value after incrementing
+   */
+  async increment(key, amount = 1) {
+    return new Promise((resolve, reject) => {
+      this.client.incr(key, amount, (err, result) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        if (result === false) {
+          this.client.set(key, amount.toString(), this.defaultTTL, (setErr) => {
+            if (setErr) {
+              reject(setErr);
+              return;
+            }
+            resolve(amount);
+          });
+        } else {
+          resolve(result);
+        }
+      });
+    });
+  }
 };
 
 // src/providers/DisabledCacheProvider.mts
 var DisabledCacheProvider = class {
+  /**
+   * Creates a new DisabledCacheProvider instance.
+   * @param config - Configuration object (currently unused)
+   */
   constructor(config = {}) {
     this.config = config;
   }
   static {
     __name(this, "DisabledCacheProvider");
   }
+  /**
+   * Always returns undefined (no caching).
+   * @param key - The cache key
+   * @returns Always undefined
+   */
   async get(key) {
     return void 0;
   }
+  /**
+   * Does nothing (no caching).
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in seconds
+   */
   async put(key, value, ttl) {
   }
+  /**
+   * Does nothing (no caching).
+   * @param key - The cache key to delete
+   */
   async delete(key) {
   }
+  /**
+   * Always returns false (no caching).
+   * @param key - The cache key to check
+   * @returns Always false
+   */
   async has(key) {
     return false;
   }
+  /**
+   * Returns the increment amount as if starting from 0 (no caching).
+   * @param key - The cache key to increment
+   * @param amount - The amount to increment by (default: 1)
+   * @returns The increment amount
+   */
+  async increment(key, amount = 1) {
+    return amount;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {