# @batchactions/core 中文文档

规范地址：https://npmcn.com/package/%40batchactions/core/

版本：0\.0\.6
npm 元数据更新时间：2026-03-14T09:54:08.611Z
中文译文更新时间：2026-11-08T07:26:27.779Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40batchactions/core
原文对照：https://npmcn.com/package/%40batchactions/core/?lang=original
项目主页：https://github.com/vgpastor/batchactions/tree/main/packages/core#readme
源码仓库：https://github.com/vgpastor/batchactions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：427 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2026-02-18T10:22:06.680Z
- 最新版本发布：2026-03-14T09:54:08.039Z
- 近 30 天下载量：1871（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

TypeScript 批量工作引擎,用于ETL 和批量数据处理,与状态管理、重试、暂停/恢复以及生命周期事件

## 安装

```sh
npm install @batchactions/core
```

也可以使用：`pnpm add @batchactions/core`、`yarn add @batchactions/core`、`bun add @batchactions/core`

## README

# @ batchactions/ core (帮助)

核心批量处理引擎 `@batchactions` 生态系统.

当您需要低级控制批量管弦、状态过渡、事件和基础设施适配器时使用此软件包.

## 安装

```bash
npm install @batchactions/core
```

## 你得到的东西

-   `BatchEngine` 用于流式批量执行
-   工作周期控制:开始、暂停、恢复、中止、处理块
-   任务、批量和记录进度的域事件
-   内建来源: `BufferSource`, (中文(简体) ), `FilePathSource`, (中文(简体) ), `StreamSource`, (中文(简体) ), `UrlSource`
-   已建成的国营商店: `InMemoryStateStore`, (中文(简体) ), `FileStateStore`
-   分配合同: `DistributedStateStore`, (中文(简体) ), `BatchReservation`,帮助者

## 快速启动

```typescript
import { BatchEngine, BufferSource, InMemoryStateStore } from '@batchactions/core';

const engine = new BatchEngine({
  stateStore: new InMemoryStateStore(),
  batchSize: 100,
  maxConcurrentBatches: 2,
  continueOnError: true,
});

engine.from(new BufferSource(JSON.stringify([{ id: 1 }, { id: 2 }])), {
  async *parse(chunk) {
    const rows = JSON.parse(chunk.toString()) as Array<Record<string, unknown>>;
    for (const row of rows) {
      yield row;
    }
  },
});

await engine.start(async (record) => {
  await processRecord(record);
});
```

## 记忆记录

当您的数据已经存在内存时( 数据库结果, API 响应等), 跳过源/ parser 管道 :

```typescript
import { BatchEngine } from '@batchactions/core';

const accounts = [
  { id: 'acc-1', channel: 'email', status: 'active' },
  { id: 'acc-2', channel: 'sms', status: 'active' },
];

const engine = new BatchEngine({
  batchSize: 50,
  maxConcurrentBatches: 4,
  continueOnError: true,
  maxRetries: 2,
});

engine.fromRecords(accounts);

await engine.start(async (record) => {
  await healthCheck(record);
});
```

此外,还利用同步发电机进行懒惰评价:

```typescript
async function* fetchPages(): AsyncIterable<Record<string, unknown>> {
  let page = 1;
  while (true) {
    const results = await api.getPage(page++);
    if (results.length === 0) break;
    for (const item of results) yield item;
  }
}

engine.fromRecords(fetchPages());
```

## 无服务器 / 断开处理

使用 `processChunk()` 与 `restore()` 以在多个引用中渐进处理记录——对有执行时限的无服务器环境(AWS Lambda、Vercel函数、Cloudflare Workers)的理想.

### 基本图案

```typescript
import { BatchEngine, InMemoryStateStore } from '@batchactions/core';

const stateStore = new InMemoryStateStore(); // or FileStateStore, SequelizeStateStore, etc.

export async function handler(event: { jobId?: string }) {
  let engine: BatchEngine;

  if (event.jobId) {
    // Subsequent invocation: restore from persisted state
    const restored = await BatchEngine.restore(event.jobId, { stateStore, batchSize: 100 });
    if (!restored) throw new Error('Job not found');
    engine = restored;
  } else {
    // First invocation: create a new engine
    engine = new BatchEngine({ stateStore, batchSize: 100, continueOnError: true });
  }

  // The source must be re-fed on every invocation (it will be re-streamed)
  engine.from(source, parser);

  const result = await engine.processChunk(
    async (record) => { await processRecord(record); },
    { maxDurationMs: 25_000 },  // stop before Lambda's 30s timeout
  );

  if (!result.done) {
    // Schedule the next invocation with the job ID
    await scheduleNext({ jobId: result.jobId });
  }

  return { done: result.done, processed: result.totalProcessed };
}
```

