@devbro/neko-cache 0.1.4 → 0.1.5

package/dist/CacheProviderInterface.d.mts

@@ -1,10 +1,40 @@
 import { JSONValue, JSONObject } from '@devbro/neko-helper';
 
+/**
+ * Interface that all cache providers must implement.
+ * Defines the contract for cache operations across different storage backends.
+ */
 interface CacheProviderInterface {
+    /**
+     * Retrieves a value from the cache.
+     * @param key - The cache key
+     * @returns The cached value or undefined if not found
+     */
     get(key: string): Promise<JSONValue | JSONObject | undefined>;
+    /**
+     * 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)
+     */
     put(key: string, value: JSONObject | JSONValue, ttl?: number): Promise<void>;
+    /**
+     * Deletes a value from the cache.
+     * @param key - The cache key to delete
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Checks if a key exists in the cache.
+     * @param key - The cache key to check
+     * @returns True if the key exists, false otherwise
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * 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
+     */
     increment(key: string, amount?: number): Promise<number>;
 }
 

package/dist/cache.d.mts

@@ -1,22 +1,72 @@
 import { JSONValue } from '@devbro/neko-helper';
 import { CacheProviderInterface } from './CacheProviderInterface.mjs';
 
+/**
+ * Options for cache operations.
+ */
 type cacheOptions = {
+    /** Time to live in seconds */
     ttl?: number;
 };
