# @godspeedai/cognate-events 中文文档

规范地址：https://npmcn.com/package/%40godspeedai/cognate-events/

版本：0\.10\.0
npm 元数据更新时间：2026-11-16T03:41:03.565Z
中文译文更新时间：2026-11-16T18:03:30.613Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40godspeedai/cognate-events
原文对照：https://npmcn.com/package/%40godspeedai/cognate-events/?lang=original
项目主页：https://github.com/GodSpeedAI/Cognate#readme
源码仓库：https://github.com/GodSpeedAI/Cognate

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

- 包体积（解压后）：78.6 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2026-10-09T02:28:17.914Z
- 最新版本发布：2026-11-16T03:41:03.145Z
- 近 30 天下载量：6438（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

活动信封,耐用商店端口, 和商店的配套套件.

## 安装

```sh
npm install @godspeedai/cognate-events
```

也可以使用：`pnpm add @godspeedai/cognate-events`、`yarn add @godspeedai/cognate-events`、`bun add @godspeedai/cognate-events`

## README

# @ godspideai/ cognate- events

科格纳特的耐久状态平面合同: Cononical event 信封, the `DurableStore` 端口每个商店工具, 以及一个发件箱调度器, 用于执行后的工作 。 这个包件定义了合同——它没有运送储存.

