@rexeus/typeweaver-server 0.6.5 → 0.8.0

package/README.md

@@ -113,8 +113,8 @@ export const userHandlers: ServerUserApiHandler = {
 };
 ```
 
-> Generated response classes (e.g. `GetUserSuccessResponse`) are also available for when you need
-> runtime type checks or `instanceof` discrimination in error handling.
+> Generated response factory functions (e.g. `createGetUserSuccessResponse`) are also available for
+> constructing typed responses with pre-set `type` and `statusCode` discriminators.
 
 ### Create the app
 
@@ -310,48 +310,67 @@ const app = new TypeweaverApp({
 
 Each router accepts `TypeweaverRouterOptions`:
 
-| Option                     | Type                         | Default    | Description                        |
-| -------------------------- | ---------------------------- | ---------- | ---------------------------------- |
-| `requestHandlers`          | `Server<Resource>ApiHandler` | _required_ | Handler methods for each operation |
-| `validateRequests`         | `boolean`                    | `true`     | Enable/disable request validation  |
-| `handleValidationErrors`   | `boolean \| function`        | `true`     | Handle validation errors           |
-| `handleHttpResponseErrors` | `boolean \| function`        | `true`     | Handle thrown `HttpResponse`       |
-| `handleUnknownErrors`      | `boolean \| function`        | `true`     | Handle unexpected errors           |
+| Option                           | Type                         | Default    | Description                        |
+| -------------------------------- | ---------------------------- | ---------- | ---------------------------------- |
+| `requestHandlers`                | `Server<Resource>ApiHandler` | _required_ | Handler methods for each operation |
+| `validateRequests`               | `boolean`                    | `true`     | Enable/disable request validation  |
+| `validateResponses`              | `boolean`                    | `true`     | Enable/disable response validation |
+| `handleRequestValidationErrors`  | `boolean \| function`        | `true`     | Handle request validation errors   |
+| `handleResponseValidationErrors` | `boolean \| function`        | `true`     | Handle response validation errors  |
+| `handleHttpResponseErrors`       | `boolean \| function`        | `true`     | Handle thrown typed HTTP responses |
+| `handleUnknownErrors`            | `boolean \| function`        | `true`     | Handle unexpected errors           |
 
 When set to `true`, error handlers use sensible defaults (400/500 responses). When set to `false`,
-errors fall through to the next handler in the chain. When set to a function, it receives the error
-and `ServerContext` and must return an `IHttpResponse`.
+errors fall through to the next handler in the chain (except `handleResponseValidationErrors`, where
+`false` means the invalid response is returned as-is — validation still runs for field stripping,
+but invalid responses pass through unchanged). When set to a function, it receives the error and
+`ServerContext` and must return an `IHttpResponse`. If a custom error handler throws, the framework
+catches the exception and falls through gracefully to the next handler.
 
 ### 🚨 Error Handling
 
 #### Throwing errors in handlers
 
-All generated error response classes (e.g. `NotFoundErrorResponse`, `ValidationErrorResponse`)
-extend `HttpResponse`. Throw them in your handlers — the framework catches them automatically:
+Throw any object matching `ITypedHttpResponse` (i.e. `{ type: string, statusCode: number, ... }`)
+from your handlers — the framework catches it automatically and returns it as the response:
 
 ```ts
 import { HttpStatusCode } from "@rexeus/typeweaver-core";
