insite-ws

library2.4.0jsnpmunverified

WebSocket abstraction for server and client with built-in heartbeat, request/response RPC protocol, and connection quality tracking. Part of the inSite stack, designed for seamless integration with insite-ws-transfers, insite-users-server-ws, and other inSite packages. Current stable version is 2.4.0. Release cadence is not actively maintained. The package provides three entry points: insite-ws/server for Node.js, insite-ws/client for browser/Bun, and insite-ws/client/node for Node.js with ws polyfill. Key differentiators: message format uses JSON arrays, built-in request/response RPC with `~r-q`/`~r-s` kinds, heartbeat at 5-second intervals, and auto-reconnect on client side. The server supports SSL, custom client classes, and event-based message handling. Requires Node.js >=20.0.0.

messaging

npm install insite-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INSITE-WS

insite-ws

messagingjavascriptv2.4.0

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.

WSServer

✓ import { WSServer } from 'insite-ws/server'

✗ import { WSServer } from 'insite-ws'

Server entry point is a separate subpath import. The main package export does not contain WSServer.

WSClient

✓ import { WSClient } from 'insite-ws/client'

✗ const WSClient = require('insite-ws').WSClient

Client is imported from 'insite-ws/client' in browser/Bun environments. For Node.js, use 'insite-ws/client/node'.

WSServerClient

✓ import { WSServerClient } from 'insite-ws/server'

WSServerClient is the client class used internally by the server for each connected client. Rarely needed directly.

Options

✓ import type { Options } from 'insite-ws/server'

Options type is only needed for TypeScript projects; import as type.

Shows how to create a WebSocket server with a request handler, connect a client, send an RPC request, and get a response.

import { WSServer } from 'insite-ws/server'; import { WSClient } from 'insite-ws/client'; async function main() { const wss = new WSServer({ port: 8080 }); console.log('Server listening on ws://localhost:8080'); wss.addRequestListener('greet', (client, name: string) => { console.log(`Greeting ${name} from ${client.id}`); return `Hello, ${name}!`; }); const client = new WSClient('ws://localhost:8080'); await client.connect(); const response = await client.request('greet', 'World'); console.log('Response:', response); // 'Hello, World!' client.close(); wss.close(); } main().catch(console.error);

Debug

Known issues

breakingVersion 2.x requires Node.js >=20.0.0. Older versions of Node.js are not supported.

fix

Upgrade Node.js to version 20 or higher.

affects: >=2.0.0

gotchaClient entry points differ between browser and Node. Using 'insite-ws/client' in Node will fail because it relies on globalThis.WebSocket which may not be defined.

fix

In Node.js, import from 'insite-ws/client/node' instead of 'insite-ws/client'.

affects: >=0.0.0

gotchaThe request/response protocol uses message kinds '~r-q' and '~r-s-{id}'. Custom message kinds starting with '~r-' may conflict.

fix

Avoid using message kinds that start with '~r-' in your application logic, as they are reserved for internal RPC.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'insite-ws/server'

The package is not installed or the import path is incorrect.

fix

Run 'npm install insite-ws' and ensure you use the correct subpath import: 'insite-ws/server'.

TypeError: globalThis.WebSocket is not a constructor

Using 'insite-ws/client' in a Node.js environment where WebSocket is not globally defined.

fix

Change import to 'insite-ws/client/node' which polyfills WebSocket using the 'ws' package.

Error [ERR_REQUIRE_ESM]: require() of ES Module

The package is ESM-only and cannot be used with CommonJS require().

fix

Use import syntax (import { ... } from 'insite-ws/server') or set type: 'module' in your package.json.

Upgrade

Version history

2.4.0latest on npm

Audit

Dependencies

wsrequiredWebSocket implementation for Node.js server and client/node entry points

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nesvet/insite ↗

packageinsite-ws ↗

homepagehttps://github.com/nesvet/insite#readme ↗