bazis 0.96.1

package/core/http/Binding/requestModelRegistry.ts

@@ -0,0 +1,117 @@
+/**
+ * "Class name -> class" registry for request models (`@RequestModel()`).
+ *
+ * Generated binding conventions refer to the request body class by name (the
+ * generated file is plain data without imports of user modules). The generated
+ * target resolves its own DTOs; this registry is the fallback for classes it
+ * does not know, such as external DTOs marked with `@RequestModel()`.
+ */
+
+/** Marker: several different classes are registered under one name. */
+export const AMBIGUOUS_REQUEST_MODEL: unique symbol = Symbol("ambiguous-request-model");
+
+export type RequestModelClass = new () => object;
+
+/**
+ * Runtime hydration metadata emitted by `bun run di:generate` for a class-
+ * typed request-model field. Standard TC39 decorators deliberately do not
+ * expose design types, so this tiny registry is the dependency-free bridge
+ * from TypeScript source types to the HTTP binder.
+ */
+interface RequestModelFieldShapeBase {
+  readonly array?: boolean;
+  /** `null` is part of the declared property type. */
+  readonly nullable?: boolean;
+  /** `null` is part of an array element type. */
+  readonly elementNullable?: boolean;
+}
+
+/** A field typed as a request-model class (or an array of them). */
+export interface RequestModelNestedFieldShape extends RequestModelFieldShapeBase {
+  readonly model: RequestModelClass;
+}
+
+/** A field declared exactly as `string`, `number` or `boolean` (or an array of one). */
+export interface RequestModelPrimitiveFieldShape extends RequestModelFieldShapeBase {
+  readonly primitive: RequestModelPrimitive;
+}
+
+export type RequestModelPrimitive = "string" | "number" | "boolean";
+export type RequestModelFieldShape = RequestModelNestedFieldShape | RequestModelPrimitiveFieldShape;
+const PRIMITIVES: ReadonlySet<unknown> = new Set<RequestModelPrimitive>(["string", "number", "boolean"]);
+
+export type RequestModelShape = Readonly<Record<string, RequestModelFieldShape>>;
+
+let registry = new Map<string, RequestModelClass | typeof AMBIGUOUS_REQUEST_MODEL>();
+// Runtime model constructors are process-owned; Map permits exact generated
+// target rollback without changing the public lookup contract.
+let shapes = new Map<RequestModelClass, RequestModelShape>();
+const FORBIDDEN_SHAPE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/** Registers a request-model class (called by the `@RequestModel()` decorator). */
+export function registerRequestModelClass(ctor: RequestModelClass): void {
+  const name = ctor.name;
+  if (!name) {
+    return; // an anonymous class cannot be addressed by name
+  }
+  const existing = registry.get(name);
+  if (existing === undefined) {
+    registry.set(name, ctor);
+  } else if (existing !== ctor) {
+    registry.set(name, AMBIGUOUS_REQUEST_MODEL);
+  }
+}
+
+/**
+ * Class by name: `undefined` if not registered (no `@RequestModel()`),
+ * `AMBIGUOUS_REQUEST_MODEL` if the name is ambiguous (two different classes).
+ */
+export function findRequestModelByName(
+  name: string,
+): RequestModelClass | typeof AMBIGUOUS_REQUEST_MODEL | undefined {
+  return registry.get(name);
+}
+
+/** Registers generated hydration metadata (nested models, primitive types) for one DTO class. */
+export function registerRequestModelShape(ctor: RequestModelClass, shape: RequestModelShape): void {
+  const snapshot: Record<string, RequestModelFieldShape> = Object.create(null) as Record<string, RequestModelFieldShape>;
+  for (const key of Object.keys(shape)) {
+    if (
+      FORBIDDEN_SHAPE_KEYS.has(key) ||
+      !Object.prototype.hasOwnProperty.call(shape, key)
+    ) {
+      continue;
+    }
+    const field = shape[key] as Partial<RequestModelNestedFieldShape & RequestModelPrimitiveFieldShape> | undefined;
+    const nested = typeof field?.model === "function";
+    const primitive = PRIMITIVES.has(field?.primitive);
+    if (field === undefined || nested === primitive) {
+      throw new TypeError(`Invalid request-model shape for ${ctor.name}.${key}`);
+    }
+    const flags = {
+      array: field.array === true || undefined,
+      nullable: field.nullable === true || undefined,
+      elementNullable: field.elementNullable === true || undefined,
+    };
+    snapshot[key] = Object.freeze(nested
+      ? { model: field.model as RequestModelClass, ...flags }
+      : { primitive: field.primitive as RequestModelPrimitive, ...flags });
+  }
+  shapes.set(ctor, Object.freeze(snapshot));
+}
+
+/** Generated hydration shape for a DTO constructor, if one was registered. */
+export function findRequestModelShape(ctor: RequestModelClass): RequestModelShape | undefined {
+  return shapes.get(ctor);
+}
+
+/** Internal generated-runtime transaction support. */
+export function snapshotRequestModelRegistry(): { readonly registry: typeof registry; readonly shapes: typeof shapes } {
+  return { registry: new Map(registry), shapes: new Map(shapes) };
+}
+
+/** Internal generated-runtime transaction support. */
+export function restoreRequestModelRegistry(snapshot: ReturnType<typeof snapshotRequestModelRegistry>): void {
+  registry = snapshot.registry;
+  shapes = snapshot.shapes;
+}

