@danielsimonjr/memoryjs 1.0.0 → 1.1.0

package/dist/utils/WorkerPoolManager.js

@@ -1,421 +0,0 @@
-/**
- * Worker Pool Manager
- *
- * Phase 12 Sprint 2: Unified worker pool management for all parallelizable operations.
- * Provides centralized lifecycle management, configuration, and statistics.
- *
- * @module utils/WorkerPoolManager
- */
-import workerpool from '@danielsimonjr/workerpool';
-/**
- * Default configuration values.
- */
-const DEFAULT_CONFIG = {
-    maxWorkers: Math.max(1, workerpool.cpus - 1),
-    workerType: 'thread',
-    workerPath: '',
-    minParallelSize: 200,
-    defaultTimeout: 30000,
-};
-/**
- * WorkerPoolManager - Unified worker pool management
- *
- * Provides centralized management of worker pools for parallel processing.
- * Features:
- * - Named pool registration with automatic lifecycle management
- * - Pool cleanup on process exit
- * - Statistics tracking per pool
- * - Event callbacks for monitoring
- *
- * @example
- * ```typescript
- * const manager = WorkerPoolManager.getInstance();
- *
- * // Get or create a pool
- * const pool = manager.getPool('fuzzySearch', {
- *   maxWorkers: 4,
- *   workerPath: '/path/to/worker.js'
- * });
- *
- * // Execute task
- * const result = await pool.exec('searchEntities', [data]);
- *
- * // Get statistics
- * const stats = manager.getPoolStats('fuzzySearch');
- *
- * // Shutdown all pools on exit
- * await manager.shutdownAll();
- * ```
- */
-export class WorkerPoolManager {
-    static instance = null;
-    pools = new Map();
-    eventCallbacks = [];
-    isShuttingDown = false;
-    shutdownRegistered = false;
-    /**
-     * Private constructor for singleton pattern.
-     */
-    constructor() {
-        this.registerShutdownHandlers();
-    }
-    /**
-     * Get the singleton instance of WorkerPoolManager.
-     *
-     * @returns The WorkerPoolManager instance
-     */
-    static getInstance() {
-        if (!WorkerPoolManager.instance) {
-            WorkerPoolManager.instance = new WorkerPoolManager();
-        }
-        return WorkerPoolManager.instance;
-    }
-    /**
-     * Reset the singleton instance (primarily for testing).
-     */
-    static resetInstance() {
-        if (WorkerPoolManager.instance) {
-            WorkerPoolManager.instance.shutdownAll().catch(() => {
-                // Ignore errors during reset
-            });
-            WorkerPoolManager.instance = null;
-        }
-    }
-    /**
-     * Register process exit handlers for cleanup.
-     */
-    registerShutdownHandlers() {
-        if (this.shutdownRegistered)
-            return;
-        this.shutdownRegistered = true;
-        const shutdownHandler = () => {
-            if (!this.isShuttingDown) {
-                this.shutdownAllSync();
-            }
-        };
-        // Register for various exit signals
-        process.on('exit', shutdownHandler);
-        process.on('SIGINT', () => {
-            this.shutdownAll().then(() => process.exit(0)).catch(() => process.exit(1));
-        });
-        process.on('SIGTERM', () => {
-            this.shutdownAll().then(() => process.exit(0)).catch(() => process.exit(1));
-        });
-        process.on('uncaughtException', (err) => {
-            console.error('Uncaught exception:', err);
-            this.shutdownAllSync();
-            process.exit(1);
-        });
-    }
-    /**
-     * Get or create a named worker pool.
-     *
-     * If a pool with the given ID exists, returns the existing pool.
-     * Otherwise, creates a new pool with the provided configuration.
-     *
-     * @param poolId - Unique identifier for the pool
-     * @param config - Pool configuration options
-     * @returns The worker pool instance
-     */
-    getPool(poolId, config = {}) {
-        const existing = this.pools.get(poolId);
-        if (existing) {
-            return existing.pool;
-        }
-        return this.createPool(poolId, config);
-    }
-    /**
-     * Create a new worker pool with the given ID.
-     *
-     * @param poolId - Unique identifier for the pool
-     * @param config - Pool configuration options
-     * @returns The newly created worker pool
-     * @throws Error if a pool with the same ID already exists
-     */
-    createPool(poolId, config = {}) {
-        if (this.pools.has(poolId)) {
-            throw new Error(`Pool with ID '${poolId}' already exists`);
-        }
-        const mergedConfig = { ...DEFAULT_CONFIG, ...config };
-        // Create pool options with inline type definition
-        // Using inline type since WorkerPoolOptions is not directly exported
-        const poolOptions = {
-            maxWorkers: mergedConfig.maxWorkers,
-            workerType: mergedConfig.workerType,
-        };
-        // Add worker thread options for ESM support
-        if (mergedConfig.workerType === 'thread') {
-            poolOptions.workerThreadOpts = { type: 'module' };
-        }
-        // Create pool with or without worker script
-        let pool;
-        if (mergedConfig.workerPath) {
-            pool = workerpool.pool(mergedConfig.workerPath, poolOptions);
-        }
-        else {
-            pool = workerpool.pool(poolOptions);
-        }
-        const entry = {
-            pool,
-            config: mergedConfig,
-            createdAt: Date.now(),
-            totalTasksExecuted: 0,
-            totalExecutionTime: 0,
-        };
-        this.pools.set(poolId, entry);
-        this.emitEvent(poolId, 'created');
-        return pool;
-    }
-    /**
-     * Check if a pool with the given ID exists.
-     *
-     * @param poolId - Pool identifier to check
-     * @returns True if pool exists
-     */
-    hasPool(poolId) {
-        return this.pools.has(poolId);
-    }
-    /**
-     * Get the configuration for a pool.
-     *
-     * @param poolId - Pool identifier
-     * @returns Pool configuration or undefined if not found
-     */
-    getPoolConfig(poolId) {
-        const entry = this.pools.get(poolId);
-        return entry ? { ...entry.config } : undefined;
-    }
-    /**
-     * Get extended statistics for a pool.
-     *
-     * @param poolId - Pool identifier
-     * @returns Extended pool statistics or undefined if not found
-     */
-    getPoolStats(poolId) {
-        const entry = this.pools.get(poolId);
-        if (!entry)
-            return undefined;
-        const baseStats = entry.pool.stats();
-        return {
-            ...baseStats,
-            poolId,
-            createdAt: entry.createdAt,
-            totalTasksExecuted: entry.totalTasksExecuted,
-            totalExecutionTime: entry.totalExecutionTime,
-            averageExecutionTime: entry.totalTasksExecuted > 0
-                ? entry.totalExecutionTime / entry.totalTasksExecuted
-                : 0,
-        };
-    }
-    /**
-     * Get statistics for all pools.
-     *
-     * @returns Map of pool IDs to their statistics
-     */
-    getAllPoolStats() {
-        const stats = new Map();
-        for (const poolId of this.pools.keys()) {
-            const poolStats = this.getPoolStats(poolId);
-            if (poolStats) {
-                stats.set(poolId, poolStats);
-            }
-        }
-        return stats;
-    }
-    /**
-     * Record task execution for statistics tracking.
-     *
-     * @param poolId - Pool identifier
-     * @param executionTimeMs - Task execution time in milliseconds
-     */
-    recordTaskExecution(poolId, executionTimeMs) {
-        const entry = this.pools.get(poolId);
-        if (entry) {
-            entry.totalTasksExecuted++;
-            entry.totalExecutionTime += executionTimeMs;
-        }
-    }
-    /**
-     * Execute a task on a pool with automatic statistics tracking.
-     *
-     * @template T - Result type
-     * @param poolId - Pool identifier
-     * @param method - Method name to execute (for worker script pools) or inline function
-     * @param args - Arguments to pass to the method/function
-     * @param timeout - Optional timeout in milliseconds
-     * @returns Promise resolving to the task result
-     */
-    async executeTask(poolId, method, args = [], timeout) {
-        const entry = this.pools.get(poolId);
-        if (!entry) {
-            throw new Error(`Pool '${poolId}' not found`);
-        }
-        const effectiveTimeout = timeout ?? entry.config.defaultTimeout ?? DEFAULT_CONFIG.defaultTimeout;
-        const startTime = Date.now();
-        try {
-            let result;
-            if (typeof method === 'string') {
-                // Execute named method from worker script
-                result = await entry.pool.exec(method, args).timeout(effectiveTimeout);
-            }
-            else {
-                // Execute inline function
-                result = await entry.pool.exec(method, args).timeout(effectiveTimeout);
-            }
-            const executionTime = Date.now() - startTime;
-            this.recordTaskExecution(poolId, executionTime);
-            return result;
-        }
-        catch (error) {
-            const executionTime = Date.now() - startTime;
-            this.recordTaskExecution(poolId, executionTime);
-            throw error;
-        }
-    }
-    /**
-     * Shutdown a specific pool.
-     *
-     * @param poolId - Pool identifier
-     * @param force - If true, forcefully terminate workers (default: false)
-     * @returns Promise resolving when shutdown is complete
-     */
-    async shutdownPool(poolId, force = false) {
-        const entry = this.pools.get(poolId);
-        if (!entry)
-            return;
-        try {
-            await entry.pool.terminate(force);
-            this.emitEvent(poolId, 'shutdown');
-        }
-        catch (error) {
-            this.emitEvent(poolId, 'error', error);
-            throw error;
-        }
-        finally {
-            this.pools.delete(poolId);
-        }
-    }
-    /**
-     * Shutdown all pools asynchronously.
-     *
-     * @param force - If true, forcefully terminate workers (default: false)
-     * @returns Promise resolving when all pools are shut down
-     */
-    async shutdownAll(force = false) {
-        if (this.isShuttingDown)
-            return;
-        this.isShuttingDown = true;
-        const shutdownPromises = [];
-        for (const poolId of this.pools.keys()) {
-            shutdownPromises.push(this.shutdownPool(poolId, force));
-        }
-        try {
-            await Promise.allSettled(shutdownPromises);
-        }
-        finally {
-            this.pools.clear();
-            this.isShuttingDown = false;
-        }
-    }
-    /**
-     * Synchronous shutdown for process exit handlers.
-     * Forces immediate termination of all pools.
-     */
-    shutdownAllSync() {
-        if (this.isShuttingDown)
-            return;
-        this.isShuttingDown = true;
-        for (const [poolId, entry] of this.pools) {
-            try {
-                entry.pool.terminate(true);
-                this.emitEvent(poolId, 'shutdown');
-            }
-            catch {
-                // Ignore errors during sync shutdown
-            }
-        }
-        this.pools.clear();
-        this.isShuttingDown = false;
-    }
-    /**
-     * Register an event callback for pool events.
-     *
-     * @param callback - Callback function to invoke on events
-     * @returns Unsubscribe function
-     */
-    onEvent(callback) {
-        this.eventCallbacks.push(callback);
-        return () => {
-            const index = this.eventCallbacks.indexOf(callback);
-            if (index >= 0) {
-                this.eventCallbacks.splice(index, 1);
-            }
-        };
-    }
-    /**
-     * Emit an event to all registered callbacks.
-     */
-    emitEvent(poolId, event, data) {
-        for (const callback of this.eventCallbacks) {
-            try {
-                callback(poolId, event, data);
-            }
-            catch {
-                // Ignore callback errors
-            }
-        }
-    }
-    /**
-     * Get the number of active pools.
-     *
-     * @returns Number of pools currently managed
-     */
-    get poolCount() {
-        return this.pools.size;
-    }
-    /**
-     * Get all pool IDs.
-     *
-     * @returns Array of pool identifiers
-     */
-    getPoolIds() {
-        return Array.from(this.pools.keys());
-    }
-    /**
-     * Check if the minimum parallel size threshold is met.
-     *
-     * @param poolId - Pool identifier
-     * @param size - Size of the data to process
-     * @returns True if size meets or exceeds minimum threshold
-     */
-    shouldUseParallel(poolId, size) {
-        const entry = this.pools.get(poolId);
-        const minSize = entry?.config.minParallelSize ?? DEFAULT_CONFIG.minParallelSize;
-        return size >= minSize;
-    }
-    /**
-     * Get the default configuration values.
-     *
-     * @returns Copy of default configuration
-     */
-    static getDefaultConfig() {
-        return { ...DEFAULT_CONFIG };
-    }
-    /**
-     * Get the CPU count available for workers.
-     *
-     * @returns Number of CPUs
-     */
-    static getCpuCount() {
-        return workerpool.cpus;
-    }
-}
-/**
- * Convenience function to get the WorkerPoolManager instance.
- *
- * @returns The WorkerPoolManager singleton
- */
-export function getWorkerPoolManager() {
-    return WorkerPoolManager.getInstance();
-}
-//# sourceMappingURL=WorkerPoolManager.js.map

