@carno.js/core 0.2.11 → 1.0.2

package/src/cache/CacheService.ts

@@ -0,0 +1,139 @@
+import type { CacheDriver, CacheConfig } from './CacheDriver';
+import { MemoryDriver } from './MemoryDriver';
+
+/**
+ * CacheService - High-performance caching with driver pattern.
+ * 
+ * Features:
+ * - In-memory (default) or Redis backend
+ * - getOrSet for cache-aside pattern
+ * - Key prefixing for namespacing
+ * - Configurable default TTL
+ * 
+ * Usage:
+ * ```typescript
+ * const cache = new CacheService();
+ * 
+ * // Basic operations
+ * await cache.set('user:123', { name: 'John' }, 3600);
+ * const user = await cache.get<User>('user:123');
+ * 
+ * // Cache-aside pattern
+ * const user = await cache.getOrSet('user:123', 
+ *   async () => db.findUser(123),
+ *   3600
+ * );
+ * ```
+ */
+export class CacheService {
+    private driver: CacheDriver;
+    private prefix: string;
+    private defaultTtl: number | undefined;
+
+    constructor(config: CacheConfig = {}) {
+        this.driver = config.driver || new MemoryDriver();
+        this.prefix = config.prefix || '';
+        this.defaultTtl = config.defaultTtl;
+    }
+
+    /**
+     * Get the full key with prefix.
+     */
+    private key(key: string): string {
+        return this.prefix ? `${this.prefix}:${key}` : key;
+    }
+
+    /**
+     * Get a value from cache.
+     */
+    async get<T>(key: string): Promise<T | null> {
+        return this.driver.get<T>(this.key(key));
+    }
+
+    /**
+     * Set a value in cache.
+     * @param ttl Time to live in seconds
+     */
+    async set<T>(key: string, value: T, ttl?: number): Promise<boolean> {
+        return this.driver.set(this.key(key), value, ttl ?? this.defaultTtl);
+    }
+
+    /**
+     * Delete a value from cache.
+     */
+    async del(key: string): Promise<boolean> {
+        return this.driver.del(this.key(key));
+    }
+
+    /**
+     * Check if key exists.
+     */
+    async has(key: string): Promise<boolean> {
+        return this.driver.has(this.key(key));
+    }
+
+    /**
+     * Clear all cached values.
+     */
+    async clear(): Promise<void> {
+        return this.driver.clear();
+    }
+
+    /**
+     * Get value from cache or compute and store it.
+     * This is the cache-aside pattern - most commonly used method.
+     * 
+     * @param key Cache key
+     * @param cb Callback to compute value if not cached
+     * @param ttl Time to live in seconds
+     */
+    async getOrSet<T>(key: string, cb: () => Promise<T>, ttl?: number): Promise<T> {
+        const cached = await this.get<T>(key);
+
+        if (cached !== null) {
+            return cached;
+        }
+
+        const value = await cb();
+        await this.set(key, value, ttl);
+
+        return value;
+    }
+
+    /**
+     * Get multiple values at once.
+     */
+    async getMany<T>(keys: string[]): Promise<(T | null)[]> {
+        return Promise.all(keys.map(key => this.get<T>(key)));
+    }
+
+    /**
+     * Set multiple values at once.
+     */
+    async setMany<T>(entries: Array<{ key: string; value: T; ttl?: number }>): Promise<boolean[]> {
+        return Promise.all(
+            entries.map(entry => this.set(entry.key, entry.value, entry.ttl))
+        );
+    }
+
+    /**
+     * Delete multiple values at once.
+     */
+    async delMany(keys: string[]): Promise<boolean[]> {
+        return Promise.all(keys.map(key => this.del(key)));
+    }
+
+    /**
+     * Close the cache driver connection.
+     */
+    async close(): Promise<void> {
+        await this.driver.close?.();
+    }
+
+    /**
+     * Get the underlying driver (for advanced use).
+     */
+    getDriver(): CacheDriver {
+        return this.driver;
+    }
+}

package/src/cache/MemoryDriver.ts

