Request Types

Generated request types are the TypeScript form of the request schemas you declared in the spec.

They save you from repeating request shapes in handlers, commands, and tests.

What gets generated

For an operation named GetTodo, Typeweaver generates names like:

IGetTodoRequest
IGetTodoRequestHeader
IGetTodoRequestParam
IGetTodoRequestQuery
IGetTodoRequestBody

Only the parts you actually declare are generated. If an operation has no query string, there is no IGetTodoRequestQuery type.

Example

Given this request schema:

const GetTodoDefinition = defineOperation({
  operationId: "GetTodo",
  summary: "Get todo",
  method: HttpMethod.GET,
  path: "/todos/:todoId",
  request: {
    header: z.object({
      Authorization: z.string(),
    }),
    param: z.object({
      todoId: z.string(),
    }),
  },
  responses: [GetTodoSuccessDefinition, TodoNotFoundErrorDefinition],
});

the generated request types look like this in practice:

export type IGetTodoRequestHeader = {
  Authorization: string;
};

export type IGetTodoRequestParam = {
  todoId: string;
};

export type IGetTodoRequest = {
  path: string;
  method: HttpMethod.GET;
  header: IGetTodoRequestHeader;
  param: IGetTodoRequestParam;
};

The full request type includes path and method, plus the request parts your schema declared.

How the request parts map back to the spec

header comes from request.header
param comes from request.param
query comes from request.query
body comes from request.body
path and method come from the operation itself

That is why changing the spec updates the generated request type automatically.

Where you use these types

In handlers

Generated server integrations pass validated request data to your handlers, so you can rely on typed access like:

async handleGetTodoRequest(request) {
  return loadTodoById(request.param.todoId);
}

In request commands

Generated commands implement the full request type and accept the request input you actually provide:

const command = new GetTodoRequestCommand({
  header: {
    Authorization: "Bearer token",
  },
  param: {
    todoId: "todo_123",
  },
});

In tests and helper code

Request types are also useful when you want strongly typed fixtures for clients, validators, or server handlers.

Why this helps

Request types make the contract visible in normal application code. If you add a required path param, rename a header, or change a request body field, TypeScript points to every affected caller.