@rexeus/typeweaver-server 0.5.1

package/dist/lib/Middleware.ts

@@ -0,0 +1,71 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import type { ServerContext } from "./ServerContext";
+
+/**
+ * A middleware function that processes requests in the pipeline.
+ *
+ * Follows a return-based onion model: call `next()` to pass control to the next
+ * middleware or handler and receive the response, then return it (optionally modified).
+ *
+ * When middleware provides state, it passes the state object to `next(state)`.
+ * The pipeline merges this state into `ctx.state` before continuing to the
+ * next middleware, guaranteeing downstream consumers can read it.
+ *
+ * To short-circuit the pipeline, return a response without calling `next()`.
+ */
+export type Middleware = (
+  ctx: ServerContext,
+  next: (state?: Record<string, unknown>) => Promise<IHttpResponse>
+) => Promise<IHttpResponse>;
+
+/**
+ * Executes a middleware pipeline in onion order (return-based).
+ *
+ * Each middleware receives a `next()` function that optionally accepts a state
+ * object. When state is provided, it is merged into `ctx.state` before invoking
+ * the next middleware in the chain. The final `next()` calls the provided
+ * `finalHandler`.
+ *
+ * @param middlewares - Ordered list of middleware functions to execute
+ * @param ctx - The server context shared across the pipeline
+ * @param finalHandler - The handler to execute after all middleware
+ * @returns The response produced by the pipeline
+ */
+export async function executeMiddlewarePipeline(
+  middlewares: Middleware[],
+  ctx: ServerContext,
+  finalHandler: () => Promise<IHttpResponse>
+): Promise<IHttpResponse> {
+  let index = 0;
+
+  const advance = async (): Promise<IHttpResponse> => {
+    if (index < middlewares.length) {
+      const currentIndex = index++;
+      let called = false;
+
+      return middlewares[currentIndex]!(ctx, async state => {
+        if (called) {
+          throw new Error("next() called multiple times");
+        }
+        called = true;
+
+        if (state) {
+          ctx.state.merge(state);
+        }
+
+        return advance();
+      });
+    }
+
+    return finalHandler();
+  };
+
+  return advance();
+}

package/dist/lib/NodeAdapter.ts

@@ -0,0 +1,121 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import { PayloadTooLargeError } from "./Errors";
+import type { TypeweaverApp } from "./TypeweaverApp";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/**
+ * Adapts a `TypeweaverApp` to Node.js `http.createServer`.
+ *
+ * Converts `IncomingMessage` to a Fetch API `Request`, calls `app.fetch()`,
+ * and writes the `Response` back to `ServerResponse`.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from "node:http";
+ * import { nodeAdapter } from "./generated/lib/server";
+ * import app from "./server";
+ *
+ * createServer(nodeAdapter(app)).listen(3000);
+ * ```
+ */
+const DEFAULT_MAX_BODY_SIZE = 1_048_576; // 1 MB
+
+export type NodeAdapterOptions = {
+  readonly maxBodySize?: number;
+};
+
+export function nodeAdapter(
+  app: TypeweaverApp<any>,
+  options?: NodeAdapterOptions
+): (req: IncomingMessage, res: ServerResponse) => void {
+  const maxBodySize = options?.maxBodySize ?? DEFAULT_MAX_BODY_SIZE;
+  return (req, res) => {
+    void handleRequest(app, req, res, maxBodySize);
+  };
+}
+
+async function handleRequest(
+  app: TypeweaverApp<any>,
+  req: IncomingMessage,
+  res: ServerResponse,
+  maxBodySize: number
+): Promise<void> {
+  try {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+    const isBodyless = req.method === "GET" || req.method === "HEAD";
+    const body = isBodyless ? undefined : await collectBody(req, maxBodySize);
+
+    const request = new Request(url, {
+      method: req.method,
+      headers: req.headers as Record<string, string>,
+      body,
+    });
+
+    const response = await app.fetch(request);
+
+    response.headers.forEach((value, key) => {
+      if (key.toLowerCase() !== "set-cookie") {
+        res.setHeader(key, value);
+      }
+    });
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length > 0) {
+      res.setHeader("set-cookie", cookies);
+    }
+    res.writeHead(response.status);
+    res.end(Buffer.from(await response.arrayBuffer()));
+  } catch (error) {
+    if (error instanceof PayloadTooLargeError) {
+      if (!res.headersSent) {
+        res.writeHead(413, { "content-type": "application/json" });
+      }
+      res.end(
+        JSON.stringify({
+          code: "PAYLOAD_TOO_LARGE",
+          message: "Request body exceeds the size limit",
+        })
+      );
+      return;
+    }
+
+    console.error(error);
+    if (!res.headersSent) {
+      res.writeHead(500, { "content-type": "application/json" });
+    }
+    res.end(
+      JSON.stringify({
+        code: "INTERNAL_SERVER_ERROR",
+        message: "An unexpected error occurred",
+      })
+    );
+  }
+}
+
+function collectBody(
+  req: IncomingMessage,
+  maxBodySize: number
+): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+
+    req.on("data", (chunk: Buffer) => {
+      totalBytes += chunk.byteLength;
+      if (totalBytes > maxBodySize) {
+        req.destroy();
+        reject(new PayloadTooLargeError(totalBytes, maxBodySize));
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => resolve(Buffer.concat(chunks, totalBytes)));
+    req.on("error", reject);
+  });
+}

