@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/tutorials/realtime-chat.md

@@ -1,6 +1,6 @@
 # Building a Real-Time Chat Application
 
-This tutorial shows you how to build a real-time chat application with rooms, direct messages, typing indicators, and presence using Socket.IO — powered by the `SocketIOComponent` and `SocketIOServerHelper`.
+This tutorial shows you how to build a real-time chat application with rooms, direct messages, typing indicators, and presence using Socket.IO - powered by the `SocketIOComponent` and `SocketIOServerHelper`.
 
 **What You'll Build:**
 
@@ -29,7 +29,7 @@ bun add hono @hono/zod-openapi @venizia/ignis @venizia/ignis-helpers
 bun add drizzle-orm drizzle-zod pg
 bun add -d typescript @types/bun @venizia/dev-configs drizzle-kit @types/pg
 
-# For Bun runtime — Socket.IO engine
+# For Bun runtime - Socket.IO engine
 bun add @socket.io/bun-engine
 ```
 
@@ -46,10 +46,10 @@ Models in IGNIS combine Drizzle ORM schemas with Entity classes.
 // src/models/user.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, varchar, text, timestamp, boolean } from 'drizzle-orm/pg-core';
@@ -64,18 +64,13 @@ export const userTable = pgTable('User', {
   lastSeenAt: timestamp('last_seen_at'),
 });
 
-export const userRelations = createRelations({
-  source: userTable,
-  relations: [],
-});
-
 export type TUserSchema = typeof userTable;
 export type TUser = TTableObject<TUserSchema>;
 
 @model({ type: 'entity' })
 export class User extends BaseEntity<typeof User.schema> {
   static override schema = userTable;
-  static override relations = () => userRelations.definitions;
+  static override relations = (): TRelationConfig[] => [];
   static override TABLE_NAME = 'User';
 }
 ```
