@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

package/dist/utils/taskScheduler.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Task Scheduler
+ *
+ * Advanced task scheduling utilities using workerpool.
+ * Phase 8 Sprint 4: Priority queues, concurrency control, progress tracking.
+ *
+ * @module utils/taskScheduler
+ */
+/**
+ * Task priority levels.
+ * Higher priority tasks are executed first.
+ */
+export declare enum TaskPriority {
+    LOW = 0,
+    NORMAL = 1,
+    HIGH = 2,
+    CRITICAL = 3
+}
+/**
+ * Task status in the queue.
+ */
+export declare enum TaskStatus {
+    PENDING = "pending",
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled"
+}
+/**
+ * Task definition for the queue.
+ */
+export interface Task<T = unknown, R = unknown> {
+    /** Unique task identifier */
+    id: string;
+    /** Task priority */
+    priority: TaskPriority;
+    /** Function to execute (must be serializable) */
+    fn: (input: T) => R;
+    /** Input data for the function */
+    input: T;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+    /** Optional task metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Task result after execution.
+ */
+export interface TaskResult<R = unknown> {
+    /** Task identifier */
+    id: string;
+    /** Task status */
+    status: TaskStatus;
+    /** Result if successful */
+    result?: R;
+    /** Error if failed */
+    error?: Error;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Start timestamp */
+    startedAt: number;
+    /** End timestamp */
+    completedAt: number;
+}
+/**
+ * Progress callback for batch operations.
+ */
+export type ProgressCallback = (progress: {
+    completed: number;
+    total: number;
+    percentage: number;
+    currentTaskId?: string;
+}) => void;
+/**
+ * Batch processing options.
+ */
+export interface BatchOptions {
+    /** Maximum concurrent tasks (default: CPU count - 1) */
+    concurrency?: number;
+    /** Task timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Progress callback */
+    onProgress?: ProgressCallback;
+    /** Whether to stop on first error (default: false) */
+    stopOnError?: boolean;
+}
+/**
+ * Task queue statistics.
+ */
+export interface QueueStats {
+    /** Number of pending tasks */
+    pending: number;
+    /** Number of running tasks */
+    running: number;
+    /** Number of completed tasks */
+    completed: number;
+    /** Number of failed tasks */
+    failed: number;
+    /** Average execution time in milliseconds */
+    averageExecutionTime: number;
+    /** Total tasks processed */
+    totalProcessed: number;
+}
+/**
+ * Priority Task Queue with advanced scheduling.
+ *
+ * Features:
+ * - Priority-based execution (CRITICAL > HIGH > NORMAL > LOW)
+ * - Configurable concurrency limits
+ * - Progress tracking
+ * - Graceful error handling
+ * - Task cancellation
+ *
+ * @example
+ * ```typescript
+ * const queue = new TaskQueue({ concurrency: 4 });
+ *
+ * // Add tasks with different priorities
+ * queue.enqueue({
+ *   id: 'task1',
+ *   priority: TaskPriority.HIGH,
+ *   fn: (x: number) => x * 2,
+ *   input: 5,
+ * });
+ *
+ * // Process all tasks
+ * const results = await queue.processAll();
+ * ```
+ */
+export declare class TaskQueue {
+    private queue;
+    private running;
+    private completed;
+    private pool;
+    private concurrency;
+    private defaultTimeout;
+    private isProcessing;
+    private totalExecutionTime;
+    private totalProcessed;
+    private useWorkerPool;
+    constructor(options?: {
+        concurrency?: number;
+        timeout?: number;
+        useWorkerPool?: boolean;
+    });
+    /**
+     * Get or create the worker pool.
+     */
+    private getPool;
+    /**
+     * Add a task to the queue.
+     *
+     * @param task - Task to add
+     * @returns Promise that resolves when the task completes
+     */
+    enqueue<T, R>(task: Task<T, R>): Promise<TaskResult<R>>;
+    /**
+     * Process the next task in the queue.
+     */
+    private processNext;
+    /**
+     * Cancel a pending task.
+     *
+     * @param taskId - ID of the task to cancel
+     * @returns True if task was cancelled, false if not found or already running
+     */
+    cancel(taskId: string): boolean;
+    /**
+     * Wait for all tasks to complete.
+     *
+     * @returns Array of all task results
+     */
+    drain(): Promise<TaskResult[]>;
+    /**
+     * Get queue statistics.
+     */
+    getStats(): QueueStats;
+    /**
+     * Clear all completed results.
+     */
+    clearCompleted(): void;
+    /**
+     * Shutdown the task queue and release resources.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Process items in parallel batches with progress tracking.
+ *
+ * Unlike parallelMap, this provides:
+ * - Progress callbacks
+ * - Configurable concurrency
+ * - Error handling options
+ * - Task-level timeouts
+ *
+ * @template T - Input item type
+ * @template R - Output item type
+ * @param items - Array of items to process
+ * @param fn - Processing function (must be serializable)
+ * @param options - Batch processing options
+ * @returns Array of results (or errors if stopOnError is false)
+ *
+ * @example
+ * ```typescript
+ * const results = await batchProcess(
+ *   urls,
+ *   (url: string) => fetch(url).then(r => r.json()),
+ *   {
+ *     concurrency: 5,
+ *     timeout: 10000,
+ *     onProgress: ({ completed, total, percentage }) => {
+ *       console.log(`Progress: ${percentage.toFixed(1)}%`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function batchProcess<T, R>(items: T[], fn: (item: T) => R | Promise<R>, options?: BatchOptions): Promise<Array<{
+    success: true;
+    result: R;
+} | {
+    success: false;
+    error: Error;
+}>>;
+/**
+ * Execute tasks with rate limiting.
+ *
+ * Ensures tasks don't exceed a specified rate (tasks per second).
+ *
+ * @template T - Input item type
+ * @template R - Output item type
+ * @param items - Items to process
+ * @param fn - Processing function
+ * @param rateLimit - Maximum tasks per second
+ * @returns Array of results
+ *
+ * @example
+ * ```typescript
+ * // Process max 10 items per second
+ * const results = await rateLimitedProcess(
+ *   items,
+ *   (item) => processItem(item),
+ *   10
+ * );
+ * ```
+ */
+export declare function rateLimitedProcess<T, R>(items: T[], fn: (item: T) => R | Promise<R>, rateLimit: number): Promise<R[]>;
+/**
+ * Retry a function with exponential backoff.
+ *
+ * @template T - Return type
+ * @param fn - Function to retry
+ * @param options - Retry options
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => T | Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    onRetry?: (error: Error, attempt: number) => void;
+}): Promise<T>;
+/**
+ * Create a debounced version of a function.
+ *
+ * @template T - Function arguments type
+ * @template R - Return type
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends unknown[], R>(fn: (...args: T) => R, delay: number): (...args: T) => Promise<R>;
+/**
+ * Create a throttled version of a function.
+ *
+ * @template T - Function arguments type
+ * @template R - Return type
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends unknown[], R>(fn: (...args: T) => R, limit: number): (...args: T) => R | undefined;
+//# sourceMappingURL=taskScheduler.d.ts.map

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

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