Controller

The @talosjs/controller component is the HTTP/WebSocket handler layer. A controller is a class with a single index method, bound to a route by a @Route decorator. When a request matches the route, the framework constructs a context (request data, response builder, logger, cache, user, locale, and route metadata) and calls index(context). The handler reads what it needs from context and returns a response. Generics carry your params, payload, queries, and response shapes end to end, so the context is fully typed.

The model

Every controller implements IController as a single typed index(context) handler. There is no base class to extend and no boilerplate. IController<T> and ContextType<T> thread your params, payload, queries, and response types through the whole handler, and the handler receives a lot in that context: the parsed request, a response builder, the logger, cache, rate limiter, locale, authenticated user, headers, files, IP, host, and the matched route metadata. Routing is decorator-bound. @Route.get, @Route.post, @Route.socket, and the rest tie a class to a path, method, version, validation schema, and roles in one place. The index method may return an IResponse directly or a Promise<IResponse>; both work. The same controller shape covers HTTP and WebSocket, with socket controllers using a context that adds a channel API.

How it works

A request flows through routing into the matched controller and back out as a response. The handler never constructs the context; the framework builds it, then calls index.

Stage	What happens
Match	The router matches the request to a route declared by a `@Route` decorator.
Context	The framework builds `ContextType<T>`: request, response, services, user, locale, route metadata.
Handle	`index(context)` runs your logic, reading `context.params`, `context.payload`, `context.queries`, etc.
Respond	The handler returns `context.response.json(...)` (or another response); the framework sends it.

The index signature is the whole contract:

interface IController<T extends ContextConfigType = ContextConfigType> {
  index: (
    context: ContextType<T>,
  ) => Promise<IResponse<T["response"]>> | IResponse<T["response"]>;
}

ContextConfigType describes the shape you bind to a route. response is always present, while params, payload, and queries come from the request config and are optional. ContextType<T> is the object passed to index. Its most-used members:

Member	Purpose
`request`	Parsed `IRequest` — call `.params()`, `.payload()`, `.queries()`.
`response`	Response builder, e.g. `response.json(data)`.
`params` / `payload` / `queries`	Typed request data taken from your config `T`.
`route`	Matched route metadata: `name`, `path`, `method`, `version`, `description`, `roles`.
`user`	Authenticated `IUser` or `null`.
`logger`	Request-scoped logger.
`cache` / `rateLimiter` / `permission`	Optional services available on the context.
`header` / `files` / `ip` / `host` / `method`	Raw request details.
`lang`	Detected locale (`LocaleInfoType`).
`env`	Application environment (`IAppEnv`).

Usage

A controller is a class with one index method, decorated with a @Route method matching the HTTP verb. Define a route type once and pass it to both the decorator config and ContextType<T> so the context is fully typed.

import type { ContextType } from "@talosjs/controller";
import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";

type UserListRouteType = {
  queries: { page?: string; limit?: string; search?: string };
  response: { data: { id: string; name: string }[]; total: number };
};

@Route.get("/users", {
  name: "user.list",
  version: 1,
  description: "List users with optional filtering and pagination",
  queries: Assert({ page: "string?", limit: "string?", search: "string?" }),
  response: Assert({ data: "object[]", total: "number" }),
  roles: ["ROLE_ADMIN"],
})
export class UserListController {
  constructor(private readonly userService: UserService) {}

  public async index(context: ContextType<UserListRouteType>) {
    const { page, limit, search } = context.request.queries();
    const result = await this.userService.execute({ page, limit, search });

    return context.response.json(result);
  }
}

The @Route object exposes one decorator per HTTP method — get, post, put, patch, delete, options, head — plus socket for WebSocket controllers. Each takes the route path and a config:

Config field	Purpose
`name`	Unique route name in dot notation, e.g. `user.list`.
`version`	Route version (number).
`description`	Human-readable description.
`params`	Per-segment validators for `/path/:id` routes, e.g. `{ id: new AssertId() }`.
`payload` / `queries` / `response`	`Assert({...})` schemas for body, query string, and response.
`roles`	Role strings required to access the route, e.g. `["ROLE_USER"]`.

A controller with URL params reads them through context.request.params() (validated by the decorator’s params):

import type { ContextType } from "@talosjs/controller";
import { Route } from "@talosjs/routing";
import { Assert, AssertId } from "@talosjs/validation";

type UserDetailRouteType = {
  params: { id: string };
  response: { id: string; name: string; email: string };
};

@Route.get("/users/:id", {
  name: "user.detail",
  version: 1,
  description: "Get user by ID",
  params: { id: new AssertId() },
  response: Assert({ id: "string", name: "string", email: "string" }),
  roles: ["ROLE_USER"],
})
export class UserDetailController {
  constructor(private readonly userService: UserService) {}

  public async index(context: ContextType<UserDetailRouteType>) {
    const { id } = context.request.params();
    const user = await this.userService.execute(id);

    return context.response.json(user);
  }
}

