@danielsimonjr/memory-mcp 0.47.1 → 9.8.0

package/dist/utils/operationUtils.js

@@ -0,0 +1,175 @@
+/**
+ * Operation Utilities
+ *
+ * Phase 9B: Utilities for long-running operations with progress tracking
+ * and cancellation support.
+ *
+ * @module utils/operationUtils
+ */
+import { OperationCancelledError } from './errors.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 function checkCancellation(signal, operation) {
+    if (signal?.aborted) {
+        throw new OperationCancelledError(operation);
+    }
+}
+/**
+ * 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 function createProgressReporter(callback, throttleMs = 100) {
+    if (!callback)
+        return undefined;
+    let lastCallTime = 0;
+    return (progress) => {
+        const now = Date.now();
+        // Always report 0% and 100%
+        if (progress.percentage === 0 || progress.percentage >= 100 || now - lastCallTime >= throttleMs) {
+            lastCallTime = now;
+            callback(progress);
+        }
+    };
+}
+/**
+ * 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 function createProgress(completed, total, currentTaskId) {
+    return {
+        completed,
+        total,
+        percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+        currentTaskId,
+    };
+}
+/**
+ * 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 async function executeWithPhases(phases, onProgress, signal) {
+    const totalWeight = phases.reduce((sum, p) => sum + p.weight, 0);
+    let completedWeight = 0;
+    const results = [];
+    for (const phase of phases) {
+        checkCancellation(signal, phase.name);
+        const phaseStartWeight = completedWeight;
+        const phaseProgress = (phasePct) => {
+            if (onProgress) {
+                const overallPct = ((phaseStartWeight + (phase.weight * phasePct / 100)) / totalWeight) * 100;
+                onProgress({
+                    completed: Math.round(overallPct),
+                    total: 100,
+                    percentage: Math.round(overallPct),
+                    currentTaskId: phase.name,
+                });
+            }
+        };
+        const result = await phase.execute(phaseProgress);
+        results.push(result);
+        completedWeight += phase.weight;
+    }
+    // Report 100% completion
+    onProgress?.({
+        completed: 100,
+        total: 100,
+        percentage: 100,
+    });
+    return results;
+}
+/**
+ * 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 async function processBatchesWithProgress(items, batchSize, processBatch, onProgress, signal, operationName) {
+    const results = [];
+    const total = items.length;
+    let processed = 0;
+    const reportProgress = createProgressReporter(onProgress);
+    reportProgress?.(createProgress(0, total, operationName));
+    for (let i = 0; i < items.length; i += batchSize) {
+        checkCancellation(signal, operationName);
+        const batch = items.slice(i, i + batchSize);
+        const result = await processBatch(batch, Math.floor(i / batchSize));
+        results.push(result);
+        processed += batch.length;
+        reportProgress?.(createProgress(processed, total, operationName));
+    }
+    reportProgress?.(createProgress(total, total, operationName));
+    return results;
+}

package/dist/utils/parallelUtils.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Parallel Utilities
+ *
+ * Utilities for parallel array operations using workerpool.
+ * Phase 8 Sprint 3: Parallel array operations for improved performance.
+ *
+ * @module utils/parallelUtils
+ */
+import workerpool from '@danielsimonjr/workerpool';
+/**
+ * Shutdown the shared worker pool and clean up resources.
+ * Should be called when parallel utilities are no longer needed.
+ */
+export declare function shutdownParallelUtils(): Promise<void>;
+/**
+ * Map items in parallel using workerpool.
+ *
+ * Splits the array into chunks and processes each chunk in a worker thread.
+ * Falls back to single-threaded for small arrays (< MIN_PARALLEL_SIZE).
+ *
+ * **Note:** The mapping function must be serializable (no closures, external variables).
+ * Due to ESM/worker thread compatibility issues, this may fall back to single-threaded
+ * execution in some environments (e.g., vitest test runner).
+ *
+ * @template T - Input item type
+ * @template R - Output item type
+ * @param items - Array of items to map
+ * @param fn - Mapping function (must be serializable)
+ * @param chunkSize - Optional chunk size (default: DEFAULT_CHUNK_SIZE)
+ * @returns Promise resolving to array of mapped results
+ *
+ * @example
+ * ```typescript
+ * // Map numbers to their squares
+ * const numbers = [1, 2, 3, 4, 5];
+ * const squared = await parallelMap(numbers, (n: number) => n * n);
+ * // Result: [1, 4, 9, 16, 25]
+ * ```
+ */
+export declare function parallelMap<T, R>(items: T[], fn: (item: T) => R, chunkSize?: number): Promise<R[]>;
+/**
+ * Filter items in parallel using workerpool.
+ *
+ * Splits the array into chunks and processes each chunk in a worker thread.
+ * Falls back to single-threaded for small arrays (< MIN_PARALLEL_SIZE).
+ *
+ * **Note:** The predicate function must be serializable (no closures, external variables).
+ * Due to ESM/worker thread compatibility issues, this may fall back to single-threaded
+ * execution in some environments (e.g., vitest test runner).
+ *
+ * @template T - Item type
+ * @param items - Array of items to filter
+ * @param predicate - Filter predicate (must be serializable)
+ * @param chunkSize - Optional chunk size (default: DEFAULT_CHUNK_SIZE)
+ * @returns Promise resolving to filtered array
+ *
+ * @example
+ * ```typescript
+ * // Filter even numbers
+ * const numbers = [1, 2, 3, 4, 5, 6];
+ * const evens = await parallelFilter(numbers, (n: number) => n % 2 === 0);
+ * // Result: [2, 4, 6]
+ * ```
+ */
+export declare function parallelFilter<T>(items: T[], predicate: (item: T) => boolean, chunkSize?: number): Promise<T[]>;
+/**
+ * Get statistics about the worker pool.
+ *
+ * @returns Pool statistics or null if pool is not initialized
+ */
+export declare function getPoolStats(): workerpool.PoolStats | null;
+//# sourceMappingURL=parallelUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallelUtils.d.ts","sourceRoot":"","sources":["../../src/utils/parallelUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,UAAU,MAAM,2BAA2B,CAAC;AAoCnD;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAClB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,CAAC,EAAE,CAAC,CAwCd;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,EAC/B,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,CAAC,EAAE,CAAC,CAwCd;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAAC,SAAS,GAAG,IAAI,CAK1D"}

