@engjts/nexus 0.1.0

package/src/core/middleware.ts

@@ -0,0 +1,262 @@
+/**
+ * Type-safe middleware system
+ * Provides composable middleware with automatic error handling
+ */
+
+import { Context, Middleware, Handler, Response, Next, LifecycleHooks } from './types';
+
+/**
+ * Middleware executor
+ * Executes a chain of middleware and the final handler
+ */
+export class MiddlewareExecutor {
+    /**
+     * Execute middleware chain with a final handler
+     */
+    async execute(
+        ctx: Context,
+        middlewares: Middleware[],
+        handler: Handler,
+        deps: any = {}
+    ): Promise<Response> {
+        let index = 0;
+
+        const next: Next = async (currentCtx: Context): Promise<Response> => {
+            if (index < middlewares.length) {
+                const middleware = middlewares[index++];
+
+                try {
+                    // Execute middleware with next function and dependencies
+                    return await middleware(currentCtx, next, deps);
+                } catch (error) {
+                    // Propagate error to be caught by error handler
+                    throw error;
+                }
+            } else {
+                // All middleware executed, call final handler
+                try {
+                    const result = await handler(currentCtx, deps);
+
+                    // If handler returns an Error, throw it to be caught by error handler
+                    if (result instanceof Error) {
+                        // Mark as intentional (returned, not thrown)
+                        (result as any)._isIntentional = true;
+                        throw result;
+                    }
+
+                    // If handler returns a Response, use it
+                    if (this.isResponse(result)) {
+                        return result;
+                    }
+
+                    // Otherwise, wrap in JSON response
+                    return currentCtx.json(result);
+                } catch (error) {
+                    throw error;
+                }
+            }
+        };
+
+        return next(ctx);
+    }
+
+    /**
+     * Execute middleware chain with lifecycle hooks
+     * This method integrates hooks at the appropriate points in the request lifecycle
+     */
+    async executeWithHooks(
+        ctx: Context,
+        middlewares: Middleware[],
+        handler: Handler,
+        hooks: LifecycleHooks,
+        deps: any = {}
+    ): Promise<Response> {
+        let index = 0;
+
+        const next: Next = async (currentCtx: Context): Promise<Response> => {
+            if (index < middlewares.length) {
+                const middleware = middlewares[index++];
+
+                try {
+                    // Execute middleware with next function and dependencies
+                    return await middleware(currentCtx, next, deps);
+                } catch (error) {
+                    throw error;
+                }
+            } else {
+                // All middleware executed, now run handler with hooks
+                
+                // === HOOK: beforeValidation ===
+                if (hooks.beforeValidation) {
+                    const hookResult = await hooks.beforeValidation(currentCtx);
+                    if (this.isResponse(hookResult)) {
+                        return hookResult;
+                    }
+                }
+
+                // TODO: Schema validation happens here (if route has schema)
+                // For now, validation is handled in middleware or by the handler itself
+
+                // === HOOK: afterValidation ===
+                if (hooks.afterValidation) {
+                    const hookResult = await hooks.afterValidation(currentCtx);
+                    if (this.isResponse(hookResult)) {
+                        return hookResult;
+                    }
+                }
+
+                // === HOOK: beforeHandler ===
+                if (hooks.beforeHandler) {
+                    const hookResult = await hooks.beforeHandler(currentCtx);
+                    if (this.isResponse(hookResult)) {
+                        return hookResult;
+                    }
+                }
+
+                // Execute the handler with dependencies
+                try {
+                    let result = await handler(currentCtx, deps);
+
+                    // If handler returns an Error, throw it
+                    if (result instanceof Error) {
+                        (result as any)._isIntentional = true;
+                        throw result;
+                    }
+
+                    // === HOOK: afterHandler ===
+                    if (hooks.afterHandler) {
+                        const transformedResult = await hooks.afterHandler(currentCtx, result);
+                        if (transformedResult !== undefined) {
+                            result = transformedResult;
+                        }
+                    }
+
+                    // If result is a Response, return it
+                    if (this.isResponse(result)) {
+                        return result;
+                    }
+
+                    // Otherwise, wrap in JSON response
+                    return currentCtx.json(result);
+                } catch (error) {
+                    throw error;
+                }
+            }
+        };
+
+        return next(ctx);
+    }
+
+    /**
+     * Compose multiple middleware into a single middleware function
+     */
+    compose(middlewares: Middleware[]): Middleware {
+        return async (ctx: Context, next: Next, deps: any): Promise<Response> => {
+            let index = 0;
+
+            const dispatch = async (i: number, currentCtx: Context): Promise<Response> => {
+                if (i >= middlewares.length) {
+                    return next(currentCtx);
+                }
+
+                const middleware = middlewares[i];
+                index = i + 1;
+
+                return middleware(currentCtx, (nextCtx) => dispatch(index, nextCtx), deps);
+            };
+
+            return dispatch(0, ctx);
+        };
+    }
+
+    /**
+     * Check if value is a Response object
+     */
+    private isResponse(value: any): value is Response {
+        return (
+            value &&
+            typeof value === 'object' &&
+            'statusCode' in value &&
+            'headers' in value &&
+            'body' in value
+        );
+    }
+}
+
+/**
+ * Built-in middleware utilities
+ */
+
+/**
+ * Logger middleware
+ */
+export function logger(): Middleware {
+    return async (ctx, next, _deps) => {
+        const start = Date.now();
+        console.log(`--> ${ctx.method} ${ctx.path}`);
+
+        try {
+            const response = await next(ctx);
+            const duration = Date.now() - start;
+            console.log(`<-- ${ctx.method} ${ctx.path} ${response.statusCode} ${duration}ms`);
+            return response;
+        } catch (error) {
+            const duration = Date.now() - start;
+            console.error(`<-- ${ctx.method} ${ctx.path} ERROR ${duration}ms`);
+            throw error;
+        }
+    };
+}
+
+/**
+ * CORS middleware
+ */
+export function cors(options: {
+    origin?: string | string[];
+    methods?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+} = {}): Middleware {
+    const {
+        origin = '*',
+        methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+        credentials = false,
+        maxAge = 86400
+    } = options;
+
+    return async (ctx, next, _deps) => {
+        const response = await next(ctx);
+
+        // Set CORS headers
+        response.headers['Access-Control-Allow-Origin'] = Array.isArray(origin) ? origin.join(',') : origin;
+        response.headers['Access-Control-Allow-Methods'] = methods.join(',');
+        response.headers['Access-Control-Max-Age'] = maxAge.toString();
+
+        if (credentials) {
+            response.headers['Access-Control-Allow-Credentials'] = 'true';
+        }
+
+        // Handle preflight
+        if (ctx.method === 'OPTIONS') {
+            response.statusCode = 204;
+            response.body = '';
+        }
+
+        return response;
+    };
+}
+
+/**
+ * Error handling middleware wrapper
+ */
+export function errorHandler(
+    handler: (error: Error, ctx: Context) => Response | Promise<Response>
+): Middleware {
+    return async (ctx, next, _deps) => {
+        try {
+            return await next(ctx);
+        } catch (error) {
+            return handler(error as Error, ctx);
+        }
+    };
+}

