@zintrust/core 0.1.0

package/src/performance/Optimizer.js

@@ -0,0 +1,396 @@
+/**
+ * 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/index.js';
+import * as path from 'node:path';
+/**
+ * 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 = path.join(process.cwd(), '.gen-cache'), ttlMs = 3600000) {
+        const state = {
+            cache: new Map(),
+            cacheDir,
+            ttlMs,
+        };
+        // Initialize
+        loadFromDisk(state);
+        // 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);
+                    // Also try to delete from disk
+                    const file = path.join(state.cacheDir, `${key}.json`);
+                    if (fs.existsSync(file)) {
+                        fs.unlinkSync(file);
+                    }
+                }
+            }
+        }, 600000);
+        return {
+            /**
+             * Get from cache
+             */
+            get(type, params) {
+                const key = getCacheKey(type, params);
+                const entry = state.cache.get(key);
+                if (entry === undefined)
+                    return null;
+                // Check TTL
+                if (Date.now() - entry.timestamp > state.ttlMs) {
+                    state.cache.delete(key);
+                    const file = path.join(state.cacheDir, `${key}.json`);
+                    if (fs.existsSync(file)) {
+                        fs.unlinkSync(file);
+                    }
+                    return null;
+                }
+                return entry.code;
+            },
+            /**
+             * Set in cache
+             */
+            set(type, params, code) {
+                const key = getCacheKey(type, params);
+                state.cache.set(key, {
+                    code,
+                    timestamp: Date.now(),
+                });
+            },
+            /**
+             * Save cache to disk
+             */
+            save() {
+                saveCacheToDisk(state);
+            },
+            /**
+             * Clear cache
+             */
+            clear() {
+                if (state.cleanupInterval) {
+                    clearInterval(state.cleanupInterval);
+                }
+                clearCache(state);
+            },
+            /**
+             * Get cache statistics
+             */
+            getStats() {
+                return getCacheStats(state);
+            },
+        };
+    },
+});
+/**
+ * Save cache to disk
+ */
+function saveCacheToDisk(state) {
+    if (fs.existsSync(state.cacheDir) === false) {
+        fs.mkdirSync(state.cacheDir, { recursive: true });
+    }
+    for (const [key, entry] of state.cache.entries()) {
+        const file = path.join(state.cacheDir, `${key}.json`);
+        fs.writeFileSync(file, JSON.stringify(entry, null, 2));
+    }
+}
+/**
+ * Clear cache
+ */
+function clearCache(state) {
+    state.cache.clear();
+    if (fs.existsSync(state.cacheDir) === true) {
+        fs.rmSync(state.cacheDir, { recursive: true });
+    }
+}
+/**
+ * Get cache statistics
+ */
+function getCacheStats(state) {
+    let diskUsage = 0;
+    if (fs.existsSync(state.cacheDir) === true) {
+        const files = fs.readdirSync(state.cacheDir);
+        for (const file of files) {
+            const stats = fs.statSync(path.join(state.cacheDir, file));
+            diskUsage += stats.size;
+        }
+    }
+    return {
+        size: diskUsage,
+        entries: state.cache.size,
+        diskUsage: formatBytes(diskUsage),
+        keys: Array.from(state.cache.keys()),
+    };
+}
+/**
+ * Format bytes as human-readable
+ */
+function formatBytes(bytes) {
+    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, params) {
+    // Use a more efficient key generation
+    const paramStr = JSON.stringify(params);
+    // Simple hash-like string for the key
+    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) {
+    const truncated = Math.trunc(value);
+    const uint32 = ((truncated % 4294967296) + 4294967296) % 4294967296;
+    return uint32 > 2147483647 ? uint32 - 4294967296 : uint32;
+}
+/**
+ * Load cache from disk
+ */
+function loadFromDisk(state) {
+    if (fs.existsSync(state.cacheDir) === true) {
+        try {
+            const files = fs.readdirSync(state.cacheDir);
+            for (const file of files) {
+                if (file.endsWith('.json') === true) {
+                    const content = fs.readFileSync(path.join(state.cacheDir, file), 'utf-8');
+                    const data = JSON.parse(content);
+                    state.cache.set(file.replace('.json', ''), data);
+                }
+            }
+        }
+        catch (err) {
+            Logger.error(`Failed to load cache from disk: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Lazy Module Loader - Load dependencies only when needed
+ * Sealed namespace for immutability
+ */
+export const LazyLoader = Object.freeze({
+    /**
+     * Create a new lazy loader instance
+     */
+    create() {
+        const modules = new Map();
+        return {
+            /**
+             * Lazy load a module
+             */
+            async load(modulePath) {
+                const cached = modules.get(modulePath);
+                if (cached !== undefined) {
+                    return cached;
+                }
+                try {
+                    const module = await import(modulePath);
+                    modules.set(modulePath, module);
+                    return module;
+                }
+                catch (err) {
+                    throw ErrorFactory.createTryCatchError(`Failed to load module: ${modulePath}`, err);
+                }
+            },
+            /**
+             * Preload modules
+             */
+            async preload(modulePaths) {
+                await Promise.all(modulePaths.map(async (path) => this.load(path)));
+            },
+            /**
+             * Clear loaded modules
+             */
+            clear() {
+                modules.clear();
+            },
+        };
+    },
+});
+/**
+ * Parallel Generator - Run multiple generators in parallel
+ */
+/**
+ * Run generators in parallel batches
+ */
+export async function runBatch(generators, batchSize = 3) {
+    const results = [];
+    for (let i = 0; i < generators.length; i += batchSize) {
+        const batch = generators.slice(i, i + batchSize);
+        const batchResults = await Promise.all(batch.map(async (gen) => gen()));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Run all generators in parallel
+ */
+export async function runAll(generators) {
+    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(fn, options = {}) {
+    const cache = new Map();
+    return ((...args) => {
+        const key = options.keyGenerator === undefined ? JSON.stringify(args) : options.keyGenerator(args);
+        const entry = cache.get(key);
+        if (entry !== undefined) {
+            if (options.ttl === undefined || Date.now() - entry.timestamp < options.ttl) {
+                return entry.result;
+            }
+            cache.delete(key);
+        }
+        const result = fn(...args);
+        cache.set(key, { result, timestamp: Date.now() });
+        return result;
+    });
+}
+export const Memoize = Object.freeze({
+    create: createMemoized,
+});
+/**
+ * Performance Optimizer - Wrapper for optimizations
+ * Sealed namespace for immutability
+ */
+export const PerformanceOptimizer = Object.freeze({
+    /**
+     * Create a new performance optimizer instance
+     */
+    create() {
+        const cache = GenerationCache.create();
+        const lazyLoader = LazyLoader.create();
+        const stats = {
+            cacheHits: 0,
+            cacheMisses: 0,
+            parallelRuns: 0,
+            savedTime: 0,
+        };
+        return {
+            /**
+             * Generate with caching
+             */
+            async generateWithCache(type, params, generatorFn) {
+                return generateWithCache(cache, stats, type, params, generatorFn);
+            },
+            /**
+             * Generate multiple in parallel
+             */
+            async generateInParallel(generators, batchSize) {
+                return generateInParallel(stats, generators, batchSize);
+            },
+            /**
+             * Preload modules
+             */
+            async preloadModules(paths) {
+                await lazyLoader.preload(paths);
+            },
+            /**
+             * Get optimization statistics
+             */
+            getStats() {
+                return getOptimizerStats(cache, stats);
+            },
+            /**
+             * Save cache to disk
+             */
+            saveCache() {
+                cache.save();
+            },
+            /**
+             * Clear everything
+             */
+            clear() {
+                resetOptimizer(cache, lazyLoader, stats);
+            },
+        };
+    },
+});
+/**
+ * Reset optimizer state
+ */
+function resetOptimizer(cache, lazyLoader, stats) {
+    cache.clear();
+    lazyLoader.clear();
+    stats.cacheHits = 0;
+    stats.cacheMisses = 0;
+    stats.parallelRuns = 0;
+    stats.savedTime = 0;
+}
+/**
+ * Generate multiple in parallel
+ */
+async function generateInParallel(stats, generators, batchSize) {
+    stats.parallelRuns++;
+    if (batchSize !== undefined) {
+        return ParallelGenerator.runBatch(generators, batchSize);
+    }
+    return ParallelGenerator.runAll(generators);
+}
+/**
+ * Generate with caching
+ */
+async function generateWithCache(cache, stats, type, params, generatorFn) {
+    // Try cache
+    const cached = cache.get(type, params);
+    if (cached !== null) {
+        stats.cacheHits++;
+        return JSON.parse(cached);
+    }
+    // Generate
+    const startTime = performance.now();
+    const result = await generatorFn();
+    const duration = performance.now() - startTime;
+    // Cache result
+    cache.set(type, params, JSON.stringify(result));
+    stats.cacheMisses++;
+    stats.savedTime += duration;
+    return result;
+}
+/**
+ * Get optimization statistics
+ */
+function getOptimizerStats(cache, stats) {
+    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: cache.getStats(),
+    };
+}
+export default PerformanceOptimizer;

package/src/performance/establish-baseline.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Establish Performance Baseline
+ * Run all code generator benchmarks and save baseline metrics
+ */
+/**
+ * Run baseline and save results
+ */
+export declare function establishBaseline(): Promise<void>;
+//# sourceMappingURL=establish-baseline.d.ts.map

package/src/performance/establish-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"establish-baseline.d.ts","sourceRoot":"","sources":["../../../src/performance/establish-baseline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAYvD"}

package/src/performance/establish-baseline.js

@@ -0,0 +1,55 @@
+/**
+ * Establish Performance Baseline
+ * Run all code generator benchmarks and save baseline metrics
+ */
+import { Logger } from '../config/logger';
+import { fs } from '../node-singletons/index.js';
+import { fileURLToPath } from '../node-singletons/url';
+import { CodeGenerationBenchmark } from './CodeGenerationBenchmark';
+import * as path from 'node:path';
+/**
+ * Run baseline and save results
+ */
+export async function establishBaseline() {
+    Logger.info('📊 Establishing Performance Baseline...');
+    const benchmark = CodeGenerationBenchmark();
+    await benchmark.runAll();
+    // Save baseline
+    const baselineFile = path.join(process.cwd(), 'performance-baseline.json');
+    benchmark.exportResults(baselineFile);
+    Logger.info('✅ Baseline established and saved to performance-baseline.json');
+    Logger.info('📈 Next: Run optimizations and compare results');
+}
+function isMainModuleEsm() {
+    try {
+        const entry = process.argv[1];
+        if (entry === undefined || entry === '')
+            return false;
+        const currentFilePath = fileURLToPath(new URL(import.meta.url));
+        // Use realpathSync to handle symlinks (common on macOS /var -> /private/var)
+        if (!('realpathSync' in fs)) {
+            return path.resolve(entry) === path.resolve(currentFilePath);
+        }
+        try {
+            const realpathSync = fs
+                .realpathSync;
+            return realpathSync(entry) === realpathSync(currentFilePath);
+        }
+        catch (err) {
+            Logger.error('realpathSync failed, falling back to path.resolve', err);
+            return path.resolve(entry) === path.resolve(currentFilePath);
+        }
+    }
+    catch (err) {
+        Logger.error('❌ Baseline failed:', err);
+        return false;
+    }
+}
+const isMainModule = globalThis.__ZINTRUST_ESTABLISH_BASELINE_MAIN__ ??
+    isMainModuleEsm();
+if (isMainModule) {
+    await establishBaseline().catch((err) => {
+        Logger.error('❌ Baseline failed:', err);
+        process.exit(1);
+    });
+}

package/src/profiling/MemoryProfiler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Memory Profiler
+ * Tracks heap memory usage and garbage collection events
+ */
+import { MemoryDelta, MemorySnapshot } from './types';
+export interface IMemoryProfiler {
+    start(): void;
+    end(): MemorySnapshot;
+    delta(): MemoryDelta;
+    getStartSnapshot(): MemorySnapshot | null;
+    getEndSnapshot(): MemorySnapshot | null;
+    getReport(): string;
+}
+/**
+ * MemoryProfiler captures memory usage before and after request execution
+ * Sealed namespace for immutability
+ */
+export declare const MemoryProfiler: Readonly<{
+    /**
+     * Create a new memory profiler instance
+     */
+    create(): IMemoryProfiler;
+    /**
+     * Format memory value as human-readable string
+     */
+    formatBytes(bytes: number): string;
+}>;
+/**
+ * Format memory value as human-readable string
+ */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=MemoryProfiler.d.ts.map

package/src/profiling/MemoryProfiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryProfiler.d.ts","sourceRoot":"","sources":["../../../src/profiling/MemoryProfiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,GAAG,IAAI,cAAc,CAAC;IACtB,KAAK,IAAI,WAAW,CAAC;IACrB,gBAAgB,IAAI,cAAc,GAAG,IAAI,CAAC;IAC1C,cAAc,IAAI,cAAc,GAAG,IAAI,CAAC;IACxC,SAAS,IAAI,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc;IACzB;;OAEG;cACO,eAAe;IAmEzB;;OAEG;uBACgB,MAAM,GAAG,MAAM;EAGlC,CAAC;AAEH;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD"}

package/src/profiling/MemoryProfiler.js

@@ -0,0 +1,84 @@
+/**
+ * Memory Profiler
+ * Tracks heap memory usage and garbage collection events
+ */
+/**
+ * MemoryProfiler captures memory usage before and after request execution
+ * Sealed namespace for immutability
+ */
+export const MemoryProfiler = Object.freeze({
+    /**
+     * Create a new memory profiler instance
+     */
+    create() {
+        let startSnapshot = null;
+        let endSnapshot = null;
+        const captureSnapshot = () => {
+            const mem = process.memoryUsage();
+            return {
+                heapUsed: mem.heapUsed,
+                heapTotal: mem.heapTotal,
+                external: mem.external,
+                rss: mem.rss,
+                timestamp: new Date(),
+            };
+        };
+        const delta = () => {
+            if (!startSnapshot || !endSnapshot) {
+                return { heapUsed: 0, heapTotal: 0, external: 0, rss: 0 };
+            }
+            return {
+                heapUsed: endSnapshot.heapUsed - startSnapshot.heapUsed,
+                heapTotal: endSnapshot.heapTotal - startSnapshot.heapTotal,
+                external: endSnapshot.external - startSnapshot.external,
+                rss: endSnapshot.rss - startSnapshot.rss,
+            };
+        };
+        const profiler = {
+            start() {
+                if (globalThis.gc)
+                    globalThis.gc();
+                startSnapshot = captureSnapshot();
+                endSnapshot = null;
+            },
+            end() {
+                endSnapshot = captureSnapshot();
+                return endSnapshot;
+            },
+            delta,
+            getStartSnapshot() {
+                return startSnapshot;
+            },
+            getEndSnapshot() {
+                return endSnapshot;
+            },
+            getReport() {
+                if (!startSnapshot || !endSnapshot) {
+                    return 'Memory profiling not started or completed';
+                }
+                const d = delta();
+                const lines = ['Memory Profile Report:'];
+                lines.push(`  Heap Used: ${formatBytes(d.heapUsed)}`, `  Heap Total: ${formatBytes(d.heapTotal)}`, `  External: ${formatBytes(d.external)}`, `  RSS: ${formatBytes(d.rss)}`);
+                return lines.join('\n');
+            },
+        };
+        return profiler;
+    },
+    /**
+     * Format memory value as human-readable string
+     */
+    formatBytes(bytes) {
+        return formatBytes(bytes);
+    },
+});
+/**
+ * Format memory value as human-readable string
+ */
+export function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(k));
+    return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+}

package/src/profiling/N1Detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * N+1 Query Pattern Detector
+ * Analyzes query logs to identify N+1 patterns
+ */
+import { IN1Detector } from './types';
+/**\n * N1Detector analyzes query logs to identify N+1 patterns
+ * Groups identical queries and flags those executed 5+ times as critical
+ * Sealed namespace for immutability
+ */
+export declare const N1Detector: Readonly<{
+    /**
+     * Create a new N1Detector instance
+     */
+    create(): IN1Detector;
+}>;
+//# sourceMappingURL=N1Detector.d.ts.map

package/src/profiling/N1Detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"N1Detector.d.ts","sourceRoot":"","sources":["../../../src/profiling/N1Detector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAA4B,MAAM,kBAAkB,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;cACO,WAAW;EAiCrB,CAAC"}