@zucker-framework/buffer 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,22 @@
+Zucker Framework
+Copyright 2026 Lind and Zucker Framework contributors
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+The framework includes TypeScript adaptations and enhancements of concepts and
+implementations from hsweb-framework and jetlinks-community, both distributed
+under the Apache License, Version 2.0. Individual packages use different subsets
+of the framework. The TypeScript adaptations and Node.js integrations were
+modified for Zucker Framework; they are not the original upstream distribution.
+
+hsweb-framework
+https://github.com/hs-web/hsweb-framework
+Copyright 2020 http://hsweb.me
+
+jetlinks-community
+https://github.com/jetlinks/jetlinks-community
+
+See THIRD_PARTY_NOTICES for license texts and attribution for bundled dependencies
+and reference implementations relevant to this package. External dependencies
+remain subject to their own licenses. This NOTICE is informational and does not
+modify any license or grant rights to upstream trademarks.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,4 @@
+@zucker-framework/buffer
+
+No separately recorded third-party implementation is bundled in this package.
+External dependencies retain their own licenses; see NOTICE for framework attribution.

package/dist/index.d.mts

@@ -0,0 +1,130 @@
+/**
+ * Buffer 配置
+ *
+ * 对齐 jetlinks BufferSettings：
+ * - filePath / fileName 用于文件队列持久化
+ * - retryWhenError 谓词控制是否重试
+ * - parallelism 基于 CPU 核数的默认值
+ */
+interface BufferSettings {
+    /** 缓冲区大小，超过后自动刷新，默认 1000 */
+    bufferSize: number;
+    /** 刷新超时时间（毫秒），默认 2000 */
+    flushTimeoutMs: number;
+    /** 最大重试次数，默认 5（对齐 jetlinks 默认值） */
+    maxRetries: number;
+    /** 并行度，默认 CPU/2（对齐 jetlinks） */
+    parallelism: number;
+    /** 文件队列目录，用于内存溢出时持久化 */
+    fileQueueDir?: string;
+    /** 错误重试判断谓词，返回 true 表示应重试 */
+    retryWhenError?: (error: unknown) => boolean;
+    /** Buffer 名称，用于日志和指标 */
+    name?: string;
+}
+/** 默认重试判断：网络/IO 相关错误可重试 */
+declare const defaultRetryWhenError: (error: unknown) => boolean;
+declare const DEFAULT_BUFFER_SETTINGS: BufferSettings;
+/**
+ * 缓冲条目接口 — 对应 jetlinks Buffered<T>
+ * 允许 handler 对每个条目标记重试或死信
+ */
+interface Buffered<T> {
+    /** 原始数据 */
+    readonly data: T;
+    /** 当前重试次数 */
+    readonly retryTimes: number;
+    /** 标记此条目需要重试 */
+    retry(shouldRetry?: boolean): void;
+    /** 标记此条目进入死信队列 */
+    dead(): void;
+}
+/**
+ * 刷新上下文 — 对应 jetlinks FlushContext<T>
+ * handler 可以通过此接口报告错误
+ */
+interface FlushContext<T> {
+    /** 报告错误信息 */
+    error(err: Error): void;
+    /** 本批次的缓冲条目列表 */
+    readonly items: ReadonlyArray<Buffered<T>>;
+    /** 本批次大小 */
+    readonly size: number;
+}
+/**
+ * 内存使用估算接口 — 对应 jetlinks MemoryUsage
+ * 实现此接口的数据类型可以提供精确的内存占用估算
+ */
+interface MemoryUsage {
+    /** 返回估算的字节数 */
+    usage(): number;
+}
+
+type FlushHandler<T> = (items: T[]) => Promise<void>;
+/**
+ * 持久化缓冲 — 批量写入工具
+ *
+ * 支持：
+ * - 自动定时刷新
+ * - 缓冲区满时自动刷新
+ * - 内存溢出时写入文件队列
+ * - 失败项进入死信队列
+ * - 可配置并行度
+ */
+declare class PersistenceBuffer<T> {
+    private buffer;
+    private deadLetterQueue;
+    private flushTimer;
+    private handlers;
+    private flushing;
+    private settings;
+    private fileQueueDir;
+    private disposed;
+    /** Optional error callback for non-fatal flush failures */
+    onError?: (err: unknown) => void;
+    constructor(settings?: Partial<BufferSettings>);
+    /**
+     * 注册刷新处理器
+     */
+    onFlush(handler: FlushHandler<T>): this;
+    /**
+     * 启动定时刷新
+     */
+    start(): this;
+    /**
+     * 停止定时刷新并刷新剩余数据
+     */
+    stop(): Promise<void>;
+    /**
+     * 写入缓冲
+     */
+    write(item: T): void;
+    /**
+     * 批量写入
+     */
+    writeMany(items: T[]): void;
+    /**
+     * 手动刷新
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取死信队列中的数据
+     */
+    getDeadLetterQueue(): T[];
+    /**
+     * 清空死信队列
+     */
+    clearDeadLetterQueue(): void;
+    /**
+     * 获取当前缓冲区大小
+     */
+    get size(): number;
+    private processChunk;
+    /**
+     * 将数据写入文件队列（内存溢出保护）
+     */
+    spillToFile(items: T[]): void;
+    private loadFromFileQueue;
+}
+
+export { type BufferSettings, type Buffered, DEFAULT_BUFFER_SETTINGS, type FlushContext, type FlushHandler, type MemoryUsage, PersistenceBuffer, defaultRetryWhenError };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Buffer 配置
+ *
+ * 对齐 jetlinks BufferSettings：
+ * - filePath / fileName 用于文件队列持久化
+ * - retryWhenError 谓词控制是否重试
+ * - parallelism 基于 CPU 核数的默认值
+ */
+interface BufferSettings {
+    /** 缓冲区大小，超过后自动刷新，默认 1000 */
+    bufferSize: number;
+    /** 刷新超时时间（毫秒），默认 2000 */
+    flushTimeoutMs: number;
+    /** 最大重试次数，默认 5（对齐 jetlinks 默认值） */
+    maxRetries: number;
+    /** 并行度，默认 CPU/2（对齐 jetlinks） */
+    parallelism: number;
+    /** 文件队列目录，用于内存溢出时持久化 */
+    fileQueueDir?: string;
+    /** 错误重试判断谓词，返回 true 表示应重试 */
+    retryWhenError?: (error: unknown) => boolean;
+    /** Buffer 名称，用于日志和指标 */
+    name?: string;
+}
+/** 默认重试判断：网络/IO 相关错误可重试 */
+declare const defaultRetryWhenError: (error: unknown) => boolean;
+declare const DEFAULT_BUFFER_SETTINGS: BufferSettings;
+/**
+ * 缓冲条目接口 — 对应 jetlinks Buffered<T>
+ * 允许 handler 对每个条目标记重试或死信
+ */
+interface Buffered<T> {
+    /** 原始数据 */
+    readonly data: T;
+    /** 当前重试次数 */
+    readonly retryTimes: number;
+    /** 标记此条目需要重试 */
+    retry(shouldRetry?: boolean): void;
+    /** 标记此条目进入死信队列 */
+    dead(): void;
+}
+/**
+ * 刷新上下文 — 对应 jetlinks FlushContext<T>
+ * handler 可以通过此接口报告错误
+ */
+interface FlushContext<T> {
+    /** 报告错误信息 */
+    error(err: Error): void;
+    /** 本批次的缓冲条目列表 */
+    readonly items: ReadonlyArray<Buffered<T>>;
+    /** 本批次大小 */
+    readonly size: number;
+}
+/**
+ * 内存使用估算接口 — 对应 jetlinks MemoryUsage
+ * 实现此接口的数据类型可以提供精确的内存占用估算
+ */
+interface MemoryUsage {
+    /** 返回估算的字节数 */
+    usage(): number;
+}
+
+type FlushHandler<T> = (items: T[]) => Promise<void>;
+/**
+ * 持久化缓冲 — 批量写入工具
+ *
+ * 支持：
+ * - 自动定时刷新
+ * - 缓冲区满时自动刷新
+ * - 内存溢出时写入文件队列
+ * - 失败项进入死信队列
+ * - 可配置并行度
+ */
+declare class PersistenceBuffer<T> {
+    private buffer;
+    private deadLetterQueue;
+    private flushTimer;
+    private handlers;
+    private flushing;
+    private settings;
+    private fileQueueDir;
+    private disposed;
+    /** Optional error callback for non-fatal flush failures */
+    onError?: (err: unknown) => void;
+    constructor(settings?: Partial<BufferSettings>);
+    /**
+     * 注册刷新处理器
+     */
+    onFlush(handler: FlushHandler<T>): this;
+    /**
+     * 启动定时刷新
+     */
+    start(): this;
+    /**
+     * 停止定时刷新并刷新剩余数据
+     */
+    stop(): Promise<void>;
+    /**
+     * 写入缓冲
+     */
+    write(item: T): void;
+    /**
+     * 批量写入
+     */
+    writeMany(items: T[]): void;
+    /**
+     * 手动刷新
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取死信队列中的数据
+     */
+    getDeadLetterQueue(): T[];
+    /**
+     * 清空死信队列
+     */
+    clearDeadLetterQueue(): void;
+    /**
+     * 获取当前缓冲区大小
+     */
+    get size(): number;
+    private processChunk;
+    /**
+     * 将数据写入文件队列（内存溢出保护）
+     */
+    spillToFile(items: T[]): void;
+    private loadFromFileQueue;
+}
+
+export { type BufferSettings, type Buffered, DEFAULT_BUFFER_SETTINGS, type FlushContext, type FlushHandler, type MemoryUsage, PersistenceBuffer, defaultRetryWhenError };