package/core/http/Decorators/attributes.ts

@@ -0,0 +1,92 @@
+import type { Class } from "../../di";
+import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+import { ownActionMeta, ownMeta } from "./metadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type MethodDecorator = (value: AnyMethod, context: ClassMethodDecoratorContext) => void;
+type ClassOrMethodDecorator = (value: AnyClass | AnyMethod, context: ClassDecoratorContext | ClassMethodDecoratorContext) => void;
+
+/** Default success status code for the action (`@HttpCode(201)`). */
+export function HttpCode(code: number): MethodDecorator {
+  return (_value, context) => {
+    ownActionMeta(context.metadata, context.name).httpCode = code;
+  };
+}
+
+/** Response Content-Type for plain-value returns (`@Produces("text/csv")`). */
+export function Produces(contentType: string): MethodDecorator {
+  return (_value, context) => {
+    ownActionMeta(context.metadata, context.name).produces = contentType;
+  };
+}
+
+/** Required request Content-Type for body bindings; mismatch -> 415. */
+export function Consumes(contentType: string): MethodDecorator {
+  return (_value, context) => {
+    ownActionMeta(context.metadata, context.name).consumes = contentType;
+  };
+}
+
+/**
+ * Attaches middleware to a controller (class) or a single route (method).
+ * Execution order: global -> controller -> route -> action.
+ */
+export function Middleware(...middleware: HttpMiddleware[]): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownMeta(context.metadata).middleware.push(...middleware);
+    } else {
+      ownActionMeta(context.metadata, context.name).middleware.push(...middleware);
+    }
+  };
+}
+
+/**
+ * Action filters (.NET style): `before` runs after binding, `after` may
+ * replace the result. Class-level filters wrap method-level ones.
+ */
+export function ActionFilter(filter: ActionFilterHooks): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownMeta(context.metadata).filters.push(filter);
+    } else {
+      ownActionMeta(context.metadata, context.name).filters.push(filter);
+    }
+  };
+}
+
+/**
+ * API version of a controller (or a single action). Routes of versioned
+ * controllers are matched according to `httpModule({ versioning })`:
+ * URL segment (`/v1.0/...`), query parameter or header.
+ */
+export function ApiVersion(version: string): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownMeta(context.metadata).version = version;
+    } else {
+      ownActionMeta(context.metadata, context.name).version = version;
+    }
+  };
+}
+
+/**
+ * Declares a controller method as an error handler for the given error type
+ * (instanceof match; omit the type to catch everything). The handler receives
+ * `(error, ctx)` and returns a result like a regular action:
+ *
+ * ```ts
+ * @Catch(EntityNotFoundError)
+ * onMissing(error: EntityNotFoundError) {
+ *   return NotFound({ error: error.message });
+ * }
+ * ```
+ *
+ * Unmatched (or re-thrown) errors fall through to the global error handler.
+ */
+export function Catch(errorType?: Class<Error>): MethodDecorator {
+  return (_value, context) => {
+    ownMeta(context.metadata).catches.push({ errorType, methodName: context.name });
+  };
+}

