@noony-serverless/core 0.3.3 → 0.4.0

package/build/middlewares/dependencyInjectionMiddleware.js

@@ -2,12 +2,14 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dependencyInjection = exports.DependencyInjectionMiddleware = void 0;
-const typedi_1 = require("typedi");
+const containerPool_1 = require("../core/containerPool");
 /**
  * Middleware to inject dependencies into the request context using typedi.
  * This allows handlers to access shared services or data via context.container.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * Basic service injection:
@@ -151,14 +153,25 @@ const typedi_1 = require("typedi");
  */
 class DependencyInjectionMiddleware {
     services;
-    constructor(services) {
+    options;
+    constructor(services = [], options) {
         this.services = services;
+        this.options = options;
     }
     async before(context) {
-        this.services.forEach((service) => {
-            typedi_1.Container.set(service.id, service.value);
-        });
-        context.container = typedi_1.Container.of();
+        const scope = this.options?.scope || 'local';
+        if (scope === 'global') {
+            // Register services globally (process-lifetime)
+            // ⚠️ Use sparingly - only for truly shared services like DB connections
+            containerPool_1.containerPool.initializeGlobal(this.services);
+        }
+        else {
+            // Register services locally (request-lifetime)
+            // ✅ Recommended for most use cases - isolated per request
+            this.services.forEach((service) => {
+                context.container?.set(service.id, service.value);
+            });
+        }
     }
 }
 exports.DependencyInjectionMiddleware = DependencyInjectionMiddleware;
@@ -166,6 +179,8 @@ exports.DependencyInjectionMiddleware = DependencyInjectionMiddleware;
  * Factory function that creates a dependency injection middleware.
  * Creates a new container instance for each request to avoid shared state issues.
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
  * @param services - Array of service definitions with id and value
  * @returns BaseMiddleware object with dependency injection logic
  *
@@ -254,12 +269,21 @@ exports.DependencyInjectionMiddleware = DependencyInjectionMiddleware;
  *   });
  * ```
  */
-const dependencyInjection = (services = []) => ({
+const dependencyInjection = (services = [], options) => ({
     before: async (context) => {
-        services.forEach((service) => {
-            typedi_1.Container.set(service.id, service.value);
-        });
-        context.container = typedi_1.Container.of();
+        const scope = options?.scope || 'local';
+        if (scope === 'global') {
+            // Register services globally (process-lifetime)
+            // ⚠️ Use sparingly - only for truly shared services like DB connections
+            containerPool_1.containerPool.initializeGlobal(services);
+        }
+        else {
+            // Register services locally (request-lifetime)
+            // ✅ Recommended for most use cases - isolated per request
+            services.forEach((service) => {
+                context.container?.set(service.id, service.value);
+            });
+        }
     },
 });
 exports.dependencyInjection = dependencyInjection;

package/build/middlewares/guards/adapters/CustomTokenVerificationPortAdapter.d.ts

@@ -245,7 +245,7 @@ export declare class TokenVerificationAdapterFactory {
      * @param expirationField - Optional field name for expiration (e.g., 'expiresAt', 'exp')
      * @returns Configured adapter for API key tokens
      */
-    static forAPIKey<T extends Record<string, any>>(verificationPort: CustomTokenVerificationPort<T>, userIdField: keyof T, expirationField?: keyof T): CustomTokenVerificationPortAdapter<T>;
+    static forAPIKey<T extends object>(verificationPort: CustomTokenVerificationPort<T>, userIdField: keyof T, expirationField?: keyof T): CustomTokenVerificationPortAdapter<T>;
     /**
      * Create adapter for OAuth tokens with standard OAuth claims.
      *

package/build/middlewares/guards/guards/FastAuthGuard.d.ts

@@ -43,7 +43,7 @@ export interface AuthenticationResult {
     success: boolean;
     user?: UserContext;
     token?: {
-        decoded: any;
+        decoded: unknown;
         raw: string;
         expiresAt: string;
         issuer?: string;
@@ -63,7 +63,7 @@ export interface AuthGuardConfig {
     allowedIssuers?: string[];
     requireEmailVerification: boolean;
     allowInactiveUsers: boolean;
-    customValidation?: (token: any, user: UserContext) => Promise<boolean>;
+    customValidation?: (token: unknown, user: UserContext) => Promise<boolean>;
 }
 /**
  * Token validation service interface
@@ -74,17 +74,17 @@ export interface TokenValidator {
      */
     validateToken(token: string): Promise<{
         valid: boolean;
-        decoded?: any;
+        decoded?: unknown;
         error?: string;
     }>;
     /**
      * Extract user ID from decoded token
      */
-    extractUserId(decoded: any): string;
+    extractUserId(decoded: unknown): string;
     /**
      * Check if token is expired
      */
-    isTokenExpired(decoded: any): boolean;
+    isTokenExpired(decoded: unknown): boolean;
 }
 /**
  * Fast Authentication Guard Implementation

package/build/middlewares/guards/guards/FastAuthGuard.js

@@ -215,14 +215,15 @@ let FastAuthGuard = class FastAuthGuard {
                 }
             }
             // Build successful authentication result
+            const decoded = tokenValidation.decoded;
             const authResult = {
                 success: true,
                 user: userContext,
                 token: {
                     decoded: tokenValidation.decoded,
                     raw: token,
-                    expiresAt: new Date(tokenValidation.decoded.exp * 1000).toISOString(),
-                    issuer: tokenValidation.decoded.iss,
+                    expiresAt: new Date(decoded.exp * 1000).toISOString(),
+                    issuer: decoded.iss,
                 },
                 cached: false,
                 resolutionTimeUs: Number(process.hrtime.bigint() - startTime) / 1000,

package/build/middlewares/guards/guards/PermissionGuardFactory.d.ts

@@ -162,16 +162,14 @@ export declare class PermissionGuardFactory {
     getStats(): {
         totalGuards: number;
         guardsByType: Record<string, number>;
-        individualGuardStats: {
-            guardType: string;
-            checkCount: number;
-            successCount: number;
-            failureCount: number;
-            successRate: number;
+        individualGuardStats: ReturnType<BasePermissionGuard['getStats']>[];
+        aggregatedStats: {
+            totalChecks: number;
+            totalSuccesses: number;
+            totalFailures: number;
+            overallSuccessRate: number;
             averageProcessingTimeUs: number;
-            totalProcessingTimeUs: number;
-        }[];
-        aggregatedStats: any;
+        };
     };
     /**
      * Clear guard cache

package/build/middlewares/guards/resolvers/ExpressionPermissionResolver.d.ts

@@ -118,7 +118,7 @@ export declare class ExpressionPermissionResolver extends PermissionResolver<Per
     /**
      * Check if this resolver can handle the given requirement type
      */
-    canHandle(requirement: any): requirement is PermissionExpression;
+    canHandle(requirement: unknown): requirement is PermissionExpression;
     /**
      * Normalize expression for consistent cache keys
      *

package/build/middlewares/guards/resolvers/ExpressionPermissionResolver.js

@@ -412,7 +412,7 @@ class ExpressionPermissionResolver extends PermissionResolver_1.PermissionResolv
      * Check if this resolver can handle the given requirement type
      */
     canHandle(requirement) {
-        return (requirement &&
+        return (!!requirement &&
             typeof requirement === 'object' &&
             PermissionResolver_1.PermissionUtils.isValidExpression(requirement));
     }

package/build/middlewares/guards/resolvers/PermissionResolver.d.ts

@@ -19,7 +19,7 @@
  * different types of permission requirements. The generic type T represents
  * the specific requirement format for each resolver.
  */
-export declare abstract class PermissionResolver<T = any> {
+export declare abstract class PermissionResolver<T = unknown> {
     /**
      * Check if user permissions satisfy the requirement
      *

package/build/middlewares/guards/resolvers/PlainPermissionResolver.d.ts

@@ -96,6 +96,6 @@ export declare class PlainPermissionResolver extends PermissionResolver<string[]
      * @param requirement - The requirement to check
      * @returns true if this resolver can handle the requirement
      */
-    canHandle(requirement: any): requirement is string[];
+    canHandle(requirement: unknown): requirement is string[];
 }
 //# sourceMappingURL=PlainPermissionResolver.d.ts.map

package/build/middlewares/guards/resolvers/WildcardPermissionResolver.d.ts

@@ -141,6 +141,6 @@ export declare class WildcardPermissionResolver extends PermissionResolver<strin
     /**
      * Check if this resolver can handle the given requirement type
      */
-    canHandle(requirement: any): requirement is string[];
+    canHandle(requirement: unknown): requirement is string[];
 }
 //# sourceMappingURL=WildcardPermissionResolver.d.ts.map

package/build/middlewares/guards/services/FastUserContextService.d.ts

@@ -23,7 +23,10 @@
  * @version 1.0.0
  */
 import { CacheAdapter } from '../cache/CacheAdapter';
-import { GuardConfiguration, PermissionResolutionStrategy } from '../config/GuardConfiguration';
+import { GuardConfiguration } from '../config/GuardConfiguration';
+import { PlainPermissionResolver } from '../resolvers/PlainPermissionResolver';
+import { WildcardPermissionResolver } from '../resolvers/WildcardPermissionResolver';
+import { ExpressionPermissionResolver } from '../resolvers/ExpressionPermissionResolver';
 import { PermissionRegistry } from '../registry/PermissionRegistry';
 import { PermissionResolverType, PermissionCheckResult, PermissionExpression } from '../resolvers/PermissionResolver';
 /**
@@ -38,7 +41,7 @@ export interface UserContext {
     userId: string;
     permissions: Set<string>;
     roles: string[];
-    metadata: Record<string, any>;
+    metadata: Record<string, unknown>;
     expandedPermissions?: Set<string>;
     lastUpdated: string;
     expiresAt?: string;
@@ -53,7 +56,7 @@ export interface UserPermissionSource {
     getUserPermissions(userId: string): Promise<{
         permissions: string[];
         roles: string[];
-        metadata?: Record<string, any>;
+        metadata?: Record<string, unknown>;
     } | null>;
     /**
      * Get role-based permissions for expansion
@@ -118,7 +121,7 @@ export declare class FastUserContextService {
      * @param options - Check options
      * @returns Detailed permission check result
      */
-    checkPermission(userId: string, requirement: any, options?: PermissionCheckOptions): Promise<PermissionCheckResult>;
+    checkPermission(userId: string, requirement: unknown, options?: PermissionCheckOptions): Promise<PermissionCheckResult>;
     /**
      * Batch check multiple permissions for a user
      *
@@ -131,7 +134,7 @@ export declare class FastUserContextService {
      * @returns Array of permission check results
      */
     checkPermissions(userId: string, requirements: Array<{
-        requirement: any;
+        requirement: unknown;
         resolverType?: PermissionResolverType;
     }>, options?: PermissionCheckOptions): Promise<PermissionCheckResult[]>;
     /**
@@ -166,33 +169,9 @@ export declare class FastUserContextService {
         averageResolutionTimeUs: number;
         totalResolutionTimeUs: number;
         resolverStats: {
-            plain: {
-                checkCount: number;
-                averageResolutionTimeUs: number;
-                totalResolutionTimeUs: number;
-            };
-            wildcard: {
-                strategy: PermissionResolutionStrategy;
-                checkCount: number;
-                averageResolutionTimeUs: number;
-                totalResolutionTimeUs: number;
-                cacheHitRate: number;
-                cacheHits: number;
-                cacheMisses: number;
-            };
-            expression: {
-                checkCount: number;
-                averageResolutionTimeUs: number;
-                totalResolutionTimeUs: number;
-                cacheHitRate: number;
-                cacheHits: number;
-                cacheMisses: number;
-                complexityDistribution: {
-                    simple: number;
-                    moderate: number;
-                    complex: number;
-                };
-            };
+            plain: ReturnType<PlainPermissionResolver['getStats']>;
+            wildcard: ReturnType<WildcardPermissionResolver['getStats']>;
+            expression: ReturnType<ExpressionPermissionResolver['getStats']>;
         };
     };
     /**

package/build/middlewares/headerVariablesMiddleware.d.ts

@@ -3,7 +3,9 @@ import { BaseMiddleware, Context } from '../core';
  * Middleware class that validates the presence of required HTTP headers.
  * Throws a ValidationError if any required header is missing or empty.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * API key authentication via headers:
@@ -63,15 +65,17 @@ import { BaseMiddleware, Context } from '../core';
  *   });
  * ```
  */