package/dist/utils/WorkerPoolManager.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"WorkerPoolManager.js","sourceRoot":"","sources":["../../src/utils/WorkerPoolManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,UAAU,MAAM,2BAA2B,CAAC;AAmDnD;;GAEG;AACH,MAAM,cAAc,GAA+B;IACjD,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC;IAC5C,UAAU,EAAE,QAAQ;IACpB,UAAU,EAAE,EAAE;IACd,eAAe,EAAE,GAAG;IACpB,cAAc,EAAE,KAAK;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAC,QAAQ,GAA6B,IAAI,CAAC;IAEjD,KAAK,GAA2B,IAAI,GAAG,EAAE,CAAC;IAC1C,cAAc,GAAwB,EAAE,CAAC;IACzC,cAAc,GAAG,KAAK,CAAC;IACvB,kBAAkB,GAAG,KAAK,CAAC;IAEnC;;OAEG;IACH;QACE,IAAI,CAAC,wBAAwB,EAAE,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC;YAChC,iBAAiB,CAAC,QAAQ,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACvD,CAAC;QACD,OAAO,iBAAiB,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa;QAClB,IAAI,iBAAiB,CAAC,QAAQ,EAAE,CAAC;YAC/B,iBAAiB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBAClD,6BAA6B;YAC/B,CAAC,CAAC,CAAC;YACH,iBAAiB,CAAC,QAAQ,GAAG,IAAI,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;OAEG;IACK,wBAAwB;QAC9B,IAAI,IAAI,CAAC,kBAAkB;YAAE,OAAO;QACpC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAE/B,MAAM,eAAe,GAAG,GAAG,EAAE;YAC3B,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;gBACzB,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,CAAC;QACH,CAAC,CAAC;QAEF,oCAAoC;QACpC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACpC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACxB,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;YACzB,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;YACtC,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAc,EAAE,SAA2B,EAAE;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,MAAc,EAAE,SAA2B,EAAE;QACtD,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,kBAAkB,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,YAAY,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;QAEtD,kDAAkD;QAClD,qEAAqE;QACrE,MAAM,WAAW,GAIb;YACF,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,UAAU,EAAE,YAAY,CAAC,UAAU;SACpC,CAAC;QAEF,4CAA4C;QAC5C,IAAI,YAAY,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YACzC,WAAW,CAAC,gBAAgB,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACpD,CAAC;QAED,4CAA4C;QAC5C,IAAI,IAAU,CAAC;QACf,IAAI,YAAY,CAAC,UAAU,EAAE,CAAC;YAC5B,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,KAAK,GAAc;YACvB,IAAI;YACJ,MAAM,EAAE,YAAY;YACpB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,kBAAkB,EAAE,CAAC;YACrB,kBAAkB,EAAE,CAAC;SACtB,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAElC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,MAAc;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,MAAc;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACjD,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,MAAc;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO;YACL,GAAG,SAAS;YACZ,MAAM;YACN,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;YAC5C,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;YAC5C,oBAAoB,EAClB,KAAK,CAAC,kBAAkB,GAAG,CAAC;gBAC1B,CAAC,CAAC,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,kBAAkB;gBACrD,CAAC,CAAC,CAAC;SACR,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,eAAe;QACb,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;QACnD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC5C,IAAI,SAAS,EAAE,CAAC;gBACd,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,MAAc,EAAE,eAAuB;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,kBAAkB,EAAE,CAAC;YAC3B,KAAK,CAAC,kBAAkB,IAAI,eAAe,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CACf,MAAc,EACd,MAA4C,EAC5C,OAAkB,EAAE,EACpB,OAAgB;QAEhB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,SAAS,MAAM,aAAa,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,gBAAgB,GAAG,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,cAAc,IAAI,cAAc,CAAC,cAAc,CAAC;QACjG,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,IAAI,CAAC;YACH,IAAI,MAAS,CAAC;YACd,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,0CAA0C;gBAC1C,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAM,CAAC;YAC9E,CAAC;iBAAM,CAAC;gBACN,0BAA0B;gBAC1B,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAM,CAAC;YAC9E,CAAC;YAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC7C,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YAEhD,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC7C,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YAChD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc,EAAE,KAAK,GAAG,KAAK;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YACvC,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,WAAW,CAAC,KAAK,GAAG,KAAK;QAC7B,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAE3B,MAAM,gBAAgB,GAAoB,EAAE,CAAC;QAC7C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACvC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAC1D,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,eAAe;QACrB,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAE3B,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACzC,IAAI,CAAC;gBACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YACrC,CAAC;YAAC,MAAM,CAAC;gBACP,qCAAqC;YACvC,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,QAA2B;QACjC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,GAAG,EAAE;YACV,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACvC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,MAAc,EAAE,KAAuC,EAAE,IAAc;QACvF,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,MAAc,EAAE,IAAY;QAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM,CAAC,eAAe,IAAI,cAAc,CAAC,eAAe,CAAC;QAChF,OAAO,IAAI,IAAI,OAAO,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,UAAU,CAAC,IAAI,CAAC;IACzB,CAAC;;AAGH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,iBAAiB,CAAC,WAAW,EAAE,CAAC;AACzC,CAAC"}

