Request

Every controller receives a context, and the incoming HTTP request lives on context.request. It is an HttpRequest instance (implementing the IRequest interface) that wraps the native Request and exposes the parsed pieces you actually need: the URL, the method, the headers, the query string, the route params, the decoded body, the client IP, the detected locale, and any uploaded files. The framework builds it from the native request before the controller runs, so you never construct one by hand. You read it. For the values you reach for most, the context also carries convenience accessors that point straight at the request: context.params, context.queries, and context.payload are the same objects as context.request.params, context.request.queries, and context.request.payload.

What the request object holds

The native Request gives you a raw URL string and a Headers bag. IRequest hands you a parsed IUrl, a typed queries record, route params, and the decoded payload, so you don’t re-parse in every controller. The interface is generic over params, payload, and queries, so a controller declares the exact shape it expects through IRequest<Config> and reads it with full typing. The headers come decoded too: request.header is a Header object with helpers for content type, auth, cookies, and IP, plus a parsed userAgent. The request resolves a lang from the query string, a custom header, or Accept-Language, so locale is ready for translation without extra work. Multipart uploads are parsed into IRequestFile instances on request.files, each one exposing size, type, format detection, read methods, and a write to disk.

How it works

The framework reads the native Request, extracts route params from the matched route and the decoded body, then constructs the HttpRequest. During construction it parses the URL (path, host, queries), normalizes the method, wraps the headers, parses the user agent, builds a RequestFile for every uploaded file, and resolves the locale.

Source	Becomes
`request.url` string	`url` (an `IUrl`), `path`, `host`, `queries`
`request.method`	`method` (uppercased `HttpMethodType`)
`request.headers`	`header` (a `Header`) and `userAgent`
Matched route	`params` (route parameters)
Decoded body	`payload` (JSON / form fields)
Multipart `FormData`	`form` and `files` (each an `IRequestFile`)
`lang`/`locale` query, `X-Custom-Lang`, `Accept-Language`	`lang` (a `LocaleInfoType`)

Properties and methods

context.request exposes these read-only members:

Member	Type	Description
`native`	`Readonly<Request>`	The underlying native `Request`.
`url`	`IUrl`	Parsed URL with helpers (`getPath`, `getQuery`, `getQueries`, `getHostname`, …).
`path`	`string`	The URL path, e.g. `/users/123`.
`method`	`HttpMethodType`	Uppercased HTTP method, e.g. `GET`, `POST`.
`host`	`string`	Host from the `Host` header (empty string if absent).
`ip`	`string \| null`	Client IP address, if provided.
`header`	`Header`	Header accessor with typed convenience getters.
`userAgent`	`IUserAgent \| null`	Parsed user agent (browser, engine, os, device, cpu).
`params`	`Config["params"]`	Route parameters from the matched route.
`queries`	`Config["queries"]`	Query string parameters as a record.
`payload`	`Config["payload"]`	Decoded request body (JSON object or form fields).
`form`	`FormData \| null`	Raw multipart form data, when present.
`files`	`Record<string, IRequestFile>`	Uploaded files keyed by form field name.
`lang`	`LocaleInfoType`	Detected locale `{ code, region }`.

Reading query and route params

Route params come from the dynamic segments of the matched route (/users/:id). Query params come from the URL query string (?page=2&search=alice). Read them from the request, or from the context.params / context.queries shortcuts.

import type { ContextType } from "@talosjs/controller";

public async handler(context: ContextType): Promise<ContextType> {
  // Route param: /users/:id
  const id = context.request.params?.id;

  // Query params: ?page=2&search=alice (same as context.queries)
  const page = context.request.queries?.page ?? 1;
  const search = context.request.queries?.search;

  // The IUrl helper reads a single query value directly
  const sort = context.request.url.getQuery("sort");

  return context;
}

Reading the payload

For POST, PUT, and PATCH requests the decoded body is on payload (and mirrored on context.payload). For JSON requests it is the parsed object; for form submissions it is the field record.

public async handler(context: ContextType): Promise<ContextType> {
  const { name, email } = context.request.payload ?? {};

  context.response.json({ created: { name, email } });

  return context;
}

Type the payload at the controller level so reads are checked:

import type { IRequest } from "@talosjs/http-request";

type CreateUserConfig = {
  payload: { name: string; email: string };
  params: { id: string };
};

const request = context.request as IRequest<CreateUserConfig>;
const { name, email } = request.payload; // typed

Validate the payload before trusting it. See Validation.

Headers and user agent

request.header is a Header object. Use get(name) and has(name) for raw values, or the typed convenience getters for common headers.

