Packages

@xtaskjs/socket-io

Socket.IO gateways, event decorators, injectable realtime services, and lifecycle-managed server attachment.

npm install @xtaskjs/socket-io socket.io reflect-metadata Package path: packages/socket-io

Overview

What this package owns in the runtime

Socket.IO integrates realtime messaging into xtaskjs without leaving the framework's DI and lifecycle model. It discovers decorated gateway services, attaches to the live HTTP server during app.listen(), exposes namespaces and broadcast helpers through DI, and tears down cleanly during app.close().

What it provides

SocketGateway(), OnSocketConnection(), OnSocketDisconnect(), and OnSocketEvent() declare realtime handlers on regular @Service() classes.
Returned values are sent through Socket.IO acknowledgements automatically when the client provides an ack callback.
InjectSocketService(), InjectSocketServer(), InjectSocketNamespace(), and InjectSocketLifecycleManager() expose the runtime through DI.
SocketIoService can broadcast events, list gateways, inspect namespaces, and reuse the lifecycle-managed Socket.IO server.

How it fits

Initialized automatically by @xtaskjs/core when the package is installed and the app starts listening on an HTTP adapter.
Attaches to the live server behind node-http, Express, or Fastify without changing controller or service registration patterns.
Demonstrated by the 23-socket_io_express_app sample with room joins, acknowledgements, and HTTP-triggered announcements.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

4/5

Dependency Injection

5/5

HTTP Delivery

4/5

Operations

5/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Configure Socket.IO defaults when needed and decorate DI-managed services with SocketGateway plus socket handler decorators so xtaskjs can discover them.

During app.listen()

The integration resolves the live HTTP server from the selected adapter, creates the Socket.IO server, registers namespace tokens, and binds discovered gateways.

During app.close()

The Socket.IO server is closed before the HTTP adapter and container are torn down so namespaces, rooms, and subscriptions stop cleanly.

API Surface

Representative exports from the upstream package

Configuration and tokens

configureSocketIo
getSocketIoConfiguration
getSocketIoLifecycleToken
getSocketIoServiceToken
getSocketIoServerToken
getSocketIoNamespaceToken

Gateways and injectors

SocketGateway
OnSocketConnection
OnSocketDisconnect
OnSocketEvent
SubscribeMessage
InjectSocketService
InjectSocketLifecycleManager
InjectSocketServer
InjectSocketNamespace

Runtime service and types

SocketIoService
SocketIoLifecycleManager
initializeSocketIoIntegration
shutdownSocketIoIntegration
getSocketIoLifecycleManager
resetSocketIoIntegration
SocketHandlerContext
SocketGatewaySummary
SocketEmitOptions

Usage

Typical adoption flow

1. Configure namespace defaults

Call configureSocketIo() when you need a non-root default namespace or custom Socket.IO server options such as CORS and transport settings.

2. Decorate gateways and events

Use SocketGateway on a regular @Service() class, then add OnSocketConnection, OnSocketDisconnect, and OnSocketEvent handlers for each namespace workflow.

3. Broadcast from the rest of the app

Inject SocketIoService, a namespace token, or the raw server when controllers and services need to emit announcements or inspect realtime runtime state.

Example

Reference snippet

Decorated gateway plus service broadcast

import { Service } from "@xtaskjs/core";
import { InjectSocketService, OnSocketEvent, SocketGateway, SocketIoService } from "@xtaskjs/socket-io";

@Service()
@SocketGateway({ namespace: "/chat", group: ["realtime", "chat"] })
export class ChatGateway {
  @OnSocketEvent("chat.message")
  onMessage(payload: { user: string; text: string }, context: { namespace: any; socket: any }) {
    context.namespace.emit("chat.message", {
      ...payload,
      socketId: context.socket.id,
      sentAt: new Date().toISOString(),
    });
    return { ok: true };
  }
}

@Service()
export class AnnouncementService {
  constructor(
    @InjectSocketService()
    private readonly sockets: SocketIoService
  ) {}

  announce(message: string) {
    this.sockets.emit("server.announcement", { message }, { namespace: "/chat", room: "lobby" });
  }
}

Samples

Official samples to inspect next

Reference samples: 23-socket_io_express_app