@velajs/vela 0.8.0 → 0.10.0

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/index.d.ts

@@ -2,14 +2,14 @@ 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';
 export { Controller, Version, Get, Post, Put, Patch, Delete, Options, Head, All, Sse, Param, Query, Body, Headers, Req, Res, Ip, Cookie, Cookies, RawBody, HttpCode, Header, Redirect, createParamDecorator, applyDecorators, } from './http/index';
 export { Logger, LogLevel } from './services/index';
-export type { LoggerService } from './services/index';
+export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './services/index';
 export { ConfigModule, ConfigService, CONFIG_OPTIONS } from './config/index';
 export type { ConfigModuleOptions } from './config/index';
 export { HttpModule, HttpService, HTTP_MODULE_OPTIONS, HttpRequestException } from './fetch/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

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>`;
+}

package/dist/openapi/types.d.ts

@@ -79,7 +79,25 @@ export interface ApiDocMetadata {
     deprecated?: boolean;
     tags?: string[];
 }
+export interface ApiResponseOptions {
+    description: string;
+    /** Zod schema, DTO class (from createZodDto), or raw JSON Schema. */
+    schema?: unknown;
+}
+export interface ApiResponseEntry extends ApiResponseOptions {
+    status: number | string;
+}
 export interface CreateOpenApiDocumentOptions {
     info?: Partial<OpenApiInfo>;
     globalPrefix?: string;
 }
+export interface MountOpenApiOptions {
+    /** Pre-built OpenAPI document to serve. */
+    document: OpenApiDocument;
+    /** Path for the JSON endpoint. Default `/docs.json`. */
+    path?: string;
+    /** Opt-in UI renderer. Only `scalar` is bundled today. */
+    ui?: 'scalar';
+    /** Path the UI is served at when `ui` is set. Default `/docs`. */
+    uiPath?: string;
+}

package/dist/services/index.d.ts

@@ -1,2 +1,2 @@
 export { Logger, LogLevel } from './logger';
-export type { LoggerService } from './logger';
+export type { LoggerService, ContextProvider, Writer, LoggerLevelName } from './logger';

package/dist/services/logger.d.ts

@@ -13,18 +13,46 @@ export interface LoggerService {
     debug?(message: unknown, ...optionalParams: unknown[]): void;
     verbose?(message: unknown, ...optionalParams: unknown[]): void;
 }
+export type ContextProvider = () => Record<string, unknown>;
+export type LoggerLevelName = 'LOG' | 'ERROR' | 'WARN' | 'DEBUG' | 'VERBOSE';
+export type Writer = (level: LoggerLevelName, line: string, ...rest: unknown[]) => void;
 export declare class Logger implements LoggerService {
     static level: LogLevel;
     private static globalLogger;
+    private static globalContextProviders;
+    private static globalWriter;
     private context?;
+    private instanceContextProviders;
+    private instanceWriter?;
     static setLogLevel(level: LogLevel): void;
     static overrideLogger(logger: LoggerService | false): void;
+    /** Register a context provider run on every log line from every logger. */
+    static addContextProvider(provider: ContextProvider): void;
+    /** Remove all registered global context providers. */
+    static clearContextProviders(): void;
+    /** Replace the default console writer. Useful on edge runtimes that have
+     *  a different output sink (e.g. `env.LOGS.writeDataPoint` on Workers). */
+    static setWriter(writer: Writer): void;
+    /** Restore the default console-based writer. */
+    static resetWriter(): void;
     constructor(context?: string);
     setContext(context: string): void;
+    /** Add a context provider that runs only for THIS logger instance.
+     *  Children created via extend() inherit these providers by copy. */
+    addContextProvider(provider: ContextProvider): this;
+    /** Override the writer for this logger (and any extend() children). */
+    setWriter(writer: Writer): this;
+    /** Create a child logger with a nested namespace. Context becomes
+     *  `parent:child`; instance-level providers and writers are inherited
+     *  by copy so later mutations on either logger stay isolated. */
+    extend(namespace: string): Logger;
     log(message: unknown, ...optionalParams: unknown[]): void;
     error(message: unknown, ...optionalParams: unknown[]): void;
     warn(message: unknown, ...optionalParams: unknown[]): void;
     debug(message: unknown, ...optionalParams: unknown[]): void;
     verbose(message: unknown, ...optionalParams: unknown[]): void;
+    private emit;
     private formatMessage;
+    private collectContext;
+    private formatContextObj;
 }

package/dist/services/logger.js

@@ -17,16 +17,50 @@ export var LogLevel = /*#__PURE__*/ function(LogLevel) {
     LogLevel[LogLevel["SILENT"] = 5] = "SILENT";
     return LogLevel;
 }({});
+const defaultWriter = (level, line, ...rest)=>{
+    if (level === 'ERROR') return console.error(line, ...rest);
+    if (level === 'WARN') return console.warn(line, ...rest);
+    if (level === 'DEBUG' || level === 'VERBOSE') return console.debug(line, ...rest);
+    return console.log(line, ...rest);
+};
+function formatValue(v) {
+    if (typeof v === 'string') {
+        return /[\s="\\]/.test(v) ? JSON.stringify(v) : v;
+    }
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    try {
+        return JSON.stringify(v);
+    } catch  {
+        return String(v);
+    }
+}
 export class Logger {
     static level = 2;
     static globalLogger;
+    static globalContextProviders = [];
+    static globalWriter = defaultWriter;
     context;
+    instanceContextProviders = [];
+    instanceWriter;
     static setLogLevel(level) {
         Logger.level = level;
     }
     static overrideLogger(logger) {
         Logger.globalLogger = logger;
     }
+    /** Register a context provider run on every log line from every logger. */ static addContextProvider(provider) {
+        Logger.globalContextProviders.push(provider);
+    }
+    /** Remove all registered global context providers. */ static clearContextProviders() {
+        Logger.globalContextProviders = [];
+    }
+    /** Replace the default console writer. Useful on edge runtimes that have
+   *  a different output sink (e.g. `env.LOGS.writeDataPoint` on Workers). */ static setWriter(writer) {
+        Logger.globalWriter = writer;
+    }
+    /** Restore the default console-based writer. */ static resetWriter() {
+        Logger.globalWriter = defaultWriter;
+    }
     constructor(context){
         if (context) {
             this.context = context;
@@ -35,55 +69,86 @@ export class Logger {
     setContext(context) {
         this.context = context;
     }
+    /** Add a context provider that runs only for THIS logger instance.
+   *  Children created via extend() inherit these providers by copy. */ addContextProvider(provider) {
+        this.instanceContextProviders.push(provider);
+        return this;
+    }
+    /** Override the writer for this logger (and any extend() children). */ setWriter(writer) {
+        this.instanceWriter = writer;
+        return this;
+    }
+    /** Create a child logger with a nested namespace. Context becomes
+   *  `parent:child`; instance-level providers and writers are inherited
+   *  by copy so later mutations on either logger stay isolated. */ extend(namespace) {
+        const newContext = this.context ? `${this.context}:${namespace}` : namespace;
+        const child = new Logger(newContext);
+        child.instanceContextProviders = [
+            ...this.instanceContextProviders
+        ];
+        if (this.instanceWriter) child.instanceWriter = this.instanceWriter;
+        return child;
+    }
     log(message, ...optionalParams) {
-        if (Logger.level > 2) return;
-        if (Logger.globalLogger === false) return;
-        if (Logger.globalLogger) {
-            Logger.globalLogger.log(message, ...optionalParams);
-            return;
-        }
-        console.log(this.formatMessage('LOG', message), ...optionalParams);
+        this.emit('LOG', 2, message, optionalParams);
     }
     error(message, ...optionalParams) {
-        if (Logger.level > 4) return;
-        if (Logger.globalLogger === false) return;
-        if (Logger.globalLogger) {
-            Logger.globalLogger.error(message, ...optionalParams);
-            return;
-        }
-        console.error(this.formatMessage('ERROR', message), ...optionalParams);
+        this.emit('ERROR', 4, message, optionalParams);
     }
     warn(message, ...optionalParams) {
-        if (Logger.level > 3) return;
-        if (Logger.globalLogger === false) return;
-        if (Logger.globalLogger) {
-            Logger.globalLogger.warn(message, ...optionalParams);
-            return;
-        }
-        console.warn(this.formatMessage('WARN', message), ...optionalParams);
+        this.emit('WARN', 3, message, optionalParams);
     }
     debug(message, ...optionalParams) {
-        if (Logger.level > 1) return;
-        if (Logger.globalLogger === false) return;
-        if (Logger.globalLogger) {
-            Logger.globalLogger.debug?.(message, ...optionalParams);
-            return;
-        }
-        console.debug(this.formatMessage('DEBUG', message), ...optionalParams);
+        this.emit('DEBUG', 1, message, optionalParams);
     }
     verbose(message, ...optionalParams) {
-        if (Logger.level > 0) return;
+        this.emit('VERBOSE', 0, message, optionalParams);
+    }
+    emit(levelName, levelValue, message, rest) {
+        if (Logger.level > levelValue) return;
         if (Logger.globalLogger === false) return;
         if (Logger.globalLogger) {
-            Logger.globalLogger.verbose?.(message, ...optionalParams);
+            const method = levelName.toLowerCase();
+            const fn = Logger.globalLogger[method];
+            if (fn) fn.call(Logger.globalLogger, message, ...rest);
             return;
         }
-        console.debug(this.formatMessage('VERBOSE', message), ...optionalParams);
+        const line = this.formatMessage(levelName, message);
+        const writer = this.instanceWriter ?? Logger.globalWriter;
+        writer(levelName, line, ...rest);
     }
     formatMessage(level, message) {
         const timestamp = new Date().toISOString();
         const ctx = this.context ? ` [${this.context}]` : '';
-        return `[Vela] ${timestamp} ${level}${ctx} ${message}`;
+        const contextStr = this.formatContextObj(this.collectContext());
+        return `[Vela] ${timestamp} ${level}${ctx} ${message}${contextStr}`;
+    }
+    collectContext() {
+        const result = {};
+        for (const provider of Logger.globalContextProviders){
+            try {
+                Object.assign(result, provider());
+            } catch  {
+            // Provider threw; drop its contribution and keep going.
+            }
+        }
+        for (const provider of this.instanceContextProviders){
+            try {
+                Object.assign(result, provider());
+            } catch  {
+            // Same — never let a provider break logging.
+            }
+        }
+        return result;
+    }
+    formatContextObj(obj) {
+        const parts = [];
+        for (const key of Object.keys(obj)){
+            const value = obj[key];
+            if (value === undefined || value === null) continue;
+            parts.push(`${key}=${formatValue(value)}`);
+        }
+        return parts.length > 0 ? ` ${parts.join(' ')}` : '';
     }
 }
 Logger = _ts_decorate([

package/package.json

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