@taicode/common-base 1.6.3 → 1.7.1

package/output/batching-buffer/batching-buffer.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 批处理缓冲区配置选项
+ */
+export interface BatchingBufferOptions<T> {
+    /**
+     * 批处理模式：批量处理器
+     */
+    batchProcessor?: (items: T[]) => Promise<void> | void;
+    /**
+     * 单个处理模式：单个处理器
+     */
+    itemProcessor?: (item: T) => Promise<void> | void;
+    /**
+     * 缓冲区大小限制，达到此数量时触发处理
+     * @default 100
+     */
+    bufferSize?: number;
+    /**
+     * 时间间隔（毫秒），距离上次处理超过此时间时触发处理
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * 是否在添加项目时立即启动定时器
+     * @default true
+     */
+    autoFlush?: boolean;
+    /**
+     * 错误处理回调函数
+     * @param error 发生的错误
+     * @param failedItems 处理失败的项目
+     */
+    onError?: (error: Error, failedItems: T[]) => void;
+}
+/**
+ * 批处理缓冲区
+ *
+ * 提供数据暂存和批量/单个处理功能的管理对象。
+ * 当缓冲区达到指定数量或距离上次处理达到一定时间时，
+ * 自动调用处理方法进行数据消费。
+ *
+ * @example
+ * ```typescript
+ * // 批量处理模式
+ * const buffer = new BatchingBuffer({
+ *   batchProcessor: async (items) => {
+ *     console.log('批量处理:', items)
+ *     await saveToDatabase(items)
+ *   },
+ *   bufferSize: 10,
+ *   flushInterval: 5000,
+ *   onError: (error, failedItems) => {
+ *     console.error('处理失败:', error, '失败项目:', failedItems)
+ *     // 可以进行重试或其他错误处理逻辑
+ *   }
+ * })
+ *
+ * // 单个处理模式
+ * const buffer = new BatchingBuffer({
+ *   itemProcessor: async (item) => {
+ *     console.log('单个处理:', item)
+ *     await saveToDatabase([item])
+ *   },
+ *   bufferSize: 1,
+ *   flushInterval: 1000
+ * })
+ *
+ * // 添加数据
+ * buffer.add('data1')                    // 添加单个数据
+ * buffer.add('data2', 'data3', 'data4')  // 添加多个数据
+ * buffer.add(...array)                   // 展开数组添加
+ *
+ * // 手动刷新
+ * await buffer.flush()
+ *
+ * // 销毁
+ * buffer.destroy()
+ * ```
+ */
+export declare class BatchingBuffer<T> {
+    private buffer;
+    private timer;
+    private isDestroyed;
+    private lastFlushTime;
+    private readonly batchProcessor?;
+    private readonly itemProcessor?;
+    private readonly bufferSize;
+    private readonly flushInterval;
+    private readonly autoFlush;
+    private readonly onError?;
+    constructor(options: BatchingBufferOptions<T>);
+    /**
+     * 添加数据到缓冲区
+     * @param items 要添加的数据项
+     */
+    add(...items: T[]): void;
+    /**
+     * 手动刷新缓冲区，处理所有待处理的数据
+     * @returns Promise，在处理完成后 resolve
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取当前缓冲区中的数据数量
+     */
+    get size(): number;
+    /**
+     * 检查缓冲区是否为空
+     */
+    get isEmpty(): boolean;
+    /**
+     * 检查是否已被销毁
+     */
+    get destroyed(): boolean;
+    /**
+     * 获取距离上次刷新的时间（毫秒）
+     */
+    get timeSinceLastFlush(): number;
+    /**
+     * 销毁缓冲区，清理定时器并处理剩余数据
+     * @param flushRemaining 是否处理剩余数据，默认为 true
+     */
+    destroy(flushRemaining?: boolean): Promise<void>;
+    /**
+     * 重置定时器
+     */
+    private resetTimer;
+    /**
+     * 清除定时器
+     */
+    private clearTimer;
+    /**
+     * 同步处理缓冲区（用于基于大小的触发）
+     */
+    private processBufferSync;
+    /**
+     * 异步处理缓冲区（用于手动刷新和销毁）
+     */
+    private processBufferAsync;
+}
+//# sourceMappingURL=batching-buffer.d.ts.map