package/dist/lib/PathMatcher.ts

@@ -0,0 +1,56 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+/**
+ * Creates a predicate that tests whether a request path matches a pattern.
+ *
+ * Supports three pattern types:
+ * - **Exact match**: `"/users"` matches only `"/users"`
+ * - **Prefix match**: `"/users/*"` matches `"/users"` and any path beneath it
+ *   (e.g. `"/users/123"`, `"/users/123/posts"`)
+ * - **Parameterized segments**: `"/users/:id"` matches paths where `:id` stands
+ *   for exactly one segment (e.g. `"/users/123"` but not `"/users/123/posts"`)
+ *
+ * Uses the same `:paramName` syntax as typeweaver route definitions.
+ *
+ * @example
+ * ```typescript
+ * const isUsersPath = pathMatcher("/users/*");
+ * const isUserDetail = pathMatcher("/users/:id");
+ *
+ * const usersGuard = defineMiddleware(async (ctx, next) => {
+ *   if (!isUsersPath(ctx.request.path)) return next();
+ *   // guard logic...
+ *   return next();
+ * });
+ * ```
+ */
+export function pathMatcher(pattern: string): (path: string) => boolean {
+  if (pattern.endsWith("/*")) {
+    const prefix = pattern.slice(0, -2);
+    return path => path === prefix || path.startsWith(prefix + "/");
+  }
+
+  const segments = pattern.split("/");
+  const hasParams = segments.some(s => s.startsWith(":"));
+
+  if (!hasParams) {
+    return path => path === pattern;
+  }
+
+  const segmentCount = segments.length;
+  const matchers = segments.map(s => (s.startsWith(":") ? null : s));
+
+  return path => {
+    const parts = path.split("/");
+    if (parts.length !== segmentCount) return false;
+    for (let i = 0; i < segmentCount; i++) {
+      if (matchers[i] !== null && matchers[i] !== parts[i]) return false;
+    }
+    return true;
+  };
+}

package/dist/lib/RequestHandler.ts

@@ -0,0 +1,35 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import type { IHttpRequest, IHttpResponse } from "@rexeus/typeweaver-core";
+import type { ServerContext } from "./ServerContext";
+
+/**
+ * A type-safe request handler function.
+ *
+ * Receives an `IHttpRequest` (validated when `validateRequests` is enabled)
+ * and the `ServerContext`, and returns a typed `IHttpResponse`. No framework-specific
+ * types — everything is in typeweaver's native format.
+ *
+ * @template TRequest - The specific request type (e.g., `ICreateTodoRequest`)
+ * @template TResponse - The specific response type (e.g., `CreateTodoResponse`)
+ * @template TState - The state shape available in the server context
+ *
+ * @example
+ * ```typescript
+ * const handler: RequestHandler<ICreateTodoRequest, CreateTodoResponse> =
+ *   async (request, ctx) => ({
+ *     statusCode: 201,
+ *     body: { id: "todo_1", title: request.body.title },
+ *   });
+ * ```
+ */
+export type RequestHandler<
+  TRequest extends IHttpRequest = IHttpRequest,
+  TResponse extends IHttpResponse = IHttpResponse,
+  TState extends Record<string, unknown> = Record<string, unknown>,
+> = (request: TRequest, ctx: ServerContext<TState>) => Promise<TResponse>;

