API Reference

Use this API reference to look up the main Typeweaver authoring helpers, HTTP enums, and runtime validation types. It focuses on the exports you use when defining specs and working with generated artifacts.

Typeweaver's public API is deliberately small, so most day-to-day work happens through a few spec helpers and a few runtime types.

Authoring helpers

`defineSpec(...)`

Use defineSpec(...) to declare the root resource map for your API.

defineSpec({
  resources: {
    todo: {
      operations: [GetTodoDefinition, CreateTodoDefinition],
    },
  },
});

What it does

groups operations under resource names
preserves literal types for generation
gives Typeweaver the full spec it later normalizes and validates

Key rule: resource names become part of generated output, so choose them carefully.

`defineOperation(...)`

Use defineOperation(...) for one HTTP contract.

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

Important fields

Field	Meaning
`operationId`	Stable identifier used for generated request/response files, handlers, and clients
`method`	HTTP verb from `HttpMethod`
`path`	Express-style path, such as `/todos/:todoId`
`summary`	Human-readable description used in generated comments and docs
`request`	Optional Zod schemas for `header`, `param`, `query`, and `body`
`responses`	Allowed responses for the operation; first entry is the success case

`defineResponse(...)`

Use defineResponse(...) for canonical or reusable responses.

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

Important rules

response names must stay globally unique across the whole spec
statusCode must come from HttpStatusCode
header and body are optional Zod schemas

`defineDerivedResponse(...)`

Use defineDerivedResponse(...) when you want a new response based on an existing one.

const TodoNotFoundErrorDefinition = defineDerivedResponse(
  NotFoundErrorDefinition,
  {
    name: "TodoNotFoundError",
    body: z.object({
      todoId: z.string(),
    }),
  }
);

What it does

inherits unspecified fields from the base response
merges object-like header schemas
merges object-like body schemas when both sides are z.object(...)
keeps the response relationship explicit in the spec

Use it for specialization, not for everyday inheritance chains.

HTTP enums and core types

`HttpMethod`

HttpMethod is the enum used in operation definitions.

HttpMethod.GET
HttpMethod.POST
HttpMethod.PUT
HttpMethod.DELETE
HttpMethod.PATCH

Use it instead of raw strings in specs.

`HttpStatusCode`

HttpStatusCode is the enum used in response definitions.

Common values:

HttpStatusCode.OK
HttpStatusCode.CREATED
HttpStatusCode.BAD_REQUEST
HttpStatusCode.NOT_FOUND
HttpStatusCode.INTERNAL_SERVER_ERROR

It includes the broader standard HTTP status code set, not just the common ones.

`ITypedHttpResponse`

Generated response types are built on ITypedHttpResponse.

Minimal shape:

type ITypedHttpResponse<
  TypeName,
  StatusCode,
  Header,
  Body
> = {
  readonly type: TypeName;
  readonly statusCode: StatusCode;
  readonly header: Header;
  readonly body: Body;
};

In normal app code, you usually consume the generated concrete response types rather than writing this type yourself.

`isTypedHttpResponse(...)`

Use isTypedHttpResponse(...) as a runtime guard when you have an unknown value and want to verify it looks like a typed Typeweaver response.

if (isTypedHttpResponse(value)) {
  console.log(value.type, value.statusCode);
}

This replaces old instanceof HttpResponse-style checks.

Validation error types

`RequestValidationError`

Thrown when request validation fails.

It groups issues by request part:

headerIssues
bodyIssues
queryIssues
pathParamIssues

try {
  validator.validate(request);
} catch (error) {
  if (error instanceof RequestValidationError) {
    console.log(error.bodyIssues);
  }
}

`ResponseValidationError`

Thrown when a response does not match the declared contract.

Useful fields and helpers:

statusCode
issues
hasStatusCodeIssues()
hasResponseIssues()

try {
  responseValidator.validate(response);
} catch (error) {
  if (error instanceof ResponseValidationError) {
    console.log(error.issues);
  }
}

Spec normalization errors

When generation loads your spec, Typeweaver can fail early with descriptive errors such as:

DuplicateOperationIdError
DuplicateRouteError
EmptyResourceOperationsError
EmptySpecResourcesError
InvalidOperationIdError
InvalidResourceNameError
PathParameterMismatchError
MissingDerivedResponseParentError
DerivedResponseCycleError

Treat these as spec-authoring feedback, not runtime exceptions to catch inside handlers.

Most common import surface

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