it-ws

library6.1.5jsnpmunverified

Simple async iterables for websocket client and server connections. Current stable version is 6.1.5, released under the npm package 'it-ws'. Provides async iterable-based (push-based) duplex streams for WebSocket communication, leveraging the 'ws' library on Node.js and native WebSocket API in browsers. Key differentiators: ESM-only, TypeScript types included, supports both client and server (including TLS), integrates with 'it-pipe' for composable streaming. Alternative to raw WebSocket or socket.io for scenarios requiring lightweight, iterable-based streaming.

messaging

npm install it-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · IT-WS

it-ws

messagingjavascriptv6.1.5

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 'it-ws/client'

✗ import { connect } from 'it-ws'

Must import from specific subpath 'it-ws/client'; top-level export is not available.

createServer

✓ import { createServer } from 'it-ws/server'

✗ const createServer = require('it-ws/server')

ESM-only since v6; CommonJS require will fail. Import from 'it-ws/server' subpath.

duplex

✓ import duplex from 'it-ws/duplex'

✗ import { duplex } from 'it-ws/duplex'

Default export from subpath; named export does not exist.

Shows a WebSocket echo server and client using async iterables with it-ws and it-pipe.

import { connect } from 'it-ws/client' import { createServer } from 'it-ws/server' import { pipe } from 'it-pipe' // Server const server = createServer((stream) => { pipe(stream, stream) // echo }) await server.listen(8080) // Client const stream = connect('ws://localhost:8080') await stream.connected() // Send and receive pipe( ['hello', 'world'], stream, async function (source) { for await (const msg of source) { console.log('received:', msg) } } )

Debug

Known issues

breakingv6 is ESM-only; CommonJS require() will throw.

fix

Use import syntax or switch to dynamic import().

affects: >=6.0.0

breakingImports must use subpath exports ('it-ws/client', 'it-ws/server'), not top-level.

fix

Change import { connect } from 'it-ws' to import { connect } from 'it-ws/client'.

affects: >=6.0.0

deprecatedThe 'binary' option in connect() may have inconsistent defaults across environments.

fix

Explicitly set binary: true/false to avoid surprises.

affects: >=2.0.0 <6.0.0

gotchaOn browsers, default binary is false (string), but on Node it's true (Buffer). This can cause type mismatches.

fix

Always set binary option explicitly: connect(url, { binary: true }) for Buffer/ArrayBuffer.

affects: >=1.0.0

gotchaThe duplex function expects a WebSocket instance; not directly usable with other transport types.

fix

Provide a raw WebSocket object from the native API or the 'ws' library.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'it-ws'

Trying to import from top-level package instead of subpath.

fix

Use import { connect } from 'it-ws/client' or import { createServer } from 'it-ws/server'.

TypeError: (0 , it_ws_client__WEBPACK_IMPORTED_MODULE_0__.connect) is not a function

Importing from wrong path or using named import instead of default.

fix

For 'duplex', import default: import duplex from 'it-ws/duplex'. For 'connect', use named import from 'it-ws/client'.

Error [ERR_REQUIRE_ESM]: require() of ES Module from CommonJS

Using require() on an ESM-only package.

fix

Switch to dynamic import() or use ESM: 'type': 'module' in package.json.

Upgrade

Version history

6.1.5latest on npm

Audit

Dependencies

wsoptionalWebSocket implementation on Node.js; optional in browser

it-pipeoptionalCommonly used for piping duplex streams together

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alanshaw/it-ws ↗

packageit-ws ↗

homepagehttps://github.com/alanshaw/it-ws#readme ↗