ws-low-level

library1.0.2jsnpmunverified

A Promise-based, low-level WebSocket server library for Node.js. Version 1.0.2 provides core functions for handling WebSocket handshakes, sending/receiving messages, and constructing frames per RFC 6455. Unlike high-level wrappers like 'ws', this library gives direct access to raw frames, opcodes, and masking, making it suitable for custom implementations such as rate limiters, custom close messages, or WebSocket extensions. It uses async iterables for message consumption and has a moderate release cadence. Key differentiators: full control over WebSocket protocol details, no abstraction layers, and TypeScript support.

devops

npm install ws-low-level

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WS-LOW-LEVEL

ws-low-level

devopsjavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sendHandshake

✓ import { sendHandshake } from 'ws-low-level'

✗ const sendHandshake = require('ws-low-level').sendHandshake

ESM-only module; CommonJS require requires dynamic import or use .default. Wrong pattern shown.

getMessagesFactory

✓ import { getMessagesFactory } from 'ws-low-level'

✗ import getMessagesFactory from 'ws-low-level'

Named export, not default export. Common mistake is to use default import.

prepareWebsocketFrame

✓ import { prepareWebsocketFrame } from 'ws-low-level'

✗ const prepareWebsocketFrame = require('ws-low-level').prepareWebsocketFrame

ESM-only; requires named import.

Creates a WebSocket server that echoes back text messages, demonstrating handshake, message sending/receiving, and frame construction.

import http from 'http'; import { sendHandshake, getMessagesFactory, sendFactory, prepareWebsocketFrame, prepareCloseFramePayload } from 'ws-low-level'; const httpServer = http.createServer((req, res) => {}); httpServer.on('upgrade', (request, socket, head) => { const send = sendFactory(socket); const getMessages = getMessagesFactory(socket, { maxInMemoryStoreSize: 2147483648 }); sendHandshake(socket, request); (async () => { for await (const { payload, opcode, mask } of getMessages()) { if (opcode === 0x1) { const message = new TextDecoder('utf-8').decode(payload); console.log('Received:', message); send(prepareWebsocketFrame(new TextEncoder().encode('Echo: ' + message), { opcode: 0x1 })); } else if (opcode === 0x8) { console.log('Connection closed'); break; } } })(); }); httpServer.listen(8080, () => console.log('WebSocket server on port 8080'));

Debug

Known issues

breakingThe library is ESM-only; CommonJS require() will fail with 'ERR_REQUIRE_ESM'.

fix

Use import syntax or dynamic import() in CommonJS projects.

affects: >=1.0.0

gotchaIncoming messages from clients must be masked (RFC 6455). The library does not automatically mask server-to-client frames; you must set mask bit if required.

fix

When sending frames to client, ensure the mask bit is set to 0. For server-to-client, mask should be 0; only client-to-server frames must be masked.

affects: all

gotchasendHandshake does not validate the request; calling it on non-WebSocket upgrade requests may cause unexpected behavior.

fix

Only call sendHandshake after confirming the request is a valid WebSocket upgrade (check request headers).

affects: all

deprecatedThe library is low-level and requires direct handling of frame opcodes and payloads; no built-in ping/pong auto-response.

fix

Manually handle opcode 0x9 (Ping) to send a Pong frame using prepareWebsocketFrame with opcode 0xA.

affects: all

Errors

Common errors & fixes

ERR_MODULE_NOT_FOUND

Attempting to require('ws-low-level') in CommonJS project.

fix

Use import { sendHandshake } from 'ws-low-level' or use dynamic import: const ws = await import('ws-low-level')

TypeError: socket.setTimeout is not a function

The socket might be an http.IncomingMessage instead of net.Socket.

fix

Ensure you access the socket from the 'upgrade' event, which is a net.Socket (or stream.Duplex).

Error: Unexpected server response: 426

Server sends HTTP 426 Upgrade Required when client does not send proper WebSocket upgrade headers.

fix

Check that client sends 'Upgrade: websocket' and 'Connection: Upgrade' headers.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/jonlachlan/node-ws-low-level ↗

packagews-low-level ↗

homepagehttps://github.com/jonlachlan/node-ws-low-level#readme ↗