package/core/http/Decorators/controller.ts

@@ -0,0 +1,24 @@
+import { ownMeta } from "./metadata";
+
+/**
+ * Marks a class as an HTTP controller with an optional base path:
+ *
+ * ```ts
+ * @Controller("users")
+ * class UsersController {
+ *   @Get(":id(int)")
+ *   getUser(id: number) { ... }
+ * }
+ * ```
+ *
+ * The controller is a regular DI service: register it in a module
+ * (`controllers: [...]` on `BazisModule`, or `httpModule({ controllers: [...] })`)
+ * with scoped lifetime and declare constructor dependencies as usual — auto deps work.
+ */
+export function Controller(prefix = "") {
+  return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {
+    const meta = ownMeta(context.metadata);
+    meta.isController = true;
+    meta.prefix = prefix;
+  };
+}

package/core/http/Decorators/metadata.ts

@@ -0,0 +1,107 @@
+import type { Class } from "../../di";
+import type { ActionFilterHooks, HttpMiddleware } from "../Middleware/types";
+
+// Same one-line polyfill as the validation module: Bun executes TC39
+// decorators natively, Symbol.metadata may be missing in the runtime.
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const HTTP_META = Symbol.for("bazis:http:meta");
+
+/** One route declared by a method decorator (@Get/@Post/...). */
+export interface RouteDeclaration {
+  /** HTTP verb, "*" for @All. */
+  readonly httpMethod: string;
+  /** Path template relative to the controller prefix (":id(int)", "*rest"). */
+  readonly template: string;
+}
+
+/** Error handler declared with @Catch on a controller method. */
+export interface CatchDeclaration {
+  /** Error class to match (instanceof); undefined matches any error. */
+  errorType?: Class<Error>;
+  methodName: string | symbol;
+}
+
+/** Metadata of a single action (method). */
+export interface ActionMeta {
+  routes: RouteDeclaration[];
+  httpCode?: number;
+  produces?: string;
+  consumes?: string;
+  version?: string;
+  maxBodyBytes?: number;
+  middleware: HttpMiddleware[];
+  filters: ActionFilterHooks[];
+}
+
+/** Metadata of a controller class (own + inherited via copy-on-write). */
+export interface ControllerMeta {
+  /** Set by @Controller. */
+  prefix?: string;
+  isController: boolean;
+  version?: string;
+  middleware: HttpMiddleware[];
+  filters: ActionFilterHooks[];
+  catches: CatchDeclaration[];
+  actions: Map<string | symbol, ActionMeta>;
+}
+
+interface HttpMetadataCarrier {
+  [HTTP_META]?: ControllerMeta;
+}
+
+function emptyMeta(): ControllerMeta {
+  return { isController: false, middleware: [], filters: [], catches: [], actions: new Map() };
+}
+
+function cloneMeta(source: ControllerMeta): ControllerMeta {
+  const actions = new Map<string | symbol, ActionMeta>();
+  for (const [name, action] of source.actions) {
+    actions.set(name, {
+      ...action,
+      routes: [...action.routes],
+      middleware: [...action.middleware],
+      filters: [...action.filters],
+    });
+  }
+  return {
+    ...source,
+    middleware: [...source.middleware],
+    filters: [...source.filters],
+    catches: [...source.catches],
+    actions,
+  };
+}
+
+/**
+ * Own (copy-on-write) controller metadata for the class being decorated.
+ * TC39 metadata objects inherit prototypically from the parent class — the
+ * first write into a subclass clones the inherited state.
+ */
+export function ownMeta(metadata: object): ControllerMeta {
+  const carrier = metadata as HttpMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, HTTP_META)) {
+    const inherited = carrier[HTTP_META];
+    carrier[HTTP_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[HTTP_META]!;
+}
+
+/** Action metadata bucket for a method decorator. */
+export function ownActionMeta(metadata: object, methodName: string | symbol): ActionMeta {
+  const meta = ownMeta(metadata);
+  let action = meta.actions.get(methodName);
+  if (!action) {
+    action = { routes: [], middleware: [], filters: [] };
+    meta.actions.set(methodName, action);
+  }
+  return action;
+}
+
+/** Reads controller metadata from a class (undefined if not decorated). */
+export function controllerMetaOf(ctor: object): ControllerMeta | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | HttpMetadataCarrier
+    | undefined;
+  return metadata?.[HTTP_META];
+}

