@velajs/vela 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.10.0 (2026-04-28)
+
+Edge-runtime audit and AI-drift cleanup.
+
+### Breaking changes
+
+- **Schedule module split.** `ScheduleExecutor`, `SCHEDULE_MODULE_OPTIONS`, and `ScheduleModuleOptions` are no longer exported from `@velajs/vela`. The `setInterval`-based timer executor moved to a new opt-in sub-export at `@velajs/vela/schedule-node`. Consumers on Node or Bun should now do:
+
+  ```ts
+  import { ScheduleNodeModule } from '@velajs/vela/schedule-node';
+
+  @Module({ imports: [ScheduleNodeModule.forRoot()], providers: [JobsService] })
+  class AppModule {}
+  ```
+
+  `ScheduleModule.forRoot()` is now metadata-only — `enableTimers` is no longer accepted (drop the option entirely). `ScheduleModule.forRootAsync()` was removed (no options to async-resolve).
+
+  Edge runtimes without `setInterval` (Cloudflare Workers, etc.) should continue to use platform cron triggers — `@velajs/cloudflare` ≥ 0.2.0 dispatches core `@Cron` jobs via its `scheduled()` handler.
+
+- **TypeScript enums replaced with `as const` objects** for `HttpMethod`, `ParamType`, `Scope`, `RequestMethod`, and `LogLevel`. Value access (`HttpMethod.GET`) keeps working; type-position usages (`: HttpMethod`) keep working via same-name type aliases. Code that imported the enum *type* with structural assumptions about enum runtime shape may need adjustment.
+
+### Fixes
+
+- `@Head()` is now HEAD-only. Previously it registered as a plain GET handler, so `GET` requests would also hit `@Head()`-decorated methods.
+- Handler-level guards / pipes / interceptors / filters now key off the controller constructor instead of `${className}:${method}`, fixing a metadata collision when two controllers shared a class name (across feature modules or after minification).
+- Removed an obsolete narration comment in `route.manager.ts`.
+
+### New
+
+- `@velajs/vela/schedule-node` — opt-in entry for Node/Bun cron and interval execution.
+- `parseCron(expression)` and `CronMatcher` exported from the core for use by platform cron adapters.
+- Edge-runtime audit test (`src/__tests__/edge-runtime-audit.test.ts`) — fails CI if any file under `src/` (excluding `schedule-node/`) references forbidden APIs (`node:*`, `Buffer`, `process.*`, `__dirname/__filename`, `fs/path/os/child_process`, `setInterval`, `Bun.serve`).
+
 ## 0.1.0 (2026-02-19)
 
 Initial release.

package/dist/application.d.ts

@@ -2,6 +2,7 @@ import type { Hono } from 'hono';
 import type { Container } from './container/container';
 import type { Token } from './container/types';
 import type { RouteManager } from './http/route.manager';
