@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/memo/async.js

@@ -1,120 +1,136 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var async_exports = {};
-__export(async_exports, {
-  memoizeAsync: () => memoizeAsync
-});
-module.exports = __toCommonJS(async_exports);
-var import_output = require("../debug/output");
-var import_date = require("../primordials/date");
-var import_map_set = require("../primordials/map-set");
-var import_promise = require("../primordials/promise");
-var import_internal = require("./_internal");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_map_set = require('../primordials/map-set.js');
+const require_primordials_date = require('../primordials/date.js');
+const require_primordials_promise = require('../primordials/promise.js');
+const require_debug_output = require('../debug/output.js');
+const require_memo__internal = require('./_internal.js');
+
+//#region src/memo/async.ts
+/**
+* @file `memoizeAsync` — async-aware memoizer with the same LRU+TTL contract as
+*   `memoize`, plus thundering-herd dedup. Concurrent callers join an in-flight
+*   promise instead of starting fresh fetches, and the cache timestamp is
+*   refreshed on resolution so a slow fn can't land a value that's already
+*   "expired".
+*/
+/**
+* Memoize an async function. Similar to memoize() but handles promises
+* properly.
+*
+* @example
+*   import { memoizeAsync } from '@socketsecurity/lib/memo/async'
+*
+*   const fetchUser = memoizeAsync(
+*     async (id: string) => {
+*       const response = await fetch(`/api/users/${id}`)
+*       return response.json()
+*     },
+*     { ttl: 300000, name: 'fetchUser' },
+*   )
+*
+*   await fetchUser('123') // Fetches from API
+*   await fetchUser('123') // Returns cached result
+*
+* @param fn - Async function to memoize.
+* @param options - Memoization options.
+*
+* @returns Memoized version of the async function
+*/
 function memoizeAsync(fn, options = {}) {
-  const {
-    keyGen = (...args) => (0, import_internal.defaultKeyGen)(args),
-    maxSize = Number.POSITIVE_INFINITY,
-    name = fn.name || "anonymous",
-    ttl = Number.POSITIVE_INFINITY
-  } = options;
-  const cache = new import_map_set.MapCtor();
-  import_internal.cacheRegistry.push(() => {
-    cache.clear();
-  });
-  function evictLRU() {
-    if (cache.size >= maxSize) {
-      const oldest = cache.keys().next().value;
-      if (oldest !== void 0) {
-        cache.delete(oldest);
-        (0, import_output.debugLog)(`[memoizeAsync:${name}] clear`, {
-          key: oldest,
-          reason: "LRU"
-        });
-      }
-    }
-  }
-  function isExpired(entry) {
-    if (ttl === Number.POSITIVE_INFINITY) {
-      return false;
-    }
-    return (0, import_date.DateNow)() - entry.timestamp > ttl;
-  }
-  function bumpRecency(key, entry) {
-    cache.delete(key);
-    cache.set(key, entry);
-  }
-  const refreshing = new import_map_set.MapCtor();
-  return async function memoized(...args) {
-    const key = keyGen(...args);
-    const cached = cache.get(key);
-    if (cached) {
-      if (!isExpired(cached)) {
-        cached.hits++;
-        bumpRecency(key, cached);
-        (0, import_output.debugLog)(`[memoizeAsync:${name}] hit`, { key, hits: cached.hits });
-        return await cached.value;
-      }
-      const inflight = refreshing.get(key);
-      if (inflight) {
-        (0, import_output.debugLog)(`[memoizeAsync:${name}] stale-dedup`, { key });
-        bumpRecency(key, cached);
-        return await inflight;
-      }
-      cache.delete(key);
-    }
-    const inflightCold = refreshing.get(key);
-    if (inflightCold) {
-      (0, import_output.debugLog)(`[memoizeAsync:${name}] cold-dedup`, { key });
-      return await inflightCold;
-    }
-    (0, import_output.debugLog)(`[memoizeAsync:${name}] miss`, { key });
-    const promise = (async () => {
-      try {
-        const result = await fn(...args);
-        refreshing.delete(key);
-        const entry = cache.get(key);
-        if (entry) {
-          entry.value = (0, import_promise.PromiseResolve)(result);
-          entry.timestamp = (0, import_date.DateNow)();
-        }
-        return result;
-      } catch (error) {
-        refreshing.delete(key);
-        cache.delete(key);
-        (0, import_output.debugLog)(`[memoizeAsync:${name}] error`, { key, error });
-        throw error;
-      }
-    })();
-    refreshing.set(key, promise);
-    evictLRU();
-    cache.set(key, {
-      value: promise,
-      timestamp: Date.now(),
-      hits: 0
-    });
-    (0, import_output.debugLog)(`[memoizeAsync:${name}] set`, { key, cacheSize: cache.size });
-    return await promise;
-  };
+	const { keyGen = (...args) => require_memo__internal.defaultKeyGen(args), maxSize = Number.POSITIVE_INFINITY, name = fn.name || "anonymous", ttl = Number.POSITIVE_INFINITY } = options;
+	const cache = new require_primordials_map_set.MapCtor();
+	require_memo__internal.cacheRegistry.push(() => {
+		cache.clear();
+	});
+	function evictLRU() {
+		if (cache.size >= maxSize) {
+			const oldest = cache.keys().next().value;
+			/* c8 ignore next 8 - cache.size >= maxSize guarantees keys().next()
+			yields a defined value; the undefined branch is defensive. */
+			if (oldest !== void 0) {
+				cache.delete(oldest);
+				require_debug_output.debugLog(`[memoizeAsync:${name}] clear`, {
+					key: oldest,
+					reason: "LRU"
+				});
+			}
+		}
+	}
+	function isExpired(entry) {
+		/* c8 ignore next 3 */
+		if (ttl === Number.POSITIVE_INFINITY) return false;
+		return require_primordials_date.DateNow() - entry.timestamp > ttl;
+	}
+	function bumpRecency(key, entry) {
+		cache.delete(key);
+		cache.set(key, entry);
+	}
+	const refreshing = new require_primordials_map_set.MapCtor();
+	return async function memoized(...args) {
+		const key = keyGen(...args);
+		const cached = cache.get(key);
+		/* c8 ignore start */
+		if (cached) {
+			if (!isExpired(cached)) {
+				cached.hits++;
+				bumpRecency(key, cached);
+				require_debug_output.debugLog(`[memoizeAsync:${name}] hit`, {
+					key,
+					hits: cached.hits
+				});
+				return await cached.value;
+			}
+			const inflight = refreshing.get(key);
+			if (inflight) {
+				require_debug_output.debugLog(`[memoizeAsync:${name}] stale-dedup`, { key });
+				bumpRecency(key, cached);
+				return await inflight;
+			}
+			cache.delete(key);
+		}
+		const inflightCold = refreshing.get(key);
+		if (inflightCold) {
+			require_debug_output.debugLog(`[memoizeAsync:${name}] cold-dedup`, { key });
+			return await inflightCold;
+		}
+		/* c8 ignore stop */
+		require_debug_output.debugLog(`[memoizeAsync:${name}] miss`, { key });
+		const promise = (async () => {
+			try {
+				const result = await fn(...args);
+				refreshing.delete(key);
+				const entry = cache.get(key);
+				if (entry) {
+					entry.value = require_primordials_promise.PromiseResolve(result);
+					entry.timestamp = require_primordials_date.DateNow();
+				}
+				return result;
+			} catch (error) {
+				refreshing.delete(key);
+				cache.delete(key);
+				require_debug_output.debugLog(`[memoizeAsync:${name}] error`, {
+					key,
+					error
+				});
+				throw error;
+			}
+		})();
+		refreshing.set(key, promise);
+		evictLRU();
+		cache.set(key, {
+			value: promise,
+			timestamp: Date.now(),
+			hits: 0
+		});
+		require_debug_output.debugLog(`[memoizeAsync:${name}] set`, {
+			key,
+			cacheSize: cache.size
+		});
+		return await promise;
+	};
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  memoizeAsync
-});
+
+//#endregion
+exports.memoizeAsync = memoizeAsync;