package/dist/lib/Router.ts

@@ -0,0 +1,263 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import type {
+  HttpMethod,
+  IHttpResponse,
+  IRequestValidator,
+  RequestValidationError,
+} from "@rexeus/typeweaver-core";
+import type { RequestHandler } from "./RequestHandler";
+import type { ServerContext } from "./ServerContext";
+
+/**
+ * A registered route with its method, path pattern, validator, and handler.
+ */
+export type RouteDefinition = {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly validator: IRequestValidator;
+  readonly handler: RequestHandler;
+  /** Reference to the router config for error handling. */
+  readonly routerConfig: RouterErrorConfig;
+};
+
+/**
+ * Error handling configuration associated with a router.
+ */
+export type RouterErrorConfig = {
+  readonly validateRequests: boolean;
+  readonly handleHttpResponseErrors: HttpResponseErrorHandler | boolean;
+  readonly handleValidationErrors: ValidationErrorHandler | 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(...)`).
+ */
+export type HttpResponseErrorHandler = (
+  error: IHttpResponse,
+  ctx: ServerContext
+) => Promise<IHttpResponse> | IHttpResponse;
+
+/**
+ * Handles request validation errors.
+ */
+export type ValidationErrorHandler = (
+  error: RequestValidationError,
+  ctx: ServerContext
+) => Promise<IHttpResponse> | IHttpResponse;
+
+/**
+ * Handles any unknown errors not caught by other handlers.
+ */
+export type UnknownErrorHandler = (
+  error: unknown,
+  ctx: ServerContext
+) => Promise<IHttpResponse> | IHttpResponse;
+
+/**
+ * Result of a successful route match.
+ */
+export type RouteMatch = {
+  readonly route: RouteDefinition;
+  readonly params: Record<string, string>;
+};
+
+/**
+ * A node in the radix tree.
+ *
+ * Each node represents a single path segment.
+ * Static children are stored in a `Map` keyed by segment string.
+ * A single `paramChild` holds the branch for `:param` segments.
+ * Leaf nodes store a `Map` of HTTP method → route definition.
+ */
+type RadixNode = {
+  readonly staticChildren: Map<string, RadixNode>;
+  paramChild: { readonly name: string; readonly node: RadixNode } | undefined;
+  readonly methods: Map<string, RouteDefinition>;
+};
+
+/**
+ * High-performance radix tree router with path parameter support.
+ *
+ * Routes are stored in a tree structure where each level corresponds
+ * to a path segment. This gives O(d) lookup time where d is the depth
+ * (number of segments) of the URL — independent of the total number
+ * of registered routes.
+ *
+ * Supports:
+ * - Static paths: `/accounts`
+ * - Named parameters: `/todos/:todoId`
+ * - Multiple parameters: `/todos/:todoId/subtodos/:subtodoId`
+ * - Automatic HEAD → GET fallback (per HTTP spec)
+ * - 405 Method Not Allowed detection with `Allow` header
+ */
+export class Router {
+  private readonly root: RadixNode = Router.createNode();
+
+  /**
+   * Register a route in the radix tree.
+   */
+  public add(definition: RouteDefinition): void {
+    const segments = Router.toSegments(definition.path);
+
+    let current = this.root;
+
+    for (const segment of segments) {
+      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}"`
+          );
+        }
+        if (!current.paramChild) {
+          current.paramChild = { name: paramName, node: Router.createNode() };
+        }
+        current = current.paramChild.node;
+      } else {
+        let child = current.staticChildren.get(segment);
+        if (!child) {
+          child = Router.createNode();
+          current.staticChildren.set(segment, child);
+        }
+        current = child;
+      }
+    }
+
+    if (current.methods.has(definition.method)) {
+      throw new Error(
+        `Route conflict: ${definition.method} ${definition.path} is already registered`
+      );
+    }
+
+    current.methods.set(definition.method, definition);
+  }
+
+  /**
+   * Find a matching route for the given method and path.
+   *
+   * Traverses the radix tree in O(d) time where d is the number
+   * of path segments. Static segments are matched first (exact match),
+   * then parameterized segments are tried as fallback.
+   *
+   * For HEAD requests, automatically falls back to the GET handler
+   * if no explicit HEAD handler is registered (per HTTP spec).
+   *
+   * @returns The matched route with extracted path parameters, or `undefined` if no match.
+   */
+  public match(method: string, path: string): RouteMatch | undefined {
+    const upperMethod = method.toUpperCase();
+    const segments = Router.toSegments(path);
+    const params: Record<string, string> = {};
+
+    const node = this.traverse(this.root, segments, 0, params);
+    if (!node) return undefined;
+
+    const definition =
+      node.methods.get(upperMethod) ??
+      (upperMethod === "HEAD" ? node.methods.get("GET") : undefined);
+
+    if (!definition) return undefined;
+
+    return { route: definition, params };
+  }
+
+  /**
+   * Find a matching node for the given path, regardless of HTTP method.
+   *
+   * Used to distinguish "path not found" (404) from "method not allowed" (405).
+   *
+   * @returns The allowed methods for this path, or `undefined` if the path doesn't exist.
+   */
+  public matchPath(path: string): { allowedMethods: string[] } | undefined {
+    const segments = Router.toSegments(path);
+    const params: Record<string, string> = {};
+
+    const node = this.traverse(this.root, segments, 0, params);
+    if (!node || node.methods.size === 0) return undefined;
+
+    const methods = Array.from(node.methods.keys());
+    if (methods.includes("GET") && !methods.includes("HEAD")) {
+      methods.push("HEAD");
+    }
+
+    return { allowedMethods: methods.sort() };
+  }
+
+  /**
+   * Recursively traverse the radix tree to find a matching node.
+   *
+   * Prioritises static children over param children for correct
+   * and predictable matching behaviour.
+   *
+   * Path parameters are URL-decoded during extraction.
+   */
+  private traverse(
+    node: RadixNode,
+    segments: string[],
+    index: number,
+    params: Record<string, string>
+  ): RadixNode | undefined {
+    // All segments consumed — this node is the match candidate
+    if (index === segments.length) {
+      return node;
+    }
+
+    const segment = segments[index]!;
+
+    // 1. Try static child first (higher priority)
+    const staticChild = node.staticChildren.get(segment);
+    if (staticChild) {
+      const result = this.traverse(staticChild, segments, index + 1, params);
+      if (result && result.methods.size > 0) return result;
+    }
+
+    // 2. Try param child as fallback
+    if (node.paramChild) {
+      const { name, node: paramNode } = node.paramChild;
+      params[name] = Router.decodePathSegment(segment);
+      const result = this.traverse(paramNode, segments, index + 1, params);
+      if (result && result.methods.size > 0) return result;
+      // Backtrack: remove param if this branch didn't match
+      delete params[name];
+    }
+
+    return undefined;
+  }
+
+  private static createNode(): RadixNode {
+    return {
+      staticChildren: new Map(),
+      paramChild: undefined,
+      methods: new Map(),
+    };
+  }
+
+  /**
+   * Decodes a URL-encoded path segment while guarding against path traversal.
+   *
+   * Encoded dot-segments like `%2e%2e` would decode to `..`, which could
+   * enable directory traversal if a downstream handler builds file paths
+   * from params. Returning the raw segment neutralises this vector.
+   */
+  private static decodePathSegment(segment: string): string {
+    try {
+      const decoded = decodeURIComponent(segment);
+      if (decoded === ".." || decoded === ".") return segment;
+      return decoded;
+    } catch {
+      return segment;
+    }
+  }
+
+  private static toSegments(path: string): string[] {
+    return path.split("/").filter(s => s.length > 0);
+  }
+}