package/dist/index.js

@@ -0,0 +1,258 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_BUFFER_SETTINGS: () => DEFAULT_BUFFER_SETTINGS,
+  PersistenceBuffer: () => PersistenceBuffer,
+  defaultRetryWhenError: () => defaultRetryWhenError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/persistence-buffer.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var os = __toESM(require("os"));
+var import_core = require("@zucker-framework/core");
+
+// src/buffer-settings.ts
+var defaultRetryWhenError = /* @__PURE__ */ __name((error) => {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return msg.includes("timeout") || msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("epipe") || msg.includes("network") || msg.includes("unavailable") || msg.includes("deadlock");
+  }
+  return false;
+}, "defaultRetryWhenError");
+function getDefaultParallelism() {
+  try {
+    const os2 = require("os");
+    return Math.max(1, Math.floor(os2.cpus().length / 2));
+  } catch {
+    return 1;
+  }
+}
+__name(getDefaultParallelism, "getDefaultParallelism");
+var DEFAULT_BUFFER_SETTINGS = {
+  bufferSize: 1e3,
+  flushTimeoutMs: 2e3,
+  maxRetries: 5,
+  parallelism: getDefaultParallelism(),
+  retryWhenError: defaultRetryWhenError
+};
+
+// src/persistence-buffer.ts
+var PersistenceBuffer = class {
+  static {
+    __name(this, "PersistenceBuffer");
+  }
+  buffer = [];
+  deadLetterQueue = [];
+  flushTimer = null;
+  handlers = [];
+  flushing = false;
+  settings;
+  fileQueueDir;
+  disposed = false;
+  /** Optional error callback for non-fatal flush failures */
+  onError;
+  constructor(settings) {
+    this.settings = {
+      ...DEFAULT_BUFFER_SETTINGS,
+      ...settings
+    };
+    this.fileQueueDir = this.settings.fileQueueDir ?? path.join(os.tmpdir(), "zucker-buffer");
+  }
+  /**
+  * 注册刷新处理器
+  */
+  onFlush(handler) {
+    this.handlers.push(handler);
+    return this;
+  }
+  /**
+  * 启动定时刷新
+  */
+  start() {
+    if (this.flushTimer) return this;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        if (this.onError) this.onError(err);
+      });
+    }, this.settings.flushTimeoutMs);
+    return this;
+  }
+  /**
+  * 停止定时刷新并刷新剩余数据
+  */
+  async stop() {
+    this.disposed = true;
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  /**
+  * 写入缓冲
+  */
+  write(item) {
+    if (this.disposed) {
+      throw new import_core.BusinessException("Buffer has been disposed", "BUFFER_DISPOSED", 500);
+    }
+    this.buffer.push(item);
+    if (this.buffer.length >= this.settings.bufferSize) {
+      this.flush().catch((err) => {
+        if (this.onError) this.onError(err);
+      });
+    }
+  }
+  /**
+  * 批量写入
+  */
+  writeMany(items) {
+    if (!items || items.length === 0) return;
+    for (const item of items) {
+      this.write(item);
+    }
+  }
+  /**
+  * 手动刷新
+  */
+  async flush() {
+    if (this.flushing || this.buffer.length === 0) return;
+    this.flushing = true;
+    try {
+      const items = this.buffer.splice(0);
+      const fileItems = this.loadFromFileQueue();
+      const allItems = [
+        ...fileItems,
+        ...items
+      ];
+      if (allItems.length === 0) return;
+      const chunkSize = Math.ceil(allItems.length / this.settings.parallelism);
+      const chunks = [];
+      for (let i = 0; i < allItems.length; i += chunkSize) {
+        chunks.push(allItems.slice(i, i + chunkSize));
+      }
+      await Promise.all(chunks.map((chunk) => this.processChunk(chunk)));
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /**
+  * 获取死信队列中的数据
+  */
+  getDeadLetterQueue() {
+    return [
+      ...this.deadLetterQueue
+    ];
+  }
+  /**
+  * 清空死信队列
+  */
+  clearDeadLetterQueue() {
+    this.deadLetterQueue = [];
+  }
+  /**
+  * 获取当前缓冲区大小
+  */
+  get size() {
+    return this.buffer.length;
+  }
+  async processChunk(items) {
+    let retries = 0;
+    while (retries <= this.settings.maxRetries) {
+      try {
+        for (const handler of this.handlers) {
+          await handler(items);
+        }
+        return;
+      } catch (err) {
+        retries++;
+        const shouldRetry = this.settings.retryWhenError?.(err) ?? false;
+        if (!shouldRetry || retries > this.settings.maxRetries) {
+          if (this.onError) this.onError(err);
+          this.deadLetterQueue.push(...items);
+          return;
+        }
+        await new Promise((r) => setTimeout(r, Math.min(100 * Math.pow(2, retries), 5e3)));
+      }
+    }
+  }
+  /**
+  * 将数据写入文件队列（内存溢出保护）
+  */
+  spillToFile(items) {
+    if (!items || items.length === 0) return;
+    try {
+      if (!fs.existsSync(this.fileQueueDir)) {
+        fs.mkdirSync(this.fileQueueDir, {
+          recursive: true
+        });
+      }
+      const filename = `buffer-${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
+      fs.writeFileSync(path.join(this.fileQueueDir, filename), JSON.stringify(items));
+    } catch (err) {
+      if (this.onError) this.onError(err);
+      this.deadLetterQueue.push(...items);
+    }
+  }
+  loadFromFileQueue() {
+    const items = [];
+    try {
+      if (!fs.existsSync(this.fileQueueDir)) return items;
+      const files = fs.readdirSync(this.fileQueueDir).filter((f) => f.endsWith(".json"));
+      for (const file of files) {
+        const filePath = path.join(this.fileQueueDir, file);
+        try {
+          const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+          if (Array.isArray(data)) items.push(...data);
+          fs.unlinkSync(filePath);
+        } catch (parseErr) {
+          if (this.onError) this.onError(parseErr);
+          try {
+            fs.unlinkSync(filePath);
+          } catch {
+          }
+        }
+      }
+    } catch (dirErr) {
+      if (this.onError) this.onError(dirErr);
+    }
+    return items;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BUFFER_SETTINGS,
+  PersistenceBuffer,
+  defaultRetryWhenError
+});

package/dist/index.mjs

@@ -0,0 +1,227 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/persistence-buffer.ts
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { BusinessException } from "@zucker-framework/core";
+
+// src/buffer-settings.ts
+var defaultRetryWhenError = /* @__PURE__ */ __name((error) => {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return msg.includes("timeout") || msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("epipe") || msg.includes("network") || msg.includes("unavailable") || msg.includes("deadlock");
+  }
+  return false;
+}, "defaultRetryWhenError");
+function getDefaultParallelism() {
+  try {
+    const os2 = __require("os");
+    return Math.max(1, Math.floor(os2.cpus().length / 2));
+  } catch {
+    return 1;
+  }
+}
+__name(getDefaultParallelism, "getDefaultParallelism");
+var DEFAULT_BUFFER_SETTINGS = {
+  bufferSize: 1e3,
+  flushTimeoutMs: 2e3,
+  maxRetries: 5,
+  parallelism: getDefaultParallelism(),
+  retryWhenError: defaultRetryWhenError
+};
+
+// src/persistence-buffer.ts
+var PersistenceBuffer = class {
+  static {
+    __name(this, "PersistenceBuffer");
+  }
+  buffer = [];
+  deadLetterQueue = [];
+  flushTimer = null;
+  handlers = [];
+  flushing = false;
+  settings;
+  fileQueueDir;
+  disposed = false;
+  /** Optional error callback for non-fatal flush failures */
+  onError;
+  constructor(settings) {
+    this.settings = {
+      ...DEFAULT_BUFFER_SETTINGS,
+      ...settings
+    };
+    this.fileQueueDir = this.settings.fileQueueDir ?? path.join(os.tmpdir(), "zucker-buffer");
+  }
+  /**
+  * 注册刷新处理器
+  */
+  onFlush(handler) {
+    this.handlers.push(handler);
+    return this;
+  }
+  /**
+  * 启动定时刷新
+  */
+  start() {
+    if (this.flushTimer) return this;
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        if (this.onError) this.onError(err);
+      });
+    }, this.settings.flushTimeoutMs);
+    return this;
+  }
+  /**
+  * 停止定时刷新并刷新剩余数据
+  */
+  async stop() {
+    this.disposed = true;
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  /**
+  * 写入缓冲
+  */
+  write(item) {
+    if (this.disposed) {
+      throw new BusinessException("Buffer has been disposed", "BUFFER_DISPOSED", 500);
+    }
+    this.buffer.push(item);
+    if (this.buffer.length >= this.settings.bufferSize) {
+      this.flush().catch((err) => {
+        if (this.onError) this.onError(err);
+      });
+    }
+  }
+  /**
+  * 批量写入
+  */
+  writeMany(items) {
+    if (!items || items.length === 0) return;
+    for (const item of items) {
+      this.write(item);
+    }
+  }
+  /**
+  * 手动刷新
+  */
+  async flush() {
+    if (this.flushing || this.buffer.length === 0) return;
+    this.flushing = true;
+    try {
+      const items = this.buffer.splice(0);
+      const fileItems = this.loadFromFileQueue();
+      const allItems = [
+        ...fileItems,
+        ...items
+      ];
+      if (allItems.length === 0) return;
+      const chunkSize = Math.ceil(allItems.length / this.settings.parallelism);
+      const chunks = [];
+      for (let i = 0; i < allItems.length; i += chunkSize) {
+        chunks.push(allItems.slice(i, i + chunkSize));
+      }
+      await Promise.all(chunks.map((chunk) => this.processChunk(chunk)));
+    } finally {
+      this.flushing = false;
+    }
+  }
+  /**
+  * 获取死信队列中的数据
+  */
+  getDeadLetterQueue() {
+    return [
+      ...this.deadLetterQueue
+    ];
+  }
+  /**
+  * 清空死信队列
+  */
+  clearDeadLetterQueue() {
+    this.deadLetterQueue = [];
+  }
+  /**
+  * 获取当前缓冲区大小
+  */
+  get size() {
+    return this.buffer.length;
+  }
+  async processChunk(items) {
+    let retries = 0;
+    while (retries <= this.settings.maxRetries) {
+      try {
+        for (const handler of this.handlers) {
+          await handler(items);
+        }
+        return;
+      } catch (err) {
+        retries++;
+        const shouldRetry = this.settings.retryWhenError?.(err) ?? false;
+        if (!shouldRetry || retries > this.settings.maxRetries) {
+          if (this.onError) this.onError(err);
+          this.deadLetterQueue.push(...items);
+          return;
+        }
+        await new Promise((r) => setTimeout(r, Math.min(100 * Math.pow(2, retries), 5e3)));
+      }
+    }
+  }
+  /**
+  * 将数据写入文件队列（内存溢出保护）
+  */
+  spillToFile(items) {
+    if (!items || items.length === 0) return;
+    try {
+      if (!fs.existsSync(this.fileQueueDir)) {
+        fs.mkdirSync(this.fileQueueDir, {
+          recursive: true
+        });
+      }
+      const filename = `buffer-${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
+      fs.writeFileSync(path.join(this.fileQueueDir, filename), JSON.stringify(items));
+    } catch (err) {
+      if (this.onError) this.onError(err);
+      this.deadLetterQueue.push(...items);
+    }
+  }
+  loadFromFileQueue() {
+    const items = [];
+    try {
+      if (!fs.existsSync(this.fileQueueDir)) return items;
+      const files = fs.readdirSync(this.fileQueueDir).filter((f) => f.endsWith(".json"));
+      for (const file of files) {
+        const filePath = path.join(this.fileQueueDir, file);
+        try {
+          const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+          if (Array.isArray(data)) items.push(...data);
+          fs.unlinkSync(filePath);
+        } catch (parseErr) {
+          if (this.onError) this.onError(parseErr);
+          try {
+            fs.unlinkSync(filePath);
+          } catch {
+          }
+        }
+      }
+    } catch (dirErr) {
+      if (this.onError) this.onError(dirErr);
+    }
+    return items;
+  }
+};
+export {
+  DEFAULT_BUFFER_SETTINGS,
+  PersistenceBuffer,
+  defaultRetryWhenError
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zucker-framework/buffer",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "dependencies": {
+    "@zucker-framework/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43"
+  },
+  "license": "Apache-2.0",
+  "author": "Lind",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lind-pro/zucker-framework.git",
+    "directory": "packages/buffer"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/"
+  }
+}