**何时使用此软件包 :** 您正在执行一个持久的商店, 在事件日志上构建工具, 或者亲自发送发件箱。 应用程序通过工作商店 [`@godspeedai/cognate-store-sqlite`](https://www.npmjs.com/package/@godspeedai/cognate-store-sqlite) 或者说 [`@godspeedai/cognate-store-memory`](https://www.npmjs.com/package/@godspeedai/cognate-store-memory), (中文(简体) ), 两者均执行本合同.

## 安装

```sh
bun add @godspeedai/cognate-events
```

要求数 [阿宝](https://bun.sh/) >= 1.4.0.

## 那个信封

`NewEvent` 是决定提出的。 店铺指定 `eventId`, (中文(简体) ), `streamId`, (中文(简体) ), `streamSequence` (每条溪流无差距), `position` (全店承诺令),以及 `recordedAt`顺序和位置是命令当局—— `occurredAt` 是源头声称的来源 从来没有命令事件.

`validateNewEvent` 写入任何文件前执行信封: 需要的字段存在, 小写点 `eventType`正整数 `schemaVersion`,ISO-8601 标准 `occurredAt`,1米B范围内的JSON载荷(`MAX_PAYLOAD_BYTES`) (中文(简体) ). 失败投出 `EnvelopeValidationError` 列出每个问题.

`fingerprint` 计算JSON请求中一个稳定,按键顺序独立的SHA-256——除了不同的请求外,用何来表示回放.

## 快开始

```ts
import { fingerprint, validateNewEvent } from "@godspeedai/cognate-events";

const placed = {
  eventType: "order.placed",
  schemaVersion: 1,
  occurredAt: new Date().toISOString(),
  tenant: "tenant-a",
  correlationId: "corr-1",
  causationId: null,
  runId: null,
  scopeId: "root",
  payload: { sku: "widget", quantity: 2 },
};
validateNewEvent(placed);

const commit = {
  idempotency: { scope: "alice:order", key: "order-1", fingerprint: fingerprint(placed.payload) },
  appends: [{ streamId: "order-1", expectedVersion: 0, events: [placed] }],
  result: { placed: true },
};
```

手 `commit` 对任意 `DurableStore` 这里的记忆之一:

```ts
import { createMemoryStore } from "@godspeedai/cognate-store-memory";

const store = createMemoryStore();
const outcome = await store.commit(commit);
// { kind: "committed", events: [...], records: [], result: { placed: true } }
```

再次提交同一请求返回 `{ kind: "duplicate", result: { placed: true } }` ——原收录的结果,没有写出新的事实. 为不同的请求重用密钥 `IdempotencyMismatchError`。 。 。 .

## 什麽 `DurableStore` 覆盖

一个原子 `commit` - 全部或无:

-   由预期版本保护的流式附件( 丢弃的比赛) `ConcurrencyError`; 重读并重试, 永不覆盖 ;
-   比较和扫描记录写道(`RecordConflictError`(三);
-   犯罪后工作意图;
-   与裁决一起记录的一能结果.

超越 `commit`数字 : `readStream`编号 :`readAll` 页面顺序和位置顺序, `getRecord`编号 :`listRecords` 读取版本记录, `onCommitted` 订阅事件(仅在交易完成后才使用),投影检查点按投影状态进行解剖,blobs被处理内容(`sha256:<hex>`),以及 `erasePayload` 移除事件的有效载荷,同时保留其信封,并将墓碑事件附在 `$erasures` 流线.

## 提供外包服务

`OutboxDispatcher` 声称有犯罪意图,并至少交付一次,有限度的指数反射:

```ts
import { OutboxDispatcher } from "@godspeedai/cognate-events";

const dispatcher = new OutboxDispatcher(store, {
  topic: "email",
  backoff: { baseMs: 100, maxMs: 5_000, maxAttempts: 10 },
  deliver: async (item) => {
    await sendEmail(item.payload);
    return { accepted: item.id };
  },
});

const report = await dispatcher.drain();
// { delivered: [...], retried: [{ id, retryAt }], poisoned: [...] }
```

掷出 `PermanentDeliveryError` 从 `deliver` 立即下毒,而不是重试。 有毒物品通过 `store.listOutbox({ status: "poisoned" })` 直到操作员打电话 `store.requeueOutbox`. 交付目标必须通过 `item.id` ——一接一送,是指重试可以送出两次.

已建成的商店也提供可选的栅栏索赔方法(`claimOutboxLeased`, (中文(简体) ), `renewOutboxLease`,以及 `settleOutboxLease`) (中文(简体) ). 它们将续约和定居与业主联系在一起,并且单调增加一代人,因此,租期已过或重新排队的工人不能承认以后提出的索偿要求. `OutboxDispatcher` 可用时使用这些方法,心跳活性地交付,失去主张后中止工作. 内容 `concurrency` 选项默认为1;1以上值需要栅栏租赁支持。 年长的适配器通过现有方法保持相容性,但不提供Stale-Worker保护;只用一个过程运行他们的调度器. 见 [租赁合同](https://npmcn.com/package/docs/contracts/fenced-outbox-leases.md) 时间和交货限制.

## 存储执行者的合规包

执行存储意味着正确执行; 在测试套件中不改变运行套件:

```ts
import { storeConformance } from "@godspeedai/cognate-events/conformance";

storeConformance("my-store", myStoreFactory, { persistent: true, fencedOutbox: true });
```

过 `persistent: false` (c) 对长期储存的商店进行额外测试,以保持每一项承诺的决定贯穿其中。 参考执行情况: [`@godspeedai/cognate-store-memory`](https://www.npmjs.com/package/@godspeedai/cognate-store-memory) 财务报告和审定财务报表 [`@godspeedai/cognate-store-sqlite`](https://www.npmjs.com/package/@godspeedai/cognate-store-sqlite)。 。 。 .

## 限制

-   这里没有存储: `DurableStore` 接口是产品。 选择一个执行或写一个.
-   事件有效载荷被封装在一米B;更大的含量属于一个blob.
-   顺序由序列号和位置来定义,从来不用时间戳来定义.

## 相关软件包

-   [`@godspeedai/cognate-store-sqlite`](https://www.npmjs.com/package/@godspeedai/cognate-store-sqlite) ——持久地SQLite执行本合同.
-   [`@godspeedai/cognate-store-memory`](https://www.npmjs.com/package/@godspeedai/cognate-store-memory) 测试和电流运行时间的模拟执行.
-   [`@godspeedai/cognate-projections`](https://www.npmjs.com/package/@godspeedai/cognate-projections) ——通过本套件所定义的日志检查衍生出.
-   [`@godspeedai/cognate-runtime-bun`](https://www.npmjs.com/package/@godspeedai/cognate-runtime-bun) ——通过本合同使用商店的参考运行时间.
-   [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) SDK伞.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @godspeedai/cognate-events 是什么？

活动信封,耐用商店端口, 和商店的配套套件\.

### 如何安装 @godspeedai/cognate-events？

在项目目录运行 npm install @godspeedai/cognate-events，或使用 pnpm add / yarn add / bun add。

### @godspeedai/cognate-events 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/godspeedai\_\_cognate-events 是否存在。

### @godspeedai/cognate-events 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @godspeedai/cognate-events 可以商用吗？

@godspeedai/cognate-events 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @godspeedai/cognate-events 的下载量有多少？

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

### @godspeedai/cognate-events 还在维护吗？

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