package/core/http/Decorators/routes.ts

@@ -0,0 +1,131 @@
+import type { HttpMiddleware } from "../Middleware/types";
+import { HttpSetupError } from "../Errors/HttpError";
+import { ownActionMeta } from "./metadata";
+
+type MethodDecorator = (value: (...args: never[]) => unknown, context: ClassMethodDecoratorContext) => void;
+
+/**
+ * Inline action options: the equivalent of separate attribute decorators
+ * gathered into one object (the `@Validator({...})` style):
+ *
+ * ```ts
+ * @Post(":id(int)", { code: 201, produces: "application/json" })
+ * update(id: number) { ... }
+ *
+ * @Post({ code: 202 })          // empty path: options as the first argument
+ * enqueue() { ... }
+ * ```
+ */
+export interface RouteOptions {
+  /** Status of a successful response (= `@HttpCode`). */
+  readonly code?: number;
+  /** Response Content-Type for plain results (= `@Produces`). */
+  readonly produces?: string;
+  /** Required request Content-Type for body bindings (= `@Consumes`). */
+  readonly consumes?: string;
+  /** API version of the action (= `@ApiVersion` on the method). */
+  readonly version?: string;
+  /** Route middleware (= `@Middleware` on the method). */
+  readonly middleware?: readonly HttpMiddleware[];
+  /** Maximum body size: an integer and a binary unit together, for example `4mb`. */
+  readonly maxBodySize?: `${bigint}${"b" | "kb" | "mb" | "gb"}`;
+}
+
+function route(httpMethod: string, templateOrOptions?: string | RouteOptions, maybeOptions?: RouteOptions): MethodDecorator {
+  const template = typeof templateOrOptions === "string" ? templateOrOptions : "";
+  const options = typeof templateOrOptions === "object" ? templateOrOptions : maybeOptions;
+  return (_value, context) => {
+    if (context.static || context.private) {
+      throw new Error(`HTTP route decorators support public instance methods only ("${String(context.name)}").`);
+    }
+    const action = ownActionMeta(context.metadata, context.name);
+    action.routes.push({ httpMethod, template });
+    if (options) {
+      // Options apply to the whole action (like attribute decorators); with
+      // several route decorators scalar fields are overwritten and
+      // middleware accumulates.
+      if (options.code !== undefined) {
+        action.httpCode = options.code;
+      }
+      if (options.produces !== undefined) {
+        action.produces = options.produces;
+      }
+      if (options.consumes !== undefined) {
+        action.consumes = options.consumes;
+      }
+      if (options.version !== undefined) {
+        action.version = options.version;
+      }
+      if (options.middleware !== undefined) {
+        action.middleware.push(...options.middleware);
+      }
+      if (options.maxBodySize !== undefined) {
+        const maxBodyBytes = parseRouteMaxBodySize(options.maxBodySize);
+        if (action.maxBodyBytes !== undefined && action.maxBodyBytes !== maxBodyBytes) {
+          throw new HttpSetupError(
+            "HTTP route decorators on one action must resolve maxBodySize to the same byte limit.",
+          );
+        }
+        action.maxBodyBytes = maxBodyBytes;
+      }
+    }
+  };
+}
+
+function parseRouteMaxBodySize(input: unknown): number {
+  const formatError = () => new HttpSetupError(
+    "HTTP route maxBodySize must match '<positive integer><b|kb|mb|gb>' (e.g. '4mb').",
+  );
+  if (typeof input !== "string" || input.length > 18) {
+    throw formatError();
+  }
+  const match = /^([1-9][0-9]{0,15})(b|kb|mb|gb)$/.exec(input);
+  if (match === null || match[0] !== input) {
+    throw formatError();
+  }
+  const multiplier = match[2] === "gb"
+    ? 1_073_741_824n
+    : match[2] === "mb"
+      ? 1_048_576n
+      : match[2] === "kb"
+        ? 1_024n
+        : 1n;
+  const bytes = BigInt(match[1]!) * multiplier;
+  if (bytes > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new HttpSetupError("HTTP route maxBodySize exceeds Number.MAX_SAFE_INTEGER bytes.");
+  }
+  return Number(bytes);
+}
+
+type RouteFactory = {
+  (template?: string, options?: RouteOptions): MethodDecorator;
+  (options: RouteOptions): MethodDecorator;
+};
+
+function createRouteFactory(httpMethod: string): RouteFactory {
+  return ((templateOrOptions?: string | RouteOptions, maybeOptions?: RouteOptions) =>
+    route(httpMethod, templateOrOptions, maybeOptions)) as RouteFactory;
+}
+
+/**
+ * Route decorators. The template is relative to the controller prefix and
+ * supports constrained parameters and a trailing wildcard:
+ *
+ * - `":id"`: a string parameter;
+ * - `":id(int)"`, `":n(number)"`, `":f(bool)"`, `":u(uuid)"`, `":a(alpha)"`:
+ *   a constrained parameter with auto-conversion (a mismatch -> the route does not match);
+ * - `"*rest"`: catch-all, captures the rest of the path (last segment only).
+ *
+ * The second argument (or the first, if the path is empty) takes inline action
+ * options, see {@link RouteOptions}. A method may have several route
+ * decorators; the action is reachable through all of them.
+ */
+export const Get = createRouteFactory("GET");
+export const Post = createRouteFactory("POST");
+export const Put = createRouteFactory("PUT");
+export const Patch = createRouteFactory("PATCH");
+export const Delete = createRouteFactory("DELETE");
+export const Options = createRouteFactory("OPTIONS");
+export const Head = createRouteFactory("HEAD");
+/** Matches any HTTP method (lowest priority when choosing). */
+export const All = createRouteFactory("*");