@@ -86,10 +81,11 @@ export class User extends BaseEntity<typeof User.schema> {
 // src/models/room.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, varchar, text, timestamp, boolean } from 'drizzle-orm/pg-core';
@@ -113,22 +109,6 @@ export const roomMemberTable = pgTable('RoomMember', {
   lastReadAt: timestamp('last_read_at'),
 });
 
-export const roomRelations = createRelations({
-  source: roomTable,
-  relations: [
-    { type: 'one', name: 'creator', target: () => userTable, fields: ['createdBy'], references: ['id'] },
-    { type: 'many', name: 'members', target: () => roomMemberTable, fields: ['id'], references: ['roomId'] },
-  ],
-});
-
-export const roomMemberRelations = createRelations({
-  source: roomMemberTable,
-  relations: [
-    { type: 'one', name: 'room', target: () => roomTable, fields: ['roomId'], references: ['id'] },
-    { type: 'one', name: 'user', target: () => userTable, fields: ['userId'], references: ['id'] },
-  ],
-});
-
 export type TRoomSchema = typeof roomTable;
 export type TRoom = TTableObject<TRoomSchema>;
 export type TRoomMemberSchema = typeof roomMemberTable;
@@ -137,14 +117,44 @@ export type TRoomMember = TTableObject<TRoomMemberSchema>;
 @model({ type: 'entity' })
 export class Room extends BaseEntity<typeof Room.schema> {
   static override schema = roomTable;
-  static override relations = () => roomRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'creator',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: { fields: [roomTable.createdBy], references: [userTable.id] },
+    },
+    {
+      name: 'members',
+      type: RelationTypes.MANY,
+      schema: roomMemberTable,
+      metadata: { fields: [roomTable.id], references: [roomMemberTable.roomId] },
+    },
+  ];
+
   static override TABLE_NAME = 'Room';
 }
 
 @model({ type: 'entity' })
 export class RoomMember extends BaseEntity<typeof RoomMember.schema> {
   static override schema = roomMemberTable;
-  static override relations = () => roomMemberRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'room',
+      type: RelationTypes.ONE,
+      schema: roomTable,
+      metadata: { fields: [roomMemberTable.roomId], references: [roomTable.id] },
+    },
+    {
+      name: 'user',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: { fields: [roomMemberTable.userId], references: [userTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'RoomMember';
 }
 ```
@@ -155,10 +165,11 @@ export class RoomMember extends BaseEntity<typeof RoomMember.schema> {
 // src/models/message.model.ts
 import {
   BaseEntity,
-  createRelations,
   generateIdColumnDefs,
   generateTzColumnDefs,
   model,
+  RelationTypes,
+  TRelationConfig,
   TTableObject,
 } from '@venizia/ignis';
 import { pgTable, text, timestamp, varchar } from 'drizzle-orm/pg-core';
@@ -189,22 +200,6 @@ export const directMessageTable = pgTable('DirectMessage', {
   deletedAt: timestamp('deleted_at'),
 });
 
-export const messageRelations = createRelations({
-  source: messageTable,
-  relations: [
-    { type: 'one', name: 'room', target: () => roomTable, fields: ['roomId'], references: ['id'] },
-    { type: 'one', name: 'sender', target: () => userTable, fields: ['senderId'], references: ['id'] },
-  ],
-});
-
-export const directMessageRelations = createRelations({
-  source: directMessageTable,
-  relations: [
-    { type: 'one', name: 'sender', target: () => userTable, fields: ['senderId'], references: ['id'] },
-    { type: 'one', name: 'receiver', target: () => userTable, fields: ['receiverId'], references: ['id'] },
-  ],
-});
-
 export type TMessageSchema = typeof messageTable;
 export type TMessage = TTableObject<TMessageSchema>;
 export type TDirectMessageSchema = typeof directMessageTable;
@@ -213,14 +208,44 @@ export type TDirectMessage = TTableObject<TDirectMessageSchema>;
 @model({ type: 'entity' })
 export class Message extends BaseEntity<typeof Message.schema> {
   static override schema = messageTable;
-  static override relations = () => messageRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'room',
+      type: RelationTypes.ONE,
+      schema: roomTable,
+      metadata: { fields: [messageTable.roomId], references: [roomTable.id] },
+    },
+    {
+      name: 'sender',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: { fields: [messageTable.senderId], references: [userTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'Message';
 }
 
 @model({ type: 'entity' })
 export class DirectMessage extends BaseEntity<typeof DirectMessage.schema> {
   static override schema = directMessageTable;
-  static override relations = () => directMessageRelations.definitions;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'sender',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: { fields: [directMessageTable.senderId], references: [userTable.id] },
+    },
+    {
+      name: 'receiver',
+      type: RelationTypes.ONE,
+      schema: userTable,
+      metadata: { fields: [directMessageTable.receiverId], references: [userTable.id] },
+    },
+  ];
+
   static override TABLE_NAME = 'DirectMessage';
 }
 ```
@@ -243,7 +268,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -254,7 +279,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -270,16 +295,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
 
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      Object.keys(schema).length,
-      Object.keys(schema),
+      schema.length,
+      schema,
     );
 
-    const client = new Pool(this.settings);
-    this.connector = drizzle({ client, schema });
+    // The client must land on this.client - a local would leave beginTransaction() with nothing
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
+    this.client = new Pool(this.settings);
   }
 }
 ```
@@ -325,25 +352,27 @@ export class RoomRepository extends DefaultCRUDRepository<typeof Room.schema> {
 
   async findByUser(opts: { userId: string }) {
     const memberships = await this._memberRepo.find({
-      where: { userId: opts.userId },
-      include: { room: true },
+      filter: { where: { userId: opts.userId }, include: [{ relation: 'room' }] },
     });
     return memberships.map(m => m.room);
   }
 
   async isMember(opts: { roomId: string; userId: string }): Promise<boolean> {
     const member = await this._memberRepo.findOne({
-      where: { roomId: opts.roomId, userId: opts.userId },
+      filter: { where: { roomId: opts.roomId, userId: opts.userId } },
     });
     return !!member;
   }
 
   async addMember(opts: { roomId: string; userId: string; role?: string }) {
-    return this._memberRepo.create({
-      roomId: opts.roomId,
-      userId: opts.userId,
-      role: opts.role ?? 'member',
+    const { data } = await this._memberRepo.create({
+      data: {
+        roomId: opts.roomId,
+        userId: opts.userId,
+        role: opts.role ?? 'member',
+      },
     });
+    return data;
   }
 
   async removeMember(opts: { roomId: string; userId: string }) {
@@ -354,14 +383,13 @@ export class RoomRepository extends DefaultCRUDRepository<typeof Room.schema> {
 
   async getMember(opts: { roomId: string; userId: string }) {
     return this._memberRepo.findOne({
-      where: { roomId: opts.roomId, userId: opts.userId },
+      filter: { where: { roomId: opts.roomId, userId: opts.userId } },
     });
   }
 
   async getMembers(opts: { roomId: string }) {
     return this._memberRepo.find({
-      where: { roomId: opts.roomId },
-      include: { user: true },
+      filter: { where: { roomId: opts.roomId }, include: [{ relation: 'user' }] },
     });
   }
 }
@@ -393,7 +421,8 @@ export class MessageRepository extends DefaultCRUDRepository<typeof Message.sche
   }
 
   async createDirectMessage(opts: { senderId: string; receiverId: string; content: string }) {
-    return this._dmRepo.create(opts);
+    const { data } = await this._dmRepo.create({ data: opts });
+    return data;
   }
 
   async findDirectMessages(opts: {
@@ -403,26 +432,26 @@ export class MessageRepository extends DefaultCRUDRepository<typeof Message.sche
     before?: string;
   }) {
     return this._dmRepo.find({
-      where: {
-        or: [
-          { senderId: opts.userId1, receiverId: opts.userId2 },
-          { senderId: opts.userId2, receiverId: opts.userId1 },
-        ],
+      filter: {
+        where: {
+          or: [
+            { senderId: opts.userId1, receiverId: opts.userId2 },
+            { senderId: opts.userId2, receiverId: opts.userId1 },
+          ],
+        },
+        order: ['createdAt DESC'],
+        limit: opts.limit ?? 50,
       },
-      orderBy: { createdAt: 'desc' },
-      limit: opts.limit ?? 50,
     });
   }
 
   async findConversations(opts: { userId: string }) {
     // Get unique conversation partners
     const sent = await this._dmRepo.find({
-      where: { senderId: opts.userId },
-      include: { receiver: true },
+      filter: { where: { senderId: opts.userId }, include: [{ relation: 'receiver' }] },
     });
     const received = await this._dmRepo.find({
-      where: { receiverId: opts.userId },
-      include: { sender: true },
+      filter: { where: { receiverId: opts.userId }, include: [{ relation: 'sender' }] },
     });
 
     // Combine and deduplicate
@@ -450,7 +479,8 @@ import {
   BindingKeys,
   BindingNamespaces,
 } from '@venizia/ignis';
-import { ISocketIOClient, getError, SocketIOServerHelper } from '@venizia/ignis-helpers';
+import { getError } from '@venizia/ignis-helpers';
+import { ISocketIOClient, SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
 import { Socket } from 'socket.io';
 import { MessageRepository } from '../repositories/message.repository';
 import { RoomRepository } from '../repositories/room.repository';
@@ -492,7 +522,7 @@ export class ChatService extends BaseService {
   }
 
   // ---------------------------------------------------------------------------
-  // SocketIOServerHelper — lazy getter (bound after server starts via post-start hook)
+  // SocketIOServerHelper - lazy getter (bound after server starts via post-start hook)
   // ---------------------------------------------------------------------------
   private get socketIOHelper(): SocketIOServerHelper {
     if (!this._socketIOHelper) {
@@ -511,7 +541,7 @@ export class ChatService extends BaseService {
   }
 
   // ---------------------------------------------------------------------------
-  // Socket event handlers — called from clientConnectedFn after authentication
+  // Socket event handlers - called from clientConnectedFn after authentication
   // ---------------------------------------------------------------------------
   registerClientHandlers(opts: { socket: Socket }) {
     const logger = this.logger.for(this.registerClientHandlers.name);
@@ -699,7 +729,7 @@ export class ChatService extends BaseService {
   // Room operations
   // ---------------------------------------------------------------------------
   async createRoom(opts: { name: string; description?: string; isPrivate?: boolean; createdBy: string }) {
-    const room = await this._roomRepo.create(opts);
+    const { data: room } = await this._roomRepo.create({ data: opts });
 
     // Add creator as admin
     await this._roomRepo.addMember({ roomId: room.id, userId: opts.createdBy, role: 'admin' });
@@ -708,7 +738,7 @@ export class ChatService extends BaseService {
   }
 
   async joinRoom(opts: { roomId: string; userId: string }) {
-    const room = await this._roomRepo.findById(opts.roomId);
+    const room = await this._roomRepo.findById({ id: opts.roomId });
     if (!room) {
       throw getError({ statusCode: 404, message: 'Room not found' });
     }
@@ -742,14 +772,16 @@ export class ChatService extends BaseService {
       throw getError({ statusCode: 403, message: 'Not a member of this room' });
     }
 
-    const message = await this._messageRepo.create({
-      roomId: opts.roomId,
-      senderId: opts.senderId,
-      content: opts.content,
-      type: opts.type ?? 'text',
+    const { data: message } = await this._messageRepo.create({
+      data: {
+        roomId: opts.roomId,
+        senderId: opts.senderId,
+        content: opts.content,
+        type: opts.type ?? 'text',
+      },
     });
 
-    const sender = await this._userRepo.findById(opts.senderId);
+    const sender = await this._userRepo.findById({ id: opts.senderId });
 
     return {
       ...message,
@@ -763,7 +795,7 @@ export class ChatService extends BaseService {
   }
 
   async editMessage(opts: { messageId: string; userId: string; content: string }) {
-    const message = await this._messageRepo.findById(opts.messageId);
+    const message = await this._messageRepo.findById({ id: opts.messageId });
 
     if (!message) {
       throw getError({ statusCode: 404, message: 'Message not found' });
@@ -773,14 +805,17 @@ export class ChatService extends BaseService {
       throw getError({ statusCode: 403, message: 'Cannot edit others messages' });
     }
 
-    return this._messageRepo.updateById(opts.messageId, {
-      content: opts.content,
-      editedAt: new Date(),
+    return this._messageRepo.updateById({
+      id: opts.messageId,
+      data: {
+        content: opts.content,
+        editedAt: new Date(),
+      },
     });
   }
 
   async deleteMessage(opts: { messageId: string; userId: string }) {
-    const message = await this._messageRepo.findById(opts.messageId);
+    const message = await this._messageRepo.findById({ id: opts.messageId });
 
     if (!message) {
       throw getError({ statusCode: 404, message: 'Message not found' });
@@ -793,8 +828,11 @@ export class ChatService extends BaseService {
       }
     }
 
-    return this._messageRepo.updateById(opts.messageId, {
-      deletedAt: new Date(),
+    return this._messageRepo.updateById({
+      id: opts.messageId,
+      data: {
+        deletedAt: new Date(),
+      },
     });
   }
 
@@ -805,16 +843,18 @@ export class ChatService extends BaseService {
     };
 
     if (opts.before) {
-      const beforeMessage = await this._messageRepo.findById(opts.before);
+      const beforeMessage = await this._messageRepo.findById({ id: opts.before });
       if (beforeMessage) {
         where.createdAt = { lt: beforeMessage.createdAt };
       }
     }
 
     return this._messageRepo.find({
-      where,
-      orderBy: { createdAt: 'desc' },
-      limit: opts.limit ?? 50,
+      filter: {
+        where,
+        order: ['createdAt DESC'],
+        limit: opts.limit ?? 50,
+      },
     });
   }
 
@@ -842,16 +882,22 @@ export class ChatService extends BaseService {
   // Presence operations
   // ---------------------------------------------------------------------------
   async setOnline(opts: { userId: string }) {
-    await this._userRepo.updateById(opts.userId, {
-      isOnline: true,
-      lastSeenAt: new Date(),
+    await this._userRepo.updateById({
+      id: opts.userId,
+      data: {
+        isOnline: true,
+        lastSeenAt: new Date(),
+      },
     });
   }
 
   async setOffline(opts: { userId: string }) {
-    await this._userRepo.updateById(opts.userId, {
-      isOnline: false,
-      lastSeenAt: new Date(),
+    await this._userRepo.updateById({
+      id: opts.userId,
+      data: {
+        isOnline: false,
+        lastSeenAt: new Date(),
+      },
     });
   }
 
@@ -948,7 +994,7 @@ import {
 import {
   applicationEnvironment,
   type ISocketIOServerBaseOptions,
-  RedisHelper,
+  RedisSingleHelper,
   SocketIOServerHelper,
 } from '@venizia/ignis-helpers';
 import { ChatService } from './services/chat.service';
@@ -958,7 +1004,7 @@ import { RoomRepository, RoomMemberRepository } from './repositories/room.reposi
 import { MessageRepository, DirectMessageRepository } from './repositories/message.repository';
 
 export class ChatApp extends BaseApplication {
-  private redisHelper: RedisHelper;
+  private redisHelper: RedisSingleHelper;
 
   getAppInfo(): IApplicationInfo {
     return { name: 'chat-api', version: '1.0.0' };
@@ -990,9 +1036,9 @@ export class ChatApp extends BaseApplication {
 
   // ---------------------------------------------------------------------------
   private setupSocketIO() {
-    // 1. Redis connection — SocketIOServerHelper creates 3 duplicate connections
+    // 1. Redis connection - SocketIOServerHelper creates 3 duplicate connections
     //    for adapter (pub/sub) and emitter automatically
-    this.redisHelper = new RedisHelper({
+    this.redisHelper = new RedisSingleHelper({
       name: 'chat-redis',
       host: process.env.APP_ENV_REDIS_HOST ?? 'localhost',
       port: +(process.env.APP_ENV_REDIS_PORT ?? 6379),
@@ -1000,11 +1046,11 @@ export class ChatApp extends BaseApplication {
       autoConnect: false,
     });
 
-    this.bind<RedisHelper>({
+    this.bind<RedisSingleHelper>({
       key: SocketIOBindingKeys.REDIS_CONNECTION,
     }).toValue(this.redisHelper);
 
-    // 2. Authentication handler — called when a client emits 'authenticate'
+    // 2. Authentication handler - called when a client emits 'authenticate'
     //    Receives the Socket.IO handshake (headers, query, auth object)
     const authenticateFn: ISocketIOServerBaseOptions['authenticateFn'] = handshake => {
       const token =
@@ -1024,7 +1070,7 @@ export class ChatApp extends BaseApplication {
       key: SocketIOBindingKeys.AUTHENTICATE_HANDLER,
     }).toValue(authenticateFn);
 
-    // 3. Client connected handler — called AFTER successful authentication
+    // 3. Client connected handler - called AFTER successful authentication
     //    This is where you register custom event handlers on each socket
     const clientConnectedFn: ISocketIOServerBaseOptions['clientConnectedFn'] = ({ socket }) => {
       const chatService = this.get<ChatService>({
@@ -1041,7 +1087,7 @@ export class ChatApp extends BaseApplication {
       key: SocketIOBindingKeys.CLIENT_CONNECTED_HANDLER,
     }).toValue(clientConnectedFn);
 
-    // 4. (Optional) Custom server options — override defaults
+    // 4. (Optional) Custom server options - override defaults
     this.bind({
       key: SocketIOBindingKeys.SERVER_OPTIONS,
     }).toValue({
@@ -1054,7 +1100,7 @@ export class ChatApp extends BaseApplication {
       },
     });
 
-    // 5. Register the component — that's it!
+    // 5. Register the component - that's it!
     //    SocketIOComponent handles:
     //    - Runtime detection (Node.js / Bun)
     //    - Post-start hook to create SocketIOServerHelper after server starts
@@ -1096,7 +1142,7 @@ Application Lifecycle
 preConfigure()
   ├── Register repositories, services, controllers
   └── setupSocketIO()
-        ├── Bind RedisHelper → REDIS_CONNECTION
+        ├── Bind RedisSingleHelper → REDIS_CONNECTION
         ├── Bind authenticateFn → AUTHENTICATE_HANDLER
         ├── Bind clientConnectedFn → CLIENT_CONNECTED_HANDLER
         ├── Bind server options → SERVER_OPTIONS
@@ -1104,12 +1150,12 @@ preConfigure()
 
 initialize()
   └── SocketIOComponent.binding()
-        ├── resolveBindings() — reads all bound values
-        ├── RuntimeModules.detect() — auto-detect Node.js or Bun
+        ├── resolveBindings() - reads all bound values
+        ├── RuntimeModules.detect() - auto-detect Node.js or Bun
         └── registerPostStartHook('socket-io-initialize')
 
 start()
-  ├── startBunModule() / startNodeModule() — server starts
+  ├── startBunModule() / startNodeModule() - server starts
   └── executePostStartHooks()
         └── 'socket-io-initialize'
               ├── Create SocketIOServerHelper (with Redis adapter + emitter)
@@ -1215,7 +1261,7 @@ export class ChatController extends BaseRestController {
       },
     });
 
-    // GET /chat/rooms/:roomId/messages
+    // GET /chat/rooms/{roomId}/messages
     this.bindRoute({ configs: ChatRoutes.GET_MESSAGES }).to({
       handler: async (c: TRouteContext) => {
         const roomId = c.req.param('roomId');
@@ -1241,7 +1287,7 @@ export class ChatController extends BaseRestController {
       },
     });
 
-    // GET /chat/dm/:userId
+    // GET /chat/dm/{userId}
     this.bindRoute({ configs: ChatRoutes.GET_DIRECT_MESSAGES }).to({
       handler: async (c: TRouteContext) => {
         const currentUserId = c.get('userId');
@@ -1265,7 +1311,7 @@ export class ChatController extends BaseRestController {
 
 ## 8. Client Usage
 
-Clients must follow the `SocketIOServerHelper` authentication flow: **connect** → **emit `authenticate`** → **receive `authenticated`** — then they're ready to send and receive events.
+Clients must follow the `SocketIOServerHelper` authentication flow: **connect** → **emit `authenticate`** → **receive `authenticated`** - then they're ready to send and receive events.
 
 ### JavaScript Client Example
 
@@ -1293,16 +1339,16 @@ class ChatClient {
   }
 
   // ---------------------------------------------------------------------------
-  // Connection lifecycle — follows SocketIOServerHelper's auth flow
+  // Connection lifecycle - follows SocketIOServerHelper's auth flow
   // ---------------------------------------------------------------------------
   private setupLifecycle() {
-    // Step 1: Connected — now send authenticate event
+    // Step 1: Connected - now send authenticate event
     this._socket.on('connect', () => {
       console.log('Connected | id:', this._socket.id);
       this._socket.emit('authenticate');
     });
 
-    // Step 2: Authenticated — ready to use
+    // Step 2: Authenticated - ready to use
     this._socket.on('authenticated', (data: { id: string; time: string }) => {
       console.log('Authenticated | id:', data.id);
       this._authenticated = true;
@@ -1317,7 +1363,7 @@ class ChatClient {
 
     // Keep-alive ping from server (every 30s)
     this._socket.on('ping', () => {
-      // Server is checking we're alive — no action needed
+      // Server is checking we're alive - no action needed
     });
 
     this._socket.on('disconnect', (reason: string) => {
@@ -1327,7 +1373,7 @@ class ChatClient {
   }
 
   // ---------------------------------------------------------------------------
-  // Custom event handlers — registered after authentication
+  // Custom event handlers - registered after authentication
   // ---------------------------------------------------------------------------
   private setupEventHandlers() {
     this._socket.on('message:new', (message) => {
@@ -1405,7 +1451,7 @@ const chat = new ChatClient({ token: 'your-jwt-token' });
 For server-to-server or microservice communication, use the built-in `SocketIOClientHelper`:
 
 ```typescript