Mutation routes read the body from context.request.payload():

type UserCreateRouteType = {
  payload: { name: string; email: string; password: string };
  response: { id: string; name: string; email: string };
};

@Route.post("/users", {
  name: "user.create",
  version: 1,
  description: "Create a new user account",
  payload: Assert({ name: "string", email: "string.email", password: "8 <= string <= 100" }),
  response: Assert({ id: "string", name: "string", email: "string" }),
  roles: ["ROLE_ADMIN"],
})
export class UserCreateController {
  constructor(private readonly userService: UserService) {}

  public async index(context: ContextType<UserCreateRouteType>) {
    const data = await context.request.payload();
    const user = await this.userService.execute(data);

    return context.response.json(user);
  }
}

The context exposes the authenticated user, logger, and locale directly, so read only what the handler needs:

public async index(context: ContextType<UserCreateRouteType>) {
  const { user, logger, lang } = context;

  logger.info("Creating user", { actor: user?.id, lang: lang.code });

  const data = await context.request.payload();
  return context.response.json(await this.userService.execute(data));
}

Socket controllers

WebSocket controllers share the same one-method shape but are bound with @Route.socket and use ContextType from @talosjs/socket, which adds a channel API (channel.send, channel.publish, channel.subscribe, channel.close, channel.ws). The CLI scaffolds either variant; pass --is-socket=true for the socket template.

Keeping controllers clean

Keep controllers thin. Validate and shape the request, hand the work to an injected service, and return the response; no business logic lives in index. Define one route type and reuse it, passing the same type to the @Route config and to ContextType<T> so params, payload, queries, and response stay in sync. Include only what the route needs: params for path segments, payload for post, put, and patch, queries for list and search endpoints, and response every time. Read request data through context.request.params(), .payload(), and .queries() so the decorator’s Assert schemas run before your code does. Set roles to the lowest role that satisfies the endpoint, since access is hierarchical and a role also grants the ones it inherits. Return responses through the context.response builder rather than assembling raw HTTP responses by hand. Finally, treat cache, rateLimiter, permission, and user as optional: they may be absent, so guard with ?. and have a fallback.

CLI command

Scaffold a controller, its route type, and a test file with the generator. It writes the class to modules/<module>/src/controllers/<Name>Controller.ts, registers it in the module, and installs @talosjs/controller if it is missing.

# Interactive: prompts for name, socket, route name/path/method
talos controller:create

# HTTP controller with route details
talos controller:create --name=UserList --module=user --route-name=user.list --route-path=/users --route-method=get

# Socket controller
talos controller:create --name=ChatMessage --module=chat --is-socket=true --route-name=chat.message --route-path=/chat

Option	Description	Default
`--name`	Controller class name. Normalized to PascalCase; the `Controller` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--is-socket`	Generate a WebSocket controller instead of HTTP.	Prompted if omitted
`--route-name`	Route name in dot notation, e.g. `user.list`.	Prompted if omitted
`--route-path`	Route path; normalized to kebab-case.	Prompted if omitted
`--route-method`	HTTP method (HTTP controllers only).	Prompted if omitted
`--override`	Overwrite an existing controller without prompting.	`false`

The generated class is a typed stub: a route type, a @Route decorator with empty Assert schemas, and an index that returns an empty JSON response, ready for you to fill in:

import type { ContextType } from "@talosjs/controller";
import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";

export type UserListRouteType = {
  params: {

  },
  payload: {

  },
  queries: {

  },
  response: {

  },
};

@Route.get("/users", {
  name: "user.list",
  version: 1,
  description: "",
  params: {
    // id: Assert("string"),
  },
  payload: Assert({

  }),
  queries: Assert({

  }),
  response: Assert({

  }),
  roles: ["ROLE_USER"],
})
export class UserListController {
  public async index(context: ContextType<UserListRouteType>) {
    // const { id } = context.params;

    return context.response.json({

    });
  }
}

See controller:create for the full command reference.

Use with Claude and Codex

The generator ships a matching controller:create skill. It runs the scaffold and then guides your AI agent through completing the controller: filling in the route type, validation schemas, roles, and the index handler, and delegating logic to a service. Initialize the skills once for your agent:

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a controller that returns the current user's profile.

talos agent:skills:create

Then ask Codex the same way; it maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a controller that returns the current user's profile.

For example, the prompt above maps to a controller:create run with an inferred name, route, and method, then implements the index handler against the user’s profile service.

Getting Started

AI

Framework

Command Line

The model

How it works

Usage

Socket controllers

Keeping controllers clean

CLI command

Use with Claude and Codex

​The model

​How it works

​Usage

​Socket controllers

​Keeping controllers clean

​CLI command

​Use with Claude and Codex

The model

How it works

Usage

Socket controllers

Keeping controllers clean

CLI command

Use with Claude and Codex