package/output/batching-buffer/batching-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching-buffer.d.ts","sourceRoot":"","sources":["../../source/batching-buffer/batching-buffer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAErD;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAEjD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,IAAI,CAAA;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAmC;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA0C;gBAEvD,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IA2B7C;;;OAGG;IACH,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAiCxB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;;OAGG;IACG,OAAO,CAAC,cAAc,GAAE,OAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB5D;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgEzB;;OAEG;YACW,kBAAkB;CA2BjC"}

package/output/batching-buffer/batching-buffer.js

@@ -0,0 +1,273 @@
+/**
+ * 批处理缓冲区
+ *
+ * 提供数据暂存和批量/单个处理功能的管理对象。
+ * 当缓冲区达到指定数量或距离上次处理达到一定时间时，
+ * 自动调用处理方法进行数据消费。
+ *
+ * @example
+ * ```typescript
+ * // 批量处理模式
+ * const buffer = new BatchingBuffer({
+ *   batchProcessor: async (items) => {
+ *     console.log('批量处理:', items)
+ *     await saveToDatabase(items)
+ *   },
+ *   bufferSize: 10,
+ *   flushInterval: 5000,
+ *   onError: (error, failedItems) => {
+ *     console.error('处理失败:', error, '失败项目:', failedItems)
+ *     // 可以进行重试或其他错误处理逻辑
+ *   }
+ * })
+ *
+ * // 单个处理模式
+ * const buffer = new BatchingBuffer({
+ *   itemProcessor: async (item) => {
+ *     console.log('单个处理:', item)
+ *     await saveToDatabase([item])
+ *   },
+ *   bufferSize: 1,
+ *   flushInterval: 1000
+ * })
+ *
+ * // 添加数据
+ * buffer.add('data1')                    // 添加单个数据
+ * buffer.add('data2', 'data3', 'data4')  // 添加多个数据
+ * buffer.add(...array)                   // 展开数组添加
+ *
+ * // 手动刷新
+ * await buffer.flush()
+ *
+ * // 销毁
+ * buffer.destroy()
+ * ```
+ */
+export class BatchingBuffer {
+    buffer = [];
+    timer = null;
+    isDestroyed = false;
+    lastFlushTime = Date.now();
+    batchProcessor;
+    itemProcessor;
+    bufferSize;
+    flushInterval;
+    autoFlush;
+    onError;
+    constructor(options) {
+        // 验证处理器配置
+        if (!options.batchProcessor && !options.itemProcessor) {
+            throw new Error('必须提供 batchProcessor 或 itemProcessor 其中之一');
+        }
+        if (options.batchProcessor && options.itemProcessor) {
+            throw new Error('只能选择 batchProcessor 或 itemProcessor 中的一个');
+        }
+        this.batchProcessor = options.batchProcessor;
+        this.itemProcessor = options.itemProcessor;
+        this.bufferSize = options.bufferSize ?? 100;
+        this.flushInterval = options.flushInterval ?? 5000;
+        this.autoFlush = options.autoFlush ?? true;
+        this.onError = options.onError;
+        // 验证配置参数
+        if (this.bufferSize <= 0) {
+            throw new Error('bufferSize 必须大于 0');
+        }
+        if (this.flushInterval <= 0) {
+            throw new Error('flushInterval 必须大于 0');
+        }
+    }
+    /**
+     * 添加数据到缓冲区
+     * @param items 要添加的数据项
+     */
+    add(...items) {
+        if (this.isDestroyed) {
+            throw new Error('BatchingBuffer 已被销毁，不能添加新数据');
+        }
+        if (items.length === 0) {
+            return;
+        }
+        let i = 0;
+        while (i < items.length) {
+            // 计算本次可以添加的数量
+            const remainingBufferSpace = this.bufferSize - this.buffer.length;
+            const itemsToAdd = Math.min(remainingBufferSpace, items.length - i);
+            // 添加数据到缓冲区
+            for (let j = 0; j < itemsToAdd; j++) {
+                this.buffer.push(items[i + j]);
+            }
+            i += itemsToAdd;
+            // 如果缓冲区满了，处理它
+            if (this.buffer.length >= this.bufferSize) {
+                this.processBufferSync();
+            }
+        }
+        // 为剩余数据启动定时器（如果还有数据且启用自动刷新）
+        if (this.buffer.length > 0 && this.autoFlush) {
+            this.resetTimer();
+        }
+    }
+    /**
+     * 手动刷新缓冲区，处理所有待处理的数据
+     * @returns Promise，在处理完成后 resolve
+     */
+    async flush() {
+        return this.processBufferAsync();
+    }
+    /**
+     * 获取当前缓冲区中的数据数量
+     */
+    get size() {
+        return this.buffer.length;
+    }
+    /**
+     * 检查缓冲区是否为空
+     */
+    get isEmpty() {
+        return this.buffer.length === 0;
+    }
+    /**
+     * 检查是否已被销毁
+     */
+    get destroyed() {
+        return this.isDestroyed;
+    }
+    /**
+     * 获取距离上次刷新的时间（毫秒）
+     */
+    get timeSinceLastFlush() {
+        return Date.now() - this.lastFlushTime;
+    }
+    /**
+     * 销毁缓冲区，清理定时器并处理剩余数据
+     * @param flushRemaining 是否处理剩余数据，默认为 true
+     */
+    async destroy(flushRemaining = true) {
+        if (this.isDestroyed) {
+            return;
+        }
+        this.clearTimer();
+        if (flushRemaining && this.buffer.length > 0) {
+            await this.processBufferAsync();
+        }
+        else {
+            this.buffer = [];
+        }
+        this.isDestroyed = true;
+    }
+    /**
+     * 重置定时器
+     */
+    resetTimer() {
+        this.clearTimer();
+        this.timer = setTimeout(() => {
+            this.processBufferSync();
+        }, this.flushInterval);
+    }
+    /**
+     * 清除定时器
+     */
+    clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * 同步处理缓冲区（用于基于大小的触发）
+     */
+    processBufferSync() {
+        if (this.buffer.length === 0 || this.isDestroyed) {
+            return;
+        }
+        this.clearTimer();
+        const itemsToProcess = this.buffer.splice(0);
+        try {
+            if (this.batchProcessor) {
+                // 批量处理模式
+                const result = this.batchProcessor(itemsToProcess);
+                // 如果返回 Promise，处理异步
+                if (result && typeof result.then === 'function') {
+                    result.catch((error) => {
+                        // 处理失败时，将数据重新放回缓冲区开头（如果没有被销毁）
+                        if (!this.isDestroyed) {
+                            this.buffer.unshift(...itemsToProcess);
+                        }
+                        // 调用错误处理回调
+                        if (this.onError) {
+                            this.onError(error, itemsToProcess);
+                        }
+                    });
+                }
+            }
+            else if (this.itemProcessor) {
+                // 单个处理模式 - 同步处理每个项目
+                const failedItems = [];
+                for (let i = 0; i < itemsToProcess.length; i++) {
+                    const item = itemsToProcess[i];
+                    try {
+                        const result = this.itemProcessor(item);
+                        // 如果返回 Promise，处理异步
+                        if (result && typeof result.then === 'function') {
+                            result.catch((error) => {
+                                // 处理失败时，将数据重新放回缓冲区开头（如果没有被销毁）
+                                if (!this.isDestroyed) {
+                                    this.buffer.unshift(item);
+                                }
+                                // 调用错误处理回调
+                                if (this.onError) {
+                                    this.onError(error, [item]);
+                                }
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // 同步错误处理 - 把当前项目和未处理的项目放回缓冲区
+                        failedItems.push(item);
+                        failedItems.push(...itemsToProcess.slice(i + 1));
+                        this.buffer.unshift(...failedItems);
+                        throw error;
+                    }
+                }
+            }
+            this.lastFlushTime = Date.now();
+        }
+        catch (error) {
+            // 批量处理模式的错误处理
+            if (this.batchProcessor) {
+                this.buffer.unshift(...itemsToProcess);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 异步处理缓冲区（用于手动刷新和销毁）
+     */
+    async processBufferAsync() {
+        if (this.buffer.length === 0) {
+            return;
+        }
+        this.clearTimer();
+        const itemsToProcess = this.buffer.splice(0);
+        try {
+            if (this.batchProcessor) {
+                // 批量处理模式
+                await this.batchProcessor(itemsToProcess);
+            }
+            else if (this.itemProcessor) {
+                // 单个处理模式
+                for (const item of itemsToProcess) {
+                    await this.itemProcessor(item);
+                }
+            }
+            this.lastFlushTime = Date.now();
+        }
+        catch (error) {
+            // 处理失败时，将数据重新放回缓冲区开头（如果没有被销毁）
+            if (!this.isDestroyed) {
+                this.buffer.unshift(...itemsToProcess);
+            }
+            throw error;
+        }
+    }
+}

package/output/batching-buffer/batching-buffer.test.d.ts

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

package/output/batching-buffer/batching-buffer.test.d.ts.map

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