@carno.js/core 0.2.11 → 1.0.2

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Carno - Ultra-Fast HTTP Framework
+ * 
+ * Design principles:
+ * 1. ZERO abstraction at runtime - everything compiled at startup
+ * 2. Direct Bun.serve() with native routes
+ * 3. JIT compiled handlers with AOT async detection
+ * 4. No intermediate layers in hot path
+ * 5. Radix tree router for dynamic routes
+ */
+
+// Application
+export { Carno } from './Carno';
+export type { MiddlewareHandler, CarnoConfig } from './Carno';
+
+// Context
+export { Context } from './context/Context';
+
+// Decorators - Controller
+export { Controller } from './decorators/Controller';
+export type { ControllerOptions } from './metadata';
+
+// Decorators - HTTP Methods
+export { Get, Post, Put, Delete, Patch, Head, Options } from './decorators/methods';
+
+// Decorators - Parameters
+export { Param, Query, Body, Header, Req, Ctx, Locals } from './decorators/params';
+
+// Decorators - Middleware
+export { Use, Use as Middleware } from './decorators/Middleware';
+
+// Middleware Interface
+export type { CarnoMiddleware, CarnoClosure } from './middleware/CarnoMiddleware';
+
+// Decorators - DI
+export { Service } from './decorators/Service';
+export { Inject } from './decorators/Inject';
+
+// Container
+export { Container, Scope } from './container/Container';
+export type { Token, ProviderConfig } from './container/Container';
+
+// Router
+export { RadixRouter } from './router/RadixRouter';
+export type { RouteMatch } from './router/RadixRouter';
+
+// CORS
+export { CorsHandler } from './cors/CorsHandler';
+export type { CorsConfig, CorsOrigin } from './cors/CorsHandler';
+
+// Validation
+export type { ValidatorAdapter, ValidationResult, ValidationError, ValidationConfig } from './validation/ValidatorAdapter';
+export { Schema, getSchema, VALIDATION_SCHEMA } from './validation/ValidatorAdapter';
+export { ZodAdapter, ValidationException } from './validation/ZodAdapter';
+export { ValibotAdapter } from './validation/ValibotAdapter';
+
+// Exceptions
+export {
+    HttpException,
+    BadRequestException,
+    UnauthorizedException,
+    ForbiddenException,
+    NotFoundException,
+    MethodNotAllowedException,
+    ConflictException,
+    UnprocessableEntityException,
+    TooManyRequestsException,
+    InternalServerErrorException,
+    ServiceUnavailableException
+} from './exceptions/HttpException';
+
+// Lifecycle Events
+export {
+    EventType,
+    OnApplicationInit,
+    OnApplicationBoot,
+    OnApplicationShutdown
+} from './events/Lifecycle';
+
+// Cache
+export { CacheService } from './cache/CacheService';
+export { MemoryDriver } from './cache/MemoryDriver';
+export { RedisDriver } from './cache/RedisDriver';
+export type { RedisConfig } from './cache/RedisDriver';
+export type { CacheDriver, CacheConfig } from './cache/CacheDriver';
+
+// Testing
+export { createTestHarness, withTestApp } from './testing/TestHarness';
+export type { TestHarness, TestOptions } from './testing/TestHarness';
+
+// Utils
+export { Metadata, isObject, isString } from './utils/Metadata';

package/src/metadata.ts

