# @anephenix/sarus 中文文档

规范地址：https://npmcn.com/package/%40anephenix/sarus/

版本：0\.7\.18
npm 元数据更新时间：2026-09-27T09:07:39.932Z
中文译文更新时间：2026-11-06T23:48:29.566Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：98.6 kB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-03-03T14:38:11.552Z
- 最新版本发布：2026-09-27T09:07:39.468Z
- 近 30 天下载量：2154（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 5 个）

## 中文简介

一个 WebSocket JavaScript 库

## 安装

```sh
npm install @anephenix/sarus
```

也可以使用：`pnpm add @anephenix/sarus`、`yarn add @anephenix/sarus`、`bun add @anephenix/sarus`

## README

# 萨鲁斯

一个 WebSocket JavaScript 库.

[![npm version](https://badge.fury.io/js/%40anephenix%2Fsarus.svg)](https://badge.fury.io/js/%40anephenix%2Fsarus) ![example workflow](https://github.com/anephenix/sarus/actions/workflows/node.js.yml/badge.svg) [![Socket Badge](https://socket.dev/api/badge/npm/package/@anephenix/sarus)](https://socket.dev/npm/package/@anephenix/sarus)

### 特征

-   断开时自动重新连接 WebSocket 连接
-   处理重新绑定事件
-   使用信件队列通过 WebSocket 连接发送信件,这意味着:
    -   如果 WebSocket 连接未打开, 信件不会丢失
    -   如果WebSocket 连接未打开, 信件发送会得到重试
    -   信件可以在浏览器存储中被坚持,这样即使在网页刷新后也能保留.

### 安装

```
npm i @anephenix/sarus
```

### 使用量

在安装 Sarus 后, 您可以使用您的前端客户端库 代码库 :

```javascript
import Sarus from '@anephenix/sarus';

const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
});
```

萨罗斯创建了与url的WebSocket连接. 然后可以附加事件 收听者通过 WebSocket 客户端的功能 `sarus` 用于下列事件:

-   当套接字收到消息时
-   当套接字出错时
-   当套接字关闭时
-   打开新套接字时

以下是附带客户端初始化事件的例子:

```javascript
// Log a message that the connection is open
const noteOpened = () => console.log('Connection opened');

// Assuming that the WebSocket server is sending JSON data,
// you can use this to parse the data payload;
const parseMessage = (event) => {
    const message = JSON.parse(event.data);
    // Then do what you like with the message
};

// Log a message that the connection has closed
const noteClosed = () => console.log('Connection closed');

// If an error occurs, throw the error
const throwError = (error) => throw error;

// Create the Sarus instance with the event listeners
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    eventListeners: {
        open: [noteOpened],
        message: [parseMessage],
        close: [noteClosed],
        error: [throwError],
    },
});
```

您可以在初始化时指定全部事件听众, 或者只指定其中之一 :

```javascript

// Assuming that the WebSocket server is sending JSON data,
// you can use this to parse the data payload;
const parseMessage = (event) => {
    const message = JSON.parse(event.data);
    // Then do what you like with the message
};


// Create the Sarus instance with the event listeners
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    eventListeners: {
        message: [parseMessage],
    },
});
```

您也可以在客户端初始化后添加事件倾听器 :

```javascript
/*
    A function that stores messages in the browser's LocalStorage, possibly 
    for debugging, or for event stream processing on the client side.
*/
const storeMessage = (event) => {
    const store = window.localStorage;
    let record = store.getItem('messages');
    if (!record) {
        record = [];
    } else {
        record = JSON.parse(record);
    }
    record.push(event.data);
    store.setItem('messages', JSON.stringify(record));
};

// Attach the storeMessage function to Sarus when it receives a message from
// the WebSocket server
sarus.on('message', storeMessage);
```

您也可以使用它向 WebSocket 服务器发送消息 :

```javascript
sarus.send('Hello world');
```

#### 自动重新连接 WebSocket

WebSockets可以意外地关闭. 当一个 WebSocket 实例被关闭时, 它 无法重开 。 要重建 WebSocket 连接, 您必须创建 新设 `WebSocket` 以实例取代已结案的案例.

通常您会通过写一些 JavaScript 来处理此事宜, 以包装 WebSocket 界面,并在关闭事件时启动新的 WebSocket 连接 正在发生.

萨罗斯会自动帮你的.

它这样做的方式是: `connect` 函数 `close` 正在发生的事件 编辑 `WebSocket` 举个例子 如果 `WebSocket` 实例关闭 `connect` 函数将简单地创建一个新的 `WebSocket` 实例 参数已传递到前一实例.

这个 `connect` 函数在默认情况下立即调用,并将重复 这直到它得到一个 `WebSocket` 实例,其连接是打开的.

如果您不希望 WebSocket 自动重新连接, 您可以通过 `reconnectAutomatically` 参数输入 sarus 客户端 初始化客户端, 如下面的例子 .

```javascript
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    reconnectAutomatically: false,
});
```

#### 断开 WebSocket 连接

可能存在您希望关闭 WebSocket 连接的情况( 例如: . . . . 萨罗斯为此提供了一种方法:

```javascript
sarus.disconnect();
```

在 sarus 客户端上调用此功能将做两件事:

1.  设定 `reconnectAutomatically` 旗为假.
2.  关闭 WebSocket 连接 .

在WebSocket的近距离活动上听节目的听众仍然会触发, 但客户端不会试图自动重接.

如果您想要关闭 WebSocket, 但不能覆盖 `reconnectAutomatically` 旗帜,通过此选项:

```javascript
sarus.disconnect(true);
```

客户端将尝试自动重新连接.

#### 延迟 WebSocket 重新连接尝试

当连接被断开, Sarus 客户端试图重新连接时 自动的,它会延迟1000ms(1秒).

如果你通过一个数字,那么它会推迟重新连接的尝试 (单位:毫秒):

```javascript
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    retryConnectionDelay: 500, // equivalent to 500ms or 1/2 second
});
```

页:1

过去,这一选择需要明确通过,但我们决定 更改为默认启用。 没有它,任何断开都会导致 数以千计的客户端试图重新连接 秒数.

#### 附加并删除事件听众

当一个 WebSocket 连接关闭时, 任何附加于已发送的事件的功能 由 WebSocket 实例需要附加到新的 WebSocket 实例中. 这意味着你最终会写一些处理附加事件的JavaScript 新建 WebSocket 实例时的收听器功能 已关闭实例.

萨罗斯这样做是为了你。 您在您的 WebSocket 有两种功能附加 事件倾听器 - 在创建 Sarus 实例时, 或在它存在后 :

```javascript
// Log a message that the connection is open
const noteOpened = () => console.log('Connection opened');

// Assuming that the WebSocket server is sending JSON data,
// you can use this to parse the data payload;
const parseMessage = (event) => {
    const message = JSON.parse(event.data);
    // Then do what you like with the message
};

// Log a message that the connection has closed
const noteClosed = () => console.log('Connection closed');

// If an error occurs, throw the error
const throwError = (error) => throw error;

// Create the Sarus instance with the event listeners
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    eventListeners: {
        open: [noteOpened],
        message: [parseMessage],
        close: [notedClosed],
        error: [throwError],
    },
});
```

在这个例子中,这些功能将约束在WebSocket实例中. 若为 webSocket 实例的连接关闭, 一个新的 WebSocket 实例是 由 Sarus 创建,可自动重接. 在萨鲁斯举办的活动听众 将自动附在新的 WebSocket 实例上.

这是萨鲁斯允许你 将事件听众绑在现场的一种方式 WebSocket连接. 另一种方式是叫 `on` 函数 Sarus的例子,像这样:

```javascript
/*
    A function that stores messages in the browser's LocalStorage, possibly 
    for debugging, or for event stream processing on the client side.
*/
const storeMessage = (event) => {
    const store = window.localStorage;
    let record = store.getItem('messages');
    if (!record) {
        record = [];
    } else {
        record = JSON.parse(record);
    }
    record.push(event.data);
    store.setItem('messages', JSON.stringify(record));
};

// Attach the storeMessage function to Sarus when it receives a message from
// the WebSocket server
sarus.on('message', storeMessage);
```

如果您想要从 WebSocket 事件收听器中删除一个函数, 您可以这样做 通过呼叫 `off` 像这样在 Sarus 上的函数 :

```javascript
// Pass the function variable
sarus.off('message', storeMessage);

// You can also pass the name of the function as well
sarus.off('message', 'storeMessage');
```

如果您试图去除未列在列表中的事件倾听器函数 事件听众,然后萨鲁斯会发出错误。 这是故意的 萨罗斯的行为 而不是默默地不删除一个函数,因为 它不在那里(或者也许有误写函数名称),它 将明确投出错误,以便让开发者意识到它 并按他们的意愿处理它.

如果开发者乐于让事件听众删除失败而不成功 扔出一个错误,他们可以传递给 `off` 函数 :

```javascript
sarus.off('message', 'myNonExistentFunction', { doNotThrowError: true });
```

#### 断开 WebSocket 连接时排队发送信件

从 Websocket 客户端向服务器发送消息取决于 正在打开 WebSocket 连接 。 如果连接关闭, 那么您会 需要防止电文发送(阻断电文发送), 或者您需要排队发送信件(排队发送信件). 任一选项都需要写一些 JavaScript 才能做到这一点.

为了处理这个案件,Sarus执行基于客户端的信息队列,以便 信件只在有开放的 WebSocket 连接时才会发送.

信件队列保存在内存中 。 如果网页被刷新,那么 队列中的消息将会丢失。 如果你想坚持在 在网页刷新之间排队, 您可以通过一个选项让 Sarus 拥有 使用 [会话堆放协议](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)数字 :

```javascript
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    storageType: 'session',
});
```

会话Storage协议保证信件存储在 网页刷新,但仅限于该网页浏览器标签或 窗口。 信件不会在新的浏览器标签/窗口中持续, 或在 浏览器已被关闭 .

如果你想在网页会话之外继续存储这些信件, 然后,你可以使用这个 [本地服务器协议](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) 作为存储机制:

```javascript
const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    storageType: 'local',
});
```

本地Storage 保证信件在浏览器之外持续 关闭并重新打开,以及当页面在新标签/窗口中打开时.

**页:1** 当持续发送信息时,要注意信息的安全性 存在于浏览器存储中,而不包含敏感信息。 狦 当用户关闭浏览器时, 想要删除信件, 使用“ 会话 ” 为 存储类型.

**页:1** 每个网页浏览器执行任意限制数据数量 存储于一个域的会话Storage/localStorage。 当达到这个限度时, 网页浏览器将丢出 QUOTA EXEDED ERR 错误 。 限制往往在 5MB- 10MB 范围, 但浏览器之间确实有差异 .

如果你认为你有一个潜在的案子 最终排队至少 在信件中发送到 WebSocket 服务器的数据 5MB, 然后您可能想要 关闭 `sarus.send` 函数在尝试/捕获语句中调用,以便处理 那些信息,如果它们发生.

### 标志性反转

配置像这样的指数后退 :

```typescript
import Sarus from '@anephenix/sarus';

const sarus = new Sarus({
    url: 'wss://ws.anephenix.com',
    exponentialBackoff: {
        // Exponential factor, here 2 will result in
        // 1 s, 2 s, 4 s, and so on increasing delays
        backoffRate: 2,
        // Never wait more than 2000 seconds
        backoffLimit: 2000,
    },
});
```

当连接尝试反复失败时, 减少延迟 在随后的每次重接尝试之间, 都称为指数 [标志性反转](https://en.wikipedia.org/wiki/Exponential_backoff)编辑 想法是如果连接尝试在1秒2秒后失败,那么它就是 不必在第三秒检查,因为概率 在第三次尝试中取得成功的重新连接很可能不会上升. 因此,在假设中增加每个尝试因素之间的延迟 连通不会更可能通过经常的反复调查而成功 间隔.

这既减少了客户端的负载,也减少了服务器上的负载. 对于 一个客户端, 减少 websocket 连接尝试减少客户端的负载 还有网络连接 对于服务器, 如果websocket请求失败 在内部,处理多次失败请求的负载会下降 还有 此外,网络的负担也将得到减轻。 应否 例如,服务器拒绝接受一个客户端的 websocket 连接, 因此,其他客户也有可能无法连接.

Sarus 设备 _截断指数倒置_,表示最大值 重连延迟被另一个因素所限制 `backoffLimit` 永远不会 超过它。 指数后退率本身是由 `backoffRate`。 。 。 . 若为 `backoffRate` 是 2, 那么延迟将是 1 s, 2 s, 4 s等 .

重新连接的算法在伪码中看起来像:

```javascript
// Configurable
const backoffRate = 2;
// The maximum delay will be 400s
const backoffLimit = 400;
let notConnected = false;
let connectionAttempts = 1;
while (notConnected) {
    const delay = Math.min(
        Math.pow(connectionAttempts, backoffRate),
        backoffLimit,
    );
    await delay(delay);
    notConnected = tryToConnect();
    connectionAttempts += 1;
}
```

### 高级选项

萨鲁斯还有其他一些选项,您可以在 初始化。 例子如下:

```javascript
const sarus = new Sarus({
    url: 'wss.anephenix.com',
    protocols: 'hybi-00',
    retryProcessTimePeriod: 25,
    storageKey: 'messageQueue',
});
```

这个 `protocols` 属性用于指定 WebSocket 的子协议 连接应该使用。 你可以通过一个字符串,或者一系列字符串.

这个 `retryProcessTimePeriod` 属性用于帮助缓冲介于 试图通过 WebSocket 连接重发消息 。 默认是 数字,50(50毫秒)。 您可以在客户端中调整此值 举个例子.

这个 `storageKey` 属性是用于会话Storage和 localStorage 以存储和取回信件队列中的信件 。 以 默认它设为 “ sarus ” 。 如果 你希望这样 您也可以独立检查 Sarus 的信息队列 使用此键向会话Storage/ localStorage api发出呼叫.

### 使用您前端代码中的库,有bayl,webpack,rollup等.

库的代码使用ES2015特性来写出,其想法是 开发者可以直接将代码加载到他们的应用程序中,而不是 以转录和精密格式装入作为外部依赖.

这让开发者可以随意使用前端 他们使用的工具,无论是Babel、WebPack、Rollup甚至浏览器.

### 开发本地测试和运行测试

```
npm t
```

这将使用笑柄进行测试,并启用代码覆盖.

### 许可证和信用

2025 Anephenix有限公司根据麻省理工学院许可证颁发许可证.

## 常见问题

### @anephenix/sarus 是什么？

一个 WebSocket JavaScript 库

### 如何安装 @anephenix/sarus？

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

### @anephenix/sarus 支持 TypeScript 吗？

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

### @anephenix/sarus 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @anephenix/sarus 可以商用吗？

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

### @anephenix/sarus 的下载量有多少？

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

### @anephenix/sarus 还在维护吗？

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