push-stream-std
Repositories
2
 Projects Packages

@push-stream-std/push-websocket (0.0.7)

Published 2026-07-20 21:39:53 +00:00 by Dvorak

Installation

@push-stream-std:registry=https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/
npm install @push-stream-std/push-websocket@0.0.7
"@push-stream-std/push-websocket": "0.0.7"

About this package

@push-stream-std/push-websocket

Push-stream based WebSocket client with native bindings, RFC 6455 compliant, with permessage-deflate support.

Published as @push-stream-std/push-websocket.

Synopsis

import { createWebSocket } from '@push-stream-std/push-websocket';

const ws = createWebSocket('wss://echo.websocket.org', {
  pingInterval: 30000,
  timeout: 10000
});

const sink = {
  paused: false,
  write(v) { console.log('received:', v); },
  end(err) { if (err) console.error('error:', err); else console.log('closed'); }
};

ws.pipe(sink);
ws.send('hello');
ws.close();

Install

npm config set @push-stream-std:registry https://hub.kl1.tenere.ai/api/packages/push-stream-std/npm/
npm config set -- //hub.kl1.tenere.ai/api/packages/push-stream-std/npm/:_authToken "$PACKAGE_TOKEN"
npm install @push-stream-std/push-websocket

Why

A complete WebSocket client implemented as a push-stream duplex. Establishes RFC 6455 WebSocket connections over TCP or TLS, performs the opening handshake, and exposes source (incoming messages) and sink (outgoing messages) as push-stream interfaces. Includes native-binding accelerated masking via bufferutil, UTF-8 validation via utf-8-validate, and optional permessage-deflate compression. Frame construction and parsing are exposed as standalone utilities for implementing custom transports.

API

createWebSocket(url, options)

Creates a WebSocket duplex stream.

  • url string – WebSocket URL (ws:// or wss://).
  • options object (optional):
    • headers object (default {}) – Additional HTTP headers for the handshake.
    • protocol string (optional) – Sec-WebSocket-Protocol value.
    • timeout number (default 30000) – Connection timeout in milliseconds.
    • pingInterval number (default 30000) – Interval between automatic ping frames.
    • perMessageDeflate boolean (default true) – Enable permessage-deflate compression.
    • rejectUnauthorized boolean (default true) – TLS certificate validation.
    • onOpen (ws) => void (optional) – Called when the connection opens.
    • onClose (code, reason) => void (optional) – Called when the connection closes.
    • onError (err) => void (optional) – Called on connection errors.
  • Returns A duplex object with pipe(sink), send(data), close(code, reason), ping(payload), resume(), abort(err), paused, ended, source, sink, and state.

request(url, message, options, callback)

One-shot request/response over WebSocket.

  • url string – WebSocket URL.
  • message any – Data to send after connecting.
  • options object (optional) – Same as createWebSocket options.
  • callback (err, response) – Called with the response or error.

requestAsync(url, message, options)

Promise-based one-shot request/response.

  • Returns Promise<any> resolving to the response data.

Frame Utilities

createFrame(opcode, payload, fin = true, compress = false)

Build a raw WebSocket frame Buffer.

createCloseFrame(code, reason = '')

Build a close frame Buffer.

createPingFrame(payload = '')

Build a ping frame Buffer.

createPongFrame(payload = '')

Build a pong frame Buffer.

createFrameParser(options)

Create a frame parser object with parse(data) method. Returns an array of parsed messages ({ type, data, ... }). Supports permessageDeflate option for decompression.

  • options object:
    • permessageDeflate boolean (default false) – Enable decompression for received frames.

Constants

OPCODE

WebSocket opcodes: CONTINUATION (0x0), TEXT (0x1), BINARY (0x2), CLOSE (0x8), PING (0x9), PONG (0xA).

CLOSE_CODE

Standard close codes: NORMAL (1000), GOING_AWAY (1001), PROTOCOL_ERROR (1002), UNSUPPORTED_DATA (1003), NO_STATUS (1005), ABNORMAL (1006), INVALID_PAYLOAD (1007), POLICY_VIOLATION (1008), MESSAGE_TOO_BIG (1009), EXTENSION_REQUIRED (1010), INTERNAL_ERROR (1011).

STATE

Connection states: CONNECTING (0), OPEN (1), CLOSING (2), CLOSED (3).

Tests

npm test

Tests cover connection handshake, message send/receive, ping/pong, close handshake, TLS connections, frame construction/parsing, and permessage-deflate compression.

Requirements

Node.js 22 or later. ESM only. Requires bufferutil and utf-8-validate native addons.

Dependencies

Dependencies

ID Version
bufferutil ^4.0.9
utf-8-validate ^6.0.5

Development Dependencies

ID Version
ws ^8.19.0

Keywords

websocket push-stream streaming native
Details
npm
2026-07-20 21:39:53 +00:00
0
SEE LICENSE IN LICENSE
9.3 KiB
Assets (1)
push-websocket-0.0.7.tgz 9.3 KiB
Versions (6) View all
0.0.9 2026-07-21
0.0.8 2026-07-20
0.0.7 2026-07-20
0.0.6 2026-07-20
0.0.5 2026-07-19