{"id":14365,"library":"ws-parser","title":"WebSocket Stream Parser for Whistle","description":"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.","status":"maintenance","version":"0.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/avwo/ws-parser","tags":["javascript","whistle","websocket","ws"],"install":[{"cmd":"npm install ws-parser","lang":"bash","label":"npm"},{"cmd":"yarn add ws-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add ws-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`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.","wrong":"import { Parser } from 'ws-parser';","symbol":"Parser","correct":"const Parser = require('ws-parser');"},{"note":"The `Parser` is a class and must be instantiated with `new`.","wrong":"const parser = Parser();","symbol":"Parser (instance)","correct":"const parser = new Parser();"}],"quickstart":{"code":"const Parser = require('ws-parser');\nconst { Duplex } = require('stream');\n\n// Simulate an incoming WebSocket stream buffer\nconst wsFrameBuffer = Buffer.from([\n  0x81, 0x05, // Fin bit, Text frame, length 5\n  0x48, 0x65, 0x6c, 0x6c, 0x6f // \"Hello\"\n]);\n\n// Create a new parser instance\nconst parser = new Parser();\n\n// Listen for 'frame' events (raw WebSocket frames)\nparser.on('frame', (frame) => {\n  console.log('Received frame:', {\n    opcode: frame.opcode,\n    mask: frame.mask,\n    data: frame.data.toString()\n  });\n});\n\n// Listen for 'message' events (complete WebSocket messages, potentially fragmented)\nparser.on('message', (message) => {\n  console.log('Received message:', message.data.toString());\n});\n\n// Listen for errors\nparser.on('error', (err) => {\n  console.error('Parser error:', err.message);\n});\n\n// Write the simulated WebSocket frame buffer to the parser\nparser.write(wsFrameBuffer);\n\n// Simulate another frame for a full message\nconst anotherWsFrameBuffer = Buffer.from([\n  0x81, 0x07, // Fin bit, Text frame, length 7\n  0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21, 0x21 // \"World!!\"\n]);\nparser.write(anotherWsFrameBuffer);\n\n// End the stream after all data is written\nparser.end();\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"This 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`).","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.6.4"}],"env_vars":null,"search_vec":"'0.6.4':51 '2021':56 'api':82 'applic':44 'cadenc':115 'choic':83 'client/server':111 'complet':104 'compon':29 'current':47 'data':97 'debug':33 'design':19 'develop':69,79 'document':67 'emit':98 'event':99 'expect':71 'explicit':37,63 'featur':78 'februari':55 'focus':92 'frame':22,102 'full':109 'general':68 'given':57 'implement':112 'integr':88 'intern':28 'javascript':128 'lack':75 'last':52 'level':15 'limit':72 'low':14 'low-level':13 'messag':24,105 'need':122 'optim':84 'packag':10 'pars':94,101 'parser':3,9,17 'parti':43 'potenti':81 'provid':11,107 'proxi':34 'purpos':60 'rather':123 'raw':95 'recommend':39 'regular':126 'releas':114 'schedul':127 'sole':85 'special':59 'specif':18 'sporad':117 'stabl':48 'stream':2,16 'support':73 'third':42 'third-parti':41 'tie':118 'typic':77 'updat':53 'use':45 'version':49 'warn':64 'websocket':1,21,96,110,130 'whistl':5,32,90,120,129 'within':89 'without':106 'ws':8,131 'ws-parser':7","created_at":"2026-04-20T01:59:20.138810+00:00","updated_at":"2026-04-20T01:59:20.138810+00:00","problems":[{"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.","cause":"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.","error":"TypeError: ws_parser_1.Parser is not a constructor"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'write')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/avwo/ws-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/ws-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}