@63klabs/cache-data 1.3.5 → 1.3.7

package/src/lib/tools/utils.js

@@ -11,6 +11,35 @@ const printMsg = function() {
 	console.log("This is a message from the demo package");
 };
 
+/**
+ * Safely clones an object, handling Promises and other non-cloneable values.
+ * If the object contains Promises, they will be converted to empty objects.
+ * Falls back to JSON.parse(JSON.stringify()) if structuredClone fails.
+ * 
+ * @param {*} obj - The object to clone
+ * @returns {*} A deep clone of the object
+ */
+const safeClone = function(obj) {
+	if (obj === null || typeof obj !== 'object') {
+		return obj;
+	}
+
+	try {
+		// Try structuredClone first (fastest for most cases)
+		return structuredClone(obj);
+	} catch (e) {
+		// If structuredClone fails (e.g., due to Promises), fall back to JSON pattern
+		// This will convert Promises to empty objects, but won't throw
+		try {
+			return JSON.parse(JSON.stringify(obj));
+		} catch (jsonError) {
+			// If even JSON fails, return the original object
+			// This handles circular references and other edge cases
+			return obj;
+		}
+	}
+};
+
 /**
  * Given a secret string, returns a string padded out at the beginning
  * with * or passed character leaving only the specified number of characters unobfuscated.
@@ -227,6 +256,9 @@ const sanitize = function (obj) {
  */
 const hashThisData = function(algorithm, data, options = {}) {
 
+	// Clone options to avoid modifying the original
+	options = safeClone(options);
+	
 	// set default values for options
 	if ( !( "salt" in options) ) { options.salt = ""; }
 	if ( !( "iterations" in options) || options.iterations < 1 ) { options.iterations = 1; }
@@ -234,7 +266,8 @@ const hashThisData = function(algorithm, data, options = {}) {
 
 	// if it is an object or array, then parse it to remove non-data elements (functions, etc)
 	if ( !options.skipParse && (typeof data === "object" || Array.isArray(data))) {
-		data = JSON.parse(JSON.stringify(data, (key, value) => {
+		// Normalize the data structure first using JSON.stringify with custom replacer
+		const normalized = JSON.parse(JSON.stringify(data, (key, value) => {
 			switch (typeof value) {
 				case 'bigint':
 					return value.toString();
@@ -244,6 +277,8 @@ const hashThisData = function(algorithm, data, options = {}) {
 					return value;
 			}
 		}));
+		// Then clone for safety
+		data = safeClone(normalized);
 		options.skipParse = true; // set to true so we don't parse during recursion
 	}
 
@@ -272,7 +307,7 @@ const hashThisData = function(algorithm, data, options = {}) {
 		// iterate through the keys alphabetically and add the key and value to the arrayOfStuff
 		keys.forEach((key) => {
 			// clone options
-			const opts = JSON.parse(JSON.stringify(options));
+			const opts = safeClone(options);
 			opts.iterations = 1; // don't iterate during recursion, only at end
 
 			const value = hashThisData(algorithm, data[key], opts);
@@ -285,11 +320,11 @@ const hashThisData = function(algorithm, data, options = {}) {
 		valueStr = `-:::${dataType}:::${data.toString()}`;
 	}
 
-	const hash = crypto.createHash(algorithm);
 	let hashOfData = "";
 
 	// hash for the number of iterations
 	for (let i = 0; i < options.iterations; i++) {
+		const hash = crypto.createHash(algorithm);
 		hash.update(valueStr + hashOfData + options.salt);
 		hashOfData = hash.digest('hex');
 	}
@@ -301,5 +336,6 @@ module.exports = {
 	printMsg,
 	sanitize,
 	obfuscate,
-	hashThisData
+	hashThisData,
+	safeClone
 };

package/src/lib/utils/InMemoryCache.js

@@ -0,0 +1,221 @@
+/**
+ * InMemoryCache - Ultra-fast in-memory L0 cache for AWS Lambda
+ * 
+ * Provides microsecond-level cache access using JavaScript Map with LRU eviction.
+ * Designed for Lambda execution model with synchronous operations and no background processes.
+ * @example
+ * // Create cache with automatic sizing based on Lambda memory
+ * const cache = new InMemoryCache();
+ * 
+ * // Store data with expiration
+ * const data = { user: 'john', email: 'john@example.com' };
+ * const expiresAt = Date.now() + (5 * 60 * 1000); // 5 minutes
+ * cache.set('user:123', data, expiresAt);
+ * 
+ * // Retrieve data
+ * const result = cache.get('user:123');
+ * if (result.cache === 1) {
+ *   console.log('Cache hit:', result.data);
+ * }
+ * 
+ * @example
+ * // Create cache with explicit max entries
+ * const cache = new InMemoryCache({ maxEntries: 10000 });
+ * 
+ * // Check cache info
+ * const info = cache.info();
+ * console.log(`Cache size: ${info.size}/${info.maxEntries}`);
+ * console.log(`Memory: ${info.memoryMB}MB`);
+ * 
+ * @example
+ * // Use with Cache.init() for in-memory caching
+ * Cache.init({
+ *   useInMemoryCache: true,
+ *   inMemoryCacheMaxEntries: 5000
+ * });
+ * 
+ * // Cache automatically uses InMemoryCache as L0 cache
+ * const cacheInstance = new Cache(connection, profile);
+ * const data = await cacheInstance.read(); // Checks in-memory first
+ * 
+ * @example
+ * // Clear cache when needed
+ * cache.clear();
+ * console.log('Cache cleared');
+ */
+
+class InMemoryCache {
+  #cache;
+  #maxEntries;
+  #memoryMB;
+
+  /**
+   * Creates a new InMemoryCache instance
+   * 
+   * @param {Object} options - Configuration options
+   * @param {number} [options.maxEntries] - Maximum number of entries (overrides calculation)
+   * @param {number} [options.entriesPerGB=5000] - Heuristic for calculating maxEntries from memory
+   * @param {number} [options.defaultMaxEntries=1000] - Fallback if Lambda memory unavailable
+   */
+  constructor(options = {}) {
+    const {
+      maxEntries,
+      entriesPerGB = 5000,
+      defaultMaxEntries = 1000
+    } = options;
+
+    // Initialize Map storage
+    this.#cache = new Map();
+
+    // Determine MAX_ENTRIES
+    if (maxEntries !== undefined && maxEntries !== null) {
+      // Use explicit maxEntries parameter
+      this.#maxEntries = maxEntries;
+      this.#memoryMB = null;
+    } else {
+      // Calculate from Lambda memory allocation
+      const lambdaMemory = process.env.AWS_LAMBDA_FUNCTION_MEMORY_SIZE;
+      
+      if (lambdaMemory !== undefined && lambdaMemory !== null) {
+        this.#memoryMB = parseInt(lambdaMemory, 10);
+        
+        if (!isNaN(this.#memoryMB) && this.#memoryMB > 0) {
+          // Calculate: (memoryMB / 1024) * entriesPerGB
+          this.#maxEntries = Math.floor((this.#memoryMB / 1024) * entriesPerGB);
+        } else {
+          // Invalid memory value, use default
+          this.#maxEntries = defaultMaxEntries;
+          this.#memoryMB = null;
+        }
+      } else {
+        // Lambda memory not available, use default
+        this.#maxEntries = defaultMaxEntries;
+        this.#memoryMB = null;
+      }
+    }
+
+    // Ensure maxEntries is at least 1
+    if (this.#maxEntries < 1) {
+      this.#maxEntries = 1;
+    }
+  }
+
+  /**
+   * Retrieves a cache entry by key
+   * 
+   * Returns an object containing the cache status and the cached data (if available).
+   * The cache status indicates whether the lookup was a hit (1), miss (0), or expired (-1).
+   * For cache hits, the data property contains the stored CacheDataFormat object. For misses, data is null.
+   * For expired entries, data contains the expired CacheDataFormat object before it's removed from cache.
+   * 
+   * @param {string} key - Cache key to look up
+   * @returns {{cache: number, data: Object|null}} Lookup result with cache status and data
+   * @returns {number} return.cache - Cache status: 1 (hit), 0 (miss), or -1 (expired)
+   * @returns {Object|null} return.data - The cached CacheDataFormat object on hit/expired, or null on miss
+   * 
+   * @example
+   * // Cache hit
+   * cache.get('myKey') 
+   * // => { cache: 1, data: { cache: { body: '...', headers: {...}, expires: 1234567890, statusCode: '200' } } }
+   * 
+   * @example
+   * // Cache miss
+   * cache.get('nonExistent') // => { cache: 0, data: null }
+   * 
+   * @example
+   * // Expired entry
+   * cache.get('expiredKey') 
+   * // => { cache: -1, data: { cache: { body: '...', headers: {...}, expires: 1234567890, statusCode: '200' } } }
+   */
+  get(key) {
+    // Check if key exists
+    if (!this.#cache.has(key)) {
+      return { cache: 0, data: null };
+    }
+
+    const entry = this.#cache.get(key);
+    const now = Date.now();
+
+    // Check if expired
+    if (entry.expiresAt <= now) {
+      // Delete expired entry
+      this.#cache.delete(key);
+      return { cache: -1, data: entry.value };
+    }
+
+    // Valid entry - update LRU position by deleting and re-setting
+    this.#cache.delete(key);
+    this.#cache.set(key, entry);
+
+    return { cache: 1, data: entry.value };
+  }
+
+  /**
+   * Stores a cache entry with expiration
+   * 
+   * Adds or updates a cache entry with the specified key, value, and expiration time.
+   * If the key already exists, it will be updated and moved to the most recent position (LRU).
+   * If the cache is at maximum capacity, the least recently used entry will be evicted automatically.
+   * The expiresAt timestamp should be in milliseconds since epoch (e.g., Date.now() + ttl).
+   * 
+   * @param {string} key - Cache key to store the value under
+   * @param {Object} value - CacheDataFormat object or any data structure to cache
+   * @param {number} expiresAt - Expiration timestamp in milliseconds since epoch (e.g., Date.now() + 60000 for 1 minute)
+   * @returns {void}
+   * 
+   * @example
+   * // Store a cache entry that expires in 5 minutes
+   * const fiveMinutes = 5 * 60 * 1000;
+   * cache.set('myKey', { cache: { body: 'response data', headers: {}, expires: Date.now() + fiveMinutes, statusCode: '200' } }, Date.now() + fiveMinutes);
+   * 
+   * @example
+   * // Store with a specific expiration timestamp
+   * const expirationTime = Date.now() + (60 * 60 * 1000); // 1 hour from now
+   * cache.set('sessionData', { userId: 123, token: 'abc' }, expirationTime);
+   * 
+   * @example
+   * // Update an existing entry (moves to most recent position)
+   * cache.set('existingKey', { updated: 'data' }, Date.now() + 300000);
+   */
+  set(key, value, expiresAt) {
+    // If key exists, delete it first for LRU repositioning
+    if (this.#cache.has(key)) {
+      this.#cache.delete(key);
+    }
+
+    // Check capacity and evict if necessary
+    if (this.#cache.size >= this.#maxEntries) {
+      // Get first (oldest) entry
+      const oldestKey = this.#cache.keys().next().value;
+      this.#cache.delete(oldestKey);
+    }
+
+    // Store new entry
+    this.#cache.set(key, { value, expiresAt });
+  }
+
+  /**
+   * Clears all entries from the cache
+   */
+  clear() {
+    this.#cache.clear();
+  }
+
+  /**
+   * Returns information about the cache state
+   * 
+   * @returns {Object} Cache information
+   * @returns {number} return.size - Current number of entries
+   * @returns {number} return.maxEntries - Maximum capacity
+   * @returns {number|null} return.memoryMB - Lambda memory allocation (if available)
+   */
+  info() {
+    return {
+      size: this.#cache.size,
+      maxEntries: this.#maxEntries,
+      memoryMB: this.#memoryMB
+    };
+  }
+}
+
+module.exports = InMemoryCache;