webspresso 0.0.106 → 0.0.107

package/src/services/loader.js

@@ -0,0 +1,120 @@
+/**
+ * Webspresso Services Module Loader
+ * Handles synchronous CommonJS and asynchronous native dynamic import (ESM)
+ * with robust export normalization and dev-mode cache busting.
+ * @module src/services/loader
+ */
+
+'use strict';
+
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+/**
+ * Execute native dynamic import() via Function constructor to prevent
+ * compilers/bundlers from down-leveling import() into require().
+ * @param {string} specifier - Module URL string
+ * @returns {Promise<any>}
+ */
+function nativeImport(specifier) {
+  return new Function('specifier', 'return import(specifier);')(specifier);
+}
+
+/**
+ * Load a module synchronously via CommonJS require
+ * @param {string} filePath - Absolute file path
+ * @param {Object} [options]
+ * @param {boolean} [options.isDev=false] - Invalidate require.cache if true
+ * @returns {any} Exported module
+ */
+function loadModuleSync(filePath, options = {}) {
+  const resolved = require.resolve(filePath);
+  if (options.isDev) {
+    try {
+      delete require.cache[resolved];
+    } catch (_) {}
+  }
+  return require(resolved);
+}
+
+/**
+ * Load a module asynchronously supporting both CommonJS and native ES Modules (ESM)
+ * @param {string} filePath - Absolute file path
+ * @param {Object} [options]
+ * @param {boolean} [options.isDev=false] - Cache busting via timestamp query param
+ * @returns {Promise<any>} Exported module
+ */
+async function loadModuleAsync(filePath, options = {}) {
+  const isDev = Boolean(options.isDev);
+  const ext = path.extname(filePath);
+
+  // If not explicitly .mjs, try synchronous CommonJS require first for maximum speed
+  if (ext !== '.mjs') {
+    try {
+      return loadModuleSync(filePath, { isDev });
+    } catch (err) {
+      // If Node.js throws ERR_REQUIRE_ESM, fall through to native dynamic import
+      if (err.code !== 'ERR_REQUIRE_ESM' && !err.message?.includes('ERR_REQUIRE_ESM')) {
+        throw err;
+      }
+    }
+  }
+
+  // Load via native dynamic import() with file URL
+  let specifier = pathToFileURL(path.resolve(filePath)).href;
+  if (isDev) {
+    specifier += `?t=${Date.now()}`;
+  }
+
+  return nativeImport(specifier);
+}
+
+/**
+ * Normalize and extract service definition from various module export conventions:
+ * 1. module.exports = defineService({ handler })
+ * 2. module.exports = async function() {}
+ * 3. export default defineService({ handler })
+ * 4. export default async function() {}
+ * 5. export const handler = async function() {}
+ * 6. export const service = defineService({ handler })
+ *
+ * @param {any} mod - Loaded module
+ * @returns {any} Extracted service definition or handler
+ */
+function extractModuleExport(mod) {
+  if (mod === null || mod === undefined) {
+    return mod;
+  }
+
+  // TypeScript / Babel transpiled default
+  if (mod.__esModule && mod.default !== undefined) {
+    return mod.default;
+  }
+
+  // Native ESM default export
+  if (mod.default !== undefined) {
+    const d = mod.default;
+    if (typeof d === 'function' || (typeof d === 'object' && d !== null && typeof d.handler === 'function')) {
+      return d;
+    }
+  }
+
+  // Named export: export const handler = ...
+  if (typeof mod.handler === 'function') {
+    return mod;
+  }
+
+  // Named export: export const service = defineService(...)
+  if (mod.service && typeof mod.service === 'object' && typeof mod.service.handler === 'function') {
+    return mod.service;
+  }
+
+  return mod.default !== undefined ? mod.default : mod;
+}
+
+module.exports = {
+  nativeImport,
+  loadModuleSync,
+  loadModuleAsync,
+  extractModuleExport,
+};

package/src/services/memoize.js

@@ -1,10 +1,5 @@
-/**
- * Webspresso Services Memoization & Caching
- * Lightweight, zero-dependency in-memory cache with stampede protection, LRU eviction, and safe serialization
- * @module src/services/memoize
- */
-
 const { parseDurationMs } = require('../../core/utils/time');