+import type { MountOpenApiOptions } from './openapi/types';
 import type { FilterType, GuardType, InterceptorType, PipeType } from './registry/types';
 export declare class VelaApplication {
     private readonly container;
@@ -22,6 +23,17 @@ export declare class VelaApplication {
     useGlobalGuards(...guards: GuardType[]): this;
     useGlobalInterceptors(...interceptors: InterceptorType[]): this;
     useGlobalFilters(...filters: FilterType[]): this;
+    /**
+     * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
+     * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
+     * CDN at runtime so nothing is bundled server-side.
+     *
+     * ```ts
+     * const doc = createOpenApiDocument(AppModule);
+     * app.mountOpenApi({ document: doc, ui: 'scalar' });
+     * ```
+     */
+    mountOpenApi(options: MountOpenApiOptions): this;
     callOnModuleInit(): Promise<void>;
     callOnApplicationBootstrap(): Promise<void>;
     close(signal?: string): Promise<void>;

package/dist/application.js

@@ -1,4 +1,5 @@
 import { hasBeforeApplicationShutdown, hasOnApplicationBootstrap, hasOnApplicationShutdown, hasOnModuleDestroy, hasOnModuleInit } from "./lifecycle/index.js";
+import { renderScalarUi } from "./openapi/scalar-ui.js";
 export class VelaApplication {
     container;
     routeManager;
@@ -52,6 +53,27 @@ export class VelaApplication {
         this.routeManager.useGlobalFilters(...filters);
         return this;
     }
+    /**
+   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on
+   * the underlying Hono app. Edge-safe: the UI HTML loads Scalar from a
+   * CDN at runtime so nothing is bundled server-side.
+   *
+   * ```ts
+   * const doc = createOpenApiDocument(AppModule);
+   * app.mountOpenApi({ document: doc, ui: 'scalar' });
+   * ```
+   */ mountOpenApi(options) {
+        const app = this.getApp();
+        const jsonPath = options.path ?? '/docs.json';
+        const doc = options.document;
+        app.get(jsonPath, (c)=>c.json(doc));
+        if (options.ui === 'scalar') {
+            const uiPath = options.uiPath ?? '/docs';
+            const html = renderScalarUi(jsonPath);
+            app.get(uiPath, (c)=>c.html(html));
+        }
+        return this;
+    }
     // Lifecycle hooks
     async callOnModuleInit() {
         for (const instance of this.instances){

package/dist/constants.d.ts

@@ -13,29 +13,32 @@ export declare const METADATA_KEYS: {
     readonly CATCH: "vela:catch";
     readonly CRUD: "vela:crud";
 };
-export declare enum HttpMethod {
-    GET = "get",
-    POST = "post",
-    PUT = "put",
-    PATCH = "patch",
-    DELETE = "delete",
-    OPTIONS = "options",
-    HEAD = "head",
-    ALL = "all"
-}
-export declare enum ParamType {
-    BODY = "body",
-    QUERY = "query",
-    PARAM = "param",
-    HEADERS = "headers",
-    REQUEST = "request",
-    RESPONSE = "response",
-    IP = "ip",
-    COOKIE = "cookie",
-    RAW_BODY = "raw_body"
-}
-export declare enum Scope {
-    SINGLETON = "singleton",
-    TRANSIENT = "transient",
-    REQUEST = "request"
-}
+export declare const HttpMethod: {
+    readonly GET: "get";
+    readonly POST: "post";
+    readonly PUT: "put";
+    readonly PATCH: "patch";
+    readonly DELETE: "delete";
+    readonly OPTIONS: "options";
+    readonly HEAD: "head";
+    readonly ALL: "all";
+};
+export type HttpMethod = (typeof HttpMethod)[keyof typeof HttpMethod];
+export declare const ParamType: {
+    readonly BODY: "body";
+    readonly QUERY: "query";
+    readonly PARAM: "param";
+    readonly HEADERS: "headers";
+    readonly REQUEST: "request";
+    readonly RESPONSE: "response";
+    readonly IP: "ip";
+    readonly COOKIE: "cookie";
+    readonly RAW_BODY: "raw_body";
+};
+export type ParamType = (typeof ParamType)[keyof typeof ParamType];
+export declare const Scope: {
+    readonly SINGLETON: "singleton";
+    readonly TRANSIENT: "transient";
+    readonly REQUEST: "request";
+};
+export type Scope = (typeof Scope)[keyof typeof Scope];

package/dist/constants.js

@@ -18,32 +18,29 @@ export const METADATA_KEYS = {
     // CRUD
     CRUD: 'vela:crud'
 };
-export var HttpMethod = /*#__PURE__*/ function(HttpMethod) {
-    HttpMethod["GET"] = "get";
-    HttpMethod["POST"] = "post";
-    HttpMethod["PUT"] = "put";
-    HttpMethod["PATCH"] = "patch";
-    HttpMethod["DELETE"] = "delete";
-    HttpMethod["OPTIONS"] = "options";
-    HttpMethod["HEAD"] = "head";
-    HttpMethod["ALL"] = "all";
-    return HttpMethod;
-}({});
-export var ParamType = /*#__PURE__*/ function(ParamType) {
-    ParamType["BODY"] = "body";
-    ParamType["QUERY"] = "query";
-    ParamType["PARAM"] = "param";
-    ParamType["HEADERS"] = "headers";
-    ParamType["REQUEST"] = "request";
-    ParamType["RESPONSE"] = "response";
-    ParamType["IP"] = "ip";
-    ParamType["COOKIE"] = "cookie";
-    ParamType["RAW_BODY"] = "raw_body";
-    return ParamType;
-}({});
-export var Scope = /*#__PURE__*/ function(Scope) {
-    Scope["SINGLETON"] = "singleton";
-    Scope["TRANSIENT"] = "transient";
-    Scope["REQUEST"] = "request";
-    return Scope;
-}({});
+export const HttpMethod = {
+    GET: 'get',
+    POST: 'post',
+    PUT: 'put',
+    PATCH: 'patch',
+    DELETE: 'delete',
+    OPTIONS: 'options',
+    HEAD: 'head',
+    ALL: 'all'
+};
+export const ParamType = {
+    BODY: 'body',
+    QUERY: 'query',
+    PARAM: 'param',
+    HEADERS: 'headers',
+    REQUEST: 'request',
+    RESPONSE: 'response',
+    IP: 'ip',
+    COOKIE: 'cookie',
+    RAW_BODY: 'raw_body'
+};
+export const Scope = {
+    SINGLETON: 'singleton',
+    TRANSIENT: 'transient',
+    REQUEST: 'request'
+};

package/dist/http/middleware-consumer.d.ts

@@ -1,15 +1,16 @@
 import type { NestMiddleware } from '../pipeline/types';
 import type { Type } from '../registry/types';
-export declare enum RequestMethod {
-    GET = "GET",
-    POST = "POST",
-    PUT = "PUT",
-    DELETE = "DELETE",
-    PATCH = "PATCH",
-    OPTIONS = "OPTIONS",
-    HEAD = "HEAD",
-    ALL = "ALL"
-}
+export declare const RequestMethod: {
+    readonly GET: "GET";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly DELETE: "DELETE";
+    readonly PATCH: "PATCH";
+    readonly OPTIONS: "OPTIONS";
+    readonly HEAD: "HEAD";
+    readonly ALL: "ALL";
+};
+export type RequestMethod = (typeof RequestMethod)[keyof typeof RequestMethod];
 export interface RouteInfo {
     path: string;
     method?: RequestMethod;

package/dist/http/middleware-consumer.js

@@ -1,15 +1,14 @@
 import { MetadataRegistry } from "../registry/metadata.registry.js";
-export var RequestMethod = /*#__PURE__*/ function(RequestMethod) {
-    RequestMethod["GET"] = "GET";
-    RequestMethod["POST"] = "POST";
-    RequestMethod["PUT"] = "PUT";
-    RequestMethod["DELETE"] = "DELETE";
-    RequestMethod["PATCH"] = "PATCH";
-    RequestMethod["OPTIONS"] = "OPTIONS";
-    RequestMethod["HEAD"] = "HEAD";
-    RequestMethod["ALL"] = "ALL";
-    return RequestMethod;
-}({});
+export const RequestMethod = {
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    DELETE: 'DELETE',
+    PATCH: 'PATCH',
+    OPTIONS: 'OPTIONS',
+    HEAD: 'HEAD',
+    ALL: 'ALL'
+};
 export class MiddlewareBuilder {
     definitions = [];
     apply(...middleware) {

package/dist/http/route.manager.js

@@ -50,7 +50,7 @@ export class RouteManager {
         ],
         [
             HttpMethod.HEAD,
-            (app, p, h)=>app.get(p, h)
+            (app, p, h)=>app.get(p, (c, next)=>c.req.method === 'HEAD' ? h(c) : next())
         ],
         [
             HttpMethod.ALL,
@@ -175,11 +175,6 @@ export class RouteManager {
     instantiateMany(items, container) {
         return items.map((item)=>this.instantiate(item, container));
     }
-    // Resolve middleware priority at build time. Supports three sources:
-    //   1. static priority on the class constructor
-    //   2. priority property on the instance
-    //   3. for container tokens, resolve and inspect the instance (+ its ctor)
-    // Falls back to 0 on any error or when no priority is set.
     getMiddlewarePriority(entry) {
         if (entry == null) return 0;
         if (typeof entry === 'function') {

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import './metadata';
 export { defineMetadata, getMetadata } from './metadata';
 export { VelaFactory, createApplication } from './factory';
 export { VelaApplication } from './application';
-export { createOpenApiDocument, ApiDoc, ApiTags, zodToJsonSchema } from './openapi/index';
-export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
+export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema, } from './openapi/index';
+export type { OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, } from './openapi/index';
 export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from './container/index';
 export type { Type, Token, InjectableOptions, ProviderOptions, } from './container/index';
 export { METADATA_KEYS, HttpMethod, ParamType, Scope } from './constants';
@@ -20,8 +20,8 @@ export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, CacheKey
 export type { CacheModuleOptions, CacheStore, CacheEntry } from './cache/index';
 export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_EVENT_METADATA, } from './event-emitter/index';
 export type { EventHandler, OnEventMetadata } from './event-emitter/index';
-export { ScheduleModule, ScheduleRegistry, ScheduleExecutor, Cron, Interval, SCHEDULE_MODULE_OPTIONS, CRON_METADATA, INTERVAL_METADATA, } from './schedule/index';
-export type { RegisteredCronJob, RegisteredIntervalJob, CronMetadata, IntervalMetadata, ScheduleModuleOptions, } from './schedule/index';
+export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA, } from './schedule/index';
+export type { RegisteredCronJob, RegisteredIntervalJob, CronMetadata, IntervalMetadata, CronMatcher, } from './schedule/index';
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator, } from './health/index';
 export type { HealthCheckResult, HealthCheckStatus, HealthIndicatorResult, HealthIndicatorFunction, ResponseCheckCallback, HttpPingOptions, } from './health/index';
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA, } from './throttler/index';

package/dist/index.js

@@ -4,7 +4,7 @@ export { defineMetadata, getMetadata } from "./metadata.js";
 export { VelaFactory, createApplication } from "./factory.js";
 export { VelaApplication } from "./application.js";
 // OpenAPI
-export { createOpenApiDocument, ApiDoc, ApiTags, zodToJsonSchema } from "./openapi/index.js";
+export { createOpenApiDocument, ApiDoc, ApiTags, ApiResponse, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
 export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from "./container/index.js";
 // Constants
@@ -24,7 +24,7 @@ export { CacheModule, CacheService, CacheInterceptor, MemoryCacheStore, CacheKey
 // Event Emitter
 export { EventEmitterModule, EventEmitter, EventEmitterSubscriber, OnEvent, ON_EVENT_METADATA } from "./event-emitter/index.js";
 // Schedule
-export { ScheduleModule, ScheduleRegistry, ScheduleExecutor, Cron, Interval, SCHEDULE_MODULE_OPTIONS, CRON_METADATA, INTERVAL_METADATA } from "./schedule/index.js";
+export { ScheduleModule, ScheduleRegistry, Cron, Interval, parseCron, CRON_METADATA, INTERVAL_METADATA } from "./schedule/index.js";
 // Health
 export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthIndicator } from "./health/index.js";
 // Throttler

package/dist/openapi/decorators.d.ts

@@ -1,6 +1,7 @@
-import type { ApiDocMetadata } from './types';
+import type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions } from './types';
 export declare const API_DOC_METADATA = "vela:openapi:doc";
 export declare const API_TAGS_METADATA = "vela:openapi:tags";
+export declare const API_RESPONSES_METADATA = "vela:openapi:responses";
 /**
  * Attach OpenAPI documentation to a route handler (or controller).
  *
@@ -18,3 +19,16 @@ export declare function ApiDoc(metadata: ApiDocMetadata): MethodDecorator & Clas
 export declare function ApiTags(...tags: string[]): MethodDecorator & ClassDecorator;
 export declare function getApiDoc(target: object, propertyKey?: string | symbol): ApiDocMetadata | undefined;
 export declare function getApiTags(target: object, propertyKey?: string | symbol): string[] | undefined;
+/**
+ * Document a response for a given status code. Stackable: apply multiple
+ * times on the same handler to declare different statuses.
+ *
+ * ```ts
+ * @Get('/:id')
+ * @ApiResponse(200, { description: 'Found', schema: UserDto })
+ * @ApiResponse(404, { description: 'Not found', schema: ErrorDto })
+ * findOne() { ... }
+ * ```
+ */
+export declare function ApiResponse(status: number | string, options: ApiResponseOptions): MethodDecorator;
+export declare function getApiResponses(target: object, propertyKey: string | symbol): ApiResponseEntry[] | undefined;

package/dist/openapi/decorators.js

@@ -1,5 +1,6 @@
 export const API_DOC_METADATA = 'vela:openapi:doc';
 export const API_TAGS_METADATA = 'vela:openapi:tags';
+export const API_RESPONSES_METADATA = 'vela:openapi:responses';
 /**
  * Attach OpenAPI documentation to a route handler (or controller).
  *
@@ -35,3 +36,26 @@ export function getApiDoc(target, propertyKey) {
 export function getApiTags(target, propertyKey) {
     return propertyKey !== undefined ? Reflect.getMetadata(API_TAGS_METADATA, target, propertyKey) : Reflect.getMetadata(API_TAGS_METADATA, target);
 }
+/**
+ * Document a response for a given status code. Stackable: apply multiple
+ * times on the same handler to declare different statuses.
+ *
+ * ```ts
+ * @Get('/:id')
+ * @ApiResponse(200, { description: 'Found', schema: UserDto })
+ * @ApiResponse(404, { description: 'Not found', schema: ErrorDto })
+ * findOne() { ... }
+ * ```
+ */ export function ApiResponse(status, options) {
+    return (target, propertyKey)=>{
+        const existing = Reflect.getMetadata(API_RESPONSES_METADATA, target, propertyKey) ?? [];
+        existing.push({
+            status,
+            ...options
+        });
+        Reflect.defineMetadata(API_RESPONSES_METADATA, existing, target, propertyKey);
+    };
+}
+export function getApiResponses(target, propertyKey) {
+    return Reflect.getMetadata(API_RESPONSES_METADATA, target, propertyKey);
+}

package/dist/openapi/document.js

@@ -2,7 +2,7 @@ import { getModuleMetadata } from "../module/decorators.js";
 import { ForwardRef } from "../container/types.js";
 import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { ParamType } from "../constants.js";
-import { getApiDoc, getApiTags } from "./decorators.js";
+import { getApiDoc, getApiResponses, getApiTags } from "./decorators.js";
 import { isOptional, zodToJsonSchema } from "./zod-to-json-schema.js";
 function isDynamicModuleLike(v) {
     return !!v && typeof v === 'object' && 'module' in v && typeof v.module === 'function';
@@ -31,7 +31,6 @@ function collectControllers(rootModule) {
     ];
 }
 function normalizePath(path) {
-    // Hono/Nest style `:id` → OpenAPI `{id}`
     return path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
 }
 function joinPath(a, b) {
@@ -40,10 +39,47 @@ function joinPath(a, b) {
     const joined = `${left}${right}`;
     return joined || '/';
 }
-function getParamSchema(param, paramtypes) {
+/**
+ * Tracks DTO classes referenced during document generation and registers
+ * each under `components.schemas`. Handles name collisions by suffixing.
+ */ let ComponentsRegistry = class ComponentsRegistry {
+    schemas = new Map();
+    classToKey = new WeakMap();
+    ref(dtoClass) {
+        const existing = this.classToKey.get(dtoClass);
+        if (existing) return {
+            $ref: `#/components/schemas/${existing}`
+        };
+        const baseName = dtoClass.name && dtoClass.name !== '' ? dtoClass.name : 'Schema';
+        let key = baseName;
+        let counter = 2;
+        while(this.schemas.has(key)){
+            key = `${baseName}${counter++}`;
+        }
+        this.classToKey.set(dtoClass, key);
+        const staticSchema = dtoClass.schema;
+        this.schemas.set(key, zodToJsonSchema(staticSchema));
+        return {
+            $ref: `#/components/schemas/${key}`
+        };
+    }
+    build() {
+        if (this.schemas.size === 0) return undefined;
+        return Object.fromEntries(this.schemas);
+    }
+};
+function isDtoClass(value) {
+    return typeof value === 'function' && value.schema != null;
+}
+function getParamSchema(param, paramtypes, registry) {
     const metatype = paramtypes?.[param.index];
-    if (metatype?.schema) {
-        return zodToJsonSchema(metatype.schema);
+    if (!metatype) return undefined;
+    if (isDtoClass(metatype)) {
+        return registry.ref(metatype);
+    }
+    const maybeSchema = metatype.schema;
+    if (maybeSchema) {
+        return zodToJsonSchema(maybeSchema);
     }
     return undefined;
 }
@@ -54,13 +90,33 @@ function isParamOptional(param, paramtypes) {
     }
     return true;
 }
-function buildOperation(controller, route, pathString) {
+function isLikelyJsonSchema(value) {
+    if (!value || typeof value !== 'object') return false;
+    const v = value;
+    if (typeof v.toJSONSchema === 'function') return false;
+    return 'type' in v || '$ref' in v || 'oneOf' in v || 'anyOf' in v || 'allOf' in v || 'enum' in v || 'const' in v;
+}
+function resolveResponseSchema(input, registry) {
+    if (input === undefined || input === null) return undefined;
+    if (isDtoClass(input)) {
+        return registry.ref(input);
+    }
+    if (isLikelyJsonSchema(input)) {
+        return {
+            ...input
+        };
+    }
+    if (typeof input === 'object' && typeof input.toJSONSchema === 'function') {
+        return zodToJsonSchema(input);
+    }
+    return undefined;
+}
+function buildOperation(controller, route, pathString, registry) {
     const handlerName = route.handlerName;
     const paramMetadata = MetadataRegistry.getParameters(controller).get(handlerName) ?? [];
     const paramtypes = Reflect.getMetadata('design:paramtypes', controller.prototype, handlerName);
     const parameters = [];
     let requestBody;
-    // Path params declared in the URL but not listed as @Param() get a string default.
     const declaredPathParams = new Set();
     const pathParamNames = [
         ...pathString.matchAll(/\{([^}]+)\}/g)
@@ -72,7 +128,7 @@ function buildOperation(controller, route, pathString) {
                 name: param.name,
                 in: 'path',
                 required: true,
-                schema: getParamSchema(param, paramtypes) ?? {
+                schema: getParamSchema(param, paramtypes, registry) ?? {
                     type: 'string'
                 }
             });
@@ -81,7 +137,7 @@ function buildOperation(controller, route, pathString) {
                 name: param.name,
                 in: 'query',
                 required: !isParamOptional(param, paramtypes),
-                schema: getParamSchema(param, paramtypes) ?? {
+                schema: getParamSchema(param, paramtypes, registry) ?? {
                     type: 'string'
                 }
             });
@@ -90,12 +146,12 @@ function buildOperation(controller, route, pathString) {
                 name: param.name,
                 in: 'header',
                 required: !isParamOptional(param, paramtypes),
-                schema: getParamSchema(param, paramtypes) ?? {
+                schema: getParamSchema(param, paramtypes, registry) ?? {
                     type: 'string'
                 }
             });
         } else if (param.type === ParamType.BODY) {
-            const schema = getParamSchema(param, paramtypes);
+            const schema = getParamSchema(param, paramtypes, registry);
             if (schema) {
                 requestBody = {
                     required: !isParamOptional(param, paramtypes),
@@ -131,12 +187,29 @@ function buildOperation(controller, route, pathString) {
             ...docTags
         ])
     ];
-    const operation = {
-        responses: {
-            '200': {
-                description: 'OK'
-            }
+    const responses = {
+        '200': {
+            description: 'OK'
+        }
+    };
+    const apiResponses = getApiResponses(controller.prototype, handlerName) ?? [];
+    for (const entry of apiResponses){
+        const key = String(entry.status);
+        const resolved = {
+            description: entry.description
+        };
+        const schema = resolveResponseSchema(entry.schema, registry);
+        if (schema) {
+            resolved.content = {
+                'application/json': {
+                    schema
+                }
+            };
         }
+        responses[key] = resolved;
+    }
+    const operation = {
+        responses
     };
     if (parameters.length > 0) operation.parameters = parameters;
     if (requestBody) operation.requestBody = requestBody;
@@ -159,6 +232,7 @@ const VERB_WHITELIST = new Set([
 export function createOpenApiDocument(rootModule, options = {}) {
     const paths = {};
     const globalPrefix = options.globalPrefix ?? '';
+    const registry = new ComponentsRegistry();
     for (const controller of collectControllers(rootModule)){
         const controllerPath = MetadataRegistry.getControllerPath(controller);
         const routes = MetadataRegistry.getRoutes(controller);
@@ -167,13 +241,13 @@ export function createOpenApiDocument(rootModule, options = {}) {
             if (!VERB_WHITELIST.has(method)) continue;
             const rawPath = joinPath(joinPath(globalPrefix, controllerPath), route.path);
             const pathString = normalizePath(rawPath);
-            const operation = buildOperation(controller, route, pathString);
+            const operation = buildOperation(controller, route, pathString, registry);
             const pathItem = paths[pathString] ?? {};
             pathItem[method] = operation;
             paths[pathString] = pathItem;
         }
     }
-    return {
+    const document = {
         openapi: '3.1.0',
         info: {
             title: options.info?.title ?? 'Vela API',
@@ -184,4 +258,11 @@ export function createOpenApiDocument(rootModule, options = {}) {
         },
         paths
     };
+    const schemas = registry.build();
+    if (schemas) {
+        document.components = {
+            schemas
+        };
+    }
+    return document;
 }

package/dist/openapi/index.d.ts

@@ -1,4 +1,5 @@
 export { createOpenApiDocument } from './document';
-export { ApiDoc, ApiTags, API_DOC_METADATA, API_TAGS_METADATA } from './decorators';
+export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA, } from './decorators';
 export { zodToJsonSchema } from './zod-to-json-schema';
-export type { ApiDocMetadata, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';
+export { renderScalarUi } from './scalar-ui';
+export type { ApiDocMetadata, ApiResponseEntry, ApiResponseOptions, CreateOpenApiDocumentOptions, HttpVerb, JsonSchema, MountOpenApiOptions, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiRequestBody, OpenApiResponse, } from './types';

package/dist/openapi/index.js

@@ -1,3 +1,4 @@
 export { createOpenApiDocument } from "./document.js";
-export { ApiDoc, ApiTags, API_DOC_METADATA, API_TAGS_METADATA } from "./decorators.js";
+export { ApiDoc, ApiTags, ApiResponse, API_DOC_METADATA, API_TAGS_METADATA, API_RESPONSES_METADATA } from "./decorators.js";
 export { zodToJsonSchema } from "./zod-to-json-schema.js";
+export { renderScalarUi } from "./scalar-ui.js";

package/dist/openapi/scalar-ui.d.ts

@@ -0,0 +1 @@
+export declare function renderScalarUi(jsonUrl: string): string;

package/dist/openapi/scalar-ui.js

@@ -0,0 +1,18 @@
+// Minimal HTML shell that bootstraps Scalar's hosted API-reference UI.
+// Served as a static string so it works on every edge runtime with no
+// Node or bundler deps. Scalar itself is loaded from a CDN at runtime.
+export function renderScalarUi(jsonUrl) {
+    const safeUrl = jsonUrl.replace(/"/g, '"');
+    return `<!doctype html>
+<html>
+  <head>
+    <title>API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script id="api-reference" data-url="${safeUrl}"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+}