Skip to main content

Socket.IO

OPRA's Socket.IO layer is a decorator-driven framework for building real-time event handlers on top of Socket.IO adapters. You define controllers and event handlers once using TypeScript decorators; the adapter manages socket lifecycle, event routing, and serialization. Event arguments are automatically validated and decoded against their declared types before your handler is called, and response payloads are encoded and validated before they are sent back to the client as acknowledgements.

A Socket.IO API in OPRA is built from two decorator types:

  • @WSController() — groups related event handlers under a single class.
  • @WSOperation() — defines a single event handler on a controller method. It declares the event name, argument types via @WsParam(), and an optional response type.
Event Receivedsocket → serverEvent Matchingcontroller · operationArgumentsdecode & validateHandlerasync methodAcknowledgementencode & emitoptionalerrorerroremit to socketerrorerroremit to socket

Controllers​

@WSController() registers a class as a Socket.IO controller. Use .UseType() to register data types scoped to this controller and its operations. The controller's name defaults to the class name without the Controller suffix.

→ Controllers

Operations​

@WSOperation() defines a single event handler on a controller method. The event option sets the event name — if omitted, the method name is used. Event names can also be a RegExp for pattern-based routing.

→ Controllers

Event Parameters​

Use @WsParam() on method parameters to declare the argument types of an operation. Arguments are decoded in the order they appear in the method signature (excluding the context parameter). OPRA infers the type from TypeScript's design metadata when possible; pass an explicit type to override.

→ Controllers

Responses​

Declare the response type in the response option of @WSOperation(). The handler's return value is automatically encoded using the declared type and sent back to the client as a WebSocket acknowledgement. Use ArrayType(T) to respond with a typed array.

→ Controllers