@velajs/vela 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -2,6 +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 { 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';

package/dist/index.js

@@ -3,6 +3,8 @@ export { defineMetadata, getMetadata } from "./metadata.js";
 // Factory & Application
 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

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/package.json

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