@naman_deep_singh/communication-core 1.0.0

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

@@ -0,0 +1,153 @@
+/**
+ * Client interface for communication layer
+ * @packageDocumentation
+ */
+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';
+import type { ICircuitBreaker } from './CircuitBreaker.interface.js';
+import type { IInterceptor } from './Interceptor.interface.js';
+import type { ILoadBalanceStrategy } from './LoadBalancer.interface.js';
+import type { IProtocol } from './Protocol.interface.js';
+import type { IRetryStrategy } from './RetryStrategy.interface.js';
+import type { IServiceDiscoverer } from './ServiceDiscovery.interface.js';
+/**
+ * Client interface for service-to-service communication
+ * This is the main interface that users interact with
+ */
+export interface 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;
+    /**
+     * 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
+     */
+    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
+     */
+    request<T = unknown>(request: Request): Promise<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 Interceptor to add
+     */
+    addInterceptor(interceptor: IInterceptor): void;
+    /**
+     * Remove an interceptor from the client
+     * @param interceptorId Interceptor identifier
+     */
+    removeInterceptor(interceptorId: string): void;
+    /**
+     * Get all interceptors
+     */
+    getInterceptors(): IInterceptor[];
+    /**
+     * Clear all interceptors
+     */
+    clearInterceptors(): 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>;
+    /**
+     * 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>;
+    /**
+     * Event emitter for client events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to client events
+         * @param event Event name
+         * @param listener Event listener
+         */
+        on(event: string, listener: (data: any) => void): void;
+        /**
+         * Unsubscribe from client events
+         * @param event Event name
+         * @param listener Event listener
+         */
+        off(event: string, listener: (data: any) => void): void;
+    };
+}
+/**
+ * Client factory interface for creating client instances
+ */
+export interface IClientFactory {
+    /**
+     * Create a new client instance
+     * @param serviceName Service name to communicate with
+     * @param config Client configuration
+     * @returns New client instance
+     */
+    create(serviceName: string, config?: Partial<ClientConfig>): IClient;
+    /**
+     * Get an existing client instance
+     * @param clientId Client identifier
+     */
+    get?(clientId: string): IClient | undefined;
+    /**
+     * Close all client instances
+     */
+    closeAll?(): Promise<void>;
+    /**
+     * Get all client instances
+     */
+    getAll?(): IClient[];
+}

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

