@naman_deep_singh/communication-core 1.0.0

package/dist/esm/utils.js

@@ -0,0 +1,193 @@
+/**
+ * Utilities integration with @naman_deep_singh/utils package
+ * @packageDocumentation
+ */
+import { Compression, GenericPool, TimeoutManager } from '@naman_deep_singh/utils';
+/**
+ * Base connection implementation that satisfies both interfaces
+ */
+export class BaseConnection {
+}
+/**
+ * Timeout utilities wrapper
+ */
+export class TimeoutUtils {
+    /**
+     * Execute with timeout
+     */
+    static async withTimeout(promise, timeoutMs, errorMessage) {
+        return TimeoutManager.withTimeout(promise, timeoutMs, errorMessage);
+    }
+    /**
+     * Create delay
+     */
+    static async delay(ms) {
+        return TimeoutManager.delay(ms);
+    }
+    /**
+     * Retry with timeout
+     */
+    static async retryWithTimeout(fn, options) {
+        return TimeoutManager.retryWithTimeout(fn, options);
+    }
+    /**
+     * Create a timeout promise
+     */
+    static createTimeout(timeoutMs, message) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(message || `Timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+        });
+    }
+    /**
+     * Create an abort signal for timeout
+     */
+    static createAbortSignal(timeoutMs) {
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), timeoutMs);
+        return controller.signal;
+    }
+    /**
+     * Race promises with timeout
+     */
+    static async raceWithTimeout(promises, timeoutMs, errorMessage) {
+        const timeoutPromise = this.createTimeout(timeoutMs, errorMessage);
+        return Promise.race([...promises, timeoutPromise]);
+    }
+}
+/**
+ * Connection pool wrapper
+ */
+export class ConnectionPoolUtils {
+    /**
+     * Create a generic connection pool
+     */
+    static createPool(config) {
+        return new GenericPool({
+            name: config.name,
+            minConnections: config.minConnections,
+            maxConnections: config.maxConnections,
+            createConnection: config.createConnection,
+            validateConnection: config.validateConnection,
+            idleTimeoutMs: config.idleTimeout,
+            maxLifetimeMs: config.maxLifetime,
+            acquireTimeoutMs: config.acquireTimeout,
+        });
+    }
+    /**
+     * Create a simple pool with basic configuration
+     */
+    static createSimplePool(name, createConnection, options) {
+        return new GenericPool({
+            name,
+            minConnections: options?.minConnections,
+            maxConnections: options?.maxConnections,
+            createConnection,
+            idleTimeoutMs: options?.idleTimeout,
+        });
+    }
+    /**
+     * Create an adapter to convert property-based isHealthy to function-based
+     */
+    static createConnectionAdapter(connection, closeFn = async () => { }, healthCheckFn = async () => true, resetFn = async () => { }) {
+        // Handle isHealthy conversion
+        const getIsHealthy = () => {
+            if (typeof connection.isHealthy === 'function') {
+                return connection.isHealthy();
+            }
+            return connection.isHealthy ?? true;
+        };
+        return {
+            id: connection.id || `conn-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            // isHealthy must be a function
+            isHealthy: getIsHealthy,
+            createdAt: connection.createdAt || Date.now(),
+            lastUsedAt: connection.lastUsedAt || Date.now(),
+            usageCount: connection.usageCount || 0,
+            metadata: connection.metadata || {},
+            close: closeFn,
+            healthCheck: healthCheckFn,
+            reset: resetFn,
+        };
+    }
+}
+/**
+ * Compression utilities wrapper
+ */
+export class CompressionUtils {
+    /**
+     * Compress data
+     */
+    static async compress(data, options) {
+        const result = await Compression.compress(Buffer.from(data), {
+            algorithm: options?.algorithm || 'gzip',
+            level: options?.level || 6,
+        });
+        return Buffer.from(result);
+    }
+    /**
+     * Decompress data
+     */
+    static async decompress(data, options) {
+        const result = await Compression.decompress(Buffer.from(data), {
+            algorithm: options?.algorithm || 'gzip',
+        });
+        return Buffer.from(result);
+    }
+    /**
+     * Compress data with metrics
+     */
+    static async compressWithMetrics(data, options) {
+        const startTime = Date.now();
+        const originalSize = Buffer.from(data).length;
+        const compressed = await Compression.compress(Buffer.from(data), {
+            algorithm: options?.algorithm || 'gzip',
+            level: options?.level || 6,
+        });
+        const compressionTime = Date.now() - startTime;
+        const compressedSize = compressed.length;
+        const compressionRatio = compressedSize / originalSize;
+        return {
+            data: Buffer.from(compressed),
+            originalSize,
+            compressedSize,
+            compressionRatio,
+            compressionTime,
+        };
+    }
+    /**
+     * Get optimal compression level based on data size
+     */
+    static getOptimalLevel(dataSize) {
+        if (dataSize < 1024)
+            return 1; // Small data, fast compression
+        if (dataSize < 10240)
+            return 6; // Medium data, balanced
+        return 9; // Large data, best compression
+    }
+    /**
+     * Estimate compression ratio for data type
+     */
+    static estimateCompressionRatio(contentType) {
+        if (!contentType)
+            return 0.7;
+        const type = contentType.toLowerCase();
+        if (type.includes('json') || type.includes('xml'))
+            return 0.3;
+        if (type.includes('text'))
+            return 0.4;
+        if (type.includes('image') || type.includes('video'))
+            return 0.95;
+        return 0.7;
+    }
+}
+/**
+ * Compression algorithm type
+ */
+CompressionUtils.Algorithm = {
+    GZIP: 'gzip',
+    DEFLATE: 'deflate',
+    BROTLI: 'brotli',
+    NONE: 'none',
+};

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