@@ -0,0 +1,46 @@
+import { Scope } from './container/Container';
+
+/**
+ * Controller options for the @Controller decorator.
+ */
+export interface ControllerOptions {
+    path?: string;
+    scope?: Scope;
+    children?: any[];
+}
+
+/**
+ * Controller metadata stored on controller classes.
+ */
+export interface ControllerMeta {
+    path: string;
+    scope?: Scope;
+    children?: any[];
+}
+
+/**
+ * Route metadata stored on controllers.
+ */
+export interface RouteInfo {
+    method: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head' | 'options';
+    path: string;
+    handlerName: string;
+}
+
+/**
+ * Middleware metadata.
+ */
+export interface MiddlewareInfo {
+    handler: Function;
+    target?: string;
+}
+
+/**
+ * Metadata keys.
+ */
+export const CONTROLLER_META = Symbol('turbo:controller');
+export const ROUTES_META = Symbol('turbo:routes');
+export const PARAMS_META = Symbol('turbo:params');
+export const MIDDLEWARE_META = Symbol('turbo:middleware');
+export const SERVICE_META = Symbol('turbo:service');
+export const INJECT_META = Symbol('turbo:inject');

package/src/middleware/CarnoMiddleware.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../context/Context';
+
+/**
+ * Closure function to call the next middleware in the chain.
+ */
+export type CarnoClosure = () => void | Promise<void>;
+
+/**
+ * Interface for onion-style middleware.
+ * Middleware must call next() to continue the chain.
+ */
+export interface CarnoMiddleware {
+  handle(ctx: Context, next: CarnoClosure): void | Promise<void>;
+}

package/src/router/RadixRouter.ts

