{"id":48204,"library":"it-ws","title":"it-ws","description":"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.","status":"active","version":"6.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/alanshaw/it-ws","tags":["javascript","async","iterable","iterator","websocket","ws","typescript"],"install":[{"cmd":"npm install it-ws","lang":"bash","label":"npm"},{"cmd":"yarn add it-ws","lang":"bash","label":"yarn"},{"cmd":"pnpm add it-ws","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"WebSocket implementation on Node.js; optional in browser","package":"ws","optional":true},{"reason":"Commonly used for piping duplex streams together","package":"it-pipe","optional":true}],"imports":[{"note":"Must import from specific subpath 'it-ws/client'; top-level export is not available.","wrong":"import { connect } from 'it-ws'","symbol":"connect","correct":"import { connect } from 'it-ws/client'"},{"note":"ESM-only since v6; CommonJS require will fail. Import from 'it-ws/server' subpath.","wrong":"const createServer = require('it-ws/server')","symbol":"createServer","correct":"import { createServer } from 'it-ws/server'"},{"note":"Default export from subpath; named export does not exist.","wrong":"import { duplex } from 'it-ws/duplex'","symbol":"duplex","correct":"import duplex from 'it-ws/duplex'"}],"quickstart":{"code":"import { connect } from 'it-ws/client'\nimport { createServer } from 'it-ws/server'\nimport { pipe } from 'it-pipe'\n\n// Server\nconst server = createServer((stream) => {\n  pipe(stream, stream) // echo\n})\nawait server.listen(8080)\n\n// Client\nconst stream = connect('ws://localhost:8080')\nawait stream.connected()\n\n// Send and receive\npipe(\n  ['hello', 'world'],\n  stream,\n  async function (source) {\n    for await (const msg of source) {\n      console.log('received:', msg)\n    }\n  }\n)","lang":"typescript","description":"Shows a WebSocket echo server and client using async iterables with it-ws and it-pipe."},"warnings":[{"fix":"Use import syntax or switch to dynamic import().","message":"v6 is ESM-only; CommonJS require() will throw.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Change import { connect } from 'it-ws' to import { connect } from 'it-ws/client'.","message":"Imports must use subpath exports ('it-ws/client', 'it-ws/server'), not top-level.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Explicitly set binary: true/false to avoid surprises.","message":"The 'binary' option in connect() may have inconsistent defaults across environments.","severity":"deprecated","affected_versions":">=2.0.0 <6.0.0"},{"fix":"Always set binary option explicitly: connect(url, { binary: true }) for Buffer/ArrayBuffer.","message":"On browsers, default binary is false (string), but on Node it's true (Buffer). This can cause type mismatches.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Provide a raw WebSocket object from the native API or the 'ws' library.","message":"The duplex function expects a WebSocket instance; not directly usable with other transport types.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'6.1.5':17 'altern':74 'api':48 'async':5,27,89 'base':30,33,86 'browser':50 'client':9,61 'communic':38 'compos':72 'connect':12 'current':13 'differenti':52 'duplex':34 'esm':54 'esm-on':53 'includ':58,64 'integr':66 'it-pip':68 'it-w':1,23 'iter':6,29,85,90,91 'iterable-bas':28,84 'javascript':88 'key':51 'leverag':39 'librari':42 'lightweight':83 'nativ':46 'node.js':44 'npm':21 'packag':22 'pipe':70 'provid':26 'push':32 'push-bas':31 'raw':76 'releas':18 'requir':82 'scenario':81 'server':11,63 'simpl':4 'socket.io':79 'stabl':14 'stream':35,73,87 'support':59 'tls':65 'type':57 'typescript':56,94 'version':15 'websocket':8,37,47,77,92 'ws':3,25,41,93","created_at":"2026-06-07T16:55:26.543458+00:00","updated_at":"2026-06-07T16:55:26.543458+00:00","problems":[{"fix":"Use import { connect } from 'it-ws/client' or import { createServer } from 'it-ws/server'.","cause":"Trying to import from top-level package instead of subpath.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'it-ws'"},{"fix":"For 'duplex', import default: import duplex from 'it-ws/duplex'. For 'connect', use named import from 'it-ws/client'.","cause":"Importing from wrong path or using named import instead of default.","error":"TypeError: (0 , it_ws_client__WEBPACK_IMPORTED_MODULE_0__.connect) is not a function"},{"fix":"Switch to dynamic import() or use ESM: 'type': 'module' in package.json.","cause":"Using require() on an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module from CommonJS"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/alanshaw/it-ws#readme","github":"https://github.com/alanshaw/it-ws","docs":null,"changelog":null,"pypi":null,"npm":"it-ws","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}