@rexeus/typeweaver-server 0.10.3 → 0.10.5

package/dist/lib/middleware/cors.ts

@@ -1,5 +1,10 @@
-import type { IHttpResponse } from "@rexeus/typeweaver-core";
+import type { IHttpRequest, IHttpResponse } from "@rexeus/typeweaver-core";
 import { defineMiddleware } from "../TypedMiddleware.js";
+import {
+  hasHeaderName,
+  readHeaderValues,
+  readSingletonHeader,
+} from "./header.js";
 
 export type CorsOptions = {
   readonly origin?:
@@ -22,13 +27,49 @@ const DEFAULT_METHODS = [
   "DELETE",
 ] as const;
 
+const POLICY_CONTROLLED_CORS_HEADERS = new Set([
+  "access-control-allow-origin",
+  "access-control-allow-credentials",
+  "access-control-expose-headers",
+  "access-control-allow-methods",
+  "access-control-allow-headers",
+  "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,
   credentials: boolean
 ): string | undefined {
   if (configOrigin === undefined || configOrigin === "*") {
-    if (credentials && requestOrigin) return requestOrigin;
+    if (credentials) return undefined;
     return "*";
   }
 
@@ -48,72 +89,219 @@ function resolveOrigin(
 function getRequestOrigin(
   header: Record<string, string | string[]> | undefined
 ): string | undefined {
-  const origin = header?.["origin"];
-  return typeof origin === "string" ? origin : undefined;
+  return readSingletonHeader(header, "origin");
 }
 
-export function cors(options?: CorsOptions) {
-  const credentials = options?.credentials ?? false;
-  const methods = (options?.allowMethods ?? DEFAULT_METHODS).join(", ");
-  const exposeHeaders = options?.exposeHeaders?.join(", ");
-  const maxAge = options?.maxAge?.toString();
+function readCorsRequest(request: IHttpRequest): CorsRequest {
+  return {
+    header: request.header,
+    method: request.method,
+    hasOrigin: hasHeaderName(request.header, "origin"),
+    origin: getRequestOrigin(request.header),
+  };
+}
 
-  return defineMiddleware(async (ctx, next) => {
-    const requestOrigin = getRequestOrigin(ctx.request.header);
-    const origin = resolveOrigin(options?.origin, requestOrigin, credentials);
+function isOriginDependentWithoutRequestOrigin(
+  configOrigin: CorsOptions["origin"],
+  credentials: boolean
+): boolean {
+  return (
+    typeof configOrigin === "function" ||
+    Array.isArray(configOrigin) ||
+    ((configOrigin === undefined || configOrigin === "*") && credentials)
+  );
+}
 
-    if (origin === undefined) return next();
+function resolveRequestOrigin(
+  options: NormalizedCorsOptions,
+  request: CorsRequest
+): string | undefined {
+  if (request.hasOrigin && request.origin === undefined) {
+    return undefined;
+  }
 
-    const corsHeaders: Record<string, string> = {
-      "access-control-allow-origin": origin,
-    };
+  const resolvedOrigin = resolveOrigin(
+    options.origin,
+    request.origin,
+    options.credentials
+  );
 
-    if (credentials) {
-      corsHeaders["access-control-allow-credentials"] = "true";
-    }
+  return options.credentials && resolvedOrigin === "*"
+    ? undefined
+    : resolvedOrigin;
+}
 
-    if (origin !== "*") {
-      corsHeaders["vary"] = "Origin";
+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 (exposeHeaders) {
-      corsHeaders["access-control-expose-headers"] = exposeHeaders;
+  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
+      .split(",")
+      .map(item => item.trim())
+      .filter(item => item.length > 0)
+  );
+}
+
+function mergeVary(existing: readonly string[], value: string): string {
+  const values = splitHeaderValues(existing);
+  if (values.length === 0) return value;
+
+  const hasValue = values.some(
+    item => item.toLowerCase() === value.toLowerCase()
+  );
+
+  return hasValue ? values.join(", ") : [...values, value].join(", ");
+}
+
+function removePolicyControlledCorsHeaders(
+  responseHeaders: Record<string, string | string[]> | undefined
+): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = {};
+
+  for (const [key, value] of Object.entries(responseHeaders ?? {})) {
+    if (POLICY_CONTROLLED_CORS_HEADERS.has(key.toLowerCase())) continue;
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+function mergeResponseHeaders(
+  responseHeaders: Record<string, string | string[]> | undefined,
+  corsHeaders: Record<string, string>
+): Record<string, string | string[]> {
+  const result = removePolicyControlledCorsHeaders(responseHeaders);
+
+  const mergedCorsHeaders = { ...corsHeaders };
+  if (corsHeaders.vary !== undefined) {
+    for (const key of Object.keys(result)) {
+      if (key.toLowerCase() === "vary") delete result[key];
     }
 
-    const isPreflight =
-      ctx.request.method === "OPTIONS" &&
-      ctx.request.header?.["access-control-request-method"] !== undefined;
-
-    if (isPreflight) {
-      corsHeaders["access-control-allow-methods"] = methods;
-
-      const configuredHeaders = options?.allowHeaders;
-      if (configuredHeaders && configuredHeaders.length > 0) {
-        corsHeaders["access-control-allow-headers"] =
-          configuredHeaders.join(", ");
-      } else {
-        const requestedHeaders =
-          ctx.request.header?.["access-control-request-headers"];
-        if (typeof requestedHeaders === "string") {
-          corsHeaders["access-control-allow-headers"] = requestedHeaders;
-        }
-      }
+    mergedCorsHeaders.vary = mergeVary(
+      readHeaderValues(responseHeaders, "vary"),
+      corsHeaders.vary
+    );
+  }
+
+  return { ...result, ...mergedCorsHeaders };
+}
+
+function mergeCorsHeadersIntoResponse(
+  response: IHttpResponse,
+  corsHeaders: Record<string, string>
+): IHttpResponse {
+  return {
+    ...response,
+    header: mergeResponseHeaders(response.header, corsHeaders),
+  };
+}
+
+export function cors(options?: CorsOptions) {
+  const normalizedOptions = normalizeCorsOptions(options);
+
+  return defineMiddleware(async (ctx, next) => {
+    const corsRequest = readCorsRequest(ctx.request);
+    const origin = resolveRequestOrigin(normalizedOptions, corsRequest);
+
+    if (origin === undefined) {
+      const response = await next();
 
-      if (maxAge) {
-        corsHeaders["access-control-max-age"] = maxAge;
+      if (!shouldVaryDeniedCorsResponse(normalizedOptions, corsRequest)) {
+        return response;
       }
 
+      return mergeCorsHeadersIntoResponse(response, { vary: "Origin" });
+    }
+
+    const corsHeaders = buildSimpleCorsHeaders(normalizedOptions, origin);
+
+    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: { ...corsHeaders, ...response.header },
-    } satisfies IHttpResponse;
+    return mergeCorsHeadersIntoResponse(response, corsHeaders);
   });
 }

package/dist/lib/middleware/header.ts

@@ -0,0 +1,59 @@
+export type HeaderMap = Record<string, string | string[]> | undefined;
+
+export function readSingletonHeader(
+  header: HeaderMap,
+  name: string
+): string | undefined {
+  const normalizedName = name.toLowerCase();
+  let foundValue: string | undefined;
+
+  for (const [key, value] of Object.entries(header ?? {})) {
+    if (key.toLowerCase() !== normalizedName) continue;
+    if (foundValue !== undefined || typeof value !== "string") {
+      return undefined;
+    }
+
+    foundValue = value;
+  }
+
+  return foundValue;
+}
+
+export function hasHeaderName(header: HeaderMap, name: string): boolean {
+  const normalizedName = name.toLowerCase();
+
+  return Object.keys(header ?? {}).some(
+    key => key.toLowerCase() === normalizedName
+  );
+}
+
+export function readHeaderValues(
+  header: HeaderMap,
+  name: string
+): readonly string[] {
+  const normalizedName = name.toLowerCase();
+  const values: string[] = [];
+
+  for (const [key, value] of Object.entries(header ?? {})) {
+    if (key.toLowerCase() !== normalizedName) continue;
+
+    values.push(...(Array.isArray(value) ? value : [value]));
+  }
+
+  return values;
+}
+
+export function omitHeaders(
+  header: HeaderMap,
+  names: readonly string[]
+): Record<string, string | string[]> {
+  const normalizedNames = new Set(names.map(name => name.toLowerCase()));
+  const headers: Record<string, string | string[]> = {};
+
+  for (const [key, value] of Object.entries(header ?? {})) {
+    if (normalizedNames.has(key.toLowerCase())) continue;
+    headers[key] = value;
+  }
+
+  return headers;
+}

package/dist/lib/middleware/logger.ts

@@ -10,6 +10,7 @@ export type LogData = {
 export type LoggerOptions = {
   readonly logFn?: (message: string) => void;
   readonly format?: (data: LogData) => string;
+  readonly nowMs?: () => number;
 };
 
 const defaultFormat = (data: LogData): string =>
@@ -18,11 +19,12 @@ const defaultFormat = (data: LogData): string =>
 export function logger(options?: LoggerOptions) {
   const logFn = options?.logFn ?? console.log;
   const format = options?.format ?? defaultFormat;
+  const nowMs = options?.nowMs ?? (() => performance.now());
 
   return defineMiddleware(async (ctx, next) => {
-    const start = performance.now();
+    const start = nowMs();
     const response = await next();
-    const durationMs = Math.round(performance.now() - start);
+    const durationMs = Math.round(nowMs() - start);
 
     logFn(
       format({

package/dist/lib/middleware/poweredBy.ts

@@ -10,10 +10,15 @@ export function poweredBy(options?: PoweredByOptions) {
 
   return defineMiddleware(async (_ctx, next) => {
     const response = await next();
+    const responseHeaders = Object.fromEntries(
+      Object.entries(response.header ?? {}).filter(
+        ([headerName]) => headerName.toLowerCase() !== "x-powered-by"
+      )
+    );
 
     return {
       ...response,
-      header: { ...response.header, "x-powered-by": value },
+      header: { ...responseHeaders, "x-powered-by": value },
     } satisfies IHttpResponse;
   });
 }

package/dist/lib/middleware/requestId.ts

@@ -1,29 +1,29 @@
 import type { IHttpResponse } from "@rexeus/typeweaver-core";
 import { defineMiddleware } from "../TypedMiddleware.js";
+import { omitHeaders, readSingletonHeader } from "./header.js";
 
 export type RequestIdOptions = {
   readonly headerName?: string;
   readonly generator?: () => string;
 };
 
+const isValidRequestId = (value: string | undefined): value is string =>
+  value !== undefined && value.length > 0 && !/[\r\n]/.test(value);
+
 export function requestId(options?: RequestIdOptions) {
   const headerName = (options?.headerName ?? "x-request-id").toLowerCase();
   const generator = options?.generator ?? (() => crypto.randomUUID());
 
   return defineMiddleware<{ requestId: string }>(async (ctx, next) => {
-    const existing = ctx.request.header?.[headerName];
-    const id =
-      typeof existing === "string"
-        ? existing
-        : Array.isArray(existing)
-          ? (existing[0] ?? generator())
-          : generator();
+    const existing = readSingletonHeader(ctx.request.header, headerName);
+    const id = isValidRequestId(existing) ? existing : generator();
 
     const response = await next({ requestId: id });
+    const header = omitHeaders(response.header, [headerName]);
 
     return {
       ...response,
-      header: { ...response.header, [headerName]: id },
+      header: { ...header, [headerName]: id },
     } satisfies IHttpResponse;
   });
 }

package/dist/lib/middleware/scoped.ts

@@ -2,55 +2,80 @@ import { pathMatcher } from "../PathMatcher.js";
 import { defineMiddleware } from "../TypedMiddleware.js";
 import type { TypedMiddleware } from "../TypedMiddleware.js";
 
+/** 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.
  *
  * Accepts the same pattern syntax as {@link pathMatcher}: exact (`"/users"`),
  * prefix (`"/api/*"`), and parameterized (`"/users/:id"`).
  *
- * Only accepts non-state middleware (`TypedMiddleware<{}, {}>`) to preserve
+ * Only accepts non-state-providing middleware to preserve
  * TypeWeaver's compile-time state guarantees — skipping a state-providing
  * middleware would leave downstream consumers with missing state.
+ * Any upstream state requirements declared by the wrapped middleware are
+ * preserved on the returned middleware descriptor.
  *
  * @example
  * ```typescript
  * app.use(scoped(["/api/*"], cors({ origin: "https://app.com" })));
  * ```
  */
-export function scoped(
+export function scoped<
+  TProvides extends Record<string, unknown>,
+  TRequires extends Record<string, unknown>,
+>(
   paths: readonly string[],
-  middleware: TypedMiddleware<{}, {}>
-): TypedMiddleware<{}, {}> {
+  middleware: StateNeutralMiddleware<TProvides, TRequires>
+): TypedMiddleware<TProvides, TRequires> {
   const matchers = paths.map(pathMatcher);
 
-  return defineMiddleware(async (ctx, next) => {
+  return defineMiddleware<{}, TRequires>(async (ctx, next) => {
     if (!matchers.some(match => match(ctx.request.path))) {
       return next();
     }
     return middleware.handler(ctx, next);
-  });
+  }) as TypedMiddleware<TProvides, TRequires>;
 }
 
 /**
  * Runs a middleware on all paths *except* those matching the given patterns.
  *
- * The inverse of {@link scoped}. Same pattern syntax and type constraint.
+ * The inverse of {@link scoped}. Same pattern syntax and type constraints,
+ * including preservation of wrapped middleware state requirements.
  *
  * @example
  * ```typescript
  * app.use(except(["/health", "/ready"], logger()));
  * ```
  */
-export function except(
+export function except<
+  TProvides extends Record<string, unknown>,
+  TRequires extends Record<string, unknown>,
+>(
   paths: readonly string[],
-  middleware: TypedMiddleware<{}, {}>
-): TypedMiddleware<{}, {}> {
+  middleware: StateNeutralMiddleware<TProvides, TRequires>
+): TypedMiddleware<TProvides, TRequires> {
   const matchers = paths.map(pathMatcher);
 
-  return defineMiddleware(async (ctx, next) => {
+  return defineMiddleware<{}, TRequires>(async (ctx, next) => {
     if (matchers.some(match => match(ctx.request.path))) {
       return next();
     }
     return middleware.handler(ctx, next);
-  });
+  }) as TypedMiddleware<TProvides, TRequires>;
 }

package/dist/lib/middleware/secureHeaders.ts

@@ -1,5 +1,6 @@
 import type { IHttpResponse } from "@rexeus/typeweaver-core";
 import { defineMiddleware } from "../TypedMiddleware.js";
+import { omitHeaders } from "./header.js";
 
 export type SecureHeadersOptions = {
   readonly contentTypeOptions?: string | false;
@@ -48,10 +49,11 @@ export function secureHeaders(options?: SecureHeadersOptions) {
 
   return defineMiddleware(async (_ctx, next) => {
     const response = await next();
+    const header = omitHeaders(response.header, Object.keys(headers));
 
     return {
       ...response,
-      header: { ...headers, ...response.header },
+      header: { ...header, ...headers },
     } satisfies IHttpResponse;
   });
 }

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.3",
+  "version": "0.10.5",
   "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.3",
-    "@rexeus/typeweaver-gen": "^0.10.3"
+    "@rexeus/typeweaver-core": "^0.10.5",
+    "@rexeus/typeweaver-gen": "^0.10.5"
   },
   "devDependencies": {
     "get-port": "^7.2.0",
     "test-utils": "file:../test-utils",
     "tsx": "^4.21.0",
-    "@rexeus/typeweaver-core": "^0.10.3",
-    "@rexeus/typeweaver-gen": "^0.10.3"
+    "@rexeus/typeweaver-core": "^0.10.5",
+    "@rexeus/typeweaver-gen": "^0.10.5"
   },
   "dependencies": {
     "polycase": "^1.1.0"