@rexeus/typeweaver-server 0.10.4 → 0.11.0

package/README.md

@@ -294,10 +294,10 @@ Each middleware is documented in detail — click the links above.
 
 `TypeweaverApp` accepts an optional options object:
 
-| Option        | Type                       | Default            | Description                                                 |
-| ------------- | -------------------------- | ------------------ | ----------------------------------------------------------- |
-| `maxBodySize` | `number`                   | `1_048_576` (1 MB) | Max request body size in bytes. Exceeding returns `413`.    |
-| `onError`     | `(error: unknown) => void` | `console.error`    | Error callback. Falls back to `console.error` if it throws. |
+| Option        | Type                       | Default            | Description                                                                                                           |
+| ------------- | -------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `maxBodySize` | `number`                   | `1_048_576` (1 MB) | Max request body size in bytes. Exceeding returns `413`.                                                              |
+| `onError`     | `(error: unknown) => void` | `console.error`    | Reports errors from the default unknown handler and top-level safety net. Falls back to `console.error` if it throws. |
 
 ```ts
 const app = new TypeweaverApp({
@@ -325,7 +325,7 @@ errors fall through to the next handler in the chain (except `handleResponseVali
 `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.
+reports that handler failure through `onError` and falls through gracefully to the next handler.
 
 ### 🚨 Error Handling
 
@@ -431,6 +431,12 @@ new UserRouter({
 });
 ```
 
+The default unknown-error handler calls `onError` before returning a sanitized 500 response. A
+custom `handleUnknownErrors` function replaces that default reporting strategy; if you need logging
+or metrics with a custom unknown handler, perform that reporting inside the custom handler. If the
+custom unknown handler throws, Typeweaver reports the handler failure through `onError` and then
+falls through to the top-level safety net.
+
 ### 📋 Error Responses
 
 | Status | Code                    | When                                                                 |

package/dist/index.cjs