package/dist/lib/ServerContext.ts

@@ -0,0 +1,54 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+import type { IHttpRequest } from "@rexeus/typeweaver-core";
+import type { StateMap } from "./StateMap";
+
+/**
+ * Context object passed through the middleware pipeline and to request handlers.
+ *
+ * The context carries the current request and a typed state map
+ * that middleware can use to pass data downstream to handlers.
+ *
+ * When parameterized with a state shape, provides compile-time type safety
+ * for state access. Without an explicit type parameter, accepts any key/value
+ * (backward compatible).
+ *
+ * All data is in typeweaver's native `IHttpRequest`/`IHttpResponse` format —
+ * no framework-specific types leak into middleware or handlers.
+ *
+ * Responses are returned, not mutated on the context (return-based middleware).
+ *
+ * @template TState - The accumulated state shape from middleware
+ *
+ * @example
+ * ```typescript
+ * // Typed state — no casts needed
+ * type AppState = { userId: string };
+ *
+ * // In middleware: set state (typed)
+ * app.use(async (ctx, next) => {
+ *   ctx.state.set("userId", "user_123");
+ *   return next();
+ * });
+ *
+ * // In handler: read state (typed)
+ * handleCreateTodo: async (request, ctx: ServerContext<AppState>) => {
+ *   const userId = ctx.state.get("userId"); // string | undefined
+ *   return { statusCode: 201, body: { id: "1", title: "..." } };
+ * };
+ * ```
+ */
+export type ServerContext<
+  TState extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  /** The incoming HTTP request in typeweaver format. */
+  readonly request: IHttpRequest;
+
+  /** Type-safe key-value store for sharing data between middleware and handlers. */
+  readonly state: StateMap<TState>;
+};

