@velajs/vela 0.9.0 → 1.0.0

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/pipeline/component.manager.d.ts

@@ -8,6 +8,7 @@ export declare class ComponentManager {
     static registerController<T extends ComponentType>(type: T, controller: Constructor, ...components: ComponentTypeMap[T][]): void;
     static registerHandler<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol, ...components: ComponentTypeMap[T][]): void;
     static getComponents<T extends ComponentType>(type: T, controller: Constructor, handlerName: string | symbol): ComponentTypeMap[T][];
+    private static resolveAll;
     static resolveMiddleware(items: MiddlewareType[]): NestMiddleware[];
     static resolveGuards(items: GuardType[]): CanActivate[];
     static resolvePipes(items: PipeType[]): PipeTransform[];

package/dist/pipeline/component.manager.js

@@ -19,16 +19,14 @@ export class ComponentManager {
         }
     }
     static registerHandler(type, controller, handlerName, ...components) {
-        const handlerKey = `${controller.name}:${String(handlerName)}`;
         for (const component of components){
-            MetadataRegistry.registerHandler(type, handlerKey, component);
+            MetadataRegistry.registerHandler(type, controller, handlerName, component);
         }
     }
     // 3-level resolution: global → controller → handler
     static getComponents(type, controller, handlerName) {
-        const handlerKey = `${controller.name}:${String(handlerName)}`;
         const controllerComponents = MetadataRegistry.getController(type, controller);
-        const handlerComponents = MetadataRegistry.getHandler(type, handlerKey);
+        const handlerComponents = MetadataRegistry.getHandler(type, controller, handlerName);
         return [
             ...MetadataRegistry.getGlobal(type),
             ...controllerComponents,
@@ -36,45 +34,23 @@ export class ComponentManager {
         ];
     }
     // Type-specific resolvers
+    static resolveAll(items, methodKey) {
+        return items.map((item)=>isObject(item) && methodKey in item ? item : this.container.resolve(item));
+    }
     static resolveMiddleware(items) {
-        return items.map((item)=>{
-            if (isObject(item) && 'use' in item) {
-                return item;
-            }
-            return this.container.resolve(item);
-        });
+        return this.resolveAll(items, 'use');
     }
     static resolveGuards(items) {
-        return items.map((item)=>{
-            if (isObject(item) && 'canActivate' in item) {
-                return item;
-            }
-            return this.container.resolve(item);
-        });
+        return this.resolveAll(items, 'canActivate');
     }
     static resolvePipes(items) {
-        return items.map((item)=>{
-            if (isObject(item) && 'transform' in item) {
-                return item;
-            }
-            return this.container.resolve(item);
-        });
+        return this.resolveAll(items, 'transform');
     }
     static resolveInterceptors(items) {
-        return items.map((item)=>{
-            if (isObject(item) && 'intercept' in item) {
-                return item;
-            }
-            return this.container.resolve(item);
-        });
+        return this.resolveAll(items, 'intercept');
     }
     static resolveFilters(items) {
-        return items.map((item)=>{
-            if (isObject(item) && 'catch' in item) {
-                return item;
-            }
-            return this.container.resolve(item);
-        });
+        return this.resolveAll(items, 'catch');
     }
     // Pipe execution
     static async executePipes(value, metadata, pipes) {

package/dist/registry/metadata.registry.d.ts

@@ -36,8 +36,8 @@ export declare class MetadataRegistry {
     static getGlobal<T extends ComponentType>(type: T): Set<ComponentTypeMap[T]>;
     static registerController<T extends ComponentType>(type: T, controller: Constructor, component: ComponentTypeMap[T]): void;
     static getController<T extends ComponentType>(type: T, controller: Constructor): ComponentTypeMap[T][];
-    static registerHandler<T extends ComponentType>(type: T, handlerKey: string, component: ComponentTypeMap[T]): void;
-    static getHandler<T extends ComponentType>(type: T, handlerKey: string): ComponentTypeMap[T][];
+    static registerHandler<T extends ComponentType>(type: T, controller: Constructor, methodName: string | symbol, component: ComponentTypeMap[T]): void;
+    static getHandler<T extends ComponentType>(type: T, controller: Constructor, methodName: string | symbol): ComponentTypeMap[T][];
     static markInjectable(target: object): void;
     static hasInjectable(target: object): boolean;
     static setScope(target: object, scope: Scope): void;

package/dist/registry/metadata.registry.js

@@ -146,16 +146,23 @@ export class MetadataRegistry {
         const typeMap = this.controller.get(type);
         return typeMap.get(controller) || [];
     }
-    static registerHandler(type, handlerKey, component) {
+    static registerHandler(type, controller, methodName, component) {
         const typeMap = this.handler.get(type);
-        if (!typeMap.has(handlerKey)) {
-            typeMap.set(handlerKey, []);
+        let methodMap = typeMap.get(controller);
+        if (!methodMap) {
+            methodMap = new Map();
+            typeMap.set(controller, methodMap);
         }
-        typeMap.get(handlerKey).push(component);
+        let components = methodMap.get(methodName);
+        if (!components) {
+            components = [];
+            methodMap.set(methodName, components);
+        }
+        components.push(component);
     }
-    static getHandler(type, handlerKey) {
+    static getHandler(type, controller, methodName) {
         const typeMap = this.handler.get(type);
-        return typeMap.get(handlerKey) || [];
+        return typeMap.get(controller)?.get(methodName) ?? [];
     }
     // DI metadata
     static markInjectable(target) {

package/dist/schedule/cron-matcher.d.ts

@@ -0,0 +1,2 @@
+export type CronMatcher = (date: Date) => boolean;
+export declare function parseCron(expression: string): CronMatcher | null;

package/dist/schedule/cron-matcher.js

@@ -0,0 +1,62 @@
+export function parseCron(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) return null;
+    const [minuteField, hourField, dayField, monthField, weekdayField] = fields;
+    const minute = parseField(minuteField, 0, 59);
+    const hour = parseField(hourField, 0, 23);
+    const day = parseField(dayField, 1, 31);
+    const month = parseField(monthField, 1, 12);
+    const weekday = parseField(weekdayField, 0, 7);
+    if (!minute || !hour || !day || !month || !weekday) return null;
+    return (date)=>minute(date.getMinutes()) && hour(date.getHours()) && day(date.getDate()) && month(date.getMonth() + 1) && weekday(date.getDay());
+}
+function parseField(field, min, max) {
+    const segments = field.split(',');
+    const predicates = [];
+    for (const rawSegment of segments){
+        const segment = rawSegment.trim();
+        if (!segment) return null;
+        const stepParts = segment.split('/');
+        if (stepParts.length > 2) return null;
+        const step = stepParts.length === 2 ? Number(stepParts[1]) : 1;
+        if (!Number.isInteger(step) || step <= 0) return null;
+        const range = parseRange(stepParts[0], min, max);
+        if (!range) return null;
+        predicates.push((value)=>{
+            if (value < range.start || value > range.end) return false;
+            return (value - range.start) % step === 0;
+        });
+    }
+    return (value)=>predicates.some((p)=>p(value));
+}
+function parseRange(segment, min, max) {
+    if (segment === '*') return {
+        start: min,
+        end: max
+    };
+    const bounds = segment.split('-');
+    if (bounds.length === 1) {
+        const value = parseCronNumber(bounds[0], min, max);
+        if (value === null) return null;
+        return {
+            start: value,
+            end: value
+        };
+    }
+    if (bounds.length !== 2) return null;
+    const start = parseCronNumber(bounds[0], min, max);
+    const end = parseCronNumber(bounds[1], min, max);
+    if (start === null || end === null || start > end) return null;
+    return {
+        start,
+        end
+    };
+}
+function parseCronNumber(raw, min, max) {
+    const value = Number(raw);
+    if (!Number.isInteger(value)) return null;
+    // Cron allows 0 and 7 as Sunday.
+    const normalized = max === 7 && value === 7 ? 0 : value;
+    if (normalized < min || normalized > max) return null;
+    return normalized;
+}

package/dist/schedule/index.d.ts

@@ -1,7 +1,8 @@
 export { ScheduleModule } from './schedule.module';
 export { ScheduleRegistry } from './schedule.registry';
 export type { RegisteredCronJob, RegisteredIntervalJob } from './schedule.registry';
-export { ScheduleExecutor } from './schedule.executor';
 export { Cron, Interval } from './schedule.decorators';
-export { SCHEDULE_MODULE_OPTIONS, CRON_METADATA, INTERVAL_METADATA } from './schedule.tokens';
-export type { CronMetadata, IntervalMetadata, ScheduleModuleOptions } from './schedule.types';
+export { CRON_METADATA, INTERVAL_METADATA } from './schedule.tokens';
+export type { CronMetadata, IntervalMetadata } from './schedule.types';
+export { parseCron } from './cron-matcher';
+export type { CronMatcher } from './cron-matcher';

package/dist/schedule/index.js

@@ -1,5 +1,5 @@
 export { ScheduleModule } from "./schedule.module.js";
 export { ScheduleRegistry } from "./schedule.registry.js";
-export { ScheduleExecutor } from "./schedule.executor.js";
 export { Cron, Interval } from "./schedule.decorators.js";
-export { SCHEDULE_MODULE_OPTIONS, CRON_METADATA, INTERVAL_METADATA } from "./schedule.tokens.js";
+export { CRON_METADATA, INTERVAL_METADATA } from "./schedule.tokens.js";
+export { parseCron } from "./cron-matcher.js";

package/dist/schedule/schedule.module.d.ts

@@ -1,8 +1,4 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
-import type { ScheduleModuleOptions } from './schedule.types';
+import type { DynamicModule } from '../module/types';
 export declare class ScheduleModule {
-    static forRoot(options?: ScheduleModuleOptions): DynamicModule;
-    static forRootAsync(options: AsyncModuleOptions<ScheduleModuleOptions> & {
-        enableTimers?: boolean;
-    }): DynamicModule;
+    static forRoot(): DynamicModule;
 }

package/dist/schedule/schedule.module.js

@@ -1,53 +1,15 @@
-import { ScheduleExecutor } from "./schedule.executor.js";
 import { ScheduleRegistry } from "./schedule.registry.js";
-import { SCHEDULE_MODULE_OPTIONS } from "./schedule.tokens.js";
 export class ScheduleModule {
-    static forRoot(options = {}) {
-        const { enableTimers = false } = options;
+    static forRoot() {
         const providers = [
-            {
-                provide: SCHEDULE_MODULE_OPTIONS,
-                useValue: options
-            },
             ScheduleRegistry
         ];
-        const exports = [
-            SCHEDULE_MODULE_OPTIONS,
-            ScheduleRegistry
-        ];
-        if (enableTimers) {
-            providers.push(ScheduleExecutor);
-            exports.push(ScheduleExecutor);
-        }
-        return {
-            module: ScheduleModule,
-            providers,
-            exports
-        };
-    }
-    static forRootAsync(options) {
-        const { enableTimers = false } = options;
-        const providers = [
-            {
-                provide: SCHEDULE_MODULE_OPTIONS,
-                useFactory: options.useFactory,
-                inject: options.inject ?? []
-            },
-            ScheduleRegistry
-        ];
-        const exports = [
-            SCHEDULE_MODULE_OPTIONS,
-            ScheduleRegistry
-        ];
-        if (enableTimers) {
-            providers.push(ScheduleExecutor);
-            exports.push(ScheduleExecutor);
-        }
         return {
             module: ScheduleModule,
-            imports: options.imports ?? [],
             providers,
-            exports
+            exports: [
+                ScheduleRegistry
+            ]
         };
     }
 }

package/dist/schedule/schedule.tokens.d.ts

@@ -1,5 +1,2 @@
-import { InjectionToken } from '../container/types';
-import type { ScheduleModuleOptions } from './schedule.types';
-export declare const SCHEDULE_MODULE_OPTIONS: InjectionToken<ScheduleModuleOptions>;
 export declare const CRON_METADATA = "vela:cron";
 export declare const INTERVAL_METADATA = "vela:interval";

package/dist/schedule/schedule.tokens.js

@@ -1,4 +1,2 @@
-import { InjectionToken } from "../container/types.js";
-export const SCHEDULE_MODULE_OPTIONS = new InjectionToken('SCHEDULE_MODULE_OPTIONS');
 export const CRON_METADATA = 'vela:cron';
 export const INTERVAL_METADATA = 'vela:interval';

package/dist/schedule/schedule.types.d.ts

@@ -6,6 +6,3 @@ export interface IntervalMetadata {
     ms: number;
     methodName: string;
 }
-export interface ScheduleModuleOptions {
-    enableTimers?: boolean;
-}

package/dist/schedule-node/index.d.ts

@@ -0,0 +1,2 @@
+export { ScheduleNodeModule } from './schedule-node.module';
+export { ScheduleExecutor } from './schedule.executor';

package/dist/schedule-node/index.js

@@ -0,0 +1,2 @@
+export { ScheduleNodeModule } from "./schedule-node.module.js";
+export { ScheduleExecutor } from "./schedule.executor.js";

package/dist/schedule-node/schedule-node.module.d.ts

@@ -0,0 +1,4 @@
+import type { DynamicModule } from '../module/types';
+export declare class ScheduleNodeModule {
+    static forRoot(): DynamicModule;
+}

package/dist/schedule-node/schedule-node.module.js

@@ -0,0 +1,18 @@
+import { ScheduleRegistry } from "../schedule/schedule.registry.js";
+import { ScheduleExecutor } from "./schedule.executor.js";
+export class ScheduleNodeModule {
+    static forRoot() {
+        const providers = [
+            ScheduleRegistry,
+            ScheduleExecutor
+        ];
+        return {
+            module: ScheduleNodeModule,
+            providers,
+            exports: [
+                ScheduleRegistry,
+                ScheduleExecutor
+            ]
+        };
+    }
+}

package/dist/{schedule → schedule-node}/schedule.executor.d.ts

@@ -1,5 +1,5 @@
 import type { OnApplicationBootstrap, OnModuleDestroy } from '../lifecycle/index';
-import { ScheduleRegistry } from './schedule.registry';
+import { ScheduleRegistry } from '../schedule/schedule.registry';
 export declare class ScheduleExecutor implements OnApplicationBootstrap, OnModuleDestroy {
     private registry;
     private intervalTimers;
@@ -12,9 +12,6 @@ export declare class ScheduleExecutor implements OnApplicationBootstrap, OnModul
     private scheduleInterval;
     private scheduleCron;
     private invoke;
-    private getCronMatcher;
-    private parseField;
-    private parseRange;
-    private parseCronNumber;
+    private getMatcher;
     onModuleDestroy(): void;
 }

package/dist/schedule-node/schedule.executor.js

@@ -0,0 +1,91 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+import { Injectable } from "../container/index.js";
+import { parseCron } from "../schedule/cron-matcher.js";
+import { ScheduleRegistry } from "../schedule/schedule.registry.js";
+export class ScheduleExecutor {
+    registry;
+    intervalTimers = [];
+    cronTimers = [];
+    cronMatcherCache = new Map();
+    lastCronMinute = new Map();
+    running = true;
+    constructor(registry){
+        this.registry = registry;
+    }
+    onApplicationBootstrap() {
+        if (typeof setInterval !== 'function') {
+            throw new Error('@velajs/vela/schedule-node requires Node or Bun. Use a platform cron adapter on edge runtimes (e.g. CloudflareApplication.scheduled).');
+        }
+        for (const job of this.registry.getIntervalJobs()){
+            this.scheduleInterval(job.instance, job.methodName, job.ms);
+        }
+        const cronJobs = this.registry.getCronJobs();
+        for(let i = 0; i < cronJobs.length; i++){
+            const job = cronJobs[i];
+            this.scheduleCron(job.instance, job.methodName, job.expression, i);
+        }
+    }
+    scheduleInterval(instance, methodName, ms) {
+        if (!this.running) return;
+        const timer = setInterval(()=>{
+            void this.invoke(instance, methodName);
+        }, ms);
+        this.intervalTimers.push(timer);
+    }
+    scheduleCron(instance, methodName, expression, index) {
+        if (!this.running) return;
+        const matcher = this.getMatcher(expression);
+        if (!matcher) return;
+        const jobKey = `${index}:${methodName}:${expression}`;
+        const timer = setInterval(()=>{
+            const now = new Date();
+            const minuteKey = Math.floor(now.getTime() / 60_000);
+            if (this.lastCronMinute.get(jobKey) === minuteKey) return;
+            if (!matcher(now)) return;
+            this.lastCronMinute.set(jobKey, minuteKey);
+            void this.invoke(instance, methodName);
+        }, 1000);
+        this.cronTimers.push(timer);
+    }
+    async invoke(instance, methodName) {
+        try {
+            const method = instance[methodName];
+            if (typeof method === 'function') {
+                await method.call(instance);
+            }
+        } catch  {
+        // Swallow errors so the scheduler keeps running
+        }
+    }
+    getMatcher(expression) {
+        if (this.cronMatcherCache.has(expression)) {
+            return this.cronMatcherCache.get(expression) ?? null;
+        }
+        const matcher = parseCron(expression);
+        this.cronMatcherCache.set(expression, matcher);
+        return matcher;
+    }
+    onModuleDestroy() {
+        this.running = false;
+        for (const timer of this.intervalTimers)clearInterval(timer);
+        for (const timer of this.cronTimers)clearInterval(timer);
+        this.intervalTimers = [];
+        this.cronTimers = [];
+        this.lastCronMinute.clear();
+    }
+}
+ScheduleExecutor = _ts_decorate([
+    Injectable(),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ScheduleRegistry === "undefined" ? Object : ScheduleRegistry
+    ])
+], ScheduleExecutor);

package/dist/services/logger.d.ts

@@ -1,11 +1,12 @@
-export declare enum LogLevel {
-    VERBOSE = 0,
-    DEBUG = 1,
-    LOG = 2,
-    WARN = 3,
-    ERROR = 4,
-    SILENT = 5
-}
+export declare const LogLevel: {
+    readonly VERBOSE: 0;
+    readonly DEBUG: 1;
+    readonly LOG: 2;
+    readonly WARN: 3;
+    readonly ERROR: 4;
+    readonly SILENT: 5;
+};
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 export interface LoggerService {
     log(message: unknown, ...optionalParams: unknown[]): void;
     error(message: unknown, ...optionalParams: unknown[]): void;

package/dist/services/logger.js

@@ -8,15 +8,14 @@ function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 import { Injectable } from "../container/decorators.js";
-export var LogLevel = /*#__PURE__*/ function(LogLevel) {
-    LogLevel[LogLevel["VERBOSE"] = 0] = "VERBOSE";
-    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
-    LogLevel[LogLevel["LOG"] = 2] = "LOG";
-    LogLevel[LogLevel["WARN"] = 3] = "WARN";
-    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
-    LogLevel[LogLevel["SILENT"] = 5] = "SILENT";
-    return LogLevel;
-}({});
+export const LogLevel = {
+    VERBOSE: 0,
+    DEBUG: 1,
+    LOG: 2,
+    WARN: 3,
+    ERROR: 4,
+    SILENT: 5
+};
 const defaultWriter = (level, line, ...rest)=>{
     if (level === 'ERROR') return console.error(line, ...rest);
     if (level === 'WARN') return console.warn(line, ...rest);
@@ -35,7 +34,7 @@ function formatValue(v) {
     }
 }
 export class Logger {
-    static level = 2;
+    static level = LogLevel.LOG;
     static globalLogger;
     static globalContextProviders = [];
     static globalWriter = defaultWriter;
@@ -90,19 +89,19 @@ export class Logger {
         return child;
     }
     log(message, ...optionalParams) {
-        this.emit('LOG', 2, message, optionalParams);
+        this.emit('LOG', LogLevel.LOG, message, optionalParams);
     }
     error(message, ...optionalParams) {
-        this.emit('ERROR', 4, message, optionalParams);
+        this.emit('ERROR', LogLevel.ERROR, message, optionalParams);
     }
     warn(message, ...optionalParams) {
-        this.emit('WARN', 3, message, optionalParams);
+        this.emit('WARN', LogLevel.WARN, message, optionalParams);
     }
     debug(message, ...optionalParams) {
-        this.emit('DEBUG', 1, message, optionalParams);
+        this.emit('DEBUG', LogLevel.DEBUG, message, optionalParams);
     }
     verbose(message, ...optionalParams) {
-        this.emit('VERBOSE', 0, message, optionalParams);
+        this.emit('VERBOSE', LogLevel.VERBOSE, message, optionalParams);
     }
     emit(levelName, levelValue, message, rest) {
         if (Logger.level > levelValue) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,10 @@
     "./streaming": {
       "types": "./dist/streaming/index.d.ts",
       "import": "./dist/streaming/index.js"
+    },
+    "./schedule-node": {
+      "types": "./dist/schedule-node/index.d.ts",
+      "import": "./dist/schedule-node/index.js"
     }
   },
   "files": [