package/dist/utils/parallelUtils.js

@@ -0,0 +1,169 @@
+/**
+ * Parallel Utilities
+ *
+ * Utilities for parallel array operations using workerpool.
+ * Phase 8 Sprint 3: Parallel array operations for improved performance.
+ *
+ * @module utils/parallelUtils
+ */
+import workerpool from '@danielsimonjr/workerpool';
+/**
+ * Default chunk size for parallel operations.
+ * Can be overridden per operation.
+ */
+const DEFAULT_CHUNK_SIZE = 100;
+/**
+ * Minimum array size to activate parallel processing.
+ * For smaller arrays, single-threaded is more efficient due to worker overhead.
+ */
+const MIN_PARALLEL_SIZE = 200;
+/**
+ * Shared worker pool instance for all parallel utilities.
+ * Initialized lazily on first use.
+ */
+let sharedPool = null;
+/**
+ * Get or create the shared worker pool.
+ * Uses inline worker execution (no separate worker file needed).
+ *
+ * @returns Worker pool instance
+ */
+function getPool() {
+    if (!sharedPool) {
+        sharedPool = workerpool.pool({
+            maxWorkers: Math.max(1, workerpool.cpus - 1),
+            workerType: 'thread',
+        });
+    }
+    return sharedPool;
+}
+/**
+ * Shutdown the shared worker pool and clean up resources.
+ * Should be called when parallel utilities are no longer needed.
+ */
+export async function shutdownParallelUtils() {
+    if (sharedPool) {
+        await sharedPool.terminate();
+        sharedPool = null;
+    }
+}
+/**
+ * Map items in parallel using workerpool.
+ *
+ * Splits the array into chunks and processes each chunk in a worker thread.
+ * Falls back to single-threaded for small arrays (< MIN_PARALLEL_SIZE).
+ *
+ * **Note:** The mapping function must be serializable (no closures, external variables).
+ * Due to ESM/worker thread compatibility issues, this may fall back to single-threaded
+ * execution in some environments (e.g., vitest test runner).
+ *
+ * @template T - Input item type
+ * @template R - Output item type
+ * @param items - Array of items to map
+ * @param fn - Mapping function (must be serializable)
+ * @param chunkSize - Optional chunk size (default: DEFAULT_CHUNK_SIZE)
+ * @returns Promise resolving to array of mapped results
+ *
+ * @example
+ * ```typescript
+ * // Map numbers to their squares
+ * const numbers = [1, 2, 3, 4, 5];
+ * const squared = await parallelMap(numbers, (n: number) => n * n);
+ * // Result: [1, 4, 9, 16, 25]
+ * ```
+ */
+export async function parallelMap(items, fn, chunkSize = DEFAULT_CHUNK_SIZE) {
+    // Fall back to single-threaded for small arrays
+    if (items.length < MIN_PARALLEL_SIZE) {
+        return items.map(fn);
+    }
+    try {
+        const pool = getPool();
+        // Split items into chunks
+        const chunks = [];
+        for (let i = 0; i < items.length; i += chunkSize) {
+            chunks.push(items.slice(i, i + chunkSize));
+        }
+        // Convert function to string for serialization
+        const fnString = fn.toString();
+        // Process chunks in parallel using inline function execution
+        const results = await Promise.all(chunks.map(chunk => pool.exec((chunkData, fnStr) => {
+            // Reconstruct function from string
+            // eslint-disable-next-line no-new-func
+            const mapFn = new Function('return ' + fnStr)();
+            return chunkData.map(mapFn);
+        }, [chunk, fnString])));
+        // Flatten results
+        return results.flat();
+    }
+    catch (error) {
+        // Fall back to single-threaded if worker execution fails
+        // (e.g., in test environments with ESM/worker compatibility issues)
+        return items.map(fn);
+    }
+}
+/**
+ * Filter items in parallel using workerpool.
+ *
+ * Splits the array into chunks and processes each chunk in a worker thread.
+ * Falls back to single-threaded for small arrays (< MIN_PARALLEL_SIZE).
+ *
+ * **Note:** The predicate function must be serializable (no closures, external variables).
+ * Due to ESM/worker thread compatibility issues, this may fall back to single-threaded
+ * execution in some environments (e.g., vitest test runner).
+ *
+ * @template T - Item type
+ * @param items - Array of items to filter
+ * @param predicate - Filter predicate (must be serializable)
+ * @param chunkSize - Optional chunk size (default: DEFAULT_CHUNK_SIZE)
+ * @returns Promise resolving to filtered array
+ *
+ * @example
+ * ```typescript
+ * // Filter even numbers
+ * const numbers = [1, 2, 3, 4, 5, 6];
+ * const evens = await parallelFilter(numbers, (n: number) => n % 2 === 0);
+ * // Result: [2, 4, 6]
+ * ```
+ */
+export async function parallelFilter(items, predicate, chunkSize = DEFAULT_CHUNK_SIZE) {
+    // Fall back to single-threaded for small arrays
+    if (items.length < MIN_PARALLEL_SIZE) {
+        return items.filter(predicate);
+    }
+    try {
+        const pool = getPool();
+        // Split items into chunks
+        const chunks = [];
+        for (let i = 0; i < items.length; i += chunkSize) {
+            chunks.push(items.slice(i, i + chunkSize));
+        }
+        // Convert function to string for serialization
+        const predicateString = predicate.toString();
+        // Process chunks in parallel using inline function execution
+        const results = await Promise.all(chunks.map(chunk => pool.exec((chunkData, predicateStr) => {
+            // Reconstruct function from string
+            // eslint-disable-next-line no-new-func
+            const filterFn = new Function('return ' + predicateStr)();
+            return chunkData.filter(filterFn);
+        }, [chunk, predicateString])));
+        // Flatten results
+        return results.flat();
+    }
+    catch (error) {
+        // Fall back to single-threaded if worker execution fails
+        // (e.g., in test environments with ESM/worker compatibility issues)
+        return items.filter(predicate);
+    }
+}
+/**
+ * Get statistics about the worker pool.
+ *
+ * @returns Pool statistics or null if pool is not initialized
+ */
+export function getPoolStats() {
+    if (!sharedPool) {
+        return null;
+    }
+    return sharedPool.stats();
+}