@naman_deep_singh/communication-core 1.0.0

package/dist/types/interfaces/Interceptor.interface.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Interceptor interface for communication layer
+ * @packageDocumentation
+ */
+import type { CommunicationError } from '../errors/CommunicationError.js';
+import type { InterceptorEvent } from '../types/events.js';
+import type { Request, RequestContext } from '../types/request.js';
+import type { Response } from '../types/response.js';
+/**
+ * Interceptor execution order
+ */
+export interface InterceptorOrder {
+    /** Phase order within request phase */
+    request?: number;
+    /** Phase order within response phase */
+    response?: number;
+    /** Phase order within error phase */
+    error?: number;
+}
+/**
+ * Interceptor interface for intercepting and modifying requests/responses
+ */
+export interface IInterceptor<TRequest = Request, TResponse = Response> {
+    /** Interceptor name */
+    readonly name: string;
+    /** Interceptor version */
+    readonly version?: string;
+    /** Interceptor description */
+    readonly description?: string;
+    /** Whether interceptor is enabled */
+    enabled: boolean;
+    /** Interceptor execution order */
+    readonly order: InterceptorOrder;
+    /**
+     * Intercept request before it's sent
+     * @param request Original request
+     * @param context Request context
+     * @returns Modified request or void
+     */
+    onRequest?(request: TRequest, context: RequestContext): TRequest | void | Promise<TRequest | void>;
+    /**
+     * Intercept response after it's received
+     * @param response Original response
+     * @param context Request context
+     * @returns Modified response or void
+     */
+    onResponse?(response: TResponse, context: RequestContext): TResponse | void | Promise<TResponse | void>;
+    /**
+     * Intercept error when request fails
+     * @param error Error that occurred
+     * @param context Request context
+     * @returns Modified error, new response, or void
+     */
+    onError?(error: CommunicationError, context: RequestContext): CommunicationError | TResponse | void | Promise<CommunicationError | TResponse | void>;
+    /**
+     * Initialize interceptor (called when added to client/protocol)
+     * @param options Initialization options
+     */
+    initialize?(options?: Record<string, unknown>): void | Promise<void>;
+    /**
+     * Cleanup interceptor (called when removed from client/protocol)
+     */
+    cleanup?(): void | Promise<void>;
+    /**
+     * Get interceptor configuration
+     */
+    getConfig(): Record<string, unknown>;
+    /**
+     * Update interceptor configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Record<string, unknown>): void;
+    /**
+     * Health check for the interceptor
+     */
+    healthCheck?(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Get interceptor statistics
+     */
+    getStats?(): {
+        totalRequests: number;
+        totalResponses: number;
+        totalErrors: number;
+        modifications: number;
+        averageProcessingTime: number;
+        lastError?: string;
+    };
+    /**
+     * Reset interceptor statistics
+     */
+    resetStats?(): void;
+    /**
+     * Event emitter for interceptor events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to interceptor events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        on(event: string | string[], listener: (event: InterceptorEvent) => void): void;
+        /**
+         * Unsubscribe from interceptor events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        off(event: string | string[], listener: (event: InterceptorEvent) => void): void;
+    };
+}
+/**
+ * Interceptor chain interface for managing multiple interceptors
+ */
+export interface IInterceptorChain<TRequest = Request, TResponse = Response> {
+    /** Chain name */
+    readonly name: string;
+    /** All interceptors in the chain */
+    readonly interceptors: IInterceptor<TRequest, TResponse>[];
+    /**
+     * Add an interceptor to the chain
+     * @param interceptor Interceptor to add
+     */
+    add(interceptor: IInterceptor<TRequest, TResponse>): void;
+    /**
+     * Remove an interceptor from the chain
+     * @param interceptorName Interceptor name to remove
+     */
+    remove(interceptorName: string): boolean;
+    /**
+     * Get an interceptor by name
+     * @param interceptorName Interceptor name
+     */
+    get(interceptorName: string): IInterceptor<TRequest, TResponse> | undefined;
+    /**
+     * Clear all interceptors from the chain
+     */
+    clear(): void;
+    /**
+     * Execute request interceptors
+     * @param request Original request
+     * @param context Request context
+     * @returns Modified request
+     */
+    executeRequest(request: TRequest, context: RequestContext): Promise<TRequest>;
+    /**
+     * Execute response interceptors
+     * @param response Original response
+     * @param context Request context
+     * @returns Modified response
+     */
+    executeResponse(response: TResponse, context: RequestContext): Promise<TResponse>;
+    /**
+     * Execute error interceptors
+     * @param error Original error
+     * @param context Request context
+     * @returns Modified error or response
+     */
+    executeError(error: CommunicationError, context: RequestContext): Promise<CommunicationError | TResponse>;
+    /**
+     * Sort interceptors by execution order
+     */
+    sortInterceptors(): void;
+    /**
+     * Health check for the interceptor chain
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: {
+            totalInterceptors: number;
+            enabledInterceptors: number;
+            interceptorHealth: Array<{
+                name: string;
+                healthy: boolean;
+                message?: string;
+            }>;
+        };
+    };
+}
+/**
+ * Interceptor factory interface
+ */
+export interface IInterceptorFactory {
+    /**
+     * Create a new interceptor instance
+     * @param name Interceptor name
+     * @param options Interceptor options
+     * @returns New interceptor instance
+     */
+    create(name: string, options?: Record<string, unknown>): IInterceptor;
+    /**
+     * Get an existing interceptor instance
+     * @param name Interceptor name
+     */
+    get(name: string): IInterceptor | undefined;
+    /**
+     * Get all interceptor instances
+     */
+    getAll(): IInterceptor[];
+    /**
+     * Register a custom interceptor
+     * @param name Interceptor name
+     * @param interceptor Interceptor instance or constructor
+     */
+    register(name: string, interceptor: IInterceptor | (new (options: Record<string, unknown>) => IInterceptor)): void;
+    /**
+     * Get available interceptor names
+     */
+    getAvailableInterceptors(): string[];
+    /**
+     * Create an interceptor chain
+     * @param name Chain name
+     * @param interceptors Initial interceptors
+     * @returns New interceptor chain
+     */
+    createChain(name: string, interceptors?: IInterceptor[]): IInterceptorChain;
+}

package/dist/types/interfaces/LoadBalancer.interface.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Load balancer interface for communication layer
+ * @packageDocumentation
+ */
+import type { LoadBalancingConfig } from '../types/config.js';
+import type { LoadBalancingEvent } from '../types/events.js';
+import type { ServiceInstance } from '../types/service.js';
+/**
+ * Load balancing strategy interface for selecting service instances
+ */
+export interface ILoadBalanceStrategy {
+    /** Strategy name */
+    readonly name: string;
+    /** Strategy configuration */
+    readonly config: LoadBalancingConfig;
+    /** Total selections made */
+    readonly totalSelections: number;
+    /** Last selection timestamp */
+    readonly lastSelectionTime?: number;
+    /**
+     * Select a service instance from available instances
+     * @param instances Available service instances
+     * @param context Selection context
+     * @returns Selected service instance
+     * @throws {CommunicationError} If no instances available
+     */
+    select(instances: ServiceInstance[], context?: Record<string, unknown>): ServiceInstance;
+    /**
+     * Select multiple service instances
+     * @param instances Available service instances
+     * @param count Number of instances to select
+     * @param context Selection context
+     * @returns Selected service instances
+     */
+    selectMultiple(instances: ServiceInstance[], count: number, context?: Record<string, unknown>): ServiceInstance[];
+    /**
+     * Update instance statistics (for adaptive strategies)
+     * @param instance Service instance
+     * @param success Whether the request was successful
+     * @param responseTime Response time in milliseconds
+     */
+    updateStats(instance: ServiceInstance, success: boolean, responseTime?: number): void;
+    /**
+     * Reset instance statistics
+     * @param instanceId Optional instance ID to reset, or reset all
+     */
+    resetStats(instanceId?: string): void;
+    /**
+     * Get instance statistics
+     * @param instanceId Optional instance ID to get stats for
+     */
+    getStats(instanceId?: string): Record<string, unknown>;
+    /**
+     * Check if an instance is currently eligible for selection
+     * @param instance Service instance to check
+     */
+    isEligible(instance: ServiceInstance): boolean;
+    /**
+     * Filter instances based on eligibility
+     * @param instances Instances to filter
+     */
+    filterEligible(instances: ServiceInstance[]): ServiceInstance[];
+    /**
+     * Sort instances by selection priority
+     * @param instances Instances to sort
+     */
+    sortByPriority(instances: ServiceInstance[]): ServiceInstance[];
+    /**
+     * Update load balancer configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<LoadBalancingConfig>): void;
+    /**
+     * Get load balancer statistics
+     */
+    getStrategyStats(): {
+        totalSelections: number;
+        successfulSelections: number;
+        failedSelections: number;
+        averageSelectionTime: number;
+        instanceStats: Record<string, {
+            selections: number;
+            successes: number;
+            failures: number;
+            averageResponseTime?: number;
+        }>;
+    };
+    /**
+     * Reset load balancer statistics
+     */
+    resetStrategyStats(): void;
+    /**
+     * Health check for the load balancer
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Event emitter for load balancing events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to load balancing events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        on(event: string | string[], listener: (event: LoadBalancingEvent) => void): void;
+        /**
+         * Unsubscribe from load balancing events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        off(event: string | string[], listener: (event: LoadBalancingEvent) => void): void;
+    };
+}
+/**
+ * Load balancer factory interface
+ */
+export interface ILoadBalancerFactory {
+    /**
+     * Create a new load balancer instance
+     * @param name Load balancer name
+     * @param strategy Load balancing strategy
+     * @param config Load balancer configuration
+     * @returns New load balancer instance
+     */
+    create(name: string, strategy: string, config?: Partial<LoadBalancingConfig>): ILoadBalanceStrategy;
+    /**
+     * Get an existing load balancer instance
+     * @param name Load balancer name
+     */
+    get(name: string): ILoadBalanceStrategy | undefined;
+    /**
+     * Get all load balancer instances
+     */
+    getAll(): ILoadBalanceStrategy[];
+    /**
+     * Register a custom load balancing strategy
+     * @param name Strategy name
+     * @param strategy Strategy instance or constructor
+     */
+    register(name: string, strategy: ILoadBalanceStrategy | (new (config: LoadBalancingConfig) => ILoadBalanceStrategy)): void;
+    /**
+     * Get available load balancing strategies
+     */
+    getAvailableStrategies(): string[];
+    /**
+     * Close all load balancer instances
+     */
+    closeAll(): Promise<void>;
+}

package/dist/types/interfaces/Protocol.interface.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Protocol interface for communication layer
+ * @packageDocumentation
+ */
+import type { BaseProtocolConfig } from '../types/config.js';
+import type { Request } from '../types/request.js';
+import type { Response } from '../types/response.js';
+import type { IInterceptor } from './Interceptor.interface.js';
+/**
+ * Protocol interface for all communication protocols
+ * This is the base contract that all protocols must implement
+ */
+export interface IProtocol<TRequest = Request, TResponse = Response> {
+    /** Protocol name identifier */
+    readonly name: string;
+    /** Protocol version */
+    readonly version?: string;
+    /** Protocol configuration */
+    readonly config: BaseProtocolConfig;
+    /**
+     * Send a request using this protocol
+     * @param request The request to send
+     * @returns Promise resolving to the response
+     * @throws {CommunicationError} If the request fails
+     */
+    send(request: TRequest): Promise<TResponse>;
+    /**
+     * Configure the protocol with new settings
+     * @param config Configuration object
+     */
+    configure(config: Partial<BaseProtocolConfig>): void;
+    /**
+     * Connect to the service (for stateful protocols)
+     * @returns Promise that resolves when connected
+     */
+    connect?(): Promise<void>;
+    /**
+     * Disconnect from the service (for stateful protocols)
+     * @returns Promise that resolves when disconnected
+     */
+    disconnect?(): Promise<void>;
+    /**
+     * Check if the protocol is currently connected
+     * @returns True if connected, false otherwise
+     */
+    isConnected?(): boolean;
+    /**
+     * Add an interceptor to the protocol
+     * @param interceptor Interceptor to add
+     */
+    addInterceptor?(interceptor: IInterceptor<TRequest, TResponse>): void;
+    /**
+     * Remove an interceptor from the protocol
+     * @param interceptorId Interceptor identifier
+     */
+    removeInterceptor?(interceptorId: string): void;
+    /**
+     * Get all interceptors
+     */
+    getInterceptors?(): IInterceptor<TRequest, TResponse>[];
+    /**
+     * Event emitter for protocol events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to protocol events
+         * @param event Event name
+         * @param listener Event listener
+         */
+        on(event: string, listener: (data: any) => void): void;
+        /**
+         * Unsubscribe from protocol events
+         * @param event Event name
+         * @param listener Event listener
+         */
+        off(event: string, listener: (data: any) => void): void;
+    };
+    /**
+     * Get protocol metrics
+     */
+    getMetrics?(): Record<string, unknown>;
+    /**
+     * Reset protocol metrics
+     */
+    resetMetrics?(): void;
+    /**
+     * Health check for the protocol
+     * @returns Promise resolving to health status
+     */
+    healthCheck?(): Promise<{
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Protocol factory interface for creating protocol instances
+ */
+export interface IProtocolFactory {
+    /**
+     * Create a new protocol instance
+     * @param config Protocol configuration
+     * @returns New protocol instance
+     */
+    create(config: BaseProtocolConfig): IProtocol;
+    /**
+     * Register a protocol implementation
+     * @param name Protocol name
+     * @param constructor Protocol constructor
+     */
+    register?(name: string, constructor: new (config: BaseProtocolConfig) => IProtocol): void;
+    /**
+     * Get available protocol names
+     * @returns Array of protocol names
+     */
+    getAvailableProtocols?(): string[];
+}

package/dist/types/interfaces/RetryStrategy.interface.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Retry strategy interface for communication layer
+ * @packageDocumentation
+ */
+import type { CommunicationError } from '../errors/CommunicationError.js';
+import type { RetryPolicyConfig } from '../types/config.js';
+import type { RetryEvent } from '../types/events.js';
+/**
+ * Retry decision result
+ */
+export interface RetryDecision {
+    /** Whether to retry */
+    shouldRetry: boolean;
+    /** Delay before next retry in milliseconds */
+    delay?: number;
+    /** Reason for decision */
+    reason?: string;
+}
+/**
+ * Retry context for each attempt
+ */
+export interface RetryContext {
+    /** Current attempt number (starting from 1) */
+    attempt: number;
+    /** Maximum allowed attempts */
+    maxAttempts: number;
+    /** Last error that occurred */
+    lastError?: CommunicationError;
+    /** Start time of first attempt */
+    startTime: number;
+    /** Total elapsed time in milliseconds */
+    elapsedTime: number;
+    /** ✅ ADD THIS: Is this a retry attempt? */
+    isRetry: boolean;
+    /** Custom context data */
+    data?: Map<string, unknown>;
+}
+/**
+ * Retry strategy interface for handling retry logic
+ */
+export interface IRetryStrategy {
+    /** Strategy name */
+    readonly name: string;
+    /** Strategy configuration */
+    readonly config: RetryPolicyConfig;
+    /** Total retry attempts made */
+    readonly totalAttempts: number;
+    /** Successful retries */
+    readonly successfulRetries: number;
+    /** Failed retries */
+    readonly failedRetries: number;
+    /**
+     * Execute a function with retry logic
+     * @param fn Function to execute
+     * @param context Initial retry context
+     * @returns Promise resolving to function result
+     * @throws {CommunicationError} If all retry attempts fail
+     */
+    execute<T>(fn: () => Promise<T>, context?: Partial<RetryContext>): Promise<T>;
+    /**
+     * Execute a function with retry logic and custom decision function
+     * @param fn Function to execute
+     * @param shouldRetry Custom retry decision function
+     * @param context Initial retry context
+     * @returns Promise resolving to function result
+     */
+    executeWithDecision<T>(fn: () => Promise<T>, shouldRetry: (error: CommunicationError, context: RetryContext) => RetryDecision, context?: Partial<RetryContext>): Promise<T>;
+    /**
+     * Determine if a retry should be attempted
+     * @param error Error that occurred
+     * @param context Current retry context
+     * @returns Retry decision
+     */
+    shouldRetry(error: CommunicationError, context: RetryContext): RetryDecision;
+    /**
+     * Calculate delay for next retry attempt
+     * @param attempt Current attempt number
+     * @param context Current retry context
+     * @returns Delay in milliseconds
+     */
+    calculateDelay(attempt: number, context: RetryContext): number;
+    /**
+     * Update retry strategy configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<RetryPolicyConfig>): void;
+    /**
+     * Get retry strategy statistics
+     */
+    getStats(): {
+        totalExecutions: number;
+        totalAttempts: number;
+        successfulRetries: number;
+        failedRetries: number;
+        successRate: number;
+        averageAttempts: number;
+        averageDelay: number;
+        totalTimeSpent: number;
+    };
+    /**
+     * Reset retry strategy statistics
+     */
+    resetStats(): void;
+    /**
+     * Health check for the retry strategy
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Event emitter for retry events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to retry events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        on(event: string | string[], listener: (event: RetryEvent) => void): void;
+        /**
+         * Unsubscribe from retry events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        off(event: string | string[], listener: (event: RetryEvent) => void): void;
+    };
+}
+/**
+ * Retry strategy factory interface
+ */
+export interface IRetryStrategyFactory {
+    /**
+     * Create a new retry strategy instance
+     * @param name Strategy name
+     * @param config Strategy configuration
+     * @returns New retry strategy instance
+     */
+    create(name: string, config?: Partial<RetryPolicyConfig>): IRetryStrategy;
+    /**
+     * Get an existing retry strategy instance
+     * @param name Strategy name
+     */
+    get(name: string): IRetryStrategy | undefined;
+    /**
+     * Get all retry strategy instances
+     */
+    getAll(): IRetryStrategy[];
+    /**
+     * Register a custom retry strategy
+     * @param name Strategy name
+     * @param strategy Strategy instance or constructor
+     */
+    register(name: string, strategy: IRetryStrategy | (new (config: RetryPolicyConfig) => IRetryStrategy)): void;
+    /**
+     * Get available retry strategy names
+     */
+    getAvailableStrategies(): string[];
+}