package/src/core/performance/buffer-pool.ts

@@ -0,0 +1,108 @@
+/**
+ * Performance optimizations - Buffer pooling
+ * Zero-copy buffer handling for request/response bodies
+ */
+
+/**
+ * Buffer pool for reusing buffers
+ */
+export class BufferPool {
+    private pool: Buffer[] = [];
+    private bufferSize: number;
+    private maxPoolSize: number;
+
+    constructor(bufferSize: number = 8192, maxPoolSize: number = 50) {
+        this.bufferSize = bufferSize;
+        this.maxPoolSize = maxPoolSize;
+    }
+
+    /**
+     * Acquire a buffer from the pool
+     */
+    acquire(): Buffer {
+        if (this.pool.length > 0) {
+            return this.pool.pop()!;
+        }
+        return Buffer.allocUnsafe(this.bufferSize);
+    }
+
+    /**
+     * Release a buffer back to the pool
+     */
+    release(buffer: Buffer): void {
+        if (this.pool.length < this.maxPoolSize && buffer.length === this.bufferSize) {
+            // Clear the buffer before returning to pool
+            buffer.fill(0);
+            this.pool.push(buffer);
+        }
+    }
+
+    /**
+     * Clear the pool
+     */
+    clear(): void {
+        this.pool = [];
+    }
+
+    /**
+     * Get pool statistics
+     */
+    getStats() {
+        return {
+            poolSize: this.pool.length,
+            maxPoolSize: this.maxPoolSize,
+            bufferSize: this.bufferSize
+        };
+    }
+}
+
+/**
+ * Stream utilities for efficient data handling
+ */
+export class StreamUtils {
+    /**
+     * Read stream into buffer without copying
+     */
+    static async readStream(stream: NodeJS.ReadableStream, maxSize?: number): Promise<Buffer> {
+        return new Promise((resolve, reject) => {
+            const chunks: Buffer[] = [];
+            let totalSize = 0;
+
+            stream.on('data', (chunk: Buffer) => {
+                totalSize += chunk.length;
+
+                if (maxSize && totalSize > maxSize) {
+                    if (typeof (stream as any).destroy === 'function') {
+                        (stream as any).destroy();
+                    }
+                    reject(new Error(`Stream size exceeds maximum of ${maxSize} bytes`));
+                    return;
+                }
+
+                chunks.push(chunk);
+            });
+
+            stream.on('end', () => {
+                resolve(Buffer.concat(chunks));
+            });
+
+            stream.on('error', reject);
+        });
+    }
+
+    /**
+     * Pipe stream with error handling
+     */
+    static pipeWithErrorHandling(
+        source: NodeJS.ReadableStream,
+        destination: NodeJS.WritableStream
+    ): Promise<void> {
+        return new Promise((resolve, reject) => {
+            source.pipe(destination);
+
+            source.on('error', reject);
+            destination.on('error', reject);
+            destination.on('finish', resolve);
+        });
+    }
+}