@@ -0,0 +1,167 @@
+/**
+ * Abstract base circuit breaker implementation
+ * @packageDocumentation
+ */
+import type { CommunicationErrorType } from '../errors/CommunicationError.js';
+import type { ICircuitBreaker } from '../interfaces/CircuitBreaker.interface.js';
+import type { CircuitBreakerConfig } from '../types/config.js';
+/**
+ * Abstract base circuit breaker implementation
+ * Provides common functionality for all circuit breaker implementations
+ */
+export declare abstract class BaseCircuitBreaker implements ICircuitBreaker {
+    /** Circuit breaker name */
+    readonly name: string;
+    /** Current state */
+    state: 'closed' | 'open' | 'half-open';
+    /** Circuit breaker configuration */
+    config: CircuitBreakerConfig;
+    /** Failure count */
+    failureCount: number;
+    /** Success count */
+    successCount: number;
+    /** Last failure timestamp */
+    lastFailureTime?: number;
+    /** Last success timestamp */
+    lastSuccessTime?: number;
+    /** Time when circuit will attempt to reset */
+    nextResetTime?: number;
+    /** Circuit breaker statistics */
+    protected stats: {
+        totalExecutions: number;
+        totalSuccesses: number;
+        totalFailures: number;
+        successRate: number;
+        failureRate: number;
+        totalTimeOpen: number;
+        totalTimeClosed: number;
+        lastStateChange: number;
+    };
+    /** Time when current state was entered */
+    protected stateEnteredTime: number;
+    /**
+     * Create a new base circuit breaker instance
+     * @param name Circuit breaker name
+     * @param config Circuit breaker configuration
+     */
+    constructor(name: string, config: CircuitBreakerConfig);
+    /**
+     * Initialize circuit breaker
+     */
+    protected initialize(): void;
+    /**
+     * Execute a function with circuit breaker protection
+     * @param fn Function to execute
+     * @returns Promise resolving to function result
+     * @throws {CommunicationError} If circuit is open or function fails
+     */
+    abstract execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute a function with circuit breaker protection and context
+     * @param fn Function to execute
+     * @param context Execution context
+     * @returns Promise resolving to function result
+     */
+    abstract executeWithContext<T, C = unknown>(fn: (context: C) => Promise<T>, context: C): Promise<T>;
+    /**
+     * Check if circuit breaker should allow execution
+     * @returns True if execution is allowed
+     */
+    protected shouldAllowExecution(): boolean;
+    /**
+     * Transition circuit breaker to closed state
+     */
+    protected transitionToClosed(): void;
+    /**
+     * Transition circuit breaker to open state
+     * @param error Optional error that caused the transition
+     */
+    protected transitionToOpen(error?: CommunicationErrorType): void;
+    /**
+     * Transition circuit breaker to half-open state
+     */
+    protected transitionToHalfOpen(): void;
+    /**
+     * Update state timing statistics
+     * @param previousState Previous state
+     */
+    protected updateStateTime(previousState: string): void;
+    /**
+     * Hook for state changes
+     * @param newState New state
+     * @param previousState Previous state
+     * @param error Optional error that caused state change
+     */
+    protected onStateChange(newState: string, previousState: string, error?: CommunicationErrorType): void;
+    /**
+     * Check if failure threshold is reached
+     * @returns True if failure threshold reached
+     */
+    protected isFailureThresholdReached(): boolean;
+    /**
+     * Check if success threshold is reached
+     * @returns True if success threshold reached
+     */
+    protected isSuccessThresholdReached(): boolean;
+    /**
+     * Manually trip the circuit breaker to open state
+     * @param error Error that caused the trip
+     */
+    trip(error?: CommunicationErrorType): void;
+    /**
+     * Manually reset the circuit breaker to closed state
+     */
+    reset(): void;
+    /**
+     * Check if circuit breaker is currently open
+     */
+    isOpen(): boolean;
+    /**
+     * Check if circuit breaker is currently closed
+     */
+    isClosed(): boolean;
+    /**
+     * Check if circuit breaker is in half-open state
+     */
+    isHalfOpen(): boolean;
+    /**
+     * Record a successful execution
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed execution
+     * @param error Error that occurred
+     */
+    recordFailure(error: CommunicationErrorType): void;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): {
+        totalExecutions: number;
+        totalSuccesses: number;
+        totalFailures: number;
+        successRate: number;
+        failureRate: number;
+        totalTimeOpen: number;
+        totalTimeClosed: number;
+        lastStateChange: number;
+    };
+    /**
+     * Reset circuit breaker statistics
+     */
+    resetStats(): void;
+    /**
+     * Update circuit breaker configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<CircuitBreakerConfig>): void;
+    /**
+     * Health check for the circuit breaker
+     */
+    healthCheck(): {
+        healthy: boolean;
+        state: 'closed' | 'open' | 'half-open';
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Abstract base client implementation
+ * @packageDocumentation
+ */
+import type { ICircuitBreaker } from '../interfaces/CircuitBreaker.interface.js';
+import type { IClient } from '../interfaces/Client.interface.js';
+import type { IInterceptor } from '../interfaces/Interceptor.interface.js';
+import type { ILoadBalanceStrategy } from '../interfaces/LoadBalancer.interface.js';
+import type { IProtocol } from '../interfaces/Protocol.interface.js';
+import type { IRetryStrategy } from '../interfaces/RetryStrategy.interface.js';
+import type { IServiceDiscoverer } from '../interfaces/ServiceDiscovery.interface.js';
+import type { ClientConfig } from '../types/config.js';
+import type { Request, RequestOptions } from '../types/request.js';
+import type { Response } from '../types/response.js';
+import type { ServiceInstance } from '../types/service.js';
+/**
+ * Abstract base client implementation
+ * Provides common functionality for all client implementations
+ */
+export declare abstract class BaseClient<TRequest = Request, TResponse = Response> implements IClient {
+    /** Client configuration */
+    readonly config: ClientConfig;
+    /** Client name/identifier */
+    readonly name: string;
+    /** Service name this client communicates with */
+    readonly serviceName: string;
+    /** Protocol being used */
+    readonly protocol: IProtocol;
+    /** Service discovery instance */
+    protected serviceDiscoverer?: IServiceDiscoverer;
+    /** Load balancer instance */
+    protected loadBalancer?: ILoadBalanceStrategy;
+    /** Circuit breaker instance */
+    protected circuitBreaker?: ICircuitBreaker;
+    /** Retry strategy instance */
+    protected retryStrategy?: IRetryStrategy;
+    /** Client interceptors */
+    protected interceptors: IInterceptor[];
+    /** Cached service instances */
+    protected cachedInstances: ServiceInstance[];
+    /** Last cache refresh time */
+    protected lastCacheRefresh?: number;
+    /** Client metrics */
+    protected metrics: Record<string, unknown>;
+    /** Client start time */
+    protected readonly startTime: number;
+    /** Total calls made */
+    protected totalCalls: number;
+    /** Successful calls */
+    protected successfulCalls: number;
+    /** Failed calls */
+    protected failedCalls: number;
+    /**
+     * Create a new base client instance
+     * @param serviceName Service name to communicate with
+     * @param config Client configuration
+     * @param protocol Protocol instance
+     */
+    constructor(serviceName: string, config: ClientConfig, protocol: IProtocol);
+    /**
+     * Initialize client components
+     */
+    protected initializeComponents(): void;
+    /**
+     * Make a request to a service endpoint
+     * @param endpoint Service endpoint/path
+     * @param data Request data
+     * @param options Request options
+     * @returns Promise resolving to the response
+     * @throws {CommunicationError} If the request fails
+     */
+    abstract call<T = unknown>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<Response<T>>;
+    /**
+     * Make a request with full control over request object
+     * @param request Complete request object
+     * @returns Promise resolving to the response
+     */
+    abstract request<T = unknown>(request: Request): Promise<Response<T>>;
+    /**
+     * Build request from endpoint and data
+     * @param endpoint Service endpoint
+     * @param data Request data
+     * @param options Request options
+     * @returns Built request object
+     */
+    protected abstract buildRequest(endpoint: string, data?: unknown, options?: RequestOptions): TRequest;
+    /**
+     * Parse response to standard format
+     * @param response Protocol response
+     * @returns Standardized response
+     */
+    protected abstract parseResponse<T>(response: TResponse): Response<T>;
+    /**
+     * Get service discovery instance
+     */
+    getServiceDiscoverer(): IServiceDiscoverer | undefined;
+    /**
+     * Get load balancer instance
+     */
+    getLoadBalancer(): ILoadBalanceStrategy | undefined;
+    /**
+     * Get circuit breaker instance
+     */
+    getCircuitBreaker(): ICircuitBreaker | undefined;
+    /**
+     * Get retry strategy instance
+     */
+    getRetryStrategy(): IRetryStrategy | undefined;
+    /**
+     * Add an interceptor to the client
+     * @param interceptor IInterceptor to add
+     */
+    addInterceptor(interceptor: IInterceptor): void;
+    /**
+     * Hook for interceptor addition
+     * @param interceptor Added interceptor
+     */
+    protected onInterceptorAdded(interceptor: IInterceptor): void;
+    /**
+     * Remove an interceptor from the client
+     * @param interceptorId IInterceptor identifier
+     */
+    removeInterceptor(interceptorId: string): void;
+    /**
+     * Hook for interceptor removal
+     * @param interceptorId Removed interceptor ID
+     */
+    protected onInterceptorRemoved(interceptorId: string): void;
+    /**
+     * Get all interceptors
+     */
+    getInterceptors(): IInterceptor[];
+    /**
+     * Clear all interceptors
+     */
+    clearInterceptors(): void;
+    /**
+     * Hook for interceptors cleared
+     */
+    protected onInterceptorsCleared(): void;
+    /**
+     * Discover service instances
+     * @returns Promise resolving to service instances
+     */
+    discoverService(): Promise<ServiceInstance[]>;
+    /**
+     * Get current service instances (cached)
+     */
+    getServiceInstances(): ServiceInstance[];
+    /**
+     * Refresh service instances cache
+     */
+    refreshServiceInstances(): Promise<void>;
+    /**
+     * Select a service instance using load balancer
+     * @param instances Available instances
+     * @returns Selected instance
+     */
+    protected selectInstance(instances: ServiceInstance[]): ServiceInstance;
+    /**
+     * Update client metrics
+     * @param success Whether call was successful
+     * @param duration Call duration in milliseconds
+     */
+    protected updateMetrics(success: boolean, duration: number): void;
+    /**
+     * Calculate average response time
+     * @param newDuration New call duration
+     * @returns Average response time
+     */
+    private calculateAverageResponseTime;
+    /**
+     * Health check for the client
+     * @returns Promise resolving to health status
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * Get client metrics
+     */
+    getMetrics(): Record<string, unknown>;
+    /**
+     * Reset client metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Close/cleanup client resources
+     */
+    close(): Promise<void>;
+    /**
+     * Hook for client close
+     */
+    protected onClose(): void;
+}