smart-socket-nestjs

smart-socket-nestjs

Author: Nurul Islam Rimon

A powerful and simple real-time WebSocket library for NestJS using Socket.IO.

Features

• NestJS Module - Easy integration with forRoot() and forRootAsync()
• Gateway Decorator - @SocketGateway("namespace") for namespace registration
• Event Decorator - @SocketEvent("event") for handling socket events
• Socket Service - Injectable service for emitting events
• JWT Authentication - Built-in JWT authentication support
• Room Management - Join/leave rooms and users
• Redis Adapter - Support for scaling using Redis adapter
• Typed Events - TypeScript generics support
• Connection Tracking - Track online users
• Rate Limiting - Built-in rate limiting

Requirements

• NestJS 11.x
• Node.js 18+

Installation

npm install smart-socket-nestjs

Quick Start

1. Import the module

import { SmartSocketModule } from 'smart-socket-nestjs';

@Module({
  imports: [
    SmartSocketModule.forRoot({
      namespace: '/chat',
      cors: {
        origin: '*',
      },
    }),
  ],
})
export class AppModule {}

2. Create a Gateway

import { Controller } from '@nestjs/common';
import { SocketGateway, SocketEvent } from 'smart-socket-nestjs';
import { SmartSocketService, AuthenticatedSocket } from 'smart-socket-nestjs';

@SocketGateway('chat')
export class ChatGateway {
  constructor(private readonly socketService: SmartSocketService) {}

  @SocketEvent('message')
  async handleMessage(socket: AuthenticatedSocket, data: { text: string }) {
    console.log(`User ${socket.user?.id} sent: ${data.text}`);
    
    // Broadcast to all users in the room
    this.socketService.toRoom('room-1', 'new-message', {
      userId: socket.user?.id,
      text: data.text,
    });
  }

  @SocketEvent('join-room')
  async handleJoinRoom(socket: AuthenticatedSocket, data: { room: string }) {
    await this.socketService.joinRoom(socket, data.room);
    socket.emit('joined', { room: data.room });
  }
}

Usage Examples

Module Configuration

Synchronous Configuration

SmartSocketModule.forRoot({
  namespace: '/api',
  cors: {
    origin: '*',
  },
  enableRateLimiting: true,
  rateLimitOptions: {
    windowMs: 60000,
    maxRequests: 100,
  },
  jwtSecret: 'your-secret-key',
  jwtAlgorithm: 'HS256',
  redis: {
    host: 'localhost',
    port: 6379,
  },
}),

Asynchronous Configuration

SmartSocketModule.forRootAsync({
  useFactory: (configService: ConfigService) => ({
    namespace: '/api',
    jwtSecret: configService.get('JWT_SECRET'),
    redis: {
      host: configService.get('REDIS_HOST'),
      port: configService.get('REDIS_PORT'),
    },
  }),
  inject: [ConfigService],
}),

Socket Service Methods

constructor(private readonly socketService: SmartSocketService) {}

// Emit to all clients
this.socketService.emit('event', data);

// Emit to specific room
this.socketService.toRoom('room-id', 'event', data);

// Emit to specific user
this.socketService.toUser(userId, 'event', data);

// Broadcast to all clients
this.socketService.broadcast('event', data);

// Join room
await this.socketService.joinRoom(socket, 'room-id');

// Leave room
await this.socketService.leaveRoom(socket, 'room-id');

// Join user to room
await this.socketService.joinUser(userId, 'room-id');

// Leave user from room
await this.socketService.leaveUser(userId, 'room-id');

// Get all connected users
const users = this.socketService.getConnectedUsers();

// Check if user is online
const online = this.socketService.isOnline(userId);

Using Typed Events

interface ChatMessage {
  id: string;
  text: string;
  userId: string;
}

@SocketGateway('chat')
export class ChatGateway {
  @SocketEvent('message')
  handleMessage(socket: AuthenticatedSocket, data: ChatMessage) {
    // data is typed as ChatMessage
  }
}

JWT Authentication

When JWT is configured, the socket will have access to socket.user:

@SocketGateway('chat')
export class ChatGateway {
  @SocketEvent('private-message')
  handlePrivateMessage(socket: AuthenticatedSocket, data: { to: string; text: string }) {
    // Access authenticated user
    const fromUserId = socket.user?.id;
    console.log(`User ${fromUserId} sending private message`);
  }
}

Client-side connection with JWT:

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000/chat', {
  auth: {
    token: 'your-jwt-token',
  },
});

Redis Adapter for Scaling

SmartSocketModule.forRoot({
  namespace: '/api',
  redis: {
    host: 'localhost',
    port: 6379,
    password: 'redis-password',
    db: 0,
  },
}),

API Reference

Decorators

@SocketGateway(namespace: string, options?: Record<string, unknown>)

Registers a Socket.IO namespace.

@SocketEvent(event: string)

Handles a socket event.

SmartSocketService Methods

Method	Description
emit(event, data, options?)	Emit to all clients or specific targets
toUser(userId, event, data, namespace?)	Emit to specific user
toRoom(room, event, data, namespace?)	Emit to specific room
broadcast(event, data, namespace?)	Broadcast to all clients
joinRoom(socket, room)	Join a socket to a room
leaveRoom(socket, room)	Leave a socket from a room
joinUser(userId, room, namespace?)	Join user to room
leaveUser(userId, room, namespace?)	Remove user from room
getConnectedUsers()	Get all connected users
isOnline(userId)	Check if user is online
getUserSocketIds(userId)	Get socket IDs for user

License

MIT