A generic websocket connection with Zod schema validation and on message execution.
update Readme
+26
-5
+25
-4
README.md
+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),