@danielsimonjr/memory-mcp 11.0.1 → 11.1.1

package/dist/utils/WorkerPoolManager.js

@@ -1,420 +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();
-}

package/dist/utils/operationUtils.d.ts

@@ -1,124 +0,0 @@
-/**
- * Operation Utilities
- *
- * Phase 9B: Utilities for long-running operations with progress tracking
- * and cancellation support.
- *
- * @module utils/operationUtils
- */
-import type { ProgressCallback } from './taskScheduler.js';
-/**
- * Check if an operation has been cancelled via AbortSignal.
- * Throws OperationCancelledError if the signal is aborted.
- *
- * @param signal - Optional AbortSignal to check
- * @param operation - Optional operation name for error message
- * @throws OperationCancelledError if signal is aborted
- *
- * @example
- * ```typescript
- * for (const item of items) {
- *   checkCancellation(options?.signal, 'batch processing');
- *   await processItem(item);
- * }
- * ```
- */
-export declare function checkCancellation(signal?: AbortSignal, operation?: string): void;
-/**
- * Create a throttled progress reporter to avoid excessive callback invocations.
- * Returns undefined if no callback is provided.
- *
- * @param callback - Optional progress callback to throttle
- * @param throttleMs - Minimum time between callbacks (default: 100ms)
- * @returns Throttled callback or undefined
- *
- * @example
- * ```typescript
- * const reportProgress = createProgressReporter(options?.onProgress, 50);
- * for (let i = 0; i < total; i++) {
- *   reportProgress?.({ completed: i, total, percentage: (i / total) * 100 });
- * }
- * ```
- */
-export declare function createProgressReporter(callback?: ProgressCallback, throttleMs?: number): ProgressCallback | undefined;
-/**
- * Create a progress object for reporting.
- *
- * @param completed - Number of completed items
- * @param total - Total number of items
- * @param currentTaskId - Optional current task identifier
- * @returns Progress object suitable for ProgressCallback
- *
- * @example
- * ```typescript
- * reportProgress?.(createProgress(50, 100, 'processing entities'));
- * // { completed: 50, total: 100, percentage: 50, currentTaskId: 'processing entities' }
- * ```
- */
-export declare function createProgress(completed: number, total: number, currentTaskId?: string): {
-    completed: number;
-    total: number;
-    percentage: number;
-    currentTaskId?: string;
-};
-/**
- * Phase definition for executeWithPhases.
- */
-export interface PhaseDefinition<T> {
-    /** Phase name (used for progress reporting and cancellation error messages) */
-    name: string;
-    /** Weight of this phase relative to others (higher = more of total progress) */
-    weight: number;
-    /** Executor function that performs the phase work */
-    execute: (phaseProgress: (pct: number) => void) => Promise<T>;
-}
-/**
- * Execute an operation with multiple distinct phases.
- * Useful when an operation has multiple distinct phases with different weights.
- *
- * @param phases - Array of phase definitions with weight and executor
- * @param onProgress - Optional progress callback
- * @param signal - Optional abort signal
- * @returns Array of results from each phase
- * @throws OperationCancelledError if cancelled during any phase
- *
- * @example
- * ```typescript
- * const [parseResult, processResult, saveResult] = await executeWithPhases([
- *   { name: 'parsing', weight: 20, execute: () => parseData() },
- *   { name: 'processing', weight: 60, execute: () => processEntities() },
- *   { name: 'saving', weight: 20, execute: () => saveResults() },
- * ], options?.onProgress, options?.signal);
- * ```
- */
-export declare function executeWithPhases<T>(phases: PhaseDefinition<T>[], onProgress?: ProgressCallback, signal?: AbortSignal): Promise<T[]>;
-/**
- * Execute an operation in batches with progress tracking and cancellation support.
- *
- * @param items - Array of items to process
- * @param batchSize - Size of each batch
- * @param processBatch - Function to process each batch
- * @param onProgress - Optional progress callback
- * @param signal - Optional abort signal
- * @param operationName - Optional operation name for cancellation error
- * @returns Array of results from all batches
- *
- * @example
- * ```typescript
- * const results = await processBatchesWithProgress(
- *   entities,
- *   100,
- *   async (batch) => {
- *     for (const entity of batch) {
- *       await saveEntity(entity);
- *     }
- *     return batch.length;
- *   },
- *   options?.onProgress,
- *   options?.signal,
- *   'createEntities'
- * );
- * ```
- */
-export declare function processBatchesWithProgress<T, R>(items: T[], batchSize: number, processBatch: (batch: T[], batchIndex: number) => Promise<R>, onProgress?: ProgressCallback, signal?: AbortSignal, operationName?: string): Promise<R[]>;
-//# sourceMappingURL=operationUtils.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"operationUtils.d.ts","sourceRoot":"","sources":["../../src/utils/operationUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAIhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,UAAU,GAAE,MAAY,GACvB,gBAAgB,GAAG,SAAS,CAa9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAOlF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,OAAO,EAAE,CAAC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,EAC5B,UAAU,CAAC,EAAE,gBAAgB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,EAAE,CAAC,CAkCd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAAE,CAAC,EACnD,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5D,UAAU,CAAC,EAAE,gBAAgB,EAC7B,MAAM,CAAC,EAAE,WAAW,EACpB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}