+const { TaggedLruCache, normalizeTags } = require('../../core/cache/tagged-lru');
 
 /**
  * Parse TTL duration into milliseconds
@@ -94,8 +89,11 @@ function stableCacheKey(input, seen = new WeakSet()) {
 /**
  * Memoize an async or sync function with:
  * - Cache stampede / thundering herd protection (in-flight promise deduping)
- * - LRU cache eviction
+ * - Zero-allocation O(1) LRU cache eviction
  * - TTL expiration
+ * - Bidirectional tag-based invalidation with zero memory leaks
+ * - Dynamic tag resolvers: `(input, ctx) => ['user:' + input.id]`
+ * - Pluggable custom or distributed cache providers (Redis, memory, etc.)
  * - Cache mutation protection (safe cloning)
  * - Safe serialization (BigInt, circular refs, Buffers)
  * 
@@ -105,7 +103,9 @@ function stableCacheKey(input, seen = new WeakSet()) {
  * @param {number} [options.maxSize=500] - Max cache entries before LRU eviction
  * @param {boolean} [options.clone=true] - Clone cached results to prevent mutation
  * @param {Function} [options.key] - Custom cache key generator `(input, ctx) => string`
- * @returns {Function} Memoized function with .clear(), .invalidate(), .delete(), .has(), .size
+ * @param {string|string[]|Function} [options.tags] - Static tags or dynamic tag resolver `(input, ctx) => string|string[]`
+ * @param {Object} [options.provider] - Pluggable cache provider (e.g. Redis, distributed store)
+ * @returns {Function} Memoized function with .clear(), .invalidate(), .delete(), .has(), .size, .invalidateByTag(), .invalidateByTags()
  */
 function memoize(fn, options = {}) {
   if (typeof fn !== 'function') {
@@ -116,13 +116,53 @@ function memoize(fn, options = {}) {
   const maxSize = Number(options.maxSize) || 500;
   const shouldClone = options.clone !== false;
   const customKeyFn = typeof options.key === 'function' ? options.key : null;
+  const tagsOption = options.tags;
+  const provider = options.provider || null;
 
-  /** @type {Map<string, { value: *, expiresAt: number }>} */
-  const cache = new Map();
-
-  /** @type {Map<string, Promise<*>>} In-flight request deduplication map */
+  /** @type {Map<string, Promise<*>>} In-flight request deduplication map (Stampede protection) */
   const inFlight = new Map();
 
+  /** @type {TaggedLruCache|null} Local zero-leak tagged LRU cache if no external provider */
+  const localCache = provider
+    ? null
+    : new TaggedLruCache({
+        maxEntries: maxSize,
+        defaultTtl: ttlMs,
+      });
+
+  // Fallback tag tracking for basic external providers that lack native tag support
+  const providerTagToKeys = new Map();
+  const providerKeyToTags = new Map();
+
+  function trackProviderTags(key, tags) {
+    if (!tags || tags.length === 0) return;
+    untrackProviderKey(key);
+    providerKeyToTags.set(key, new Set(tags));
+    for (const t of tags) {
+      let set = providerTagToKeys.get(t);
+      if (!set) {
+        set = new Set();
+        providerTagToKeys.set(t, set);
+      }
+      set.add(key);
+    }
+  }
+
+  function untrackProviderKey(key) {
+    const tags = providerKeyToTags.get(key);
+    if (!tags) return;
+    for (const t of tags) {
+      const set = providerTagToKeys.get(t);
+      if (set) {
+        set.delete(key);
+        if (set.size === 0) {
+          providerTagToKeys.delete(t);
+        }
+      }
+    }
+    providerKeyToTags.delete(key);
+  }
+
   function getKey(input, ctx) {
     if (customKeyFn) {
       return String(customKeyFn(input, ctx));
@@ -130,20 +170,20 @@ function memoize(fn, options = {}) {
     return stableCacheKey(input);
   }
 
-  async function memoized(input, ctx) {
-    const key = getKey(input, ctx);
-    const now = Date.now();
-    const hit = cache.get(key);
-
-    if (hit) {
-      if (hit.expiresAt > now) {
-        // Refresh LRU position
-        cache.delete(key);
-        cache.set(key, hit);
-        return shouldClone ? safeClone(hit.value) : hit.value;
+  function resolveTags(input, ctx) {
+    if (!tagsOption) return [];
+    if (typeof tagsOption === 'function') {
+      try {
+        return normalizeTags(tagsOption(input, ctx));
+      } catch (_) {
+        return [];
       }
-      cache.delete(key);
     }
+    return normalizeTags(tagsOption);
+  }
+
+  async function memoized(input, ctx) {
+    const key = getKey(input, ctx);
 
     // 1. In-flight Promise Deduping (Thundering Herd / Cache Stampede Protection)
     if (inFlight.has(key)) {
@@ -151,7 +191,29 @@ function memoize(fn, options = {}) {
       return shouldClone ? safeClone(inFlightResult) : inFlightResult;
     }
 
-    // 2. Execute and track in-flight promise
+    // 2. Check Cache Hit
+    if (provider) {
+      const hit = await provider.get(key);
+      if (hit !== undefined && hit !== null) {
+        return shouldClone ? safeClone(hit) : hit;
+      }
+      if (typeof provider.has === 'function') {
+        const exists = await provider.has(key);
+        if (exists) {
+          return shouldClone ? safeClone(hit) : hit;
+        }
+      }
+    } else {
+      const hit = localCache.get(key);
+      if (hit !== undefined) {
+        return shouldClone ? safeClone(hit) : hit;
+      }
+      if (localCache.has(key)) {
+        return undefined;
+      }
+    }
+
+    // 3. Execute and track in-flight promise
     const executionPromise = (async () => {
       try {
         return await fn(input, ctx);
@@ -170,18 +232,34 @@ function memoize(fn, options = {}) {
       throw execErr;
     }
 
-    // 3. LRU Eviction when exceeding maxSize
-    if (cache.size >= maxSize) {
-      const oldestKey = cache.keys().next().value;
-      if (oldestKey !== undefined) {
-        cache.delete(oldestKey);
+    // 4. Store result with tags
+    const entryTags = resolveTags(input, ctx);
+    const valToStore = shouldClone ? safeClone(result) : result;
+
+    if (provider) {
+      const hasNativeTagSupport = typeof provider.invalidateTag === 'function' ||
+        typeof provider.invalidateByTag === 'function' ||
+        typeof provider.invalidateTags === 'function' ||
+        typeof provider.invalidateByTags === 'function';
+
+      if (!hasNativeTagSupport && entryTags.length > 0) {
+        trackProviderTags(key, entryTags);
       }
-    }
 
-    cache.set(key, {
-      value: shouldClone ? safeClone(result) : result,
-      expiresAt: Date.now() + ttlMs,
-    });
+      if (typeof provider.set === 'function') {
+        await provider.set(key, valToStore, {
+          ttl: ttlMs,
+          ttlMs,
+          tags: entryTags,
+        });
+      }
+    } else {
+      localCache.set(key, valToStore, {
+        tags: entryTags,
+        ttlMs,
+        ttl: ttlMs,
+      });
+    }
 
     return shouldClone ? safeClone(result) : result;
   }
@@ -189,40 +267,135 @@ function memoize(fn, options = {}) {
   memoized.invalidate = function invalidate(input, ctx) {
     const key = getKey(input, ctx);
     inFlight.delete(key);
-    return cache.delete(key);
+    if (provider) {
+      untrackProviderKey(key);
+      if (typeof provider.delete === 'function') return provider.delete(key);
+      if (typeof provider.del === 'function') return provider.del(key);
+      return false;
+    }
+    return localCache.delete(key);
   };
 
   memoized.delete = memoized.invalidate;
 
+  memoized.invalidateByTag = function invalidateByTag(tag) {
+    const tagStr = String(tag);
+
+    if (provider) {
+      if (typeof provider.invalidateTag === 'function') {
+        return provider.invalidateTag(tagStr);
+      }
+      if (typeof provider.invalidateByTag === 'function') {
+        return provider.invalidateByTag(tagStr);
+      }
+      if (typeof provider.invalidateTags === 'function') {
+        return provider.invalidateTags([tagStr]);
+      }
+      if (typeof provider.invalidateByTags === 'function') {
+        return provider.invalidateByTags([tagStr]);
+      }
+
+      // Fallback tag tracking for basic providers
+      const keys = providerTagToKeys.get(tagStr);
+      if (!keys || keys.size === 0) return 0;
+      const keyArr = Array.from(keys);
+      providerTagToKeys.delete(tagStr);
+      for (const k of keyArr) {
+        inFlight.delete(k);
+        untrackProviderKey(k);
+      }
+      const delOps = keyArr.map(k => {
+        if (typeof provider.delete === 'function') return provider.delete(k);
+        if (typeof provider.del === 'function') return provider.del(k);
+        return false;
+      });
+      const hasPromise = delOps.some(p => p && typeof p.then === 'function');
+      if (hasPromise) {
+        return Promise.all(delOps).then(() => keyArr.length);
+      }
+      return keyArr.length;
+    }
+
+    // TaggedLruCache
+    const keys = localCache.getKeysForTag(tagStr);
+    for (const k of keys) {
+      inFlight.delete(k);
+    }
+    return localCache.invalidateTag(tagStr);
+  };
+
+  memoized.invalidateByTags = function invalidateByTags(tags) {
+    const normTags = normalizeTags(tags);
+    if (normTags.length === 0) return 0;
+
+    if (provider) {
+      if (typeof provider.invalidateTags === 'function') {
+        return provider.invalidateTags(normTags);
+      }
+      if (typeof provider.invalidateByTags === 'function') {
+        return provider.invalidateByTags(normTags);
+      }
+      const results = [];
+      for (const t of normTags) {
+        results.push(memoized.invalidateByTag(t));
+      }
+      const hasPromise = results.some(r => r && typeof r.then === 'function');
+      if (hasPromise) {
+        return Promise.all(results).then(counts =>
+          counts.reduce((acc, c) => acc + (typeof c === 'number' ? c : 0), 0)
+        );
+      }
+      return results.reduce((acc, c) => acc + (typeof c === 'number' ? c : 0), 0);
+    }
+
+    // TaggedLruCache
+    for (const t of normTags) {
+      const keys = localCache.getKeysForTag(t);
+      for (const k of keys) {
+        inFlight.delete(k);
+      }
+    }
+    return localCache.invalidateTags(normTags);
+  };
+
+  memoized.invalidateTag = memoized.invalidateByTag;
+  memoized.invalidateTags = memoized.invalidateByTags;
+
   memoized.clear = function clear() {
     inFlight.clear();
-    cache.clear();
+    if (provider) {
+      providerTagToKeys.clear();
+      providerKeyToTags.clear();
+      if (typeof provider.clear === 'function') return provider.clear();
+      return true;
+    }
+    return localCache.clear();
   };
 
   memoized.has = function has(input, ctx) {
     const key = getKey(input, ctx);
-    const hit = cache.get(key);
-    if (!hit) return false;
-    if (hit.expiresAt <= Date.now()) {
-      cache.delete(key);
+    if (provider) {
+      if (typeof provider.has === 'function') return provider.has(key);
       return false;
     }
-    return true;
+    return localCache.has(key);
   };
 
   Object.defineProperty(memoized, 'size', {
     get() {
-      // Clean expired entries on size access
-      const now = Date.now();
-      for (const [k, v] of cache.entries()) {
-        if (v.expiresAt <= now) {
-          cache.delete(k);
-        }
+      if (provider) {
+        if (typeof provider.size === 'number') return provider.size;
+        if (typeof provider.getSizeStats === 'function') return provider.getSizeStats().entries;
+        return providerKeyToTags.size;
       }
-      return cache.size;
+      localCache.pruneExpired();
+      return localCache.size;
     },
+    configurable: true,
   });
 
+  memoized.cache = provider || localCache;
+
   return memoized;
 }
 
@@ -231,4 +404,5 @@ module.exports = {
   parseTtlMs,
   stableCacheKey,
   safeClone,
+  normalizeTags,
 };