@naman_deep_singh/communication-core 1.0.0

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

@@ -0,0 +1,161 @@
+/**
+ * Abstract base service discoverer implementation
+ * @packageDocumentation
+ */
+import type { IServiceDiscoverer } from '../interfaces/ServiceDiscovery.interface.js';
+import type { ServiceInstance, ServiceDiscoveryResult, ServiceInstanceFilter, HealthCheckResult, WatchCallback, UnwatchFunction, ServiceRegistryConfig } from '../types/service.js';
+/**
+ * Abstract base service discoverer implementation
+ * Provides common functionality for all service discovery implementations
+ */
+export declare abstract class BaseServiceDiscoverer implements IServiceDiscoverer {
+    /** Discovery type */
+    readonly type: string;
+    /** Discovery configuration */
+    config: ServiceRegistryConfig;
+    /** Whether discovery is currently active */
+    isActive: boolean;
+    /** Last discovery timestamp */
+    lastDiscoveryTime?: number;
+    /** Total services discovered */
+    totalServicesDiscovered: number;
+    /** Total instances discovered */
+    totalInstancesDiscovered: number;
+    /** Service cache */
+    protected cache: Map<string, ServiceInstance[]>;
+    /** Cache timestamps */
+    protected cacheTimestamps: Map<string, number>;
+    /** Watch callbacks */
+    protected watchers: Map<string, Set<WatchCallback>>;
+    /** Discovery statistics */
+    protected stats: {
+        totalResolves: number;
+        totalWatches: number;
+        cacheHits: number;
+        cacheMisses: number;
+        cacheHitRate: number;
+        averageResolveTime: number;
+        totalResolveTime: number;
+        lastError?: string;
+        uptime: number;
+        startTime: number;
+    };
+    /**
+     * Create a new base service discoverer instance
+     * @param type Discovery type
+     * @param config Discovery configuration
+     */
+    constructor(type: string, config: ServiceRegistryConfig);
+    /**
+     * Initialize service discoverer
+     */
+    protected initialize(): void;
+    /**
+     * Resolve service instances for a given service name
+     * @param serviceName Service name to resolve
+     * @param filter Optional filter for instances
+     * @returns Promise resolving to service discovery result
+     */
+    abstract resolve(serviceName: string, filter?: ServiceInstanceFilter): Promise<ServiceDiscoveryResult>;
+    /**
+     * Resolve all instances for multiple services
+     * @param serviceNames Array of service names
+     * @returns Promise resolving to map of service names to instances
+     */
+    resolveAll(serviceNames: string[]): Promise<Map<string, ServiceInstance[]>>;
+    /**
+     * Watch for changes to service instances
+     * @param serviceName Service name to watch
+     * @param callback Callback function for changes
+     * @returns Unwatch function
+     */
+    watch(serviceName: string, callback: WatchCallback): UnwatchFunction;
+    /**
+     * Stop watching a service
+     * @param serviceName Service name to stop watching
+     */
+    unwatch(serviceName: string): void;
+    /**
+     * Stop watching all services
+     */
+    unwatchAll(): void;
+    /**
+     * Perform health check on service instances
+     * @param serviceName Optional service name to check
+     * @returns Promise resolving to health check results
+     */
+    abstract healthCheck(serviceName?: string): Promise<Map<string, HealthCheckResult[]>>;
+    /**
+     * Get cached service instances
+     * @param serviceName Service name
+     * @returns Cached instances or empty array
+     */
+    getCachedInstances(serviceName: string): ServiceInstance[];
+    /**
+     * Clear cache for a service
+     * @param serviceName Service name
+     */
+    clearCache(serviceName?: string): void;
+    /**
+     * Refresh cache for a service
+     * @param serviceName Service name
+     * @returns Promise resolving when cache is refreshed
+     */
+    refreshCache(serviceName?: string): Promise<void>;
+    /**
+     * Check if cache is valid for a service
+     * @param serviceName Service name
+     * @returns True if cache is valid
+     */
+    protected isCacheValid(serviceName: string): boolean;
+    /**
+     * Update cache for a service
+     * @param serviceName Service name
+     * @param instances Service instances
+     */
+    protected updateCache(serviceName: string, instances: ServiceInstance[]): void;
+    /**
+     * Notify watchers of service changes
+     * @param serviceName Service name
+     * @param instances Updated instances
+     */
+    protected notifyWatchers(serviceName: string, instances: ServiceInstance[]): void;
+    /**
+     * Get service discovery statistics
+     */
+    getStats(): {
+        totalResolves: number;
+        totalWatches: number;
+        cacheHits: number;
+        cacheMisses: number;
+        cacheHitRate: number;
+        averageResolveTime: number;
+        lastError?: string;
+        uptime: number;
+    };
+    /**
+     * Reset service discovery statistics
+     */
+    resetStats(): void;
+    /**
+     * Update service discovery configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<ServiceRegistryConfig>): void;
+    /**
+     * Health check for the service discoverer itself
+     */
+    healthCheckSelf(): Promise<{
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * Close/cleanup service discovery resources
+     */
+    close(): Promise<void>;
+    /**
+     * Hook for cleanup logic
+     */
+    protected onClose(): Promise<void>;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Abstract base timeout manager implementation
+ * @packageDocumentation
+ */
+import type { ITimeoutManager, TimeoutOptions } from '../interfaces/Timeout.interface.js';
+import type { TimeoutConfig } from '../types/config.js';
+/**
+ * Abstract base timeout manager implementation
+ * Provides common functionality for timeout management
+ */
+export declare abstract class BaseTimeoutManager implements ITimeoutManager {
+    /** Timeout manager name */
+    readonly name: string;
+    /** Timeout configuration */
+    config: TimeoutConfig;
+    /** Operation-specific timeouts */
+    protected operationTimeouts: Map<string, number>;
+    /** Timeout statistics */
+    protected stats: {
+        totalOperations: number;
+        timedOutOperations: number;
+        totalOperationTime: number;
+        averageOperationTime: number;
+        timeoutRate: number;
+        perOperationStats: Map<string, {
+            calls: number;
+            timeouts: number;
+            totalTime: number;
+            averageTime: number;
+        }>;
+    };
+    /**
+     * Create a new base timeout manager instance
+     * @param name Timeout manager name
+     * @param config Timeout configuration
+     */
+    constructor(name: string, config: TimeoutConfig);
+    /**
+     * Initialize timeout manager
+     */
+    protected initialize(): void;
+    /**
+     * Execute a function with timeout
+     * @param fn Function to execute
+     * @param options Timeout options
+     * @returns Promise resolving to function result
+     * @throws {CommunicationError} If timeout occurs
+     */
+    execute<T>(fn: () => Promise<T>, options?: TimeoutOptions): Promise<T>;
+    /**
+     * Create a timeout promise
+     * @param timeout Timeout in milliseconds
+     * @param message Error message
+     * @returns Promise that rejects after timeout
+     */
+    createTimeout(timeout: number, message?: string): Promise<never>;
+    /**
+     * Create an abort signal for timeout
+     * @param timeout Timeout in milliseconds
+     * @returns AbortSignal
+     */
+    createAbortSignal(timeout: number): AbortSignal;
+    /**
+     * Execute multiple promises with timeout
+     * @param promises Array of promises
+     * @param timeout Timeout in milliseconds
+     * @returns Promise that resolves when first promise resolves or times out
+     */
+    race<T>(promises: Promise<T>[], timeout: number): Promise<T>;
+    /**
+     * Delay execution for specified time
+     * @param delay Delay in milliseconds
+     * @returns Promise that resolves after delay
+     */
+    delay(delay: number): Promise<void>;
+    /**
+     * Set operation timeout
+     * @param operation Operation identifier
+     * @param timeout Timeout in milliseconds
+     */
+    setOperationTimeout(operation: string, timeout: number): void;
+    /**
+     * Get operation timeout
+     * @param operation Operation identifier
+     * @returns Timeout in milliseconds or undefined
+     */
+    getOperationTimeout(operation: string): number | undefined;
+    /**
+     * Record successful operation
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     */
+    protected recordSuccess(operation: string, duration: number): void;
+    /**
+     * Record timed out operation
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     */
+    protected recordTimeout(operation: string, duration: number): void;
+    /**
+     * Record failed operation (not timeout)
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     * @param error Error that occurred
+     */
+    protected recordFailure(operation: string, duration: number, error: Error): void;
+    /**
+     * Update operation-specific statistics
+     * @param operation Operation name
+     * @param duration Duration in milliseconds
+     * @param isTimeout Whether operation timed out
+     */
+    protected updateOperationStats(operation: string, duration: number, isTimeout: boolean): void;
+    /**
+     * Update timeout configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<TimeoutConfig>): void;
+    /**
+     * Get timeout statistics
+     */
+    getStats(): {
+        totalOperations: number;
+        timedOutOperations: number;
+        averageOperationTime: number;
+        timeoutRate: number;
+        perOperationStats: Record<string, {
+            calls: number;
+            timeouts: number;
+            averageTime: number;
+        }>;
+    };
+    /**
+     * Reset timeout statistics
+     */
+    resetStats(): void;
+    /**
+     * Health check for timeout manager
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+}

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

@@ -0,0 +1,11 @@
+export { BaseProtocol } from './BaseProtocol.js';
+export { BaseClient } from './BaseClient.js';
+export { BaseCircuitBreaker } from './BaseCircuitBreaker.js';
+export { BaseRetryStrategy } from './BaseRetryStrategy.js';
+export { BaseLoadBalancer } from './BaseLoadBalancer.js';
+export { BaseSerializer } from './BaseSerializer.js';
+export { BaseServiceDiscoverer } from './BaseServiceDiscoverer.js';
+export { BaseInterceptor } from './BaseInterceptor.js';
+export { BaseTimeoutManager } from './BaseTimeoutManager.js';
+export { BaseConnectionPool } from './BaseConnectionPool.js';
+export { BaseCompressionManager } from './BaseCompressionManager.js';

package/dist/types/errors/CircuitBreakerError.d.ts

@@ -0,0 +1,8 @@
+import { CommunicationError } from "./CommunicationError.js";
+/**
+ * Circuit breaker error - when circuit is open
+ */
+export declare class CircuitBreakerError extends CommunicationError {
+    constructor(details?: unknown, cause?: Error);
+}
+export type CircuitBreakerErrorType = CircuitBreakerError;

package/dist/types/errors/CommunicationError.d.ts

@@ -0,0 +1,10 @@
+import { AppError } from "@naman_deep_singh/errors";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Base communication error class
+ * Extends AppError from errors package
+ */
+export declare class CommunicationError extends AppError {
+    constructor(code: CommunicationErrorCode, statusCode?: number, details?: unknown, cause?: Error);
+}
+export type CommunicationErrorType = CommunicationError;

package/dist/types/errors/ConnectionError.d.ts

@@ -0,0 +1,9 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Connection error - when connection fails
+ */
+export declare class ConnectionError extends CommunicationError {
+    constructor(code?: CommunicationErrorCode, details?: unknown, cause?: Error);
+}
+export type ConnectionErrorType = ConnectionError;

package/dist/types/errors/DiscoveryError.d.ts

@@ -0,0 +1,9 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Service discovery error
+ */
+export declare class DiscoveryError extends CommunicationError {
+    constructor(code?: CommunicationErrorCode, details?: unknown, cause?: Error);
+}
+export type DiscoveryErrorType = DiscoveryError;

package/dist/types/errors/LoadBalancerError.d.ts

@@ -0,0 +1,9 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Load balancer error - when load balancing fails
+ */
+export declare class LoadBalancerError extends CommunicationError {
+    constructor(code?: CommunicationErrorCode, details?: unknown, cause?: Error);
+}
+export type LoadBalancerErrorType = LoadBalancerError;

package/dist/types/errors/ProtocolError.d.ts

@@ -0,0 +1,9 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Protocol error - when protocol communication fails
+ */
+export declare class ProtocolError extends CommunicationError {
+    constructor(code?: CommunicationErrorCode, details?: unknown, cause?: Error);
+}
+export type ProtocolErrorType = ProtocolError;

package/dist/types/errors/RetryError.d.ts

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+/**
+ * Retry exhausted error - when all retry attempts fail
+ */
+export declare class RetryError extends CommunicationError {
+    constructor(details?: {
+        attempts: number;
+        lastError?: Error;
+    }, cause?: Error);
+}
+export type RetryErrorType = RetryError;

package/dist/types/errors/SerializationError.d.ts

@@ -0,0 +1,9 @@
+import { CommunicationError } from "./CommunicationError.js";
+import { type CommunicationErrorCode } from "./communicationErrorCodes.js";
+/**
+ * Serialization error - when serialization/deserialization fails
+ */
+export declare class SerializationError extends CommunicationError {
+    constructor(code?: CommunicationErrorCode, details?: unknown, cause?: Error);
+}
+export type SerializationErrorType = SerializationError;

package/dist/types/errors/ServiceUnavailableError.d.ts

@@ -0,0 +1,12 @@
+import { ServiceUnavailableError as BaseServiceUnavailableError } from '@naman_deep_singh/errors';
+/**
+ * Service unavailable error for communication layer
+ * Extends the existing ServiceUnavailableError
+ */
+export declare class ServiceUnavailableError extends BaseServiceUnavailableError {
+    constructor(details?: {
+        service: string;
+        reason?: string;
+    }, cause?: Error);
+}
+export type ServiceUnavailableErrorType = ServiceUnavailableError;

package/dist/types/errors/TimeoutError.d.ts

@@ -0,0 +1,11 @@
+import { CommunicationError } from "./CommunicationError.js";
+/**
+ * Timeout error - when operation times out
+ */
+export declare class TimeoutError extends CommunicationError {
+    constructor(details?: {
+        timeout: number;
+        operation: string;
+    }, cause?: Error);
+}
+export type TimeoutErrorType = TimeoutError;

package/dist/types/errors/communicationErrorCodes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Communication-specific error codes
+ * Extends the existing ERROR_CODES
+ */
+export declare const COMMUNICATION_ERROR_CODES: {
+    readonly PROTOCOL_ERROR: "Protocol communication failed";
+    readonly HTTP_PROTOCOL_ERROR: "HTTP protocol error occurred";
+    readonly GRPC_PROTOCOL_ERROR: "gRPC protocol error occurred";
+    readonly WEBSOCKET_PROTOCOL_ERROR: "WebSocket protocol error occurred";
+    readonly DISCOVERY_ERROR: "Service discovery failed";
+    readonly SERVICE_NOT_FOUND: "Service not found in registry";
+    readonly NO_AVAILABLE_INSTANCES: "No available service instances";
+    readonly DISCOVERY_TIMEOUT: "Service discovery timed out";
+    readonly CIRCUIT_BREAKER_OPEN: "Circuit breaker is open, request blocked";
+    readonly CIRCUIT_BREAKER_ERROR: "Circuit breaker encountered an error";
+    readonly RETRY_EXHAUSTED: "Retry attempts exhausted";
+    readonly BULKHEAD_FULL: "Bulkhead is full, request rejected";
+    readonly TIMEOUT_EXHAUSTED: "Operation timeout exceeded";
+    readonly LOAD_BALANCER_ERROR: "Load balancing failed";
+    readonly NO_HEALTHY_INSTANCES: "No healthy instances available";
+    readonly SERIALIZATION_ERROR: "Serialization failed";
+    readonly DESERIALIZATION_ERROR: "Deserialization failed";
+    readonly CONNECTION_ERROR: "Connection failed";
+    readonly CONNECTION_TIMEOUT: "Connection timeout";
+    readonly CONNECTION_REFUSED: "Connection refused";
+};
+export type CommunicationErrorCode = typeof COMMUNICATION_ERROR_CODES[keyof typeof COMMUNICATION_ERROR_CODES];

package/dist/types/errors/index.d.ts

@@ -0,0 +1,11 @@
+export { CircuitBreakerError, type CircuitBreakerErrorType } from "./CircuitBreakerError.js";
+export { CommunicationError, type CommunicationErrorType } from "./CommunicationError.js";
+export { ConnectionError, type ConnectionErrorType } from "./ConnectionError.js";
+export { DiscoveryError, type DiscoveryErrorType } from "./DiscoveryError.js";
+export { LoadBalancerError, type LoadBalancerErrorType } from "./LoadBalancerError.js";
+export { ProtocolError, type ProtocolErrorType } from "./ProtocolError.js";
+export { RetryError, type RetryErrorType } from "./RetryError.js";
+export { SerializationError, type SerializationErrorType } from "./SerializationError.js";
+export { ServiceUnavailableError, type ServiceUnavailableErrorType } from "./ServiceUnavailableError.js";
+export { TimeoutError, type TimeoutErrorType } from "./TimeoutError.js";
+export { COMMUNICATION_ERROR_CODES, type CommunicationErrorCode } from "./communicationErrorCodes.js";

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Communication Core Package
+ * @packageDocumentation
+ *
+ * Core interfaces and abstract implementations for service-to-service communication.
+ * This package provides the foundation for communication protocols, resilience patterns,
+ * service discovery, load balancing, and interceptors.
+ */
+export * from './interfaces/index.js';
+export * from './abstract/index.js';
+export * from './types/index.js';
+export * from './errors/index.js';
+export { TimeoutUtils, ConnectionPoolUtils, CompressionUtils, type Connection, type BaseConnection, } from './utils.js';

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

@@ -0,0 +1,150 @@
+/**
+ * Circuit breaker interface for communication layer
+ * @packageDocumentation
+ */
+import type { CommunicationError } from '../errors/CommunicationError.js';
+import type { CircuitBreakerConfig, CircuitBreakerState } from '../types/config.js';
+import type { CircuitBreakerEvent } from '../types/events.js';
+/**
+ * Circuit breaker interface for resilience pattern
+ * Prevents cascading failures by stopping requests when failures exceed threshold
+ */
+export interface ICircuitBreaker {
+    /** Circuit breaker name */
+    readonly name: string;
+    /** Current state */
+    readonly state: CircuitBreakerState;
+    /** Circuit breaker configuration */
+    readonly config: CircuitBreakerConfig;
+    /** Failure count */
+    readonly failureCount: number;
+    /** Success count */
+    readonly successCount: number;
+    /** Last failure timestamp */
+    readonly lastFailureTime?: number;
+    /** Last success timestamp */
+    readonly lastSuccessTime?: number;
+    /** Time when circuit will attempt to reset */
+    readonly nextResetTime?: number;
+    /**
+     * 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
+     */
+    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
+     */
+    executeWithContext<T, C = unknown>(fn: (context: C) => Promise<T>, context: C): Promise<T>;
+    /**
+     * Manually trip the circuit breaker to open state
+     * @param error Error that caused the trip
+     */
+    trip(error?: CommunicationError): 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: CommunicationError): 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: CircuitBreakerState;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Event emitter for circuit breaker events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to circuit breaker events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        on(event: string | string[], listener: (event: CircuitBreakerEvent) => void): void;
+        /**
+         * Unsubscribe from circuit breaker events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        off(event: string | string[], listener: (event: CircuitBreakerEvent) => void): void;
+    };
+}
+/**
+ * Circuit breaker factory interface
+ */
+export interface ICircuitBreakerFactory {
+    /**
+     * Create a new circuit breaker instance
+     * @param name Circuit breaker name
+     * @param config Circuit breaker configuration
+     * @returns New circuit breaker instance
+     */
+    create(name: string, config?: Partial<CircuitBreakerConfig>): ICircuitBreaker;
+    /**
+     * Get an existing circuit breaker instance
+     * @param name Circuit breaker name
+     */
+    get(name: string): ICircuitBreaker | undefined;
+    /**
+     * Get all circuit breaker instances
+     */
+    getAll(): ICircuitBreaker[];
+    /**
+     * Reset all circuit breaker instances
+     */
+    resetAll(): void;
+    /**
+     * Close all circuit breaker instances
+     */
+    closeAll(): Promise<void>;
+}