@moostjs/event-ws 0.6.0

package/skills/moostjs-event-ws/request-data.md

@@ -0,0 +1,185 @@
+# Request data — @moostjs/event-ws
+
+> Resolver decorators for extracting message data, connection info, and route parameters from WebSocket events.
+
+## Concepts
+
+Moost WS provides parameter decorators that resolve values from the WebSocket event context. These decorators are applied to handler method arguments and participate in the Moost pipes pipeline (resolve, transform, validate).
+
+There are two categories:
+- **Message decorators** — only available in `@Message` handlers
+- **Connection decorators** — available in all handler types (`@Message`, `@Connect`, `@Disconnect`)
+
+Additionally, Wooks composable functions (`useWsMessage()`, `useWsConnection()`, etc.) can be called directly inside handler bodies.
+
+## API Reference
+
+### `@MessageData()`
+
+Resolves the parsed message payload (the `data` field from the client message).
+
+```ts
+@Message('message', '/chat/:room')
+onMessage(@MessageData() data: { from: string; text: string }) {
+  console.log(`${data.from}: ${data.text}`)
+}
+```
+
+**Returns:** `unknown` (typed by the parameter's type annotation)
+**Available in:** `@Message` only
+
+### `@RawMessage()`
+
+Resolves the raw message before JSON parsing.
+
+```ts
+@Message('debug', '/raw')
+onRaw(@RawMessage() raw: Buffer | string) {
+  console.log('Raw message:', raw.toString())
+}
+```
+
+**Returns:** `Buffer | string`
+**Available in:** `@Message` only
+
+### `@MessageId()`
+
+Resolves the message correlation ID. `undefined` for fire-and-forget, `string | number` for RPC calls.
+
+```ts
+@Message('query', '/info')
+info(@MessageId() messageId: string | number | undefined) {
+  console.log('Correlation ID:', messageId)
+  return { timestamp: Date.now() }
+}
+```
+
+**Returns:** `string | number | undefined`
+**Available in:** `@Message` only
+
+### `@MessageType()`
+
+Resolves the event type string from the message.
+
+```ts
+@Message('*', '/log')
+onAny(@MessageType() event: string) {
+  console.log('Event type:', event)
+}
+```
+
+**Returns:** `string`
+**Available in:** `@Message` only
+
+### `@MessagePath()`
+
+Resolves the concrete message path (after routing).
+
+```ts
+@Message('action', '/game/:id')
+onAction(@MessagePath() path: string) {
+  console.log('Message path:', path) // e.g. "/game/42"
+}
+```
+
+**Returns:** `string`
+**Available in:** `@Message` only
+
+### `@ConnectionId()`
+
+Resolves the unique connection identifier (UUID).
+
+```ts
+@Connect()
+onConnect(@ConnectionId() id: string) {
+  console.log(`Connected: ${id}`)
+}
+
+@Message('ping', '/ping')
+ping(@ConnectionId() id: string) {
+  return { pong: true, connectionId: id }
+}
+
+@Disconnect()
+onDisconnect(@ConnectionId() id: string) {
+  console.log(`Disconnected: ${id}`)
+}
+```
+
+**Returns:** `string`
+**Available in:** All handlers (`@Message`, `@Connect`, `@Disconnect`)
+
+### `@Param(name: string)`
+
+Resolves a named route parameter from the message path. Same decorator as HTTP routing (re-exported from `moost`).
+
+```ts
+@Message('message', ':room')
+onMessage(@Param('room') room: string, @MessageData() data: { text: string }) {
+  console.log(`[${room}] ${data.text}`)
+}
+```
+
+**Returns:** `string`
+**Available in:** `@Message` only
+
+### `@Params()`
+
+Resolves all route parameters as an object. Re-exported from `moost`.
+
+```ts
+@Message('move', '/game/:gameId/player/:playerId')
+onMove(@Params() params: { gameId: string; playerId: string }) {
+  console.log(params) // { gameId: '1', playerId: 'alice' }
+}
+```
+
+**Returns:** `Record<string, string>`
+**Available in:** `@Message` only
+
+## Using Composables Directly
+
+You can also call Wooks composables inside handler bodies instead of using decorators:
+
+```ts
+import { useWsMessage, useWsConnection } from '@moostjs/event-ws'
+
+@Message('echo', '/echo')
+echo() {
+  const { data, id, path, event } = useWsMessage()
+  const { id: connId, send } = useWsConnection()
+  return data
+}
+```
+
+## HTTP Context in WS Handlers
+
+In HTTP-integrated mode, HTTP composables from the upgrade request are available:
+
+```ts
+import { Connect, ConnectionId } from '@moostjs/event-ws'
+import { useHeaders, useRequest } from '@wooksjs/event-http'
+
+@Connect()
+onConnect(@ConnectionId() id: string) {
+  const { url } = useRequest()
+  const headers = useHeaders()
+  console.log('Upgrade URL:', url)
+  console.log('User-Agent:', headers['user-agent'])
+}
+```
+
+HTTP composables are read-only — response composables like `useResponse()` are not available in WS handlers.
+
+## Summary
+
+| Decorator | Returns | Available In |
+|-----------|---------|-------------|
+| `@MessageData()` | Parsed message payload | `@Message` |
+| `@RawMessage()` | Raw `Buffer \| string` | `@Message` |
+| `@MessageId()` | Correlation ID `string \| number \| undefined` | `@Message` |
+| `@MessageType()` | Event type `string` | `@Message` |
+| `@MessagePath()` | Concrete message path `string` | `@Message` |
+| `@ConnectionId()` | Connection UUID `string` | All handlers |
+| `@Param(name)` | Named route parameter `string` | `@Message` |
+| `@Params()` | All route parameters `object` | `@Message` |

package/skills/moostjs-event-ws/rooms.md

@@ -0,0 +1,196 @@
+# Rooms & broadcasting — @moostjs/event-ws
+
+> Room management, broadcasting, direct sends, server-wide queries, and multi-instance scaling.
+
+## Concepts
+
+Rooms group WebSocket connections for targeted broadcasting. A connection can join multiple rooms. Room names are strings — by default, the current message path is used as the room name.
+
+Three composables handle communication:
+- `useWsRooms()` — room-scoped operations (join, leave, broadcast). Available in message handlers only.
+- `useWsConnection()` — direct send to the current connection. Available in all handlers.
+- `useWsServer()` — server-wide operations (broadcast to all, query connections). Available in any context.
+
+## API Reference
+
+### `useWsRooms()`
+
+Room management for the current connection. Only available in `@Message` handlers.
+
+```ts
+const { join, leave, broadcast, rooms } = useWsRooms()
+```
+
+| Method | Description |
+|--------|-------------|
+| `join(room?)` | Join a room (default: current message path) |
+| `leave(room?)` | Leave a room (default: current message path) |
+| `broadcast(event, data?, opts?)` | Broadcast to room members |
+| `rooms()` | List rooms this connection has joined (`string[]`) |
+
+**Broadcast options:**
+```ts
+broadcast('message', data, {
+  room: '/custom-room',  // target a different room (default: current path)
+  excludeSelf: false,     // include the sender (default: true)
+})
+```
+
+### `useWsConnection()`
+
+Access the current WebSocket connection. Available in all handler types.
+
+```ts
+const { id, send, close } = useWsConnection()
+```
+
+| Property/Method | Description |
+|----------------|-------------|
+| `id` | Connection UUID (`string`) |
+| `send(event, path, data?, params?)` | Push a message to this client |
+| `close(code?, reason?)` | Close the connection |
+| `context` | The connection `EventContext` |
+
+### `useWsServer()`
+
+Server-wide operations. Available in any context.
+
+```ts
+const server = useWsServer()
+```
+
+| Method | Description |
+|--------|-------------|
+| `broadcast(event, path, data?)` | Broadcast to ALL connected clients |
+| `connections()` | Get all connections (`Map<string, WsConnection>`) |
+| `roomConnections(room)` | Get connections in a room (`Set<WsConnection>`) |
+| `getConnection(id)` | Get connection by ID (`WsConnection \| undefined`) |
+
+### `currentConnection()`
+
+Returns the connection `EventContext` regardless of context level:
+- In `@Connect`/`@Disconnect`: returns `current()` directly
+- In `@Message`: returns `current().parent` (the connection context)
+
+## Common Patterns
+
+### Pattern: Join a room and broadcast
+
+```ts
+@Controller('chat')
+export class ChatController {
+  @Message('join', ':room')
+  join(
+    @Param('room') room: string,
+    @ConnectionId() id: string,
+    @MessageData() data: { name: string },
+  ) {
+    const { join, broadcast, rooms } = useWsRooms()
+    join() // joins room matching current path (e.g. "/chat/general")
+    broadcast('system', { text: `${data.name} joined` })
+    return { joined: true, room, rooms: rooms() }
+  }
+}
+```
+
+### Pattern: Broadcast a message to a room
+
+```ts
+@Message('message', ':room')
+onMessage(@MessageData() data: { from: string; text: string }) {
+  const { broadcast } = useWsRooms()
+  broadcast('message', { from: data.from, text: data.text })
+  // all room members except sender receive the message
+}
+```
+
+### Pattern: Direct send to current connection
+
+```ts
+@Message('notify', '/self')
+notify() {
+  const { send } = useWsConnection()
+  send('notification', '/alerts', { text: 'Just for you' })
+}
+```
+
+### Pattern: Server-wide broadcast
+
+```ts
+@Message('admin', '/announce')
+announce(@MessageData() data: { text: string }) {
+  const server = useWsServer()
+  server.broadcast('announcement', '/announce', { text: data.text })
+  return { announced: true }
+}
+```
+
+### Pattern: Send to a specific connection by ID
+
+```ts
+@Message('dm', '/direct')
+directMessage(@MessageData() data: { targetId: string; text: string }) {
+  const server = useWsServer()
+  const target = server.getConnection(data.targetId)
+  if (target) {
+    target.send('dm', '/direct', { text: data.text })
+  }
+}
+```
+
+## Multi-Instance Broadcasting
+
+For horizontal scaling, implement `WsBroadcastTransport` to relay room broadcasts across instances:
+
+```ts
+import type { WsBroadcastTransport } from '@moostjs/event-ws'
+
+class RedisBroadcastTransport implements WsBroadcastTransport {
+  publish(channel: string, payload: string) {
+    redis.publish(channel, payload)
+  }
+  subscribe(channel: string, handler: (payload: string) => void) {
+    redis.subscribe(channel, handler)
+  }
+  unsubscribe(channel: string) {
+    redis.unsubscribe(channel)
+  }
+}
+```
+
+Pass it in adapter options:
+
+```ts
+const ws = new MoostWs({
+  httpApp: http.getHttpApp(),
+  wooksWs: {
+    broadcastTransport: new RedisBroadcastTransport(),
+  },
+})
+```
+
+Channels follow the pattern `ws:room:<room-path>`.
+
+### WsBroadcastTransport Interface
+
+```ts
+interface WsBroadcastTransport {
+  publish(channel: string, payload: string): void | Promise<void>
+  subscribe(channel: string, handler: (payload: string) => void): void | Promise<void>
+  unsubscribe(channel: string): void | Promise<void>
+}
+```
+
+## Best Practices
+
+- Let rooms auto-clean on disconnect — don't manually leave in `@Disconnect` handlers
+- Use `excludeSelf: true` (default) to prevent echo in chat-like scenarios
+- Use `useWsServer()` sparingly — prefer room-scoped broadcasts over server-wide
+- For large-scale deployments, implement `WsBroadcastTransport` with Redis/NATS
+
+## Gotchas
+
+- `useWsRooms()` throws if called outside a message context (e.g. inside `@Connect`)
+- `join()` without arguments uses the current message path as the room name, including the controller prefix
+- `useWsConnection().send()` silently drops messages if the socket is not in OPEN state
+- Broadcast `excludeId` only prevents echo on the originating server instance — the same user's other connections still receive it

package/skills/moostjs-event-ws/routing.md

@@ -0,0 +1,115 @@
+# Routing — @moostjs/event-ws
+
+> Event+path routing, controller prefixes, parametric routes, and wildcards.
+
+## Concepts
+
+WebSocket message routing uses a two-dimensional scheme: messages are matched by both **event type** and **path**. This is powered by the same Wooks router used for HTTP routes.
+
+Every client message carries: `{ event: "message", path: "/chat/general", data: {...} }`
+
+The `@Message` decorator matches both dimensions. The `event` must match exactly. The `path` supports parametric patterns (`:param`) and wildcards (`*`).
+
+## Routing Rules
+
+### Event + Path
+
+```ts
+@Message('message', '/chat/general')
+onMessage(@MessageData() data: { text: string }) {
+  // matches event="message" at path="/chat/general"
+}
+```
+
+### Controller Prefixes
+
+The `@Controller` prefix is prepended to handler paths:
+
+```ts
+@Controller('game')
+export class GameController {
+  @Message('move', 'board/:id')
+  // effective path: /game/board/:id
+  onMove(@Param('id') id: string) { /* ... */ }
+}
+```
+
+Nested controllers with `@ImportController` compose prefixes:
+
+```ts
+@Controller('v2')
+export class V2Controller {
+  @ImportController(() => GameController)
+  game!: GameController
+  // GameController routes become /v2/game/board/:id
+}
+```
+
+### Parametric Routes
+
+Use `:param` syntax for path parameters:
+
+```ts
+@Controller('chat')
+export class ChatController {
+  @Message('join', ':room')
+  join(@Param('room') room: string) { /* ... */ }
+
+  @Message('dm', ':sender/:receiver')
+  dm(
+    @Param('sender') sender: string,
+    @Param('receiver') receiver: string,
+  ) { /* ... */ }
+}
+```
+
+Client message `{ event: "dm", path: "/chat/alice/bob" }` resolves `sender="alice"`, `receiver="bob"`.
+
+### All Route Parameters
+
+Use `@Params()` to get all parameters as an object:
+
+```ts
+import { Params } from 'moost'
+
+@Message('action', ':type/:id')
+handle(@Params() params: { type: string; id: string }) {
+  console.log(params) // { type: 'move', id: '42' }
+}
+```
+
+### Wildcards
+
+```ts
+@Message('log', '/events/*')
+handleAllEvents(@Param('*') subPath: string) {
+  // matches /events/user/login, /events/system/error, etc.
+}
+```
+
+### Path Omission
+
+When `path` is omitted, the method name becomes the path:
+
+```ts
+@Controller('api')
+export class ApiController {
+  @Message('query')
+  status() {
+    // effective path: /api/status
+    return { ok: true }
+  }
+}
+```
+
+## Best Practices
+
+- Use controller prefixes to namespace related handlers
+- Prefer explicit `path` argument over relying on method name inference for clarity
+- Use parametric routes (`:room`) rather than separate handlers per room
+
+## Gotchas
+
+- Event matching is exact — no wildcard support on the event field itself
+- Path parameters are always strings, even if they look like numbers
+- Leading slash in `@Message` path is optional — `':room'` and `'/:room'` behave the same when composed with a controller prefix

package/skills/moostjs-event-ws/testing.md

@@ -0,0 +1,209 @@
+# Testing — @moostjs/event-ws
+
+> Unit-testing WebSocket handlers with mock contexts using prepareTestWsMessageContext and prepareTestWsConnectionContext.
+
+## Concepts
+
+`@moostjs/event-ws` re-exports test helpers from `@wooksjs/event-ws` that create mock event contexts for unit-testing handlers and composables without starting a real server.
+
+Two context factories match the two context layers:
+1. **`prepareTestWsConnectionContext`** — for `@Connect`/`@Disconnect` handler logic
+2. **`prepareTestWsMessageContext`** — for `@Message` handler logic (includes a parent connection context)
+
+Both return a **runner function** `<T>(cb: () => T) => T` that executes a callback inside a fully initialized event context.
+
+## API Reference
+
+### `prepareTestWsMessageContext(options)`
+
+Creates a message context with a parent connection context. Both contexts are fully seeded.
+
+```ts
+interface TTestWsMessageContext {
+  event: string                                 // required — message event type
+  path: string                                  // required — message route path
+  data?: unknown                                // parsed message payload
+  messageId?: string | number                   // correlation ID
+  rawMessage?: Buffer | string                  // raw message before parsing
+  id?: string                                   // connection ID (default: 'test-conn-id')
+  params?: Record<string, string | string[]>    // pre-set route parameters
+  parentCtx?: EventContext                      // optional parent context (e.g. HTTP)
+}
+```
+
+**Returns:** `<T>(cb: (...a: any[]) => T) => T`
+
+```ts
+import { prepareTestWsMessageContext, useWsMessage, useWsConnection } from '@moostjs/event-ws'
+
+const runInCtx = prepareTestWsMessageContext({
+  event: 'message',
+  path: '/chat/general',
+  data: { from: 'Alice', text: 'Hello!' },
+  messageId: 1,
+})
+
+runInCtx(() => {
+  const { data, id, path, event } = useWsMessage<{ from: string; text: string }>()
+  expect(data.from).toBe('Alice')
+  expect(id).toBe(1)
+})
+```
+
+### `prepareTestWsConnectionContext(options?)`
+
+Creates a connection context for testing connection lifecycle handlers.
+
+```ts
+interface TTestWsConnectionContext {
+  id?: string                                   // connection ID (default: 'test-conn-id')
+  params?: Record<string, string | string[]>    // pre-set route parameters
+  parentCtx?: EventContext                      // optional parent context
+}
+```
+
+**Returns:** `<T>(cb: (...a: any[]) => T) => T`
+
+```ts
+import { prepareTestWsConnectionContext, useWsConnection } from '@moostjs/event-ws'
+
+const runInCtx = prepareTestWsConnectionContext({ id: 'conn-456' })
+
+runInCtx(() => {
+  const { id } = useWsConnection()
+  expect(id).toBe('conn-456')
+})
+```
+
+## Common Patterns
+
+### Pattern: Testing message data access
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { prepareTestWsMessageContext, useWsMessage } from '@moostjs/event-ws'
+
+describe('ChatController', () => {
+  it('should access message data', () => {
+    const runInCtx = prepareTestWsMessageContext({
+      event: 'message',
+      path: '/chat/general',
+      data: { from: 'Alice', text: 'Hello!' },
+      messageId: 1,
+    })
+
+    runInCtx(() => {
+      const { data, id, path, event } = useWsMessage<{ from: string; text: string }>()
+      expect(data.from).toBe('Alice')
+      expect(data.text).toBe('Hello!')
+      expect(id).toBe(1)
+      expect(path).toBe('/chat/general')
+      expect(event).toBe('message')
+    })
+  })
+})
+```
+
+### Pattern: Testing with route parameters
+
+```ts
+import { prepareTestWsMessageContext } from '@moostjs/event-ws'
+import { useRouteParams } from '@wooksjs/event-core'
+
+it('should resolve route params', () => {
+  const runInCtx = prepareTestWsMessageContext({
+    event: 'join',
+    path: '/chat/rooms/lobby',
+    params: { room: 'lobby' },
+    data: { name: 'Alice' },
+  })
+
+  runInCtx(() => {
+    const { get } = useRouteParams<{ room: string }>()
+    expect(get('room')).toBe('lobby')
+  })
+})
+```
+
+### Pattern: Testing connection ID
+
+```ts
+it('should access connection id in message context', () => {
+  const runInCtx = prepareTestWsMessageContext({
+    event: 'join',
+    path: '/chat/general',
+    data: { name: 'Alice' },
+    id: 'conn-123',
+  })
+
+  runInCtx(() => {
+    const { id } = useWsConnection()
+    expect(id).toBe('conn-123')
+  })
+})
+```
+
+### Pattern: Testing with HTTP parent context
+
+For handlers that access HTTP composables from the upgrade request:
+
+```ts
+import { EventContext } from '@wooksjs/event-core'
+import { prepareTestWsMessageContext, currentConnection } from '@moostjs/event-ws'
+
+it('should have access to parent HTTP context', () => {
+  const httpCtx = new EventContext({ logger: console as any })
+
+  const runInCtx = prepareTestWsMessageContext({
+    event: 'test',
+    path: '/test',
+    parentCtx: httpCtx,
+  })
+
+  runInCtx(() => {
+    const connCtx = currentConnection()
+    expect(connCtx.parent).toBe(httpCtx)
+  })
+})
+```
+
+### Pattern: Testing handler functions directly
+
+Extract handler logic into testable functions:
+
+```ts
+import { prepareTestWsMessageContext, useWsRooms } from '@moostjs/event-ws'
+
+function handleJoin(room: string, name: string) {
+  const { join, broadcast, rooms } = useWsRooms()
+  join()
+  broadcast('system', { text: `${name} joined` })
+  return { joined: true, room, rooms: rooms() }
+}
+
+it('should join a room and return room list', () => {
+  const runInCtx = prepareTestWsMessageContext({
+    event: 'join',
+    path: '/chat/general',
+    data: { name: 'Alice' },
+  })
+
+  const result = runInCtx(() => handleJoin('general', 'Alice'))
+  expect(result.joined).toBe(true)
+  expect(result.room).toBe('general')
+})
+```
+
+## Best Practices
+
+- Use test helpers rather than manually constructing `EventContext`
+- Keep handler logic testable by extracting business logic into composable-using functions
+- Test edge cases with different message data, missing fields, and error conditions
+- Use `parentCtx` to simulate HTTP-integrated mode
+- Default connection ID is `'test-conn-id'` — override with the `id` option when needed
+
+## Gotchas
+
+- `useWsRooms()` and `useWsServer()` depend on adapter state — for full integration testing with rooms and broadcasting, you may need to set up `WsRoomManager` manually
+- The runner function is synchronous — wrap async handler logic in a returned promise if needed
+- Route parameters must be pre-set via the `params` option — the test context doesn't run the router