@taicode/common-base 1.7.2 → 1.7.4

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

@@ -0,0 +1,486 @@
+/**
+ * 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 调用
+ */
+type FlowQueueInput = {};
+type FlowQueueOutput = {};
+export type FlowQueueOnGenerate<T> = (item: T) => void;
+export type FlowQueueProcessor<I extends FlowQueueInput = FlowQueueInput, O extends FlowQueueOutput = FlowQueueOutput> = (input: I) => Promise<O>;
+/**
+ * FlowQueue 重试策略枚举
+ *
+ * 在处理复杂嵌套结构和深度循环时，不同的重试策略适用于不同场景：
+ * - immediate: 立即重试，适用于临时性错误
+ * - exponential: 指数退避，适用于资源竞争或外部服务限流
+ * - fixed: 固定延迟，适用于已知的处理间隔需求
+ * - linear: 线性增长，适用于逐步增加等待时间的场景
+ * - custom: 自定义策略，适用于特殊的业务逻辑需求
+ */
+export type FlowQueueRetryStrategy = 'immediate' | 'exponential' | 'fixed' | 'linear' | 'custom';
+type FlowQueueRetryConfigBase = {
+    maxRetries?: number;
+    jitter?: boolean;
+};
+type FlowQueueRetryConfigImmediate = FlowQueueRetryConfigBase & {
+    strategy?: 'immediate';
+};
+type FlowQueueRetryConfigFixed = FlowQueueRetryConfigBase & {
+    strategy: 'fixed';
+    baseDelay: number;
+    maxDelay?: number;
+};
+type FlowQueueRetryConfigExponential = FlowQueueRetryConfigBase & {
+    strategy: 'exponential';
+    baseDelay: number;
+    multiplier?: number;
+    maxDelay?: number;
+};
+type FlowQueueRetryConfigLinear = FlowQueueRetryConfigBase & {
+    strategy: 'linear';
+    baseDelay: number;
+    maxDelay?: number;
+};
+type FlowQueueRetryConfigCustom = FlowQueueRetryConfigBase & {
+    strategy: 'custom';
+    maxDelay?: number;
+    baseDelay?: number;
+    customDelayFn: (retryCount: number, baseDelay: number) => number;
+};
+export type FlowQueueRetryConfig = FlowQueueRetryConfigImmediate | FlowQueueRetryConfigFixed | FlowQueueRetryConfigExponential | FlowQueueRetryConfigLinear | FlowQueueRetryConfigCustom;
+/**
+ * 任务间延迟配置
+ *
+ * 在深度循环解耦场景中，合理的延迟配置可以：
+ * - 避免过快处理导致的资源竞争
+ * - 防止阻塞主线程影响用户体验
+ * - 通过抖动减少系统负载峰值
+ *
+ * @example
+ * ```typescript
+ * // 适用于 CPU 密集型任务的配置
+ * const delayConfig = {
+ *   base: 50,           // 基础延迟 50ms
+ *   jitter: true,       // 启用抖动
+ *   jitterRange: 0.2,   // 20% 的抖动范围
+ * };
+ *
+ * // 适用于 I/O 密集型任务的配置
+ * const ioDelayConfig = {
+ *   base: 100,
+ *   customDelayFn: () => {
+ *     // 根据系统负载动态调整延迟
+ *     return getCurrentSystemLoad() > 80 ? 200 : 50;
+ *   }
+ * };
+ * ```
+ */
+export type FlowQueueDelayConfig = {
+    base?: number;
+    jitter?: boolean;
+    jitterRange?: number;
+    customDelayFn?: () => number;
+};
+export type FlowQueueOptions = {
+    retry?: FlowQueueRetryConfig;
+    delay?: FlowQueueDelayConfig;
+    concurrency?: number;
+};
+/**
+ * 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 declare class FlowQueue<I extends FlowQueueInput, O extends FlowQueueOutput> {
+    private options;
+    private processor;
+    private pendingInputs;
+    private processedInputs;
+    successOutputs: Map<I, O>;
+    erroredOutputs: Map<I, unknown>;
+    private processingCount;
+    private retryCount;
+    private onGenerates;
+    private isInputClosed;
+    private completionPromise;
+    private completionResolve;
+    /**
+     * 创建 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: FlowQueueOptions, processor: FlowQueueProcessor<I, O>);
+    /**
+     * 计算重试延迟时间
+     */
+    private calculateRetryDelay;
+    /**
+     * 计算任务间延迟时间
+     */
+    private calculateTaskDelay;
+    /**
+     * 调度下一个处理任务
+     */
+    private scheduleNextProcessing;
+    /**
+     * 延迟执行重试
+     */
+    private scheduleRetry;
+    /**
+     * 检查是否已完成并触发完成回调
+     */
+    private checkAndTriggerCompletion;
+    /**
+     * 检查当前的待处理队列，取出一个进行处理
+     * 处理完成后更新 output 并将输入移动到 processedInputs
+     * 当 processor 处理失败时，将错误信息存入 output（FlowError）
+     * 可以设置失败的重试次数，如果超过最大重试次数则不再重试
+     */
+    private processFlow;
+    /**
+     * 通知所有注册的回调函数
+     */
+    private notifyOnGenerates;
+    /**
+     * 向队列添加输入数据
+     *
+     * 此方法是解耦复杂嵌套结构的关键：
+     * - 在 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: I[]): FlowQueue<I, O>;
+    /**
+     * 注册输出监听器
+     *
+     * 用于监听每个成功处理的输出，适用于：
+     * - 实时更新处理进度
+     * - 流式处理大数据集
+     * - 实现观察者模式解耦
+     *
+     * @param callback 当有新输出时调用的回调函数
+     * @returns 取消监听的函数
+     *
+     * @example
+     * ```typescript
+     * // 监听处理进度
+     * const unsubscribe = queue.onGenerate((result) => {
+     *   updateProgressBar(result);
+     *   saveToDatabase(result);
+     * });
+     *
+     * // 在适当时机取消监听
+     * unsubscribe();
+     * ```
+     */
+    onGenerate(callback: FlowQueueOnGenerate<O>): () => void;
+    /**
+     * 只读标记，代表是否当前已经 closeInput 并且所有输入都已经处理完毕
+     */
+    get isCompleted(): boolean;
+    /**
+     * 标记当前 FlowQueue 不会再有新的输入了
+     *
+     * 调用此方法后：
+     * - 队列将不再接受新的输入
+     * - 当所有现有输入处理完成后，队列将进入完成状态
+     * - 可以通过 awaitCompletion() 等待所有处理完成
+     * - 支持链式调用
+     *
+     * 在深度循环解耦场景中，这是控制处理边界的重要方法。
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 添加所有初始数据
+     * queue.input(...initialData);
+     *
+     * // 标记输入结束
+     * queue.closeInput();
+     *
+     * // 等待所有处理完成
+     * await queue.awaitCompletion();
+     * console.log('所有数据处理完成');
+     *
+     * // 链式调用示例
+     * await queue
+     *   .input(data1, data2)
+     *   .closeInput()
+     *   .awaitCompletion();
+     * ```
+     */
+    closeInput(): FlowQueue<I, O>;
+    /**
+     * 返回一个 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(): Promise<void>;
+    /**
+     * 移除尚未处理的输入并调用 closeInput
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 链式调用示例
+     * queue
+     *   .input(data1, data2)
+     *   .cancel()
+     *   .reset();
+     * ```
+     */
+    cancel(): FlowQueue<I, O>;
+    /**
+     * 重置 FlowQueue 到初始状态
+     * 清空所有数据，包括待处理、已处理、输出、重试计数等
+     * 重置后可以重新开始处理
+     *
+     * @returns 返回 FlowQueue 实例以支持链式调用
+     *
+     * @example
+     * ```typescript
+     * // 链式调用示例
+     * queue
+     *   .reset()
+     *   .input(newData1, newData2)
+     *   .closeInput();
+     * ```
+     */
+    reset(): FlowQueue<I, O>;
+    /**
+     * 重试所有失败的输入
+     *
+     * 自动将所有失败的输入从已处理队列移回待处理队列，并启动处理。
+     * 在处理复杂嵌套结构时，某些节点可能因为依赖关系而暂时失败，
+     * 此方法可以在依赖解决后重新处理这些失败的节点。
+     *
+     * @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(): number;
+}
+export {};
+//# sourceMappingURL=flow-queue.d.ts.map

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

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