@rexeus/typeweaver-hono 0.7.0 → 0.8.0

package/README.md

@@ -51,28 +51,24 @@ Implement your handlers and mount the generated router in a Hono app.
 // api/user-handlers.ts
 import type { Context } from "hono";
 import { HttpStatusCode } from "@rexeus/typeweaver-core";
-import type { IGetUserRequest, GetUserResponse, UserNotFoundErrorResponse } from "./generated";
-import { GetUserSuccessResponse } from "./generated";
+import type { HonoUserApiHandler, IGetUserRequest, GetUserResponse } from "./generated";
+import { createUserNotFoundErrorResponse, createGetUserSuccessResponse } from "./generated";
 
 export class UserHandlers implements HonoUserApiHandler {
-    async handleGetUserRequest(request: IGetUserRequest, context: Context): Promise<GetUserResponse> {
-      // Symbolic database fetch
-      const databaseResult = {} as any;
-      if (!databaseResult) {
-        // Will be properly handled by the generated router and returned as a 404 response
-        return new UserNotFoundErrorResponse({
-          statusCode: HttpStatusCode.NotFound,
-          header: { "Content-Type": "application/json" },
-          body: { message: "User not found" },
-        });
-      }
-
-      return new GetUserSuccessResponse({
-        statusCode: HttpStatusCode.OK,
+  async handleGetUserRequest(request: IGetUserRequest, context: Context): Promise<GetUserResponse> {
+    const user = await db.findUser(request.param.userId);
+    if (!user) {
+      return createUserNotFoundErrorResponse({
         header: { "Content-Type": "application/json" },
-        body: { id: request.param.userId, name: "Jane", email: "jane@example.com" },
+        body: { message: "User not found" },
       });
-  },
+    }
+
+    return createGetUserSuccessResponse({
+      header: { "Content-Type": "application/json" },
+      body: { id: request.param.userId, name: "Jane", email: "jane@example.com" },
+    });
+  }
   // Implement other operation handlers: handleCreateUserRequest, ...
 }
 ```
@@ -91,8 +87,10 @@ const userHandlers = new UserHandlers();
 const userRouter = new UserHono({
   requestHandlers: userHandlers,
   validateRequests: true, // default, validates requests
-  handleValidationErrors: true, // default: returns 400 with issues
-  handleHttpResponseErrors: true, // default: returns thrown HttpResponse as-is
+  validateResponses: true, // default, validates responses and strips extra fields
+  handleRequestValidationErrors: true, // default: returns 400 with issues
+  handleResponseValidationErrors: true, // default: returns 500
+  handleHttpResponseErrors: true, // default: returns thrown typed HTTP responses as-is
   handleUnknownErrors: true, // default: returns 500
 });
 
@@ -110,14 +108,27 @@ serve({ fetch: app.fetch, port: 3000 }, () => {
 
 - `requestHandlers`: object implementing the generated `Hono<ResourceName>ApiHandler` type
 - `validateRequests` (default: `true`): enable/disable request validation
-- `handleValidationErrors`: `true` | `false` | `(err, c) => IHttpResponse | Promise<IHttpResponse>`,
+- `validateResponses` (default: `true`): enable/disable response validation. When enabled, responses
+  are validated against the operation's schema and extra body fields are stripped before sending.
+- `handleRequestValidationErrors`: `true` | `false` |
+  `(err, c) => IHttpResponse | Promise<IHttpResponse>`
   - If `true` (default), returns `400 Bad Request` with validation issues in the body
   - If `false`, disables this handler (errors fall through to the unknown error handler)
   - If function, calls the function with the error and context, expects an `IHttpResponse` to
     return, so you can customize the response in the way you want
+- `handleResponseValidationErrors`: `true` | `false` |
+  `(err, response, c) => IHttpResponse | Promise<IHttpResponse>`
+  - If `true` (default), returns `500 Internal Server Error`
+  - If `false`, disables response validation error handling — the invalid response is returned
+    as-is. Validation still runs (and strips extra fields on valid responses), but invalid responses
+    pass through unchanged. Useful when you want field stripping without blocking invalid responses.
+  - If function, calls the function with the `ResponseValidationError`, the original (invalid)
+    response, and the Hono context. The function should return an `IHttpResponse`. If the custom
+    handler throws, the original response is returned as a fallback.
 - `handleHttpResponseErrors`: `true` | `false` |
   `(err, c) => IHttpResponse | Promise<IHttpResponse>`
-  - If `true` (default), returns thrown `HttpResponse` as-is, they will be sent as the response
+  - If `true` (default), returns thrown typed HTTP responses (`ITypedHttpResponse`) as-is, they will
+    be sent as the response
   - If `false`, disables this handler (errors fall through to the unknown error handler)
   - If function, calls the function with the error and context, expects an `IHttpResponse` to
     return, so you can customize the response in the way you want

package/dist/lib/TypeweaverHono.ts

@@ -5,11 +5,17 @@
  * @generated by @rexeus/typeweaver
  */
 
-import { HttpResponse, RequestValidationError } from "@rexeus/typeweaver-core";
+import {
+  isTypedHttpResponse,
+  RequestValidationError,
+} from "@rexeus/typeweaver-core";
 import type {
   IHttpRequest,
   IHttpResponse,
   IRequestValidator,
+  IResponseValidator,
+  ITypedHttpResponse,
+  ResponseValidationError,
 } from "@rexeus/typeweaver-core";
 import { Hono } from "hono";
 import { HonoAdapter } from "./HonoAdapter";
@@ -25,7 +31,7 @@ import type { BlankEnv, BlankSchema, Env, Schema } from "hono/types";
  * @returns The HTTP response to send to the client
  */
 export type HonoHttpResponseErrorHandler = (
-  error: HttpResponse,
+  error: ITypedHttpResponse,
   context: Context
 ) => Promise<IHttpResponse> | IHttpResponse;
 
@@ -35,7 +41,7 @@ export type HonoHttpResponseErrorHandler = (
  * @param context - The Hono context for the current request
  * @returns The HTTP response to send to the client
  */
-export type HonoValidationErrorHandler = (
+export type HonoRequestValidationErrorHandler = (
   error: RequestValidationError,
   context: Context
 ) => Promise<IHttpResponse> | IHttpResponse;
@@ -51,6 +57,20 @@ export type HonoUnknownErrorHandler = (
   context: Context
 ) => Promise<IHttpResponse> | IHttpResponse;
 
+/**
+ * Handles response validation errors.
+ * Called when a handler returns a response that does not match the expected schema.
+ * @param error - The response validation error with schema mismatch details
+ * @param response - The original (invalid) response from the handler
+ * @param context - The Hono context for the current request
+ * @returns The HTTP response to send to the client (typically a 500)
+ */
+export type HonoResponseValidationErrorHandler = (
+  error: ResponseValidationError,
+  response: IHttpResponse,
+  context: Context
+) => Promise<IHttpResponse> | IHttpResponse;
+
 /**
  * Configuration options for TypeweaverHono routers.
  * @template RequestHandlers - Type containing all request handler methods
@@ -64,32 +84,52 @@ export type TypeweaverHonoOptions<
    * Request handler methods for each operation.
    * Each handler receives a request (validated if `validateRequests` is true) and Hono context.
    */
-  requestHandlers: RequestHandlers;
+  readonly requestHandlers: RequestHandlers;
 
   /**
    * Enable request validation using generated validators.
    * When false, requests are passed through without validation.
    * @default true
    */
-  validateRequests?: boolean;
+  readonly validateRequests?: boolean;
 
   /**
-   * Configure handling of HttpResponse errors thrown by handlers.
-   * - `true`: Use default handler (returns the error as-is)
-   * - `false`: Let errors bubble up to Hono
-   * - `function`: Use custom error handler
+   * Enable response validation using generated validators.
+   * When true, responses are validated and stripped of extra fields before sending.
    * @default true
    */
-  handleHttpResponseErrors?: HonoHttpResponseErrorHandler | boolean;
+  readonly validateResponses?: boolean;
 
   /**
    * Configure handling of request validation errors.
    * - `true`: Use default handler (400 with error details)
    * - `false`: Let errors bubble up to Hono
+   * - `function`: Use custom request validation error handler
+   * @default true
+   */
+  readonly handleRequestValidationErrors?:
+    | HonoRequestValidationErrorHandler
+    | boolean;
+
+  /**
+   * Configure handling of response validation errors.
+   * - `true`: Use default handler (500 Internal Server Error)
+   * - `false`: Disable response validation error handling (return response as-is)
+   * - `function`: Use custom response validation error handler
+   * @default true
+   */
+  readonly handleResponseValidationErrors?:
+    | HonoResponseValidationErrorHandler
+    | boolean;
+
+  /**
+   * Configure handling of HttpResponse errors thrown by handlers.
+   * - `true`: Use default handler (returns the error as-is)
+   * - `false`: Let errors bubble up to Hono
    * - `function`: Use custom error handler
    * @default true
    */
-  handleValidationErrors?: HonoValidationErrorHandler | boolean;
+  readonly handleHttpResponseErrors?: HonoHttpResponseErrorHandler | boolean;
 
   /**
    * Configure handling of unknown errors.
@@ -98,7 +138,7 @@ export type TypeweaverHonoOptions<
    * - `function`: Use custom error handler
    * @default true
    */
-  handleUnknownErrors?: HonoUnknownErrorHandler | boolean;
+  readonly handleUnknownErrors?: HonoUnknownErrorHandler | boolean;
 };
 
 /**
@@ -134,11 +174,15 @@ export abstract class TypeweaverHono<
    * Resolved configuration for validation and error handling.
    */
   private readonly config: {
-    validateRequests: boolean;
-    errorHandlers: {
-      validation: HonoValidationErrorHandler | undefined;
-      httpResponse: HonoHttpResponseErrorHandler | undefined;
-      unknown: HonoUnknownErrorHandler | undefined;
+    readonly validateRequests: boolean;
+    readonly validateResponses: boolean;
+    readonly errorHandlers: {
+      readonly requestValidation: HonoRequestValidationErrorHandler | undefined;
+      readonly responseValidation:
+        | HonoResponseValidationErrorHandler
+        | undefined;
+      readonly httpResponse: HonoHttpResponseErrorHandler | undefined;
+      readonly unknown: HonoUnknownErrorHandler | undefined;
     };
   };
 
@@ -146,7 +190,7 @@ export abstract class TypeweaverHono<
    * Default error handlers used when custom handlers are not provided.
    */
   private readonly defaultHandlers = {
-    validation: (error: RequestValidationError): IHttpResponse => ({
+    requestValidation: (error: RequestValidationError): IHttpResponse => ({
       statusCode: 400,
       body: {
         code: "VALIDATION_ERROR",
@@ -160,13 +204,21 @@ export abstract class TypeweaverHono<
       },
     }),
 
-    httpResponse: (error: HttpResponse): IHttpResponse => error,
+    responseValidation: (): IHttpResponse => ({
+      statusCode: 500,
+      body: {
+        code: "INTERNAL_SERVER_ERROR",
+        message: "An unexpected error occurred",
+      },
+    }),
+
+    httpResponse: (error: ITypedHttpResponse): IHttpResponse => error,
 
     unknown: (): IHttpResponse => ({
       statusCode: 500,
       body: {
         code: "INTERNAL_SERVER_ERROR",
-        message: "An unexpected error occurred.",
+        message: "An unexpected error occurred",
       },
     }),
   };
@@ -178,15 +230,17 @@ export abstract class TypeweaverHono<
    * @param options.requestHandlers - Object containing all request handler methods
    * @param options.validateRequests - Whether to validate requests (default: true)
    * @param options.handleHttpResponseErrors - Handler or boolean for HTTP errors (default: true)
-   * @param options.handleValidationErrors - Handler or boolean for validation errors (default: true)
+   * @param options.handleRequestValidationErrors - Handler or boolean for request validation errors (default: true)
    * @param options.handleUnknownErrors - Handler or boolean for unknown errors (default: true)
    */
   public constructor(options: TypeweaverHonoOptions<RequestHandlers, HonoEnv>) {
     const {
       requestHandlers,
       validateRequests = true,
+      validateResponses = true,
       handleHttpResponseErrors,
-      handleValidationErrors,
+      handleRequestValidationErrors,
+      handleResponseValidationErrors,
       handleUnknownErrors,
       ...honoOptions
     } = options;
@@ -198,9 +252,15 @@ export abstract class TypeweaverHono<
     // Resolve configuration
     this.config = {
       validateRequests,
+      validateResponses,
       errorHandlers: {
-        validation: this.resolveErrorHandler(handleValidationErrors, error =>
-          this.defaultHandlers.validation(error)
+        requestValidation: this.resolveErrorHandler(
+          handleRequestValidationErrors,
+          error => this.defaultHandlers.requestValidation(error)
+        ),
+        responseValidation: this.resolveErrorHandler(
+          handleResponseValidationErrors,
+          (_error, _response) => this.defaultHandlers.responseValidation()
         ),
         httpResponse: this.resolveErrorHandler(
           handleHttpResponseErrors,
@@ -239,24 +299,29 @@ export abstract class TypeweaverHono<
    * Processes errors in order: validation, HTTP response, unknown.
    */
   protected registerErrorHandler(): void {
-    this.onError(this.handleError.bind(this));
+    this.onError(async (error, context) =>
+      this.adapter.toResponse(await this.handleError(error, context))
+    );
   }
 
   /**
    * Safely executes an error handler and returns null if it fails.
-   * This allows for graceful fallback to the next handler in the chain.
+   * This allows for graceful fallback to the next handler in the chain
+   * without crashing the request pipeline.
    *
    * @param handlerFn - Function that executes the error handler
-   * @returns Response if successful, null if handler throws
+   * @returns The handler's response if successful, null if the handler throws
    */
-  private async safelyExecuteHandler(
+  private async safelyExecuteErrorHandler(
     handlerFn: () => Promise<IHttpResponse> | IHttpResponse
-  ): Promise<Response | null> {
+  ): Promise<IHttpResponse | null> {
     try {
-      const response = await handlerFn();
-      return this.adapter.toResponse(response);
-    } catch {
-      // Handler execution failed, return null to continue to next handler
+      return await handlerFn();
+    } catch (error) {
+      console.error(
+        "TypeweaverHono: error handler threw while handling error",
+        error
+      );
       return null;
     }
   }
@@ -264,24 +329,21 @@ export abstract class TypeweaverHono<
   protected async handleError(
     error: unknown,
     context: Context
-  ): Promise<Response> {
+  ): Promise<IHttpResponse> {
     // Handle validation errors
     if (
       error instanceof RequestValidationError &&
-      this.config.errorHandlers.validation
+      this.config.errorHandlers.requestValidation
     ) {
-      const response = await this.safelyExecuteHandler(() =>
-        this.config.errorHandlers.validation!(error, context)
+      const response = await this.safelyExecuteErrorHandler(() =>
+        this.config.errorHandlers.requestValidation!(error, context)
       );
       if (response) return response;
     }
 
     // Handle HTTP response errors
-    if (
-      error instanceof HttpResponse &&
-      this.config.errorHandlers.httpResponse
-    ) {
-      const response = await this.safelyExecuteHandler(() =>
+    if (isTypedHttpResponse(error) && this.config.errorHandlers.httpResponse) {
+      const response = await this.safelyExecuteErrorHandler(() =>
         this.config.errorHandlers.httpResponse!(error, context)
       );
       if (response) return response;
@@ -289,7 +351,7 @@ export abstract class TypeweaverHono<
 
     // Handle unknown errors
     if (this.config.errorHandlers.unknown) {
-      const response = await this.safelyExecuteHandler(() =>
+      const response = await this.safelyExecuteErrorHandler(() =>
         this.config.errorHandlers.unknown!(error, context)
       );
       if (response) return response;
@@ -304,7 +366,8 @@ export abstract class TypeweaverHono<
    *
    * @param context - Hono context for the current request
    * @param operationId - Unique operation identifier from the API definition
-   * @param validator - Request validator for the specific operation
+   * @param requestValidator - Request validator for the specific operation
+   * @param responseValidator - Response validator for the specific operation
    * @param handler - Type-safe request handler function
    * @returns Hono-compatible Response object
    */
@@ -314,7 +377,8 @@ export abstract class TypeweaverHono<
   >(
     context: Context,
     operationId: string,
-    validator: IRequestValidator,
+    requestValidator: IRequestValidator,
+    responseValidator: IResponseValidator,
     handler: HonoRequestHandler<TRequest, TResponse>
   ): Promise<Response> {
     try {
@@ -322,15 +386,67 @@ export abstract class TypeweaverHono<
 
       const httpRequest = await this.adapter.toRequest(context);
 
-      // Conditionally validate
       const validatedRequest = this.config.validateRequests
-        ? (validator.validate(httpRequest) as TRequest)
+        ? (requestValidator.validate(httpRequest) as TRequest)
         : (httpRequest as TRequest);
 
       const httpResponse = await handler(validatedRequest, context);
-      return this.adapter.toResponse(httpResponse);
+      return this.adapter.toResponse(
+        await this.validateResponse(responseValidator, httpResponse, context)
+      );
     } catch (error) {
-      return this.handleError(error, context);
+      if (isTypedHttpResponse(error) && this.config.validateResponses) {
+        const validated = await this.validateResponse(
+          responseValidator,
+          error,
+          context
+        );
+        return this.adapter.toResponse(validated);
+      }
+      return this.adapter.toResponse(await this.handleError(error, context));
     }
   }
+
+  /**
+   * Validates a response against the operation's response validator.
+   *
+   * Behavior depends on configuration:
+   * - `validateResponses: false` → returns the original response unchanged.
+   * - `validateResponses: true` (default) → runs validation:
+   *   - Valid response → returns the stripped response (extra fields removed).
+   *   - Invalid response + handler configured → calls the handler safely.
+   *     If the handler throws, falls back to the original response.
+   *   - Invalid response + `handleResponseValidationErrors: false` → returns
+   *     the original (invalid) response as-is.
+   *
+   * @param responseValidator - The response validator for the operation
+   * @param response - The response to validate
+   * @param context - The Hono context for the current request
+   * @returns The validated (and stripped) response, the handler's response, or the original
+   */
+  private async validateResponse(
+    responseValidator: IResponseValidator,
+    response: IHttpResponse,
+    context: Context
+  ): Promise<IHttpResponse> {
+    if (!this.config.validateResponses) return response;
+
+    const result = responseValidator.safeValidate(response);
+
+    if (result.isValid) return result.data;
+
+    if (this.config.errorHandlers.responseValidation) {
+      const handlerResponse = await this.safelyExecuteErrorHandler(() =>
+        this.config.errorHandlers.responseValidation!(
+          result.error,
+          response,
+          context
+        )
+      );
+
+      if (handlerResponse) return handlerResponse;
+    }
+
+    return response;
+  }
 }

package/dist/templates/HonoRouter.ejs

@@ -12,6 +12,7 @@ import { TypeweaverHono, type HonoRequestHandler, type TypeweaverHonoOptions } f
 import type { I<%- operation.className %>Request } from "./<%- operation.className %>Request";
 import { <%- operation.className %>RequestValidator } from "./<%- operation.className %>RequestValidator";
 import type { <%- operation.className %>Response } from "./<%- operation.className %>Response";
+import { <%- operation.className %>ResponseValidator } from "./<%- operation.className %>ResponseValidator";
 <% } %>
 
 export type Hono<%- pascalCaseEntityName %>ApiHandler = {
@@ -33,6 +34,7 @@ export class <%- pascalCaseEntityName %>Hono extends TypeweaverHono<Hono<%- pasc
         context,
         '<%- operation.operationId %>',
         new <%- operation.className %>RequestValidator(),
+        new <%- operation.className %>ResponseValidator(),
         this.requestHandlers.<%- operation.handlerName %>.bind(this.requestHandlers)
       ));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexeus/typeweaver-hono",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Generates Hono routers and handlers straight from your API definitions. Powered by Typeweaver 🧵✨",
   "type": "module",
   "sideEffects": false,
@@ -47,20 +47,20 @@
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
     "hono": "^4.11.0",
-    "@rexeus/typeweaver-core": "^0.7.0",
-    "@rexeus/typeweaver-gen": "^0.7.0"
+    "@rexeus/typeweaver-core": "^0.8.0",
+    "@rexeus/typeweaver-gen": "^0.8.0"
   },
   "devDependencies": {
     "hono": "^4.11.3",
     "test-utils": "file:../test-utils",
-    "@rexeus/typeweaver-core": "^0.7.0",
-    "@rexeus/typeweaver-gen": "^0.7.0"
+    "@rexeus/typeweaver-core": "^0.8.0",
+    "@rexeus/typeweaver-gen": "^0.8.0"
   },
   "dependencies": {
     "case": "^1.6.3"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "format": "oxfmt",
     "build": "tsdown && mkdir -p ./dist/templates ./dist/lib && cp -r ./src/templates/* ./dist/templates/ && cp -r ./src/lib/* ./dist/lib/ && cp ../../LICENSE ../../NOTICE ./dist/",
     "test": "vitest --run",