# @httptoolkit/websocket-stream

> Use websockets with the node streams API. Works in browser and node, with all current WS versions

Latest version **6.0.1** (published 2022-06-17) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install @httptoolkit/websocket-stream
pnpm add @httptoolkit/websocket-stream
yarn add @httptoolkit/websocket-stream
bun add @httptoolkit/websocket-stream
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.1 |
| Published | 2022-06-17 |
| First published | 2021-09-30 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 29 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Maintainers | pimterry |
| Keywords | websocket, websockets, stream, streams, realtime |

## Links

- npm: https://www.npmjs.com/package/@httptoolkit/websocket-stream
- Repository: https://github.com/httptoolkit/websocket-stream
- Homepage: https://github.com/httptoolkit/websocket-stream#readme
- Issues: https://github.com/httptoolkit/websocket-stream/issues
- npm.io page: https://npm.io/package/@httptoolkit/websocket-stream

## Dependencies (8)

- [ws](https://npm.io/package/ws.md) *
- [xtend](https://npm.io/package/xtend.md) ^4.0.0
- [inherits](https://npm.io/package/inherits.md) ^2.0.1
- [@types/ws](https://npm.io/package/@types/ws.md) *
- [duplexify](https://npm.io/package/duplexify.md) ^3.5.1
- [safe-buffer](https://npm.io/package/safe-buffer.md) ^5.1.2
- [isomorphic-ws](https://npm.io/package/isomorphic-ws.md) ^4.0.1
- [readable-stream](https://npm.io/package/readable-stream.md) ^2.3.3

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 6.0.1 (latest) — 2022-06-17
- 6.0.0 — 2021-09-30

## README

# websocket-stream [![Build Status](https://github.com/httptoolkit/websocket-stream/workflows/CI/badge.svg)](https://github.com/httptoolkit/websocket-stream/actions) [![Get it on npm](https://img.shields.io/npm/v/@httptoolkit/websocket-stream.svg)](https://www.npmjs.com/package/@httptoolkit/websocket-stream)

> _Part of [HTTP Toolkit](https://httptoolkit.tech): powerful tools for building, testing & debugging HTTP(S)_

Use HTML5 [websockets](https://developer.mozilla.org/en-US/docs/WebSockets) using the Node Streams API.

This is a fork of the original [websocket-stream](https://www.npmjs.com/package/websocket-stream) (now unmaintained), for use in HTTP Toolkit. This fork:

* Uses [isomorphic-ws](https://www.npmjs.com/package/isomorphic-ws) so that the 'ws' module is not loaded unnecessarily in browsers
* Supports WS up to version 8 (note that isomorphic-ws uses * as its ws version, so this will always use the latest compatible release)
* Fixes and extends the TypeScript types, and adds an explicit dependency on @types/ws
* Has a CI build for automated testing
* Adds a 'ws-close' event, which exposes the close event data when a websocket is closed by a close frame (before the stream 'close' event, which is different)

### Usage

This module works in Node or in Browsers that support WebSockets. You can use [browserify](http://github.com/substack/node-browserify) to package this module for browser use.

```javascript
var websocket = require('@httptoolkit/websocket-stream')
var ws = websocket('ws://echo.websocket.org')
process.stdin.pipe(ws)
ws.pipe(process.stdout)
```

In the example above `ws` is a duplex stream. That means you can pipe output to anything that accepts streams. You can also pipe data into streams (such as a webcam feed or audio data).

The underlying `WebSocket` instance is available as `ws.socket`.

#### Options

The available options differs depending on if you use this module in the browser or with node.js. Options can be passed in as the third or second argument - `WebSocket(address, [protocols], [options])`.

##### `options.browserBufferSize`

How much to allow the [socket.bufferedAmount](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket#Attributes) to grow before starting to throttle writes. This option has no effect in node.js.

Default: `1024 * 512` (512KiB)

##### `options.browserBufferTimeout`

How long to wait before checking if the socket buffer has drained sufficently for another write. This option has no effect in node.js.

Default: `1000` (1 second)

##### `options.objectMode`

Send each chunk on its own, and do not try to pack them in a single
websocket frame.

Default: `false`

##### `options.binary`

Always convert to `Buffer` in Node.js before sending.
Forces `options.objectMode` to `false`.

Default: `true`

##### `options.perMessageDeflate`

We recommend disabling the [per message deflate
extension](https://tools.ietf.org/html/rfc7692) to achieve the best
throughput.

Default: `true` on the client, `false` on the server.

Example:

```js
var websocket = require('@httptoolkit/websocket-stream')
var ws = websocket('ws://realtimecats.com', {
  perMessageDeflate: false
})
```

Beware that this option is ignored by browser clients. To make sure that permessage-deflate is never used, disable it on the server.

##### Other options

When used in node.js see the [ws.WebSocket documentation](https://github.com/websockets/ws/blob/master/doc/ws.md#class-wswebsocket)

### On the server

Using the [`ws`](http://npmjs.org/ws) module you can make a websocket server and use this module to get websocket streams on the server:

```javascript
var websocket = require('@httptoolkit/websocket-stream')
var wss = websocket.createServer({server: someHTTPServer}, handle)

function handle(stream, request) {
  // `request` is the upgrade request sent by the client.
  fs.createReadStream('bigdata.json').pipe(stream)
}
```

We recommend disabling the [per message deflate
extension](https://tools.ietf.org/html/rfc7692) to achieve the best
throughput:

```javascript
var websocket = require('@httptoolkit/websocket-stream')
var wss = websocket.createServer({
  perMessageDeflate: false,
  server: someHTTPServer
}, handle)

function handle(stream) {
  fs.createReadStream('bigdata.json').pipe(stream)
}
```

You can even use it on express.js with the [express-ws](https://www.npmjs.com/package/express-ws) library:

```js
const express = require('express');
const expressWebSocket = require('express-ws');
const websocketStream = require('websocket-stream/stream');
const app = express();

// extend express app with app.ws()
expressWebSocket(app, null, {
    // ws options here
    perMessageDeflate: false,
});

app.ws('/bigdata.json', function(ws, req) {
  // convert ws instance to stream
  const stream = websocketStream(ws, {
    // websocket-stream options here
    binary: true,
  });

  fs.createReadStream('bigdata.json').pipe(stream);
});

app.listen(3000);
```

## Run the tests

### Server-side tests

```
npm test
```

### Client-side tests

First start the echo server by running `node test-server.js`

Then run `npm start` and open `localhost:9966` in your browser and open the Dev Tools console to see test output.

## license

BSD LICENSE

---
_Source: https://npm.io/package/@httptoolkit/websocket-stream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._