@taicode/common-base 1.7.2 → 1.7.4

package/output/flow-queue/flow-queue.js

@@ -0,0 +1,655 @@
+/**
+ * FlowQueue 流式队列处理器
+ *
+ * 一个支持异步处理、错误重试、延迟执行的队列管理工具，特别适用于以下场景：
+ *
+ * ## 使用场景
+ *
+ * ### 1. 复杂嵌套的解耦
+ * 当需要处理复杂的嵌套数据结构或多层依赖关系时，FlowQueue 可以帮助解耦处理逻辑：
+ *
+ * ```typescript
+ * // 示例：处理嵌套的文件目录结构
+ * interface FileNode {
+ *   path: string;
+ *   children?: FileNode[];
+ * }
+ *
+ * const queue = new FlowQueue<FileNode, ProcessedFile>(
+ *   { delay: { base: 100 } }, // 避免过快处理导致资源竞争
+ *   async (node) => {
+ *     // 处理当前文件节点
+ *     const result = await processFile(node.path);
+ *
+ *     // 将子节点加入队列，实现解耦
+ *     if (node.children) {
+ *       queue.input(...node.children);
+ *     }
+ *
+ *     return result;
+ *   }
+ * );
+ *
+ * // 开始处理根节点
+ * queue.input(rootNode);
+ * ```
+ *
+ * ### 2. 深度循环的解耦
+ * 在需要处理大量数据或深度递归时，FlowQueue 可以避免调用栈溢出和阻塞主线程：
+ *
+ * ```typescript
+ * // 示例：大数据集的分批处理
+ * interface DataChunk {
+ *   data: any[];
+ *   offset: number;
+ *   total: number;
+ * }
+ *
+ * const queue = new FlowQueue<DataChunk, ProcessedChunk>(
+ *   {
+ *     delay: { base: 50, jitter: true }, // 避免连续处理导致的性能问题
+ *     retry: { strategy: 'exponential', baseDelay: 1000, maxRetries: 3 }
+ *   },
+ *   async (chunk) => {
+ *     const result = await processDataChunk(chunk.data);
+ *
+ *     // 如果还有更多数据，继续加入队列
+ *     if (chunk.offset + chunk.data.length < chunk.total) {
+ *       const nextChunk = await loadNextChunk(chunk.offset + chunk.data.length);
+ *       queue.input(nextChunk);
+ *     }
+ *
+ *     return result;
+ *   }
+ * );
+ *
+ * // 监听处理进度
+ * queue.onGenerate((result) => {
+ *   updateProgress(result);
+ * });
+ * ```
+ *
+ * ## 关键特性
+ * - **异步解耦**：通过队列机制避免深度递归和调用栈溢出
+ * - **错误重试**：支持多种重试策略，提高处理的可靠性
+ * - **流量控制**：可配置任务间延迟，避免资源竞争
+ * - **状态追踪**：清晰的成功/失败状态管理
+ * - **背压处理**：避免内存溢出的队列管理
+ * - **并发控制**：支持配置并发处理数量，默认为 1
+ * - **链式调用**：支持流畅的链式 API 调用
+ */
+import { catchIt } from '../catch';
+function delay(arg0) {
+    return new Promise(resolve => setTimeout(() => resolve(), arg0));
+}
+/**
+ * FlowQueue 流式队列处理器类
+ *
+ * 提供高效的异步队列处理能力，特别适用于需要解耦复杂嵌套结构和深度循环的场景。
+ *
+ * @template I 输入数据类型，继承自 FlowQueueInput
+ * @template O 输出数据类型，继承自 FlowQueueOutput
+ *
+ * @example
+ * ```typescript
+ * // 创建队列实例
+ * const queue = new FlowQueue<InputType, OutputType>(
+ *   {
+ *     retry: { strategy: 'exponential', baseDelay: 1000, maxRetries: 3 },
+ *     delay: { base: 100, jitter: true },
+ *     concurrency: 3 // 支持 3 个并发处理
+ *   },
+ *   async (input) => {
+ *     // 处理逻辑
+ *     return await processInput(input);
+ *   }
+ * );
+ *
+ * // 传统方式
+ * queue.input(data1, data2, data3);
+ * queue.onGenerate(result => console.log('处理完成:', result));
+ * queue.closeInput();
+ * await queue.awaitCompletion();
+ *
+ * // 链式调用方式
+ * await queue
+ *   .input(data1, data2)
+ *   .input(data3)
+ *   .closeInput()
+ *   .awaitCompletion();
+ *
+ * // 重置并重新开始
+ * await queue
+ *   .reset()
+ *   .input(newData1, newData2)
+ *   .closeInput()
+ *   .awaitCompletion();
+ * ```
+ */
+export class FlowQueue {
+    options;
+    processor;
+    pendingInputs = []; // 待处理
+    processedInputs = []; // 已处理
+    successOutputs = new Map();
+    erroredOutputs = new Map();
+    processingCount = 0; // 当前正在处理的任务数量
+    retryCount = new Map(); // 记录每个输入的重试次数
+    onGenerates = new Map();
+    isInputClosed = false; // 标记输入是否已关闭
+    completionPromise = null; // 完成状态的 Promise
+    completionResolve = null; // 完成状态的 resolve 函数
+    /**
+     * 创建 FlowQueue 实例
+     *
+     * @param options 队列配置选项
+     * @param processor 处理函数，接收输入并返回处理结果的 Promise
+     *
+     * processor 函数是解耦的核心：
+     * - 可以在处理过程中通过 this.input() 动态添加新任务
+     * - 支持异步处理，避免阻塞主线程
+     * - 失败时会根据重试策略自动重试
+     * - 支持并发处理，默认并发数为 1
+     *
+     * @example
+     * ```typescript
+     * // 处理嵌套文件结构的示例（单线程）
+     * const fileQueue = new FlowQueue<FileNode, ProcessedFile>(
+     *   {
+     *     retry: { strategy: 'exponential', baseDelay: 1000, maxRetries: 3 },
+     *     delay: { base: 100, jitter: true },
+     *     concurrency: 1 // 默认值，可省略
+     *   },
+     *   async (node) => {
+     *     try {
+     *       const result = await processFile(node.path);
+     *
+     *       // 动态添加子节点，实现深度优先遍历的解耦
+     *       if (node.children) {
+     *         fileQueue.input(...node.children);
+     *       }
+     *
+     *       return result;
+     *     } catch (error) {
+     *       throw new Error(`处理文件 ${node.path} 失败: ${error.message}`);
+     *     }
+     *   }
+     * );
+     *
+     * // 并发处理示例
+     * const concurrentQueue = new FlowQueue<Task, Result>(
+     *   {
+     *     concurrency: 5, // 同时处理 5 个任务
+     *     retry: { strategy: 'exponential', baseDelay: 1000, maxRetries: 3 }
+     *   },
+     *   async (task) => {
+     *     return await processTask(task);
+     *   }
+     * );
+     * ```
+     */
+    constructor(options, processor) {
+        this.options = options;
+        this.processor = processor;
+        // 设置重试配置默认值
+        this.options.retry = this.options.retry || { strategy: 'immediate' };
+        this.options.retry.maxRetries = this.options.retry.maxRetries ?? 3;
+        this.options.retry.jitter = this.options.retry.jitter ?? false;
+        // 设置任务间延迟配置默认值
+        this.options.delay = this.options.delay || {};
+        this.options.delay.base = this.options.delay.base ?? 0;
+        this.options.delay.jitter = this.options.delay.jitter ?? false;
+        this.options.delay.jitterRange = this.options.delay.jitterRange ?? 0.1;
+        // 设置并发配置默认值
+        this.options.concurrency = this.options.concurrency ?? 1;
+    }
+    /**
+     * 计算重试延迟时间
+     */
+    calculateRetryDelay(retryCount) {
+        const retryConfig = this.options.retry;
+        let delay = 0;
+        switch (retryConfig.strategy) {
+            case 'immediate':
+            case undefined:
+                delay = 0;
+                break;
+            case 'fixed':
+                delay = retryConfig.baseDelay;
+                if (retryConfig.maxDelay) {
+                    delay = Math.min(delay, retryConfig.maxDelay);
+                }
+                break;
+            case 'exponential':
+                const multiplier = retryConfig.multiplier ?? 2;
+                delay = retryConfig.baseDelay * Math.pow(multiplier, retryCount);
+                if (retryConfig.maxDelay) {
+                    delay = Math.min(delay, retryConfig.maxDelay);
+                }
+                break;
+            case 'linear':
+                delay = retryConfig.baseDelay * (retryCount + 1);
+                if (retryConfig.maxDelay) {
+                    delay = Math.min(delay, retryConfig.maxDelay);
+                }
+                break;
+            case 'custom':
+                const baseDelay = retryConfig.baseDelay ?? 1000;
+                delay = retryConfig.customDelayFn(retryCount, baseDelay);
+                if (retryConfig.maxDelay) {
+                    delay = Math.min(delay, retryConfig.maxDelay);
+                }
+                break;
+            default:
+                delay = 0;
+        }
+        // 添加随机抖动
+        if (retryConfig.jitter && delay > 0) {
+            const jitterRange = delay * 0.1; // 10% 的抖动范围
+            const jitter = (Math.random() - 0.5) * 2 * jitterRange;
+            delay = Math.max(0, delay + jitter);
+        }
+        return Math.floor(delay);
+    }
+    /**
+     * 计算任务间延迟时间
+     */
+    calculateTaskDelay() {
+        const delayConfig = this.options.delay;
+        let delay = delayConfig.base;
+        if (delayConfig.customDelayFn) {
+            delay = delayConfig.customDelayFn();
+        }
+        // 添加随机抖动
+        if (delayConfig.jitter && delay > 0) {
+            const jitterRange = delay * delayConfig.jitterRange;
+            const jitter = (Math.random() - 0.5) * 2 * jitterRange;
+            delay = Math.max(0, delay + jitter);
+        }
+        return Math.floor(delay);
+    }
+    /**
+     * 调度下一个处理任务
+     */
+    scheduleNextProcessing() {
+        // 启动尽可能多的处理任务，直到达到并发限制
+        const tasksToStart = Math.min(this.pendingInputs.length, this.options.concurrency - this.processingCount);
+        for (let i = 0; i < tasksToStart; i++) {
+            // 计算任务间延迟
+            const taskDelay = this.calculateTaskDelay();
+            if (taskDelay > 0) {
+                // 有延迟，使用 setTimeout
+                setTimeout(() => this.processFlow(), taskDelay);
+            }
+            else {
+                // 无延迟，使用 setTimeout(0) 避免调用栈过深
+                setTimeout(() => this.processFlow(), 0);
+            }
+        }
+        // 检查是否已标记为完成
+        this.checkAndTriggerCompletion();
+    }
+    /**
+     * 延迟执行重试
+     */
+    scheduleRetry(input, delayTime) {
+        this.pendingInputs.unshift(input);
+        if (delayTime <= 0) {
+            // 立即重试，启动调度
+            this.scheduleNextProcessing();
+        }
+        else {
+            // 延迟重试
+            setTimeout(() => {
+                this.scheduleNextProcessing();
+            }, delayTime);
+        }
+    }
+    /**
+     * 检查是否已完成并触发完成回调
+     */
+    async checkAndTriggerCompletion() {
+        await delay(0); // 确保在当前执行栈完成后再检查
+        if (this.isInputClosed && this.pendingInputs.length === 0 && this.processingCount === 0 && this.completionResolve) {
+            this.completionResolve();
+            this.completionResolve = null;
+        }
+    }
+    /**
+     * 检查当前的待处理队列，取出一个进行处理
+     * 处理完成后更新 output 并将输入移动到 processedInputs
+     * 当 processor 处理失败时，将错误信息存入 output（FlowError）
+     * 可以设置失败的重试次数，如果超过最大重试次数则不再重试
+     */
+    async processFlow() {
+        // 检查并发限制
+        if (this.processingCount >= this.options.concurrency) {
+            return;
+        }
+        // 取出第一个待处理的输入
+        const input = this.pendingInputs.shift();
+        if (!input) {
+            this.checkAndTriggerCompletion();
+            return;
+        }
+        // 增加处理计数
+        this.processingCount++;
+        try {
+            // 获取当前输入的重试次数
+            const currentRetries = this.retryCount.get(input) || 0;
+            // 使用 processor 处理输入
+            const result = await catchIt(() => this.processor(input));
+            if (result.isError()) {
+                if (currentRetries < this.options.retry.maxRetries) {
+                    // 还可以重试，增加重试次数并计算延迟
+                    this.retryCount.set(input, currentRetries + 1);
+                    const delay = this.calculateRetryDelay(currentRetries);
+                    this.scheduleRetry(input, delay);
+                }
+                else {
+                    // 超过最大重试次数，记录错误并移动到已处理
+                    this.erroredOutputs.set(input, result.error);
+                    this.processedInputs.push(input);
+                    this.retryCount.delete(input);
+                }
+            }
+            else {
+                // 处理成功，存储结果
+                this.successOutputs.set(input, result.value);
+                this.processedInputs.push(input);
+                this.retryCount.delete(input);
+                // 清除可能存在的错误记录
+                this.erroredOutputs.delete(input);
+                // 通知所有注册的回调
+                await this.notifyOnGenerates(result.value);
+            }
+        }
+        catch (error) {
+            console.error('Error in processFlow:', error);
+        }
+        finally {
+            // 减少正在处理的任务计数
+            this.processingCount--;
+            // 处理完当前输入后，尝试启动更多处理任务
+            this.scheduleNextProcessing();
+        }
+    }
+    /**
+     * 通知所有注册的回调函数
+     */
+    async notifyOnGenerates(output) {
+        for (const callback of this.onGenerates.values()) {
+            const result = await catchIt(() => callback(output));
+            if (result.isError()) {
+                console.error('Error in onGenerate callback:', result.error);
+            }
+        }
+    }
+    /**
+     * 向队列添加输入数据
+     *
+     * 此方法是解耦复杂嵌套结构的关键：
+     * - 在 processor 函数内部可以动态添加新的输入
+     * - 避免了深度递归调用栈
+     * - 支持批量添加多个输入
+     * - 支持链式调用
+     *
+     * @param inputs 要处理的输入数据
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 在处理器中动态添加子任务
+     * const processor = async (node: TreeNode) => {
+     *   const result = await processNode(node);
+     *
+     *   // 将子节点加入队列，实现解耦
+     *   if (node.children) {
+     *     queue.input(...node.children);
+     *   }
+     *
+     *   return result;
+     * };
+     *
+     * // 链式调用示例
+     * queue
+     *   .input(data1, data2)
+     *   .input(data3)
+     *   .closeInput();
+     * ```
+     */
+    input(...inputs) {
+        if (this.isInputClosed)
+            return this;
+        this.pendingInputs.push(...inputs);
+        this.processFlow();
+        return this;
+    }
+    /**
+     * 注册输出监听器
+     *
+     * 用于监听每个成功处理的输出，适用于：
+     * - 实时更新处理进度
+     * - 流式处理大数据集
+     * - 实现观察者模式解耦
+     *
+     * @param callback 当有新输出时调用的回调函数
+     * @returns 取消监听的函数
+     *
+     * @example
+     * ```typescript
+     * // 监听处理进度
+     * const unsubscribe = queue.onGenerate((result) => {
+     *   updateProgressBar(result);
+     *   saveToDatabase(result);
+     * });
+     *
+     * // 在适当时机取消监听
+     * unsubscribe();
+     * ```
+     */
+    onGenerate(callback) {
+        const id = Math.random().toString(36);
+        this.onGenerates.set(id, callback);
+        return () => this.onGenerates.delete(id);
+    }
+    /**
+     * 只读标记，代表是否当前已经 closeInput 并且所有输入都已经处理完毕
+     */
+    get isCompleted() {
+        return this.isInputClosed && this.pendingInputs.length === 0 && this.processingCount === 0;
+    }
+    /**
+     * 标记当前 FlowQueue 不会再有新的输入了
+     *
+     * 调用此方法后：
+     * - 队列将不再接受新的输入
+     * - 当所有现有输入处理完成后，队列将进入完成状态
+     * - 可以通过 awaitCompletion() 等待所有处理完成
+     * - 支持链式调用
+     *
+     * 在深度循环解耦场景中，这是控制处理边界的重要方法。
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 添加所有初始数据
+     * queue.input(...initialData);
+     *
+     * // 标记输入结束
+     * queue.closeInput();
+     *
+     * // 等待所有处理完成
+     * await queue.awaitCompletion();
+     * console.log('所有数据处理完成');
+     *
+     * // 链式调用示例
+     * await queue
+     *   .input(data1, data2)
+     *   .closeInput()
+     *   .awaitCompletion();
+     * ```
+     */
+    closeInput() {
+        this.isInputClosed = true;
+        // 使用统一的完成检查方法
+        this.checkAndTriggerCompletion();
+        return this;
+    }
+    /**
+     * 返回一个 Promise，代表当前已经标记为输入关闭状态、所有输入都已经处理完毕
+     *
+     * 这是等待所有异步处理完成的最佳方式，特别适用于：
+     * - 等待深度循环处理完成
+     * - 确保所有嵌套任务都已处理
+     * - 在测试中等待异步操作完成
+     *
+     * @returns Promise，在所有输入处理完成时 resolve
+     *
+     * @example
+     * ```typescript
+     * // 处理大量嵌套数据
+     * queue.input(rootData);
+     * queue.closeInput();
+     *
+     * // 等待所有嵌套处理完成
+     * await queue.awaitCompletion();
+     *
+     * // 检查处理结果
+     * console.log('成功处理:', queue.successOutputs.size);
+     * console.log('处理失败:', queue.erroredOutputs.size);
+     * ```
+     */
+    awaitCompletion() {
+        if (this.completionPromise) {
+            return this.completionPromise;
+        }
+        // 如果已经标记为输入关闭且没有待处理的输入和正在处理的任务，立即返回 resolved Promise
+        if (this.isInputClosed && this.pendingInputs.length === 0 && this.processingCount === 0) {
+            console.log('所有输入已处理完毕');
+            return Promise.resolve();
+        }
+        // 创建新的 Promise
+        this.completionPromise = new Promise((resolve) => {
+            this.completionResolve = () => {
+                console.log('所有输入已处理完毕');
+                resolve();
+            };
+        });
+        return this.completionPromise;
+    }
+    /**
+     * 移除尚未处理的输入并调用 closeInput
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 链式调用示例
+     * queue
+     *   .input(data1, data2)
+     *   .cancel()
+     *   .reset();
+     * ```
+     */
+    cancel() {
+        // 清除所有待处理的输入
+        this.pendingInputs.length = 0;
+        // 清除重试计数
+        this.retryCount.clear();
+        // 标记输入已关闭
+        this.closeInput();
+        return this;
+    }
+    /**
+     * 重置 FlowQueue 到初始状态
+     * 清空所有数据，包括待处理、已处理、输出、重试计数等
+     * 重置后可以重新开始处理
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 链式调用示例
+     * queue
+     *   .reset()
+     *   .input(newData1, newData2)
+     *   .closeInput();
+     * ```
+     */
+    reset() {
+        // 清空所有队列和状态
+        this.successOutputs.clear();
+        this.erroredOutputs.clear();
+        this.retryCount.clear();
+        this.pendingInputs.length = 0;
+        this.processedInputs.length = 0;
+        // 重置处理状态
+        this.processingCount = 0;
+        this.isInputClosed = false;
+        // 重置完成状态
+        if (this.completionResolve) {
+            this.completionResolve();
+            this.completionResolve = null;
+        }
+        this.completionPromise = null;
+        return this;
+    }
+    /**
+     * 重试所有失败的输入
+     *
+     * 自动将所有失败的输入从已处理队列移回待处理队列，并启动处理。
+     * 在处理复杂嵌套结构时，某些节点可能因为依赖关系而暂时失败，
+     * 此方法可以在依赖解决后重新处理这些失败的节点。
+     *
+     * @returns 被移动到待处理队列的输入数量
+     *
+     * @example
+     * ```typescript
+     * // 第一轮处理
+     * queue.input(...allData);
+     * queue.closeInput();
+     * await queue.awaitCompletion();
+     *
+     * // 检查是否有失败的项
+     * if (queue.erroredOutputs.size > 0) {
+     *   console.log(`有 ${queue.erroredOutputs.size} 个项目处理失败`);
+     *
+     *   // 重试失败的项目
+     *   const retryCount = queue.retry();
+     *   console.log(`重试 ${retryCount} 个项目`);
+     *
+     *   // 等待重试完成
+     *   await queue.awaitCompletion();
+     * }
+     * ```
+     */
+    retry() {
+        // 直接从 erroredOutputs Map 中获取所有失败的输入
+        const retryInputs = Array.from(this.erroredOutputs.keys());
+        if (retryInputs.length > 0) {
+            // 从已处理队列中移除这些输入
+            for (const input of retryInputs) {
+                const index = this.processedInputs.indexOf(input);
+                if (index > -1) {
+                    this.processedInputs.splice(index, 1);
+                }
+            }
+            // 清除错误记录和重试计数
+            this.erroredOutputs.clear();
+            for (const input of retryInputs) {
+                this.retryCount.delete(input);
+            }
+            // 将要重试的输入添加到待处理队列的前面（优先处理）
+            this.pendingInputs.unshift(...retryInputs);
+            // 启动处理（保持输入关闭状态，仅重试现有错误）
+            this.processFlow();
+        }
+        else {
+            // 没有失败的输入需要重试，检查是否应该触发完成状态
+            this.checkAndTriggerCompletion();
+        }
+        return retryInputs.length;
+    }
+}

package/output/flow-queue/flow-queue.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flow-queue.test.d.ts.map

package/output/flow-queue/flow-queue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-queue.test.d.ts","sourceRoot":"","sources":["../../source/flow-queue/flow-queue.test.ts"],"names":[],"mappings":""}