WebSocket plugin for the TSDIAPI-Server framework, providing seamless integration with Socket.IO and socket-controllers.
npm install @tsdiapi/socket.ioSocket.IO for real-time communication.
bash
npm install @tsdiapi/socket.io
`
Or use the TSDIAPI CLI to install and configure it automatically:
`bash
tsdiapi plugins add socket.io
`
---
š Code Generation
| Command | Description |
|--------------------------|-----------------------------------------------|
| tsdiapi generate socket.io | Creates a new WebSocket event handler template. |
The tsdiapi generate socket.io command generates a basic WebSocket handler, allowing for quick implementation of custom socket logic.
---
š Getting Started
$3
To enable WebSocket functionality, register the plugin in your TSDIAPI-Server application:
`typescript
import { createApp } from "@tsdiapi/server";
import createSocketIOPlugin from "@tsdiapi/socket.io";
createApp({
plugins: [createSocketIOPlugin()],
});
`
---
$3
Define WebSocket events and implement custom handlers within your server:
`typescript
import { FastifyInstance } from "fastify";
export function setupWebSocketHandlers(io: FastifyInstance["io"]) {
io.on("connection", (socket) => {
console.log("Client connected:", socket.id);
socket.on("message", (data) => {
console.log("Received message:", data);
socket.emit("response", { status: "ok", message: "Message received!" });
});
socket.on("disconnect", () => {
console.log("Client disconnected:", socket.id);
});
});
}
`
This functional approach makes it easier to customize and extend WebSocket logic without relying on decorators.
---
$3
TSDIAPI-Socket.IO supports authentication through the verify function:
`typescript
import createSocketIOPlugin from "@tsdiapi/socket.io";
createSocketIOPlugin({
verify: async (token: string) => {
// Simulate token validation
if (token === "valid-token") {
return { userId: "12345", role: "admin" }; // Example session object
}
throw new Error("Authentication failed");
},
});
`
- If verify is provided, the server rejects unauthenticated connections.
- The session object is attached to the socket for later use.
Example handling authenticated sockets:
`typescript
io.on("connection", (socket) => {
if ("session" in socket) {
console.log(User ${socket.session.userId} connected.);
}
});
`
---
š API Reference
$3
Sends a success response to the client.
`typescript
socket.emitSuccess("someEvent", { message: "Hello, world!" });
`
$3
Sends an error response to the client.
`typescript
socket.emitError("someEvent", "Something went wrong.");
`
$3
Registers an event listener.
`typescript
socket.on("message", (data) => {
console.log("Received:", data);
});
`
---
š Lifecycle Hooks
TSDIAPI-Socket.IO integrates into the TSDIAPI lifecycle:
| Hook | Description |
|--------------|--------------------------------------------------|
| onInit | Initializes the WebSocket server. |
| beforeStart| Sets up authentication and event handling. |
---
š Logging & Debugging
TSDIAPI-Socket.IO logs key events for easier debugging:
`plaintext
[INFO] WebSocket server started on port 3000
[INFO] Client connected: abc123
[INFO] Received message: { text: "Hello" }
[INFO] Client disconnected: abc123
[ERROR] Authentication failed
`
---
š Example Full Implementation
`typescript
import { createApp } from "@tsdiapi/server";
import createSocketIOPlugin from "@tsdiapi/socket.io";
import { setupWebSocketHandlers } from "./websocket-handlers";
const socketIOPlugin = createSocketIOPlugin({
verify: async (token) => {
if (token === "valid-token") return { userId: "123" };
throw new Error("Invalid token");
},
});
createApp({
plugins: [socketIOPlugin],
});
``