package/dist/memo/clear.js

@@ -1,37 +1,28 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var clear_exports = {};
-__export(clear_exports, {
-  clearAllMemoizationCaches: () => clearAllMemoizationCaches
-});
-module.exports = __toCommonJS(clear_exports);
-var import_output = require("../debug/output");
-var import_internal = require("./_internal");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_debug_output = require('../debug/output.js');
+const require_memo__internal = require('./_internal.js');
+
+//#region src/memo/clear.ts
+/**
+* @file `clearAllMemoizationCaches` — fan out to every per-cache clear function
+*   registered in `_internal.cacheRegistry`. Useful for tests and for callers
+*   that need to force recomputation across every memoize instance.
+*/
+/**
+* Clear all memoization caches. Useful for testing or when you need to force
+* recomputation.
+*
+* @example
+*   ;```typescript
+*   clearAllMemoizationCaches()
+*   ```
+*/
 function clearAllMemoizationCaches() {
-  (0, import_output.debugLog)("[memoize:all] clear", { action: "clear-all-caches" });
-  for (const clear of import_internal.cacheRegistry) {
-    clear();
-  }
+	require_debug_output.debugLog("[memoize:all] clear", { action: "clear-all-caches" });
+	for (const clear of require_memo__internal.cacheRegistry) clear();
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  clearAllMemoizationCaches
-});
+
+//#endregion
+exports.clearAllMemoizationCaches = clearAllMemoizationCaches;