@@ -0,0 +1,225 @@
+/**
+ * Ultra-fast Radix Router for Turbo.
+ * 
+ * Optimizations:
+ * - Char code comparisons (no string allocations)
+ * - Frozen empty params object
+ * - O(1) method lookup via char code index
+ * - Minimal allocations in hot path
+ */
+
+const EMPTY_PARAMS: Readonly<Record<string, string>> = Object.freeze({});
+
+interface Node<T> {
+    part: string;
+    store: T | null;
+    children: Map<number, Node<T>> | null;
+    paramChild: ParamNode<T> | null;
+    wildcardStore: T | null;
+}
+
+interface ParamNode<T> {
+    name: string;
+    store: T | null;
+    child: Node<T> | null;
+}
+
+export interface RouteMatch<T> {
+    store: T;
+    params: Record<string, string>;
+}
+
+function createNode<T>(part: string): Node<T> {
+    return {
+        part,
+        store: null,
+        children: null,
+        paramChild: null,
+        wildcardStore: null
+    };
+}
+
+export class RadixRouter<T> {
+    private roots: Record<string, Node<T>> = {};
+
+    add(method: string, path: string, store: T): void {
+        if (path === '') path = '/';
+        if (path[0] !== '/') path = '/' + path;
+
+        const isWildcard = path.endsWith('*');
+
+        if (isWildcard) path = path.slice(0, -1);
+
+        let node = this.roots[method];
+
+        if (!node) {
+            node = this.roots[method] = createNode('/');
+        }
+
+        let i = 0;
+        const len = path.length;
+
+        while (i < len) {
+            const char = path.charCodeAt(i);
+
+            if (char === 58) {
+                const paramStart = i + 1;
+                let paramEnd = paramStart;
+
+                while (paramEnd < len && path.charCodeAt(paramEnd) !== 47) {
+                    paramEnd++;
+                }
+
+                const paramName = path.slice(paramStart, paramEnd);
+
+                if (!node.paramChild) {
+                    node.paramChild = { name: paramName, store: null, child: null };
+                }
+
+                if (paramEnd >= len) {
+                    node.paramChild.store = store;
+                    return;
+                }
+
+                if (!node.paramChild.child) {
+                    node.paramChild.child = createNode(path.slice(paramEnd));
+                }
+
+                node = node.paramChild.child;
+                i = paramEnd;
+                continue;
+            }
+
+            let segmentEnd = i;
+
+            while (segmentEnd < len && path.charCodeAt(segmentEnd) !== 47 && path.charCodeAt(segmentEnd) !== 58) {
+                segmentEnd++;
+            }
+
+            if (segmentEnd < len && path.charCodeAt(segmentEnd) === 47) {
+                segmentEnd++;
+            }
+
+            const segment = path.slice(i, segmentEnd);
+
+            if (segment === node.part) {
+                i = segmentEnd;
+                continue;
+            }
+
+            if (!node.children) {
+                node.children = new Map();
+            }
+
+            const firstChar = segment.charCodeAt(0);
+            let child = node.children.get(firstChar);
+
+            if (!child) {
+                child = createNode(segment);
+                node.children.set(firstChar, child);
+            }
+
+            node = child;
+            i = segmentEnd;
+        }
+
+        if (isWildcard) {
+            node.wildcardStore = store;
+        } else {
+            node.store = store;
+        }
+    }
+
+    find(method: string, path: string): RouteMatch<T> | null {
+        const root = this.roots[method];
+
+        if (!root) return null;
+
+        return this.matchPath(root, path, 0, path.length);
+    }
+
+    private matchPath(
+        node: Node<T>,
+        path: string,
+        start: number,
+        len: number
+    ): RouteMatch<T> | null {
+        const partLen = node.part.length;
+        const end = start + partLen;
+
+        if (partLen > 1) {
+            if (end > len) return null;
+
+            for (let i = 1, j = start + 1; i < partLen; i++, j++) {
+                if (node.part.charCodeAt(i) !== path.charCodeAt(j)) {
+                    return null;
+                }
+            }
+        }
+
+        if (end === len) {
+            if (node.store !== null) {
+                return { store: node.store, params: EMPTY_PARAMS };
+            }
+
+            if (node.wildcardStore !== null) {
+                return { store: node.wildcardStore, params: { '*': '' } };
+            }
+
+            return null;
+        }
+
+        if (node.children) {
+            const child = node.children.get(path.charCodeAt(end));
+
+            if (child) {
+                const result = this.matchPath(child, path, end, len);
+
+                if (result) return result;
+            }
+        }
+
+        if (node.paramChild) {
+            const param = node.paramChild;
+            let paramEnd = end;
+
+            while (paramEnd < len && path.charCodeAt(paramEnd) !== 47) {
+                paramEnd++;
+            }
+
+            if (paramEnd === end) return null;
+
+            const paramValue = path.slice(end, paramEnd);
+
+            if (paramEnd >= len) {
+                if (param.store !== null) {
+                    return {
+                        store: param.store,
+                        params: { [param.name]: paramValue }
+                    };
+                }
+            } else if (param.child) {
+                const result = this.matchPath(param.child, path, paramEnd, len);
+
+                if (result) {
+                    if (result.params === EMPTY_PARAMS) {
+                        result.params = { [param.name]: paramValue };
+                    } else {
+                        result.params[param.name] = paramValue;
+                    }
+
+                    return result;
+                }
+            }
+        }
+
+        if (node.wildcardStore !== null) {
+            return {
+                store: node.wildcardStore,
+                params: { '*': path.slice(end) }
+            };
+        }
+
+        return null;
+    }
+}

package/src/testing/TestHarness.ts

