@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/components/socket-io/usage.md

@@ -1,20 +1,26 @@
-# Socket.IO -- Usage & Examples
+---
+title: Socket.IO Component - Usage & Examples
+description: Full setup steps, server-side usage, the client helper, and advanced patterns
+difficulty: intermediate
+---
 
-> Full setup steps, server-side usage patterns, client helper, and advanced examples.
+# Usage & Examples
 
-## Full Setup
+Task-oriented patterns for the Socket.IO component: full setup, sending messages from a service, using the standalone client helper, and reading the example app.
 
-### 1. Install Dependencies
+## Full setup
+
+### 1. Install dependencies
 
 ```bash
 # Core dependency (already included via @venizia/ignis)
 # ioredis is required for the Redis adapter
 
-# For Bun runtime only -- optional peer dependency
+# Bun runtime only - optional peer dependency
 bun add @socket.io/bun-engine
 ```
 
-### 2. Bind Required + Optional Services
+### 2. Bind required and optional services
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
@@ -51,7 +57,7 @@ export class Application extends BaseApplication {
     // 2. Authentication handler (required)
     const authenticateFn: TSocketIOAuthenticateFn = handshake => {
       const token = handshake.headers.authorization;
-      // Implement your auth logic -- JWT verification, session check, etc.
+      // Implement your auth logic: JWT verification, session check, etc.
       return !!token;
     };
 
@@ -59,11 +65,10 @@ export class Application extends BaseApplication {
       key: SocketIOBindingKeys.AUTHENTICATE_HANDLER,
     }).toValue(authenticateFn);
 
-    // 3. Room validation handler (optional -- joins rejected without this)
+    // 3. Room validation handler (optional - joins rejected without this)
     const validateRoomFn: TSocketIOValidateRoomFn = ({ socket, rooms }) => {
       // Return the rooms that the client is allowed to join
-      const allowedRooms = rooms.filter(room => room.startsWith('public-'));
-      return allowedRooms;
+      return rooms.filter(room => room.startsWith('public-'));
     };
 
     this.bind<TSocketIOValidateRoomFn>({
@@ -80,7 +85,7 @@ export class Application extends BaseApplication {
       key: SocketIOBindingKeys.CLIENT_CONNECTED_HANDLER,
     }).toValue(clientConnectedFn);
 
-    // 5. Register the component -- that's it!
+    // 5. Register the component - that's it!
     this.component(SocketIOComponent);
   }
 }