public async handler(context: ContextType): Promise<ContextType> {
  // Raw header access
  const custom = context.request.header.get("X-Request-Id");
  const hasAuth = context.request.header.has("Authorization");

  // Typed convenience getters
  const token = context.request.header.getBearerToken();
  const contentType = context.request.header.getContentType();
  const cookies = context.request.header.getCookies();

  // Parsed user agent
  const ua = context.request.userAgent;
  const browser = ua?.browser; // { name, version, ... }
  const os = ua?.os;

  return context;
}

The user agent is parsed once during construction into an IUserAgent with browser, engine, os, device, and cpu. It is null when no User-Agent header is present.

File uploads

When the request is multipart form data, the framework parses it into request.form (the raw FormData) and request.files, a record keyed by form field name where each value is an IRequestFile. A RequestFile wraps the native File and adds metadata, format detection, read methods, and disk writing.

public async handler(context: ContextType): Promise<ContextType> {
  const avatar = context.request.files.avatar;

  if (avatar && avatar.isImage && avatar.size <= 2_000_000) {
    // Persist to disk using the generated, collision-safe name
    await avatar.write(`./uploads/${avatar.name}`);
  }

  // Iterate over every uploaded file
  for (const [field, file] of Object.entries(context.request.files)) {
    console.log(field, file.originalName, file.type, file.size);
  }

  return context;
}

`RequestFile` API

Member	Type	Description
`id`	`string`	Unique 25-character identifier.
`name`	`string`	Generated collision-safe name, `{id}.{extension}`.
`originalName`	`string`	Original name, kebab-cased, extension preserved.
`type`	`MimeType`	MIME type with charset stripped.
`size`	`number`	Size in bytes.
`extension`	`string`	Lowercased file extension.
`isImage` / `isSvg` / `isVideo` / `isAudio`	`boolean`	Media format detection.
`isPdf` / `isText` / `isExcel` / `isCsv` / `isJson` / `isXml` / `isHtml`	`boolean`	Document format detection.
`readAsArrayBuffer()`	`Promise<ArrayBuffer>`	Read the contents as an `ArrayBuffer`.
`readAsStream()`	`ReadableStream<Uint8Array>`	Stream the contents (for large files).
`readAsText()`	`Promise<string>`	Read the contents as text.
`write(path)`	`Promise<void>`	Write the file to disk at `path`.

const upload = context.request.files.document;

if (upload.isText || upload.isCsv) {
  const text = await upload.readAsText();
}

if (upload.isImage && !upload.isSvg) {
  const buffer = await upload.readAsArrayBuffer();
}

For organizing uploads, derived paths, and storage backends, see Storage.

Language and locale detection

Every request resolves a lang ({ code, region }) during construction, with a fixed precedence:

Priority	Source	Example
1	`lang` query parameter	`?lang=fr`
2	`locale` query parameter	`?locale=de`
3	`X-Custom-Lang` header	`X-Custom-Lang: es`
4	`Accept-Language` header	`Accept-Language: en-US,en;q=0.9`

When the locale comes from a query param or the custom header, region is null and only code is set. When it falls back to Accept-Language, the first language is parsed into code and region (e.g. { code: "en", region: "US" }). If nothing matches, it defaults to en-US.

public async handler(context: ContextType): Promise<ContextType> {
  const { code, region } = context.request.lang; // e.g. { code: "fr", region: null }

  context.response.json({ locale: code, region });

  return context;
}

Reading the request well

For everyday access, read context.params, context.queries, and context.payload; reach for context.request when you need headers, IP, files, or locale. Declare a Config for IRequest<Config> (or cast) so those members are checked rather than typed any. Query and body values are user input, so run them through Validation before acting on them. Treat the request as read-only. Every member of IRequest is immutable, so build your reply on context.response instead of changing the request. When you save an upload, use file.name, the generated collision-safe name, not the user-supplied originalName, and check size and the is* flags first. For locale, read request.lang rather than re-parsing Accept-Language yourself; it already applies the documented precedence.

Controllers: where the request reaches your handler via context.
Validation: validate params, queries, and payload before use.
Response: build the reply with context.response.
Storage: persist uploaded files beyond a single request.

Getting Started

AI

Framework

Command Line

What the request object holds

How it works

Properties and methods

Reading query and route params

Reading the payload

Headers and user agent

File uploads

`RequestFile` API

Language and locale detection

Reading the request well

​What the request object holds

​How it works

​Properties and methods

​Reading query and route params

​Reading the payload

​Headers and user agent

​File uploads

​RequestFile API

​Language and locale detection

​Reading the request well

​Related

What the request object holds

How it works

Properties and methods

Reading query and route params

Reading the payload

Headers and user agent

File uploads

`RequestFile` API

Language and locale detection

Reading the request well

Related