-import { GetUserSuccessResponse, NotFoundErrorResponse } from "./generated";
 
 async handleGetUserRequest(request) {
   const user = await db.findUser(request.param.userId);
   if (!user) {
-    throw new NotFoundErrorResponse({
+    // Plain objects work — anything with `type` and `statusCode` is recognized
+    throw {
+      type: "NotFoundError",
       statusCode: HttpStatusCode.NOT_FOUND,
       header: { "Content-Type": "application/json" },
       body: { message: "Resource not found", code: "NOT_FOUND_ERROR" },
-    });
+    };
   }
-  return new GetUserSuccessResponse({
+  return {
+    type: "GetUserSuccess",
     statusCode: HttpStatusCode.OK,
     header: { "Content-Type": "application/json" },
     body: user,
-  });
+  };
 }
 ```
 
-When `handleHttpResponseErrors` is `true` (the default), thrown `HttpResponse` instances are
-returned as-is. No extra configuration needed.
+Generated factory functions (e.g. `createNotFoundErrorResponse`) are a convenient shorthand — they
+set `type` and `statusCode` for you so you only pass `header` and `body`:
+
+```ts
+import { createNotFoundErrorResponse } from "./generated";
+
+throw createNotFoundErrorResponse({
+  header: { "Content-Type": "application/json" },
+  body: { message: "Resource not found", code: "NOT_FOUND_ERROR" },
+});
+```
+
+When `handleHttpResponseErrors` is `true` (the default), thrown typed HTTP responses
+(`ITypedHttpResponse`) are returned as-is. No extra configuration needed.
 
 #### Custom error mapping
 
@@ -362,21 +381,21 @@ Use custom handler functions to transform errors into your own response shape.
 ```ts
 new UserRouter({
   requestHandlers: userHandlers,
-  handleValidationErrors: (error, ctx) =>
-    new ValidationErrorResponse({
-      statusCode: HttpStatusCode.BAD_REQUEST,
-      header: { "Content-Type": "application/json" },
-      body: {
-        code: "VALIDATION_ERROR",
-        message: "Request is invalid",
-        issues: {
-          body: error.bodyIssues,
-          query: error.queryIssues,
-          param: error.pathParamIssues,
-          header: error.headerIssues,
-        },
+  handleRequestValidationErrors: (error, ctx) => ({
+    type: "ValidationError",
+    statusCode: HttpStatusCode.BAD_REQUEST,
+    header: { "Content-Type": "application/json" },
+    body: {
+      code: "VALIDATION_ERROR",
+      message: "Request is invalid",
+      issues: {
+        body: error.bodyIssues,
+        query: error.queryIssues,
+        param: error.pathParamIssues,
+        header: error.headerIssues,
       },
-    }),
+    },
+  }),
 });
 ```
 
@@ -402,25 +421,27 @@ new UserRouter({
   requestHandlers: userHandlers,
   handleUnknownErrors: (error, ctx) => {
     logger.error("Unhandled error", { error, path: ctx.request.path });
-    return new InternalServerErrorResponse({
+    return {
+      type: "InternalServerError",
       statusCode: HttpStatusCode.INTERNAL_SERVER_ERROR,
       header: { "Content-Type": "application/json" },
       body: { code: "INTERNAL_SERVER_ERROR", message: "Something went wrong" },
-    });
+    };
   },
 });
 ```
 
 ### 📋 Error Responses
 
-| Status | Code                    | When                                                          |
-| ------ | ----------------------- | ------------------------------------------------------------- |
-| `400`  | `BAD_REQUEST`           | Malformed request body                                        |
-| `400`  | Validation issues       | `handleValidationErrors: true` and request fails validation   |
-| `404`  | `NOT_FOUND`             | No matching route                                             |
-| `405`  | `METHOD_NOT_ALLOWED`    | Route exists but method not allowed (includes `Allow` header) |
-| `413`  | `PAYLOAD_TOO_LARGE`     | Request body exceeds `maxBodySize`                            |
-| `500`  | `INTERNAL_SERVER_ERROR` | Unhandled error in handler                                    |
+| Status | Code                    | When                                                                 |
+| ------ | ----------------------- | -------------------------------------------------------------------- |
+| `400`  | `BAD_REQUEST`           | Malformed request body                                               |
+| `400`  | Validation issues       | `handleRequestValidationErrors: true` and request fails validation   |
+| `404`  | `NOT_FOUND`             | No matching route                                                    |
+| `405`  | `METHOD_NOT_ALLOWED`    | Route exists but method not allowed (includes `Allow` header)        |
+| `413`  | `PAYLOAD_TOO_LARGE`     | Request body exceeds `maxBodySize`                                   |
+| `500`  | `INTERNAL_SERVER_ERROR` | `handleResponseValidationErrors: true` and response fails validation |
+| `500`  | `INTERNAL_SERVER_ERROR` | Unhandled error in handler                                           |
 
 All error responses follow the shape: `{ code: string, message: string }`.
 

package/dist/index.cjs

@@ -66,8 +66,10 @@ var RouterGenerator = class {
 		context.writeFile(relativePath, content);
 	}
 	static createOperationData(resource) {
-		const className = case$1.default.pascal(resource.definition.operationId);
+		const operationId = resource.definition.operationId;
+		const className = case$1.default.pascal(operationId);
 		return {
+			operationId,
 			className,
 			handlerName: `handle${className}Request`,
 			method: resource.definition.method,

package/dist/index.mjs

@@ -37,8 +37,10 @@ var RouterGenerator = class {
 		context.writeFile(relativePath, content);
 	}
 	static createOperationData(resource) {
-		const className = Case.pascal(resource.definition.operationId);
+		const operationId = resource.definition.operationId;
+		const className = Case.pascal(operationId);
 		return {
+			operationId,
 			className,
 			handlerName: `handle${className}Request`,
 			method: resource.definition.method,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/RouterGenerator.ts","../src/index.ts"],"sourcesContent":["import path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { HttpMethod } from \"@rexeus/typeweaver-core\";\nimport { Path } from \"@rexeus/typeweaver-gen\";\nimport type {\n  GeneratorContext,\n  OperationResource,\n} from \"@rexeus/typeweaver-gen\";\nimport Case from \"case\";\n\ntype OperationData = {\n  readonly className: string;\n  readonly handlerName: string;\n  readonly method: string;\n  readonly path: string;\n};\n\n/**\n * Generates TypeweaverRouter subclasses from API definitions.\n *\n * For each resource (e.g., `Todo`, `Account`), produces a `<ResourceName>Router.ts`\n * file that extends `TypeweaverRouter` and registers all operations as routes.\n */\nexport class RouterGenerator {\n  /**\n   * Generates router files for all resources in the given context.\n   *\n   * @param context - The generator context containing resources, templates, and output configuration\n   */\n  public static generate(context: GeneratorContext): void {\n    const moduleDir = path.dirname(fileURLToPath(import.meta.url));\n    const templateFile = path.join(moduleDir, \"templates\", \"Router.ejs\");\n\n    for (const [entityName, entityResource] of Object.entries(\n      context.resources.entityResources\n    )) {\n      this.writeRouter(\n        entityName,\n        templateFile,\n        entityResource.operations,\n        context\n      );\n    }\n  }\n\n  private static writeRouter(\n    entityName: string,\n    templateFile: string,\n    operationResources: OperationResource[],\n    context: GeneratorContext\n  ): void {\n    const pascalCaseEntityName = Case.pascal(entityName);\n    const outputDir = path.join(context.outputDir, entityName);\n    const outputPath = path.join(outputDir, `${pascalCaseEntityName}Router.ts`);\n\n    const operations = operationResources\n      .filter(resource => resource.definition.method !== HttpMethod.HEAD)\n      .map(resource => this.createOperationData(resource))\n      .sort((a, b) => this.compareRoutes(a, b));\n\n    const content = context.renderTemplate(templateFile, {\n      coreDir: Path.relative(outputDir, context.outputDir),\n      entityName,\n      pascalCaseEntityName,\n      operations,\n    });\n\n    const relativePath = path.relative(context.outputDir, outputPath);\n    context.writeFile(relativePath, content);\n  }\n\n  private static createOperationData(\n    resource: OperationResource\n  ): OperationData {\n    const className = Case.pascal(resource.definition.operationId);\n\n    return {\n      className,\n      handlerName: `handle${className}Request`,\n      method: resource.definition.method,\n      path: resource.definition.path,\n    };\n  }\n\n  private static compareRoutes(a: OperationData, b: OperationData): number {\n    const aSegments = a.path.split(\"/\").filter(s => s);\n    const bSegments = b.path.split(\"/\").filter(s => s);\n\n    // 1. Compare by depth first (shallow to deep)\n    if (aSegments.length !== bSegments.length) {\n      return aSegments.length - bSegments.length;\n    }\n\n    // 2. Compare segment by segment\n    for (let i = 0; i < aSegments.length; i++) {\n      const aSegment = aSegments[i]!;\n      const bSegment = bSegments[i]!;\n\n      const aIsParam = aSegment.startsWith(\":\");\n      const bIsParam = bSegment.startsWith(\":\");\n\n      // Static segments before parameters\n      if (aIsParam !== bIsParam) {\n        return aIsParam ? 1 : -1;\n      }\n\n      // Within same type, alphabetical order\n      if (aSegment !== bSegment) {\n        return aSegment.localeCompare(bSegment);\n      }\n    }\n\n    // 3. Same path = sort by HTTP method priority\n    return this.getMethodPriority(a.method) - this.getMethodPriority(b.method);\n  }\n\n  private static readonly METHOD_PRIORITY: Record<string, number> = {\n    GET: 1,\n    POST: 2,\n    PUT: 3,\n    PATCH: 4,\n    DELETE: 5,\n    OPTIONS: 6,\n    HEAD: 7,\n  };\n\n  private static getMethodPriority(method: string): number {\n    return this.METHOD_PRIORITY[method] ?? 999;\n  }\n}\n","import path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { BasePlugin } from \"@rexeus/typeweaver-gen\";\nimport type { GeneratorContext } from \"@rexeus/typeweaver-gen\";\nimport { RouterGenerator } from \"./RouterGenerator\";\n\nconst moduleDir = path.dirname(fileURLToPath(import.meta.url));\n\n/**\n * Typeweaver plugin that generates a lightweight, dependency-free server\n * with built-in routing and middleware support.\n *\n * Copies the runtime library files (`TypeweaverApp`, `TypeweaverRouter`, `Router`,\n * `Middleware`, etc.) and generates typed router classes for each resource.\n */\nexport default class ServerPlugin extends BasePlugin {\n  public name = \"server\";\n\n  /**\n   * Generates the server runtime and typed routers for all resources.\n   *\n   * @param context - The generator context\n   */\n  public override generate(context: GeneratorContext): void {\n    const libSourceDir = path.join(moduleDir, \"lib\");\n    this.copyLibFiles(context, libSourceDir, this.name);\n\n    RouterGenerator.generate(context);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAuBA,IAAa,kBAAb,MAA6B;;;;;;CAM3B,OAAc,SAAS,SAAiC;EACtD,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;EAC9D,MAAM,eAAe,KAAK,KAAK,WAAW,aAAa,aAAa;AAEpE,OAAK,MAAM,CAAC,YAAY,mBAAmB,OAAO,QAChD,QAAQ,UAAU,gBACnB,CACC,MAAK,YACH,YACA,cACA,eAAe,YACf,QACD;;CAIL,OAAe,YACb,YACA,cACA,oBACA,SACM;EACN,MAAM,uBAAuB,KAAK,OAAO,WAAW;EACpD,MAAM,YAAY,KAAK,KAAK,QAAQ,WAAW,WAAW;EAC1D,MAAM,aAAa,KAAK,KAAK,WAAW,GAAG,qBAAqB,WAAW;EAE3E,MAAM,aAAa,mBAChB,QAAO,aAAY,SAAS,WAAW,WAAW,WAAW,KAAK,CAClE,KAAI,aAAY,KAAK,oBAAoB,SAAS,CAAC,CACnD,MAAM,GAAG,MAAM,KAAK,cAAc,GAAG,EAAE,CAAC;EAE3C,MAAM,UAAU,QAAQ,eAAe,cAAc;GACnD,SAAS,KAAK,SAAS,WAAW,QAAQ,UAAU;GACpD;GACA;GACA;GACD,CAAC;EAEF,MAAM,eAAe,KAAK,SAAS,QAAQ,WAAW,WAAW;AACjE,UAAQ,UAAU,cAAc,QAAQ;;CAG1C,OAAe,oBACb,UACe;EACf,MAAM,YAAY,KAAK,OAAO,SAAS,WAAW,YAAY;AAE9D,SAAO;GACL;GACA,aAAa,SAAS,UAAU;GAChC,QAAQ,SAAS,WAAW;GAC5B,MAAM,SAAS,WAAW;GAC3B;;CAGH,OAAe,cAAc,GAAkB,GAA0B;EACvE,MAAM,YAAY,EAAE,KAAK,MAAM,IAAI,CAAC,QAAO,MAAK,EAAE;EAClD,MAAM,YAAY,EAAE,KAAK,MAAM,IAAI,CAAC,QAAO,MAAK,EAAE;AAGlD,MAAI,UAAU,WAAW,UAAU,OACjC,QAAO,UAAU,SAAS,UAAU;AAItC,OAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK;GACzC,MAAM,WAAW,UAAU;GAC3B,MAAM,WAAW,UAAU;GAE3B,MAAM,WAAW,SAAS,WAAW,IAAI;AAIzC,OAAI,aAHa,SAAS,WAAW,IAAI,CAIvC,QAAO,WAAW,IAAI;AAIxB,OAAI,aAAa,SACf,QAAO,SAAS,cAAc,SAAS;;AAK3C,SAAO,KAAK,kBAAkB,EAAE,OAAO,GAAG,KAAK,kBAAkB,EAAE,OAAO;;CAG5E,OAAwB,kBAA0C;EAChE,KAAK;EACL,MAAM;EACN,KAAK;EACL,OAAO;EACP,QAAQ;EACR,SAAS;EACT,MAAM;EACP;CAED,OAAe,kBAAkB,QAAwB;AACvD,SAAO,KAAK,gBAAgB,WAAW;;;;;;ACzH3C,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;AAS9D,IAAqB,eAArB,cAA0C,WAAW;CACnD,AAAO,OAAO;;;;;;CAOd,AAAgB,SAAS,SAAiC;EACxD,MAAM,eAAe,KAAK,KAAK,WAAW,MAAM;AAChD,OAAK,aAAa,SAAS,cAAc,KAAK,KAAK;AAEnD,kBAAgB,SAAS,QAAQ"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/RouterGenerator.ts","../src/index.ts"],"sourcesContent":["import path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { HttpMethod } from \"@rexeus/typeweaver-core\";\nimport { Path } from \"@rexeus/typeweaver-gen\";\nimport type {\n  GeneratorContext,\n  OperationResource,\n} from \"@rexeus/typeweaver-gen\";\nimport Case from \"case\";\n\ntype OperationData = {\n  readonly operationId: string;\n  readonly className: string;\n  readonly handlerName: string;\n  readonly method: string;\n  readonly path: string;\n};\n\n/**\n * Generates TypeweaverRouter subclasses from API definitions.\n *\n * For each resource (e.g., `Todo`, `Account`), produces a `<ResourceName>Router.ts`\n * file that extends `TypeweaverRouter` and registers all operations as routes.\n */\nexport class RouterGenerator {\n  /**\n   * Generates router files for all resources in the given context.\n   *\n   * @param context - The generator context containing resources, templates, and output configuration\n   */\n  public static generate(context: GeneratorContext): void {\n    const moduleDir = path.dirname(fileURLToPath(import.meta.url));\n    const templateFile = path.join(moduleDir, \"templates\", \"Router.ejs\");\n\n    for (const [entityName, entityResource] of Object.entries(\n      context.resources.entityResources\n    )) {\n      this.writeRouter(\n        entityName,\n        templateFile,\n        entityResource.operations,\n        context\n      );\n    }\n  }\n\n  private static writeRouter(\n    entityName: string,\n    templateFile: string,\n    operationResources: OperationResource[],\n    context: GeneratorContext\n  ): void {\n    const pascalCaseEntityName = Case.pascal(entityName);\n    const outputDir = path.join(context.outputDir, entityName);\n    const outputPath = path.join(outputDir, `${pascalCaseEntityName}Router.ts`);\n\n    const operations = operationResources\n      .filter(resource => resource.definition.method !== HttpMethod.HEAD)\n      .map(resource => this.createOperationData(resource))\n      .sort((a, b) => this.compareRoutes(a, b));\n\n    const content = context.renderTemplate(templateFile, {\n      coreDir: Path.relative(outputDir, context.outputDir),\n      entityName,\n      pascalCaseEntityName,\n      operations,\n    });\n\n    const relativePath = path.relative(context.outputDir, outputPath);\n    context.writeFile(relativePath, content);\n  }\n\n  private static createOperationData(\n    resource: OperationResource\n  ): OperationData {\n    const operationId = resource.definition.operationId;\n    const className = Case.pascal(operationId);\n\n    return {\n      operationId,\n      className,\n      handlerName: `handle${className}Request`,\n      method: resource.definition.method,\n      path: resource.definition.path,\n    };\n  }\n\n  private static compareRoutes(a: OperationData, b: OperationData): number {\n    const aSegments = a.path.split(\"/\").filter(s => s);\n    const bSegments = b.path.split(\"/\").filter(s => s);\n\n    // 1. Compare by depth first (shallow to deep)\n    if (aSegments.length !== bSegments.length) {\n      return aSegments.length - bSegments.length;\n    }\n\n    // 2. Compare segment by segment\n    for (let i = 0; i < aSegments.length; i++) {\n      const aSegment = aSegments[i]!;\n      const bSegment = bSegments[i]!;\n\n      const aIsParam = aSegment.startsWith(\":\");\n      const bIsParam = bSegment.startsWith(\":\");\n\n      // Static segments before parameters\n      if (aIsParam !== bIsParam) {\n        return aIsParam ? 1 : -1;\n      }\n\n      // Within same type, alphabetical order\n      if (aSegment !== bSegment) {\n        return aSegment.localeCompare(bSegment);\n      }\n    }\n\n    // 3. Same path = sort by HTTP method priority\n    return this.getMethodPriority(a.method) - this.getMethodPriority(b.method);\n  }\n\n  private static readonly METHOD_PRIORITY: Record<string, number> = {\n    GET: 1,\n    POST: 2,\n    PUT: 3,\n    PATCH: 4,\n    DELETE: 5,\n    OPTIONS: 6,\n    HEAD: 7,\n  };\n\n  private static getMethodPriority(method: string): number {\n    return this.METHOD_PRIORITY[method] ?? 999;\n  }\n}\n","import path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { BasePlugin } from \"@rexeus/typeweaver-gen\";\nimport type { GeneratorContext } from \"@rexeus/typeweaver-gen\";\nimport { RouterGenerator } from \"./RouterGenerator\";\n\nconst moduleDir = path.dirname(fileURLToPath(import.meta.url));\n\n/**\n * Typeweaver plugin that generates a lightweight, dependency-free server\n * with built-in routing and middleware support.\n *\n * Copies the runtime library files (`TypeweaverApp`, `TypeweaverRouter`, `Router`,\n * `Middleware`, etc.) and generates typed router classes for each resource.\n */\nexport default class ServerPlugin extends BasePlugin {\n  public name = \"server\";\n\n  /**\n   * Generates the server runtime and typed routers for all resources.\n   *\n   * @param context - The generator context\n   */\n  public override generate(context: GeneratorContext): void {\n    const libSourceDir = path.join(moduleDir, \"lib\");\n    this.copyLibFiles(context, libSourceDir, this.name);\n\n    RouterGenerator.generate(context);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAa,kBAAb,MAA6B;;;;;;CAM3B,OAAc,SAAS,SAAiC;EACtD,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;EAC9D,MAAM,eAAe,KAAK,KAAK,WAAW,aAAa,aAAa;AAEpE,OAAK,MAAM,CAAC,YAAY,mBAAmB,OAAO,QAChD,QAAQ,UAAU,gBACnB,CACC,MAAK,YACH,YACA,cACA,eAAe,YACf,QACD;;CAIL,OAAe,YACb,YACA,cACA,oBACA,SACM;EACN,MAAM,uBAAuB,KAAK,OAAO,WAAW;EACpD,MAAM,YAAY,KAAK,KAAK,QAAQ,WAAW,WAAW;EAC1D,MAAM,aAAa,KAAK,KAAK,WAAW,GAAG,qBAAqB,WAAW;EAE3E,MAAM,aAAa,mBAChB,QAAO,aAAY,SAAS,WAAW,WAAW,WAAW,KAAK,CAClE,KAAI,aAAY,KAAK,oBAAoB,SAAS,CAAC,CACnD,MAAM,GAAG,MAAM,KAAK,cAAc,GAAG,EAAE,CAAC;EAE3C,MAAM,UAAU,QAAQ,eAAe,cAAc;GACnD,SAAS,KAAK,SAAS,WAAW,QAAQ,UAAU;GACpD;GACA;GACA;GACD,CAAC;EAEF,MAAM,eAAe,KAAK,SAAS,QAAQ,WAAW,WAAW;AACjE,UAAQ,UAAU,cAAc,QAAQ;;CAG1C,OAAe,oBACb,UACe;EACf,MAAM,cAAc,SAAS,WAAW;EACxC,MAAM,YAAY,KAAK,OAAO,YAAY;AAE1C,SAAO;GACL;GACA;GACA,aAAa,SAAS,UAAU;GAChC,QAAQ,SAAS,WAAW;GAC5B,MAAM,SAAS,WAAW;GAC3B;;CAGH,OAAe,cAAc,GAAkB,GAA0B;EACvE,MAAM,YAAY,EAAE,KAAK,MAAM,IAAI,CAAC,QAAO,MAAK,EAAE;EAClD,MAAM,YAAY,EAAE,KAAK,MAAM,IAAI,CAAC,QAAO,MAAK,EAAE;AAGlD,MAAI,UAAU,WAAW,UAAU,OACjC,QAAO,UAAU,SAAS,UAAU;AAItC,OAAK,IAAI,IAAI,GAAG,IAAI,UAAU,QAAQ,KAAK;GACzC,MAAM,WAAW,UAAU;GAC3B,MAAM,WAAW,UAAU;GAE3B,MAAM,WAAW,SAAS,WAAW,IAAI;AAIzC,OAAI,aAHa,SAAS,WAAW,IAAI,CAIvC,QAAO,WAAW,IAAI;AAIxB,OAAI,aAAa,SACf,QAAO,SAAS,cAAc,SAAS;;AAK3C,SAAO,KAAK,kBAAkB,EAAE,OAAO,GAAG,KAAK,kBAAkB,EAAE,OAAO;;CAG5E,OAAwB,kBAA0C;EAChE,KAAK;EACL,MAAM;EACN,KAAK;EACL,OAAO;EACP,QAAQ;EACR,SAAS;EACT,MAAM;EACP;CAED,OAAe,kBAAkB,QAAwB;AACvD,SAAO,KAAK,gBAAgB,WAAW;;;;;;AC5H3C,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;AAS9D,IAAqB,eAArB,cAA0C,WAAW;CACnD,AAAO,OAAO;;;;;;CAOd,AAAgB,SAAS,SAAiC;EACxD,MAAM,eAAe,KAAK,KAAK,WAAW,MAAM;AAChD,OAAK,aAAa,SAAS,cAAc,KAAK,KAAK;AAEnD,kBAAgB,SAAS,QAAQ"}

package/dist/lib/Router.ts

@@ -9,18 +9,32 @@ import type {
   HttpMethod,
   IHttpResponse,
   IRequestValidator,
+  IResponseValidator,
+  ITypedHttpResponse,
   RequestValidationError,
+  ResponseValidationError,
 } from "@rexeus/typeweaver-core";
 import type { RequestHandler } from "./RequestHandler";
 import type { ServerContext } from "./ServerContext";
 
+/**
+ * Metadata about a matched route, available in middleware and handlers via `ctx.route`.
+ */
+export type RouteMetadata = {
+  readonly operationId: string;
+  readonly method: HttpMethod;
+  readonly path: string;
+};
+
 /**
  * A registered route with its method, path pattern, validator, and handler.
  */
 export type RouteDefinition = {
+  readonly operationId: string;
   readonly method: HttpMethod;
   readonly path: string;
-  readonly validator: IRequestValidator;
+  readonly requestValidator: IRequestValidator;
+  readonly responseValidator: IResponseValidator;
   readonly handler: RequestHandler<any, any, any>;
   /** Reference to the router config for error handling. */
   readonly routerConfig: RouterErrorConfig;
@@ -31,28 +45,44 @@ export type RouteDefinition = {
  */
 export type RouterErrorConfig = {
   readonly validateRequests: boolean;
+  readonly validateResponses: boolean;
   readonly handleHttpResponseErrors: HttpResponseErrorHandler | boolean;
-  readonly handleValidationErrors: ValidationErrorHandler | boolean;
+  readonly handleRequestValidationErrors:
+    | RequestValidationErrorHandler
+    | boolean;
+  readonly handleResponseValidationErrors:
+    | ResponseValidationErrorHandler
+    | boolean;
   readonly handleUnknownErrors: UnknownErrorHandler | boolean;
 };
 
 /**
  * Handles HTTP response errors thrown by request handlers.
- * The error parameter is an `HttpResponse` instance (thrown via `throw new HttpResponse(...)`).
+ * The error parameter is a typed HTTP response object (thrown via `throw { type, statusCode, ... }`).
  */
 export type HttpResponseErrorHandler = (
-  error: IHttpResponse,
+  error: ITypedHttpResponse,
   ctx: ServerContext
 ) => Promise<IHttpResponse> | IHttpResponse;
 
 /**
  * Handles request validation errors.
  */
-export type ValidationErrorHandler = (
+export type RequestValidationErrorHandler = (
   error: RequestValidationError,
   ctx: ServerContext
 ) => Promise<IHttpResponse> | IHttpResponse;
 
+/**
+ * Handles response validation errors.
+ * Called when a handler returns a response that does not match the expected schema.
+ */
+export type ResponseValidationErrorHandler = (
+  error: ResponseValidationError,
+  response: IHttpResponse,
+  ctx: ServerContext
+) => Promise<IHttpResponse> | IHttpResponse;
+
 /**
  * Handles any unknown errors not caught by other handlers.
  */

package/dist/lib/ServerContext.ts

@@ -6,6 +6,7 @@
  */
 
 import type { IHttpRequest } from "@rexeus/typeweaver-core";
+import type { RouteMetadata } from "./Router";
 import type { StateMap } from "./StateMap";
 
 /**
@@ -51,4 +52,7 @@ export type ServerContext<
 
   /** Type-safe key-value store for sharing data between middleware and handlers. */
   readonly state: StateMap<TState>;
+
+  /** Metadata about the matched route, or `undefined` for 404/405 requests. */
+  readonly route: RouteMetadata | undefined;
 };

package/dist/lib/TypeweaverApp.ts

@@ -5,7 +5,10 @@
  * @generated by @rexeus/typeweaver
  */
 
-import { HttpResponse, RequestValidationError } from "@rexeus/typeweaver-core";
+import {
+  isTypedHttpResponse,
+  RequestValidationError,
+} from "@rexeus/typeweaver-core";
 import type { IHttpResponse } from "@rexeus/typeweaver-core";
 import { BodyParseError, PayloadTooLargeError } from "./Errors";
 import { FetchApiAdapter } from "./FetchApiAdapter";
@@ -16,9 +19,11 @@ import type { Middleware } from "./Middleware";
 import type { RequestHandler } from "./RequestHandler";
 import type {
   HttpResponseErrorHandler,
+  ResponseValidationErrorHandler,
   RouteDefinition,
+  RouteMatch,
   UnknownErrorHandler,
-  ValidationErrorHandler,
+  RequestValidationErrorHandler,
 } from "./Router";
 import type { ServerContext } from "./ServerContext";
 import type { StateRequirementError, TypedMiddleware } from "./TypedMiddleware";
@@ -186,15 +191,24 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
     const url = new URL(request.url);
     const httpRequest = await this.adapter.toRequest(request, url);
 
+    const match = this.router.match(request.method, url.pathname);
+
     const ctx: ServerContext = {
       request: httpRequest,
       state: new StateMap(),
+      route: match
+        ? {
+            operationId: match.route.operationId,
+            method: match.route.method,
+            path: match.route.path,
+          }
+        : undefined,
     };
 
     const response = await executeMiddlewarePipeline(
       this.middlewares,
       ctx,
-      () => this.resolveAndExecute(request.method, url.pathname, ctx)
+      () => this.resolveAndExecute(match, url.pathname, ctx)
     );
 
     return request.method.toUpperCase() === "HEAD"
@@ -203,21 +217,26 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
   }
 
   /**
-   * Match the route and execute the handler.
+   * Execute the matched route handler, or produce 404/405 responses.
    * Called as the final handler in the middleware pipeline.
    */
   private async resolveAndExecute(
-    method: string,
+    match: RouteMatch | undefined,
     pathname: string,
     ctx: ServerContext
   ): Promise<IHttpResponse> {
-    const match = this.router.match(method, pathname);
-
     if (match) {
       const routeCtx = this.withPathParams(ctx, match.params);
       try {
-        return await this.executeHandler(routeCtx, match.route);
+        const response = await this.executeHandler(routeCtx, match.route);
+        return await this.validateResponse(match.route, response, routeCtx);
       } catch (error) {
+        if (
+          isTypedHttpResponse(error) &&
+          match.route.routerConfig.validateResponses
+        ) {
+          return await this.validateResponse(match.route, error, routeCtx);
+        }
         return this.handleError(error, routeCtx, match.route);
       }
     }
@@ -253,44 +272,123 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
     route: RouteDefinition
   ): Promise<IHttpResponse> {
     const validatedRequest = route.routerConfig.validateRequests
-      ? route.validator.validate(ctx.request)
+      ? route.requestValidator.validate(ctx.request)
       : ctx.request;
 
     return route.handler(validatedRequest, ctx);
   }
 
+  /**
+   * 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 route - The route definition containing the response validator and config
+   * @param response - The response to validate
+   * @param ctx - The server context for the current request
+   * @returns The validated (and stripped) response, the handler's response, or the original
+   */
+  private async validateResponse(
+    route: RouteDefinition,
+    response: IHttpResponse,
+    ctx: ServerContext
+  ): Promise<IHttpResponse> {
+    if (!route.routerConfig.validateResponses) return response;
+
+    const result = route.responseValidator.safeValidate(response);
+
+    if (result.isValid) return result.data;
+
+    const handler = this.resolveErrorHandler<ResponseValidationErrorHandler>(
+      route.routerConfig.handleResponseValidationErrors,
+      TypeweaverApp.defaultResponseValidationHandler
+    );
+
+    if (handler) {
+      const handlerResponse = await this.safelyExecuteErrorHandler(() =>
+        handler(result.error, response, ctx)
+      );
+      if (handlerResponse) return handlerResponse;
+    }
+
+    return response;
+  }
+
+  /**
+   * Safely executes an error handler and returns null if it fails.
+   * This allows for graceful fallback to the next handler in the chain
+   * without crashing the request pipeline.
+   *
+   * If the handler throws, the error is reported via `safeOnError`
+   * and null is returned so the caller can fall through to the next handler.
+   *
+   * @param handlerFn - Function that executes the error handler
+   * @returns The handler's response if successful, null if the handler throws
+   */
+  private async safelyExecuteErrorHandler(
+    handlerFn: () => Promise<IHttpResponse> | IHttpResponse
+  ): Promise<IHttpResponse | null> {
+    try {
+      return await handlerFn();
+    } catch (error) {
+      this.safeOnError(error);
+      return null;
+    }
+  }
+
   /**
    * Handle errors using the route's configured error handlers.
-   * Handler errors bubble up to the safety net in `fetch()`.
    */
-  private handleError(
+  private async handleError(
     error: unknown,
     ctx: ServerContext,
     route: RouteDefinition
-  ): IHttpResponse | Promise<IHttpResponse> {
+  ): Promise<IHttpResponse> {
     const config = route.routerConfig;
 
     if (error instanceof RequestValidationError) {
-      const handler = this.resolveErrorHandler<ValidationErrorHandler>(
-        config.handleValidationErrors,
-        TypeweaverApp.defaultValidationHandler
+      const handler = this.resolveErrorHandler<RequestValidationErrorHandler>(
+        config.handleRequestValidationErrors,
+        TypeweaverApp.defaultRequestValidationHandler
       );
-      if (handler) return handler(error, ctx);
+      if (handler) {
+        const response = await this.safelyExecuteErrorHandler(() =>
+          handler(error, ctx)
+        );
+        if (response) return response;
+      }
     }
 
-    if (error instanceof HttpResponse) {
+    if (isTypedHttpResponse(error)) {
       const handler = this.resolveErrorHandler<HttpResponseErrorHandler>(
         config.handleHttpResponseErrors,
         TypeweaverApp.defaultHttpResponseHandler
       );
-      if (handler) return handler(error, ctx);
+      if (handler) {
+        const response = await this.safelyExecuteErrorHandler(() =>
+          handler(error, ctx)
+        );
+        if (response) return response;
+      }
     }
 
     const handler = this.resolveErrorHandler<UnknownErrorHandler>(
       config.handleUnknownErrors,
       this.defaultUnknownHandler
     );
-    if (handler) return handler(error, ctx);
+    if (handler) {
+      const response = await this.safelyExecuteErrorHandler(() =>
+        handler(error, ctx)
+      );
+      if (response) return response;
+    }
 
     throw error;
   }
@@ -331,30 +429,35 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
     return issues.map(({ message, path }) => ({ message, path }));
   }
 
-  private static defaultValidationHandler: ValidationErrorHandler = (
-    err
-  ): IHttpResponse => {
-    const issues: Record<string, unknown> = Object.create(null);
+  private static defaultRequestValidationHandler: RequestValidationErrorHandler =
+    (err): IHttpResponse => {
+      const issues: Record<string, unknown> = Object.create(null);
 
-    const header = TypeweaverApp.sanitizeIssues(err.headerIssues);
-    const body = TypeweaverApp.sanitizeIssues(err.bodyIssues);
-    const query = TypeweaverApp.sanitizeIssues(err.queryIssues);
-    const param = TypeweaverApp.sanitizeIssues(err.pathParamIssues);
+      const header = TypeweaverApp.sanitizeIssues(err.headerIssues);
+      const body = TypeweaverApp.sanitizeIssues(err.bodyIssues);
+      const query = TypeweaverApp.sanitizeIssues(err.queryIssues);
+      const param = TypeweaverApp.sanitizeIssues(err.pathParamIssues);
 
-    if (header) issues.header = header;
-    if (body) issues.body = body;
-    if (query) issues.query = query;
-    if (param) issues.param = param;
+      if (header) issues.header = header;
+      if (body) issues.body = body;
+      if (query) issues.query = query;
+      if (param) issues.param = param;
 
-    return {
-      statusCode: 400,
-      body: {
-        code: "VALIDATION_ERROR",
-        message: err.message,
-        issues,
-      },
+      return {
+        statusCode: 400,
+        body: {
+          code: "VALIDATION_ERROR",
+          message: err.message,
+          issues,
+        },
+      };
     };
-  };
+
+  private static defaultResponseValidationHandler: ResponseValidationErrorHandler =
+    (): IHttpResponse => ({
+      statusCode: 500,
+      body: TypeweaverApp.INTERNAL_SERVER_ERROR_BODY,
+    });
 
   private static defaultHttpResponseHandler: HttpResponseErrorHandler = (
     err

package/dist/lib/TypeweaverRouter.ts

@@ -7,14 +7,19 @@
  * @generated by @rexeus/typeweaver
  */
 
-import type { HttpMethod, IRequestValidator } from "@rexeus/typeweaver-core";
+import type {
+  HttpMethod,
+  IRequestValidator,
+  IResponseValidator,
+} from "@rexeus/typeweaver-core";
 import type { RequestHandler } from "./RequestHandler";
 import type {
   HttpResponseErrorHandler,
+  ResponseValidationErrorHandler,
   RouteDefinition,
   RouterErrorConfig,
   UnknownErrorHandler,
-  ValidationErrorHandler,
+  RequestValidationErrorHandler,
 } from "./Router";
 
 /**
@@ -39,22 +44,42 @@ export type TypeweaverRouterOptions<
   readonly validateRequests?: boolean;
 
   /**
-   * Configure handling of HttpResponse errors thrown by handlers.
-   * - `true`: Use default handler (returns the error as response)
-   * - `false`: Disable this handler (errors fall through to the unknown error handler)
-   * - `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
    */
-  readonly handleHttpResponseErrors?: HttpResponseErrorHandler | boolean;
+  readonly validateResponses?: boolean;
 
   /**
    * Configure handling of request validation errors.
    * - `true`: Use default handler (400 with error details)
    * - `false`: Disable this handler (errors fall through to the unknown error handler)
+   * - `function`: Use custom request validation error handler
+   * @default true
+   */
+  readonly handleRequestValidationErrors?:
+    | RequestValidationErrorHandler
+    | 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?:
+    | ResponseValidationErrorHandler
+    | boolean;
+
+  /**
+   * Configure handling of HttpResponse errors thrown by handlers.
+   * - `true`: Use default handler (returns the error as response)
+   * - `false`: Disable this handler (errors fall through to the unknown error handler)
    * - `function`: Use custom error handler
    * @default true
    */
-  readonly handleValidationErrors?: ValidationErrorHandler | boolean;
+  readonly handleHttpResponseErrors?: HttpResponseErrorHandler | boolean;
 
   /**
    * Configure handling of unknown errors.
@@ -91,8 +116,10 @@ export abstract class TypeweaverRouter<
     const {
       requestHandlers,
       validateRequests = true,
+      validateResponses = true,
       handleHttpResponseErrors = true,
-      handleValidationErrors = true,
+      handleRequestValidationErrors = true,
+      handleResponseValidationErrors = true,
       handleUnknownErrors = true,
     } = options;
 
@@ -100,8 +127,10 @@ export abstract class TypeweaverRouter<
 
     this.errorConfig = {
       validateRequests,
+      validateResponses,
       handleHttpResponseErrors,
-      handleValidationErrors,
+      handleRequestValidationErrors,
+      handleResponseValidationErrors,
       handleUnknownErrors,
     };
   }
@@ -109,21 +138,27 @@ export abstract class TypeweaverRouter<
   /**
    * Register a route. Called by generated subclasses in their constructor.
    *
+   * @param operationId - Unique operation identifier from the API definition
    * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
    * @param path - Path pattern with `:param` placeholders
    * @param validator - Request validator for this operation
+   * @param responseValidator - Response validator for this operation
    * @param handler - Type-safe request handler
    */
   protected route(
+    operationId: string,
     method: HttpMethod,
     path: string,
-    validator: IRequestValidator,
+    requestValidator: IRequestValidator,
+    responseValidator: IResponseValidator,
     handler: RequestHandler<any, any, any>
   ): void {
     this.routes.push({
+      operationId,
       method,
       path,
-      validator,
+      requestValidator,
+      responseValidator,
       handler,
       routerConfig: this.errorConfig,
     });

package/dist/lib/index.ts

@@ -15,8 +15,10 @@ export {
 export { HttpMethod } from "@rexeus/typeweaver-core";
 export type {
   HttpResponseErrorHandler,
+  RequestValidationErrorHandler,
+  ResponseValidationErrorHandler,
+  RouteMetadata,
   UnknownErrorHandler,
-  ValidationErrorHandler,
 } from "./Router";
 export type { ServerContext } from "./ServerContext";
 export type { RequestHandler } from "./RequestHandler";

package/dist/templates/Router.ejs

@@ -11,6 +11,7 @@ import { HttpMethod, TypeweaverRouter, type RequestHandler, type TypeweaverRoute
 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 Server<%- pascalCaseEntityName %>ApiHandler<
@@ -32,9 +33,11 @@ export class <%- pascalCaseEntityName %>Router<
   protected setupRoutes(): void {
 <% for (const operation of operations) { %>
     this.route(
+      '<%- operation.operationId %>',
       HttpMethod.<%- operation.method %>,
       '<%- operation.path %>',
       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-server",
-  "version": "0.6.5",
+  "version": "0.8.0",
   "description": "Generates a lightweight, dependency-free server with built-in routing and middleware from your API definitions. Powered by Typeweaver.",
   "type": "module",
   "sideEffects": false,
@@ -47,21 +47,21 @@
   },
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
-    "@rexeus/typeweaver-core": "^0.6.5",
-    "@rexeus/typeweaver-gen": "^0.6.5"
+    "@rexeus/typeweaver-gen": "^0.8.0",
+    "@rexeus/typeweaver-core": "^0.8.0"
   },
   "devDependencies": {
     "get-port": "^7.1.0",
     "test-utils": "file:../test-utils",
     "tsx": "^4.21.0",
-    "@rexeus/typeweaver-core": "^0.6.5",
-    "@rexeus/typeweaver-gen": "^0.6.5"
+    "@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",