@@ -88,11 +93,18 @@ export class Application extends BaseApplication {
 
 ### 3. Why `autoConnect: false`
 
-- **The helper owns connection, not you.** `RedisSingleHelper` is created with `autoConnect: false` because the server helper internally calls `client.duplicate()` to create 3 independent Redis connections (pub, sub, emitter).
-- **Duplicates inherit `lazyConnect`, not connection state.** During `configure()`, the helper detects clients in `wait` status and explicitly calls `client.connect()` on each, then awaits all 3 to reach `ready` status before proceeding.
-- **This avoids a race.** If the parent connects before the duplicates exist, the duplicates can end up in an inconsistent state relative to the parent's connection lifecycle.
+The helper owns the connection timing, not you. `RedisSingleHelper` is created with `autoConnect: false` because the server helper calls `duplicateClient()` three times:
+
+| Duplicate | Role |
+|---|---|
+| `redisPub` | Redis adapter - publishes room broadcasts |
+| `redisSub` | Redis adapter - subscribes to room broadcasts |
+| `redisEmitter` | Redis emitter - direct cross-instance send |
+
+- **Duplicates inherit `lazyConnect`, not connection state.** During `configure()`, the helper checks each client's status. Any client still `wait`ing gets `connect()` called on it explicitly. The helper then waits for all three to reach `ready` before proceeding.
+- **This avoids a race.** If the parent connects before the duplicates exist, the duplicates can end up in a state inconsistent with the parent's connection lifecycle.
 
-### Redis Connection Alternatives
+### Redis connection alternatives
 
 `RedisSingleHelper` (single instance), `RedisClusterHelper` (cluster mode), and `RedisSentinelHelper` (Sentinel HA) all extend `AbstractRedisHelper` and satisfy the `IRedisHelper` interface the component validates against.
 
@@ -116,17 +128,14 @@ this.bind<RedisClusterHelper>({
 }).toValue(redisHelper);
 ```
 
-The internal `TRedisClient` type is `Redis | Cluster`, so both ioredis connection types are supported transparently.
+The internal `TRedisClient` type is `Redis | Cluster`, so both ioredis connection types work transparently.
 
 > [!NOTE]
-> Full defaults, the complete binding key table, and every system event/room constant are in the [API Reference](./api#configuration-reference).
+> Full defaults, the complete binding key table, and every system event/room constant are in the [Full Reference](./api#configuration-reference).
 
-## Server-Side Usage
+## Inject the helper in a service or controller
 
-### Inject and Use in Services/Controllers
-
-- **`SOCKET_IO_INSTANCE` does not exist at construction time.** The component binds `SocketIOServerHelper` from a post-start hook, which runs after the server starts -- well after every service/controller has already been constructed by the DI container.
-- **Use a lazy getter, not `@inject`.** Resolve the helper from the application container on first access, and cache it. `@inject`-ing `SOCKET_IO_INSTANCE` directly in a constructor will resolve to nothing.
+`SocketIOServerHelper` is bound to `SOCKET_IO_INSTANCE` inside a post-start hook. That hook runs after the server starts - well after the DI container already built every service and controller. Use a lazy getter that resolves the helper on first access. Never `@inject` it in a constructor.
 
 ```typescript
 import {
@@ -178,30 +187,27 @@ export class NotificationService extends BaseService {
   notifyRoom(opts: { room: string; message: string }) {
     this.io.send({
       destination: opts.room,
-      payload: {
-        topic: 'room:update',
-        data: { message: opts.message },
-      },
+      payload: { topic: 'room:update', data: { message: opts.message } },
     });
   }
 
   // Broadcast to all clients
   broadcastAnnouncement(opts: { message: string }) {
     this.io.send({
-      payload: {
-        topic: 'system:announcement',
-        data: { message: opts.message },
-      },
+      payload: { topic: 'system:announcement', data: { message: opts.message } },
     });
   }
 }
 ```
 
-## Client Helper
+- **Never `@inject` `SOCKET_IO_INSTANCE` in a constructor.** It is not bound yet at that point.
+- **`send()` reads via the Redis emitter.** It works even if the destination client is connected to a different server instance - see [`send()` in the Full Reference](./api#messaging-via-send).
 
-`SocketIOClientHelper` provides a managed Socket.IO client for connecting to Socket.IO servers -- useful for service-to-service communication, testing, or building relay services. It extends `BaseHelper` for scoped logging and wraps `socket.io-client` with authentication flow, lifecycle callbacks, and error-safe event subscription.
+## Use the client helper
 
-### Client Setup
+`SocketIOClientHelper` wraps `socket.io-client` with authentication flow, lifecycle callbacks, and error-safe event subscription. Use it when your process needs to connect *to* a Socket.IO server, not run one - service-to-service communication, testing, or relay services.
+
+### Client setup
 
 ```typescript
 import { SocketIOClientHelper } from '@venizia/ignis-helpers/socket-io';
@@ -211,9 +217,7 @@ const client = new SocketIOClientHelper({
   host: 'http://localhost:3000',
   options: {
     path: '/io',
-    extraHeaders: {
-      authorization: 'Bearer <token>',
-    },
+    extraHeaders: { authorization: 'Bearer <token>' },
   },
 
   // Lifecycle callbacks (all optional)
@@ -221,57 +225,52 @@ const client = new SocketIOClientHelper({
     console.log('Connected to server');
     client.authenticate();
   },
-  onDisconnected: (reason) => {
-    console.log('Disconnected:', reason);
-  },
-  onError: (error) => {
-    console.error('Connection error:', error);
-  },
-  onAuthenticated: () => {
-    console.log('Authentication successful');
-  },
-  onUnauthenticated: (message) => {
-    console.warn('Authentication failed:', message);
-  },
+  onDisconnected: reason => console.log('Disconnected:', reason),
+  onError: error => console.error('Connection error:', error),
+  onAuthenticated: () => console.log('Authentication successful'),
+  onUnauthenticated: message => console.warn('Authentication failed:', message),
 });
 ```
 
-- **The constructor calls `configure()` immediately.** `configure()` creates the `socket.io-client` `Socket` instance via `io(host, options)` and registers all internal event handlers (`connect`, `disconnect`, `connect_error`, `authenticated`, `unauthenticated`, `ping`).
-- **The socket does not connect on its own accord unless `autoConnect` allows it.** Call `client.connect()` explicitly when `autoConnect: false` is set in `options`; otherwise the socket connects automatically.
+- **The constructor calls `configure()` immediately.** It creates the `socket.io-client` `Socket` instance via `io(host, options)` and registers the internal event handlers. See the [full handler table](./api#client-configure-event-handlers) in the Full Reference.
+- **The socket connects on its own unless you disable it.** Set `autoConnect: false` in `options` and call `client.connect()` yourself when you're ready.
+
+#### `connect` vs `connection` event
+
+Client and server fire different event names for the same moment:
 
-#### `connect` vs `connection` Event
+| Side | Fires |
+|---|---|
+| Client (`socket.io-client`) | `connect` - no suffix |
+| Server (`socket.io`) | `connection` - with the suffix |
 
-- **Client and server use different event names.** `socket.io-client` fires `connect` (no suffix) when the connection is established; server-side `socket.io` fires `connection` (with the suffix). This is a Socket.IO convention, not IGNIS-specific.
-- **The two helpers mirror this.** The client helper registers on `'connect'`; the server helper registers on `SocketIOConstants.EVENT_CONNECT`, which equals `'connection'`.
+This is a Socket.IO convention, not an IGNIS one. The client helper listens on `'connect'`. The server helper listens on `SocketIOConstants.EVENT_CONNECT`, which equals `'connection'`.
 
-### Authentication Flow
+### Authentication flow
 
-After connecting, the client must emit `authenticate` to start the auth handshake. The server validates credentials from the socket handshake (headers, query params, `auth` object) and responds with either `authenticated` or `unauthenticated`.
+After connecting, the client must emit `authenticate` to start the handshake. The server validates credentials from the socket handshake (headers, query params, `auth` object) and responds with either `authenticated` or `unauthenticated`.
 
 ```typescript
-// Manual authentication after connection
 client.authenticate();
 ```
 
-`authenticate()` has two guard conditions -- both make the call a no-op with a warning log:
+`authenticate()` is a no-op with a warning log unless both conditions hold:
 
-1. The socket must be connected (`client.connected === true`)
-2. The current state must be `unauthorized` -- calling `authenticate()` while `authenticating` or already `authenticated` does nothing
+1. The socket is connected (`client.connected === true`).
+2. The current state is `unauthorized` - calling `authenticate()` while `authenticating` or already `authenticated` does nothing.
 
-#### Authentication Failure Details
+#### Authentication failure messages
 
-The server sends two distinct error messages depending on how `authenticateFn` fails:
+The server sends a different message depending on how `authenticateFn` failed. Both paths reset the client to `unauthorized`, emit `unauthenticated` with the message, and disconnect the socket after delivery (via `setImmediate`).
 
-| Failure Mode | Message | Cause |
-|-------------|---------|-------|
-| `authenticateFn` returned `false` | `"Invalid token to authenticate! Please login again!"` | Credentials were checked but deemed invalid |
-| `authenticateFn` threw an error | `"Failed to authenticate connection! Please login again!"` | An unexpected error occurred during validation |
+| Failure mode | Message |
+|---|---|
+| `authenticateFn` returned `false` | `"Invalid token to authenticate! Please login again!"` |
+| `authenticateFn` threw an error | `"Failed to authenticate connection! Please login again!"` |
 
-Both failure paths set the client state back to `unauthorized`, emit the `unauthenticated` event to the client with the message, and disconnect the socket after the message is delivered (via a `setImmediate` callback).
+### Event subscription
 
-### Event Subscription
-
-Subscribe to custom events with automatic error safety. Handlers are wrapped in a dual try-catch that catches both synchronous throws and asynchronous rejections:
+Handlers are wrapped in a dual try-catch. It catches both synchronous throws and asynchronous rejections, so a broken handler never crashes the client.
 
 ```typescript
 // Subscribe to a single event
@@ -282,27 +281,24 @@ client.subscribe({
   },
 });
 
-// Subscribe with duplicate detection disabled
+// ignoreDuplicate: false stacks a second handler for the same event
 client.subscribe({
   event: 'chat:message',
-  handler: (data) => { /* second handler */ },
-  ignoreDuplicate: false, // default: true -- set to false to allow multiple handlers
+  handler: data => { /* second handler */ },
+  ignoreDuplicate: false,
 });
 
 // Subscribe to multiple events at once
 client.subscribeMany({
   events: {
-    'user:joined': (data) => console.log('User joined:', data),
-    'user:left': (data) => console.log('User left:', data),
-    'room:updated': (data) => console.log('Room updated:', data),
+    'user:joined': data => console.log('User joined:', data),
+    'user:left': data => console.log('User left:', data),
+    'room:updated': data => console.log('Room updated:', data),
   },
 });
 ```
 
-#### Deduplication Behavior
-
-- **The default (`ignoreDuplicate: true`) checks `socket.hasListeners(event)` first.** If listeners already exist for the event, `subscribe()` is a no-op and logs an info message.
-- **Set `ignoreDuplicate: false` to stack handlers.** This allows multiple handlers to run for the same event.
+The default (`ignoreDuplicate: true`) checks `socket.hasListeners(event)` first. If a listener already exists, `subscribe()` is a no-op that logs an info message. Set `ignoreDuplicate: false` to stack handlers instead.
 
 ### Unsubscribing
 
@@ -317,7 +313,7 @@ client.unsubscribe({ event: 'chat:message', handler: myHandler });
 client.unsubscribeMany({ events: ['chat:message', 'user:joined', 'room:updated'] });
 ```
 
-### Emitting Events
+### Emitting events
 
 ```typescript
 client.emit({
@@ -330,9 +326,9 @@ client.emit({
 });
 ```
 
-`emit()` throws if the socket is not connected or if no `topic` is provided. Unlike `send()` on the server helper, this method does **not** silently swallow missing-argument errors.
+`emit()` throws if the socket is not connected or if `topic` is missing. The server helper's `send()` silently drops a message with a missing field - `emit()` never does that. It always throws instead.
 
-### Room Management
+### Room management
 
 ```typescript
 // Request to join rooms (server validates via validateRoomFn)
@@ -342,9 +338,9 @@ client.joinRooms({ rooms: ['chat-room-1', 'notifications'] });
 client.leaveRooms({ rooms: ['chat-room-1'] });
 ```
 
-Both methods emit Socket.IO events (`join` / `leave`) to the server -- the actual join/leave happens server-side. If the socket is not connected, the call is a no-op with a warning log.
+Both methods emit a Socket.IO event to the server: `join` or `leave`. The actual join or leave happens server-side. If the socket isn't connected, the call is a no-op with a warning log.
 
-### Connection Management
+### Connection management
 
 ```typescript
 // Manually connect (useful when autoConnect: false in options)
@@ -363,35 +359,30 @@ const rawSocket = client.getSocketClient();
 ### Shutdown
 
 ```typescript
-// Clean shutdown: removes all listeners, disconnects, resets state
 client.shutdown();
 ```
 
 `shutdown()` does three things, in order:
 
-1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks
-2. Disconnects if still connected
-3. Resets state to `unauthorized`
+1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks.
+2. Disconnects if still connected.
+3. Resets state to `unauthorized`.
 
-## Advanced Usage
+## Run the complete example
 
-### Complete Example
-
-A full working example is available at `examples/socket-io-test/`. It demonstrates:
+A full working example lives at `examples/socket-io-test/`.
 
 | Feature | Implementation |
-|---------|---------------|
-| Application setup | `src/application.ts` -- bindings, component registration, graceful shutdown |
-| REST endpoints | `src/controllers/socket-test.controller.ts` -- 9 endpoints for Socket.IO management |
-| Event handling | `src/services/socket-event.service.ts` -- chat, echo, room management |
-| Automated test client | `client.ts` -- 15+ test cases covering all features |
-
-#### REST API Endpoints
+|---|---|
+| Application setup | `src/application.ts` - bindings, component registration, graceful shutdown |
+| REST endpoints | `src/controllers/socket-test.controller.ts` - 9 endpoints for Socket.IO management |
+| Event handling | `src/services/socket-event.service.ts` - chat, echo, room management |
+| Automated test client | `client.ts` - 15+ test cases covering all features |
 
-The example provides a REST API for managing Socket.IO:
+### REST API endpoints
 
 | Method | Path | Description |
-|--------|------|-------------|
+|---|---|---|
 | `GET` | `/socket/info` | Server status + connected client count |
 | `GET` | `/socket/clients` | List all connected client IDs |
 | `GET` | `/socket/health` | Health check (is SocketIO ready?) |
@@ -402,38 +393,37 @@ The example provides a REST API for managing Socket.IO:
 | `POST` | `/socket/client/{clientId}/leave` | Remove client from <code v-pre>{{ rooms: string[] }}</code> |
 | `GET` | `/socket/client/{clientId}/rooms` | List rooms a client belongs to |
 
-#### Running the Example
+### Running the example
 
 ```bash
 # Start the server
 cd examples/socket-io-test
 bun run server:dev
 
-# In another terminal -- run automated tests
+# In another terminal - run automated tests
 bun client.ts
 ```
 
-The automated client tests the following features:
+The automated client exercises:
 
-- Authentication (valid and invalid tokens)
+- Authentication with valid and invalid tokens
 - Ping/pong keepalive
 - Room join/leave with validation
 - Client-to-client messaging
-- Room broadcasting
-- Global broadcasting
-- REST API for Socket.IO management
+- Room and global broadcasting
+- The REST API
 - Graceful disconnection
 
-Review the example code to understand production-ready patterns for:
+Read the example for these production-ready patterns:
 
-- Binding multiple handlers in a single `setupSocketIO()` method
-- Lazy getter pattern for accessing `SocketIOServerHelper` in services
+- Binding multiple handlers in one `setupSocketIO()` method
+- The lazy getter pattern for `SocketIOServerHelper`
 - Custom event registration via `CLIENT_CONNECTED_HANDLER`
-- Room validation logic preventing unauthorized room access
-- Graceful shutdown sequence in `application.stop()`
+- Room validation that blocks unauthorized rooms
+- A graceful shutdown sequence in `application.stop()`
 
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Quick reference, import paths, use cases
-- [API Reference](./api) -- Architecture, configuration reference, method signatures, internals, types
-- [Error Reference](./errors) -- Error conditions and troubleshooting
+- [Overview](./) - quick start, imports, common configuration tasks
+- [Full Reference](./api) - architecture, configuration reference, method signatures, internals, types
+- [Error Reference](./errors) - error conditions and troubleshooting