ultra-ws

Ultra-fast WebSocket client built for Discord gateway workloads. Raw TLS, hand-rolled frame codec, incremental zero-copy parser, native payload filtering, zlib-stream transport compression, built-in ETF codec — zero dependencies.

Drop-in replacement for the ws client API surface used by latency-critical code (vanity snipers, gateway consumers). Benchmarked against ws 8.21.3 (bench.js, best-of-3 loopback): ~1.1x RTT, ~1.2x throughput, with the real win coming from the native hot path (below) that ws cannot offer at all.

Why it is fast

• Native filter (filter option): frames whose payload does not contain the needle are dropped inside Buffer.indexOf (C++ / SIMD) before any JS callback, string conversion, or object allocation. On the Discord gateway this drops ~99% of traffic (presence spam, typing, message events) without touching the JS event loop.
• Raw mode (raw: true): matching frames are delivered as Buffer with no utf8 conversion — scan with buf.indexOf(...) directly.
• Zero-copy receive: a frame that fits in one TCP chunk is dispatched as a Buffer.slice view — no concat, no copy.
• Single-allocation sends with word-wise (4-byte) masking instead of per-byte.
• Property-callback dispatch (onmessage = fn) — no EventEmitter, no listener arrays on the hot path. addEventListener exists for compatibility.
• TLS 1.3 only, TCP_NODELAY, keepAlive 5s, no permessage-deflate negotiation.

Layout

ultra-ws/
  index.js            package entry (CommonJS, license header)
  index.mjs           ESM entry
  index.d.ts          TypeScript types
  src/
    index.js          exports
    websocket.js      client core
    frame.js          frame codec (build/scan, word-wise masking)
    compress.js       zlib-stream (shared-dictionary inflate)
    etf.js            ETF encoder/decoder
    discord.js        gateway URL / identify / heartbeat helpers
    event-target.js   addEventListener support

Usage

Sniper hot path (maximum speed)

const UltraWS = require('ultra-ws');

const ws = new UltraWS(UltraWS.discord.gatewayUrl(), {
  origin: 'https://discord.com',
  handshakeTimeout: 500,
  raw: true,                        // deliver Buffers, skip utf8 decode
  filter: 'vanity_url_code',        // drop everything else in native code
});

const NEEDLE_NULL = Buffer.from('"vanity_url_code":null');

ws.onopen = () => ws.send(UltraWS.discord.identify(token));
ws.onmessage = (ev) => {
  const buf = ev.data;              // Buffer, zero-copy
  if (buf.indexOf(NEEDLE_NULL) !== -1) firePatch();
};

Standard JSON

const ws = new UltraWS('wss://gateway.discord.gg/?v=9&encoding=json', {
  headers: { 'x-super-properties': '...' },
});
ws.onmessage = (ev) => console.log(ev.data);   // string

ETF mode

const ws = new UltraWS(UltraWS.discord.gatewayUrl({ encoding: 'etf' }), { etf: true });
ws.onopen = () => ws.send({ op: 2, d: { token, intents: 1 } });   // auto ETF-encoded
ws.onmessage = (ev) => {
  const p = ev.data;                // decoded object: { op, d, s, t }
  if (p.t === 'GUILD_UPDATE') { /* ... */ }
};

zlib-stream transport compression

const ws = new UltraWS(UltraWS.discord.gatewayUrl({ compress: 'zlib-stream' }));
// Shared-dictionary inflate is handled internally; onmessage receives
// decompressed payloads (string in json mode, object in etf mode).

API

• new UltraWS(url, opts) — token, headers, origin, userAgent, handshakeTimeout (default 10s, 0=off), rejectUnauthorized (default false), binary, raw, filter, compress: 'zlib-stream', etf, maxPayload (default 256MB)
• ws.send(string | Buffer | object[, cb]) — throws when not open (like ws); plain objects are ETF-encoded when etf: true
• ws.ping([data]) / ws.pong([data]) / ws.close([code[, reason]]) / ws.terminate()
• ws.readyState, ws.bufferedAmount, ws.handshakeMs, ws.stats()
• UltraWS.etf.encode(value) / UltraWS.etf.decode(buf)
• UltraWS.discord.gatewayUrl(opts) / .identify(token, opts) / .heartbeat(seq)

License

MIT — see LICENSE.