# @cratis/chronicle 中文文档

规范地址：https://npmcn.com/package/%40cratis/chronicle/

版本：6\.62\.0
npm 元数据更新时间：2026-11-10T11:54:24.502Z
中文译文更新时间：2026-11-10T23:37:27.912Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cratis/chronicle
原文对照：https://npmcn.com/package/%40cratis/chronicle/?lang=original
项目主页：https://www.cratis.io/chronicle/
源码仓库：https://github.com/Cratis/Chronicle.TypeScript

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

- 包体积（解压后）：7 MB，3519 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：@cratis/fundamentals ^7\.24\.1
- 首次发布：2026-05-11T08:24:22.375Z
- 最新版本发布：2026-11-10T11:54:24.097Z
- 近 30 天下载量：3491（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 103 个）

## 中文简介

TypeScript和Node.js 的事件源代码——克拉蒂斯纪事的平庸客户端,开源事件源数据库

## 安装

```sh
npm install @cratis/chronicle
```

也可以使用：`pnpm add @cratis/chronicle`、`yarn add @cratis/chronicle`、`bun add @cratis/chronicle`

## README

# 纪事类型脚本客户端

**TypeScript 和 Node.js 的事件源代码——用于平庸的客户端 [克拉蒂斯纪事](https://github.com/Cratis/Chronicle)。 。 。 .**

[![npm](https://img.shields.io/npm/v/@cratis/chronicle?label=npm&logo=npm)](https://www.npmjs.com/package/@cratis/chronicle) [![Build](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml/badge.svg)](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE) [![Discord](https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&logoColor=white)](https://discord.gg/kt4AMpV8WV)

Chronical是一个事件包数据库和处理运行时间,拥有一等的.NET SDK和额外的TypeScript,Kotlin/Java(JVM),和Elixir客户端——一个Python客户端即将到来——加上可插接的存储提供器执行,包括MongoDB(默认),PostgreSQL,SQL Server,和SQLite. 这个包是 **类型脚本客户端**。 。 。 .

## 概览

`@cratis/chronicle` 为与"纪事核心"互动提供一个干净,类型安全的TypeScript API. 它建立在顶端 [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) (gRPC合同套件)并曝光了平庸的TypeScript构造,包括:

-   **装饰者** —— 说 `@eventType`, (中文(简体) ), `@eventTypeMigration`, (中文(简体) ), `@reactor`, (中文(简体) ), `@reducer`, (中文(简体) ), `@seeder`, (中文(简体) ), `@constraint`, (中文(简体) ), `@projection`,例如 `@node` 财务报告和审定财务报表 `@edge`,以及诸如 `@fromEvent`
-   **值对象** —— 说 `EventSequenceNumber`, (中文(简体) ), `EventTypeId`, (中文(简体) ), `EventStoreName`等 (中文(简体) ).
-   **流利客户端** —— 说 `ChronicleClient` → `EventStore` → `EventLog` → `append()`

除了附件和观察事件外,客户端还覆盖了完整的"纪事"表面:

-   **交易** ——以单项承诺组合成工作单位
-   **工作** 检查和控制长期内核工作
-   **网络呼号** 将事件推向 HTTP 端点
-   **遵约/PII** ——分类事件数据并处理个人可识别信息
-   **打开几何** 内置计量和追查仪器

## 安装

```bash
npm install @cratis/chronicle @cratis/fundamentals reflect-metadata
```

所需经费:

-   节点.js 22.19或后. 这个 `undici` 依赖性需要它,而软件包未能在Node.js 20上导入.
-   包只载ES模块. 使用来自ES模块项目,或 `require()` 它在一个节点Js版本 `require(esm)` 支助.
-   运行中的纪事内核 。 最简单的本地设置是开发出Docker图像,只发布于此机上:

```bash
docker run -d --name chronicle -p 127.0.0.1:35000:35000 cratis/chronicle:latest-development
```

## 快速示例

```typescript
import 'reflect-metadata';
import { field } from '@cratis/fundamentals';
import { ChronicleClient, ChronicleOptions, eventType } from '@cratis/chronicle';

@eventType()
class EmployeeHired {
    @field(String) firstName!: string;
    @field(String) lastName!: string;

    constructor(firstName: string, lastName: string) {
        this.firstName = firstName;
        this.lastName = lastName;
    }
}

const client = new ChronicleClient(ChronicleOptions.development());
const store = await client.getEventStore('MyStore');
const result = await store.eventLog.append('employee-123', new EmployeeHired('Jane', 'Doe'));
console.log(`Appended at sequence number ${result.sequenceNumber.value}`);
client.dispose();
```

## 装饰和类型脚本配置

纪事装饰者与 TC39 标准装饰者合作( TypeScript 5. 2+; 不启用) `experimentalDecorators`)和遗迹装饰者(`experimentalDecorators: true`) (中文(简体) ). 保留 `reflect-metadata` 在您的切入点中导入了 Crime 运行时间元数据存储 。 在标准模式下, TypeScript 不发射 `design:type` 或者说 `design:paramtypes`; 以 `@field(Type)` 从 `@cratis/fundamentals` 故"纪事"可以产生他们的计划. 对于数组,提供元素类型 `@field(Array, { genericArguments: [ItemType] })`为 a `ConceptAs<string>` 或者说 `ConceptAs<number>`,声明 `static readonly valueType = String`, (中文(简体) ), `Number`, (中文(简体) ), `Boolean`, (中文(简体) ), `Guid`,或 `Date` 在概念课。 无会员事件类型和读取模型有效. 未解的标准模式类型在Kernel注册前的首个读取计划或连接期间会失败;财产装饰器支持公共实例字段,而不是标准存取器或获取器.

从 `@projection('id', Model)`, (中文(简体) ), `@reducer('id', sequenceId, Model)`,或导出型号 `@fromEvent(Event)` 或其他模型化的地产映射。 他们的图案出自模型类型;默认标识符是其类名. 见 [读取模型](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/read-models.md) 用于保存现有自定义标识符.

装有装饰的文物在进口其模块时进行登记. 当条目文件为 TypeScript (通过加载器运行, 如 `tsx`),客户端也扫描 `**/*.ts` 文件默认; 编译的 JavaScript 扫描, 除非设置 `discoveryPatterns`。见 [文物发现](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/getting-started.md#artifact-discovery)。 。 。 .

客户端跳过 TLS 证书验证, 除非连接字符串设置 `skipTlsValidation=false` (默认保留) `true` ; 明确 `false` 需要验证)。 为本地开发内核以外的每个服务器设定它; 当客户端跳过非锁定主机的验证时, 客户端会登录一个警告; 见 [连接到纪事](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/connecting.md)。 。 。 .

## 文档

读取 [类型脚本客户端文档](https://www.cratis.io/chronicle/clients/typescript/),从 [启动 TypeScript 客户端](https://www.cratis.io/chronicle/clients/typescript/getting-started/)编辑 [纪事文档](https://www.cratis.io/chronicle/) 以 TypeScript 为例解释概念.

## 克拉蒂斯生态系统

此软件包是 [克拉蒂斯语Name](https://www.cratis.io/) ——用于构建事件源代码和CQRS应用的免费,MIT许可工具.

-   **[纪事](https://github.com/Cratis/Chronicle)** ——事件外包数据库和运行时间. 基于奥尔良的内核,可插件存储(MongoDB默认;PostgreSQL,SQL服务器,SQLite, in-memory),语言-不可知GRPC合同. [文档](https://www.cratis.io/chronicle/)
-   **纪事客户端** 一等舱 [.NET SDK 软件](https://github.com/Cratis/Chronicle)附加时 [类型脚本](https://github.com/Cratis/Chronicle.TypeScript), (中文(简体) ), [科特林/贾瓦](https://github.com/Cratis/Chronicle.Kotlin),以及 [埃利克斯尔](https://github.com/Cratis/Chronicle.Elixir)· ; [蟒](https://github.com/Cratis/Chronicle.Python) 即将来临, 人工智能代理通过 [纪事 MCP 服务器](https://github.com/Cratis/Chronicle.Mcp)。 。 。 .
-   **[弧形](https://github.com/Cratis/Arc)** - 对ASP.NET的CQRS框架有意见 核心包含命令,查询,验证,授权,以及TypeScript代理生成. 工作没有活动来源. [文档](https://www.cratis.io/arc/)
-   **[构成部分](https://github.com/Cratis/Components)** ——反应组件与Arc图案一致. [文档](https://www.cratis.io/components/)
-   **[国 际](https://github.com/Cratis/cli) + 工作台** ——从终端或浏览器检查和诊断"纪事". [文档](https://www.cratis.io/cli/)
-   **[样本](https://github.com/Cratis/Samples)** 整个堆栈的可运行事件来源和CQRS样本

克拉蒂斯今天出版的每部作品都是麻省理工学院的许可和自由使用.

* * *

_部分 [克拉蒂斯语Name](https://www.cratis.io/) · 获得许可证 [麻省理工学院许可证](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE)_

## 常见问题

### @cratis/chronicle 是什么？

TypeScript和Node\.js 的事件源代码——克拉蒂斯纪事的平庸客户端,开源事件源数据库

### 如何安装 @cratis/chronicle？

在项目目录运行 npm install @cratis/chronicle，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@cratis/fundamentals（^7\.24\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cratis/chronicle 支持 TypeScript 吗？

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

### @cratis/chronicle 支持 ESM 还是 CommonJS？

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

### @cratis/chronicle 可以商用吗？

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

### @cratis/chronicle 的下载量有多少？

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

### @cratis/chronicle 还在维护吗？

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