package/dist/utils/compressedCache.d.ts

@@ -1,221 +0,0 @@
-/**
- * Compressed Cache Utility
- *
- * Provides an LRU cache with automatic compression of old entries.
- * Reduces memory footprint for large knowledge graphs (50k+ entities).
- *
- * Uses synchronous brotli compression/decompression for cache operations
- * to avoid async complexity in hot paths.
- *
- * Phase 3 Sprint 5: Archive & Cache Compression
- *
- * @module utils/compressedCache
- */
-import type { Entity } from '../types/index.js';
-/**
- * Options for CompressedCache configuration.
- */
-export interface CompressedCacheOptions {
-    /**
-     * Maximum number of uncompressed (hot) entries to keep.
-     * Entries beyond this limit may be compressed.
-     * @default 1000
-     */
-    maxUncompressed?: number;
-    /**
-     * Time in milliseconds before an entry is eligible for compression.
-     * Entries accessed within this time window stay uncompressed.
-     * @default 300000 (5 minutes)
-     */
-    compressionThresholdMs?: number;
-    /**
-     * Whether to enable automatic compression.
-     * If false, entries are never automatically compressed.
-     * @default true
-     */
-    autoCompress?: boolean;
-    /**
-     * Minimum entry size in bytes before compression is applied.
-     * Entries smaller than this are not compressed (overhead exceeds benefit).
-     * Phase 12 Sprint 6: Adaptive compression.
-     * @default 256
-     */
-    minCompressionSize?: number;
-    /**
-     * Minimum compression ratio to keep entry compressed.
-     * If compression achieves less than this ratio, entry stays uncompressed.
-     * Phase 12 Sprint 6: Adaptive compression.
-     * @default 0.7 (30% reduction minimum)
-     */
-    minCompressionRatio?: number;
-}
-/**
- * Statistics about the cache state.
- */
-export interface CompressedCacheStats {
-    /** Total number of entries in the cache */
-    total: number;
-    /** Number of compressed entries */
-    compressed: number;
-    /** Number of uncompressed (hot) entries */
-    uncompressed: number;
-    /** Estimated memory saved by compression in bytes */
-    memorySaved: number;
-    /** Total original size of all entries in bytes */
-    totalOriginalSize: number;
-    /** Total compressed size in bytes */
-    totalCompressedSize: number;
-    /** Cache hit count since creation */
-    hits: number;
-    /** Cache miss count since creation */
-    misses: number;
-    /** Number of compressions performed */
-    compressions: number;
-    /** Number of decompressions performed */
-    decompressions: number;
-    /** Phase 12 Sprint 6: Number of entries skipped due to size */
-    skippedSmallEntries: number;
-    /** Phase 12 Sprint 6: Number of entries skipped due to poor ratio */
-    skippedPoorRatio: number;
-    /** Phase 12 Sprint 6: Average compression ratio (0-1) */
-    avgCompressionRatio: number;
-    /** Phase 12 Sprint 6: Estimated memory usage in bytes */
-    estimatedMemoryBytes: number;
-}
-/**
- * LRU cache with automatic compression of old entries.
- *
- * Reduces memory footprint by compressing infrequently accessed entries
- * using brotli compression. Hot (recently accessed) entries stay
- * uncompressed for fast access.
- *
- * @example
- * ```typescript
- * const cache = new CompressedCache({
- *   maxUncompressed: 500,
- *   compressionThresholdMs: 60000 // 1 minute
- * });
- *
- * // Store entity
- * cache.set('Alice', { name: 'Alice', entityType: 'person', observations: [] });
- *
- * // Retrieve entity (decompresses if needed)
- * const entity = cache.get('Alice');
- *
- * // Check stats
- * const stats = cache.getStats();
- * console.log(`Memory saved: ${stats.memorySaved} bytes`);
- * ```
- */
-export declare class CompressedCache {
-    private _entryMap;
-    private readonly maxUncompressed;
-    private readonly compressionThresholdMs;
-    private readonly autoCompress;
-    private readonly minCompressionSize;
-    private readonly minCompressionRatio;
-    private hits;
-    private misses;
-    private compressions;
-    private decompressions;
-    private skippedSmallEntries;
-    private skippedPoorRatio;
-    private compressionRatios;
-    constructor(options?: CompressedCacheOptions);
-    /**
-     * Get an entity from the cache.
-     *
-     * If the entity is compressed, it will be decompressed on access.
-     * The entry is marked as recently accessed to prevent re-compression.
-     *
-     * @param name - Entity name to retrieve
-     * @returns The entity if found, undefined otherwise
-     */
-    get(name: string): Entity | undefined;
-    /**
-     * Store an entity in the cache.
-     *
-     * Entries are stored uncompressed initially. Old entries may be
-     * compressed automatically based on cache settings.
-     *
-     * @param name - Entity name (key)
-     * @param entity - Entity to store
-     */
-    set(name: string, entity: Entity): void;
-    /**
-     * Check if an entity exists in the cache.
-     *
-     * @param name - Entity name to check
-     * @returns True if entity exists in cache
-     */
-    has(name: string): boolean;
-    /**
-     * Delete an entity from the cache.
-     *
-     * @param name - Entity name to delete
-     * @returns True if entity was deleted, false if not found
-     */
-    delete(name: string): boolean;
-    /**
-     * Clear all entries from the cache.
-     */
-    clear(): void;
-    /**
-     * Get the number of entries in the cache.
-     */
-    get size(): number;
-    /**
-     * Get all entity names in the cache.
-     */
-    keys(): IterableIterator<string>;
-    /**
-     * Get comprehensive cache statistics.
-     *
-     * @returns Statistics about cache state and performance
-     */
-    getStats(): CompressedCacheStats;
-    /**
-     * Force compression of entries older than the threshold.
-     *
-     * Called automatically after set() when autoCompress is enabled.
-     * Can be called manually to trigger compression on demand.
-     *
-     * @returns Number of entries compressed
-     */
-    compressOldEntries(): number;
-    /**
-     * Compress old entries if we're over the uncompressed limit.
-     *
-     * @param force - If true, compress regardless of limit
-     * @returns Number of entries compressed
-     */
-    private maybeCompressOldEntries;
-    /**
-     * Decompress all entries in the cache.
-     *
-     * Useful when preparing for bulk operations or export.
-     *
-     * @returns Number of entries decompressed
-     */
-    decompressAll(): number;
-    /**
-     * Get all entities from the cache (decompressing as needed).
-     *
-     * @returns Array of all entities in the cache
-     */
-    getAllEntities(): Entity[];
-    /**
-     * Iterate over all entries with their compression status.
-     *
-     * Does not decompress entries - useful for inspection.
-     *
-     * @yields Entry information without decompressing
-     */
-    entries(): IterableIterator<{
-        name: string;
-        compressed: boolean;
-        originalSize: number;
-        lastAccessed: number;
-    }>;
-}
-//# sourceMappingURL=compressedCache.d.ts.map

package/dist/utils/compressedCache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compressedCache.d.ts","sourceRoot":"","sources":["../../src/utils/compressedCache.ts"],"names":[],"mappings":"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"}