WebSocket Stream Adapter

Common errors

• TypeError: websocket.createServer is not a function

  cause Attempting to import `createServer` as a named export from `websocket-stream` in an ESM context, or incorrectly destructuring it from the default import.
  fix The `createServer` method is a property of the default export. Use `import websocket from 'websocket-stream'; websocket.createServer(...)`.

• Error: WebSocket is not open: readyState 0 (CONNECTING)

  cause Attempting to write to the WebSocket stream before the connection is fully established. The stream is in `CONNECTING` state (readyState 0) and not yet `OPEN` (readyState 1).
  fix Ensure you wait for the WebSocket connection to be open before piping data. You can listen for the `open` event on `ws.socket` or the `ready` event on the stream itself if provided by an abstraction layer, or simply ensure your stream pipeline starts after connection is established.

• ReferenceError: require is not defined in ES module scope

  cause Using `require('websocket-stream')` in a TypeScript or JavaScript file configured for ESM, or directly in a browser environment without a bundler.
  fix For ESM projects, use `import websocket from 'websocket-stream';`. If targeting browsers, ensure you are using a bundler like Browserify or Webpack that handles CommonJS modules for client-side code.

Warnings

• breaking Major version updates (v4.0.0, v5.0.0) updated the underlying `ws` dependency, which might introduce breaking changes from `ws` itself, such as API changes or different behaviors in message handling and options.
  Fix: Review the changelog for `ws` (versions 2.0.0 and 3.0.0 respectively) for any breaking changes that might affect your application logic or server configuration. Update configurations and code accordingly.
• gotcha The `perMessageDeflate` option default value differs between client (true) and server (false), and this option is ignored by browser clients. This can lead to unexpected compression behavior or performance issues if not explicitly configured consistently.
  Fix: Explicitly set `perMessageDeflate: false` on both the client and server if you aim for the best throughput, especially for large, frequent messages, as recommended in the documentation. For browser clients, ensure server-side configuration dictates the compression behavior.
• gotcha Options for `websocket-stream` vary between browser and Node.js environments. Options like `browserBufferSize` and `browserBufferTimeout` are specific to browser clients and have no effect in Node.js.
  Fix: Carefully review the documentation for each option and understand its applicability. Implement conditional logic or separate configuration files if your application targets both browser and Node.js environments with different requirements.
• deprecated Older versions might have used deprecated `Buffer` constructors, which can lead to runtime warnings or security issues in newer Node.js environments.
  Fix: Upgrade to `websocket-stream@5.1.2` or higher to ensure the use of modern and safe `Buffer` allocation methods (e.g., `Buffer.from()`).

Install

• npm install websocket-stream npm
• yarn add websocket-stream yarn
• pnpm add websocket-stream pnpm

Imports

• websocket
  wrong:

  const websocket = require('websocket-stream')

  correct:

  import websocket from 'websocket-stream'

  Primary import for both client and server-side usage. For ESM, use the default import; for CJS, use `require`.
• createServer
  wrong:

  import { createServer } from 'websocket-stream'

  correct:

  import websocket from 'websocket-stream'; websocket.createServer(...)

  `createServer` is a property of the default export, not a named export. It is used to create a WebSocket server compatible with Node.js streams.
• websocketStream
  wrong:

  import { websocketStream } from 'websocket-stream'

  correct:

  import websocketStream from 'websocket-stream/stream'

  This specific import path (`websocket-stream/stream`) is used when integrating with `express-ws` to convert a raw `ws` instance into a `websocket-stream` instance.

Quickstart

This quickstart demonstrates basic client-side usage, piping standard input to a WebSocket and piping received data to standard output, highlighting its duplex stream capabilities.

import websocket from 'websocket-stream';
import { createReadStream, createWriteStream } from 'fs';

const ws = websocket('ws://echo.websocket.org');

// Pipe stdin to the WebSocket
process.stdin.pipe(ws);

// Pipe WebSocket data to stdout
ws.pipe(process.stdout);

// Example of piping a file to the WebSocket
// const fileStream = createReadStream('data.txt');
// fileStream.pipe(ws);

// Example of receiving data from WebSocket and saving to a file
// const outputFileStream = createWriteStream('received.txt');
// ws.pipe(outputFileStream);

console.log('Connected to ws://echo.websocket.org. Type something and press Enter!');