@@ -0,0 +1,104 @@
+import type { CacheDriver } from './CacheDriver';
+
+interface CacheEntry<T> {
+    value: T;
+    expiresAt: number | null;
+}
+
+/**
+ * In-Memory Cache Driver.
+ * Ultra-fast, perfect for single-instance applications.
+ * 
+ * Features:
+ * - O(1) get/set/del operations
+ * - Lazy expiration (checked on access)
+ * - Periodic cleanup of expired entries
+ */
+export class MemoryDriver implements CacheDriver {
+    readonly name = 'MemoryDriver';
+
+    private cache = new Map<string, CacheEntry<any>>();
+    private cleanupInterval: Timer | null = null;
+
+    constructor(cleanupIntervalMs: number = 0) {
+        // Periodic cleanup of expired entries (disabled by default for performance)
+        if (cleanupIntervalMs > 0) {
+            this.cleanupInterval = setInterval(() => this.cleanup(), cleanupIntervalMs);
+        }
+    }
+
+    async get<T>(key: string): Promise<T | null> {
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            return null;
+        }
+
+        // Check expiration
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+
+        return entry.value;
+    }
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<boolean> {
+        const expiresAt = ttl ? Date.now() + ttl : null;
+
+        this.cache.set(key, { value, expiresAt });
+
+        return true;
+    }
+
+    async del(key: string): Promise<boolean> {
+        return this.cache.delete(key);
+    }
+
+    async has(key: string): Promise<boolean> {
+        const entry = this.cache.get(key);
+
+        if (!entry) {
+            return false;
+        }
+
+        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+
+        return true;
+    }
+
+    async clear(): Promise<void> {
+        this.cache.clear();
+    }
+
+    async close(): Promise<void> {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+    }
+
+    /**
+     * Remove expired entries.
+     */
+    private cleanup(): void {
+        const now = Date.now();
+
+        for (const [key, entry] of this.cache) {
+            if (entry.expiresAt !== null && now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Get cache stats (for debugging).
+     */
+    stats(): { size: number } {
+        return { size: this.cache.size };
+    }
+}

package/src/cache/RedisDriver.ts

@@ -0,0 +1,116 @@
+import type { CacheDriver } from './CacheDriver';
+
+/**
+ * Redis Cache Driver Configuration.
+ */
+export interface RedisConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    url?: string;
+}
+
+/**
+ * Redis Cache Driver.
+ * For distributed caching in multi-instance deployments.
+ * 
+ * Uses Bun's native Redis client for maximum performance.
+ */
+export class RedisDriver implements CacheDriver {
+    readonly name = 'RedisDriver';
+
+    private client: any = null;
+    private connected = false;
+
+    constructor(private config: RedisConfig = {}) { }
+
+    /**
+     * Connect to Redis (lazy - connects on first use).
+     */
+    private async ensureConnected(): Promise<void> {
+        if (this.connected) return;
+
+        const url = this.config.url ||
+            `redis://${this.config.host || 'localhost'}:${this.config.port || 6379}`;
+
+        // Use Bun's native Redis client if available
+        if (typeof Bun !== 'undefined' && (Bun as any).redis) {
+            this.client = new (Bun as any).redis(url);
+        } else {
+            // Fallback to ioredis
+            try {
+                const Redis = require('ioredis');
+                this.client = new Redis({
+                    host: this.config.host || 'localhost',
+                    port: this.config.port || 6379,
+                    password: this.config.password,
+                    db: this.config.db || 0
+                });
+            } catch {
+                throw new Error('Redis client not available. Install ioredis or use Bun with Redis support.');
+            }
+        }
+
+        this.connected = true;
+    }
+
+    async get<T>(key: string): Promise<T | null> {
+        await this.ensureConnected();
+
+        const value = await this.client.get(key);
+
+        if (value === null) {
+            return null;
+        }
+
+        try {
+            return JSON.parse(value);
+        } catch {
+            return value as T;
+        }
+    }
+
+    async set<T>(key: string, value: T, ttl?: number): Promise<boolean> {
+        await this.ensureConnected();
+
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+
+        if (ttl) {
+            await this.client.setex(key, ttl, serialized);
+        } else {
+            await this.client.set(key, serialized);
+        }
+
+        return true;
+    }
+
+    async del(key: string): Promise<boolean> {
+        await this.ensureConnected();
+
+        const result = await this.client.del(key);
+
+        return result > 0;
+    }
+
+    async has(key: string): Promise<boolean> {
+        await this.ensureConnected();
+
+        const result = await this.client.exists(key);
+
+        return result > 0;
+    }
+
+    async clear(): Promise<void> {
+        await this.ensureConnected();
+
+        await this.client.flushdb();
+    }
+
+    async close(): Promise<void> {
+        if (this.client && this.connected) {
+            await this.client.quit?.();
+            this.connected = false;
+        }
+    }
+}

package/src/compiler/JITCompiler.ts

@@ -0,0 +1,167 @@
+/**
+ * JIT Compiler for Turbo.
+ * 
+ * Aggressive AOT optimizations:
+ * - Detects async at compile time (not runtime)
+ * - Generates specialized handlers via new Function()
+ * - Inlines parameter access
+ * - Zero overhead for simple handlers
+ */
+
+import type { ParamType } from '../decorators/params';
+
+export interface ParamInfo {
+    type: ParamType;
+    key?: string;
+    index: number;
+}
+
+export interface CompiledHandler {
+    fn: Function;
+    isAsync: boolean;
+    isStatic: boolean;
+    staticValue?: any;
+}
+
+const ASYNC_REGEX = /^async\s|^\([^)]*\)\s*=>\s*\{[\s\S]*await\s|^function\s*\*|\.then\s*\(/;
+
+/**
+ * Detects if function is async at compile time.
+ * Checks: async keyword, await usage, generators, .then()
+ */
+export function isAsyncFunction(fn: Function): boolean {
+    if (fn.constructor.name === 'AsyncFunction') {
+        return true;
+    }
+
+    const source = fn.toString();
+
+    return ASYNC_REGEX.test(source);
+}
+
+/**
+ * Detects if handler returns a static value.
+ * Static handlers can be pre-computed at startup.
+ */
+export function isStaticHandler(fn: Function): boolean {
+    const source = fn.toString();
+
+    if (source.includes('this.') || source.includes('await')) {
+        return false;
+    }
+
+    const returnMatch = source.match(/=>\s*["'`]|return\s+["'`]|=>\s*\{|=>\s*\d/);
+
+    return !!returnMatch;
+}
+
+/**
+ * Compiles handler with inlined parameter access.
+ * Uses new Function() for maximum V8 optimization.
+ */
+export function compileHandler(
+    instance: any,
+    methodName: string,
+    params: ParamInfo[]
+): CompiledHandler {
+    const method = instance[methodName];
+    const bound = method.bind(instance);
+    const async = isAsyncFunction(method);
+
+    if (params.length === 0) {
+        const isStatic = isStaticHandler(method);
+
+        if (isStatic && !async) {
+            const staticValue = bound();
+
+            return {
+                fn: bound,
+                isAsync: false,
+                isStatic: true,
+                staticValue
+            };
+        }
+
+        return {
+            fn: bound,
+            isAsync: async,
+            isStatic: false
+        };
+    }
+
+    const argExprs = params
+        .sort((a, b) => a.index - b.index)
+        .map(p => buildArgExpression(p));
+
+    const argsCode = argExprs.join(',');
+    const hasBody = params.some(p => p.type === 'body');
+
+    if (hasBody) {
+        const code = `return async function(c){
+await c.parseBody();
+return h(${argsCode});
+}`;
+
+        return {
+            fn: new Function('h', code)(bound),
+            isAsync: true,
+            isStatic: false
+        };
+    }
+
+    if (async) {
+        const code = `return async function(c){
+return await h(${argsCode});
+}`;
+
+        return {
+            fn: new Function('h', code)(bound),
+            isAsync: true,
+            isStatic: false
+        };
+    }
+
+    const code = `return function(c){
+return h(${argsCode});
+}`;
+
+    return {
+        fn: new Function('h', code)(bound),
+        isAsync: false,
+        isStatic: false
+    };
+}
+
+function escapeKey(key: string): string {
+    return key.replace(/['\"\\]/g, '\\$&');
+}
+
+function buildArgExpression(param: ParamInfo): string {
+    const key = param.key ? escapeKey(param.key) : undefined;
+
+    switch (param.type) {
+        case 'param':
+            return key ? `c.params['${key}']` : 'c.params';
+
+        case 'query':
+            return key ? `c.query['${key}']` : 'c.query';
+
+        case 'body':
+            return key ? `c.body['${key}']` : 'c.body';
+
+        case 'header':
+            return key ? `c.req.headers.get('${key}')` : 'c.req.headers';
+
+        case 'req':
+            return 'c.req';
+
+        case 'ctx':
+            return 'c';
+
+        case 'locals':
+            return key ? `c.locals['${key}']` : 'c.locals';
+
+        default:
+            return 'undefined';
+    }
+}

package/src/container/Container.ts

@@ -0,0 +1,168 @@
+/**
+ * Lightweight DI Container for Turbo.
+ * 
+ * Features:
+ * - Constructor injection via reflect-metadata
+ * - Singleton scope by default
+ * - Request scope support
+ * - Lazy instantiation
+ */
+
+export type Token<T = any> = new (...args: any[]) => T;
+
+export enum Scope {
+    SINGLETON = 'singleton', // Always the same instance
+    REQUEST = 'request',     // New instance per request
+    INSTANCE = 'instance'    // New instance per dependency injection
+}
+
+export interface ProviderConfig<T = any> {
+    token: Token<T>;
+    useClass?: Token<T>;
+    useValue?: T;
+    scope?: Scope;
+}
+
+interface ProviderEntry {
+    config: ProviderConfig;
+    instance: any | null;
+}
+
+export class Container {
+    private configs = new Map<Token, ProviderConfig>();
+    private instances = new Map<Token, any>();
+    private resolving = new Set<Token>();
+
+    register<T>(config: ProviderConfig<T> | Token<T>): this {
+        const normalized = this.normalizeConfig(config);
+
+        this.configs.set(normalized.token, normalized);
+
+        if (normalized.useValue !== undefined) {
+            this.instances.set(normalized.token, normalized.useValue);
+        }
+
+        return this;
+    }
+
+    get<T>(token: Token<T>): T {
+        const cached = this.instances.get(token);
+
+        if (cached !== undefined) {
+            return cached;
+        }
+
+        const res = this.resolveInternal(token);
+        return res.instance;
+    }
+
+    has(token: Token): boolean {
+        return this.configs.has(token);
+    }
+
+    /**
+     * Resolves a token to return instance and its effective scope.
+     */
+    private resolveInternal<T>(token: Token<T>, requestLocals?: Map<Token, any>): { instance: T, scope: Scope } {
+        // 1. Check Request Cache
+        if (requestLocals?.has(token)) {
+            return { instance: requestLocals.get(token), scope: Scope.REQUEST };
+        }
+
+        // 2. Check Singleton Cache
+        const cached = this.instances.get(token);
+        if (cached !== undefined) {
+            return { instance: cached, scope: Scope.SINGLETON };
+        }
+
+        const config = this.configs.get(token);
+
+        if (!config) {
+            throw new Error(`Provider not found: ${token.name}`);
+        }
+
+        // 3. Create Instance with Scope Bubbling
+        const creation = this.createInstance(config, requestLocals);
+
+        // 4. Cache based on Effective Scope
+        if (creation.scope === Scope.SINGLETON) {
+            this.instances.set(token, creation.instance);
+        } else if (creation.scope === Scope.REQUEST && requestLocals) {
+            requestLocals.set(token, creation.instance);
+        }
+        // INSTANCE scope is never cached
+
+        return creation;
+    }
+
+    private createInstance(config: ProviderConfig, requestLocals?: Map<Token, any>): { instance: any, scope: Scope } {
+        const target = config.useClass ?? config.token;
+
+        if (this.resolving.has(target)) {
+            throw new Error(`Circular dependency detected: ${target.name}`);
+        }
+
+        this.resolving.add(target);
+
+        try {
+            const depsToken = this.getDependencies(target);
+
+            if (depsToken.length === 0) {
+                // No deps: Scope is as configured
+                return { instance: new target(), scope: config.scope || Scope.SINGLETON };
+            }
+
+            const args: any[] = [];
+            let effectiveScope = config.scope || Scope.SINGLETON;
+
+            for (const depToken of depsToken) {
+                const depResult = this.resolveInternal(depToken, requestLocals);
+                args.push(depResult.instance);
+
+                // Scope Bubbling Logic:
+                // If a dependency is REQUEST scoped, the parent MUST become REQUEST scoped (if it was Singleton)
+                // to avoid holding a stale reference to a request-bound instance.
+                if (depResult.scope === Scope.REQUEST && effectiveScope === Scope.SINGLETON) {
+                    effectiveScope = Scope.REQUEST;
+                }
+
+                // Note: INSTANCE scope dependencies do not force bubbling because they are transient and safe to hold (usually),
+                // unless semantic logic dictates otherwise. For now, strictly bubbling REQUEST scope.
+            }
+
+            return { instance: new target(...args), scope: effectiveScope };
+        } finally {
+            this.resolving.delete(target);
+        }
+    }
+
+    private getDependencies(target: Token): Token[] {
+        const types = Reflect.getMetadata('design:paramtypes', target) || [];
+        return types.filter((t: any) => t && typeof t === 'function' && !this.isPrimitive(t));
+    }
+
+    private isPrimitive(type: any): boolean {
+        return type === String || type === Number || type === Boolean || type === Object || type === Array || type === Symbol;
+    }
+
+    private normalizeConfig<T>(config: ProviderConfig<T> | Token<T>): ProviderConfig<T> {
+        if (typeof config === 'function') {
+            return {
+                token: config,
+                useClass: config,
+                scope: Scope.SINGLETON
+            };
+        }
+
+        return {
+            ...config,
+            useClass: config.useClass ?? config.token,
+            scope: config.scope ?? Scope.SINGLETON
+        };
+    }
+
+    clear(): void {
+        this.configs.clear();
+        this.instances.clear();
+    }
+}