pull-websocket

library3.4.2jsnpmunverified

A pull-stream-based WebSocket client and server library, actively maintained as a friendly fork of the unmaintained pull-ws. Current version 3.4.2 (stable, last updated 2022). Provides a simple pull-stream interface for WebSocket connections, supporting both client (connect) and server (createServer) modes. Key differentiators: uses pull-streams for backpressure and composability, works in Node.js and browsers (with bundlers), and supports TLS and HTTP server integration. Compared to raw ws or WebSocket, it integrates seamlessly with the pull-stream ecosystem for streaming data.

messaging

npm install pull-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PULL-WEBSOCKET

pull-websocket

messagingjavascriptv3.4.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.

connect

✓ import { connect } from 'pull-websocket'

✗ const connect = require('pull-websocket/client')

Default import is preferred for ESM; the client subpath is also valid but less common in modern code.

createServer

✓ import { createServer } from 'pull-websocket'

✗ const createServer = require('pull-websocket/server')

Same as connect; importing from main module is recommended over subpath require.

duplex

✓ import { duplex } from 'pull-websocket'

✗ const duplex = require('pull-websocket/duplex')

For direct WebSocket-to-pull-stream conversion; less common but available.

Shows basic server and client using pull-stream duplex connection. Server echoes data; client sends messages and logs responses.

import { connect, createServer } from 'pull-websocket'; import pull from 'pull-stream'; // Server createServer((stream) => { pull(stream, stream); // echo }).listen(8080, () => console.log('Server listening on port 8080')); // Client connect('ws://localhost:8080', (err, stream) => { if (err) return console.error('Connection error:', err); pull( pull.values(['hello', 'world']), stream, pull.drain(console.log, () => console.log('done')) ); });

Debug

Known issues

breakingVersion 3.0.0 changed the import path: previously require('pull-ws') now require('pull-websocket').

fix

Update all imports from 'pull-ws' to 'pull-websocket'.

affects: >=3.0.0

gotchaBinary mode defaults differ: on Node.js binary: true, on browser binary: false (strings). This can cause data type mismatches in cross-platform code.

fix

Always explicitly set binary: true when expecting binary data across platforms.

affects: >=3.0.0

deprecatedThe subpath require('pull-websocket/client') or require('pull-websocket/server') are deprecated in favor of named imports from main module.

fix

Use import { connect, createServer } from 'pull-websocket' instead.

affects: >=3.4.0

gotchaWebSocket connections do not support half-open mode. Using pull-stream protocols that assume half-open (e.g., muxrpc) may cause issues.

fix

Use pull-goodbye or design protocol to handle WebSocket's full-duplex nature.

affects: >=3.0.0

gotchaIn browser environments, require('ws') is not available. The library will try to use native WebSocket but may fail if not bundled correctly.

fix

Ensure bundler (webpack, browserify) correctly polyfills or excludes ws for browser targets.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pull-websocket/client'

Using subpath require in a bundler that doesn't support package.json exports field incorrectly.

fix

Use import { connect } from 'pull-websocket' instead.

TypeError: pull is not a function

Missing pull-stream dependency or incorrect import.

fix

Install pull-stream: npm install pull-stream, and import pull: import pull from 'pull-stream'.

Error: connect ECONNREFUSED ws://localhost:8080

Server not running or wrong URL.

fix

Ensure server is started and URL is correct (ws:// or wss://).

TypeError: stream is not a duplex pull stream

Passing non-stream object to createServer callback.

fix

Use pull(stream, ...) directly on the callback parameter passed to createServer.

ReferenceError: WebSocket is not defined

Using in Node.js without ws dependency.

fix

Install ws: npm install ws, or use a bundler for browser.

Upgrade

Version history

3.4.2latest on npm

Audit

Dependencies

pull-streamrequiredPeer dependency for pull-stream interfaces (duplex, source, sink). Must be installed manually.

wsoptionalUnderlying WebSocket implementation on Node.js. Required for server.

Agent activity

15 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/arj03/pull-websocket ↗

packagepull-websocket ↗

homepagehttps://github.com/arj03/pull-websocket/ ↗