@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/memoization.d.ts

@@ -1,131 +0,0 @@
-/**
- * @fileoverview Memoization utilities for caching function results.
- * Provides function result caching to optimize repeated computations and expensive operations.
- */
-/**
- * Options for memoization behavior.
- */
-export type MemoizeOptions<Args extends unknown[]> = {
-    /** Custom cache key generator (defaults to JSON.stringify) */
-    keyGen?: (...args: Args) => string;
-    /** Maximum cache size (LRU eviction when exceeded) */
-    maxSize?: number;
-    /** TTL in milliseconds (cache entries expire after this time) */
-    ttl?: number;
-    /** Cache name for debugging */
-    name?: string;
-    /** Weak cache for object keys (enables GC) */
-    weak?: boolean;
-    /** Custom equality check for cache hits */
-    equals?: (a: Args, b: Args) => boolean;
-};
-/**
- * Clear all memoization caches.
- * Useful for testing or when you need to force recomputation.
- *
- * @example
- * ```typescript
- * clearAllMemoizationCaches()
- * ```
- */
-export declare function clearAllMemoizationCaches(): void;
-/**
- * Create a memoized version of a method.
- * Preserves 'this' context for class methods.
- *
- * @param target - Object containing the method
- * @param propertyKey - Method name
- * @param descriptor - Property descriptor
- * @returns Modified descriptor with memoized method
- *
- * @example
- * import { Memoize } from '@socketsecurity/lib/memoization'
- *
- * class Calculator {
- *   @Memoize()
- *   fibonacci(n: number): number {
- *     if (n <= 1) return n
- *     return this.fibonacci(n - 1) + this.fibonacci(n - 2)
- *   }
- * }
- */
-export declare function Memoize(options?: MemoizeOptions<unknown[]>): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
-/**
- * Memoize a function with configurable caching behavior.
- * Caches function results to avoid repeated computation.
- *
- * @param fn - Function to memoize
- * @param options - Memoization options
- * @returns Memoized version of the function
- *
- * @example
- * import { memoize } from '@socketsecurity/lib/memoization'
- *
- * 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
- */
-export declare function memoize<Args extends unknown[], Result>(fn: (...args: Args) => Result, options?: MemoizeOptions<Args>): (...args: Args) => Result;
-/**
- * Memoize an async function.
- * Similar to memoize() but handles promises properly.
- *
- * @param fn - Async function to memoize
- * @param options - Memoization options
- * @returns Memoized version of the async function
- *
- * @example
- * import { memoizeAsync } from '@socketsecurity/lib/memoization'
- *
- * 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
- */
-export declare function memoizeAsync<Args extends unknown[], Result>(fn: (...args: Args) => Promise<Result>, options?: MemoizeOptions<Args>): (...args: Args) => Promise<Result>;
-/**
- * Memoize with WeakMap for object keys.
- * Allows garbage collection when objects are no longer referenced.
- * Only works when first argument is an object.
- *
- * @param fn - Function to memoize
- * @returns Memoized version using WeakMap
- *
- * @example
- * import { memoizeWeak } from '@socketsecurity/lib/memoization'
- *
- * const processConfig = memoizeWeak((config: Config) => {
- *   return expensiveTransform(config)
- * })
- *
- * processConfig(config1) // Computed
- * processConfig(config1) // Cached
- * // When config1 is no longer referenced, cache entry is GC'd
- */
-export declare function memoizeWeak<K extends object, Result>(fn: (key: K) => Result): (key: K) => Result;
-/**
- * Simple once() for zero-argument initialization functions.
- * Caches a single result forever and emits debug-log events on hit/miss.
- *
- * @param fn - Zero-argument function to run once
- * @returns Memoized version that only executes once
- *
- * @example
- * import { once } from '@socketsecurity/lib/memoization'
- *
- * const initialize = once(() => {
- *   console.log('Initializing…')
- *   return loadConfig()
- * })
- *
- * initialize() // Logs "Initializing…" and returns config
- * initialize() // Returns cached config (no log)
- */
-export declare function once<Result>(fn: () => Result): () => Result;

package/dist/memoization.js

