# @asterql/sync 中文文档

规范地址：https://npmcn.com/package/%40asterql/sync/

版本：0\.5\.0
npm 元数据更新时间：2026-07-08T20:31:54.160Z
中文译文更新时间：2026-11-07T08:06:52.224Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40asterql/sync
原文对照：https://npmcn.com/package/%40asterql/sync/?lang=original
项目主页：https://www.asterql.org/sync
源码仓库：https://github.com/ricokahler/asterql

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

- 包体积（解压后）：26.3 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-06-11T04:26:42.390Z
- 最新版本发布：2026-07-08T20:31:54.027Z
- 近 30 天下载量：1996（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

多功能范围订阅同步客户端:一个连接,服务器事件信封,光标恢复.

## 安装

```sh
npm install @asterql/sync
```

也可以使用：`pnpm add @asterql/sync`、`yarn add @asterql/sync`、`bun add @asterql/sync`

## README

# @ asterql/ sync

AsterQL 状态同步每个会话连接一次: 多重轴, 范围订阅的 WebSocket 客户端 `@asterql/view-protocol` 同步有线词汇,有可穿透的处理器和光标恢复.

## 安装

```sh
npm install @asterql/sync @asterql/view-protocol
```

## 使用量

```ts
import { SyncClient } from "@asterql/sync";
import { EntityStore } from "@asterql/store";

const client = new SyncClient({
  url: "wss://app.example.com/api/sync/socket",
  // browser: defaults to globalThis.WebSocket; Node/TUI: pass `ws`
});

const store = new EntityStore();
store.cursors.beginScope("run:run_1", 0);

const unsubscribe = client.subscribe("run:run_1", {
  onEnvelope: (envelope) => store.ingest(envelope).result.kind,
  since: () => store.cursors.scopeLastSeq("run:run_1"),
  onSnapshotRequired: async () => {
    // fetch a registered view (Protocol A), seed the store, then
    // store.cursors.beginScope("run:run_1", seqFromSnapshot)
  },
});
// later
unsubscribe();
```

## 语义

-   **一个插座,许多瞄准镜,很多商店.** 每个 `subscribe(scope, handler)` 拥有该范围摄入: 一个身份范围可以驱动缓存 无效, 而每个运行范围会输入自己的存储, 遍及一个 连接。 订阅按每个范围计算.
-   **克索尔简历.** `sub.since` 从操作器的 `since()`; 省略 指从现在开始的活(服务器从当前头开始). 重新连接 重新订阅光标中的每个范围, 因此错过信封重放 服务器的分类账.
-   **差距重放.** 处理器返回 `"gap"` 从 `onEnvelope` 触发 a 从其光标重放请求; 异常事件从未应用 .
-   **靴子接头.** `scopeError snapshot_required` (超过 服务器的再播放视野)调用 `onSnapshotRequired()`; 打电话者之后 重新种子,客户端从新光标重新订阅.
-   **众生相.** 心跳乒乓球(两只错过了套接字循环) 和指数重联后退.

## 服务器的期望

主机拥有端口:认证在升级握手, (a) 每一范围的授权,连续封装在可查看分类账中 相接序列号,从 `sub.since`,发出一粒种子 截图,因为每个范围的第一个分类账条目 所以从-0重播是 决断相. 参考服务器住在周五的地盘 (单位:千美元)`packages/server/src/sync-socket.ts`) (中文(简体) ).

## 常见问题

### @asterql/sync 是什么？

多功能范围订阅同步客户端:一个连接,服务器事件信封,光标恢复\.

### 如何安装 @asterql/sync？

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

### @asterql/sync 支持 TypeScript 吗？

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

### @asterql/sync 支持 ESM 还是 CommonJS？

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

### @asterql/sync 需要什么版本的 Node\.js？

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

### @asterql/sync 可以商用吗？

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

### @asterql/sync 的下载量有多少？

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

### @asterql/sync 还在维护吗？

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