# @alpamayo-solutions/colca-client 中文文档

规范地址：https://npmcn.com/package/%40alpamayo-solutions/colca-client/

版本：0\.44\.1
npm 元数据更新时间：2026-11-05T13:48:06.133Z
中文译文更新时间：2026-11-06T07:25:37.825Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40alpamayo-solutions/colca-client
原文对照：https://npmcn.com/package/%40alpamayo-solutions/colca-client/?lang=original
项目主页：https://alpamayo-solutions.github.io/colca/
源码仓库：https://github.com/alpamayo-solutions/colca

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

- 包体积（解压后）：216 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：0 个
- peer 依赖：mqtt ^5\.0\.0
- 首次发布：2026-09-17T06:15:27.492Z
- 最新版本发布：2026-11-05T13:48:05.800Z
- 近 30 天下载量：4186（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：90（近 12 个月 90 个）

## 中文简介

一个Colca节点的门的客户端:取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.

## 安装

```sh
npm install @alpamayo-solutions/colca-client
```

也可以使用：`pnpm add @alpamayo-solutions/colca-client`、`yarn add @alpamayo-solutions/colca-client`、`bun add @alpamayo-solutions/colca-client`

## README

# @alpamayo-溶液/colca-客户端

一个Colca节点的门,在TypeScript中:记录在HTTP上—— `fetch`, (中文(简体) ), `ack`, (中文(简体) ), `publish`, (中文(简体) ), `kv`, (中文(简体) ), `self` ——活值超过MQTT. 没有运行时间依赖关系 对于门,没有框架, 没有意见如何构建你的服务.

```sh
npm install @alpamayo-solutions/colca-client
```

## 消费者

```ts
import { Door, Doorbell, Stream } from "@alpamayo-solutions/colca-client";

const door = new Door({ baseUrl: "http://colca", service: "my-app" });
const panels = new Stream(door, "annotations", door.cursorName("panels"), {
  prefix: "wisewoods/line1",
});

// Ring the bell whenever the stream may have grown: an MQTT message on the
// topics this stream reads, a /watch hint, a reconnect.
const bell = new Doorbell();
for await (const record of panels.follow({ bell })) {
  // Acked page by page: a handler that throws sees its page again.
  console.log(record.topic, record.payload);
}
```

`follow()` 当铃声响起时 `idleDrainMs` (默认5分钟),所以丢失的戒指不会拖延 消费者为好。 这是一次复苏,不是一次投票:留着它 长. `idleDrainMs: null` 独等一戒.

## 一个制片人

```ts
await door.publishTo(
  { root: "steine", contract: "_Metric", node: "n-technikum", path: "wisewoods/line1/mas2/grit" },
  { signal_id: "01M2AB…", timestamp: Date.now() / 1000, value: 60 },
);
```

## 浏览树

```ts
// One level below "wisewoods/": its records, plus the paths that expand.
const { entries, folders } = await door.kvLevel("wisewoods/");
// The same scan without folders, narrowed to one contract.
const signals = await door.kv("wisewoods/line1/", { depth: 2, contract: "_Signal" });
```

## 活值

`@alpamayo-solutions/colca-client/live` 保持一个与节点的 MQTT 连接 WebSocket门供人和应用程序使用,在它们改变时伸出价值.

```sh
npm install mqtt
```

```ts
import { Live } from "@alpamayo-solutions/colca-client/live";

const live = new Live({
  url: "wss://node:8885",
  // Asked before every connection, so hand back a token that is valid now.
  token: () => auth.freshToken(),
});

const stop = live.subscribe("steine/v1/_Metric/n-technikum/wisewoods/#", (value) => {
  show(value.topic, value.payload);
});
live.onState((state) => showOffline(state !== "online"));
```

在节点保留数据和实体路径,所以订阅开始于 当前值并随变化而继续。 例外是节点 儿童:没有保留 `_Metric` 记录其儿童复制 (单位:千美元)`bus.retain_child_metrics`),所以一个儿童指标的视图读取了当前 来自 `/kv` 首先从订阅中取出更改。 周围 客户端做一个全天开放的页面需要做的事:

-   **整个页面的一个连接 .** `subscribe` 返回函数 结束订阅而不是其他;节点的订阅在 过滤器上最后的监听器.
-   **第二订阅者立即获得该值.** 客户端保留最后一个值 每一主题,以及 `latest()` 财务报告和审定财务报表 `values()` 读取.
-   **旧的还没用完前再换个新标志.** 节点当其 符号过期 。 之前不久,客户在节点上 递出一个新的符号 打开连接( MQTT 5 重新认证), 因此没有再次订阅 。 A 类 不提供与新符号连接的节点 每一个订阅再次发送。 不管怎样,客户都留下 `online`。 。 。 .
-   **等待在滴水后成长**每一次尝试都用一副新标志.
-   **订阅再次出道时说一句.** `onResubscribe()` 一次开火 在每一个新的连接上, 节点保留了的交货开始 结束,如果一个视图调和了保留的一组.

这些是价值,不是日志。 重新连接期间的更改被 保留随附的价值。 无论看到什么 记录读出一行 通过门.

### 图标

一个人的会话发送命令,而不是值. `command()` 派一个来等 执行者 `_Ack`数字 :

```ts
const ack = await live.command("steine/v1/_CmdParam/n-technikum/wisewoods/line1/mas2/sta1/aggos/setGrit", {
  params: { signal: "grit", value: 120 },
});
if (ack.result_code !== 200) showRefusal(ack.message);
```

