@velajs/vela 0.6.1 → 0.8.0

package/dist/cache/cache.module.js

@@ -1,33 +1,12 @@
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { APP_INTERCEPTOR } from "../pipeline/tokens.js";
 import { CacheInterceptor } from "./cache.interceptor.js";
 import { CacheService } from "./cache.service.js";
 import { MemoryCacheStore } from "./cache.store.js";
 import { CACHE_MANAGER, CACHE_MODULE_OPTIONS } from "./cache.tokens.js";
-function makeCacheModuleClass(name) {
-    const moduleClass = class {
-    };
-    Object.defineProperty(moduleClass, 'name', {
-        value: name
-    });
-    defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-    return moduleClass;
-}
 export class CacheModule {
     static forRoot(options = {}) {
         const { ttl = 5, max = 100, isGlobal = false } = options;
         const store = new MemoryCacheStore(ttl, max);
-        const moduleClass = makeCacheModuleClass('CacheModule');
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports: [
-                CACHE_MANAGER,
-                CACHE_MODULE_OPTIONS,
-                CacheService,
-                CacheInterceptor
-            ]
-        });
         const providers = [
             {
                 provide: CACHE_MANAGER,
@@ -47,21 +26,17 @@ export class CacheModule {
             });
         }
         return {
-            module: moduleClass,
-            providers
-        };
-    }
-    static registerAsync(options) {
-        const moduleClass = makeCacheModuleClass('CacheModule');
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            imports: options.imports ?? [],
+            module: CacheModule,
+            providers,
             exports: [
                 CACHE_MANAGER,
                 CACHE_MODULE_OPTIONS,
                 CacheService,
                 CacheInterceptor
             ]
-        });
+        };
+    }
+    static registerAsync(options) {
         const providers = [
             {
                 provide: CACHE_MODULE_OPTIONS,
@@ -85,8 +60,15 @@ export class CacheModule {
             });
         }
         return {
-            module: moduleClass,
-            providers
+            module: CacheModule,
+            imports: options.imports ?? [],
+            providers,
+            exports: [
+                CACHE_MANAGER,
+                CACHE_MODULE_OPTIONS,
+                CacheService,
+                CacheInterceptor
+            ]
         };
     }
 }

package/dist/config/config.module.js