package/src/core/performance/middleware-optimizer.ts

@@ -0,0 +1,162 @@
+/**
+ * Middleware Optimizer
+ * Provides utilities for composing and optimizing middleware chains
+ */
+
+import { Handler, Middleware } from '../types';
+
+/**
+ * Optimization statistics
+ */
+interface OptimizationStats {
+    cachedHandlers: number;
+    cachedMiddlewares: number;
+    composedChains: number;
+}
+
+/**
+ * Middleware Optimizer
+ * Caches and composes middleware chains for better performance
+ */
+export class MiddlewareOptimizer {
+    private handlerCache: WeakMap<Handler, Handler> = new WeakMap();
+    private middlewareCache: WeakMap<Middleware, Middleware> = new WeakMap();
+    private stats: OptimizationStats = {
+        cachedHandlers: 0,
+        cachedMiddlewares: 0,
+        composedChains: 0
+    };
+
+    /**
+     * Cache a handler to avoid repeated wrapping
+     */
+    cacheHandler(handler: Handler): Handler {
+        const cached = this.handlerCache.get(handler);
+        if (cached) return cached;
+
+        // Store reference for caching
+        this.handlerCache.set(handler, handler);
+        this.stats.cachedHandlers++;
+
+        return handler;
+    }
+
+    /**
+     * Cache middleware functions
+     */
+    cacheMiddleware(middlewares: Middleware[]): Middleware[] {
+        return middlewares.map(mw => {
+            const cached = this.middlewareCache.get(mw);
+            if (cached) return cached;
+
+            this.middlewareCache.set(mw, mw);
+            this.stats.cachedMiddlewares++;
+
+            return mw;
+        });
+    }
+
+    /**
+     * Compose middleware chain into single function
+     * Reduces function call overhead for frequently used routes
+     */
+    compose(middlewares: Middleware[]): Middleware {
+        if (middlewares.length === 0) {
+            return async (ctx, next, _deps) => next(ctx);
+        }
+
+        if (middlewares.length === 1) {
+            return middlewares[0];
+        }
+
+        this.stats.composedChains++;
+
+        // Create composed middleware that reduces call stack depth
+        return async (ctx, next, deps) => {
+            let index = 0;
+
+            const dispatch = async (currentCtx: any): Promise<any> => {
+                if (index >= middlewares.length) {
+                    return next(currentCtx);
+                }
+
+                const mw = middlewares[index++];
+                return mw(currentCtx, dispatch, deps);
+            };
+
+            return dispatch(ctx);
+        };
+    }
+
+    /**
+     * Get optimization statistics
+     */
+    getStats(): OptimizationStats {
+        return { ...this.stats };
+    }
+
+    /**
+     * Clear caches
+     */
+    clearCache(): void {
+        this.handlerCache = new WeakMap();
+        this.middlewareCache = new WeakMap();
+        this.stats.cachedHandlers = 0;
+        this.stats.cachedMiddlewares = 0;
+        this.stats.composedChains = 0;
+    }
+}
+
+/**
+ * Performance monitoring utilities
+ */
+export class PerformanceMonitor {
+    private metrics: Map<string, { count: number; totalTime: number; avgTime: number }> = new Map();
+
+    /**
+     * Measure execution time of a function
+     */
+    async measure<T>(name: string, fn: () => Promise<T>): Promise<T> {
+        const start = performance.now();
+
+        try {
+            return await fn();
+        } finally {
+            const duration = performance.now() - start;
+            this.recordMetric(name, duration);
+        }
+    }
+
+    /**
+     * Record a metric
+     */
+    private recordMetric(name: string, duration: number): void {
+        const existing = this.metrics.get(name);
+
+        if (existing) {
+            existing.count++;
+            existing.totalTime += duration;
+            existing.avgTime = existing.totalTime / existing.count;
+        } else {
+            this.metrics.set(name, {
+                count: 1,
+                totalTime: duration,
+                avgTime: duration
+            });
+        }
+    }
+
+    /**
+     * Get all metrics
+     */
+    getMetrics() {
+        return Object.fromEntries(this.metrics);
+    }
+
+    /**
+     * Clear metrics
+     */
+    clearMetrics(): void {
+        this.metrics.clear();
+    }
+}