First Operation

An operation describes one HTTP action. It defines the method, path, request shape, and every allowed response.

Here is a complete getTodo example:

import {
  defineOperation,
  defineResponse,
  HttpMethod,
  HttpStatusCode,
} from "@rexeus/typeweaver-core";
import { z } from "zod";

const todoSchema = z.object({
  id: z.string(),
  title: z.string(),
  completed: z.boolean(),
});

const TodoNotFoundErrorDefinition = defineResponse({
  name: "TodoNotFoundError",
  statusCode: HttpStatusCode.NOT_FOUND,
  description: "Todo was not found",
  body: z.object({
    message: z.string(),
    todoId: z.string(),
  }),
});

export const GetTodoDefinition = defineOperation({
  operationId: "GetTodo",
  method: HttpMethod.GET,
  summary: "Get todo",
  path: "/todos/:todoId",
  request: {
    param: z.object({
      todoId: z.string(),
    }),
  },
  responses: [
    defineResponse({
      name: "GetTodoSuccess",
      statusCode: HttpStatusCode.OK,
      description: "Todo retrieved successfully",
      body: todoSchema,
    }),
    TodoNotFoundErrorDefinition,
  ],
});

Why each part matters

`operationId`

operationId is the stable name for the operation across generated output. It shows up in generated request commands, response types, validators, and server handlers.

Use either PascalCase or camelCase consistently. In these docs we use PascalCase such as GetTodo, because it matches the generated class names beginners will see. snake_case and kebab-case are not supported.

`summary`

summary is a short human-readable description of the operation. It appears in generated output such as OpenAPI descriptions and code comments, so every operation definition needs one.

`method`

method declares the HTTP verb. Typeweaver uses it during generation, and generated servers use it to match incoming requests.

`path`

path is the route template. Path parameters such as :todoId must line up with request.param.

`request.param`

request.param defines the path parameter schema. In this case, callers must provide a todoId, and generated validators can enforce that shape before your handler runs.

`responses`

responses lists every valid outcome for the operation.

The first response should be the success case.
Error responses come after it.
Each response has a name, status code, description, and optional schemas.

That explicit list is what makes generated clients and server handlers type-safe instead of loosely documented.

Keep the first operation small

For a first operation, a path param plus one success and one error response is enough. Once that feels natural, move on to shared responses and larger specs.