@@ -1,243 +0,0 @@
-"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 memoization_exports = {};
-__export(memoization_exports, {
-  Memoize: () => Memoize,
-  clearAllMemoizationCaches: () => clearAllMemoizationCaches,
-  memoize: () => memoize,
-  memoizeAsync: () => memoizeAsync,
-  memoizeWeak: () => memoizeWeak,
-  once: () => once
-});
-module.exports = __toCommonJS(memoization_exports);
-var import_debug = require("./debug");
-var import_primordials = require("./primordials");
-const cacheRegistry = [];
-function defaultKeyGen(args) {
-  return (0, import_primordials.JSONStringify)(args, (_key, value) => {
-    if (value === void 0) {
-      return "\0undefined";
-    }
-    if (typeof value === "bigint") {
-      return `\0bigint:${value.toString()}`;
-    }
-    if (typeof value === "function") {
-      return `\0fn:${value.name || "anonymous"}`;
-    }
-    if (value instanceof Map) {
-      return { __tag: "Map", entries: Array.from(value.entries()) };
-    }
-    if (value instanceof Set) {
-      return { __tag: "Set", values: Array.from(value.values()) };
-    }
-    return value;
-  });
-}
-function clearAllMemoizationCaches() {
-  (0, import_debug.debugLog)("[memoize:all] clear", { action: "clear-all-caches" });
-  for (const clear of cacheRegistry) {
-    clear();
-  }
-}
-function Memoize(options = {}) {
-  return (_target, propertyKey, descriptor) => {
-    const originalMethod = descriptor.value;
-    descriptor.value = memoize(originalMethod, {
-      ...options,
-      name: options.name || propertyKey
-    });
-    return descriptor;
-  };
-}
-function memoize(fn, options = {}) {
-  const {
-    keyGen = (...args) => defaultKeyGen(args),
-    maxSize = Number.POSITIVE_INFINITY,
-    name = fn.name || "anonymous",
-    ttl = Number.POSITIVE_INFINITY
-  } = options;
-  if (ttl < 0) {
-    throw new import_primordials.TypeErrorCtor("TTL must be non-negative");
-  }
-  const cache = new import_primordials.MapCtor();
-  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_debug.debugLog)(`[memoize:${name}] clear`, {
-          key: oldest,
-          reason: "LRU"
-        });
-      }
-    }
-  }
-  function isExpired(entry) {
-    if (ttl === Number.POSITIVE_INFINITY) {
-      return false;
-    }
-    return (0, import_primordials.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_debug.debugLog)(`[memoize:${name}] hit`, { key, hits: cached.hits });
-        return cached.value;
-      }
-      cache.delete(key);
-    }
-    (0, import_debug.debugLog)(`[memoize:${name}] miss`, { key });
-    const value = fn(...args);
-    evictLRU();
-    cache.set(key, {
-      value,
-      timestamp: Date.now(),
-      hits: 0
-    });
-    (0, import_debug.debugLog)(`[memoize:${name}] set`, { key, cacheSize: cache.size });
-    return value;
-  };
-}
-function memoizeAsync(fn, options = {}) {
-  const {
-    keyGen = (...args) => defaultKeyGen(args),
-    maxSize = Number.POSITIVE_INFINITY,
-    name = fn.name || "anonymous",
-    ttl = Number.POSITIVE_INFINITY
-  } = options;
-  const cache = new import_primordials.MapCtor();
-  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_debug.debugLog)(`[memoizeAsync:${name}] clear`, {
-          key: oldest,
-          reason: "LRU"
-        });
-      }
-    }
-  }
-  function isExpired(entry) {
-    if (ttl === Number.POSITIVE_INFINITY) {
-      return false;
-    }
-    return (0, import_primordials.DateNow)() - entry.timestamp > ttl;
-  }
-  function bumpRecency(key, entry) {
-    cache.delete(key);
-    cache.set(key, entry);
-  }
-  const refreshing = new import_primordials.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_debug.debugLog)(`[memoizeAsync:${name}] hit`, { key, hits: cached.hits });
-        return await cached.value;
-      }
-      const inflight = refreshing.get(key);
-      if (inflight) {
-        (0, import_debug.debugLog)(`[memoizeAsync:${name}] stale-dedup`, { key });
-        bumpRecency(key, cached);
-        return await inflight;
-      }
-      cache.delete(key);
-    }
-    (0, import_debug.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_primordials.PromiseResolve)(result);
-          entry.timestamp = (0, import_primordials.DateNow)();
-        }
-        return result;
-      } catch (error) {
-        refreshing.delete(key);
-        cache.delete(key);
-        (0, import_debug.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_debug.debugLog)(`[memoizeAsync:${name}] set`, { key, cacheSize: cache.size });
-    return await promise;
-  };
-}
-function memoizeWeak(fn) {
-  const cache = new import_primordials.WeakMapCtor();
-  return function memoized(key) {
-    if (cache.has(key)) {
-      (0, import_debug.debugLog)(`[memoizeWeak:${fn.name}] hit`);
-      return cache.get(key);
-    }
-    (0, import_debug.debugLog)(`[memoizeWeak:${fn.name}] miss`);
-    const result = fn(key);
-    cache.set(key, result);
-    return result;
-  };
-}
-function once(fn) {
-  let called = false;
-  let result;
-  return function memoized() {
-    if (!called) {
-      result = fn();
-      called = true;
-      (0, import_debug.debugLog)(`[once:${fn.name}] set`);
-    } else {
-      (0, import_debug.debugLog)(`[once:${fn.name}] hit`);
-    }
-    return result;
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  Memoize,
-  clearAllMemoizationCaches,
-  memoize,
-  memoizeAsync,
-  memoizeWeak,
-  once
-});