🧵✨ @rexeus/typeweaver-types

Typeweaver is a type-safe HTTP API framework built for API-first development with a focus on developer experience. Use typeweaver to specify your HTTP APIs in TypeScript and Zod, and generate clients, validators, routers, and more ✨

📝 Types Plugin

This plugin generates TypeScript types and Zod validators from your typeweaver API definitions, providing the foundation for type-safe API development. This is the core plugin that's included by default in every typeweaver generation.

📥 Installation

# Install the CLI as a dev dependency
# Types plugin will be automatically included
npm install -D @rexeus/typeweaver

# Install the runtime as a dependency
npm install @rexeus/typeweaver-core

💡 How to use

This plugin is included by default and doesn't need to be explicitly specified:

# Generate with clients + types plugins
npx typeweaver generate --input ./api/definition --output ./api/generated --plugins clients

More details on how to use the CLI.

📂 Generated Output

For each operation (e.g., CreateTodo), the plugin generates four main files:

• <OperationId>Request.ts
• <OperationId>Response.ts
• <OperationId>RequestValidator.ts
• <OperationId>ResponseValidator.ts

These files contain the necessary types and validators for requests and responses. All of these provided types and classes are exported.

📨 Request Types

All request-related types for an operation are defined in one file: <OperationId>Request.ts, e.g. CreateTodoRequest.ts. This file contains:

• I<OperationId>RequestHeader - Type of request headers, if defined, e.g. ICreateTodoRequestHeader
• I<OperationId>RequestPath - Type for path parameters, if defined, e.g. ICreateTodoRequestPath
• I<OperationId>RequestQuery - Type for query parameters, if defined, e.g. ICreateTodoRequestQuery
• I<OperationId>RequestBody - Type for request body, if defined, e.g. ICreateTodoRequestBody
• I<OperationId>Request - Complete request interface combining path, method, headers, and body, e.g. ICreateTodoRequest
• Successful<OperationId>Response - Union type excluding error responses for success-only handling

📬 Response Types

All response-related types for an operation are defined in one file: <OperationId>Response.ts, e.g. CreateTodoResponse.ts. This file contains for each response defined inline in an operation:

• I<ResponseName>ResponseHeader - Type for success response headers, if defined, e.g. ICreateTodoSuccessResponseHeader
• I<ResponseName>ResponseBody - Type for success response payload structure, if defined, e.g. ICreateTodoSuccessResponseBody
• I<ResponseName>Response - Complete success response interface with status code, e.g. I<ResponseName>Response
• <ResponseName>Response - Response class extending HttpResponse with validation and type safety, e.g. CreateTodoSuccessResponse

Furthermore, two union types are generated, which include details about all possible responses (success + error), not only those defined inline in the operation:

• I<OperationId>Response - Union type of all response types e.g. ICreateTodoResponse
• <OperationId>Response - Union type of all response classes, e.g. CreateTodoResponse

📨✓ Request Validators

Request validation logic for an operation is defined in one file: <OperationId>RequestValidator.ts, e.g. CreateTodoRequestValidator.ts. This file contains:

• <OperationId>RequestValidator - Main validation class extending RequestValidator, e.g. CreateTodoRequestValidator
• safeValidate() - Non-throwing validation method returning SafeRequestValidationResult
• validate() - Throwing validation method that returns validated request or throws RequestValidationError
• Header coercion logic - Automatic conversion of headers to schema-appropriate types (single string value & multi string value headers)
• Query parameter coercion logic - Automatic conversion of query parameters to schema-appropriate types (single string value & multi string value query parameters)
• Request validation errors - Includes all issues related to the incoming request for headers, query parameters, and body.
• Unknown property filtering - Automatically removes properties not defined in the request schema. If a request exceeds the definition, it is not rejected directly.

Using the generated request validators

import { RequestValidationError, type IHttpRequest } from "@rexeus/typeweaver-core";
import { CreateTodoRequestValidator } from "path/to/generated/output";

const requestValidator = new CreateTodoRequestValidator();

// A request in structure of IHttpRequest
const request: IHttpRequest = {
  // ...
};

// Using safe validation
const safeResult = requestValidator.safeValidate(request);
if (safeResult.isValid) {
  console.log("Request is valid", safeResult.data);
} else {
  // Error is instance of RequestValidationError class
  console.log("Request is invalid", safeResult.error);
}

// Using throwing validation
try {
  const validatedRequest = requestValidator.validate(request);
  console.log("Request is valid", validatedRequest);
} catch (error) {
  if (error instanceof RequestValidationError) {
    console.log("Request is invalid", error);
  }
}

📬✓ Response Validators

Response validation logic for an operation is defined in one file: <OperationId>ResponseValidator.ts, e.g. CreateTodoResponseValidator.ts. This file contains:

• <OperationId>ResponseValidator - Main validation class extending ResponseValidator, e.g. CreateTodoResponseValidator
• safeValidate() - Non-throwing validation method returning SafeResponseValidationResult
• validate() - Throwing validation method that returns validated response or throws ResponseValidationError
• Valid response data is an instance of one of the generated response classes
• Header coercion logic - Automatic conversion of headers to schema-appropriate types (single string value & multi string value headers)
• Response validation errors - Include details about the issues with all possible responses for the given status code:
  • An issue for a possible response includes details about header and body issues
  • If the given status code is not specified in the operation at all an issue with details about expected status codes is included
• Unknown property filtering - Automatically removes properties not defined in the response schema. If a response exceeds the definition, it is not rejected directly.

Using the generated response validators

import { ResponseValidationError, type IHttpResponse } from "@rexeus/typeweaver-core";
import {
  CreateTodoResponseValidator,
  CreateTodoSuccessResponse,
  InternalServerErrorResponse,
} from "path/to/generated/output";

const responseValidator = new CreateTodoResponseValidator();

// A response in structure of IHttpResponse
const response: IHttpResponse = {
  // ...
};

// Using safe validation
const safeResult = responseValidator.safeValidate(response);
if (safeResult.isValid) {
  console.log("Response is valid", safeResult.data);

  // Data is an instance of one of the defined response classes
  if (safeResult.data instanceof CreateTodoSuccessResponse) {
    // handle CreateTodoSuccessResponse
  }
  if (safeResult.data instanceof InternalServerErrorResponse) {
    // handle InternalServerErrorResponse
  }
  // handle other response types ...
} else {
  // Error is instance of ResponseValidationError class
  console.log("Response is invalid", safeResult.error);
}

// Using throwing validation
try {
  const validatedResponse = responseValidator.validate(response);
  console.log("Response is valid", validatedResponse);

  // Same here: Data is an instance of one of the defined response classes
  if (validatedResponse instanceof CreateTodoSuccessResponse) {
    // handle CreateTodoSuccessResponse
  }
  // ... handle other response types
} catch (error) {
  if (error instanceof ResponseValidationError) {
    console.log("Response is invalid", error);
  }
}

📄 License

Apache 2.0 © Dennis Wentzien 2025