package/dist/memo/decorator.js

@@ -1,40 +1,46 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var decorator_exports = {};
-__export(decorator_exports, {
-  Memoize: () => Memoize
-});
-module.exports = __toCommonJS(decorator_exports);
-var import_memoize = require("./memoize");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_memo_memoize = require('./memoize.js');
+
+//#region src/memo/decorator.ts
+/**
+* @file `Memoize` — class-method decorator that wraps the decorated method via
+*   `memoize`. Preserves `this`-context by installing the wrapper on the
+*   property descriptor. Defaults the cache `name` option to the property key
+*   for nicer debug output.
+*/
+/**
+* Create a memoized version of a method. Preserves 'this' context for class
+* methods.
+*
+* @example
+*   import { Memoize } from '@socketsecurity/lib/memo/decorator'
+*
+*   class Calculator {
+*     @Memoize()
+*     fibonacci(n: number): number {
+*       if (n <= 1) return n
+*       return this.fibonacci(n - 1) + this.fibonacci(n - 2)
+*     }
+*   }
+*
+* @param target - Object containing the method.
+* @param propertyKey - Method name.
+* @param descriptor - Property descriptor.
+*
+* @returns Modified descriptor with memoized method
+*/
 function Memoize(options = {}) {
-  return (_target, propertyKey, descriptor) => {
-    const originalMethod = descriptor.value;
-    descriptor.value = (0, import_memoize.memoize)(originalMethod, {
-      ...options,
-      name: options.name || propertyKey
-    });
-    return descriptor;
-  };
+	return (_target, propertyKey, descriptor) => {
+		const originalMethod = descriptor.value;
+		descriptor.value = require_memo_memoize.memoize(originalMethod, {
+			...options,
+			name: options.name || propertyKey
+		});
+		return descriptor;
+	};
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Memoize
-});
+
+//#endregion
+exports.Memoize = Memoize;

package/dist/memo/memoize.js