-export declare class HeaderVariablesMiddleware implements BaseMiddleware {
+export declare class HeaderVariablesMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
     private requiredHeaders;
     constructor(requiredHeaders: string[]);
-    before(context: Context): Promise<void>;
+    before(context: Context<TBody, TUser>): Promise<void>;
 }
 /**
  * Factory function that creates a header validation middleware.
  * Validates that all required headers are present in the request.
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
  * @param requiredHeaders - Array of header names that must be present
  * @returns BaseMiddleware object with header validation logic
  *
@@ -122,5 +126,5 @@ export declare class HeaderVariablesMiddleware implements BaseMiddleware {
  *   });
  * ```
  */
-export declare const headerVariablesMiddleware: (requiredHeaders: string[]) => BaseMiddleware;
+export declare const headerVariablesMiddleware: <TBody = unknown, TUser = unknown>(requiredHeaders: string[]) => BaseMiddleware<TBody, TUser>;
 //# sourceMappingURL=headerVariablesMiddleware.d.ts.map

package/build/middlewares/headerVariablesMiddleware.js

@@ -15,7 +15,9 @@ const validateHeaders = (requiredHeaders, headers) => {
  * Middleware class that validates the presence of required HTTP headers.
  * Throws a ValidationError if any required header is missing or empty.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * API key authentication via headers:
@@ -90,6 +92,8 @@ exports.HeaderVariablesMiddleware = HeaderVariablesMiddleware;
  * Factory function that creates a header validation middleware.
  * Validates that all required headers are present in the request.
  *
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
  * @param requiredHeaders - Array of header names that must be present
  * @returns BaseMiddleware object with header validation logic
  *

package/build/middlewares/httpAttributesMiddleware.d.ts

@@ -5,7 +5,9 @@ import { ZodSchema } from 'zod';
  * Middleware class that extracts path parameters from the URL.
  * Parses URL segments and extracts parameters based on colon-prefixed patterns.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * Basic path parameter extraction:
@@ -56,8 +58,8 @@ import { ZodSchema } from 'zod';
  *   });
  * ```
  */
-export declare class PathParametersMiddleware implements BaseMiddleware {
-    before(context: Context): Promise<void>;
+export declare class PathParametersMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
+    before(context: Context<TBody, TUser>): Promise<void>;
 }
 /**
  * Factory function that creates a path parameters extraction middleware.

package/build/middlewares/httpAttributesMiddleware.js

@@ -7,7 +7,9 @@ const zod_1 = require("zod");
  * Middleware class that extracts path parameters from the URL.
  * Parses URL segments and extracts parameters based on colon-prefixed patterns.
  *
- * @implements {BaseMiddleware}
+ * @template TBody - The type of the request body payload (preserves type chain)
+ * @template TUser - The type of the authenticated user (preserves type chain)
+ * @implements {BaseMiddleware<TBody, TUser>}
  *
  * @example
  * Basic path parameter extraction:

package/build/middlewares/index.d.ts

@@ -5,6 +5,7 @@ export * from './dependencyInjectionMiddleware';
 export * from './errorHandlerMiddleware';
 export * from './headerVariablesMiddleware';
 export * from './httpAttributesMiddleware';
+export * from './openTelemetryMiddleware';
 export * from './queryParametersMiddleware';
 export * from './rateLimitingMiddleware';
 export * from './responseWrapperMiddleware';

package/build/middlewares/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./dependencyInjectionMiddleware"), exports);
 __exportStar(require("./errorHandlerMiddleware"), exports);
 __exportStar(require("./headerVariablesMiddleware"), exports);
 __exportStar(require("./httpAttributesMiddleware"), exports);
+__exportStar(require("./openTelemetryMiddleware"), exports);
 __exportStar(require("./queryParametersMiddleware"), exports);
 __exportStar(require("./rateLimitingMiddleware"), exports);
 __exportStar(require("./responseWrapperMiddleware"), exports);

package/build/middlewares/openTelemetryMiddleware.d.ts

@@ -0,0 +1,162 @@
+import { BaseMiddleware, Context } from '../core';
+import { TelemetryProvider, TelemetryConfig } from '../core/telemetry/provider';
+/**
+ * OpenTelemetry Middleware Options
+ */
+export interface OpenTelemetryOptions {
+    /**
+     * Telemetry provider (auto-detects if not provided)
+     * @default Auto-detected based on environment variables
+     */
+    provider?: TelemetryProvider;
+    /**
+     * Enable telemetry
+     * @default true for production, false for NODE_ENV=test
+     */
+    enabled?: boolean;
+    /**
+     * Extract custom attributes from context
+     * @default Extracts http.method, http.url, request.id, http.user_agent
+     */
+    extractAttributes?: (context: Context<unknown, unknown>) => Record<string, unknown>;
+    /**
+     * Filter which requests to trace
+     * @default Traces all requests
+     *
+     * @example
+     * shouldTrace: (context) => context.req.path !== '/health'
+     */
+    shouldTrace?: (context: Context<unknown, unknown>) => boolean;
+    /**
+     * Custom error handler for telemetry errors
+     * @default Logs error to console
+     */
+    onError?: (error: Error, context: Context<unknown, unknown>) => void;
+    /**
+     * Fail silently on telemetry errors (never throw)
+     * @default true (telemetry errors never break application)
+     */
+    failSilently?: boolean;
+    /**
+     * Enable trace context propagation for Google Cloud Pub/Sub messages
+     *
+     * When enabled:
+     * - Extracts W3C Trace Context from incoming Pub/Sub message attributes
+     * - Links new spans to parent trace from publisher
+     * - Allows distributed tracing across Pub/Sub producers and consumers
+     *
+     * Trace context is stored in message attributes as:
+     * - `traceparent`: W3C Trace Context version-traceid-spanid-flags
+     * - `tracestate`: Vendor-specific trace state (optional)
+     *
+     * @default true
+     */
+    propagatePubSubTraces?: boolean;
+}
+/**
+ * OpenTelemetry Middleware
+ *
+ * Provides distributed tracing and metrics collection with:
+ * - Auto-detection of telemetry provider from environment
+ * - Graceful degradation when configuration is missing
+ * - Zero-configuration local development support
+ * - Type-safe generics to preserve middleware chain
+ *
+ * Provider Auto-Detection Priority:
+ * 1. Explicit provider via options.provider
+ * 2. New Relic (if NEW_RELIC_LICENSE_KEY set)
+ * 3. Datadog (if DD_API_KEY or DD_SERVICE set)
+ * 4. Standard OTEL (if OTEL_EXPORTER_OTLP_ENDPOINT set)
+ * 5. Console (if NODE_ENV=development and no OTEL endpoint)
+ * 6. Noop (if NODE_ENV=test or no configuration)
+ *
+ * @template TBody - Request body type
+ * @template TUser - Authenticated user type
+ *
+ * @example
+ * // Zero configuration (auto-detects provider)
+ * const handler = new Handler()
+ *   .use(new OpenTelemetryMiddleware())
+ *   .handle(async (context) => {
+ *     // Your business logic
+ *   });
+ *
+ * @example
+ * // With custom filtering
+ * const handler = new Handler()
+ *   .use(new OpenTelemetryMiddleware({
+ *     shouldTrace: (context) => context.req.path !== '/health'
+ *   }))
+ *   .handle(async (context) => {
+ *     // Your business logic
+ *   });
+ */
+export declare class OpenTelemetryMiddleware<TBody = unknown, TUser = unknown> implements BaseMiddleware<TBody, TUser> {
+    private provider;
+    private enabled;
+    private failSilently;
+    private propagatePubSubTraces;
+    private extractAttributes;
+    private shouldTrace;
+    private customErrorHandler;
+    private initialized;
+    constructor(options?: OpenTelemetryOptions);
+    /**
+     * Auto-detect telemetry provider based on environment
+     */
+    private autoDetectProvider;
+    /**
+     * Initialize provider with configuration
+     *
+     * This should be called once at application startup.
+     * If not called explicitly, it will be initialized on first request.
+     *
+     * @param config Telemetry configuration
+     */
+    initialize(config: TelemetryConfig): Promise<void>;
+    /**
+     * Before hook - Create span and store in context
+     *
+     * If propagatePubSubTraces is enabled and the request is a Pub/Sub message:
+     * 1. Extracts W3C Trace Context from message attributes
+     * 2. Creates a child span linked to the publisher's trace
+     * 3. Enables end-to-end distributed tracing across Pub/Sub
+     */
+    before(context: Context<TBody, TUser>): Promise<void>;
+    /**
+     * After hook - End span with success status and add X-Trace-Id header
+     */
+    after(context: Context<TBody, TUser>): Promise<void>;
+    /**
+     * Error hook - Record exception and end span
+     */
+    onError(error: Error, context: Context<TBody, TUser>): Promise<void>;
+    /**
+     * Default attribute extractor
+     */
+    private defaultExtractAttributes;
+    /**
+     * Default error handler
+     */
+    private defaultOnError;
+    /**
+     * Get current provider (useful for testing)
+     */
+    getProvider(): TelemetryProvider;
+    /**
+     * Shutdown telemetry provider
+     *
+     * Should be called during application shutdown to flush pending data.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Factory function for OpenTelemetry middleware
+ *
+ * @example
+ * const handler = new Handler()
+ *   .use(openTelemetry({ shouldTrace: ctx => ctx.req.path !== '/health' }))
+ *   .handle(async (context) => { });
+ */
+export declare const openTelemetry: <TBody = unknown, TUser = unknown>(options?: OpenTelemetryOptions) => OpenTelemetryMiddleware<TBody, TUser>;
+//# sourceMappingURL=openTelemetryMiddleware.d.ts.map