@carno.js/core 0.2.11 → 1.0.2

package/src/context/Context.ts

@@ -0,0 +1,128 @@
+/**
+ * Request Context for Turbo.
+ * 
+ * Lazy initialization for maximum performance:
+ * - Query parsed only when accessed
+ * - Body parsed only when needed
+ * - Minimal allocations in hot path
+ */
+
+const EMPTY_PARAMS: Record<string, string> = Object.freeze({}) as Record<string, string>;
+
+export class Context {
+    readonly req: Request;
+    params: Record<string, string>;
+    locals: Record<string, any> = {};
+
+    // Lazy fields - only allocated when accessed
+    private _query: Record<string, string> | null = null;
+    private _body: any;
+    private _bodyParsed = false;
+    private _url: URL | null = null;
+    private _status = 0;
+
+    constructor(req: Request, params: Record<string, string> = EMPTY_PARAMS) {
+        this.req = req;
+        this.params = params;
+    }
+
+    get status(): number {
+        return this._status || 200;
+    }
+
+    set status(value: number) {
+        this._status = value;
+    }
+
+    get url(): URL {
+        if (!this._url) {
+            this._url = new URL(this.req.url);
+        }
+
+        return this._url;
+    }
+
+    get query(): Record<string, string> {
+        if (!this._query) {
+            this._query = Object.fromEntries(this.url.searchParams);
+        }
+
+        return this._query;
+    }
+
+    get body(): any {
+        return this._body;
+    }
+
+    async parseBody(): Promise<any> {
+        if (this._bodyParsed) {
+            return this._body;
+        }
+
+        this._bodyParsed = true;
+        const contentType = this.req.headers.get('content-type') || '';
+
+        if (contentType.includes('application/json')) {
+            this._body = await this.req.json();
+        } else if (contentType.includes('form')) {
+            const formData = await this.req.formData();
+            this._body = Object.fromEntries(formData);
+        } else if (contentType.includes('text')) {
+            this._body = await this.req.text();
+        } else {
+            this._body = await this.req.arrayBuffer();
+        }
+
+        return this._body;
+    }
+
+    get method(): string {
+        return this.req.method;
+    }
+
+    get headers(): Headers {
+        return this.req.headers;
+    }
+
+    get path(): string {
+        return this.url.pathname;
+    }
+
+    json(data: any, status?: number): Response {
+        if (status) this.status = status;
+
+        return Response.json(data, { status: this.status });
+    }
+
+    text(data: string, status?: number): Response {
+        if (status) this.status = status;
+
+        return new Response(data, {
+            status: this.status,
+            headers: { 'Content-Type': 'text/plain' }
+        });
+    }
+
+    html(data: string, status?: number): Response {
+        if (status) this.status = status;
+
+        return new Response(data, {
+            status: this.status,
+            headers: { 'Content-Type': 'text/html' }
+        });
+    }
+
+    redirect(url: string, status: number = 302): Response {
+        return Response.redirect(url, status);
+    }
+
+    /**
+     * Creates a Context from a job (for queue processing).
+     */
+    static createFromJob(job: any): Context {
+        const fakeRequest = new Request('http://localhost/job');
+        const ctx = new Context(fakeRequest);
+        ctx.locals.job = job;
+        return ctx;
+    }
+}

package/src/cors/CorsHandler.ts