@@ -1,91 +1,100 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var memoize_exports = {};
-__export(memoize_exports, {
-  memoize: () => memoize
-});
-module.exports = __toCommonJS(memoize_exports);
-var import_output = require("../debug/output");
-var import_date = require("../primordials/date");
-var import_error = require("../primordials/error");
-var import_map_set = require("../primordials/map-set");
-var import_internal = require("./_internal");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_error = require('../primordials/error.js');
+const require_primordials_map_set = require('../primordials/map-set.js');
+const require_primordials_date = require('../primordials/date.js');
+const require_debug_output = require('../debug/output.js');
+const require_memo__internal = require('./_internal.js');
+
+//#region src/memo/memoize.ts
+/**
+* @file `memoize` — synchronous function memoizer with LRU eviction (Map
+*   insertion-order based), optional TTL, and optional custom key generator.
+*   Each instance registers itself with the shared `cacheRegistry` so
+*   `clearAllMemoizationCaches` can sweep it.
+*/
+/**
+* Memoize a function with configurable caching behavior. Caches function
+* results to avoid repeated computation.
+*
+* @example
+*   import { memoize } from '@socketsecurity/lib/memo/memoize'
+*
+*   const expensiveOperation = memoize(
+*     (n: number) => {
+*       // Heavy computation
+*       return Array(n)
+*         .fill(0)
+*         .reduce((a, _, i) => a + i, 0)
+*     },
+*     { maxSize: 100, ttl: 60000, name: 'sum' },
+*   )
+*
+*   expensiveOperation(1000) // Computed
+*   expensiveOperation(1000) // Cached
+*
+* @param fn - Function to memoize.
+* @param options - Memoization options.
+*
+* @returns Memoized version of the function
+*/
 function memoize(fn, options = {}) {
-  const {
-    keyGen = (...args) => (0, import_internal.defaultKeyGen)(args),
-    maxSize = Number.POSITIVE_INFINITY,
-    name = fn.name || "anonymous",
-    ttl = Number.POSITIVE_INFINITY
-  } = options;
-  if (ttl < 0) {
-    throw new import_error.TypeErrorCtor("TTL must be non-negative");
-  }
-  const cache = new import_map_set.MapCtor();
-  import_internal.cacheRegistry.push(() => {
-    cache.clear();
-  });
-  function evictLRU() {
-    if (cache.size >= maxSize) {
-      const oldest = cache.keys().next().value;
-      if (oldest !== void 0) {
-        cache.delete(oldest);
-        (0, import_output.debugLog)(`[memoize:${name}] clear`, {
-          key: oldest,
-          reason: "LRU"
-        });
-      }
-    }
-  }
-  function isExpired(entry) {
-    if (ttl === Number.POSITIVE_INFINITY) {
-      return false;
-    }
-    return (0, import_date.DateNow)() - entry.timestamp > ttl;
-  }
-  return function memoized(...args) {
-    const key = keyGen(...args);
-    const cached = cache.get(key);
-    if (cached) {
-      if (!isExpired(cached)) {
-        cached.hits++;
-        cache.delete(key);
-        cache.set(key, cached);
-        (0, import_output.debugLog)(`[memoize:${name}] hit`, { key, hits: cached.hits });
-        return cached.value;
-      }
-      cache.delete(key);
-    }
-    (0, import_output.debugLog)(`[memoize:${name}] miss`, { key });
-    const value = fn(...args);
-    evictLRU();
-    cache.set(key, {
-      value,
-      timestamp: Date.now(),
-      hits: 0
-    });
-    (0, import_output.debugLog)(`[memoize:${name}] set`, { key, cacheSize: cache.size });
-    return value;
-  };
+	const { keyGen = (...args) => require_memo__internal.defaultKeyGen(args), maxSize = Number.POSITIVE_INFINITY, name = fn.name || "anonymous", ttl = Number.POSITIVE_INFINITY } = options;
+	if (ttl < 0) throw new require_primordials_error.TypeErrorCtor("TTL must be non-negative");
+	const cache = new require_primordials_map_set.MapCtor();
+	require_memo__internal.cacheRegistry.push(() => {
+		cache.clear();
+	});
+	function evictLRU() {
+		if (cache.size >= maxSize) {
+			const oldest = cache.keys().next().value;
+			/* c8 ignore next 8 - cache.size >= maxSize guarantees keys().next()
+			yields a defined value; the undefined branch is defensive. */
+			if (oldest !== void 0) {
+				cache.delete(oldest);
+				require_debug_output.debugLog(`[memoize:${name}] clear`, {
+					key: oldest,
+					reason: "LRU"
+				});
+			}
+		}
+	}
+	function isExpired(entry) {
+		if (ttl === Number.POSITIVE_INFINITY) return false;
+		return require_primordials_date.DateNow() - entry.timestamp > ttl;
+	}
+	return function memoized(...args) {
+		const key = keyGen(...args);
+		const cached = cache.get(key);
+		if (cached) {
+			if (!isExpired(cached)) {
+				cached.hits++;
+				cache.delete(key);
+				cache.set(key, cached);
+				require_debug_output.debugLog(`[memoize:${name}] hit`, {
+					key,
+					hits: cached.hits
+				});
+				return cached.value;
+			}
+			cache.delete(key);
+		}
+		require_debug_output.debugLog(`[memoize:${name}] miss`, { key });
+		const value = fn(...args);
+		evictLRU();
+		cache.set(key, {
+			value,
+			timestamp: Date.now(),
+			hits: 0
+		});
+		require_debug_output.debugLog(`[memoize:${name}] set`, {
+			key,
+			cacheSize: cache.size
+		});
+		return value;
+	};
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  memoize
-});
+
+//#endregion
+exports.memoize = memoize;