@godspeedai/cognate-events

中文文档
0.10.0发布于 2026/11/16Apache-2.0ES Module构建来源已验证近 30 天下载 6438

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

中文使用文档
文档目录9 节
  1. 安装
  2. 那个信封
  3. 快开始
  4. 什麽 DurableStore 覆盖
  5. 提供外包服务
  6. 存储执行者的合规包
  7. 限制
  8. 相关软件包
  9. 许可证

@ godspideai/ cognate- events

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

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

安装

bun add @godspeedai/cognate-events

要求数 阿宝 >= 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——除了不同的请求外,用何来表示回放.

快开始

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 这里的记忆之一:

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 声称有犯罪意图,并至少交付一次,有限度的指数反射:

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保护;只用一个过程运行他们的调度器. 见 租赁合同 时间和交货限制.

存储执行者的合规包

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

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

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

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

限制

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

许可证

阿帕奇 - 2.0

版本与发布记录

@godspeedai/cognate-events 共发布 20 个版本,首次发布于 2026/10/09;过去 12 个月发布了 20 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.22026/11/152 天前
0.9.12026/11/143 天前
0.9.02026/11/0610 天前
0.8.02026/10/2720 天前
0.7.12026/10/2523 天前

关于 @godspeedai/cognate-events 的常见问题

@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 和提交记录判断。