@joekiller/ws-manager v1.1.0
Joe's WebSocket Manager
A simple interface to connect to a websocket and receive an event when messages are pending.
The manager works by emitting a 'messages' event as soon as messages are
within its queue. Read the messages by calling .getMessages() repeatedly
until no more messages are in the queue. The 'messages' event will be
emitted again when the queue was empty and more messages have arrived.
Please remember: The 'messages' event will only fire the first time a message
is available on the queue and will not emit again until .getMessages() has
been called and there are no more messages to consume. You should always call
.getMessages() until you get zero messages back. Once no messages are queued
you can rely on the emission of the 'messages' event to trigger when more
messages have arrived.
The manager is uses the NodeJS ws WebSockets Library.
Installing
npm install @joekiller/ws-managerUsage
The manager will emit a 'messages' event whenever the queue was exhausted
and more messages are available. manager.on('messages', fn)
Events
The following events are emitted from the manager.
type ManagerEvents = {
messages: () => void;
close: (code: number, reason: Buffer) => void;
error: (err: Error) => void; // just log this or errors will trip you up
opened: () => void;
};Example
import WSManager from '@joekiller/ws-manager';
const webSocketManager = new WSManager<unknown>('wss://ws.backpack.tf/events');
function run() {
let running = true
webSocketManager.on('error', (err: ErrorEvent) => console.log(err.error, err.message, err.type));
webSocketManager.on('messages', () => {
const messages = webSocketManager.getMessages();
if(messages.length > 0 && running) {
running = false;
const message = messages.shift();
console.log(JSON.stringify(message, null, 2));
webSocketManager.shutdown();
}
});
// connect after setting up to receive messages
webSocketManager.connect();
}
run();Notes and Features
- The manager will automatically reconnect to websockets with some backoff if it keeps failing to connect.
- The manager utilizes the WebSocket standard of Pings to detect if the line has gone silent without a disconnect.
- The manager allows minimal to zero polling as the consumer is always notified as soon as more messages have arrived.
- The manager caches all pending messages in memory for eventual consumption. With a fast enough processor, memory consumption is not a problem. However, be aware that this mechanism could cause heavy memory consumption if the consumer cannot keep up with the stream.
- I have run this engine with some other projects consuming over 66 million messages in a row with no memory leaks or issues. It seems pretty solid.
About Me
I made this in my spare time and I hope you find it useful. Look me up on any of the following social networks:
Please understand I will not offer any support outside GitHub issues and I make no promises to attend to those either. Happy coding!