@naman_deep_singh/communication-core 1.0.0

package/dist/types/abstract/BaseLoadBalancer.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Abstract base load balancer implementation
+ * @packageDocumentation
+ */
+import type { ILoadBalanceStrategy } from '../interfaces/LoadBalancer.interface.js';
+import type { LoadBalancerSelection } from '../types/config.js';
+import type { LoadBalancingConfig } from '../types/config.js';
+import type { ServiceInstance } from '../types/service.js';
+/**
+ * Abstract base load balancer implementation
+ * Provides common functionality for all load balancing strategy implementations
+ */
+export declare abstract class BaseLoadBalancer implements ILoadBalanceStrategy {
+    /** Strategy name */
+    readonly name: string;
+    /** Strategy configuration */
+    config: LoadBalancingConfig;
+    /** Total selections made */
+    totalSelections: number;
+    /** Last selection timestamp */
+    lastSelectionTime?: number;
+    /** Instance statistics */
+    protected instanceStats: Map<string, {
+        selections: number;
+        successes: number;
+        failures: number;
+        totalResponseTime: number;
+        averageResponseTime?: number;
+        lastSelected?: number;
+    }>;
+    /** Load balancer statistics */
+    protected stats: {
+        totalSelections: number;
+        successfulSelections: number;
+        failedSelections: number;
+        averageSelectionTime: number;
+        instanceStats: Record<string, {
+            selections: number;
+            successes: number;
+            failures: number;
+            averageResponseTime?: number;
+        }>;
+    };
+    /**
+     * Create a new base load balancer instance
+     * @param name Load balancer name
+     * @param config Load balancer configuration
+     */
+    constructor(name: string, config: LoadBalancingConfig);
+    /**
+     * Initialize load balancer
+     */
+    protected initialize(): void;
+    /**
+     * 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
+     */
+    abstract 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;
+    /**
+     * Update aggregate statistics
+     * @param instanceId Instance ID
+     * @param instanceStats Instance statistics
+     */
+    protected updateAggregateStats(instanceId: string, instanceStats: {
+        selections: number;
+        successes: number;
+        failures: number;
+        totalResponseTime: number;
+        averageResponseTime?: number;
+        lastSelected?: 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[];
+    /**
+     * Get instance weight
+     * @param instance Service instance
+     * @returns Instance weight
+     */
+    protected getInstanceWeight(instance: ServiceInstance): number;
+    /**
+     * Record selection
+     * @param instance Selected instance
+     * @param selectionTime Selection time in milliseconds
+     */
+    protected recordSelection(instance: ServiceInstance, selectionTime: number): void;
+    /**
+     * Create selection result
+     * @param instance Selected instance
+     * @param instances Available instances
+     * @param selectionTime Selection time in milliseconds
+     * @returns Selection result
+     */
+    protected createSelectionResult(instance: ServiceInstance, instances: ServiceInstance[], selectionTime: number): LoadBalancerSelection;
+    /**
+     * 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>;
+    };
+}

package/dist/types/abstract/BaseProtocol.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Abstract base protocol implementation
+ * @packageDocumentation
+ */
+import { type CommunicationErrorType } from '../errors/CommunicationError.js';
+import type { Request } from '../types/request.js';
+import type { BaseProtocolConfig } from '../types/config.js';
+import type { IProtocol } from '../interfaces/Protocol.interface.js';
+import type { IInterceptor } from '../interfaces/Interceptor.interface.js';
+import type { Response } from '../types/response.js';
+/**
+ * Abstract base protocol implementation
+ * Provides common functionality for all protocol implementations
+ */
+export declare abstract class BaseProtocol<TRequest = Request, TResponse = Response> implements IProtocol<TRequest, TResponse> {
+    /** Protocol name identifier */
+    readonly name: string;
+    /** Protocol version */
+    readonly version?: string;
+    /** Protocol configuration */
+    config: BaseProtocolConfig;
+    /** Protocol interceptors */
+    protected interceptors: IInterceptor<TRequest, TResponse>[];
+    /** Protocol metrics */
+    protected metrics: Record<string, unknown>;
+    /** Whether protocol is connected (for stateful protocols) */
+    protected connected: boolean;
+    /** Protocol start time */
+    protected readonly startTime: number;
+    /** Total requests sent */
+    protected totalRequests: number;
+    /** Total successful requests */
+    protected successfulRequests: number;
+    /** Total failed requests */
+    protected failedRequests: number;
+    /**
+     * Create a new base protocol instance
+     * @param name Protocol name
+     * @param config Protocol configuration
+     */
+    constructor(name: string, 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
+     */
+    abstract send(request: TRequest): Promise<TResponse>;
+    /**
+     * Configure the protocol with new settings
+     * @param config Configuration object
+     */
+    configure(config: Partial<BaseProtocolConfig>): void;
+    /**
+     * Hook for protocol configuration changes
+     * @param newConfig New configuration
+     */
+    protected onConfigure(newConfig: Partial<BaseProtocolConfig>): void;
+    /**
+     * Connect to the service (for stateful protocols)
+     * @returns Promise that resolves when connected
+     */
+    connect(): Promise<void>;
+    /**
+     * Hook for connection logic
+     */
+    protected onConnect?(): Promise<void>;
+    /**
+     * Disconnect from the service (for stateful protocols)
+     * @returns Promise that resolves when disconnected
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Hook for disconnection logic
+     */
+    protected onDisconnect?(): 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;
+    /**
+     * Hook for interceptor addition
+     * @param interceptor Added interceptor
+     */
+    protected onInterceptorAdded(interceptor: IInterceptor<TRequest, TResponse>): void;
+    /**
+     * Remove an interceptor from the protocol
+     * @param interceptorId Interceptor identifier
+     */
+    removeInterceptor(interceptorId: string): void;
+    /**
+     * Hook for interceptor removal
+     * @param interceptorId Removed interceptor ID
+     */
+    protected onInterceptorRemoved(interceptorId: string): void;
+    /**
+     * Get all interceptors
+     */
+    getInterceptors(): IInterceptor<TRequest, TResponse>[];
+    /**
+     * Execute request interceptors
+     * @param request Original request
+     * @param context Request context
+     * @returns Modified request
+     */
+    protected executeRequestInterceptors(request: TRequest, context: any): Promise<TRequest>;
+    /**
+     * Execute response interceptors
+     * @param response Original response
+     * @param context Request context
+     * @returns Modified response
+     */
+    protected executeResponseInterceptors(response: TResponse, context: any): Promise<TResponse>;
+    /**
+     * Execute error interceptors
+     * @param error Original error
+     * @param context Request context
+     * @returns Modified error or response
+     */
+    protected executeErrorInterceptors(error: CommunicationErrorType, context: any): Promise<CommunicationErrorType | TResponse>;
+    /**
+     * Update request metrics
+     * @param success Whether request was successful
+     * @param duration Request duration in milliseconds
+     */
+    protected updateMetrics(success: boolean, duration: number): void;
+    /**
+     * Calculate average response time
+     * @param newDuration New request duration
+     * @returns Average response time
+     */
+    private calculateAverageResponseTime;
+    /**
+     * 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>;
+    }>;
+    /**
+     * Create request context
+     * @param request Request object
+     * @param attempt Attempt number
+     * @returns Request context
+     */
+    protected createRequestContext(request: TRequest, attempt?: number): any;
+}

package/dist/types/abstract/BaseRetryStrategy.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Abstract base retry strategy implementation
+ * @packageDocumentation
+ */
+import type { CommunicationErrorType } from '../errors/CommunicationError.js';
+import type { IRetryStrategy, RetryContext, RetryDecision } from '../interfaces/RetryStrategy.interface.js';
+import type { RetryPolicyConfig } from '../types/config.js';
+/**
+ * Abstract base retry strategy implementation
+ * Provides common functionality for all retry strategy implementations
+ */
+export declare abstract class BaseRetryStrategy implements IRetryStrategy {
+    /** Strategy name */
+    readonly name: string;
+    /** Strategy configuration */
+    config: RetryPolicyConfig;
+    /** Total retry attempts made */
+    totalAttempts: number;
+    /** Successful retries */
+    successfulRetries: number;
+    /** Failed retries */
+    failedRetries: number;
+    /** Retry statistics */
+    protected stats: {
+        totalExecutions: number;
+        totalAttempts: number;
+        successfulRetries: number;
+        failedRetries: number;
+        successRate: number;
+        averageAttempts: number;
+        averageDelay: number;
+        totalTimeSpent: number;
+    };
+    /**
+     * Create a new base retry strategy instance
+     * @param name Strategy name
+     * @param config Strategy configuration
+     */
+    constructor(name: string, config: RetryPolicyConfig);
+    /**
+     * Initialize retry strategy
+     */
+    protected initialize(): void;
+    /**
+     * 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
+     */
+    abstract 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
+     */
+    abstract executeWithDecision<T>(fn: () => Promise<T>, shouldRetry: (error: CommunicationErrorType, 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: CommunicationErrorType, context: RetryContext): RetryDecision;
+    /**
+     * Check if an error is retryable
+     * @param error Error to check
+     * @returns True if error is retryable
+     */
+    protected isRetryableError(error: CommunicationErrorType): boolean;
+    /**
+     * 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;
+    /**
+     * Create retry context
+     * @param initialContext Initial context values
+     * @returns Complete retry context
+     */
+    protected createRetryContext(initialContext?: Partial<RetryContext>): RetryContext;
+    /**
+     * Update retry context after attempt
+     * @param context Current context
+     * @param error Error from attempt (if any)
+     * @returns Updated context
+     */
+    protected updateRetryContext(context: RetryContext, error?: CommunicationErrorType): RetryContext;
+    /**
+     * Update retry statistics
+     * @param success Whether retry was successful
+     * @param attempts Number of attempts
+     * @param totalDelay Total delay time
+     */
+    protected updateStats(success: boolean, attempts: number, totalDelay: number): void;
+    /**
+     * 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>;
+    };
+}

package/dist/types/abstract/BaseSerializer.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Abstract base serializer implementation
+ * @packageDocumentation
+ */
+import type { DeserializationContext, ISerializer, SerializationContext } from '../interfaces/Serializer.interface.js';
+import type { SerializationConfig, SerializationFormat } from '../types/config.js';
+/**
+ * Abstract base serializer implementation
+ * Provides common functionality for all serializer implementations
+ */
+export declare abstract class BaseSerializer implements ISerializer {
+    /** Serializer name */
+    readonly name: string;
+    /** Supported formats */
+    readonly supportedFormats: SerializationFormat[];
+    /** Default format */
+    readonly defaultFormat: SerializationFormat;
+    /** Serializer configuration */
+    config: SerializationConfig;
+    /** Format handlers registry */
+    protected formatHandlers: Map<SerializationFormat, {
+        serialize: (data: unknown, context?: SerializationContext) => string | Buffer | Uint8Array;
+        deserialize: (data: string | Buffer | Uint8Array, context?: DeserializationContext) => unknown;
+        contentType?: string;
+    }>;
+    /** Serializer statistics */
+    protected stats: {
+        totalSerializations: number;
+        totalDeserializations: number;
+        serializationErrors: number;
+        deserializationErrors: number;
+        averageSerializationTime: number;
+        averageDeserializationTime: number;
+        formatUsage: Record<string, number>;
+    };
+    /**
+     * Create a new base serializer instance
+     * @param name Serializer name
+     * @param config Serializer configuration
+     */
+    constructor(name: string, config: SerializationConfig);
+    /**
+     * Initialize supported formats
+     * @returns Array of supported formats
+     */
+    protected abstract initializeSupportedFormats(): SerializationFormat[];
+    /**
+     * Initialize serializer
+     */
+    protected initialize(): void;
+    /**
+     * Register default format handlers
+     */
+    protected abstract registerDefaultHandlers(): void;
+    /**
+     * Serialize data to a specific format
+     * @param data Data to serialize
+     * @param context Serialization context
+     * @returns Serialized data
+     * @throws {CommunicationError} If serialization fails
+     */
+    abstract serialize<T = unknown>(data: T, context?: Partial<SerializationContext>): string | Buffer | Uint8Array;
+    /**
+     * Deserialize data from a specific format
+     * @param data Data to deserialize
+     * @param context Deserialization context
+     * @returns Deserialized data
+     * @throws {CommunicationError} If deserialization fails
+     */
+    abstract deserialize<T = unknown>(data: string | Buffer | Uint8Array, context?: Partial<DeserializationContext>): T;
+    /**
+     * Perform serialization with timing and error handling
+     * @param data Data to serialize
+     * @param context Serialization context
+     * @param handler Serialization handler
+     * @returns Serialized data
+     */
+    protected performSerialization(data: unknown, context: SerializationContext, handler: (data: unknown, context: SerializationContext) => string | Buffer | Uint8Array): string | Buffer | Uint8Array;
+    /**
+     * Perform deserialization with timing and error handling
+     * @param data Data to deserialize
+     * @param context Deserialization context
+     * @param handler Deserialization handler
+     * @returns Deserialized data
+     */
+    protected performDeserialization<T>(data: string | Buffer | Uint8Array, context: DeserializationContext, handler: (data: string | Buffer | Uint8Array, context: DeserializationContext) => unknown): T;
+    /**
+     * Transform data (e.g., date parsing, bigint handling)
+     * @param data Data to transform
+     * @param direction 'serialize' or 'deserialize'
+     */
+    protected transformData(data: unknown, direction: 'serialize' | 'deserialize'): unknown;
+    /**
+     * Transform dates based on configuration
+     * @param data Data containing dates
+     * @param direction Transformation direction
+     */
+    protected transformDates(data: unknown, direction: 'serialize' | 'deserialize'): unknown;
+    /**
+     * Transform bigints based on configuration
+     * @param data Data containing bigints
+     * @param direction Transformation direction
+     */
+    protected transformBigInts(data: unknown, direction: 'serialize' | 'deserialize'): unknown;
+    /**
+     * Apply custom transformations
+     * @param data Data to transform
+     * @param direction Transformation direction
+     */
+    protected applyCustomTransformations(data: unknown, direction: 'serialize' | 'deserialize'): unknown;
+    /**
+     * Update serialization statistics
+     * @param success Whether serialization succeeded
+     * @param duration Serialization duration in milliseconds
+     * @param format Format used
+     */
+    protected updateSerializationStats(success: boolean, duration: number, format: string): void;
+    /**
+     * Update deserialization statistics
+     * @param success Whether deserialization succeeded
+     * @param duration Deserialization duration in milliseconds
+     * @param format Format used
+     */
+    protected updateDeserializationStats(success: boolean, duration: number, format: string): void;
+    /**
+     * Check if a format is supported
+     * @param format Format to check
+     */
+    supportsFormat(format: SerializationFormat): boolean;
+    /**
+     * Get content type for a format
+     * @param format Format
+     * @returns Content type string
+     */
+    getContentType(format: SerializationFormat): string;
+    /**
+     * Get format from content type
+     * @param contentType Content type
+     * @returns Format or undefined if not recognized
+     */
+    getFormatFromContentType(contentType: string): SerializationFormat | undefined;
+    /**
+     * Register a custom format handler
+     * @param format Format name
+     * @param handler Serialization/deserialization functions
+     */
+    registerFormat(format: SerializationFormat, handler: {
+        serialize: (data: unknown) => string | Buffer | Uint8Array;
+        deserialize: (data: string | Buffer | Uint8Array) => unknown;
+        contentType?: string;
+    }): void;
+    /**
+     * Update serializer configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<SerializationConfig>): void;
+    /**
+     * Get serializer statistics
+     */
+    getStats(): {
+        totalSerializations: number;
+        totalDeserializations: number;
+        serializationErrors: number;
+        deserializationErrors: number;
+        averageSerializationTime: number;
+        averageDeserializationTime: number;
+        formatUsage: Record<string, number>;
+    };
+    /**
+     * Reset serializer statistics
+     */
+    resetStats(): void;
+    /**
+     * Health check for the serializer
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+}