zerva-websocket

library0.3.5jsnpmunverified

Zerva WebSocket is a lightweight, resilient WebSocket module for the Zerva event-driven server framework. Version 0.3.5 provides plain WebSocket connections with automatic reconnection, heartbeat (ping/pong), and supports three communication patterns: raw binary channels (via Zeed Channel), typed message interfaces (via Zeed Message), and PubSub. It is designed for Node.js (>=14.13.1) with full TypeScript support. Key differentiators include transparent reconnection that preserves the same channel object, binary-first encoding with pluggable codecs, and tight integration with Zeed's messaging primitives. Ideal for applications needing simple, reliable WebSocket communication without the overhead of Socket.IO.

messaging

npm install zerva-websocket

package ↗

INSTALL

IMPORT

SIG · ZERVA-WEBSOCKET

zerva-websocket

messagingjavascriptv0.3.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.

useWebSocket

✓ import { useWebSocket } from 'zerva-websocket'

✗ const { useWebSocket } = require('zerva-websocket')

ESM only; CommonJS require is not supported.

✓ import { on } from 'zerva'

✗ import { on } from 'zerva-websocket'

The `on` function is exported by the `zerva` core package, not by `zerva-websocket`.

WebSocketConnection

✓ import { WebSocketConnection } from 'zerva-websocket'

✗ import { WebSocketConnection } from 'zerva'

WebSocketConnection is a class for client-side use, exported from zerva-websocket.

useMessageHub

✓ import { useMessageHub } from 'zeed'

✗ import { useMessageHub } from 'zerva-websocket'

useMessageHub is from the zeed package, not from zerva-websocket.

Sets up a WebSocket server using Zerva, listens for connections, echoes messages via MessageHub, and connects from client side.

import { useWebSocket, WebSocketConnection } from 'zerva-websocket' import { useHttp } from 'zerva-http' import { on } from 'zerva' import { useMessageHub } from 'zeed' // Server useHttp({ port: 8080 }) useWebSocket() on('webSocketConnect', ({ channel }) => { const hub = useMessageHub({ channel }) hub.listen({ echo(msg) { return msg } }) }) // Client const channel = new WebSocketConnection('ws://localhost:8080') const send = useMessageHub({ channel }).send() const response = await send.echo('Hello') console.log(response) // 'Hello'

Debug

Known issues

gotchaWebSocketConnection requires the WebSocket protocol URL (ws:// or wss://) for client connections; otherwise it defaults to window.location but may fail in Node.js.

fix

Always pass a full URL to the WebSocketConnection constructor when running in Node.js, e.g., new WebSocketConnection('ws://localhost:8080').

affects: >=0.0.0

gotchauseWebSocket() must be called after useHttp() to attach to the HTTP server; otherwise it will throw or not work.

fix

Ensure useHttp() is called before useWebSocket().

affects: >=0.0.0

gotchaThe `on` function for events like 'webSocketConnect' must be imported from 'zerva', not 'zerva-websocket'.

fix

import { on } from 'zerva'

affects: >=0.0.0

gotchaTypeScript types are shipped but may require tsconfig to have 'moduleResolution' set to 'node' or 'nodenext' to resolve correctly.

fix

Set 'moduleResolution' to 'node' (or 'nodenext') in tsconfig.json.

affects: >=0.3.0

Errors

Common errors & fixes

Error: Cannot find module 'zerva-websocket'

Missing installation of zerva-websocket package

fix

npm install zerva-websocket

TypeError: on is not a function

`on` imported from zerva-websocket instead of zerva

fix

import { on } from 'zerva'

Error: useWebSocket must be called after useHttp

useWebSocket() invoked before HTTP server is created

fix

Call useHttp() before useWebSocket()

Upgrade

Version history

0.3.5latest on npm

Audit

Dependencies

zeedrequiredProvides Channel, Message, and PubSub primitives used by zerva-websocket

zervarequiredCore framework for event handling and HTTP integration

zerva-httprequiredHTTP module required to upgrade server to WebSocket (useHttp is a prerequisite)

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

packagezerva-websocket ↗