@danielsimonjr/memoryjs 1.0.0

package/dist/utils/BatchProcessor.js

@@ -0,0 +1,377 @@
+/**
+ * Batch Processor
+ *
+ * Phase 12 Sprint 2: Generic batch processing utility with parallel execution,
+ * retry logic, progress callbacks, and error collection.
+ *
+ * @module utils/BatchProcessor
+ */
+/**
+ * Default options for batch processing.
+ */
+const DEFAULT_OPTIONS = {
+    concurrency: 4,
+    batchSize: 4,
+    maxRetries: 0,
+    retryDelayMs: 1000,
+    retryBackoffMultiplier: 2,
+    maxRetryDelayMs: 30000,
+    continueOnError: true,
+    itemTimeoutMs: 0,
+};
+/**
+ * BatchProcessor - Generic batch processing with parallel execution
+ *
+ * Provides a flexible utility for processing arrays of items with:
+ * - Configurable concurrency
+ * - Automatic retry with exponential backoff
+ * - Progress callbacks for monitoring
+ * - Error collection without failing the entire batch
+ * - Cancellation support via AbortSignal
+ *
+ * @example
+ * ```typescript
+ * const processor = new BatchProcessor<string, number>({
+ *   concurrency: 4,
+ *   maxRetries: 3,
+ *   onProgress: (p) => console.log(`${p.percentage.toFixed(1)}% complete`),
+ * });
+ *
+ * const result = await processor.process(
+ *   ['item1', 'item2', 'item3'],
+ *   async (item) => {
+ *     const response = await fetchData(item);
+ *     return response.value;
+ *   }
+ * );
+ *
+ * console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`);
+ * ```
+ */
+export class BatchProcessor {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            batchSize: options.batchSize ?? options.concurrency ?? DEFAULT_OPTIONS.concurrency,
+        };
+    }
+    /**
+     * Process all items in batches with the specified processor function.
+     *
+     * @param items - Array of items to process
+     * @param processor - Async function to process each item
+     * @returns Batch processing result with all item results and statistics
+     */
+    async process(items, processor) {
+        const startTime = Date.now();
+        const results = new Array(items.length);
+        const errors = new Map();
+        let succeeded = 0;
+        let failed = 0;
+        const totalBatches = Math.ceil(items.length / this.options.batchSize);
+        // Process items in batches
+        for (let batchIndex = 0; batchIndex < items.length; batchIndex += this.options.batchSize) {
+            // Check for cancellation
+            if (this.options.signal?.aborted) {
+                throw new Error('Batch processing cancelled');
+            }
+            const batchItems = items.slice(batchIndex, batchIndex + this.options.batchSize);
+            const batchStartIndex = batchIndex;
+            const currentBatchIndex = Math.floor(batchIndex / this.options.batchSize);
+            // Process batch concurrently
+            const batchPromises = batchItems.map((item, localIndex) => this.processItem(item, batchStartIndex + localIndex, processor));
+            const batchResults = await Promise.all(batchPromises);
+            // Collect results
+            for (let i = 0; i < batchResults.length; i++) {
+                const itemResult = batchResults[i];
+                const globalIndex = batchStartIndex + i;
+                results[globalIndex] = itemResult;
+                if (itemResult.success) {
+                    succeeded++;
+                }
+                else {
+                    failed++;
+                    if (itemResult.error) {
+                        errors.set(globalIndex, itemResult.error);
+                    }
+                    // Stop if continueOnError is false
+                    if (!this.options.continueOnError) {
+                        return {
+                            results,
+                            succeeded,
+                            failed,
+                            totalTimeMs: Date.now() - startTime,
+                            allSucceeded: false,
+                            errors,
+                        };
+                    }
+                }
+            }
+            // Report progress
+            if (this.options.onProgress) {
+                const completed = Math.min(batchIndex + batchItems.length, items.length);
+                this.options.onProgress({
+                    completed,
+                    total: items.length,
+                    percentage: (completed / items.length) * 100,
+                    succeeded,
+                    failed,
+                    batchIndex: currentBatchIndex,
+                    totalBatches,
+                });
+            }
+        }
+        return {
+            results,
+            succeeded,
+            failed,
+            totalTimeMs: Date.now() - startTime,
+            allSucceeded: failed === 0,
+            errors,
+        };
+    }
+    /**
+     * Process a single item with retry logic.
+     */
+    async processItem(item, index, processor) {
+        const startTime = Date.now();
+        let lastError;
+        let attempts = 0;
+        for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+            attempts = attempt + 1;
+            // Check for cancellation before each attempt
+            if (this.options.signal?.aborted) {
+                return {
+                    index,
+                    success: false,
+                    error: new Error('Processing cancelled'),
+                    attempts,
+                    durationMs: Date.now() - startTime,
+                };
+            }
+            try {
+                let result;
+                if (this.options.itemTimeoutMs > 0) {
+                    // Process with timeout
+                    result = await Promise.race([
+                        processor(item, index),
+                        this.createTimeout(this.options.itemTimeoutMs),
+                    ]);
+                }
+                else {
+                    result = await processor(item, index);
+                }
+                return {
+                    index,
+                    success: true,
+                    result,
+                    attempts,
+                    durationMs: Date.now() - startTime,
+                };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on last attempt
+                if (attempt < this.options.maxRetries) {
+                    const delay = this.calculateRetryDelay(attempt);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        return {
+            index,
+            success: false,
+            error: lastError,
+            attempts,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Calculate delay for retry with exponential backoff.
+     */
+    calculateRetryDelay(attempt) {
+        const delay = this.options.retryDelayMs * Math.pow(this.options.retryBackoffMultiplier, attempt);
+        return Math.min(delay, this.options.maxRetryDelayMs);
+    }
+    /**
+     * Create a timeout promise.
+     */
+    createTimeout(ms) {
+        return new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('Item processing timeout')), ms);
+        });
+    }
+    /**
+     * Sleep for the specified duration.
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Get the configured options.
+     */
+    getOptions() {
+        return { ...this.options };
+    }
+}
+/**
+ * Process items in parallel batches (convenience function).
+ *
+ * @template TInput - Input item type
+ * @template TOutput - Output result type
+ * @param items - Array of items to process
+ * @param processor - Async function to process each item
+ * @param options - Batch processing options
+ * @returns Batch processing result
+ *
+ * @example
+ * ```typescript
+ * const result = await processBatch(
+ *   urls,
+ *   async (url) => fetch(url).then(r => r.json()),
+ *   { concurrency: 5, maxRetries: 2 }
+ * );
+ * ```
+ */
+export async function processBatch(items, processor, options = {}) {
+    const batchProcessor = new BatchProcessor(options);
+    return batchProcessor.process(items, processor);
+}
+/**
+ * Process items with automatic retry on failure (convenience function).
+ *
+ * @template TInput - Input item type
+ * @template TOutput - Output result type
+ * @param items - Array of items to process
+ * @param processor - Async function to process each item
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @param onProgress - Optional progress callback
+ * @returns Batch processing result
+ *
+ * @example
+ * ```typescript
+ * const result = await processWithRetry(
+ *   items,
+ *   async (item) => unreliableOperation(item),
+ *   3,
+ *   (p) => console.log(`${p.percentage}%`)
+ * );
+ * ```
+ */
+export async function processWithRetry(items, processor, maxRetries = 3, onProgress) {
+    return processBatch(items, processor, { maxRetries, onProgress });
+}
+/**
+ * Chunk an array into smaller arrays of specified size.
+ *
+ * @template T - Item type
+ * @param array - Array to chunk
+ * @param size - Size of each chunk
+ * @returns Array of chunks
+ *
+ * @example
+ * ```typescript
+ * const chunks = chunkArray([1, 2, 3, 4, 5], 2);
+ * // [[1, 2], [3, 4], [5]]
+ * ```
+ */
+export function chunkArray(array, size) {
+    if (size <= 0) {
+        throw new Error('Chunk size must be greater than 0');
+    }
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Execute async functions in parallel with a concurrency limit.
+ *
+ * @template T - Result type
+ * @param tasks - Array of async functions to execute
+ * @param concurrency - Maximum concurrent executions
+ * @returns Array of results (successful results or errors)
+ *
+ * @example
+ * ```typescript
+ * const tasks = urls.map(url => () => fetch(url));
+ * const results = await parallelLimit(tasks, 5);
+ * ```
+ */
+export async function parallelLimit(tasks, concurrency) {
+    const results = [];
+    for (let i = 0; i < tasks.length; i += concurrency) {
+        const batch = tasks.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(async (task) => {
+            try {
+                const value = await task();
+                return { success: true, value };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                };
+            }
+        }));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Map over items in parallel with a concurrency limit.
+ *
+ * @template TInput - Input item type
+ * @template TOutput - Output result type
+ * @param items - Array of items to map
+ * @param mapper - Async mapping function
+ * @param concurrency - Maximum concurrent operations (default: 4)
+ * @returns Array of results (in order)
+ *
+ * @example
+ * ```typescript
+ * const results = await mapParallel(
+ *   ids,
+ *   async (id) => fetchUser(id),
+ *   10
+ * );
+ * ```
+ */
+export async function mapParallel(items, mapper, concurrency = 4) {
+    const results = new Array(items.length);
+    for (let i = 0; i < items.length; i += concurrency) {
+        const batch = items.slice(i, i + concurrency);
+        const startIndex = i;
+        const batchResults = await Promise.all(batch.map((item, localIndex) => mapper(item, startIndex + localIndex)));
+        for (let j = 0; j < batchResults.length; j++) {
+            results[startIndex + j] = batchResults[j];
+        }
+    }
+    return results;
+}
+/**
+ * Filter items in parallel with a concurrency limit.
+ *
+ * @template T - Item type
+ * @param items - Array of items to filter
+ * @param predicate - Async predicate function
+ * @param concurrency - Maximum concurrent operations (default: 4)
+ * @returns Filtered array (in order)
+ *
+ * @example
+ * ```typescript
+ * const validItems = await filterParallel(
+ *   items,
+ *   async (item) => validateItem(item),
+ *   10
+ * );
+ * ```
+ */
+export async function filterParallel(items, predicate, concurrency = 4) {
+    const includeFlags = await mapParallel(items, predicate, concurrency);
+    return items.filter((_, index) => includeFlags[index]);
+}
+//# sourceMappingURL=BatchProcessor.js.map

package/dist/utils/BatchProcessor.js.map

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

package/dist/utils/MemoryMonitor.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Memory Usage Monitor
+ *
+ * Phase 12 Sprint 6: Track memory usage across all components
+ * with human-readable formatting.
+ *
+ * @module utils/MemoryMonitor
+ */
+/**
+ * Memory usage for a single component.
+ */
+export interface ComponentMemoryUsage {
+    /** Component name */
+    name: string;
+    /** Estimated memory usage in bytes */
+    bytes: number;
+    /** Item count (if applicable) */
+    itemCount?: number;
+    /** Average bytes per item */
+    bytesPerItem?: number;
+}
+/**
+ * Aggregate memory usage statistics.
+ */
+export interface MemoryUsageStats {
+    /** Total memory usage in bytes */
+    totalBytes: number;
+    /** Formatted total memory */
+    totalFormatted: string;
+    /** Per-component breakdown */
+    components: ComponentMemoryUsage[];
+    /** Timestamp of measurement */
+    timestamp: Date;
+    /** Node.js heap stats (if available) */
+    heapStats?: {
+        heapUsed: number;
+        heapTotal: number;
+        external: number;
+        rss: number;
+    };
+}
+/**
+ * Memory threshold configuration.
+ */
+export interface MemoryThresholds {
+    /** Warning threshold in bytes */
+    warning: number;
+    /** Critical threshold in bytes */
+    critical: number;
+}
+/**
+ * Memory alert.
+ */
+export interface MemoryAlert {
+    /** Alert level */
+    level: 'warning' | 'critical';
+    /** Component that triggered the alert */
+    component: string;
+    /** Current usage */
+    currentBytes: number;
+    /** Threshold exceeded */
+    threshold: number;
+    /** Message */
+    message: string;
+}
+/**
+ * Callback for memory change events.
+ */
+export type MemoryChangeCallback = (usage: MemoryUsageStats) => void;
+/**
+ * Memory Monitor for tracking usage across components.
+ *
+ * @example
+ * ```typescript
+ * const monitor = new MemoryMonitor();
+ *
+ * // Register components
+ * monitor.registerComponent('entities', () => entities.length * 500);
+ * monitor.registerComponent('vectors', () => vectors.size * dimension * 4);
+ *
+ * // Get usage stats
+ * const stats = monitor.getUsage();
+ * console.log(`Total memory: ${stats.totalFormatted}`);
+ *
+ * // Check for alerts
+ * const alerts = monitor.checkThresholds();
+ * ```
+ */
+export declare class MemoryMonitor {
+    private componentEstimators;
+    private itemCounters;
+    private thresholds;
+    private listeners;
+    private lastUsage;
+    constructor(thresholds?: Partial<MemoryThresholds>);
+    /**
+     * Register a component for memory tracking.
+     *
+     * @param name - Component name
+     * @param estimator - Function that returns estimated bytes
+     * @param itemCounter - Optional function that returns item count
+     */
+    registerComponent(name: string, estimator: () => number, itemCounter?: () => number): void;
+    /**
+     * Unregister a component.
+     *
+     * @param name - Component name
+     */
+    unregisterComponent(name: string): void;
+    /**
+     * Get current memory usage statistics.
+     */
+    getUsage(): MemoryUsageStats;
+    /**
+     * Get memory usage for a specific component.
+     *
+     * @param name - Component name
+     */
+    getComponentUsage(name: string): ComponentMemoryUsage | undefined;
+    /**
+     * Check memory thresholds and return alerts.
+     */
+    checkThresholds(): MemoryAlert[];
+    /**
+     * Set memory thresholds.
+     *
+     * @param thresholds - New threshold values
+     */
+    setThresholds(thresholds: Partial<MemoryThresholds>): void;
+    /**
+     * Get current thresholds.
+     */
+    getThresholds(): MemoryThresholds;
+    /**
+     * Add a listener for memory changes.
+     *
+     * @param callback - Callback to invoke on memory changes
+     */
+    addListener(callback: MemoryChangeCallback): void;
+    /**
+     * Remove a listener.
+     *
+     * @param callback - Callback to remove
+     */
+    removeListener(callback: MemoryChangeCallback): void;
+    /**
+     * Get a human-readable summary of memory usage.
+     */
+    getSummary(): string;
+    /**
+     * Get the last recorded usage without triggering a new measurement.
+     */
+    getLastUsage(): MemoryUsageStats | null;
+    /**
+     * Format bytes as human-readable string.
+     *
+     * @param bytes - Number of bytes
+     */
+    formatBytes(bytes: number): string;
+    /**
+     * Parse a formatted byte string back to number.
+     *
+     * @param formatted - Formatted string like "10 MB"
+     */
+    parseBytes(formatted: string): number;
+    /**
+     * Clear all registered components.
+     */
+    clear(): void;
+    private notifyListeners;
+}
+/**
+ * Singleton instance for global memory monitoring.
+ */
+export declare const globalMemoryMonitor: MemoryMonitor;
+//# sourceMappingURL=MemoryMonitor.d.ts.map

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

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