### `maxRecords` 对 `maxDurationMs`

| 选项 | 何时使用 | 边界行为 |
| --- | --- | --- |
| `maxRecords` | 可预测块大小(例如“每次引用处理500个记录”) | 完成超过记录限制的批次后停止 |
| `maxDurationMs` | 有时间限制的环境(例如"在兰布达超时前停车") | 检查在 **批量边界** - 实际期限可超过限额一次 |

两个选项可以合并. 块停止当 **无论是** 已达到极限.

### 重要说明

-   **重组要求**: 来源必须在每次援引时通过 `from()` 或者说 `fromRecords()`。引擎从头进行再流,并自动跳过已完成的批次.
-   **批量级别边界**:在批次之间,而不是记录之间检查春克限制. 一批总是在块停止前完成. 用一个较小的 `batchSize` 为了更好的控制.
-   **使用持久状态 Store**数字 : `InMemoryStateStore` 在进程重新启动之间失去状态。 用于生产无服务器,配对 `@batchactions/state-sequelize` 或者说 `@batchactions/state-prisma`。 。 。 .
-   **`done` 旗帜**编号: `ChunkResult.done` 财产可靠地表明是否已处理所有记录。 进展衡量尺度`totalRecords`, (中文(简体) ), `percentage`在来源被完全消耗之前,可能显示部分总数.

## 主要出口

-   `BatchEngine`
-   `BatchSplitter`
-   `EventBus`, (中文(简体) ), `JobContext`
-   `JobStatus`, (中文(简体) ), `BatchStatus`
-   `BufferSource`, (中文(简体) ), `FilePathSource`, (中文(简体) ), `StreamSource`, (中文(简体) ), `UrlSource`
-   `InMemoryStateStore`, (中文(简体) ), `FileStateStore`
-   `isDistributedStateStore`

完整类型出口,见 `packages/core/src/index.ts`。 。 。 .

## 兼容性

-   节点.js >= 20.0.0

## 相关软件包

-   `@batchactions/import`: 高级进口外观
-   `@batchactions/distributed`: 多工管弦乐
-   `@batchactions/state-sequelize`: SQL 持久性适配器(Sequelize)
-   `@batchactions/state-prisma`: SQL 持久性适配器 (Prisma v6/v7)

## 链接

-   仓库 : [https://github.com/vgpastor/batchactions/tree/main/packages/core 页面存档备份,存于互联网档案馆](https://github.com/vgpastor/batchactions/tree/main/packages/core)
-   问题: [https://github.com/vgpastor/batchactions/ issues (中文(简体) )](https://github.com/vgpastor/batchactions/issues)
-   贡献指南 : [https://github.com/vgpastor/batchactions/blob/main/CONTRIPIBUTING.md 互联网档案馆的存檔,存档日期2014-12-22](https://github.com/vgpastor/batchactions/blob/main/CONTRIBUTING.md)

## 许可证

麻省理工学院

## 常见问题

### @batchactions/core 是什么？

TypeScript 批量工作引擎,用于ETL 和批量数据处理,与状态管理、重试、暂停/恢复以及生命周期事件

### 如何安装 @batchactions/core？

在项目目录运行 npm install @batchactions/core，或使用 pnpm add / yarn add / bun add。

### @batchactions/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @batchactions/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @batchactions/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @batchactions/core 可以商用吗？

@batchactions/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @batchactions/core 的下载量有多少？

根据 npm 官方下载统计，@batchactions/core 在 2026/10/08 – 2026/11/06 这 30 天内被下载 1,871 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @batchactions/core 还在维护吗？

最新版本 0\.0\.6 发布于 2026/03/14（7 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/02/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。