-import { SocketIOClientHelper } from '@venizia/ignis-helpers';
+import { SocketIOClientHelper } from '@venizia/ignis-helpers/socket-io';
 
 const client = new SocketIOClientHelper({
   identifier: 'chat-service-client',
@@ -1446,7 +1492,7 @@ Redis scaling is **built-in** and **automatic** when using `SocketIOComponent`.
 
 ### How It Works
 
-When you bind a `RedisHelper` to `SocketIOBindingKeys.REDIS_CONNECTION`, the `SocketIOServerHelper` automatically:
+When you bind a `RedisSingleHelper` (or any `AbstractRedisHelper` subclass) to `SocketIOBindingKeys.REDIS_CONNECTION`, the `SocketIOServerHelper` automatically:
 
 1. Creates 3 duplicate Redis connections from your helper
 2. Sets up `@socket.io/redis-adapter` for cross-instance pub/sub
@@ -1464,7 +1510,7 @@ Process A                     Redis                     Process B
 
 ### Multi-Instance Deployment
 
-Run multiple instances behind a load balancer — Redis keeps them in sync:
+Run multiple instances behind a load balancer - Redis keeps them in sync:
 
 ```bash
 # Instance 1
@@ -1481,10 +1527,10 @@ All calls to `socketIOHelper.send()` go through the Redis emitter, so messages r
 
 ### Redis Configuration
 
-The only thing you need is a `RedisHelper` bound to the correct key (already done in the application setup):
+The only thing you need is a `RedisSingleHelper` bound to the correct key (already done in the application setup):
 
 ```typescript
-this.redisHelper = new RedisHelper({
+this.redisHelper = new RedisSingleHelper({
   name: 'chat-redis',
   host: process.env.APP_ENV_REDIS_HOST ?? 'localhost',
   port: +(process.env.APP_ENV_REDIS_PORT ?? 6379),
@@ -1492,7 +1538,7 @@ this.redisHelper = new RedisHelper({
   autoConnect: false,
 });
 
-this.bind<RedisHelper>({
+this.bind<RedisSingleHelper>({
   key: SocketIOBindingKeys.REDIS_CONNECTION,
 }).toValue(this.redisHelper);
 ```
@@ -1507,7 +1553,7 @@ this.bind<RedisHelper>({
 | Presence | `socketIOHelper.send()` broadcast on connect/disconnect |
 | History | REST API with cursor-based pagination |
 | Authentication | `SocketIOServerHelper` built-in flow (connect → authenticate → authenticated) |
-| Scaling | Redis adapter/emitter — automatic via `RedisHelper` binding |
+| Scaling | Redis adapter/emitter - automatic via `RedisSingleHelper` binding |
 | Runtime | Auto-detected (Node.js or Bun) by `SocketIOComponent` |
 
 ## Next Steps
@@ -1520,6 +1566,6 @@ this.bind<RedisHelper>({
 
 ## See Also
 
-- [Socket.IO Component](/extensions/components/socket-io/) — Component reference
-- [Socket.IO Helper](/extensions/helpers/socket-io/) — Server + Client helper API
-- [Socket.IO Test Example](https://github.com/VENIZIA-AI/ignis/tree/main/examples/socket-io-test) — Working example with automated test client
+- [Socket.IO Component](/extensions/components/socket-io/) - Component reference
+- [Socket.IO Helper](/extensions/helpers/socket-io/) - Server + Client helper API
+- [Socket.IO Test Example](https://github.com/VENIZIA-AI/ignis/tree/main/examples/socket-io-test) - Working example with automated test client