package/core/http/Errors/HttpError.ts

@@ -0,0 +1,92 @@
+import type { ModelValidationIssue } from "../Binding/modelValidator";
+
+/**
+ * Base class for errors that map directly to an HTTP response.
+ * The global error handler turns any thrown HttpError into
+ * `{ error: message, details? }` with the given status code.
+ */
+export class HttpError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+export class BadRequestError extends HttpError {
+  constructor(message = "Bad Request", details?: unknown) {
+    super(400, message, details);
+  }
+}
+
+export class UnauthorizedError extends HttpError {
+  readonly challenge = "Bearer";
+
+  constructor(message = "Unauthorized", details?: unknown) {
+    super(401, message, details);
+  }
+}
+
+export class ForbiddenError extends HttpError {
+  constructor(message = "Forbidden", details?: unknown) {
+    super(403, message, details);
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message = "Not Found", details?: unknown) {
+    super(404, message, details);
+  }
+}
+
+export class MethodNotAllowedError extends HttpError {
+  constructor(readonly allow: readonly string[]) {
+    super(405, "Method Not Allowed");
+  }
+}
+
+export class UnsupportedMediaTypeError extends HttpError {
+  constructor(expected: string) {
+    super(415, `Unsupported Media Type: expected ${expected}`);
+  }
+}
+
+export class PayloadTooLargeError extends HttpError {
+  constructor(maxBytes: number) {
+    super(413, "Payload Too Large", { maxBytes });
+  }
+}
+
+export class TooManyRequestsError extends HttpError {
+  constructor(readonly retryAfterSeconds: number) {
+    super(429, "Too Many Requests");
+  }
+}
+
+/**
+ * Request body failed model validation (generated DTO binding + `@Validator`
+ * rules on the DTO). The error handler renders it as 400 with the full list
+ * of validation problems.
+ */
+export class ModelValidationError extends BadRequestError {
+  constructor(readonly errors: readonly ModelValidationIssue[]) {
+    super(
+      "Validation failed",
+      errors.map((error) => ({ property: error.property, message: error.message, code: error.code })),
+    );
+  }
+}
+
+/**
+ * Misconfigured routes/controllers (duplicate route, bad template, missing
+ * @Controller). Thrown at startup, never at request time — fail fast.
+ */
+export class HttpSetupError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HttpSetupError";
+  }
+}