@@ -0,0 +1,177 @@
+import type { Server } from 'bun';
+import { Carno, type CarnoConfig } from '../Carno';
+import { Container, type Token } from '../container/Container';
+
+/**
+ * Test configuration options.
+ */
+export interface TestOptions {
+    config?: CarnoConfig;
+    listen?: boolean | number;
+    port?: number;
+    controllers?: (new (...args: any[]) => any)[];
+    services?: (Token | any)[];
+}
+
+/**
+ * Test harness - provides utilities for testing Carno applications.
+ */
+export interface TestHarness {
+    /** The Carno app instance */
+    app: Carno;
+
+    /** The internal DI container */
+    container: Container;
+
+    /** The HTTP server (if listening) */
+    server?: Server<any>;
+
+    /** The port the server is running on */
+    port?: number;
+
+    /** Resolve a service from the container */
+    resolve<T>(token: Token<T>): T;
+
+    /** Make an HTTP request to the app */
+    request(path: string, init?: RequestInit): Promise<Response>;
+
+    /** Make a GET request */
+    get(path: string, init?: Omit<RequestInit, 'method'>): Promise<Response>;
+
+    /** Make a POST request */
+    post(path: string, body?: any, init?: Omit<RequestInit, 'method' | 'body'>): Promise<Response>;
+
+    /** Make a PUT request */
+    put(path: string, body?: any, init?: Omit<RequestInit, 'method' | 'body'>): Promise<Response>;
+
+    /** Make a DELETE request */
+    delete(path: string, init?: Omit<RequestInit, 'method'>): Promise<Response>;
+
+    /** Close the test harness and cleanup */
+    close(): Promise<void>;
+}
+
+/**
+ * Create a test harness for Turbo applications.
+ * 
+ * @example
+ * ```typescript
+ * const harness = await createTestHarness({
+ *   controllers: [UserController],
+ *   services: [UserService],
+ *   listen: true
+ * });
+ * 
+ * const response = await harness.get('/users');
+ * expect(response.status).toBe(200);
+ * 
+ * await harness.close();
+ * ```
+ */
+export async function createTestHarness(options: TestOptions = {}): Promise<TestHarness> {
+    const config: CarnoConfig = {
+        ...options.config,
+        disableStartupLog: true
+    };
+
+    const app = new Carno(config);
+
+    // Register controllers
+    if (options.controllers) {
+        app.controllers(options.controllers);
+    }
+
+    // Register services
+    if (options.services) {
+        app.services(options.services);
+    }
+
+    const port = resolvePort(options);
+    let server: Server<any> | undefined;
+
+    if (shouldListen(options.listen)) {
+        app.listen(port);
+        server = (app as any).server;
+    }
+
+    const actualPort = server?.port ?? port;
+    const container = (app as any).container as Container;
+
+    // Pre-bind methods for performance
+    const baseUrl = `http://127.0.0.1:${actualPort}`;
+
+    const request = async (path: string, init?: RequestInit): Promise<Response> => {
+        if (!server) {
+            throw new Error('Server not running. Set listen: true in options.');
+        }
+        const url = path.startsWith('http') ? path : `${baseUrl}${path.startsWith('/') ? path : '/' + path}`;
+        return fetch(url, init);
+    };
+
+    return {
+        app,
+        container,
+        server,
+        port: actualPort,
+
+        resolve: <T>(token: Token<T>): T => container.get(token),
+
+        request,
+
+        get: (path, init) => request(path, { ...init, method: 'GET' }),
+
+        post: (path, body, init) => request(path, {
+            ...init,
+            method: 'POST',
+            body: body ? JSON.stringify(body) : undefined,
+            headers: { 'Content-Type': 'application/json', ...init?.headers }
+        }),
+
+        put: (path, body, init) => request(path, {
+            ...init,
+            method: 'PUT',
+            body: body ? JSON.stringify(body) : undefined,
+            headers: { 'Content-Type': 'application/json', ...init?.headers }
+        }),
+
+        delete: (path, init) => request(path, { ...init, method: 'DELETE' }),
+
+        close: async () => {
+            app.stop();
+        }
+    };
+}
+
+/**
+ * Run a test routine with automatic harness cleanup.
+ * 
+ * @example
+ * ```typescript
+ * await withTestApp(async (harness) => {
+ *   const response = await harness.get('/health');
+ *   expect(response.status).toBe(200);
+ * }, { controllers: [HealthController], listen: true });
+ * ```
+ */
+export async function withTestApp(
+    routine: (harness: TestHarness) => Promise<void>,
+    options: TestOptions = {}
+): Promise<void> {
+    const harness = await createTestHarness(options);
+
+    try {
+        await routine(harness);
+    } finally {
+        await harness.close();
+    }
+}
+
+function shouldListen(value: TestOptions['listen']): boolean {
+    return typeof value === 'number' || Boolean(value);
+}
+
+function resolvePort(options: TestOptions): number {
+    if (typeof options.listen === 'number') return options.listen;
+    if (typeof options.port === 'number') return options.port;
+    return 0; // Random port
+}