@@ -0,0 +1,145 @@
+/**
+ * CORS Configuration types.
+ */
+export type CorsOrigin =
+    | string
+    | string[]
+    | RegExp
+    | ((origin: string) => boolean);
+
+export interface CorsConfig {
+    origins: CorsOrigin;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+
+export const DEFAULT_CORS_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'];
+export const DEFAULT_CORS_HEADERS = ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'Origin'];
+
+type OriginMatcher = (origin: string) => boolean;
+
+/**
+ * CORS Handler - Pre-computes headers at startup for maximum performance.
+ */
+export class CorsHandler {
+    private readonly cache = new Map<string, Record<string, string>>();
+    private readonly methodsStr: string;
+    private readonly headersStr: string;
+    private readonly exposedStr: string | null;
+    private readonly maxAgeStr: string | null;
+    private readonly hasCredentials: boolean;
+    private readonly isWildcard: boolean;
+    private readonly matcher: OriginMatcher;
+
+    // Pre-created preflight response for wildcard CORS
+    private readonly preflightResponse: Response | null = null;
+
+    constructor(config: CorsConfig) {
+        this.methodsStr = (config.methods || DEFAULT_CORS_METHODS).join(', ');
+        this.headersStr = (config.allowedHeaders || DEFAULT_CORS_HEADERS).join(', ');
+        this.exposedStr = config.exposedHeaders?.join(', ') || null;
+        this.maxAgeStr = config.maxAge?.toString() || null;
+        this.hasCredentials = !!config.credentials;
+        this.isWildcard = config.origins === '*';
+        this.matcher = this.buildMatcher(config.origins);
+
+        // Pre-create preflight response for wildcard
+        if (this.isWildcard) {
+            this.preflightResponse = new Response(null, {
+                status: 204,
+                headers: this.buildHeaders('*')
+            });
+        }
+    }
+
+    /**
+     * Handle preflight (OPTIONS) request.
+     */
+    preflight(origin: string): Response {
+        if (this.isWildcard && this.preflightResponse) {
+            return this.preflightResponse.clone();
+        }
+
+        if (!this.isAllowed(origin)) {
+            return new Response(null, { status: 403 });
+        }
+
+        return new Response(null, {
+            status: 204,
+            headers: this.getHeaders(origin)
+        });
+    }
+
+    /**
+     * Apply CORS headers to a response.
+     */
+    apply(response: Response, origin: string): Response {
+        if (!this.isAllowed(origin)) {
+            return response;
+        }
+
+        const headers = this.getHeaders(origin);
+        for (const [key, value] of Object.entries(headers)) {
+            response.headers.set(key, value);
+        }
+
+        return response;
+    }
+
+    /**
+     * Check if origin is allowed.
+     */
+    isAllowed(origin: string): boolean {
+        return this.matcher(origin);
+    }
+
+    /**
+     * Get cached CORS headers for origin.
+     */
+    private getHeaders(origin: string): Record<string, string> {
+        const key = this.isWildcard ? '*' : origin;
+        let headers = this.cache.get(key);
+
+        if (!headers) {
+            headers = this.buildHeaders(origin);
+            this.cache.set(key, headers);
+        }
+
+        return headers;
+    }
+
+    private buildHeaders(origin: string): Record<string, string> {
+        const headers: Record<string, string> = {
+            'Access-Control-Allow-Origin': this.isWildcard ? '*' : origin,
+            'Access-Control-Allow-Methods': this.methodsStr,
+            'Access-Control-Allow-Headers': this.headersStr
+        };
+
+        if (this.hasCredentials) {
+            headers['Access-Control-Allow-Credentials'] = 'true';
+        }
+        if (this.exposedStr) {
+            headers['Access-Control-Expose-Headers'] = this.exposedStr;
+        }
+        if (this.maxAgeStr) {
+            headers['Access-Control-Max-Age'] = this.maxAgeStr;
+        }
+
+        return headers;
+    }
+
+    private buildMatcher(origins: CorsOrigin): OriginMatcher {
+        if (origins === '*') return () => true;
+        if (typeof origins === 'string') return (o) => o === origins;
+        if (Array.isArray(origins)) {
+            const set = new Set(origins);
+            return (o) => set.has(o);
+        }
+        if (origins instanceof RegExp) return (o) => origins.test(o);
+        if (typeof origins === 'function') return origins;
+        return () => false;
+    }
+}

package/src/decorators/Controller.ts