+/**
+ * Cache class providing a unified interface for various cache providers.
+ * Handles key generation, serialization, and common cache operations.
+ */
 declare class Cache {
     private provider;
+    /**
+     * Creates a new Cache instance.
+     * @param provider - The cache provider implementation to use
+     */
     constructor(provider: CacheProviderInterface);
+    /**
+     * 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
+     */
     get<T>(key: JSONValue): Promise<T | undefined>;
+    /**
+     * 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)
+     */
     put(key: JSONValue, value: any, ttl?: number): Promise<void>;
+    /**
+     * Deletes a value from the cache.
+     * @param key - The cache key to delete
+     */
     delete(key: JSONValue): Promise<void>;
+    /**
+     * 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
+     */
     has(key: JSONValue): Promise<boolean>;
+    /**
+     * 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
+     */
     increment(key: JSONValue, amount?: number): Promise<number>;
+    /**
+     * 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
+     */
     remember<T>(key: JSONValue, callback: () => Promise<T>, options?: cacheOptions): Promise<T>;
     /**
-     * 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: JSONValue): string;
 }

package/dist/cache.mjs

@@ -2,27 +2,67 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 import { createHash } from "crypto";
 class Cache {
+  /**
+   * 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);
@@ -34,9 +74,11 @@ class Cache {
     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) {

package/dist/cache.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cache.mts"],"sourcesContent":["import { JSONValue } from '@devbro/neko-helper';\nimport { CacheProviderInterface } from './CacheProviderInterface.mjs';\nimport { createHash } from 'crypto';\n\nexport type cacheOptions = {\n  ttl?: number;\n};\n\nexport class Cache {\n  constructor(private provider: CacheProviderInterface) {}\n\n  async get<T>(key: JSONValue): Promise<T | undefined> {\n    return this.provider.get(this.generateKey(key)) as Promise<T | undefined>;\n  }\n\n  async put(key: JSONValue, value: any, ttl?: number): Promise<void> {\n    return this.provider.put(this.generateKey(key), value, ttl);\n  }\n\n  async delete(key: JSONValue): Promise<void> {\n    return this.provider.delete(this.generateKey(key));\n  }\n\n  async has(key: JSONValue): Promise<boolean> {\n    return this.provider.has(this.generateKey(key));\n  }\n\n  async increment(key: JSONValue, amount: number = 1): Promise<number> {\n    return this.provider.increment(this.generateKey(key), amount);\n  }\n\n  async remember<T>(\n    key: JSONValue,\n    callback: () => Promise<T>,\n    options: cacheOptions = {}\n  ): Promise<T> {\n    options.ttl = options.ttl ?? 3600; // default TTL 1 hour\n\n    const cached = await this.get<T>(key);\n    if (cached) {\n      return cached;\n    }\n\n    const result = await callback();\n    await this.put(key, result, options.ttl);\n    return result;\n  }\n\n  /**\n   * Generates a cache key by serializing and concatenating the provided parts.\n   * @param parts\n   * @returns\n   */\n  generateKey(key: JSONValue): string {\n    if (typeof key === 'string' && key.length <= 250) {\n      return key;\n    }\n    return createHash('md5').update(JSON.stringify(key)).digest('hex');\n  }\n}\n"],"mappings":";;AAEA,SAAS,kBAAkB;AAMpB,MAAM,MAAM;AAAA,EACjB,YAAoB,UAAkC;AAAlC;AAAA,EAAmC;AAAA,EATzD,OAQmB;AAAA;AAAA;AAAA,EAGjB,MAAM,IAAO,KAAwC;AACnD,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,CAAC;AAAA,EAChD;AAAA,EAEA,MAAM,IAAI,KAAgB,OAAY,KAA6B;AACjE,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,GAAG,OAAO,GAAG;AAAA,EAC5D;AAAA,EAEA,MAAM,OAAO,KAA+B;AAC1C,WAAO,KAAK,SAAS,OAAO,KAAK,YAAY,GAAG,CAAC;AAAA,EACnD;AAAA,EAEA,MAAM,IAAI,KAAkC;AAC1C,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,CAAC;AAAA,EAChD;AAAA,EAEA,MAAM,UAAU,KAAgB,SAAiB,GAAoB;AACnE,WAAO,KAAK,SAAS,UAAU,KAAK,YAAY,GAAG,GAAG,MAAM;AAAA,EAC9D;AAAA,EAEA,MAAM,SACJ,KACA,UACA,UAAwB,CAAC,GACb;AACZ,YAAQ,MAAM,QAAQ,OAAO;AAE7B,UAAM,SAAS,MAAM,KAAK,IAAO,GAAG;AACpC,QAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAEA,UAAM,SAAS,MAAM,SAAS;AAC9B,UAAM,KAAK,IAAI,KAAK,QAAQ,QAAQ,GAAG;AACvC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,YAAY,KAAwB;AAClC,QAAI,OAAO,QAAQ,YAAY,IAAI,UAAU,KAAK;AAChD,aAAO;AAAA,IACT;AACA,WAAO,WAAW,KAAK,EAAE,OAAO,KAAK,UAAU,GAAG,CAAC,EAAE,OAAO,KAAK;AAAA,EACnE;AACF;","names":[]}
+{"version":3,"sources":["../src/cache.mts"],"sourcesContent":["import { JSONValue } from '@devbro/neko-helper';\nimport { CacheProviderInterface } from './CacheProviderInterface.mjs';\nimport { createHash } from 'crypto';\n\n/**\n * Options for cache operations.\n */\nexport type cacheOptions = {\n  /** Time to live in seconds */\n  ttl?: number;\n};\n\n/**\n * Cache class providing a unified interface for various cache providers.\n * Handles key generation, serialization, and common cache operations.\n */\nexport class Cache {\n  /**\n   * Creates a new Cache instance.\n   * @param provider - The cache provider implementation to use\n   */\n  constructor(private provider: CacheProviderInterface) {}\n\n  /**\n   * Retrieves a value from the cache.\n   * @template T - The expected type of the cached value\n   * @param key - The cache key (can be string, number, object, or array)\n   * @returns The cached value or undefined if not found or expired\n   */\n  async get<T>(key: JSONValue): Promise<T | undefined> {\n    return this.provider.get(this.generateKey(key)) as Promise<T | undefined>;\n  }\n\n  /**\n   * Stores a value in the cache.\n   * @param key - The cache key (can be string, number, object, or array)\n   * @param value - The value to cache\n   * @param ttl - Time to live in seconds (optional)\n   */\n  async put(key: JSONValue, value: any, ttl?: number): Promise<void> {\n    return this.provider.put(this.generateKey(key), value, ttl);\n  }\n\n  /**\n   * Deletes a value from the cache.\n   * @param key - The cache key to delete\n   */\n  async delete(key: JSONValue): Promise<void> {\n    return this.provider.delete(this.generateKey(key));\n  }\n\n  /**\n   * Checks if a key exists in the cache.\n   * @param key - The cache key to check\n   * @returns True if the key exists and has not expired, false otherwise\n   */\n  async has(key: JSONValue): Promise<boolean> {\n    return this.provider.has(this.generateKey(key));\n  }\n\n  /**\n   * Increments a numeric value in the cache atomically.\n   * @param key - The cache key to increment\n   * @param amount - The amount to increment by (default: 1)\n   * @returns The new value after incrementing\n   */\n  async increment(key: JSONValue, amount: number = 1): Promise<number> {\n    return this.provider.increment(this.generateKey(key), amount);\n  }\n\n  /**\n   * Gets a value from cache or executes callback and caches the result.\n   * This is useful for caching expensive operations.\n   * @template T - The expected type of the value\n   * @param key - The cache key\n   * @param callback - Function to execute if cache miss occurs\n   * @param options - Cache options including TTL (default: 3600 seconds)\n   * @returns The cached value or the result of the callback\n   */\n  async remember<T>(\n    key: JSONValue,\n    callback: () => Promise<T>,\n    options: cacheOptions = {}\n  ): Promise<T> {\n    options.ttl = options.ttl ?? 3600; // default TTL 1 hour\n\n    const cached = await this.get<T>(key);\n    if (cached) {\n      return cached;\n    }\n\n    const result = await callback();\n    await this.put(key, result, options.ttl);\n    return result;\n  }\n\n  /**\n   * Generates a cache key by serializing and hashing complex keys.\n   * Simple string keys under 250 characters are returned as-is.\n   * Complex keys (objects, arrays, long strings) are MD5 hashed.\n   * @param key - The key to generate a cache key from\n   * @returns A string suitable for use as a cache key\n   */\n  generateKey(key: JSONValue): string {\n    if (typeof key === 'string' && key.length <= 250) {\n      return key;\n    }\n    return createHash('md5').update(JSON.stringify(key)).digest('hex');\n  }\n}\n"],"mappings":";;AAEA,SAAS,kBAAkB;AAcpB,MAAM,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA,EAKjB,YAAoB,UAAkC;AAAlC;AAAA,EAAmC;AAAA,EArBzD,OAgBmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAajB,MAAM,IAAO,KAAwC;AACnD,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,CAAC;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,IAAI,KAAgB,OAAY,KAA6B;AACjE,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,GAAG,OAAO,GAAG;AAAA,EAC5D;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,OAAO,KAA+B;AAC1C,WAAO,KAAK,SAAS,OAAO,KAAK,YAAY,GAAG,CAAC;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,IAAI,KAAkC;AAC1C,WAAO,KAAK,SAAS,IAAI,KAAK,YAAY,GAAG,CAAC;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,UAAU,KAAgB,SAAiB,GAAoB;AACnE,WAAO,KAAK,SAAS,UAAU,KAAK,YAAY,GAAG,GAAG,MAAM;AAAA,EAC9D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,SACJ,KACA,UACA,UAAwB,CAAC,GACb;AACZ,YAAQ,MAAM,QAAQ,OAAO;AAE7B,UAAM,SAAS,MAAM,KAAK,IAAO,GAAG;AACpC,QAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAEA,UAAM,SAAS,MAAM,SAAS;AAC9B,UAAM,KAAK,IAAI,KAAK,QAAQ,QAAQ,GAAG;AACvC,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAAY,KAAwB;AAClC,QAAI,OAAO,QAAQ,YAAY,IAAI,UAAU,KAAK;AAChD,aAAO;AAAA,IACT;AACA,WAAO,WAAW,KAAK,EAAE,OAAO,KAAK,UAAU,GAAG,CAAC,EAAE,OAAO,KAAK;AAAA,EACnE;AACF;","names":[]}