A generic websocket connection with Zod schema validation and on message execution.
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

update Readme

vinerima a6feb7b2 3af26a56

+26 -5
+25 -4
README.md
··· 2 2 3 3 Generic WebSocket action handler for TypeScript. Connect to any WebSocket, define message schemas with [Zod](https://zod.dev), and dispatch to typed handlers. 4 4 5 + Works in both Node.js and browser environments with zero configuration — the runtime is detected automatically. 6 + 5 7 ## Features 6 8 9 + - **Cross-platform** — Runs in Node.js (using `ws`) and browsers (using native `WebSocket`) with the same API. Runtime detection is automatic. 7 10 - **Schema-matched handlers** — Register Zod schemas with handler functions. Incoming messages are validated at runtime, and all matching handlers are invoked with fully typed data. 8 11 - **Multi-service failover** — Provide multiple WebSocket URLs. On connection failure, wah cycles through them with exponential backoff. 9 12 - **Dynamic query parameters** — Update URL query parameters at runtime. The connection gracefully reconnects with the new URL. ··· 14 17 ## Installation 15 18 16 19 ```bash 17 - pnpm add wah 20 + pnpm add @vinerima/wah 21 + ``` 22 + 23 + In Node.js, install `ws` as well: 24 + 25 + ```bash 26 + pnpm add ws 18 27 ``` 19 28 29 + `ws` is an optional peer dependency — browser environments use the native `WebSocket` and don't need it. 30 + 20 31 ## Quick Start 21 32 22 33 ```typescript 23 - import { WebSocketClient, LogLevel } from "wah"; 34 + import { WebSocketClient, LogLevel } from "@vinerima/wah"; 24 35 import { z } from "zod"; 25 36 26 37 // Define message schemas ··· 73 84 client.close(); 74 85 ``` 75 86 87 + ## Platform Behavior 88 + 89 + | Concern | Node.js | Browser | 90 + |---|---|---| 91 + | WebSocket | `ws` package (peer dependency) | Native `WebSocket` | 92 + | Binary-to-string | `Buffer` | `TextDecoder` | 93 + | Heartbeat ping | Sends ping frames at `pingInterval` | No-op (browsers handle keepalive at the protocol level) | 94 + 95 + The `pingInterval` option has no effect in browser environments. Servers that send ping frames receive automatic pong responses from the browser's WebSocket implementation. 96 + 76 97 ## API Reference 77 98 78 99 ### `WebSocketClient` ··· 94 115 | `reconnect.backoffFactor` | `number` | `1.5` | Multiplier applied after each failed attempt. | 95 116 | `reconnect.maxAttempts` | `number` | `3` | Max attempts per service before switching. | 96 117 | `reconnect.maxServiceCycles` | `number` | `2` | Max full cycles through all services. | 97 - | `pingInterval` | `number` | `10000` | Heartbeat ping interval (ms). | 118 + | `pingInterval` | `number` | `10000` | Heartbeat ping interval (ms). No-op in browsers. | 98 119 | `logger.enabled` | `boolean` | `true` | Enable/disable logging. | 99 120 | `logger.level` | `LogLevel` | `INFO` | Minimum log level. | 100 121 | `logger.custom` | `LoggerInterface` | — | Custom logger implementation. | ··· 187 208 Replace the built-in console logger with your own implementation: 188 209 189 210 ```typescript 190 - import { WebSocketClient, LoggerInterface } from "wah"; 211 + import { WebSocketClient, LoggerInterface } from "@vinerima/wah"; 191 212 192 213 const myLogger: LoggerInterface = { 193 214 debug: (msg, ctx) => myLoggingService.log("debug", msg, ctx),
+1 -1
package.json
··· 1 1 { 2 2 "name": "@vinerima/wah", 3 - "version": "1.0.0", 3 + "version": "1.0.1", 4 4 "description": "Generic WebSocket action handler with Zod-based schema validation and typed message dispatch", 5 5 "author": "vinerima", 6 6 "license": "MIT",