package/src/utils/Metadata.ts

@@ -0,0 +1,43 @@
+/**
+ * Utility class for handling metadata operations.
+ * Wraps Reflect.getMetadata and Reflect.defineMetadata.
+ */
+export class Metadata {
+  static get<T = any>(key: string | symbol, target: any): T | undefined {
+    return Reflect.getMetadata(key, target);
+  }
+
+  static set(key: string | symbol, value: any, target: any): void {
+    Reflect.defineMetadata(key, value, target);
+  }
+
+  static has(key: string | symbol, target: any): boolean {
+    return Reflect.hasMetadata(key, target);
+  }
+
+  static delete(key: string | symbol, target: any): boolean {
+    return Reflect.deleteMetadata(key, target);
+  }
+
+  static keys(target: any): (string | symbol)[] {
+    return Reflect.getMetadataKeys(target);
+  }
+
+  static getType(target: any, propertyKey: string | symbol): any {
+    return Reflect.getMetadata('design:type', target, propertyKey);
+  }
+}
+
+/**
+ * Type guard for checking if value is an object.
+ */
+export function isObject(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Type guard for checking if value is a string.
+ */
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}

package/src/validation/ValibotAdapter.ts

@@ -0,0 +1,95 @@
+import type { ValidatorAdapter, ValidationResult, ValidationError } from './ValidatorAdapter';
+import { VALIDATION_SCHEMA, getSchema } from './ValidatorAdapter';
+import { ValidationException } from './ZodAdapter';
+
+/**
+ * Valibot Adapter for Turbo validation.
+ * 
+ * Usage:
+ * ```typescript
+ * import * as v from 'valibot';
+ * 
+ * @Schema(v.object({
+ *   name: v.pipe(v.string(), v.minLength(1)),
+ *   email: v.pipe(v.string(), v.email())
+ * }))
+ * class CreateUserDto {
+ *   name: string;
+ *   email: string;
+ * }
+ * ```
+ */
+export class ValibotAdapter implements ValidatorAdapter {
+    readonly name = 'ValibotAdapter';
+
+    private schemaCache = new Map<any, any>();
+    private valibot: any = null;
+
+    constructor() {
+        // Lazy load valibot
+        try {
+            this.valibot = require('valibot');
+        } catch {
+            // Will be loaded on first use
+        }
+    }
+
+    private ensureValibot(): any {
+        if (!this.valibot) {
+            this.valibot = require('valibot');
+        }
+        return this.valibot;
+    }
+
+    hasValidation(target: any): boolean {
+        return getSchema(target) !== undefined;
+    }
+
+    validate<T>(target: any, value: unknown): ValidationResult<T> {
+        const schema = this.getOrCacheSchema(target);
+
+        if (!schema) {
+            return { success: true, data: value as T };
+        }
+
+        const v = this.ensureValibot();
+        const result = v.safeParse(schema, value);
+
+        if (result.success) {
+            return { success: true, data: result.output };
+        }
+
+        return {
+            success: false,
+            errors: this.formatErrors(result.issues)
+        };
+    }
+
+    validateOrThrow<T>(target: any, value: unknown): T {
+        const result = this.validate<T>(target, value);
+
+        if (result.success) {
+            return result.data!;
+        }
+
+        throw new ValidationException(result.errors!);
+    }
+
+    private getOrCacheSchema(target: any): any {
+        let schema = this.schemaCache.get(target);
+
+        if (schema === undefined) {
+            schema = getSchema(target) ?? null;
+            this.schemaCache.set(target, schema);
+        }
+
+        return schema;
+    }
+
+    private formatErrors(issues: any[]): ValidationError[] {
+        return issues.map((issue: any) => ({
+            path: issue.path?.map((p: any) => p.key).join('.') || '',
+            message: issue.message
+        }));
+    }
+}