@@ -1,26 +1,10 @@
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { ConfigService } from "./config.service.js";
 import { CONFIG_OPTIONS } from "./config.tokens.js";
 export class ConfigModule {
     static forRoot(options) {
         const config = options.validate ? options.validate(options.config) : options.config;
-        const moduleClass = class ConfigDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'ConfigModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            isGlobal: options.isGlobal
-        });
         return {
-            module: moduleClass,
+            module: ConfigModule,
             providers: [
                 {
                     provide: CONFIG_OPTIONS,
@@ -28,28 +12,19 @@ export class ConfigModule {
                 },
                 ConfigService
             ],
+            exports: [
+                ConfigService,
+                CONFIG_OPTIONS
+            ],
             ...options.isGlobal ? {
                 global: true
             } : {}
         };
     }
     static forRootAsync(options) {
-        const moduleClass = class ConfigAsyncDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'ConfigModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            imports: options.imports ?? [],
-            exports: [
-                ConfigService,
-                CONFIG_OPTIONS
-            ],
-            isGlobal: options.isGlobal
-        });
         return {
-            module: moduleClass,
+            module: ConfigModule,
+            imports: options.imports ?? [],
             providers: [
                 {
                     provide: CONFIG_OPTIONS,
@@ -61,6 +36,10 @@ export class ConfigModule {
                 },
                 ConfigService
             ],
+            exports: [
+                ConfigService,
+                CONFIG_OPTIONS
+            ],
             ...options.isGlobal ? {
                 global: true
             } : {}

package/dist/container/container.js

@@ -1,6 +1,7 @@
 import { Scope } from "../constants.js";
 import { getConstructorDependencies, getInjectMetadata, getScope, isInjectable } from "./decorators.js";
 import { ForwardRef, InjectionToken } from "./types.js";
+const IMPORT_TYPE_HINT = 'Did you use `import type { X }`? TypeScript strips type-only imports at ' + 'runtime and `design:paramtypes` emits `Object`/`undefined` for their ' + 'positions. Use a runtime `import { X }` for DI tokens.';
 export class Container {
     providers = new Map();
     resolutionStack = new Set();
@@ -52,6 +53,12 @@ export class Container {
     resolve(token) {
         const registration = this.providers.get(token);
         if (!registration) {
+            // `Object`/undefined at a token position is the fingerprint of a
+            // type-only import that TypeScript stripped — emit the hint BEFORE
+            // auto-registering Object as a provider (which would silently "succeed").
+            if (token === Object || token == null) {
+                throw new Error(`No provider found for token: ${this.tokenToString(token)}. ` + IMPORT_TYPE_HINT);
+            }
             if (typeof token === 'function') {
                 this.register(token);
                 return this.resolve(token);
@@ -155,7 +162,7 @@ export class Container {
             const token = isForwardRef ? rawToken.factory() : rawToken ?? paramType;
             if (!token || token === Object) {
                 if (meta?.optional) return undefined;
-                throw new Error(`Cannot resolve dependency at index ${index} for ${target.name}. ` + `Parameter type is undefined or Object. ` + `Use @Inject() to specify the token explicitly.`);
+                throw new Error(`Cannot resolve dependency at index ${index} for ${target.name}. ` + `Parameter type is undefined or Object. ` + IMPORT_TYPE_HINT + ` Alternatively, use \`@Inject()\` to specify the token explicitly.`);
             }
             if (meta?.optional && !this.has(token)) {
                 return undefined;

package/dist/cors/cors.module.js

@@ -1,7 +1,4 @@
 import { cors } from "hono/cors";
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { APP_MIDDLEWARE } from "../pipeline/tokens.js";
 import { CORS_OPTIONS } from "./cors.tokens.js";
 export class CorsModule {
@@ -17,19 +14,8 @@ export class CorsModule {
         const middleware = {
             use: (c, next)=>corsMiddleware(c, next)
         };
-        const moduleClass = class CorsDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'CorsModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports: [
-                CORS_OPTIONS
-            ]
-        });
         return {
-            module: moduleClass,
+            module: CorsModule,
             providers: [
                 {
                     provide: CORS_OPTIONS,
@@ -39,6 +25,9 @@ export class CorsModule {
                     provide: APP_MIDDLEWARE,
                     useValue: middleware
                 }
+            ],
+            exports: [
+                CORS_OPTIONS
             ]
         };
     }

package/dist/factory.d.ts

@@ -4,3 +4,4 @@ import type { RouteManagerOptions } from './http/route.manager';
 export declare const VelaFactory: {
     create(rootModule: Type, options?: RouteManagerOptions): Promise<VelaApplication>;
 };
+export declare const createApplication: typeof VelaFactory.create;

package/dist/factory.js

@@ -73,3 +73,4 @@ export const VelaFactory = {
         return app;
     }
 };
+export const createApplication = VelaFactory.create.bind(VelaFactory);

package/dist/fetch/fetch.module.js

@@ -4,52 +4,30 @@ function _ts_decorate(decorators, target, key, desc) {
     else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { createModuleRef } from "../module/decorators.js";
 import { Module } from "../module/decorators.js";
 import { HttpService, HTTP_MODULE_OPTIONS } from "./fetch.service.js";
 export class HttpModule {
     static register(options = {}) {
-        const moduleClass = class HttpDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'HttpModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports: [
-                HttpService,
-                HTTP_MODULE_OPTIONS
-            ]
-        });
         return {
-            module: moduleClass,
+            module: createModuleRef('HttpModule'),
             providers: [
                 {
                     provide: HTTP_MODULE_OPTIONS,
                     useValue: options
                 },
                 HttpService
-            ]
-        };
-    }
-    static registerAsync(options) {
-        const moduleClass = class HttpAsyncDynamicModule {
-        };
-        Object.defineProperty(moduleClass, 'name', {
-            value: 'HttpModule'
-        });
-        defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            imports: options.imports ?? [],
+            ],
             exports: [
                 HttpService,
                 HTTP_MODULE_OPTIONS
             ]
-        });
+        };
+    }
+    static registerAsync(options) {
         return {
-            module: moduleClass,
+            module: createModuleRef('HttpModule'),
+            imports: options.imports ?? [],
             providers: [
                 {
                     provide: HTTP_MODULE_OPTIONS,
@@ -57,6 +35,10 @@ export class HttpModule {
                     inject: options.inject ?? []
                 },
                 HttpService
+            ],
+            exports: [
+                HttpService,
+                HTTP_MODULE_OPTIONS
             ]
         };
     }

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

@@ -18,9 +18,12 @@ export interface MiddlewareRouteDefinition {
     middleware: Array<Type<NestMiddleware> | NestMiddleware>;
     routes: RouteInfo[];
     excludes: RouteInfo[];
+    /** Stable-sort key; lower runs first. Default 0. */
+    priority?: number;
 }
 export interface MiddlewareConfigProxy {
     exclude(...routes: Array<string | RouteInfo>): MiddlewareConfigProxy;
+    withPriority(priority: number): MiddlewareConfigProxy;
     forRoutes(...routes: Array<string | Function | RouteInfo>): MiddlewareConsumer;
 }
 export interface MiddlewareConsumer {

package/dist/http/middleware-consumer.js

@@ -17,11 +17,16 @@ export class MiddlewareBuilder {
             ...middleware
         ];
         let currentExcludes = [];
+        let currentPriority;
         const proxy = {
             exclude: (...routes)=>{
                 currentExcludes = routes.map(normalizeRouteArg);
                 return proxy;
             },
+            withPriority: (priority)=>{
+                currentPriority = priority;
+                return proxy;
+            },
             // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
             forRoutes: (...routes)=>{
                 this.definitions.push({
@@ -29,9 +34,13 @@ export class MiddlewareBuilder {
                     routes: routes.flatMap(resolveRouteArg),
                     excludes: [
                         ...currentExcludes
-                    ]
+                    ],
+                    ...currentPriority !== undefined ? {
+                        priority: currentPriority
+                    } : {}
                 });
                 currentExcludes = [];
+                currentPriority = undefined;
                 return this;
             }
         };

package/dist/http/route.manager.d.ts

@@ -38,6 +38,7 @@ export declare class RouteManager {
     useGlobalFilterTokens(...filterTokens: Array<Token<ExceptionFilter>>): this;
     private instantiate;
     private instantiateMany;
+    private getMiddlewarePriority;
     private getRequestContainer;
     registerController(controller: Type): this;
     build(): Promise<Hono>;

package/dist/http/route.manager.js

@@ -175,6 +175,35 @@ 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') {
+            const p = entry.priority;
+            if (typeof p === 'number') return p;
+        }
+        if (typeof entry === 'object') {
+            const inst = entry;
+            if (typeof inst.priority === 'number') return inst.priority;
+            if (typeof inst.constructor?.priority === 'number') return inst.constructor.priority;
+        }
+        try {
+            const resolved = this.instantiate(entry, this.container);
+            if (resolved && typeof resolved === 'object') {
+                const p = resolved.priority;
+                if (typeof p === 'number') return p;
+                const cp = resolved.constructor?.priority;
+                if (typeof cp === 'number') return cp;
+            }
+        } catch  {
+        // Unresolvable at build time (e.g. request-scoped) — default 0
+        }
+        return 0;
+    }
     getRequestContainer(c) {
         const existing = c.get('container');
         if (existing) {
@@ -203,16 +232,29 @@ export class RouteManager {
     }
     async build() {
         const app = new Hono();
+        // Sort global middleware by priority (lower runs first) with insertion
+        // index as tiebreaker so equal priorities preserve registration order.
+        const sortedGlobal = this.globalMiddleware.map((entry, index)=>({
+                entry,
+                index,
+                priority: this.getMiddlewarePriority(entry)
+            })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
         // Register global middleware on the Hono app
-        for (const mw of this.globalMiddleware){
+        for (const { entry } of sortedGlobal){
             app.use('*', (c, next)=>{
                 const requestContainer = this.getRequestContainer(c);
-                const resolved = this.instantiate(mw, requestContainer);
+                const resolved = this.instantiate(entry, requestContainer);
                 return resolved.use(c, next);
             });
         }
+        // Sort consumer middleware with the same stable-by-index rule.
+        const sortedConsumer = this.consumerMiddlewareDefinitions.map((def, index)=>({
+                def,
+                index,
+                priority: def.priority ?? 0
+            })).sort((a, b)=>a.priority - b.priority || a.index - b.index);
         // Register MiddlewareConsumer-configured middleware
-        for (const def of this.consumerMiddlewareDefinitions){
+        for (const { def } of sortedConsumer){
             const matchRoute = this.compileRouteMatcher(def.routes);
             const matchExclude = this.compileRouteMatcher(def.excludes);
             app.use('*', (c, next)=>{

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import './metadata';
 export { defineMetadata, getMetadata } from './metadata';
-export { VelaFactory } from './factory';
+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 { 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';
@@ -24,7 +26,7 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 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';
 export type { ThrottlerModuleOptions, ThrottleConfig, ThrottlerStore, ThrottlerStorageRecord, RateLimitInfo, } from './throttler/index';
-export { Global, Module } from './module/index';
+export { Global, Module, createModuleRef } from './module/index';
 export type { ModuleOptions, DynamicModule, AsyncModuleOptions, ModuleImport } from './module/index';
 export { RequestMethod } from './http/index';
 export type { MiddlewareConsumer, NestModule, RouteInfo } from './http/index';
@@ -41,6 +43,7 @@ export type { RouteManagerOptions } from './http/index';
 export { ModuleLoader } from './module/index';
 export { ComponentManager } from './pipeline/index';
 export { createZodDto, ValidationPipe } from './validation/index';
+export type { CreateZodDtoOptions } from './validation/index';
 export { Serialize, SerializerInterceptor, SERIALIZE_METADATA } from './serialization/index';
 export { Test, TestingModule, TestingModuleBuilder } from './testing/index';
 export { getRuntimeKey, env } from 'hono/adapter';

package/dist/index.js

@@ -1,8 +1,10 @@
 import "./metadata.js";
 export { defineMetadata, getMetadata } from "./metadata.js";
 // Factory & Application
-export { VelaFactory } from "./factory.js";
+export { VelaFactory, createApplication } from "./factory.js";
 export { VelaApplication } from "./application.js";
+// OpenAPI
+export { createOpenApiDocument, ApiDoc, ApiTags, zodToJsonSchema } from "./openapi/index.js";
 // DI Container
 export { Container, Injectable, Inject, Optional, InjectionToken, ForwardRef, forwardRef, ModuleRef, mixin } from "./container/index.js";
 // Constants
@@ -28,7 +30,7 @@ export { HealthModule, HealthCheckService, HealthIndicatorService, HttpHealthInd
 // Throttler
 export { ThrottlerModule, ThrottlerGuard, ThrottlerStorage, Throttle, SkipThrottle, THROTTLER_OPTIONS, THROTTLER_STORAGE, THROTTLE_METADATA, SKIP_THROTTLE_METADATA } from "./throttler/index.js";
 // Module
-export { Global, Module } from "./module/index.js";
+export { Global, Module, createModuleRef } from "./module/index.js";
 export { RequestMethod } from "./http/index.js";
 // Pipeline Decorators
 export { UseMiddleware, UseGuards, UsePipes, UseInterceptors, UseFilters, Catch, SetMetadata, Reflector, APP_GUARD, APP_PIPE, APP_INTERCEPTOR, APP_FILTER, APP_MIDDLEWARE } from "./pipeline/index.js";

package/dist/module/decorators.d.ts

@@ -1,6 +1,8 @@
 import type { Constructor } from '../registry/types';
+import type { Type } from '../container/types';
 import type { ModuleMetadata, ModuleOptions } from './types';
 export declare function Global(): ClassDecorator;
 export declare function Module(options?: ModuleOptions): ClassDecorator;
 export declare function isModule(target: Constructor): boolean;
+export declare function createModuleRef(name: string): Type;
 export declare function getModuleMetadata(target: Constructor): ModuleMetadata | undefined;

package/dist/module/decorators.js

@@ -30,6 +30,14 @@ export function Module(options = {}) {
 export function isModule(target) {
     return MetadataRegistry.getModuleOptions(target) !== undefined || getMetadata(METADATA_KEYS.MODULE, target) === true || getMetadata(METADATA_KEYS.MODULE_OPTIONS, target) !== undefined;
 }
+export function createModuleRef(name) {
+    const moduleClass = class {
+    };
+    Object.defineProperty(moduleClass, 'name', {
+        value: name
+    });
+    return moduleClass;
+}
 export function getModuleMetadata(target) {
     if (!isModule(target)) {
         return undefined;

package/dist/module/index.d.ts

@@ -1,3 +1,3 @@
-export { Global, Module, isModule, getModuleMetadata } from './decorators';
+export { Global, Module, isModule, getModuleMetadata, createModuleRef } from './decorators';
 export { ModuleLoader } from './module-loader';
 export type { ModuleOptions, ModuleMetadata, DynamicModule, AsyncModuleOptions, ModuleImport } from './types';

package/dist/module/index.js

@@ -1,2 +1,2 @@
-export { Global, Module, isModule, getModuleMetadata } from "./decorators.js";
+export { Global, Module, isModule, getModuleMetadata, createModuleRef } from "./decorators.js";
 export { ModuleLoader } from "./module-loader.js";

package/dist/module/module-loader.js

@@ -63,11 +63,13 @@ export class ModuleLoader {
         let extraImports = [];
         let extraControllers = [];
         let extraProviders = [];
+        let extraExports = [];
         if (isDynamicModule(moduleClassOrDynamic)) {
             moduleClass = moduleClassOrDynamic.module;
             extraImports = moduleClassOrDynamic.imports ?? [];
             extraControllers = moduleClassOrDynamic.controllers ?? [];
             extraProviders = moduleClassOrDynamic.providers ?? [];
+            extraExports = moduleClassOrDynamic.exports ?? [];
         } else {
             moduleClass = moduleClassOrDynamic;
         }
@@ -86,7 +88,11 @@ export class ModuleLoader {
             throw new Error(`Circular module dependency detected: ${chain}`);
         }
         if (!isModule(moduleClass)) {
-            throw new Error(`${moduleClass.name} is not a module. Add @Module() decorator to the class.`);
+            if (isDynamicModule(moduleClassOrDynamic)) {
+                MetadataRegistry.setModuleOptions(moduleClass, {});
+            } else {
+                throw new Error(`${moduleClass.name} is not a module. Add @Module() decorator to the class.`);
+            }
         }
         const metadata = getModuleMetadata(moduleClass);
         if (!metadata) {
@@ -134,7 +140,11 @@ export class ModuleLoader {
                 MetadataRegistry.propagateControllerComponents(moduleClass, controller);
             }
             this.processedModules.add(moduleClass);
-            const exports = this.buildExportSet(metadata.exports, allProviders, importedProviders);
+            const allExports = [
+                ...metadata.exports,
+                ...extraExports
+            ];
+            const exports = this.buildExportSet(allExports, allProviders, importedProviders);
             this.moduleExportsCache.set(moduleClass, exports);
             const isGlobal = metadata.isGlobal || isDynamicModule(moduleClassOrDynamic) && moduleClassOrDynamic.global === true;
             if (isGlobal) {

package/dist/openapi/decorators.d.ts

@@ -0,0 +1,20 @@
+import type { ApiDocMetadata } from './types';
+export declare const API_DOC_METADATA = "vela:openapi:doc";
+export declare const API_TAGS_METADATA = "vela:openapi:tags";
+/**
+ * Attach OpenAPI documentation to a route handler (or controller).
+ *
+ * ```ts
+ * @Get('/:id')
+ * @ApiDoc({ summary: 'Get a user', description: '...', operationId: 'getUser' })
+ * findOne(@Param('id') id: string) { ... }
+ * ```
+ */
+export declare function ApiDoc(metadata: ApiDocMetadata): MethodDecorator & ClassDecorator;
+/**
+ * Attach OpenAPI tags to a controller or handler. Handler-level tags merge
+ * with controller-level tags; duplicates are de-duplicated in the output.
+ */
+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;

package/dist/openapi/decorators.js

@@ -0,0 +1,37 @@
+export const API_DOC_METADATA = 'vela:openapi:doc';
+export const API_TAGS_METADATA = 'vela:openapi:tags';
+/**
+ * Attach OpenAPI documentation to a route handler (or controller).
+ *
+ * ```ts
+ * @Get('/:id')
+ * @ApiDoc({ summary: 'Get a user', description: '...', operationId: 'getUser' })
+ * findOne(@Param('id') id: string) { ... }
+ * ```
+ */ export function ApiDoc(metadata) {
+    return (target, propertyKey)=>{
+        if (propertyKey !== undefined) {
+            Reflect.defineMetadata(API_DOC_METADATA, metadata, target, propertyKey);
+        } else {
+            Reflect.defineMetadata(API_DOC_METADATA, metadata, target);
+        }
+    };
+}
+/**
+ * Attach OpenAPI tags to a controller or handler. Handler-level tags merge
+ * with controller-level tags; duplicates are de-duplicated in the output.
+ */ export function ApiTags(...tags) {
+    return (target, propertyKey)=>{
+        if (propertyKey !== undefined) {
+            Reflect.defineMetadata(API_TAGS_METADATA, tags, target, propertyKey);
+        } else {
+            Reflect.defineMetadata(API_TAGS_METADATA, tags, target);
+        }
+    };
+}
+export function getApiDoc(target, propertyKey) {
+    return propertyKey !== undefined ? Reflect.getMetadata(API_DOC_METADATA, target, propertyKey) : Reflect.getMetadata(API_DOC_METADATA, target);
+}
+export function getApiTags(target, propertyKey) {
+    return propertyKey !== undefined ? Reflect.getMetadata(API_TAGS_METADATA, target, propertyKey) : Reflect.getMetadata(API_TAGS_METADATA, target);
+}

package/dist/openapi/document.d.ts

@@ -0,0 +1,3 @@
+import type { Type } from '../container/types';
+import type { CreateOpenApiDocumentOptions, OpenApiDocument } from './types';
+export declare function createOpenApiDocument(rootModule: Type, options?: CreateOpenApiDocumentOptions): OpenApiDocument;

package/dist/openapi/document.js

@@ -0,0 +1,187 @@
+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 { isOptional, zodToJsonSchema } from "./zod-to-json-schema.js";
+function isDynamicModuleLike(v) {
+    return !!v && typeof v === 'object' && 'module' in v && typeof v.module === 'function';
+}
+function collectControllers(rootModule) {
+    const visited = new Set();
+    const controllers = new Set();
+    function visit(entry) {
+        const unwrapped = entry instanceof ForwardRef ? entry.factory() : entry;
+        const moduleClass = isDynamicModuleLike(unwrapped) ? unwrapped.module : unwrapped;
+        const extraControllers = isDynamicModuleLike(unwrapped) ? unwrapped.controllers ?? [] : [];
+        const extraImports = isDynamicModuleLike(unwrapped) ? unwrapped.imports ?? [] : [];
+        if (typeof moduleClass !== 'function' || visited.has(moduleClass)) return;
+        visited.add(moduleClass);
+        const metadata = getModuleMetadata(moduleClass);
+        if (metadata) {
+            for (const controller of metadata.controllers)controllers.add(controller);
+            for (const imp of metadata.imports)visit(imp);
+        }
+        for (const controller of extraControllers)controllers.add(controller);
+        for (const imp of extraImports)visit(imp);
+    }
+    visit(rootModule);
+    return [
+        ...controllers
+    ];
+}
+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) {
+    const left = a.endsWith('/') ? a.slice(0, -1) : a;
+    const right = b && !b.startsWith('/') ? `/${b}` : b;
+    const joined = `${left}${right}`;
+    return joined || '/';
+}
+function getParamSchema(param, paramtypes) {
+    const metatype = paramtypes?.[param.index];
+    if (metatype?.schema) {
+        return zodToJsonSchema(metatype.schema);
+    }
+    return undefined;
+}
+function isParamOptional(param, paramtypes) {
+    const metatype = paramtypes?.[param.index];
+    if (metatype?.schema) {
+        return isOptional(metatype.schema);
+    }
+    return true;
+}
+function buildOperation(controller, route, pathString) {
+    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)
+    ].map((m)=>m[1]);
+    for (const param of paramMetadata){
+        if (param.type === ParamType.PARAM && param.name) {
+            declaredPathParams.add(param.name);
+            parameters.push({
+                name: param.name,
+                in: 'path',
+                required: true,
+                schema: getParamSchema(param, paramtypes) ?? {
+                    type: 'string'
+                }
+            });
+        } else if (param.type === ParamType.QUERY && param.name) {
+            parameters.push({
+                name: param.name,
+                in: 'query',
+                required: !isParamOptional(param, paramtypes),
+                schema: getParamSchema(param, paramtypes) ?? {
+                    type: 'string'
+                }
+            });
+        } else if (param.type === ParamType.HEADERS && param.name) {
+            parameters.push({
+                name: param.name,
+                in: 'header',
+                required: !isParamOptional(param, paramtypes),
+                schema: getParamSchema(param, paramtypes) ?? {
+                    type: 'string'
+                }
+            });
+        } else if (param.type === ParamType.BODY) {
+            const schema = getParamSchema(param, paramtypes);
+            if (schema) {
+                requestBody = {
+                    required: !isParamOptional(param, paramtypes),
+                    content: {
+                        'application/json': {
+                            schema
+                        }
+                    }
+                };
+            }
+        }
+    }
+    for (const name of pathParamNames){
+        if (!declaredPathParams.has(name)) {
+            parameters.push({
+                name,
+                in: 'path',
+                required: true,
+                schema: {
+                    type: 'string'
+                }
+            });
+        }
+    }
+    const docMeta = getApiDoc(controller.prototype, handlerName);
+    const controllerTags = getApiTags(controller) ?? [];
+    const handlerTags = getApiTags(controller.prototype, handlerName) ?? [];
+    const docTags = docMeta?.tags ?? [];
+    const mergedTags = [
+        ...new Set([
+            ...controllerTags,
+            ...handlerTags,
+            ...docTags
+        ])
+    ];
+    const operation = {
+        responses: {
+            '200': {
+                description: 'OK'
+            }
+        }
+    };
+    if (parameters.length > 0) operation.parameters = parameters;
+    if (requestBody) operation.requestBody = requestBody;
+    if (docMeta?.summary) operation.summary = docMeta.summary;
+    if (docMeta?.description) operation.description = docMeta.description;
+    if (docMeta?.operationId) operation.operationId = docMeta.operationId;
+    if (docMeta?.deprecated) operation.deprecated = docMeta.deprecated;
+    if (mergedTags.length > 0) operation.tags = mergedTags;
+    return operation;
+}
+const VERB_WHITELIST = new Set([
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'options',
+    'head'
+]);
+export function createOpenApiDocument(rootModule, options = {}) {
+    const paths = {};
+    const globalPrefix = options.globalPrefix ?? '';
+    for (const controller of collectControllers(rootModule)){
+        const controllerPath = MetadataRegistry.getControllerPath(controller);
+        const routes = MetadataRegistry.getRoutes(controller);
+        for (const route of routes){
+            const method = route.method.toLowerCase();
+            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 pathItem = paths[pathString] ?? {};
+            pathItem[method] = operation;
+            paths[pathString] = pathItem;
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: options.info?.title ?? 'Vela API',
+            version: options.info?.version ?? '1.0.0',
+            ...options.info?.description ? {
+                description: options.info.description
+            } : {}
+        },
+        paths
+    };
+}

package/dist/openapi/index.d.ts

@@ -0,0 +1,4 @@
+export { createOpenApiDocument } from './document';
+export { ApiDoc, ApiTags, API_DOC_METADATA, API_TAGS_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';

package/dist/openapi/index.js

@@ -0,0 +1,3 @@
+export { createOpenApiDocument } from "./document.js";
+export { ApiDoc, ApiTags, API_DOC_METADATA, API_TAGS_METADATA } from "./decorators.js";
+export { zodToJsonSchema } from "./zod-to-json-schema.js";

package/dist/openapi/types.d.ts

@@ -0,0 +1,85 @@
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+export interface JsonSchema {
+    type?: string | string[];
+    format?: string;
+    enum?: Array<string | number | boolean | null>;
+    const?: unknown;
+    description?: string;
+    nullable?: boolean;
+    default?: unknown;
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    $ref?: string;
+    [key: string]: unknown;
+}
+export interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: JsonSchema;
+}
+export interface OpenApiRequestBody {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, {
+        schema: JsonSchema;
+    }>;
+}
+export interface OpenApiResponse {
+    description: string;
+    content?: Record<string, {
+        schema: JsonSchema;
+    }>;
+}
+export interface OpenApiOperation {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    deprecated?: boolean;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBody;
+    responses: Record<string, OpenApiResponse>;
+}
+export type HttpVerb = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options' | 'head';
+export type OpenApiPathItem = {
+    [verb in HttpVerb]?: OpenApiOperation;
+};
+export interface OpenApiDocument {
+    openapi: '3.1.0';
+    info: OpenApiInfo;
+    paths: Record<string, OpenApiPathItem>;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+    };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+}
+export interface ApiDocMetadata {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    deprecated?: boolean;
+    tags?: string[];
+}
+export interface CreateOpenApiDocumentOptions {
+    info?: Partial<OpenApiInfo>;
+    globalPrefix?: string;
+}

package/dist/openapi/types.js

@@ -0,0 +1,4 @@
+// Minimal OpenAPI 3.1 subset Vela emits. Kept intentionally loose (index
+// signatures on schemas, open tags array) so users can extend without
+// fighting the types. Covers what createOpenApiDocument actually produces.
+export { };

package/dist/openapi/zod-to-json-schema.d.ts

@@ -0,0 +1,4 @@
+import type { JsonSchema } from './types';
+export declare function zodToJsonSchema(schema: unknown): JsonSchema;
+export declare function isOptional(schema: unknown): boolean;
+export declare function isNullable(schema: unknown): boolean;

package/dist/openapi/zod-to-json-schema.js

@@ -0,0 +1,57 @@
+// Zod v4 exposes `schema.toJSONSchema()` on every schema instance — an
+// authoritative, zero-cost converter. We delegate to it when present and
+// strip the `$schema` meta so the result embeds cleanly into OpenAPI
+// components. For non-Zod schemas (anything that doesn't expose the
+// method) we return an empty (permissive) schema.
+function stripOpenApiIncompatible(schema) {
+    const out = {
+        ...schema
+    };
+    delete out.$schema;
+    // Zod v4 emits `additionalProperties: false` by default; users rarely
+    // want that constraint in their published OpenAPI doc, so leave it in
+    // — it's a faithful reflection of the schema. No change here.
+    if (Array.isArray(out.properties)) {
+    // shouldn't happen, but guard
+    } else if (out.properties && typeof out.properties === 'object') {
+        const props = out.properties;
+        const cleaned = {};
+        for (const [key, val] of Object.entries(props)){
+            cleaned[key] = stripOpenApiIncompatible(val);
+        }
+        out.properties = cleaned;
+    }
+    if (out.items && typeof out.items === 'object') {
+        out.items = stripOpenApiIncompatible(out.items);
+    }
+    return out;
+}
+export function zodToJsonSchema(schema) {
+    if (!schema || typeof schema !== 'object') return {};
+    const maybe = schema.toJSONSchema;
+    if (typeof maybe === 'function') {
+        try {
+            const result = maybe.call(schema);
+            if (result && typeof result === 'object') {
+                return stripOpenApiIncompatible(result);
+            }
+        } catch  {
+        // Zod may refuse to convert certain schemas; fall through.
+        }
+    }
+    return {};
+}
+// Zod v4 and v3 both name constructors `ZodOptional` / `ZodDefault` /
+// `ZodNullable`. Checking the constructor name is cheap and avoids
+// depending on internal `_def` shape.
+function ctorName(schema) {
+    if (!schema || typeof schema !== 'object') return undefined;
+    return schema.constructor?.name;
+}
+export function isOptional(schema) {
+    const name = ctorName(schema);
+    return name === 'ZodOptional' || name === 'ZodDefault';
+}
+export function isNullable(schema) {
+    return ctorName(schema) === 'ZodNullable';
+}

package/dist/schedule/schedule.module.js

@@ -1,22 +1,9 @@
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { ScheduleExecutor } from "./schedule.executor.js";
 import { ScheduleRegistry } from "./schedule.registry.js";
 import { SCHEDULE_MODULE_OPTIONS } from "./schedule.tokens.js";
-function makeScheduleModuleClass() {
-    const moduleClass = class ScheduleDynamicModule {
-    };
-    Object.defineProperty(moduleClass, 'name', {
-        value: 'ScheduleModule'
-    });
-    defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-    return moduleClass;
-}
 export class ScheduleModule {
     static forRoot(options = {}) {
         const { enableTimers = false } = options;
-        const moduleClass = makeScheduleModuleClass();
         const providers = [
             {
                 provide: SCHEDULE_MODULE_OPTIONS,
@@ -32,17 +19,14 @@ export class ScheduleModule {
             providers.push(ScheduleExecutor);
             exports.push(ScheduleExecutor);
         }
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports
-        });
         return {
-            module: moduleClass,
-            providers
+            module: ScheduleModule,
+            providers,
+            exports
         };
     }
     static forRootAsync(options) {
         const { enableTimers = false } = options;
-        const moduleClass = makeScheduleModuleClass();
         const providers = [
             {
                 provide: SCHEDULE_MODULE_OPTIONS,
@@ -59,13 +43,11 @@ export class ScheduleModule {
             providers.push(ScheduleExecutor);
             exports.push(ScheduleExecutor);
         }
-        MetadataRegistry.setModuleOptions(moduleClass, {
+        return {
+            module: ScheduleModule,
             imports: options.imports ?? [],
+            providers,
             exports
-        });
-        return {
-            module: moduleClass,
-            providers
         };
     }
 }

package/dist/throttler/throttler.module.js

@@ -1,29 +1,9 @@
-import { METADATA_KEYS } from "../constants.js";
-import { defineMetadata } from "../metadata.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { APP_GUARD } from "../pipeline/tokens.js";
 import { ThrottlerGuard } from "./throttler.guard.js";
 import { ThrottlerStorage } from "./throttler.storage.js";
 import { THROTTLER_OPTIONS, THROTTLER_STORAGE } from "./throttler.tokens.js";
-function makeThrottlerModuleClass() {
-    const moduleClass = class ThrottlerDynamicModule {
-    };
-    Object.defineProperty(moduleClass, 'name', {
-        value: 'ThrottlerModule'
-    });
-    defineMetadata(METADATA_KEYS.MODULE, true, moduleClass);
-    return moduleClass;
-}
 export class ThrottlerModule {
     static forRoot(options) {
-        const moduleClass = makeThrottlerModuleClass();
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            exports: [
-                THROTTLER_OPTIONS,
-                THROTTLER_STORAGE,
-                ThrottlerGuard
-            ]
-        });
         const providers = [
             {
                 provide: THROTTLER_OPTIONS,
@@ -40,20 +20,16 @@ export class ThrottlerModule {
             }
         ];
         return {
-            module: moduleClass,
-            providers
-        };
-    }
-    static forRootAsync(options) {
-        const moduleClass = makeThrottlerModuleClass();
-        MetadataRegistry.setModuleOptions(moduleClass, {
-            imports: options.imports ?? [],
+            module: ThrottlerModule,
+            providers,
             exports: [
                 THROTTLER_OPTIONS,
                 THROTTLER_STORAGE,
                 ThrottlerGuard
             ]
-        });
+        };
+    }
+    static forRootAsync(options) {
         const providers = [
             {
                 provide: THROTTLER_OPTIONS,
@@ -74,8 +50,14 @@ export class ThrottlerModule {
             }
         ];
         return {
-            module: moduleClass,
-            providers
+            module: ThrottlerModule,
+            imports: options.imports ?? [],
+            providers,
+            exports: [
+                THROTTLER_OPTIONS,
+                THROTTLER_STORAGE,
+                ThrottlerGuard
+            ]
         };
     }
 }

package/dist/validation/create-zod-dto.d.ts

@@ -1,8 +1,13 @@
-interface ZodSchema {
+interface ZodLikeSchema {
     parse(data: unknown): unknown;
 }
-export declare function createZodDto<T extends ZodSchema>(schema: T): {
-    new (): unknown;
+type InferOutput<T extends ZodLikeSchema> = ReturnType<T['parse']>;
+export interface CreateZodDtoOptions {
+    /** Override the generated class name (useful for debugging and OpenAPI). */
+    name?: string;
+}
+export declare function createZodDto<T extends ZodLikeSchema>(schema: T, options?: CreateZodDtoOptions): {
+    new (initial?: InferOutput<T>): InferOutput<T>;
     schema: T;
 };
 export {};

package/dist/validation/create-zod-dto.js

@@ -1,6 +1,17 @@
-export function createZodDto(schema) {
+export function createZodDto(schema, options = {}) {
     let ZodDto = class ZodDto {
         static schema = schema;
+        constructor(initial){
+            if (initial && typeof initial === 'object') {
+                Object.assign(this, initial);
+            }
+        }
     };
+    if (options.name) {
+        Object.defineProperty(ZodDto, 'name', {
+            value: options.name,
+            configurable: true
+        });
+    }
     return ZodDto;
 }

package/dist/validation/index.d.ts

@@ -1,2 +1,3 @@
 export { createZodDto } from './create-zod-dto';
+export type { CreateZodDtoOptions } from './create-zod-dto';
 export { ValidationPipe } from './validation.pipe';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",