@wooksjs/ws-client 0.7.0

package/skills/wooksjs-ws-client/core.md

@@ -0,0 +1,203 @@
+# Core concepts & setup — @wooksjs/ws-client
+
+> WebSocket client with RPC, subscriptions, reconnection, and push listeners — designed to pair with `@wooksjs/event-ws`.
+
+## Concepts
+
+`@wooksjs/ws-client` is a standalone WebSocket client (no dependency on `@wooksjs/event-core`) that speaks the same JSON wire protocol as `@wooksjs/event-ws`. It provides:
+
+- **Fire-and-forget messaging** via `send()`
+- **RPC (request-response)** via `call()` with correlation IDs and timeouts
+- **Subscriptions** via `subscribe()` with auto-resubscribe on reconnect
+- **Push listeners** via `on()` with exact and wildcard path matching
+- **Auto-reconnection** with configurable backoff
+- **Message queuing** when disconnected (with reconnect enabled)
+
+### Wire protocol
+
+The client sends `WsClientMessage` and receives either `WsReplyMessage` (for RPC) or `WsPushMessage` (for push/broadcast):
+
+```ts
+// Client → Server
+interface WsClientMessage {
+  event: string // e.g. "message", "rpc", "subscribe"
+  path: string // e.g. "/chat/rooms/lobby"
+  data?: unknown
+  id?: number // auto-generated for call(), triggers a reply
+}
+
+// Server → Client (reply)
+interface WsReplyMessage {
+  id: string | number
+  data?: unknown
+  error?: { code: number; message: string }
+}
+
+// Server → Client (push)
+interface WsPushMessage {
+  event: string
+  path: string
+  params?: Record<string, string>
+  data?: unknown
+}
+```
+
+## Installation / Setup
+
+```bash
+pnpm add @wooksjs/ws-client
+```
+
+The client uses the native `WebSocket` API (available in browsers and Node.js >= 22). For Node.js < 22, install the `ws` package — it's an optional peer dependency.
+
+## API Reference
+
+### `createWsClient(url, options?)`
+
+Factory function. Creates and immediately connects a `WsClient`.
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', {
+  reconnect: true,
+  rpcTimeout: 5000,
+})
+```
+
+### `WsClientOptions`
+
+```ts
+interface WsClientOptions {
+  protocols?: string | string[] // WebSocket sub-protocols
+  reconnect?: boolean | WsClientReconnectOptions // default: disabled
+  rpcTimeout?: number // ms (default: 10000)
+  messageParser?: (raw: string) => WsReplyMessage | WsPushMessage
+  messageSerializer?: (msg: WsClientMessage) => string
+  _WebSocket?: WebSocketConstructor // @internal — for testing
+}
+```
+
+### `WsClient` class
+
+#### `client.send(event, path, data?)`
+
+Fire-and-forget message. Queued when disconnected if reconnect is enabled.
+
+```ts
+client.send('message', '/chat/rooms/lobby', { text: 'hello' })
+```
+
+#### `client.call<T>(event, path, data?): Promise<T>`
+
+RPC call. Auto-generates a correlation ID. Rejects with `WsClientError` on timeout, server error, or disconnect.
+
+```ts
+const user = await client.call<User>('rpc', '/users/me')
+```
+
+#### `client.subscribe(path, data?): Promise<() => void>`
+
+Subscribe to a server path. Sends a `subscribe` event via RPC, stores the subscription for auto-resubscribe on reconnect. Returns an unsubscribe function.
+
+```ts
+const unsub = await client.subscribe('/chat/rooms/lobby')
+// later:
+unsub() // sends "unsubscribe" event
+```
+
+#### `client.on<T>(event, pathPattern, handler): () => void`
+
+Register a client-side push listener. Supports exact paths and wildcard (`*`) suffix. Returns an unregister function.
+
+```ts
+const off = client.on<{ text: string }>('message', '/chat/rooms/*', ({ data, path }) => {
+  console.log(`${path}: ${data.text}`)
+})
+```
+
+#### `client.close()`
+
+Close the connection. Disables reconnect. Rejects all pending RPCs. Clears the message queue.
+
+#### Lifecycle events
+
+```ts
+client.onOpen(() => console.log('Connected'))
+client.onClose((code, reason) => console.log(`Closed: ${code}`))
+client.onError((event) => console.error('Error:', event))
+client.onReconnect((attempt) => console.log(`Reconnecting #${attempt}`))
+```
+
+All lifecycle methods return an unregister function.
+
+### `WsClientError`
+
+Error class with a numeric `code`. Thrown/rejected by `call()` and `subscribe()`.
+
+Common codes:
+
+- `408` — RPC timeout
+- `503` — Not connected / connection lost / connection closed
+- Server error codes (e.g., `404`, `403`, `500`) from `WsReplyMessage.error`
+
+```ts
+try {
+  await client.call('rpc', '/protected')
+} catch (err) {
+  if (err instanceof WsClientError && err.code === 403) {
+    console.log('Forbidden')
+  }
+}
+```
+
+## Common Patterns
+
+### Pattern: Basic chat client
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', { reconnect: true })
+
+// Listen for messages
+client.on<{ text: string }>('message', '/chat/rooms/*', ({ data, path }) => {
+  console.log(`[${path}] ${data.text}`)
+})
+
+// Subscribe to a room
+await client.subscribe('/chat/rooms/lobby')
+
+// Send a message
+client.send('message', '/chat/rooms/lobby', { text: 'Hello everyone!' })
+```
+
+### Pattern: RPC calls
+
+```ts
+const client = createWsClient('wss://api.example.com/ws')
+
+const user = await client.call<{ name: string }>('rpc', '/users/me')
+console.log(user.name)
+```
+
+### Pattern: Custom serializer
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', {
+  messageSerializer: (msg) => JSON.stringify(msg),
+  messageParser: (raw) => JSON.parse(raw),
+})
+```
+
+## Best Practices
+
+- Always enable `reconnect` for production clients — network interruptions are inevitable
+- Set `rpcTimeout` appropriate for your use case (default: 10s)
+- Use typed generics with `call<T>()` and `on<T>()` for type-safe payloads
+- Store the unsubscribe/unregister functions returned by `subscribe()`, `on()`, `onOpen()`, etc. to prevent leaks
+- Call `client.close()` when the client is no longer needed
+
+## Gotchas
+
+- `call()` rejects immediately with code 503 if the socket is not open — it does NOT queue like `send()`
+- `send()` only queues when disconnected if `reconnect` is enabled; otherwise the message is silently dropped
+- The client connects immediately on construction — there is no `connect()` method
+- For Node.js < 22 without the `ws` package, the constructor throws `TypeError`
+- Subscriptions are auto-resubscribed on reconnect, but failures are silently swallowed — the next reconnect will retry

package/skills/wooksjs-ws-client/push.md

@@ -0,0 +1,111 @@
+# Push listeners — @wooksjs/ws-client
+
+> Client-side listeners for server push messages with exact and wildcard path matching.
+
+## Concepts
+
+Server push messages (`WsPushMessage`) arrive without a correlation ID — they represent broadcasts, room messages, or subscription notifications. The client dispatches these to registered handlers based on `event` + `path` matching.
+
+Two matching modes:
+
+1. **Exact match** — O(1) Map lookup by `"event:path"` key
+2. **Wildcard match** — path pattern ends with `*`, uses `startsWith` prefix check
+
+Handlers receive a `WsClientPushEvent<T>` with typed `data`.
+
+## API Reference
+
+### `client.on<T>(event, pathPattern, handler): () => void`
+
+Register a push listener. Returns an unregister function.
+
+Parameters:
+
+- `event: string` — the event type to match (e.g. `"message"`, `"notification"`)
+- `pathPattern: string` — exact path or wildcard (`"/chat/rooms/*"`)
+- `handler: WsPushHandler<T>` — receives `WsClientPushEvent<T>`
+
+```ts
+interface WsClientPushEvent<T = unknown> {
+  event: string // event type from server
+  path: string // concrete path from server
+  params: Record<string, string> // route params from server
+  data: T // typed payload
+}
+
+type WsPushHandler<T = unknown> = (ev: WsClientPushEvent<T>) => void
+```
+
+### Matching rules
+
+**Exact:**
+
+```ts
+client.on('message', '/chat/rooms/lobby', handler)
+// Matches: { event: 'message', path: '/chat/rooms/lobby' }
+// No match: { event: 'message', path: '/chat/rooms/general' }
+```
+
+**Wildcard:**
+
+```ts
+client.on('message', '/chat/rooms/*', handler)
+// Matches: { event: 'message', path: '/chat/rooms/lobby' }
+// Matches: { event: 'message', path: '/chat/rooms/general' }
+// No match: { event: 'notification', path: '/chat/rooms/lobby' }
+```
+
+The wildcard `*` only works as a suffix — `"/*/rooms"` is NOT supported.
+
+## Common Patterns
+
+### Pattern: Listen for chat messages in all rooms
+
+```ts
+client.on<{ text: string; from: string }>('message', '/chat/rooms/*', ({ data, path, params }) => {
+  console.log(`[${params.roomId ?? path}] ${data.from}: ${data.text}`)
+})
+```
+
+### Pattern: Notifications
+
+```ts
+client.on<{ title: string; body: string }>('notification', '/notifications', ({ data }) => {
+  showToast(data.title, data.body)
+})
+```
+
+### Pattern: Multiple listeners for the same path
+
+```ts
+// Both handlers fire for the same message
+client.on('message', '/chat/rooms/lobby', ({ data }) => updateUI(data))
+client.on('message', '/chat/rooms/lobby', ({ data }) => logMessage(data))
+```
+
+### Pattern: Cleanup
+
+```ts
+const handlers: Array<() => void> = []
+
+handlers.push(client.on('message', '/chat/*', handleChat))
+handlers.push(client.on('notification', '/alerts', handleAlert))
+
+// Cleanup all:
+for (const off of handlers) off()
+```
+
+## Best Practices
+
+- Use wildcard patterns sparingly — each incoming push message is checked against all wildcards (linear scan)
+- Prefer exact paths when the set of paths is known at compile time
+- Always store the unregister function to prevent memory leaks when handlers are no longer needed
+- Type the generic `<T>` on `on<T>()` to get typed `data` in the handler
+
+## Gotchas
+
+- Wildcard only works as a suffix (`/path/*`); it is NOT a glob or regex
+- The `params` field comes from the server (extracted by the Wooks router) — the client does NOT parse path params itself
+- If no handler matches a push message, it is silently dropped
+- Handlers are called synchronously in iteration order — a slow handler delays dispatch to subsequent handlers
+- The event type must match exactly — there is no wildcard for event types

package/skills/wooksjs-ws-client/reconnect.md

@@ -0,0 +1,145 @@
+# Reconnection — @wooksjs/ws-client
+
+> Auto-reconnection with configurable backoff, message queuing during disconnect, and subscription rehydration.
+
+## Concepts
+
+When `reconnect` is enabled, the client automatically attempts to re-establish the connection after an unexpected close. The reconnection system has three components:
+
+1. **ReconnectController** — manages backoff timing and attempt counting
+2. **MessageQueue** — buffers `send()` messages while disconnected
+3. **Subscription store** — remembers active subscriptions for auto-resubscribe
+
+On reconnection:
+
+1. Backoff delay elapses → new WebSocket connection attempt
+2. On open → reset attempt counter, flush queued messages, re-subscribe all stored subscriptions
+3. On failure → increment attempt, schedule next attempt (up to `maxRetries`)
+
+## API Reference
+
+### `WsClientReconnectOptions`
+
+```ts
+interface WsClientReconnectOptions {
+  enabled: boolean // must be true to enable
+  maxRetries?: number // default: Infinity
+  baseDelay?: number // ms (default: 1000)
+  maxDelay?: number // ms (default: 30000)
+  backoff?: 'linear' | 'exponential' // default: 'exponential'
+}
+```
+
+Shorthand: pass `reconnect: true` for defaults, `reconnect: false` to disable.
+
+### Backoff calculation
+
+**Exponential** (default): `delay = baseDelay * 2^attempt` (capped at `maxDelay`)
+
+- Attempt 0: 1000ms
+- Attempt 1: 2000ms
+- Attempt 2: 4000ms
+- Attempt 3: 8000ms
+- ... capped at 30000ms
+
+**Linear**: `delay = baseDelay * (attempt + 1)` (capped at `maxDelay`)
+
+- Attempt 0: 1000ms
+- Attempt 1: 2000ms
+- Attempt 2: 3000ms
+- ... capped at 30000ms
+
+### `client.onReconnect(handler): () => void`
+
+Register a handler called before each reconnection attempt. Receives the attempt number.
+
+```ts
+client.onReconnect((attempt) => {
+  console.log(`Reconnecting... attempt #${attempt}`)
+})
+```
+
+### Message queuing
+
+When disconnected and reconnect is enabled:
+
+- `send()` queues messages (serialized strings)
+- `call()` rejects immediately with code 503 (NOT queued)
+- On reconnect success, all queued messages are flushed in order
+
+### Auto-resubscribe
+
+Subscriptions created via `subscribe()` are stored as `Map<path, data>`. On successful reconnect, the client calls `call('subscribe', path, data)` for each stored subscription. Failures are silently caught and will retry on the next reconnect.
+
+## Common Patterns
+
+### Pattern: Basic reconnect
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', {
+  reconnect: true, // exponential backoff, unlimited retries
+})
+```
+
+### Pattern: Custom backoff
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', {
+  reconnect: {
+    enabled: true,
+    maxRetries: 10,
+    baseDelay: 500,
+    maxDelay: 15000,
+    backoff: 'linear',
+  },
+})
+```
+
+### Pattern: Reconnect with UI feedback
+
+```ts
+const client = createWsClient('wss://api.example.com/ws', { reconnect: true })
+
+client.onClose((code, reason) => {
+  showBanner('Connection lost, reconnecting...')
+})
+
+client.onReconnect((attempt) => {
+  updateBanner(`Reconnecting (attempt ${attempt})...`)
+})
+
+client.onOpen(() => {
+  hideBanner()
+})
+```
+
+### Pattern: Send during disconnection
+
+```ts
+// With reconnect enabled, messages are queued:
+client.send('message', '/chat/rooms/lobby', { text: 'hello' })
+// If disconnected, this will be sent when the connection is restored
+
+// RPCs are NOT queued — they reject immediately:
+try {
+  await client.call('rpc', '/users/me')
+} catch (err) {
+  // WsClientError(503, 'Not connected')
+}
+```
+
+## Best Practices
+
+- Use exponential backoff (default) for production — it reduces server load during outages
+- Set `maxRetries` for scenarios where giving up is better than infinite retry (e.g., auth failures)
+- Monitor `onReconnect` to update UI state
+- Use `send()` for messages that can tolerate delayed delivery; use `call()` only when you need an immediate response
+- Call `client.close()` to permanently stop reconnection — useful on logout or page unload
+
+## Gotchas
+
+- `client.close()` permanently disables reconnection — there is no way to re-enable it; create a new `WsClient` instead
+- Queued messages are lost if `client.close()` is called — the queue is cleared
+- Auto-resubscribe happens after `onOpen` handlers fire — your `onOpen` handler runs before subscriptions are re-established
+- The attempt counter resets to 0 on successful connection — if the connection drops again, backoff restarts from `baseDelay`
+- `call()` during disconnection always rejects, even with reconnect enabled — there is no "queue and resolve later" mode for RPCs

package/skills/wooksjs-ws-client/rpc.md

@@ -0,0 +1,134 @@
+# RPC & subscriptions — @wooksjs/ws-client
+
+> Request-response calls with correlation IDs, timeouts, and managed subscriptions with auto-resubscribe.
+
+## Concepts
+
+RPC in `@wooksjs/ws-client` uses correlation IDs to match requests with responses. When you call `client.call()`, the client:
+
+1. Generates an auto-incrementing numeric `id`
+2. Sends `{ event, path, data, id }` to the server
+3. Starts a timeout timer
+4. Returns a `Promise` that resolves/rejects when the server replies with the same `id`
+
+The server must include the `id` in its `WsReplyMessage` for the response to be matched.
+
+Subscriptions build on RPC — `subscribe()` calls `call('subscribe', path, data)` and remembers the subscription for auto-resubscribe on reconnect.
+
+## API Reference
+
+### `client.call<T>(event, path, data?): Promise<T>`
+
+Send a message with an auto-generated correlation ID and wait for the server's reply.
+
+- Rejects with `WsClientError(503)` if not connected
+- Rejects with `WsClientError(408)` on timeout (default: 10s)
+- Rejects with `WsClientError(code, message)` if the server replies with an `error`
+- Resolves with `reply.data` typed as `T`
+
+```ts
+interface User {
+  name: string
+  email: string
+}
+
+const user = await client.call<User>('rpc', '/users/me')
+```
+
+### `client.subscribe(path, data?): Promise<() => void>`
+
+Subscribe to a server path:
+
+1. Sends `{ event: 'subscribe', path, data, id }` via RPC
+2. Waits for server confirmation (reply)
+3. Stores `{ path, data }` for auto-resubscribe on reconnect
+4. Returns an unsubscribe function that:
+   - Removes the stored subscription
+   - Sends `{ event: 'unsubscribe', path }` (fire-and-forget) if still connected
+
+```ts
+const unsub = await client.subscribe('/chat/rooms/lobby')
+
+// Later:
+unsub()
+```
+
+### `RpcTracker` (internal)
+
+Tracks pending RPC calls. Not part of the public API but useful for understanding internals:
+
+- `generateId()` — auto-incrementing numeric IDs
+- `track(id, timeout)` — returns a Promise, starts timeout timer
+- `resolve(reply)` — matches `reply.id`, resolves or rejects based on `reply.error`
+- `rejectAll(code, message)` — called on disconnect/close, rejects all pending promises
+
+## Common Patterns
+
+### Pattern: Error handling
+
+```ts
+try {
+  const result = await client.call('rpc', '/protected/resource')
+} catch (err) {
+  if (err instanceof WsClientError) {
+    switch (err.code) {
+      case 403:
+        console.log('Forbidden')
+        break
+      case 404:
+        console.log('Not found')
+        break
+      case 408:
+        console.log('Timeout')
+        break
+      case 503:
+        console.log('Not connected')
+        break
+      default:
+        console.log(`Error ${err.code}: ${err.message}`)
+    }
+  }
+}
+```
+
+### Pattern: Multiple subscriptions
+
+```ts
+const unsubs: Array<() => void> = []
+
+unsubs.push(await client.subscribe('/chat/rooms/lobby'))
+unsubs.push(await client.subscribe('/chat/rooms/general'))
+unsubs.push(await client.subscribe('/notifications'))
+
+// Cleanup:
+for (const unsub of unsubs) unsub()
+```
+
+### Pattern: Typed RPC calls
+
+```ts
+interface CreateRoomResponse {
+  roomId: string
+  created: boolean
+}
+
+const response = await client.call<CreateRoomResponse>('rpc', '/rooms/create', {
+  name: 'My Room',
+})
+console.log(response.roomId)
+```
+
+## Best Practices
+
+- Set `rpcTimeout` to match your server's expected response time — 10s default is generous for most APIs
+- Always handle `WsClientError` in `.catch()` — unhandled rejections from timeout or disconnect are common
+- Use `subscribe()` for durable subscriptions that should survive reconnections; use `send()` for one-off events
+- Store unsubscribe functions and call them during cleanup to avoid server-side resource leaks
+
+## Gotchas
+
+- `call()` rejects immediately if not connected — it does NOT queue. Use `send()` for queued fire-and-forget
+- RPC IDs are auto-incrementing integers, not UUIDs — they reset to 1 on new `WsClient` instances
+- On disconnect, ALL pending RPCs are rejected with code 503 — there is no retry mechanism for in-flight calls
+- `subscribe()` rejects if the server's subscribe handler throws/rejects — the subscription is NOT stored in that case
+- Auto-resubscribe on reconnect silently swallows errors — check server logs if subscriptions seem lost