package/dist/lib/StateMap.ts

@@ -0,0 +1,57 @@
+/**
+ * This file was automatically generated by typeweaver.
+ * DO NOT EDIT. Instead, modify the source definition file and generate again.
+ *
+ * @generated by @rexeus/typeweaver
+ */
+
+/**
+ * A type-safe wrapper around `Map<string, unknown>` for middleware state.
+ *
+ * When parameterized with a specific state shape, provides compile-time
+ * type safety for `get`/`set`/`has` operations. When using the default
+ * `Record<string, unknown>`, behaves identically to `Map<string, unknown>`.
+ *
+ * The API surface is intentionally narrow (`get`, `set`, `has`, `merge` only).
+ * Generic `Map` methods like `forEach`, `entries`, or `delete` are excluded
+ * to prevent bypassing type safety.
+ *
+ * @template TState - The shape of state this map carries
+ *
+ * @example
+ * ```typescript
+ * // Typed — constrains keys and values
+ * type MyState = { userId: string; role: "admin" | "user" };
+ * const typed = new StateMap<MyState>();
+ * typed.set("userId", "u_123");     // ✓
+ * typed.set("userId", 123);         // ✗ compile error
+ * typed.get("userId");              // string (guaranteed by middleware pipeline)
+ * typed.get("nonexistent");         // ✗ compile error
+ * ```
+ */
+export class StateMap<
+  TState extends Record<string, unknown> = Record<string, unknown>,
+> {
+  private readonly map = new Map<string, unknown>();
+
+  public set<K extends string & keyof TState>(key: K, value: TState[K]): void {
+    this.map.set(key, value);
+  }
+
+  public get<K extends string & keyof TState>(key: K): TState[K] {
+    return this.map.get(key) as TState[K];
+  }
+
+  public has<K extends string & keyof TState>(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  public merge(state: Record<string, unknown>): void {
+    for (const [key, value] of Object.entries(state)) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        continue;
+      }
+      this.map.set(key, value);
+    }
+  }
+}