Registry / http-networking / ws-parser

ws-parser

JSON →
library0.6.4jsnpmunverified

The `ws-parser` package provides a low-level stream parser specifically designed for WebSocket frames and messages. It is an internal component of the `whistle` debugging proxy and is explicitly *not* recommended for third-party application use. The current stable version is 0.6.4, last updated in February 2021. Given its specialized purpose and the explicit warning in its documentation, general developers should expect limited support, a lack of typical feature development, and potentially API choices optimized solely for its integration within `whistle`. It focuses on parsing raw WebSocket data, emitting events for parsed frames and complete messages, without providing a full WebSocket client/server implementation. Its release cadence is sporadic, tied to `whistle`'s needs, rather than a regular schedule.

http-networking
npm install ws-parser
github ↗package ↗
INSTALL
IMPORT
SIG · WS-PARSER
W
ws-parser
http-networkingjavascriptv0.6.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

Parser
✓ const Parser = require('ws-parser');
✗ import { Parser } from 'ws-parser';
`ws-parser` is a CommonJS module. Attempting to use ES module `import` syntax will result in an error in most Node.js environments without explicit configuration.
Parser (instance)
✓ const parser = new Parser();
✗ const parser = Parser();
The `Parser` is a class and must be instantiated with `new`.

This quickstart demonstrates how to instantiate the `ws-parser` `Parser` class, feed it raw WebSocket frame buffers, and listen for emitted `frame` and `message` events, including basic error handling.

const Parser = require('ws-parser'); const { Duplex } = require('stream'); // Simulate an incoming WebSocket stream buffer const wsFrameBuffer = Buffer.from([ 0x81, 0x05, // Fin bit, Text frame, length 5 0x48, 0x65, 0x6c, 0x6c, 0x6f // "Hello" ]); // Create a new parser instance const parser = new Parser(); // Listen for 'frame' events (raw WebSocket frames) parser.on('frame', (frame) => { console.log('Received frame:', { opcode: frame.opcode, mask: frame.mask, data: frame.data.toString() }); }); // Listen for 'message' events (complete WebSocket messages, potentially fragmented) parser.on('message', (message) => { console.log('Received message:', message.data.toString()); }); // Listen for errors parser.on('error', (err) => { console.error('Parser error:', err.message); }); // Write the simulated WebSocket frame buffer to the parser parser.write(wsFrameBuffer); // Simulate another frame for a full message const anotherWsFrameBuffer = Buffer.from([ 0x81, 0x07, // Fin bit, Text frame, length 7 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21, 0x21 // "World!!" ]); parser.write(anotherWsFrameBuffer); // End the stream after all data is written parser.end();
Debug
Known issues
breakingThe `ws-parser` module is explicitly stated in its README as being 'dedicated to whistle use, third-party app do not use the module.' This means its API is not guaranteed to be stable for external consumers, and breaking changes may occur without notice or adherence to semantic versioning for non-whistle users.
fix
Avoid using this module directly in third-party applications. If you need a WebSocket parser, consider general-purpose libraries like `ws` (which has its own framing parser) or dedicated WebSocket protocol parsers designed for broader consumption.
affects: >=0.1.0
gotchaThis package is a CommonJS module and does not officially support ES Module `import` syntax. Attempting to `import Parser from 'ws-parser'` directly in an ESM context will lead to runtime errors without explicit Node.js configuration (e.g., `createRequire`).
fix
Use `const Parser = require('ws-parser');` for importing the module in CommonJS environments. For ES Modules, if absolutely necessary, use `const Parser = require('ws-parser').Parser;` or consider dynamic `import('ws-parser').then(mod => new mod.Parser())` but be aware of the primary 'do not use' warning.
affects: >=0.1.0
gotchaThe package has seen infrequent updates, with the latest release (0.6.4) published over three years ago. This indicates a low maintenance priority for general use, meaning bug fixes or new features for non-`whistle` applications are unlikely.
fix
Be aware that issues encountered may not be resolved. Consider contributing fixes upstream or forking the repository if critical updates are required for a `whistle`-dependent workflow. For independent projects, use a more actively maintained library.
affects: >=0.6.4
Errors
Common errors & fixes
TypeError: ws_parser_1.Parser is not a constructor
Attempting to use ES module `import` syntax in a TypeScript or ESM project without proper CommonJS interoperability for a CommonJS-only package. The default export is not `Parser` in this context.
fix
In TypeScript/ESM, use `import Parser = require('ws-parser');` or `const Parser = require('ws-parser').Parser;` to correctly import the CommonJS class. Ensure your `tsconfig.json` or build setup handles CommonJS interoperability.
TypeError: Cannot read properties of undefined (reading 'write')
This error often occurs when the `Parser` class is not correctly instantiated with `new`, or when trying to call `write` on a variable that is not a `Parser` instance.
fix
Ensure you are creating an instance of the parser using `const parser = new Parser();` before attempting to call methods like `write()` or `end()` on it.
Upgrade
Version history
0.6.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
githubhttps://github.com/avwo/ws-parser ↗
packagehttps://www.npmjs.com/package/ws-parser ↗
ws-parser — npm install ws-parser · libregistry