萨鲁斯

一个 WebSocket JavaScript 库.

特征

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

安装

npm i @anephenix/sarus

使用量

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

import Sarus from '@anephenix/sarus';

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

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

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

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

// 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],
    },
});

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


// 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],
    },
});

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

/*
    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 服务器发送消息 :

sarus.send('Hello world');

自动重新连接 WebSocket

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

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

萨罗斯会自动帮你的.

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

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

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

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

断开 WebSocket 连接

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

sarus.disconnect();

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

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

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

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

sarus.disconnect(true);

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

延迟 WebSocket 重新连接尝试

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

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

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 实例时, 或在它存在后 :

// 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的例子,像这样:

/*
    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 上的函数 :

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

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

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

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

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

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

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

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

信件队列保存在内存中。如果网页被刷新,那么队列中的消息将会丢失。如果你想坚持在在网页刷新之间排队, 您可以通过一个选项让 Sarus 拥有使用会话堆放协议数字 :

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

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

如果你想在网页会话之外继续存储这些信件, 然后,你可以使用这个本地服务器协议作为存储机制:

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 函数在尝试/捕获语句中调用,以便处理那些信息,如果它们发生.

标志性反转

配置像这样的指数后退 :

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,
    },
});

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

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

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

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

// 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;
}

高级选项

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

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有限公司根据麻省理工学院许可证颁发许可证.

版本	发布日期	距今
`0.7.18`latest	2026/09/27	1 个月前
`0.7.16`	2026/03/29	7 个月前
`0.7.15`	2026/03/22	7 个月前
`0.7.14`	2026/01/05	10 个月前
`0.7.13`	2025/12/04	11 个月前
`0.7.12`	2025/10/13	1.1 年前

@anephenix/sarus

萨鲁斯

特征

安装

使用量

自动重新连接 WebSocket

断开 WebSocket 连接

延迟 WebSocket 重新连接尝试

附加并删除事件听众

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

标志性反转

高级选项

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

开发本地测试和运行测试

许可证和信用

版本与发布记录

关于 @anephenix/sarus 的常见问题

@anephenix/sarus 是什么？

如何安装 @anephenix/sarus？

@anephenix/sarus 支持 TypeScript 吗？

@anephenix/sarus 支持 ESM 还是 CommonJS？

@anephenix/sarus 可以商用吗？

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

@anephenix/sarus 还在维护吗？