@zintrust/core 0.1.27 → 0.1.28

package/src/performance/Optimizer.ts

@@ -0,0 +1,846 @@
+/**
+ * Performance Optimizations for Code Generation
+ * Implements caching, lazy-loading, and parallel generation
+ */
+
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { fs } from '@node-singletons';
+import * as path from '@node-singletons/path';
+
+const GENERATION_CACHE_STATE_SYMBOL = Symbol.for('zintrust:GenerationCacheState');
+
+export interface IGenerationCache {
+  get(type: string, params: Record<string, unknown>): Promise<string | null>;
+  set(type: string, params: Record<string, unknown>, code: string): Promise<void>;
+  save(): Promise<void>;
+  clear(): Promise<void>;
+  getStats(): Promise<{
+    size: number;
+    entries: number;
+    diskUsage: string;
+    keys: string[];
+  }>;
+}
+
+interface CacheState {
+  cache: Map<string, { code: string; timestamp: number }>;
+  cacheDir: string;
+  ttlMs: number;
+  cleanupInterval?: NodeJS.Timeout;
+  flushTimer?: NodeJS.Timeout;
+  pendingWrites: Map<string, { payload: string }>;
+}
+
+type UnrefableTimer = { unref: () => void };
+
+function isUnrefableTimer(value: unknown): value is UnrefableTimer {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'unref' in value && typeof (value as UnrefableTimer).unref === 'function';
+}
+
+function deleteFileNonBlocking(filePath: string): void {
+  try {
+    const anyFs = fs as unknown as {
+      promises?: { unlink?: (p: string) => Promise<void> };
+      unlink?: (p: string, cb: (err: NodeJS.ErrnoException | null) => void) => void;
+    };
+
+    if (typeof anyFs.promises?.unlink === 'function') {
+      void anyFs.promises.unlink(filePath).catch((err: unknown) => {
+        const maybeErr = err as Partial<NodeJS.ErrnoException>;
+        if (maybeErr.code === 'ENOENT') return;
+        Logger.error(
+          `Failed to delete cache file: ${filePath} (${err instanceof Error ? err.message : String(err)})`
+        );
+      });
+      return;
+    }
+
+    if (typeof anyFs.unlink === 'function') {
+      anyFs.unlink(filePath, (err) => {
+        if (err && err.code !== 'ENOENT') {
+          Logger.error(`Failed to delete cache file: ${filePath} (${err.message})`);
+        }
+      });
+    }
+  } catch (err) {
+    Logger.error(
+      `Failed to schedule cache file deletion: ${filePath} (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+}
+
+/**
+ * Generation Cache - Cache generated code to avoid re-generating identical code
+ * Sealed namespace for immutability
+ */
+export const GenerationCache = Object.freeze({
+  /**
+   * Create a new generation cache instance
+   */
+  create(
+    cacheDir: string = path.join(process.cwd(), '.gen-cache'),
+    ttlMs: number = 3600000,
+    maxEntries: number = 1000
+  ): IGenerationCache {
+    const state = createCacheState(cacheDir, ttlMs, maxEntries);
+    initializeCacheState(state);
+    startCacheCleanup(state);
+
+    const instance = createCacheInstance(state);
+    attachCacheStateForTests(instance, state);
+
+    return instance;
+  },
+});
+
+function createCacheState(
+  cacheDir: string,
+  ttlMs: number,
+  maxEntries: number
+): CacheState & { maxEntries?: number } {
+  return {
+    cache: new Map(),
+    cacheDir,
+    ttlMs,
+    maxEntries,
+    pendingWrites: new Map(),
+  };
+}
+
+async function ensureCacheDir(cacheDir: string): Promise<void> {
+  try {
+    await fs.fsPromises.access(cacheDir);
+  } catch {
+    await fs.fsPromises.mkdir(cacheDir, { recursive: true });
+  }
+}
+
+async function flushPendingWrites(state: CacheState): Promise<boolean> {
+  if (state.pendingWrites.size === 0) {
+    state.flushTimer = undefined;
+    return false;
+  }
+
+  const pending = state.pendingWrites;
+  state.pendingWrites = new Map();
+  state.flushTimer = undefined;
+  try {
+    await ensureCacheDir(state.cacheDir);
+  } catch (error) {
+    Logger.error('Failed to ensure cache directory before flush', error);
+    return false;
+  }
+
+  const writes = Array.from(pending.entries()).map(async ([key, entry]) => {
+    const file = path.join(state.cacheDir, `${key}.json`);
+    await fs.fsPromises.writeFile(file, entry.payload);
+  });
+
+  await Promise.all(writes);
+  return true;
+}
+
+function scheduleCacheWrite(state: CacheState, key: string, payload: string): void {
+  state.pendingWrites.set(key, { payload });
+
+  if (state.flushTimer !== undefined) return;
+
+  state.flushTimer = setTimeout(() => {
+    void flushPendingWrites(state).catch((error) => {
+      Logger.error('Failed to flush generation cache writes', error);
+    });
+  }, 50);
+
+  if (isUnrefableTimer(state.flushTimer)) {
+    state.flushTimer.unref();
+  }
+}
+
+function initializeCacheState(state: CacheState): void {
+  loadFromDisk(state);
+}
+
+function startCacheCleanup(state: CacheState & { maxEntries?: number }): void {
+  // Active cleanup every 10 minutes
+  state.cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of state.cache.entries()) {
+      if (now - entry.timestamp > state.ttlMs) {
+        state.cache.delete(key);
+        const file = path.join(state.cacheDir, `${key}.json`);
+        deleteFileNonBlocking(file);
+      }
+    }
+
+    // Enforce maxEntries by evicting oldest keys
+    if (state.maxEntries !== undefined) {
+      while (state.cache.size > state.maxEntries) {
+        const oldestKey = state.cache.keys().next().value;
+        if (oldestKey === undefined) break;
+        state.cache.delete(oldestKey);
+        const file = path.join(state.cacheDir, `${oldestKey}.json`);
+        deleteFileNonBlocking(file);
+      }
+    }
+  }, 600000);
+
+  // Node: allow process to exit; other runtimes may not support unref()
+  if (isUnrefableTimer(state.cleanupInterval)) {
+    state.cleanupInterval.unref();
+  }
+}
+
+function createCacheInstance(state: CacheState & { maxEntries?: number }): IGenerationCache {
+  return {
+    /**
+     * Get from cache (async)
+     */
+
+    async get(type: string, params: Record<string, unknown>): Promise<string | null> {
+      const key = getCacheKey(type, params);
+      const entry = state.cache.get(key);
+
+      if (entry === undefined) return Promise.resolve(null); //NoSONAR
+
+      // Check TTL
+      if (Date.now() - entry.timestamp > state.ttlMs) {
+        state.cache.delete(key);
+        const file = path.join(state.cacheDir, `${key}.json`);
+        deleteFileNonBlocking(file);
+        return Promise.resolve(null); //NoSONAR
+      }
+
+      return Promise.resolve(entry.code); //NoSONAR
+    },
+
+    /**
+     * Set in cache (async)
+     */
+
+    async set(type: string, params: Record<string, unknown>, code: string): Promise<void> {
+      const key = getCacheKey(type, params);
+
+      // If key already exists, delete first so insertion order updates for LRU
+      if (state.cache.has(key)) state.cache.delete(key);
+
+      state.cache.set(key, {
+        code,
+        timestamp: Date.now(),
+      });
+
+      // Enforce maxEntries immediately
+      if (state.maxEntries !== undefined) {
+        while (state.cache.size > state.maxEntries) {
+          const oldest = state.cache.keys().next().value;
+          if (oldest === undefined) break;
+          state.cache.delete(oldest);
+          const file = path.join(state.cacheDir, `${oldest}.json`);
+          deleteFileNonBlocking(file);
+        }
+      }
+
+      const payload = JSON.stringify({ code, timestamp: Date.now() }, null, 2);
+      scheduleCacheWrite(state, key, payload);
+      return Promise.resolve(); // NOSONAR
+    },
+
+    /**
+     * Save cache to disk (async)
+     */
+    async save(): Promise<void> {
+      await saveCacheToDisk(state);
+    },
+
+    /**
+     * Clear cache (async)
+     */
+    async clear(): Promise<void> {
+      if (state.cleanupInterval) {
+        clearInterval(state.cleanupInterval);
+        state.cleanupInterval = undefined;
+      }
+      if (state.flushTimer) {
+        clearTimeout(state.flushTimer);
+        state.flushTimer = undefined;
+      }
+      state.pendingWrites.clear();
+      await clearCache(state);
+    },
+
+    /**
+     * Get cache statistics (async)
+     */
+    async getStats(): Promise<{
+      size: number;
+      entries: number;
+      diskUsage: string;
+      keys: string[];
+    }> {
+      return getCacheStats(state);
+    },
+  };
+}
+
+function attachCacheStateForTests(instance: IGenerationCache, state: CacheState): void {
+  Object.defineProperty(instance, GENERATION_CACHE_STATE_SYMBOL, {
+    value: state as unknown,
+    enumerable: false,
+  });
+}
+
+/**
+ * Save cache to disk (async)
+ */
+async function saveCacheToDisk(state: CacheState): Promise<void> {
+  try {
+    const flushedEnsured = await flushPendingWrites(state);
+    if (!flushedEnsured) {
+      await ensureCacheDir(state.cacheDir);
+    }
+
+    const writes = Array.from(state.cache.entries()).map(async ([key, entry]) => {
+      const file = path.join(state.cacheDir, `${key}.json`);
+      await fs.fsPromises.writeFile(file, JSON.stringify(entry, null, 2));
+    });
+
+    await Promise.all(writes);
+  } catch (error) {
+    Logger.error('Failed to save cache to disk', error);
+  }
+}
+
+/**
+ * Clear cache (async)
+ */
+async function clearCache(state: CacheState): Promise<void> {
+  state.cache.clear();
+  state.pendingWrites.clear();
+  try {
+    try {
+      await fs.fsPromises.access(state.cacheDir);
+    } catch {
+      return; // Dir doesn't exist
+    }
+    await fs.fsPromises.rm(state.cacheDir, { recursive: true });
+  } catch (error) {
+    Logger.error('Failed to clear cache', error);
+  }
+}
+
+/**
+ * Get cache statistics (async)
+ */
+async function getCacheStats(state: CacheState): Promise<{
+  size: number;
+  entries: number;
+  diskUsage: string;
+  keys: string[];
+}> {
+  let diskUsage = 0;
+  try {
+    try {
+      await fs.fsPromises.access(state.cacheDir);
+      const files = await fs.fsPromises.readdir(state.cacheDir);
+
+      const sizes = await Promise.all(
+        files.map(async (file) => {
+          const stats = await fs.fsPromises.stat(path.join(state.cacheDir, file));
+          return stats.size;
+        })
+      );
+
+      diskUsage = sizes.reduce((sum, size) => sum + size, 0);
+    } catch {
+      // ignore
+    }
+  } catch {
+    // ignore
+  }
+
+  return {
+    size: diskUsage,
+    entries: state.cache.size,
+    diskUsage: formatBytes(diskUsage),
+    keys: Array.from(state.cache.keys()),
+  };
+}
+
+function formatBytes(bytes: number): string {
+  const units = ['B', 'KB', 'MB'];
+  let size = bytes;
+  let i = 0;
+  while (size > 1024 && i < units.length - 1) {
+    size /= 1024;
+    i++;
+  }
+  return `${size.toFixed(2)} ${units[i]}`;
+}
+
+/**
+ * Get cache key from params
+ */
+function getCacheKey(type: string, params: Record<string, unknown>): string {
+  // Use a more efficient key generation
+  // Simple hash-like string for the key
+  const paramStr = JSON.stringify(
+    params,
+    Object.keys(params).sort((a, b) => a.localeCompare(b))
+  );
+  let hash = 0;
+  for (let i = 0; i < paramStr.length; i++) {
+    const char = paramStr.codePointAt(i);
+    hash = (hash << 5) - hash + (char ?? 0);
+    hash = toInt32(hash); // Convert to 32bit integer
+  }
+  return `${type}:${hash.toString(36)}:${Buffer.from(paramStr.slice(0, 32)).toString('base64')}`;
+}
+
+/**
+ * Convert a number to a signed 32-bit integer (equivalent to JS ToInt32)
+ */
+function toInt32(value: number): number {
+  const truncated = Math.trunc(value);
+  const uint32 = ((truncated % 4294967296) + 4294967296) % 4294967296;
+  return uint32 > 2147483647 ? uint32 - 4294967296 : uint32;
+}
+
+/**
+ * Load cache from disk (async)
+ */
+async function loadFromDisk(state: CacheState): Promise<void> {
+  try {
+    try {
+      await fs.fsPromises.access(state.cacheDir);
+    } catch {
+      return;
+    }
+
+    const files = await fs.fsPromises.readdir(state.cacheDir);
+    const jsonFiles = files.filter((file) => file.endsWith('.json') === true);
+
+    const parsedEntries = await Promise.all(
+      jsonFiles.map(async (file) => {
+        const filePath = path.join(state.cacheDir, file);
+        const content = await fs.fsPromises.readFile(filePath, 'utf-8');
+        try {
+          const data = JSON.parse(content);
+          return { key: file.replace('.json', ''), data };
+        } catch {
+          // ignore corrupted files
+          return null;
+        }
+      })
+    );
+
+    for (const entry of parsedEntries) {
+      if (entry !== null) {
+        state.cache.set(entry.key, entry.data);
+      }
+    }
+  } catch (err) {
+    Logger.error(
+      `Failed to load cache from disk: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+export interface ILazyLoader {
+  load<T>(modulePath: string): Promise<T>;
+  preload(modulePaths: string[]): Promise<void>;
+  clear(): void;
+}
+
+/**
+ * Lazy Module Loader - Load dependencies only when needed
+ * Sealed namespace for immutability
+ */
+export const LazyLoader = Object.freeze({
+  /**
+   * Create a new lazy loader instance
+   */
+  create(): ILazyLoader {
+    const modules: Map<string, unknown> = new Map();
+
+    return {
+      /**
+       * Lazy load a module
+       */
+      async load<T>(modulePath: string): Promise<T> {
+        const cached = modules.get(modulePath);
+        if (cached !== undefined) {
+          return cached as T;
+        }
+
+        try {
+          const module = await import(modulePath);
+          modules.set(modulePath, module);
+          return module as T;
+        } catch (err) {
+          throw ErrorFactory.createTryCatchError(`Failed to load module: ${modulePath}`, err);
+        }
+      },
+
+      /**
+       * Preload modules
+       */
+      async preload(modulePaths: string[]): Promise<void> {
+        await Promise.all(modulePaths.map(async (path) => this.load(path)));
+      },
+
+      /**
+       * Clear loaded modules
+       */
+      clear(): void {
+        modules.clear();
+      },
+    };
+  },
+});
+
+/**
+ * Parallel Generator - Run multiple generators in parallel
+ */
+
+/**
+ * Run generators in parallel batches
+ */
+export async function runBatch<T>(
+  generators: Array<() => Promise<T>>,
+  batchSize: number = 3
+): Promise<T[]> {
+  const batches: Array<Array<() => Promise<T>>> = [];
+  for (let i = 0; i < generators.length; i += batchSize) {
+    batches.push(generators.slice(i, i + batchSize));
+  }
+
+  return batches.reduce(
+    async (accPromise, batch) => {
+      const acc = await accPromise;
+      const batchResults = await Promise.all(batch.map(async (gen) => gen()));
+      return acc.concat(batchResults);
+    },
+    Promise.resolve([] as T[])
+  );
+}
+
+/**
+ * Run all generators in parallel
+ */
+export async function runAll<T>(generators: Array<() => Promise<T>>): Promise<T[]> {
+  return Promise.all(generators.map(async (gen) => gen()));
+}
+
+export const ParallelGenerator = Object.freeze({
+  runBatch,
+  runAll,
+});
+
+/**
+ * Memoize - Cache function results based on arguments
+ */
+
+/**
+ * Create a memoized version of a function
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createMemoized<T extends (...args: any[]) => any>(
+  fn: T,
+  options: { ttl?: number; keyGenerator?: (args: Parameters<T>) => string; maxSize?: number } = {}
+): T {
+  const cache = new Map<
+    string,
+    { result: ReturnType<T>; createdAt: number; lastAccessAt: number }
+  >();
+  const maxSize = options.maxSize ?? 1000; // Default max size: 1000 entries
+
+  const evictLRU = (): void => {
+    if (cache.size < maxSize) return;
+
+    // Find oldest entry (LRU)
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of cache.entries()) {
+      if (entry.lastAccessAt < oldestTime) {
+        oldestTime = entry.lastAccessAt;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey !== null) {
+      cache.delete(oldestKey);
+    }
+  };
+
+  return ((...args: Parameters<T>) => {
+    let key: string;
+    if (options.keyGenerator === undefined) {
+      // Optimization: Avoid JSON.stringify for simple primitive arguments
+      const arePrimitives = args.every(
+        (a) =>
+          a === null ||
+          typeof a === 'string' ||
+          typeof a === 'number' ||
+          typeof a === 'boolean' ||
+          a === 'undefined'
+      );
+      key = arePrimitives ? args.join('|') : JSON.stringify(args);
+    } else {
+      key = options.keyGenerator(args);
+    }
+
+    const entry = cache.get(key);
+
+    if (entry !== undefined) {
+      if (options.ttl === undefined || Date.now() - entry.createdAt < options.ttl) {
+        // Update access time for LRU; TTL remains based on creation time
+        entry.lastAccessAt = Date.now();
+        return entry.result;
+      }
+      cache.delete(key);
+    }
+
+    const result = fn(...args) as ReturnType<T>;
+
+    // Evict LRU before adding new entry
+    evictLRU();
+
+    const now = Date.now();
+    cache.set(key, { result, createdAt: now, lastAccessAt: now });
+    return result;
+  }) as unknown as T;
+}
+
+export const Memoize = Object.freeze({
+  create: createMemoized,
+});
+
+export interface IPerformanceOptimizer {
+  generateWithCache<T>(
+    type: string,
+    params: Record<string, unknown>,
+    generatorFn: () => Promise<T>
+  ): Promise<T>;
+  generateInParallel<T>(generators: Array<() => Promise<T>>, batchSize?: number): Promise<T[]>;
+  preloadModules(paths: string[]): Promise<void>;
+  getStats(): {
+    cacheHits: number;
+    cacheMisses: number;
+    hitRate: string;
+    parallelRuns: number;
+    estimatedSavedTime: string;
+    cacheStatus: { size: number; keys: string[] };
+  };
+  saveCache(): void;
+  clear(): void;
+}
+
+interface OptimizerStats {
+  cacheHits: number;
+  cacheMisses: number;
+  parallelRuns: number;
+  savedTime: number;
+}
+
+/**
+ * Performance Optimizer - Wrapper for optimizations
+ * Sealed namespace for immutability
+ */
+export const PerformanceOptimizer = Object.freeze({
+  /**
+   * Create a new performance optimizer instance
+   */
+  create(): IPerformanceOptimizer {
+    const cache = GenerationCache.create();
+    const lazyLoader = LazyLoader.create();
+    const stats: OptimizerStats = {
+      cacheHits: 0,
+      cacheMisses: 0,
+      parallelRuns: 0,
+      savedTime: 0,
+    };
+
+    return {
+      /**
+       * Generate with caching
+       */
+      async generateWithCache<T>(
+        type: string,
+        params: Record<string, unknown>,
+        generatorFn: () => Promise<T>
+      ): Promise<T> {
+        return generateWithCache(cache, stats, type, params, generatorFn);
+      },
+
+      /**
+       * Generate multiple in parallel
+       */
+      async generateInParallel<T>(
+        generators: Array<() => Promise<T>>,
+        batchSize?: number
+      ): Promise<T[]> {
+        return generateInParallel(stats, generators, batchSize);
+      },
+
+      /**
+       * Preload modules
+       */
+      async preloadModules(paths: string[]): Promise<void> {
+        await lazyLoader.preload(paths);
+      },
+
+      /**
+       * Get optimization statistics
+       */
+      getStats(): {
+        cacheHits: number;
+        cacheMisses: number;
+        hitRate: string;
+        parallelRuns: number;
+        estimatedSavedTime: string;
+        cacheStatus: { size: number; keys: string[] };
+      } {
+        return getOptimizerStats(cache, stats);
+      },
+
+      /**
+       * Save cache to disk
+       */
+      saveCache(): void {
+        cache.save();
+      },
+
+      /**
+       * Clear everything
+       */
+      clear(): void {
+        resetOptimizer(cache, lazyLoader, stats);
+      },
+    };
+  },
+});
+
+/**
+ * Reset optimizer state
+ */
+function resetOptimizer(
+  cache: IGenerationCache,
+  lazyLoader: ILazyLoader,
+  stats: OptimizerStats
+): void {
+  cache.clear();
+  lazyLoader.clear();
+  stats.cacheHits = 0;
+  stats.cacheMisses = 0;
+  stats.parallelRuns = 0;
+  stats.savedTime = 0;
+}
+
+/**
+ * Generate multiple in parallel
+ */
+async function generateInParallel<T>(
+  stats: OptimizerStats,
+  generators: Array<() => Promise<T>>,
+  batchSize?: number
+): Promise<T[]> {
+  stats.parallelRuns++;
+  if (batchSize !== undefined) {
+    return ParallelGenerator.runBatch(generators, batchSize);
+  }
+  return ParallelGenerator.runAll(generators);
+}
+
+/**
+ * Generate with caching
+ */
+async function generateWithCache<T>(
+  cache: IGenerationCache,
+  stats: OptimizerStats,
+  type: string,
+  params: Record<string, unknown>,
+  generatorFn: () => Promise<T>
+): Promise<T> {
+  // Try cache
+  let cached: string | null = null;
+  try {
+    cached = await cache.get(type, params);
+  } catch (err) {
+    Logger.warn('GenerationCache.get failed; treating as cache miss', {
+      type,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  if (cached !== null) {
+    try {
+      stats.cacheHits++;
+      return JSON.parse(cached) as T;
+    } catch (err) {
+      Logger.warn('Failed to parse cached generation result; treating as cache miss', {
+        type,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // Generate
+  const startTime = performance.now();
+  const result = await generatorFn();
+  const duration = performance.now() - startTime;
+
+  // Cache result (fire-and-forget)
+  void cache
+    .set(type, params, JSON.stringify(result))
+    .catch((err) => Logger.error('GenerationCache.set failed', err));
+
+  stats.cacheMisses++;
+  stats.savedTime += duration;
+
+  return result;
+}
+
+/**
+ * Get optimization statistics
+ */
+function getCacheStatusSync(cache: IGenerationCache): { size: number; keys: string[] } {
+  const state = (cache as unknown as Record<symbol, unknown>)[GENERATION_CACHE_STATE_SYMBOL] as
+    | Partial<CacheState>
+    | undefined;
+
+  const map = state?.cache;
+  if (!(map instanceof Map)) return { size: 0, keys: [] };
+
+  return {
+    size: map.size,
+    keys: Array.from(map.keys()),
+  };
+}
+
+function getOptimizerStats(
+  cache: IGenerationCache,
+  stats: OptimizerStats
+): {
+  cacheHits: number;
+  cacheMisses: number;
+  hitRate: string;
+  parallelRuns: number;
+  estimatedSavedTime: string;
+  cacheStatus: { size: number; keys: string[] };
+} {
+  const total = stats.cacheHits + stats.cacheMisses;
+  const hitRate = total > 0 ? (stats.cacheHits / total) * 100 : 0;
+
+  return {
+    cacheHits: stats.cacheHits,
+    cacheMisses: stats.cacheMisses,
+    hitRate: `${hitRate.toFixed(1)}%`,
+    parallelRuns: stats.parallelRuns,
+    estimatedSavedTime: `${stats.savedTime.toFixed(2)}ms`,
+    cacheStatus: getCacheStatusSync(cache),
+  };
+}
+
+export default PerformanceOptimizer;