@@ -61,10 +61,12 @@ function writeRouter(resource, templateFile, context) {
 function createOperationData(operation) {
 	const operationId = operation.operationId;
 	const className = (0, polycase.pascalCase)(operationId);
+	const jsDoc = (0, _rexeus_typeweaver_gen.createJSDocComment)(operation.summary, { indentation: "  " });
 	return {
 		operationId,
 		className,
 		handlerName: `handle${className}Request`,
+		...jsDoc ? { jsDoc } : {},
 		method: operation.method,
 		path: operation.path
 	};

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { BasePlugin, compareRoutes, relative } from "@rexeus/typeweaver-gen";
+import { BasePlugin, compareRoutes, createJSDocComment, relative } from "@rexeus/typeweaver-gen";
 import { HttpMethod } from "@rexeus/typeweaver-core";
 import { pascalCase } from "polycase";
 //#region src/routerGenerator.ts
@@ -37,10 +37,12 @@ function writeRouter(resource, templateFile, context) {
 function createOperationData(operation) {
 	const operationId = operation.operationId;
 	const className = pascalCase(operationId);
+	const jsDoc = createJSDocComment(operation.summary, { indentation: "  " });
 	return {
 		operationId,
 		className,
 		handlerName: `handle${className}Request`,
+		...jsDoc ? { jsDoc } : {},
 		method: operation.method,
 		path: operation.path
 	};

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 { compareRoutes, relative } from \"@rexeus/typeweaver-gen\";\nimport type {\n  GeneratorContext,\n  NormalizedOperation,\n  NormalizedResource,\n} from \"@rexeus/typeweaver-gen\";\nimport { pascalCase } from \"polycase\";\n\nexport type RouterGenerationContext = Pick<\n  GeneratorContext,\n  | \"normalizedSpec\"\n  | \"outputDir\"\n  | \"getResourceOutputDir\"\n  | \"renderTemplate\"\n  | \"writeFile\"\n>;\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 */\n\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 */\nexport function generate(context: RouterGenerationContext): void {\n  const moduleDir = path.dirname(fileURLToPath(import.meta.url));\n  const templateFile = path.join(moduleDir, \"templates\", \"Router.ejs\");\n\n  for (const resource of context.normalizedSpec.resources) {\n    writeRouter(resource, templateFile, context);\n  }\n}\n\nfunction writeRouter(\n  resource: NormalizedResource,\n  templateFile: string,\n  context: RouterGenerationContext\n): void {\n  const pascalCaseEntityName = pascalCase(resource.name);\n  const outputDir = context.getResourceOutputDir(resource.name);\n  const outputPath = path.join(outputDir, `${pascalCaseEntityName}Router.ts`);\n\n  const operations = resource.operations\n    .filter(operation => operation.method !== HttpMethod.HEAD)\n    .map(operation => createOperationData(operation))\n    .sort((a, b) => compareRoutes(a, b));\n\n  const content = context.renderTemplate(templateFile, {\n    coreDir: relative(outputDir, context.outputDir),\n    entityName: resource.name,\n    pascalCaseEntityName,\n    operations,\n  });\n\n  const relativePath = path.relative(context.outputDir, outputPath);\n  context.writeFile(relativePath, content);\n}\n\nfunction createOperationData(operation: NormalizedOperation): OperationData {\n  const operationId = operation.operationId;\n  const className = pascalCase(operationId);\n\n  return {\n    operationId,\n    className,\n    handlerName: `handle${className}Request`,\n    method: operation.method,\n    path: operation.path,\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 { generate as generateRouters } from \"./routerGenerator.js\";\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 class ServerPlugin extends BasePlugin {\n  public name = \"server\";\n  public override depends = [\"types\"];\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    generateRouters(context);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwCA,SAAgB,SAAS,SAAwC;CAC/D,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;CAC9D,MAAM,eAAe,KAAK,KAAK,WAAW,aAAa,aAAa;AAEpE,MAAK,MAAM,YAAY,QAAQ,eAAe,UAC5C,aAAY,UAAU,cAAc,QAAQ;;AAIhD,SAAS,YACP,UACA,cACA,SACM;CACN,MAAM,uBAAuB,WAAW,SAAS,KAAK;CACtD,MAAM,YAAY,QAAQ,qBAAqB,SAAS,KAAK;CAC7D,MAAM,aAAa,KAAK,KAAK,WAAW,GAAG,qBAAqB,WAAW;CAE3E,MAAM,aAAa,SAAS,WACzB,QAAO,cAAa,UAAU,WAAW,WAAW,KAAK,CACzD,KAAI,cAAa,oBAAoB,UAAU,CAAC,CAChD,MAAM,GAAG,MAAM,cAAc,GAAG,EAAE,CAAC;CAEtC,MAAM,UAAU,QAAQ,eAAe,cAAc;EACnD,SAAS,SAAS,WAAW,QAAQ,UAAU;EAC/C,YAAY,SAAS;EACrB;EACA;EACD,CAAC;CAEF,MAAM,eAAe,KAAK,SAAS,QAAQ,WAAW,WAAW;AACjE,SAAQ,UAAU,cAAc,QAAQ;;AAG1C,SAAS,oBAAoB,WAA+C;CAC1E,MAAM,cAAc,UAAU;CAC9B,MAAM,YAAY,WAAW,YAAY;AAEzC,QAAO;EACL;EACA;EACA,aAAa,SAAS,UAAU;EAChC,QAAQ,UAAU;EAClB,MAAM,UAAU;EACjB;;;;AC9EH,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;AAS9D,IAAa,eAAb,cAAkC,WAAW;CAC3C,OAAc;CACd,UAA0B,CAAC,QAAQ;;;;;;CAOnC,SAAyB,SAAiC;EACxD,MAAM,eAAe,KAAK,KAAK,WAAW,MAAM;AAChD,OAAK,aAAa,SAAS,cAAc,KAAK,KAAK;AAEnD,WAAgB,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 {\n  compareRoutes,\n  createJSDocComment,\n  relative,\n} from \"@rexeus/typeweaver-gen\";\nimport type {\n  GeneratorContext,\n  NormalizedOperation,\n  NormalizedResource,\n} from \"@rexeus/typeweaver-gen\";\nimport { pascalCase } from \"polycase\";\n\nexport type RouterGenerationContext = Pick<\n  GeneratorContext,\n  | \"normalizedSpec\"\n  | \"outputDir\"\n  | \"getResourceOutputDir\"\n  | \"renderTemplate\"\n  | \"writeFile\"\n>;\n\ntype OperationData = {\n  readonly operationId: string;\n  readonly className: string;\n  readonly handlerName: string;\n  readonly jsDoc?: 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 */\n\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 */\nexport function generate(context: RouterGenerationContext): void {\n  const moduleDir = path.dirname(fileURLToPath(import.meta.url));\n  const templateFile = path.join(moduleDir, \"templates\", \"Router.ejs\");\n\n  for (const resource of context.normalizedSpec.resources) {\n    writeRouter(resource, templateFile, context);\n  }\n}\n\nfunction writeRouter(\n  resource: NormalizedResource,\n  templateFile: string,\n  context: RouterGenerationContext\n): void {\n  const pascalCaseEntityName = pascalCase(resource.name);\n  const outputDir = context.getResourceOutputDir(resource.name);\n  const outputPath = path.join(outputDir, `${pascalCaseEntityName}Router.ts`);\n\n  const operations = resource.operations\n    .filter(operation => operation.method !== HttpMethod.HEAD)\n    .map(operation => createOperationData(operation))\n    .sort((a, b) => compareRoutes(a, b));\n\n  const content = context.renderTemplate(templateFile, {\n    coreDir: relative(outputDir, context.outputDir),\n    entityName: resource.name,\n    pascalCaseEntityName,\n    operations,\n  });\n\n  const relativePath = path.relative(context.outputDir, outputPath);\n  context.writeFile(relativePath, content);\n}\n\nfunction createOperationData(operation: NormalizedOperation): OperationData {\n  const operationId = operation.operationId;\n  const className = pascalCase(operationId);\n  const jsDoc = createJSDocComment(operation.summary, { indentation: \"  \" });\n\n  return {\n    operationId,\n    className,\n    handlerName: `handle${className}Request`,\n    ...(jsDoc ? { jsDoc } : {}),\n    method: operation.method,\n    path: operation.path,\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 { generate as generateRouters } from \"./routerGenerator.js\";\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 class ServerPlugin extends BasePlugin {\n  public name = \"server\";\n  public override depends = [\"types\"];\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    generateRouters(context);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA6CA,SAAgB,SAAS,SAAwC;CAC/D,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;CAC9D,MAAM,eAAe,KAAK,KAAK,WAAW,aAAa,aAAa;AAEpE,MAAK,MAAM,YAAY,QAAQ,eAAe,UAC5C,aAAY,UAAU,cAAc,QAAQ;;AAIhD,SAAS,YACP,UACA,cACA,SACM;CACN,MAAM,uBAAuB,WAAW,SAAS,KAAK;CACtD,MAAM,YAAY,QAAQ,qBAAqB,SAAS,KAAK;CAC7D,MAAM,aAAa,KAAK,KAAK,WAAW,GAAG,qBAAqB,WAAW;CAE3E,MAAM,aAAa,SAAS,WACzB,QAAO,cAAa,UAAU,WAAW,WAAW,KAAK,CACzD,KAAI,cAAa,oBAAoB,UAAU,CAAC,CAChD,MAAM,GAAG,MAAM,cAAc,GAAG,EAAE,CAAC;CAEtC,MAAM,UAAU,QAAQ,eAAe,cAAc;EACnD,SAAS,SAAS,WAAW,QAAQ,UAAU;EAC/C,YAAY,SAAS;EACrB;EACA;EACD,CAAC;CAEF,MAAM,eAAe,KAAK,SAAS,QAAQ,WAAW,WAAW;AACjE,SAAQ,UAAU,cAAc,QAAQ;;AAG1C,SAAS,oBAAoB,WAA+C;CAC1E,MAAM,cAAc,UAAU;CAC9B,MAAM,YAAY,WAAW,YAAY;CACzC,MAAM,QAAQ,mBAAmB,UAAU,SAAS,EAAE,aAAa,MAAM,CAAC;AAE1E,QAAO;EACL;EACA;EACA,aAAa,SAAS,UAAU;EAChC,GAAI,QAAQ,EAAE,OAAO,GAAG,EAAE;EAC1B,QAAQ,UAAU;EAClB,MAAM,UAAU;EACjB;;;;ACrFH,MAAM,YAAY,KAAK,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC;;;;;;;;AAS9D,IAAa,eAAb,cAAkC,WAAW;CAC3C,OAAc;CACd,UAA0B,CAAC,QAAQ;;;;;;CAOnC,SAAyB,SAAiC;EACxD,MAAM,eAAe,KAAK,KAAK,WAAW,MAAM;AAChD,OAAK,aAAa,SAAS,cAAc,KAAK,KAAK;AAEnD,WAAgB,QAAQ"}

package/dist/lib/Middleware.ts

@@ -6,6 +6,7 @@
  */
 
 import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import { MiddlewareNextAlreadyCalledError } from "./errors/index.js";
 import type { ServerContext } from "./ServerContext.js";
 
 /**
@@ -52,7 +53,7 @@ export async function executeMiddlewarePipeline(
 
       return middlewares[currentIndex]!(ctx, async state => {
         if (called) {
-          throw new Error("next() called multiple times");
+          throw new MiddlewareNextAlreadyCalledError(currentIndex);
         }
         called = true;
 

package/dist/lib/NodeAdapter.ts

@@ -19,8 +19,10 @@ import {
 } from "./BodyLimitPolicy.js";
 import {
   PayloadTooLargeError,
+  RequestBodyClosedBeforeEndError,
   RequestBodyDrainTimeoutError,
-} from "./Errors.js";
+  RequestBodyReadAbortedError,
+} from "./errors/index.js";
 import {
   getTypeweaverAppErrorReporter,
   getTypeweaverAppRuntimeContext,
@@ -648,12 +650,14 @@ function collectBody(
     };
 
     const handleAborted = (): void => {
-      rejectOnce(new Error("Request aborted while reading body"));
+      rejectOnce(new RequestBodyReadAbortedError(totalBytes, maxBodySize));
     };
 
     const handleClose = (): void => {
       if (!req.readableEnded) {
-        rejectOnce(new Error("Request closed before body was fully read"));
+        rejectOnce(
+          new RequestBodyClosedBeforeEndError(totalBytes, maxBodySize)
+        );
       }
     };
 

package/dist/lib/Router.ts

@@ -14,6 +14,10 @@ import type {
   RequestValidationError,
   ResponseValidationError,
 } from "@rexeus/typeweaver-core";
+import {
+  ConflictingPathParameterNameError,
+  DuplicateRouteRegistrationError,
+} from "./errors/index.js";
 import type { RequestHandler } from "./RequestHandler.js";
 import type { ServerContext } from "./ServerContext.js";
 
@@ -148,8 +152,10 @@ export class Router {
       if (segment.startsWith(":")) {
         const paramName = segment.slice(1);
         if (current.paramChild && current.paramChild.name !== paramName) {
-          throw new Error(
-            `Conflicting path parameter names at "${definition.path}": ":${current.paramChild.name}" vs ":${paramName}"`
+          throw new ConflictingPathParameterNameError(
+            definition.path,
+            current.paramChild.name,
+            paramName
           );
         }
         if (!current.paramChild) {
@@ -167,9 +173,7 @@ export class Router {
     }
 
     if (current.methods.has(method)) {
-      throw new Error(
-        `Route conflict: ${method} ${definition.path} is already registered`
-      );
+      throw new DuplicateRouteRegistrationError(method, definition.path);
     }
 
     current.methods.set(method, normalizedDefinition);

package/dist/lib/TypeweaverApp.ts

@@ -21,7 +21,11 @@ import {
   validationDefaultError,
 } from "@rexeus/typeweaver-core";
 import type { IHttpResponse } from "@rexeus/typeweaver-core";
-import { BodyParseError, PayloadTooLargeError } from "./Errors.js";
+import {
+  BodyParseError,
+  MissingRouterForPrefixedMountError,
+  PayloadTooLargeError,
+} from "./errors/index.js";
 import { executeMiddlewarePipeline } from "./Middleware.js";
 import { Router } from "./Router.js";
 import { StateMap } from "./StateMap.js";
@@ -154,7 +158,7 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
   ): this {
     if (typeof prefixOrRouter === "string") {
       if (!router) {
-        throw new Error("Router is required when mounting with a prefix");
+        throw new MissingRouterForPrefixedMountError(prefixOrRouter);
       }
       return this.mountRouter(router, prefixOrRouter);
     }
@@ -248,16 +252,6 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
           routeCtx
         );
       } catch (error) {
-        if (
-          isTypedHttpResponse(error) &&
-          match.route.routerConfig.validateResponses
-        ) {
-          return await this.validateResponse(
-            match.route,
-            toHttpResponse(error),
-            routeCtx
-          );
-        }
         return this.handleError(error, routeCtx, match.route);
       }
     }
@@ -395,7 +389,13 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
         const response = await this.safelyExecuteErrorHandler(() =>
           handler(error, ctx)
         );
-        if (response) return response;
+        if (response) {
+          return await this.validateResponse(
+            route,
+            normalizeHttpResponse(response),
+            ctx
+          );
+        }
       }
     }
 
@@ -407,7 +407,10 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
       const response = await this.safelyExecuteErrorHandler(() =>
         handler(error, ctx)
       );
-      if (response) return response;
+      if (response) {
+        this.safeOnError(error);
+        return response;
+      }
     }
 
     throw error;
@@ -481,9 +484,8 @@ export class TypeweaverApp<TState extends Record<string, unknown> = {}> {
   ): IHttpResponse => toHttpResponse(err);
 
   private readonly defaultUnknownHandler: UnknownErrorHandler = (
-    error
+    _error
   ): IHttpResponse => {
-    this.safeOnError(error);
     return {
       statusCode: internalServerErrorDefaultError.statusCode,
       body: TypeweaverApp.INTERNAL_SERVER_ERROR_BODY,

package/dist/lib/errors/ConflictingPathParameterNameError.ts

@@ -0,0 +1,20 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class ConflictingPathParameterNameError extends Error {
+  public override readonly name = "ConflictingPathParameterNameError";
+
+  public constructor(
+    public readonly path: string,
+    public readonly existingParameterName: string,
+    public readonly conflictingParameterName: string
+  ) {
+    super(
+      `Conflicting path parameter names in '${path}': existing parameter ':${existingParameterName}' conflicts with ':${conflictingParameterName}' at the same route position.`
+    );
+  }
+}

package/dist/lib/errors/DuplicateRouteRegistrationError.ts

@@ -0,0 +1,19 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class DuplicateRouteRegistrationError extends Error {
+  public override readonly name = "DuplicateRouteRegistrationError";
+
+  public constructor(
+    public readonly method: string,
+    public readonly path: string
+  ) {
+    super(
+      `Duplicate route registration refused: ${method} ${path} is already registered.`
+    );
+  }
+}

package/dist/lib/errors/MiddlewareNextAlreadyCalledError.ts

@@ -0,0 +1,16 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class MiddlewareNextAlreadyCalledError extends Error {
+  public override readonly name = "MiddlewareNextAlreadyCalledError";
+
+  public constructor(public readonly middlewareIndex: number) {
+    super(
+      `Middleware at index ${middlewareIndex} called next() more than once.`
+    );
+  }
+}

package/dist/lib/errors/MissingRouterForPrefixedMountError.ts

@@ -0,0 +1,16 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class MissingRouterForPrefixedMountError extends Error {
+  public override readonly name = "MissingRouterForPrefixedMountError";
+
+  public constructor(public readonly prefix: string) {
+    super(
+      `Router is required when mounting with prefix '${prefix}'. Pass both a prefix and a Typeweaver router instance.`
+    );
+  }
+}

package/dist/lib/errors/RequestBodyClosedBeforeEndError.ts

@@ -0,0 +1,19 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class RequestBodyClosedBeforeEndError extends Error {
+  public override readonly name = "RequestBodyClosedBeforeEndError";
+
+  public constructor(
+    public readonly bytesRead: number,
+    public readonly maxBodySize: number
+  ) {
+    super(
+      `Request closed before the body finished reading after ${bytesRead} bytes; maximum allowed body size is ${maxBodySize} bytes.`
+    );
+  }
+}

package/dist/lib/errors/RequestBodyReadAbortedError.ts

@@ -0,0 +1,19 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export class RequestBodyReadAbortedError extends Error {
+  public override readonly name = "RequestBodyReadAbortedError";
+
+  public constructor(
+    public readonly bytesRead: number,
+    public readonly maxBodySize: number
+  ) {
+    super(
+      `Request was aborted while reading the body after ${bytesRead} bytes; maximum allowed body size is ${maxBodySize} bytes.`
+    );
+  }
+}

package/dist/lib/errors/index.ts

@@ -0,0 +1,19 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+export {
+  BodyParseError,
+  PayloadTooLargeError,
+  RequestBodyDrainTimeoutError,
+  ResponseSerializationError,
+} from "../Errors.js";
+export { ConflictingPathParameterNameError } from "./ConflictingPathParameterNameError.js";
+export { DuplicateRouteRegistrationError } from "./DuplicateRouteRegistrationError.js";
+export { MiddlewareNextAlreadyCalledError } from "./MiddlewareNextAlreadyCalledError.js";
+export { MissingRouterForPrefixedMountError } from "./MissingRouterForPrefixedMountError.js";
+export { RequestBodyClosedBeforeEndError } from "./RequestBodyClosedBeforeEndError.js";
+export { RequestBodyReadAbortedError } from "./RequestBodyReadAbortedError.js";

package/dist/lib/middleware/cors.ts

@@ -1,4 +1,4 @@
-import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import type { IHttpRequest, IHttpResponse } from "@rexeus/typeweaver-core";
 import { defineMiddleware } from "../TypedMiddleware.js";
 import {
   hasHeaderName,
@@ -36,6 +36,33 @@ const POLICY_CONTROLLED_CORS_HEADERS = new Set([
   "access-control-max-age",
 ]);
 
+type NormalizedCorsOptions = {
+  readonly origin: CorsOptions["origin"];
+  readonly allowMethods: string;
+  readonly allowHeaders: readonly string[] | undefined;
+  readonly exposeHeaders: string | undefined;
+  readonly maxAge: string | undefined;
+  readonly credentials: boolean;
+};
+
+type CorsRequest = {
+  readonly header: IHttpRequest["header"];
+  readonly method: IHttpRequest["method"];
+  readonly hasOrigin: boolean;
+  readonly origin: string | undefined;
+};
+
+function normalizeCorsOptions(options?: CorsOptions): NormalizedCorsOptions {
+  return {
+    origin: options?.origin,
+    allowMethods: (options?.allowMethods ?? DEFAULT_METHODS).join(", "),
+    allowHeaders: options?.allowHeaders,
+    exposeHeaders: options?.exposeHeaders?.join(", "),
+    maxAge: options?.maxAge?.toString(),
+    credentials: options?.credentials ?? false,
+  };
+}
+
 function resolveOrigin(
   configOrigin: CorsOptions["origin"],
   requestOrigin: string | undefined,
@@ -65,6 +92,15 @@ function getRequestOrigin(
   return readSingletonHeader(header, "origin");
 }
 
+function readCorsRequest(request: IHttpRequest): CorsRequest {
+  return {
+    header: request.header,
+    method: request.method,
+    hasOrigin: hasHeaderName(request.header, "origin"),
+    origin: getRequestOrigin(request.header),
+  };
+}
+
 function isOriginDependentWithoutRequestOrigin(
   configOrigin: CorsOptions["origin"],
   credentials: boolean
@@ -76,6 +112,97 @@ function isOriginDependentWithoutRequestOrigin(
   );
 }
 
+function resolveRequestOrigin(
+  options: NormalizedCorsOptions,
+  request: CorsRequest
+): string | undefined {
+  if (request.hasOrigin && request.origin === undefined) {
+    return undefined;
+  }
+
+  const resolvedOrigin = resolveOrigin(
+    options.origin,
+    request.origin,
+    options.credentials
+  );
+
+  return options.credentials && resolvedOrigin === "*"
+    ? undefined
+    : resolvedOrigin;
+}
+
+function shouldVaryDeniedCorsResponse(
+  options: NormalizedCorsOptions,
+  request: CorsRequest
+): boolean {
+  return (
+    request.hasOrigin ||
+    isOriginDependentWithoutRequestOrigin(options.origin, options.credentials)
+  );
+}
+
+function buildSimpleCorsHeaders(
+  options: NormalizedCorsOptions,
+  origin: string
+): Record<string, string> {
+  const corsHeaders: Record<string, string> = {
+    "access-control-allow-origin": origin,
+  };
+
+  if (options.credentials) {
+    corsHeaders["access-control-allow-credentials"] = "true";
+  }
+
+  if (origin !== "*") {
+    corsHeaders["vary"] = "Origin";
+  }
+
+  if (options.exposeHeaders) {
+    corsHeaders["access-control-expose-headers"] = options.exposeHeaders;
+  }
+
+  return corsHeaders;
+}
+
+function isPreflightCorsRequest(request: CorsRequest): boolean {
+  return (
+    request.method === "OPTIONS" &&
+    request.origin !== undefined &&
+    readSingletonHeader(request.header, "access-control-request-method") !==
+      undefined
+  );
+}
+
+function buildPreflightCorsHeaders(
+  options: NormalizedCorsOptions,
+  request: CorsRequest,
+  simpleCorsHeaders: Record<string, string>
+): Record<string, string> {
+  const corsHeaders = { ...simpleCorsHeaders };
+  corsHeaders["access-control-allow-methods"] = options.allowMethods;
+
+  if (options.allowHeaders !== undefined) {
+    if (options.allowHeaders.length > 0) {
+      corsHeaders["access-control-allow-headers"] =
+        options.allowHeaders.join(", ");
+    }
+  } else {
+    const requestedHeaders = readSingletonHeader(
+      request.header,
+      "access-control-request-headers"
+    );
+    if (typeof requestedHeaders === "string") {
+      corsHeaders["access-control-allow-headers"] = requestedHeaders;
+    }
+  }
+
+  if (options.maxAge !== undefined) {
+    corsHeaders["access-control-max-age"] = options.maxAge;
+  }
+
+  return corsHeaders;
+}
+
 function splitHeaderValues(values: readonly string[]): readonly string[] {
   return values.flatMap(value =>
     value
@@ -131,97 +258,50 @@ function mergeResponseHeaders(
   return { ...result, ...mergedCorsHeaders };
 }
 
-export function cors(options?: CorsOptions) {
-  const credentials = options?.credentials ?? false;
+function mergeCorsHeadersIntoResponse(
+  response: IHttpResponse,
+  corsHeaders: Record<string, string>
+): IHttpResponse {
+  return {
+    ...response,
+    header: mergeResponseHeaders(response.header, corsHeaders),
+  };
+}
 
-  const methods = (options?.allowMethods ?? DEFAULT_METHODS).join(", ");
-  const exposeHeaders = options?.exposeHeaders?.join(", ");
-  const maxAge = options?.maxAge?.toString();
+export function cors(options?: CorsOptions) {
+  const normalizedOptions = normalizeCorsOptions(options);
 
   return defineMiddleware(async (ctx, next) => {
-    const requestOrigin = getRequestOrigin(ctx.request.header);
-    const hasOrigin = hasHeaderName(ctx.request.header, "origin");
-    const resolvedOrigin =
-      hasOrigin && requestOrigin === undefined
-        ? undefined
-        : resolveOrigin(options?.origin, requestOrigin, credentials);
-    const origin =
-      credentials && resolvedOrigin === "*" ? undefined : resolvedOrigin;
+    const corsRequest = readCorsRequest(ctx.request);
+    const origin = resolveRequestOrigin(normalizedOptions, corsRequest);
 
     if (origin === undefined) {
       const response = await next();
 
-      if (
-        !hasOrigin &&
-        !isOriginDependentWithoutRequestOrigin(options?.origin, credentials)
-      ) {
+      if (!shouldVaryDeniedCorsResponse(normalizedOptions, corsRequest)) {
         return response;
       }
 
-      return {
-        ...response,
-        header: mergeResponseHeaders(response.header, { vary: "Origin" }),
-      } satisfies IHttpResponse;
-    }
-
-    const corsHeaders: Record<string, string> = {
-      "access-control-allow-origin": origin,
-    };
-
-    if (credentials) {
-      corsHeaders["access-control-allow-credentials"] = "true";
-    }
-
-    if (origin !== "*") {
-      corsHeaders["vary"] = "Origin";
+      return mergeCorsHeadersIntoResponse(response, { vary: "Origin" });
     }
 
-    if (exposeHeaders) {
-      corsHeaders["access-control-expose-headers"] = exposeHeaders;
-    }
+    const corsHeaders = buildSimpleCorsHeaders(normalizedOptions, origin);
 
-    const isPreflight =
-      ctx.request.method === "OPTIONS" &&
-      requestOrigin !== undefined &&
-      readSingletonHeader(
-        ctx.request.header,
-        "access-control-request-method"
-      ) !== undefined;
-
-    if (isPreflight) {
-      corsHeaders["access-control-allow-methods"] = methods;
-
-      const configuredHeaders = options?.allowHeaders;
-      if (configuredHeaders !== undefined) {
-        if (configuredHeaders.length > 0) {
-          corsHeaders["access-control-allow-headers"] =
-            configuredHeaders.join(", ");
-        }
-      } else {
-        const requestedHeaders = readSingletonHeader(
-          ctx.request.header,
-          "access-control-request-headers"
-        );
-        if (typeof requestedHeaders === "string") {
-          corsHeaders["access-control-allow-headers"] = requestedHeaders;
-        }
-      }
-
-      if (maxAge) {
-        corsHeaders["access-control-max-age"] = maxAge;
-      }
+    if (isPreflightCorsRequest(corsRequest)) {
+      const preflightHeaders = buildPreflightCorsHeaders(
+        normalizedOptions,
+        corsRequest,
+        corsHeaders
+      );
 
       return {
         statusCode: 204,
-        header: corsHeaders,
+        header: preflightHeaders,
       } satisfies IHttpResponse;
     }
 
     const response = await next();
 
-    return {
-      ...response,
-      header: mergeResponseHeaders(response.header, corsHeaders),
-    } satisfies IHttpResponse;
+    return mergeCorsHeadersIntoResponse(response, corsHeaders);
   });
 }

package/dist/lib/middleware/scoped.ts

@@ -2,12 +2,22 @@ import { pathMatcher } from "../PathMatcher.js";
 import { defineMiddleware } from "../TypedMiddleware.js";
 import type { TypedMiddleware } from "../TypedMiddleware.js";
 
-type NoProvidedKeys<TProvides extends Record<string, unknown>> = [
+/** Rejects middleware that would provide state from a conditional branch. */
+type RejectsProvidedState<TProvides extends Record<string, unknown>> = [
   keyof TProvides,
 ] extends [never]
   ? unknown
   : never;
 
+/**
+ * scoped/except middleware may be skipped, so it cannot safely provide
+ * downstream state; any upstream state requirements remain part of its type.
+ */
+type StateNeutralMiddleware<
+  TProvides extends Record<string, unknown>,
+  TRequires extends Record<string, unknown>,
+> = TypedMiddleware<TProvides, TRequires> & RejectsProvidedState<TProvides>;
+
 /**
  * Restricts a middleware to only run on paths matching the given patterns.
  *
@@ -30,7 +40,7 @@ export function scoped<
   TRequires extends Record<string, unknown>,
 >(
   paths: readonly string[],
-  middleware: TypedMiddleware<TProvides, TRequires> & NoProvidedKeys<TProvides>
+  middleware: StateNeutralMiddleware<TProvides, TRequires>
 ): TypedMiddleware<TProvides, TRequires> {
   const matchers = paths.map(pathMatcher);
 
@@ -58,7 +68,7 @@ export function except<
   TRequires extends Record<string, unknown>,
 >(
   paths: readonly string[],
-  middleware: TypedMiddleware<TProvides, TRequires> & NoProvidedKeys<TProvides>
+  middleware: StateNeutralMiddleware<TProvides, TRequires>
 ): TypedMiddleware<TProvides, TRequires> {
   const matchers = paths.map(pathMatcher);
 

package/dist/templates/Router.ejs

@@ -18,7 +18,8 @@ export type Server<%- pascalCaseEntityName %>ApiHandler<
   TState extends Record<string, unknown> = Record<string, unknown>,
 > = {
 <% for (const operation of operations) { %>
-  <%- operation.handlerName %>: RequestHandler<I<%- operation.className %>Request, <%- operation.className %>Response, TState>;
+<% if (operation.jsDoc) { %><%- operation.jsDoc %>
+<% } %>  <%- operation.handlerName %>: RequestHandler<I<%- operation.className %>Request, <%- operation.className %>Response, TState>;
 <% } %>
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexeus/typeweaver-server",
-  "version": "0.10.4",
+  "version": "0.11.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,15 +47,15 @@
   },
   "homepage": "https://github.com/rexeus/typeweaver#readme",
   "peerDependencies": {
-    "@rexeus/typeweaver-core": "^0.10.4",
-    "@rexeus/typeweaver-gen": "^0.10.4"
+    "@rexeus/typeweaver-core": "^0.11.0",
+    "@rexeus/typeweaver-gen": "^0.11.0"
   },
   "devDependencies": {
     "get-port": "^7.2.0",
     "test-utils": "file:../test-utils",
     "tsx": "^4.21.0",
-    "@rexeus/typeweaver-core": "^0.10.4",
-    "@rexeus/typeweaver-gen": "^0.10.4"
+    "@rexeus/typeweaver-core": "^0.11.0",
+    "@rexeus/typeweaver-gen": "^0.11.0"
   },
   "dependencies": {
     "polycase": "^1.1.0"