xy-websocket

library1.14.1jsnpmunverified

Simple protocol for awaitable RPC calls and events over WebSocket connections. Current stable version is 1.14.1, with regular updates. Key differentiators: built-in RPC with automatic promise resolution, event broadcasting to all/single clients, and error handling that passes exceptions across the wire. Supports both server and client usage with a straightforward API. Compared to raw WebSocket or socket.io, it provides a higher-level abstraction for request-response patterns without heavy framework dependencies.

messaging

npm install xy-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XY-WEBSOCKET

xy-websocket

messagingjavascriptv1.14.1

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.

createServer

✓ import { createServer } from 'xy-websocket'

✗ const { createServer } = require('xy-websocket')

ESM only; package does not support CommonJS require().

createClient

✓ import { createClient } from 'xy-websocket'

✗ import createClient from 'xy-websocket'

Named export, not default. Use curly braces.

Server

✓ import type { Server } from 'xy-websocket'

✗ import { Server } from 'xy-websocket'

Server is a TypeScript type, not a runtime value. Use 'import type' to avoid bundling issues.

Creates a WebSocket server using Koa HTTP server, registers an RPC function 'greet', and broadcasts user count.

import http from 'http'; import Koa from 'koa'; import { createServer } from 'xy-websocket'; const app = new Koa(); const httpServer = http.createServer(app.callback()); const wsServer = createServer({ httpServer }); wsServer.register('greet', async ({ params }) => { return `Hello, ${params.name}!`; }); wsServer.broadcast('user_count', { count: wsServer.sockets.length });

Debug

Known issues

gotchaThe 'createServer' and 'createClient' are named exports, not default exports. Using default import will import 'undefined' instead.

fix

Use import { createServer } from 'xy-websocket' (curly braces).

affects: >=1.0

gotchaThe package is ESM-only; it cannot be imported via CommonJS require(). Attempting require() will result in an error.

fix

Use dynamic import() if in a CJS context, or switch to ESM.

affects: >=1.0

deprecatedThe 'Server' type export is deprecated for runtime use; it should only be used as a TypeScript type.

fix

Use import type { Server } from 'xy-websocket' for type annotations.

affects: >=1.10

Errors

Common errors & fixes

TypeError: xy_websocket_1.default is not a function

Using default import instead of named import for createServer or createClient.

fix

import { createServer } from 'xy-websocket'

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Using CommonJS require() to import an ESM-only package.

fix

Use import() or set type: 'module' in package.json.

Upgrade

Version history

1.14.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/xylogistics/xy-websocket ↗

packagexy-websocket ↗

homepagehttps://github.com/xylogistics/xy-websocket#readme ↗