triad-channel

Channels (WebSockets)

Channels are the real-time counterpart to endpoints. Same schema DSL, same behavior builder, same router. Currently supported by the Fastify adapter only. The AsyncAPI generator (@triadjs/asyncapi) produces asyncapi.yaml alongside openapi.yaml when the router has channels.

channel() signature

import { channel, t } from '@triadjs/core';

interface ChatRoomState {
  userId: string;
  userName: string;
  roomId: string;
}

export const chatRoom = channel({
  name: 'chatRoom',
  path: '/ws/rooms/:roomId',
  summary: 'Real-time chat room',
  description: 'Bidirectional chat for a room',
  tags: ['Chat'],

  // Phantom witness for typed ctx.state — value is ignored, type is used
  state: {} as ChatRoomState,

  connection: {
    params:  { roomId: t.string().format('uuid') },
    headers: {
      'x-user-id':   t.string().format('uuid'),
      'x-user-name': t.string().minLength(1),
    },
    // query: optional, same shape
  },

  clientMessages: {
    sendMessage: { schema: SendMessagePayload, description: 'Post a message' },
    typing:      { schema: TypingPayload,      description: 'Typing state' },
  },

  serverMessages: {
    message:  { schema: ChatMessage,     description: 'New message' },
    typing:   { schema: TypingIndicator, description: 'Typing indicator' },
    presence: { schema: UserPresence,    description: 'Join/leave' },
    error:    { schema: ChannelError,    description: 'Error' },
  },

  onConnect: async (ctx) => {
    if (!isValidRoom(ctx.params.roomId)) {
      return ctx.reject(404, 'Room not found');
    }
    ctx.state.userId   = ctx.headers['x-user-id'];
    ctx.state.userName = ctx.headers['x-user-name'];
    ctx.state.roomId   = ctx.params.roomId;

    ctx.broadcast.presence({
      userId:   ctx.state.userId,
      userName: ctx.state.userName,
      action:   'joined',
    });
  },

  onDisconnect: async (ctx) => {
    if (ctx.state.userId) {
      ctx.broadcast.presence({ /* ... */ action: 'left' });
    }
  },

  handlers: {
    // One handler per clientMessage. Missing or extra keys = compile error.
    sendMessage: async (ctx, data) => {
      const message = await ctx.services.messageStore.create({ /* ... */ });
      ctx.broadcast.message(message);          // to everyone including sender
    },
    typing: async (ctx, data) => {
      ctx.broadcastOthers.typing({ /* ... */ }); // to everyone EXCEPT sender
    },
  },

  behaviors: [ /* channel behavior scenarios */ ],
});