@@ -0,0 +1,190 @@
+/**
+ * Compression interface for communication layer
+ * @packageDocumentation
+ */
+import type { CompressionConfig } from '../types/config.js';
+/**
+ * Compression algorithm
+ */
+export type CompressionAlgorithm = 'gzip' | 'deflate' | 'brotli' | 'none';
+/**
+ * Compression result
+ */
+export interface CompressionResult {
+    /** Compressed data */
+    data: Buffer | Uint8Array;
+    /** Original size in bytes */
+    originalSize: number;
+    /** Compressed size in bytes */
+    compressedSize: number;
+    /** Compression ratio (0-1) */
+    compressionRatio: number;
+    /** Compression algorithm used */
+    algorithm: CompressionAlgorithm;
+    /** Compression level used */
+    level: number;
+    /** Compression time in milliseconds */
+    compressionTime: number;
+}
+/**
+ * Decompression result
+ */
+export interface DecompressionResult {
+    /** Decompressed data */
+    data: Buffer | string;
+    /** Original compressed size in bytes */
+    originalSize: number;
+    /** Decompressed size in bytes */
+    decompressedSize: number;
+    /** Decompression time in milliseconds */
+    decompressionTime: number;
+    /** Algorithm used for decompression */
+    algorithm: CompressionAlgorithm;
+}
+/**
+ * Compression options
+ */
+export interface CompressionOptions {
+    /** Compression algorithm */
+    algorithm?: CompressionAlgorithm;
+    /** Compression level (1-11) */
+    level?: number;
+    /** Chunk size for streaming */
+    chunkSize?: number;
+    /** Custom compression options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Compression manager interface
+ */
+export interface ICompressionManager {
+    /** Compression configuration */
+    readonly config: CompressionConfig;
+    /** Supported algorithms */
+    readonly supportedAlgorithms: CompressionAlgorithm[];
+    /**
+     * Compress data
+     * @param data Data to compress
+     * @param options Compression options
+     * @returns Promise resolving to compression result
+     * @throws {CommunicationError} If compression fails
+     */
+    compress(data: Buffer | string | Uint8Array, options?: CompressionOptions): Promise<CompressionResult>;
+    /**
+     * Compress data with detailed metrics
+     * @param data Data to compress
+     * @param options Compression options
+     * @returns Promise resolving to compression result with metrics
+     */
+    compressWithMetrics(data: Buffer | string | Uint8Array, options?: CompressionOptions): Promise<CompressionResult>;
+    /**
+     * Decompress data
+     * @param data Data to decompress
+     * @param options Decompression options
+     * @returns Promise resolving to decompression result
+     * @throws {CommunicationError} If decompression fails
+     */
+    decompress(data: Buffer | Uint8Array, options?: CompressionOptions): Promise<DecompressionResult>;
+    /**
+     * Check if algorithm is supported
+     * @param algorithm Algorithm to check
+     * @returns True if algorithm is supported
+     */
+    isAlgorithmSupported(algorithm: CompressionAlgorithm): boolean;
+    /**
+     * Get content encoding header for algorithm
+     * @param algorithm Compression algorithm
+     * @returns Content-Encoding header value
+     */
+    getContentEncoding(algorithm: CompressionAlgorithm): string;
+    /**
+     * Get algorithm from content encoding header
+     * @param contentEncoding Content-Encoding header value
+     * @returns Compression algorithm or undefined
+     */
+    getAlgorithmFromEncoding(contentEncoding: string): CompressionAlgorithm | undefined;
+    /**
+     * Should compress based on configuration
+     * @param dataSize Data size in bytes
+     * @param contentType Content type
+     * @returns True if should compress
+     */
+    shouldCompress(dataSize: number, contentType?: string): boolean;
+    /**
+     * Create compression stream
+     * @param algorithm Compression algorithm
+     * @param options Compression options
+     * @returns Transform stream for compression
+     */
+    createCompressionStream(algorithm: CompressionAlgorithm, options?: CompressionOptions): TransformStream;
+    /**
+     * Create decompression stream
+     * @param algorithm Compression algorithm
+     * @returns Transform stream for decompression
+     */
+    createDecompressionStream(algorithm: CompressionAlgorithm): TransformStream;
+    /**
+     * Update compression configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<CompressionConfig>): void;
+    /**
+     * Get compression statistics
+     */
+    getStats(): {
+        totalCompressions: number;
+        totalDecompressions: number;
+        compressionErrors: number;
+        decompressionErrors: number;
+        averageCompressionTime: number;
+        averageDecompressionTime: number;
+        averageCompressionRatio: number;
+        algorithmUsage: Record<string, number>;
+        totalBytesCompressed: number;
+        totalBytesDecompressed: number;
+        bytesSaved: number;
+    };
+    /**
+     * Reset compression statistics
+     */
+    resetStats(): void;
+    /**
+     * Health check for compression manager
+     */
+    healthCheck(): {
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    };
+}
+/**
+ * Compression manager factory interface
+ */
+export interface ICompressionManagerFactory {
+    /**
+     * Create a new compression manager instance
+     * @param name Compression manager name
+     * @param config Compression configuration
+     * @returns New compression manager instance
+     */
+    create(name: string, config?: Partial<CompressionConfig>): ICompressionManager;
+    /**
+     * Get an existing compression manager instance
+     * @param name Compression manager name
+     */
+    get(name: string): ICompressionManager | undefined;
+    /**
+     * Get all compression manager instances
+     */
+    getAll(): ICompressionManager[];
+    /**
+     * Register a custom compression manager
+     * @param name Compression manager name
+     * @param manager Compression manager instance or constructor
+     */
+    register(name: string, manager: ICompressionManager | (new (config: CompressionConfig) => ICompressionManager)): void;
+    /**
+     * Get available compression manager names
+     */
+    getAvailableManagers(): string[];
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Connection pool interface for communication layer
+ * @packageDocumentation
+ */
+import type { ConnectionPoolConfig } from '../types/config.js';
+/**
+ * Connection interface that must be implemented by pooled connections
+ * Note: isHealthy must be a function to be compatible with @naman_deep_singh/utils
+ */
+export interface IConnection {
+    /** Connection ID */
+    readonly id: string;
+    /** Is connection healthy? - Must be a function for utils compatibility */
+    readonly isHealthy: () => boolean;
+    /** Connection creation time */
+    readonly createdAt: number;
+    /** Last used time */
+    readonly lastUsedAt: number;
+    /** Usage count */
+    readonly usageCount: number;
+    /** Connection metadata */
+    readonly metadata: Record<string, unknown>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+    /**
+     * Health check for connection
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Reset connection state
+     */
+    reset(): Promise<void>;
+}
+/**
+ * Connection acquisition result
+ */
+export interface ConnectionAcquisition<T extends IConnection = IConnection> {
+    /** Acquired connection */
+    connection: T;
+    /** Acquisition timestamp */
+    timestamp: number;
+    /** Wait time in milliseconds */
+    waitTime: number;
+    /** Connection pool statistics */
+    poolStats: {
+        totalConnections: number;
+        activeConnections: number;
+        idleConnections: number;
+        waitingClients: number;
+    };
+}
+/**
+ * Connection pool interface
+ */
+export interface IConnectionPool<T extends IConnection = IConnection> {
+    /** Pool name */
+    readonly name: string;
+    /** Pool configuration */
+    readonly config: ConnectionPoolConfig;
+    /** Is pool healthy? */
+    readonly isHealthy: boolean;
+    /** Total connections in pool */
+    readonly totalConnections: number;
+    /** Active connections */
+    readonly activeConnections: number;
+    /** Idle connections */
+    readonly idleConnections: number;
+    /** Waiting clients */
+    readonly waitingClients: number;
+    /**
+     * Acquire a connection from the pool
+     * @param timeout Acquisition timeout in milliseconds
+     * @returns Promise resolving to connection acquisition
+     * @throws {CommunicationError} If timeout or pool exhausted
+     */
+    acquire(timeout?: number): Promise<ConnectionAcquisition<T>>;
+    /**
+     * Release a connection back to the pool
+     * @param connection Connection to release
+     */
+    release(connection: T): Promise<void>;
+    /**
+     * Destroy a connection (remove from pool)
+     * @param connection Connection to destroy
+     */
+    destroy(connection: T): Promise<void>;
+    /**
+     * Execute a function with a connection from the pool
+     * @param fn Function to execute with connection
+     * @param timeout Operation timeout in milliseconds
+     * @returns Promise resolving to function result
+     */
+    withConnection<R>(fn: (connection: T) => Promise<R>, timeout?: number): Promise<R>;
+    /**
+     * Create a new connection (factory method)
+     * @returns New connection instance
+     */
+    createConnection(): Promise<T>;
+    /**
+     * Validate a connection
+     * @param connection Connection to validate
+     * @returns True if connection is valid
+     */
+    validateConnection(connection: T): Promise<boolean>;
+    /**
+     * Drain the pool (gracefully close all connections)
+     * @param force Force immediate drain
+     */
+    drain(force?: boolean): Promise<void>;
+    /**
+     * Clear the pool (force close all connections)
+     */
+    clear(): Promise<void>;
+    /**
+     * Health check for the pool
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        message?: string;
+        details?: Record<string, unknown>;
+    }>;
+    /**
+     * Get pool statistics
+     */
+    getStats(): {
+        totalConnections: number;
+        activeConnections: number;
+        idleConnections: number;
+        waitingClients: number;
+        totalAcquisitions: number;
+        totalReleases: number;
+        totalDestructions: number;
+        totalErrors: number;
+        acquisitionTimeAverage: number;
+        acquisitionTimeMax: number;
+        poolUtilization: number;
+        connectionStats: Array<{
+            id: string;
+            createdAt: number;
+            lastUsedAt: number;
+            usageCount: number;
+            isHealthy: boolean;
+        }>;
+    };
+    /**
+     * Reset pool statistics
+     */
+    resetStats(): void;
+    /**
+     * Update pool configuration
+     * @param config New configuration
+     */
+    updateConfig(config: Partial<ConnectionPoolConfig>): void;
+}
+/**
+ * Connection pool factory interface
+ */
+export interface IConnectionPoolFactory {
+    /**
+     * Create a new connection pool instance
+     * @param name Pool name
+     * @param config Pool configuration
+     * @param createConnection Connection factory function
+     * @param validateConnection Connection validation function
+     * @returns New connection pool instance
+     */
+    create<T extends IConnection>(name: string, config: ConnectionPoolConfig, createConnection: () => Promise<T>, validateConnection?: (connection: T) => Promise<boolean>): IConnectionPool<T>;
+    /**
+     * Get an existing connection pool instance
+     * @param name Pool name
+     */
+    get<T extends IConnection>(name: string): IConnectionPool<T> | undefined;
+    /**
+     * Get all connection pool instances
+     */
+    getAll(): IConnectionPool[];
+    /**
+     * Drain all connection pools
+     */
+    drainAll(): Promise<void>;
+    /**
+     * Clear all connection pools
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get global connection pool statistics
+     */
+    getGlobalStats(): Record<string, unknown>;
+}