@@ -0,0 +1,63 @@
+import { CONTROLLER_META, ROUTES_META } from '../metadata';
+import type { ControllerOptions, ControllerMeta } from '../metadata';
+
+/**
+ * Normalizes path or options to ControllerOptions.
+ */
+function normalizeOptions(pathOrOptions?: string | ControllerOptions): ControllerOptions {
+    if (!pathOrOptions) {
+        return {};
+    }
+
+    if (typeof pathOrOptions === 'string') {
+        return { path: pathOrOptions };
+    }
+
+    return pathOrOptions;
+}
+
+/**
+ * Normalizes a path to start with / and not end with /.
+ */
+function normalizePath(path: string): string {
+    if (!path) return '';
+
+    let normalized = path.startsWith('/') ? path : '/' + path;
+
+    if (normalized !== '/' && normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+
+    return normalized;
+}
+
+/**
+ * Marks a class as a controller with a base path.
+ *
+ * @example
+ * // Simple path
+ * @Controller('/users')
+ *
+ * @example
+ * // With options
+ * @Controller({ path: '/users', children: [ProfileController] })
+ */
+export function Controller(pathOrOptions?: string | ControllerOptions): ClassDecorator {
+    return (target) => {
+        const options = normalizeOptions(pathOrOptions);
+        const path = normalizePath(options.path || '');
+
+        const meta: ControllerMeta = {
+            path,
+            scope: options.scope,
+            children: options.children
+        };
+
+        Reflect.defineMetadata(CONTROLLER_META, meta, target);
+
+        // Ensure routes array exists
+        if (!Reflect.hasMetadata(ROUTES_META, target)) {
+            Reflect.defineMetadata(ROUTES_META, [], target);
+        }
+    };
+}

package/src/decorators/Inject.ts

@@ -0,0 +1,16 @@
+import { INJECT_META } from '../metadata';
+import type { Token } from '../container/Container';
+
+/**
+ * Explicitly specifies which token to inject.
+ * Useful for interfaces or when automatic detection fails.
+ */
+export function Inject(token: Token): ParameterDecorator {
+    return (target, propertyKey, parameterIndex) => {
+        const existing: Map<number, Token> = Reflect.getMetadata(INJECT_META, target) || new Map();
+
+        existing.set(parameterIndex, token);
+
+        Reflect.defineMetadata(INJECT_META, existing, target);
+    };
+}

package/src/decorators/Middleware.ts

@@ -0,0 +1,22 @@
+import { MIDDLEWARE_META, type MiddlewareInfo } from '../metadata';
+
+/**
+ * Middleware decorator.
+ * Can be applied to controllers or individual methods.
+ */
+export function Use(...middlewares: Function[]): ClassDecorator & MethodDecorator {
+    return function (target: any, propertyKey?: string) {
+        const isMethod = propertyKey !== undefined;
+        const metaTarget = isMethod ? target.constructor : target;
+        const existing: MiddlewareInfo[] = Reflect.getMetadata(MIDDLEWARE_META, metaTarget) || [];
+
+        for (const handler of middlewares) {
+            existing.push({
+                handler,
+                target: isMethod ? propertyKey : undefined
+            });
+        }
+
+        Reflect.defineMetadata(MIDDLEWARE_META, existing, metaTarget);
+    } as ClassDecorator & MethodDecorator;
+}

package/src/decorators/Service.ts

@@ -0,0 +1,18 @@
+import { SERVICE_META } from '../metadata';
+import { Scope } from '../container/Container';
+
+export interface ServiceOptions {
+    scope?: Scope;
+}
+
+/**
+ * Marks a class as an injectable service.
+ * Services are singleton by default.
+ */
+export function Service(options: ServiceOptions = {}): ClassDecorator {
+    return (target) => {
+        Reflect.defineMetadata(SERVICE_META, {
+            scope: options.scope ?? Scope.SINGLETON
+        }, target);
+    };
+}

package/src/decorators/methods.ts

@@ -0,0 +1,58 @@
+import { ROUTES_META, type RouteInfo } from '../metadata';
+
+type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
+
+/**
+ * Creates a method decorator for HTTP methods.
+ * Supports both legacy decorators (experimentalDecorators) and TS5 stage 3 decorators.
+ */
+function createMethodDecorator(method: HttpMethod) {
+    return function (path: string = ''): any {
+        return function (
+            targetOrMethod: any,
+            contextOrPropertyKey?: string | symbol | ClassMethodDecoratorContext,
+            descriptor?: PropertyDescriptor
+        ): any {
+            // TS5 Stage 3 decorators: context is ClassMethodDecoratorContext
+            if (contextOrPropertyKey && typeof contextOrPropertyKey === 'object' && 'kind' in contextOrPropertyKey) {
+                const context = contextOrPropertyKey as ClassMethodDecoratorContext;
+
+                context.addInitializer(function (this: any) {
+                    const constructor = this.constructor;
+                    const routes: RouteInfo[] = Reflect.getMetadata(ROUTES_META, constructor) || [];
+
+                    routes.push({
+                        method,
+                        path: path.startsWith('/') ? path : '/' + path,
+                        handlerName: String(context.name)
+                    });
+
+                    Reflect.defineMetadata(ROUTES_META, routes, constructor);
+                });
+
+                return targetOrMethod;
+            }
+
+            // Legacy decorators (experimentalDecorators: true)
+            const constructor = targetOrMethod.constructor;
+            const propertyKey = contextOrPropertyKey as string | symbol;
+            const routes: RouteInfo[] = Reflect.getMetadata(ROUTES_META, constructor) || [];
+
+            routes.push({
+                method,
+                path: path.startsWith('/') ? path : '/' + path,
+                handlerName: String(propertyKey)
+            });
+
+            Reflect.defineMetadata(ROUTES_META, routes, constructor);
+        };
+    };
+}
+
+export const Get = createMethodDecorator('get');
+export const Post = createMethodDecorator('post');
+export const Put = createMethodDecorator('put');
+export const Delete = createMethodDecorator('delete');
+export const Patch = createMethodDecorator('patch');
+export const Head = createMethodDecorator('head');
+export const Options = createMethodDecorator('options');

package/src/decorators/params.ts

@@ -0,0 +1,47 @@
+import { PARAMS_META } from '../metadata';
+
+export type ParamType = 'param' | 'query' | 'body' | 'header' | 'req' | 'ctx' | 'locals';
+
+export interface ParamMetadata {
+    type: ParamType;
+    key?: string;
+    index: number;
+}
+
+function createParamDecorator(type: ParamType, key?: string) {
+    return function (target: any, propertyKey: string, index: number) {
+        const params: ParamMetadata[] = Reflect.getMetadata(PARAMS_META, target.constructor, propertyKey) || [];
+
+        params.push({ type, key, index });
+
+        Reflect.defineMetadata(PARAMS_META, params, target.constructor, propertyKey);
+    };
+}
+
+export function Param(key?: string): ParameterDecorator {
+    return createParamDecorator('param', key) as ParameterDecorator;
+}
+
+export function Query(key?: string): ParameterDecorator {
+    return createParamDecorator('query', key) as ParameterDecorator;
+}
+
+export function Body(key?: string): ParameterDecorator {
+    return createParamDecorator('body', key) as ParameterDecorator;
+}
+
+export function Header(key?: string): ParameterDecorator {
+    return createParamDecorator('header', key) as ParameterDecorator;
+}
+
+export function Req(): ParameterDecorator {
+    return createParamDecorator('req') as ParameterDecorator;
+}
+
+export function Ctx(): ParameterDecorator {
+    return createParamDecorator('ctx') as ParameterDecorator;
+}
+
+export function Locals(key?: string): ParameterDecorator {
+    return createParamDecorator('locals', key) as ParameterDecorator;
+}

package/src/events/Lifecycle.ts

@@ -0,0 +1,97 @@
+/**
+ * Lifecycle Event Types.
+ */
+export enum EventType {
+    /** Called when DI container initializes, before server starts */
+    INIT = 'onInit',
+    /** Called right after application is fully bootstrapped */
+    BOOT = 'onBoot',
+    /** Called when application receives SIGTERM/SIGINT */
+    SHUTDOWN = 'onShutdown'
+}
+
+/**
+ * Stored event handler info.
+ */
+export interface EventHandler {
+    target: any;
+    methodName: string;
+    priority: number;
+}
+
+/**
+ * Metadata key for storing events.
+ */
+export const EVENTS_META = Symbol('turbo:events');
+
+/**
+ * Event registry - stores all decorated event handlers.
+ * Populated at decoration time, read at bootstrap.
+ */
+const eventRegistry = new Map<EventType, EventHandler[]>();
+
+/**
+ * Register an event handler (called by decorators).
+ */
+export function registerEvent(type: EventType, target: any, methodName: string, priority: number = 0): void {
+    let handlers = eventRegistry.get(type);
+    if (!handlers) {
+        handlers = [];
+        eventRegistry.set(type, handlers);
+    }
+    handlers.push({ target, methodName, priority });
+}
+
+/**
+ * Get all handlers for an event type, sorted by priority (descending).
+ */
+export function getEventHandlers(type: EventType): EventHandler[] {
+    const handlers = eventRegistry.get(type) || [];
+    return handlers.sort((a, b) => b.priority - a.priority);
+}
+
+/**
+ * Check if any handlers exist for an event type.
+ */
+export function hasEventHandlers(type: EventType): boolean {
+    return (eventRegistry.get(type)?.length ?? 0) > 0;
+}
+
+/**
+ * Clear all event handlers (for testing).
+ */
+export function clearEventRegistry(): void {
+    eventRegistry.clear();
+}
+
+// ============ Decorators ============
+
+/**
+ * Called when DI container initializes, before the server starts.
+ * Use for database connections, cache warming, etc.
+ */
+export function OnApplicationInit(priority: number = 0) {
+    return function (target: any, propertyKey: string) {
+        registerEvent(EventType.INIT, target.constructor, propertyKey, priority);
+    };
+}
+
+/**
+ * Called right after the application is fully bootstrapped and server is ready.
+ * Use for logging, health checks, etc.
+ */
+export function OnApplicationBoot(priority: number = 0) {
+    return function (target: any, propertyKey: string) {
+        registerEvent(EventType.BOOT, target.constructor, propertyKey, priority);
+    };
+}
+
+/**
+ * Called when application receives SIGTERM or SIGINT.
+ * Use for graceful cleanup, closing connections, etc.
+ */
+export function OnApplicationShutdown(priority: number = 0) {
+    return function (target: any, propertyKey: string) {
+        registerEvent(EventType.SHUTDOWN, target.constructor, propertyKey, priority);
+    };
+}

package/src/exceptions/HttpException.ts

@@ -0,0 +1,99 @@
+/**
+ * Base HTTP Exception class.
+ * Throw this from handlers to return custom HTTP error responses.
+ */
+export class HttpException extends Error {
+    constructor(
+        public readonly statusCode: number,
+        message: string,
+        public readonly errors?: any[]
+    ) {
+        super(message);
+        this.name = 'HttpException';
+    }
+
+    /**
+     * Convert exception to Response.
+     */
+    toResponse(): Response {
+        const body = {
+            statusCode: this.statusCode,
+            message: this.message,
+            ...(this.errors && { errors: this.errors })
+        };
+
+        return Response.json(body, { status: this.statusCode });
+    }
+}
+
+// Common HTTP Exceptions
+
+export class BadRequestException extends HttpException {
+    constructor(message: string = 'Bad Request', errors?: any[]) {
+        super(400, message, errors);
+        this.name = 'BadRequestException';
+    }
+}
+
+export class UnauthorizedException extends HttpException {
+    constructor(message: string = 'Unauthorized') {
+        super(401, message);
+        this.name = 'UnauthorizedException';
+    }
+}
+
+export class ForbiddenException extends HttpException {
+    constructor(message: string = 'Forbidden') {
+        super(403, message);
+        this.name = 'ForbiddenException';
+    }
+}
+
+export class NotFoundException extends HttpException {
+    constructor(message: string = 'Not Found') {
+        super(404, message);
+        this.name = 'NotFoundException';
+    }
+}
+
+export class MethodNotAllowedException extends HttpException {
+    constructor(message: string = 'Method Not Allowed') {
+        super(405, message);
+        this.name = 'MethodNotAllowedException';
+    }
+}
+
+export class ConflictException extends HttpException {
+    constructor(message: string = 'Conflict') {
+        super(409, message);
+        this.name = 'ConflictException';
+    }
+}
+
+export class UnprocessableEntityException extends HttpException {
+    constructor(message: string = 'Unprocessable Entity', errors?: any[]) {
+        super(422, message, errors);
+        this.name = 'UnprocessableEntityException';
+    }
+}
+
+export class TooManyRequestsException extends HttpException {
+    constructor(message: string = 'Too Many Requests') {
+        super(429, message);
+        this.name = 'TooManyRequestsException';
+    }
+}
+
+export class InternalServerErrorException extends HttpException {
+    constructor(message: string = 'Internal Server Error') {
+        super(500, message);
+        this.name = 'InternalServerErrorException';
+    }
+}
+
+export class ServiceUnavailableException extends HttpException {
+    constructor(message: string = 'Service Unavailable') {
+        super(503, message);
+        this.name = 'ServiceUnavailableException';
+    }
+}