From f3bcb46ccd620fdee9f3d7bc2f273eba2443a352 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 29 Jan 2026 21:29:51 -0600 Subject: [PATCH] docs(websocket): add JSDoc documentation --- apps/api/src/websocket/websocket.gateway.ts | 62 +++++++++++++++------ 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/apps/api/src/websocket/websocket.gateway.ts b/apps/api/src/websocket/websocket.gateway.ts index fbc138f..77d86ba 100644 --- a/apps/api/src/websocket/websocket.gateway.ts +++ b/apps/api/src/websocket/websocket.gateway.ts @@ -33,8 +33,7 @@ interface Project { } /** - * WebSocket Gateway for real-time updates - * Handles workspace-scoped rooms for broadcasting events + * @description WebSocket Gateway for real-time updates. Handles workspace-scoped rooms for broadcasting events. */ @WSGateway({ cors: { @@ -49,8 +48,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec private readonly logger = new Logger(WebSocketGateway.name); /** - * Handle client connection - * Joins client to workspace-specific room + * @description Handle client connection by authenticating and joining the workspace-specific room. + * @param client - The authenticated socket client containing userId and workspaceId in data. + * @returns Promise that resolves when the client is joined to the workspace room or disconnected. */ async handleConnection(client: AuthenticatedSocket): Promise { const { userId, workspaceId } = client.data; @@ -68,8 +68,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Handle client disconnect - * Leaves workspace room + * @description Handle client disconnect by leaving the workspace room. + * @param client - The socket client containing workspaceId in data. + * @returns void */ handleDisconnect(client: AuthenticatedSocket): void { const { workspaceId } = client.data; @@ -82,7 +83,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit task:created event to workspace room + * @description Emit task:created event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param task - The task object that was created. + * @returns void */ emitTaskCreated(workspaceId: string, task: Task): void { const room = this.getWorkspaceRoom(workspaceId); @@ -91,7 +95,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit task:updated event to workspace room + * @description Emit task:updated event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param task - The task object that was updated. + * @returns void */ emitTaskUpdated(workspaceId: string, task: Task): void { const room = this.getWorkspaceRoom(workspaceId); @@ -100,7 +107,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit task:deleted event to workspace room + * @description Emit task:deleted event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param taskId - The ID of the task that was deleted. + * @returns void */ emitTaskDeleted(workspaceId: string, taskId: string): void { const room = this.getWorkspaceRoom(workspaceId); @@ -109,7 +119,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit event:created event to workspace room + * @description Emit event:created event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param event - The event object that was created. + * @returns void */ emitEventCreated(workspaceId: string, event: Event): void { const room = this.getWorkspaceRoom(workspaceId); @@ -118,7 +131,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit event:updated event to workspace room + * @description Emit event:updated event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param event - The event object that was updated. + * @returns void */ emitEventUpdated(workspaceId: string, event: Event): void { const room = this.getWorkspaceRoom(workspaceId); @@ -127,7 +143,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit event:deleted event to workspace room + * @description Emit event:deleted event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param eventId - The ID of the event that was deleted. + * @returns void */ emitEventDeleted(workspaceId: string, eventId: string): void { const room = this.getWorkspaceRoom(workspaceId); @@ -136,7 +155,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit project:created event to workspace room + * @description Emit project:created event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param project - The project object that was created. + * @returns void */ emitProjectCreated(workspaceId: string, project: Project): void { const room = this.getWorkspaceRoom(workspaceId); @@ -145,7 +167,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit project:updated event to workspace room + * @description Emit project:updated event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param project - The project object that was updated. + * @returns void */ emitProjectUpdated(workspaceId: string, project: Project): void { const room = this.getWorkspaceRoom(workspaceId); @@ -154,7 +179,10 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Emit project:deleted event to workspace room + * @description Emit project:deleted event to all clients in the workspace room. + * @param workspaceId - The workspace identifier for the room to broadcast to. + * @param projectId - The ID of the project that was deleted. + * @returns void */ emitProjectDeleted(workspaceId: string, projectId: string): void { const room = this.getWorkspaceRoom(workspaceId); @@ -163,7 +191,9 @@ export class WebSocketGateway implements OnGatewayConnection, OnGatewayDisconnec } /** - * Get workspace room name + * @description Get workspace room name for Socket.IO room management. + * @param workspaceId - The workspace identifier. + * @returns The room name in format "workspace:{workspaceId}". */ private getWorkspaceRoom(workspaceId: string): string { return `workspace:${workspaceId}`;