@noony-serverless/core 0.3.4 → 0.4.1

package/build/core/containerPool.js

@@ -3,98 +3,243 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.containerPool = exports.ContainerPool = void 0;
 const typedi_1 = require("typedi");
 /**
- * Performance optimization: Container Pool for reusing TypeDI containers
- * This reduces object creation overhead and improves memory efficiency
+ * Symbol used to mark services as "deleted" in request-local scope
+ * @internal
+ */
+const TOMBSTONE = Symbol('TOMBSTONE');
+/**
+ * Hybrid Proxy Container Pool for serverless environments
+ *
+ * This implementation uses a zero-copy proxy pattern that provides:
+ * - Process Lifetime (Global): Services initialized once and shared across requests
+ * - Request Lifetime (Local): Services isolated per request with zero overhead
+ *
+ * Architecture:
+ * - Global Container: Singleton with process-lifetime services (DB, Logger, etc.)
+ * - Proxy Container: Lightweight wrapper per-request that shadows local overrides
+ * - Memory: O(1) per request (just the proxy + local overrides Map)
+ * - Performance: ~99% memory reduction vs traditional container pooling
+ *
+ * @example
+ * Basic usage with global services:
+ * ```typescript
+ * // Initialize global services once at startup
+ * containerPool.initializeGlobal([
+ *   { id: 'Database', value: new DatabaseService() },
+ *   { id: 'Logger', value: new LoggerService() }
+ * ]);
+ *
+ * // Per-request: Create lightweight proxy
+ * const container = containerPool.createProxyContainer();
+ * const db = container.get('Database');  // From global
+ * ```
+ *
+ * @example
+ * Request-scoped services with local overrides:
+ * ```typescript
+ * // Global services
+ * containerPool.initializeGlobal([
+ *   { id: UserService, value: new UserService() }
+ * ]);
+ *
+ * // Per-request: Add request-scoped data
+ * const container = containerPool.createProxyContainer();
+ * container.set('RequestId', 'req-123');      // Local scope only
+ * container.set('CurrentUser', currentUser);  // Local scope only
+ *
+ * const userService = container.get(UserService);  // From global
+ * const requestId = container.get('RequestId');    // From local
+ * ```
  */
 class ContainerPool {
-    availableContainers = [];
-    maxPoolSize = 10;
-    createdContainers = 0;
-    constructor(maxPoolSize = 10) {
-        this.maxPoolSize = maxPoolSize;
-    }
+    static globalContainer = null;
+    static useProxy = true;
     /**
-     * Get a container from the pool or create a new one
+     * Initialize the global container with process-lifetime services
+     * This should be called once at application startup
+     *
+     * @param services - Array of service definitions to register globally
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * containerPool.initializeGlobal([
+     *   { id: 'config', value: { apiUrl: 'https://api.example.com' } },
+     *   { id: DatabaseService, value: new DatabaseService() },
+     *   { id: LoggerService, value: new LoggerService() }
+     * ]);
+     * ```
      */
-    acquire() {
-        if (this.availableContainers.length > 0) {
-            return this.availableContainers.pop();
+    static initializeGlobal(services = [], options) {
+        if (options?.useProxy !== undefined) {
+            this.useProxy = options.useProxy;
         }
-        // Create new container if pool is empty and under limit
-        if (this.createdContainers < this.maxPoolSize) {
-            this.createdContainers++;
-            return typedi_1.Container.of();
+        // Create global container if not exists
+        if (!this.globalContainer) {
+            this.globalContainer = typedi_1.Container.of('__noony_global__');
         }
-        // If pool is at capacity, create a temporary container
-        // This should rarely happen in normal usage
-        return typedi_1.Container.of();
+        // Register all global services
+        services.forEach((service) => {
+            this.globalContainer.set(service.id, service.value);
+        });
     }
     /**
-     * Return a container to the pool for reuse
+     * Create a lightweight proxy container for a single request
+     *
+     * The proxy provides:
+     * - Read access to global services (zero-copy)
+     * - Local overrides for request-scoped data
+     * - Automatic garbage collection (no manual cleanup needed)
+     *
+     * @returns A proxy container instance with request-local scope
+     *
+     * @example
+     * ```typescript
+     * async function handleRequest(req, res) {
+     *   const container = containerPool.createProxyContainer();
+     *
+     *   // Add request-specific data
+     *   container.set('TraceId', req.headers['x-trace-id']);
+     *
+     *   // Access global services
+     *   const db = container.get(DatabaseService);
+     *
+     *   // No cleanup needed - auto GC'd
+     * }
+     * ```
      */
-    release(container) {
-        if (this.availableContainers.length < this.maxPoolSize) {
-            // Reset container state by removing all instances
-            // This prevents memory leaks and cross-request contamination
-            this.resetContainer(container);
-            this.availableContainers.push(container);
+    static createProxyContainer() {
+        // Ensure global container is initialized
+        if (!this.globalContainer) {
+            this.initializeGlobal([]);
         }
-        // If pool is full, let the container be garbage collected
+        // Request-local overrides Map (only allocates if services are set)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const localOverrides = new Map();
+        // Create proxy that intercepts container operations
+        const proxyContainer = new Proxy(this.globalContainer, {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            get(target, prop, receiver) {
+                // Intercept 'get' method for service resolution
+                if (prop === 'get') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return function (serviceId) {
+                        // 1. Check local overrides first (request scope)
+                        if (localOverrides.has(serviceId)) {
+                            const value = localOverrides.get(serviceId);
+                            // Handle tombstone (service marked as "deleted")
+                            if (value === TOMBSTONE) {
+                                throw new Error(`Service "${String(serviceId)}" not found (removed in request scope)`);
+                            }
+                            return value;
+                        }
+                        // 2. Fallback to global container (process scope)
+                        return target.get(serviceId);
+                    };
+                }
+                // Intercept 'set' method to write to local scope only
+                if (prop === 'set') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return function (serviceId, value) {
+                        // ✅ Write to local scope ONLY - never mutate global
+                        localOverrides.set(serviceId, value);
+                        return proxyContainer;
+                    };
+                }
+                // Intercept 'remove' method to mark as deleted locally
+                if (prop === 'remove') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return function (serviceId) {
+                        // Mark service as "deleted" in local scope using tombstone
+                        localOverrides.set(serviceId, TOMBSTONE);
+                        return proxyContainer;
+                    };
+                }
+                // Intercept 'reset' method to clear local overrides
+                if (prop === 'reset') {
+                    return function () {
+                        // Clear local overrides - revert to pure global state
+                        localOverrides.clear();
+                    };
+                }
+                // Intercept 'has' method for service existence check
+                if (prop === 'has') {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return function (serviceId) {
+                        // Check local overrides first
+                        if (localOverrides.has(serviceId)) {
+                            const value = localOverrides.get(serviceId);
+                            // Tombstone means service is "deleted"
+                            return value !== TOMBSTONE;
+                        }
+                        // Fallback to global container
+                        return target.has(serviceId);
+                    };
+                }
+                // For all other properties/methods, delegate to global container
+                const value = Reflect.get(target, prop, receiver);
+                // Bind methods to target to preserve 'this' context
+                if (typeof value === 'function') {
+                    return value.bind(target);
+                }
+                return value;
+            },
+        });
+        return proxyContainer;
     }
     /**
-     * Reset container state to prevent cross-request contamination
-     * Note: TypeDI containers are isolated by default, so we mainly need
-     * to clear any manually set values
+     * Create a middleware-compatible container factory
+     *
+     * @param services - Optional services to set as local overrides per-request
+     * @returns Function that creates proxy container with optional local services
+     *
+     * @example
+     * ```typescript
+     * const handler = new Handler()
+     *   .use(containerPool.asMiddleware([
+     *     { id: 'RequestId', value: 'req-123' }
+     *   ]))
+     *   .handle(async (context) => {
+     *     const requestId = context.container.get('RequestId');
+     *   });
+     * ```
      */
-    resetContainer(_container) {
-        try {
-            // For TypeDI containers created with Container.of(), each container
-            // is already isolated. We just need to ensure no memory leaks.
-            // The container will be garbage collected when released from pool
-            // if it contains too much data
-            // TypeDI containers are self-contained and don't need explicit reset
-            // This is a placeholder for future enhancements if needed
-        }
-        catch (error) {
-            // If any issues occur, don't add back to pool
-            console.warn('Failed to reset container, discarding:', error);
-        }
+    static asMiddleware(services = []) {
+        return (existingContainer) => {
+            const container = existingContainer || this.createProxyContainer();
+            // Set local services if provided
+            services.forEach((service) => {
+                container.set(service.id, service.value);
+            });
+            return container;
+        };
     }
     /**
-     * Get pool statistics for monitoring
+     * Get statistics about the container pool
+     * (Maintained for backward compatibility)
      */
-    getStats() {
+    static getStats() {
         return {
-            available: this.availableContainers.length,
-            created: this.createdContainers,
-            maxSize: this.maxPoolSize,
+            useProxy: this.useProxy,
+            globalInitialized: this.globalContainer !== null,
         };
     }
     /**
-     * Warm up the pool by pre-creating containers
+     * Clear the global container (useful for testing)
+     * ⚠️ WARNING: This resets ALL global services
      */
-    warmUp(count = 5) {
-        const warmUpCount = Math.min(count, this.maxPoolSize);
-        for (let i = 0; i < warmUpCount; i++) {
-            if (this.createdContainers < this.maxPoolSize) {
-                const container = typedi_1.Container.of();
-                this.createdContainers++;
-                this.availableContainers.push(container);
-            }
+    static clear() {
+        if (this.globalContainer) {
+            this.globalContainer.reset();
+            this.globalContainer = null;
         }
     }
-    /**
-     * Clear all containers from the pool
-     */
-    clear() {
-        this.availableContainers = [];
-        this.createdContainers = 0;
-    }
 }
 exports.ContainerPool = ContainerPool;
-// Global container pool instance
-const containerPool = new ContainerPool(15); // Slightly higher limit for serverless
+/**
+ * Global container pool instance
+ * Pre-initialized for immediate use in serverless environments
+ */
+const containerPool = ContainerPool;
 exports.containerPool = containerPool;
-// Warm up the pool for better cold start performance
-containerPool.warmUp(3);
 //# sourceMappingURL=containerPool.js.map

package/build/core/handler.d.ts

@@ -1,4 +1,4 @@
-import { Context, CustomRequest, CustomResponse, GenericRequest, GenericResponse } from './core';
+import { Context, GenericRequest, GenericResponse } from './core';
 /**
  * Interface representing a base structure for middleware with optional lifecycle methods.
  *
@@ -51,7 +51,7 @@ export declare class Handler<T = unknown, U = unknown> {
      * Performance optimization: Pre-compute middleware arrays to avoid runtime array operations
      */
     private precomputeMiddlewareArrays;
-    execute(req: CustomRequest<T>, res: CustomResponse): Promise<void>;
+    execute(req: GenericRequest<T>, res: GenericResponse): Promise<void>;
     /**
      * Execute before middlewares with optimized batching for independent middlewares
      */

package/build/core/handler.js

@@ -66,8 +66,8 @@ class Handler {
     async execute(req, res) {
         const genericReq = (0, core_1.adaptGCPRequest)(req);
         const genericRes = (0, core_1.adaptGCPResponse)(res);
-        // Performance optimization: Use container pool instead of creating new containers
-        const container = containerPool_1.containerPool.acquire();
+        // Hybrid Proxy Container: Lightweight zero-copy container per request
+        const container = containerPool_1.containerPool.createProxyContainer();
         const context = (0, core_1.createContext)(genericReq, genericRes, {
             container,
         });
@@ -83,10 +83,7 @@ class Handler {
             // Execute error handlers using pre-computed array
             await this.executeErrorMiddlewares(error, context);
         }
-        finally {
-            // Always return container to pool for reuse
-            containerPool_1.containerPool.release(container);
-        }
+        // No finally block needed - proxy container is auto-GC'd
     }
     /**
      * Execute before middlewares with optimized batching for independent middlewares
@@ -124,8 +121,8 @@ class Handler {
      * Framework-agnostic execute method that works with GenericRequest/GenericResponse
      */
     async executeGeneric(req, res) {
-        // Performance optimization: Use container pool instead of creating new containers
-        const container = containerPool_1.containerPool.acquire();
+        // Hybrid Proxy Container: Lightweight zero-copy container per request
+        const container = containerPool_1.containerPool.createProxyContainer();
         const context = (0, core_1.createContext)(req, res, {
             container,
         });
@@ -141,10 +138,7 @@ class Handler {
             // Execute error handlers using pre-computed array
             await this.executeErrorMiddlewares(error, context);
         }
-        finally {
-            // Always return container to pool for reuse
-            containerPool_1.containerPool.release(container);
-        }
+        // No finally block needed - proxy container is auto-GC'd
     }
 }
 exports.Handler = Handler;

package/build/core/index.d.ts

@@ -4,5 +4,6 @@ export * from './handler';
 export * from './logger';
 export * from './containerPool';
 export * from './performanceMonitor';
+export * from './telemetry';
 export * from '../middlewares';
 //# sourceMappingURL=index.d.ts.map

package/build/core/index.js

@@ -20,5 +20,6 @@ __exportStar(require("./handler"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./containerPool"), exports);
 __exportStar(require("./performanceMonitor"), exports);
+__exportStar(require("./telemetry"), exports);
 __exportStar(require("../middlewares"), exports);
 //# sourceMappingURL=index.js.map

package/build/core/logger.d.ts

@@ -1,13 +1,22 @@
+import type { Span, Context as OtelContext } from '@opentelemetry/api';
+import { type OTELLogContext } from '../utils/otel.helper';
 export interface LogOptions {
     structuredData?: boolean;
     [key: string]: boolean | string | number | object | undefined;
 }
+export interface LoggerConfig {
+    enableOTEL?: boolean;
+    structuredLogging?: boolean;
+    debugMode?: boolean;
+}
 declare class Logger {
     private logDataPool;
     private isDebugEnabled;
     private timestampCache;
     private lastTimestamp;
-    constructor();
+    private enableOTEL;
+    private otelContext?;
+    constructor(config?: LoggerConfig);
     /**
      * Performance optimized timestamp generation with caching
      * Cache timestamps for up to 1 second to reduce Date object creation
@@ -15,6 +24,7 @@ declare class Logger {
     private getTimestamp;
     /**
      * Optimized log method with object pooling and lazy evaluation
+     * Includes automatic OTEL trace/span ID injection when enabled
      */
     private log;
     /**
@@ -28,6 +38,83 @@ declare class Logger {
      * Performance monitoring method for internal framework use
      */
     logPerformance(operation: string, duration: number, metadata?: Record<string, unknown>): void;
+    /**
+     * Create a child logger with a specific span context
+     *
+     * This method creates a new logger instance that will automatically include
+     * the trace/span IDs from the provided span in all log entries.
+     *
+     * Useful for passing logger instances to services/functions that need
+     * to log within a specific span context.
+     *
+     * @param span - OpenTelemetry span to attach to logs
+     * @returns New logger instance with span context
+     *
+     * @example
+     * ```typescript
+     * import { trace } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const tracer = trace.getTracer('my-service');
+     * const span = tracer.startSpan('process-order');
+     *
+     * const spanLogger = logger.withSpan(span);
+     * spanLogger.info('Processing order'); // Includes span's trace/span IDs
+     *
+     * span.end();
+     * ```
+     */
+    withSpan(span: Span): Logger;
+    /**
+     * Create a child logger with a specific OTEL context
+     *
+     * This method creates a new logger instance that will automatically include
+     * trace/span IDs from the provided OTEL context in all log entries.
+     *
+     * Useful when working with OTEL Context propagation (e.g., Pub/Sub messages).
+     *
+     * @param context - OpenTelemetry context to extract span from
+     * @returns New logger instance with context
+     *
+     * @example
+     * ```typescript
+     * import { context, propagation } from '@opentelemetry/api';
+     * import { logger } from '@noony-serverless/core';
+     *
+     * // Extract context from Pub/Sub message
+     * const extractedContext = propagation.extract(
+     *   context.active(),
+     *   message.attributes
+     * );
+     *
+     * const contextLogger = logger.withOTEL(extractedContext);
+     * contextLogger.info('Processing message'); // Includes trace/span IDs
+     * ```
+     */
+    withOTEL(otelContext: OtelContext): Logger;
+    /**
+     * Create a child logger with custom OTEL context
+     *
+     * This method creates a new logger instance with manually specified
+     * trace/span IDs. Useful when you have trace context from external sources.
+     *
+     * @param context - OTEL log context with trace/span IDs
+     * @returns New logger instance with custom context
+     *
+     * @example
+     * ```typescript
+     * import { logger } from '@noony-serverless/core';
+     *
+     * const customLogger = logger.withContext({
+     *   traceId: '13ea7e3c2d3b4547baaa399062df1f2d',
+     *   spanId: '1234567890123456',
+     *   traceFlags: 1
+     * });
+     *
+     * customLogger.info('Custom trace context'); // Includes specified IDs
+     * ```
+     */
+    withContext(context: OTELLogContext): Logger;
     /**
      * Get logger statistics for monitoring
      */
@@ -35,6 +122,7 @@ declare class Logger {
         poolSize: number;
         maxPoolSize: number;
         debugEnabled: boolean;
+        otelEnabled: boolean;
     };
 }
 export declare const logger: Logger;