它加入了关联 id 和过期, 订阅确认 在它发出之前, 所以一个执行者 一次回答不被错过 以它的身份回答,无论它到达树上。 承诺已经达成 页:1 `_Ack` 无论结果代码如何 都拒绝 `CommandTimeout` 何时 没有人及时回答(默认为30 s,这也是命令的过期). 下行,没有队列:延迟几分钟发送的设置点不同 设置点.

`publish()` 不等待就发出一份记录 `newUlid()` 创建 id 就像节点自己做的.

### 常备警报

`_AlarmState` 保留,每个警报记录一份,空有效载荷当 警报响起。 因此,节点所持的就是站立的:无物可取 首先,没有历史可以折叠,没有 `normal` 记录读取过去.

```ts
import { Alarms } from "@alpamayo-solutions/colca-client/live";

const alarms = new Alarms({ live, node: "n-technikum", root: "steine" });

const stop = alarms.onChange((standing) => showBanner(standing), { minSeverity: "warning" });

// Throws when the node refuses it, and when nobody answers.
await alarms.acknowledge("wisewoods/line1/mas2/gritLow", { note: "Korn getauscht" });
```

`standing()` 随时阅读该集——最坏的先读,最古老的先读 在一个严重. `onChange()` 被告诉了现在和现在 更改,并返回结束该表而不是其他表的函数。 警报 名称来自 `_SystemElement` 它挂起,它的路径是 在那里一个视图 跳起来.

当连接恢复时——在下降之后,在符号更新之后 必须重新连接——节点开始保留交货,警报响起 当客户不在时 却没留下什么好说的. `Alarms` 因此 给这套750毫秒的重机`resyncMs`并放弃未到之处 背面:一个视图可能是在节点后面的那么多,但它从来没有继续显示一个 警报结束了 这是一个窗口,一个猜测, 因为节点没有说 (一) 其留存交付终止; `resyncMs: 0` 关闭调节.

`acknowledge()` 发送一个 `_CmdAcknowledge`,以及 `silence(path, { minutes: 30 })` 财务报告和审定财务报表 `unsilence()` 发送 `_CmdOperate`,每个在警报器自己的路径上,每个 等待着它 `_Ack`因此,发出警报需要 `acknowledge` 赠款, 静音 `operate` 补助金(参见 [警卫](https://alpamayo-solutions.github.io/colca/security/)) (中文(简体) ). 这个 有效载荷中的最后载荷 `command` 标的,合同中 保留动词的论点。 客户端没有发送身份: 退出提醒是 节点在记录上的话,而来电者会再加注. 拒绝——300多) `AlarmRefused` 而不是解决问题,因为被吞噬的承认更糟糕 而不是从未送过的信.

## 哪个门,什么证书

| 门 | 網址 | 证书 |
| --- | --- | --- |
| 当地 | `http://colca` (80号口,部署网络内) | 无——可达性是证书; `service` 给呼叫者起名 |
| 已出版 | `https://node:443` | 某人的无记名证或机器的贴有标签的客户证书 |

客户端证书是 TLS 事项, 因此它属于运行时间而非 转到此软件包: `fetch` 携带它`options.fetch`) (中文(简体) ).

## 节点坚持的东西

-   **诅咒属于他们的召唤者.** 他们的名字 `c/{service}/…`,这是 什麽 `door.cursorName()` 构建; 节点拒绝其他名称 .
-   **获取从不移动光标 .** 仅 `ack` 是的,只有前进. `tail` 读取一个溪的尽头而不碰它,这就是一个视图想要的.
-   **空白不是错误.** 当记录被浏览到光标下方时,页 这么说的. `Stream` 传到 `onGap` 并按住它,故有人报告它 一次而不是永远.
-   **节点决定所见.** `/fetch` 财务报告和审定财务报表 `/kv` 由呼叫者过滤 读取补助金; 根据其地区和补助金判断出版物。 403个载具 节点的原因.

## 日记

`deriveAnnotationId()` 计算一个注释的id 节点自己的方式 一揽子合同确实如此。 由它产生,而不是被绘制来创建,更新 并删除一个注释是同一id下的附件——一个制片人 运行两次覆盖自己的记录而不是翻倍.

对协议进行核对 `clients/spec/vectors.json`从 `colca-data-contracts`如果规则在那里发生变化,这里的测试会失败.

## 发展

```sh
npm install
npm run lint
npm run typecheck
npm test
npm run build
```

电线格式本身有记载 [HTTP API 密码](https://alpamayo-solutions.github.io/colca/http-api/)。 。 。 .

## 常见问题

### @alpamayo-solutions/colca-client 是什么？

一个Colca节点的门的客户端:取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取\.

### 如何安装 @alpamayo-solutions/colca-client？

在项目目录运行 npm install @alpamayo-solutions/colca-client，或使用 pnpm add / yarn add / bun add。

### @alpamayo-solutions/colca-client 支持 TypeScript 吗？

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

### @alpamayo-solutions/colca-client 支持 ESM 还是 CommonJS？

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

### @alpamayo-solutions/colca-client 需要什么版本的 Node\.js？

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

### @alpamayo-solutions/colca-client 可以商用吗？

@alpamayo-solutions/colca-client 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @alpamayo-solutions/colca-client 的下载量有多少？

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

### @alpamayo-solutions/colca-client 还在维护吗？

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