@naman_deep_singh/communication-core 1.0.0

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

@@ -0,0 +1,176 @@
+/**
+ * Serializer interface for communication layer
+ * @packageDocumentation
+ */
+import type { SerializationConfig, SerializationFormat } from '../types/config.js';
+/**
+ * Serialization context
+ */
+export interface SerializationContext {
+    /** Target format */
+    format: SerializationFormat;
+    /** Content type */
+    contentType?: string;
+    /** Character encoding */
+    encoding?: string;
+    /** Custom serialization options */
+    options?: Record<string, unknown>;
+    /** Request/response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Deserialization context
+ */
+export interface DeserializationContext {
+    /** Source format */
+    format: SerializationFormat;
+    /** Content type */
+    contentType?: string;
+    /** Character encoding */
+    encoding?: string;
+    /** Target type (for type-safe deserialization) */
+    targetType?: unknown;
+    /** Custom deserialization options */
+    options?: Record<string, unknown>;
+    /** Request/response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serializer interface for serializing and deserializing data
+ */
+export interface ISerializer {
+    /** Serializer name */
+    readonly name: string;
+    /** Supported formats */
+    readonly supportedFormats: SerializationFormat[];
+    /** Default format */
+    readonly defaultFormat: SerializationFormat;
+    /** Serializer configuration */
+    readonly config: SerializationConfig;
+    /**
+     * Serialize data to a specific format
+     * @param data Data to serialize
+     * @param context Serialization context
+     * @returns Serialized data
+     * @throws {CommunicationError} If serialization fails
+     */
+    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
+     */
+    deserialize<T = unknown>(data: string | Buffer | Uint8Array, context?: Partial<DeserializationContext>): T;
+    /**
+     * 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;
+    /**
+     * Validate data against a schema
+     * @param data Data to validate
+     * @param schema Validation schema
+     * @returns Validation result
+     */
+    validate?(data: unknown, schema: unknown): {
+        valid: boolean;
+        errors?: string[];
+        details?: Record<string, unknown>;
+    };
+    /**
+     * Transform data (e.g., date parsing, bigint handling)
+     * @param data Data to transform
+     * @param direction 'serialize' or 'deserialize'
+     */
+    transform?(data: unknown, direction: 'serialize' | 'deserialize'): unknown;
+    /**
+     * 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>;
+    };
+}
+/**
+ * Serializer factory interface
+ */
+export interface ISerializerFactory {
+    /**
+     * Create a new serializer instance
+     * @param name Serializer name
+     * @param config Serializer configuration
+     * @returns New serializer instance
+     */
+    create(name: string, config?: Partial<SerializationConfig>): ISerializer;
+    /**
+     * Get an existing serializer instance
+     * @param name Serializer name
+     */
+    get(name: string): ISerializer | undefined;
+    /**
+     * Get all serializer instances
+     */
+    getAll(): ISerializer[];
+    /**
+     * Register a custom serializer
+     * @param name Serializer name
+     * @param serializer Serializer instance or constructor
+     */
+    register(name: string, serializer: ISerializer | (new (config: SerializationConfig) => ISerializer)): void;
+    /**
+     * Get available serializer names
+     */
+    getAvailableSerializers(): string[];
+    /**
+     * Get serializer for a specific format
+     * @param format Format
+     * @returns Serializer or undefined
+     */
+    getSerializerForFormat(format: SerializationFormat): ISerializer | undefined;
+}

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

@@ -0,0 +1,189 @@
+/**
+ * Service discovery interface for communication layer
+ * @packageDocumentation
+ */
+import type { ServiceDiscoveryEvent } from '../types/events.js';
+import type { HealthCheckResult, ServiceDiscoveryResult, ServiceInstance, ServiceInstanceFilter, ServiceRegistration, ServiceRegistryConfig, UnwatchFunction, WatchCallback } from '../types/service.js';
+/**
+ * Service discovery interface for discovering and monitoring service instances
+ */
+export interface IServiceDiscoverer {
+    /** Discovery type (kubernetes, consul, etc.) */
+    readonly type: string;
+    /** Discovery configuration */
+    readonly config: ServiceRegistryConfig;
+    /** Whether discovery is currently active */
+    readonly isActive: boolean;
+    /** Last discovery timestamp */
+    readonly lastDiscoveryTime?: number;
+    /** Total services discovered */
+    readonly totalServicesDiscovered: number;
+    /** Total instances discovered */
+    readonly totalInstancesDiscovered: number;
+    /**
+     * 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
+     * @throws {CommunicationError} If discovery fails
+     */
+    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;
+    /**
+     * Register a service instance
+     * @param registration Service registration information
+     * @returns Promise resolving when registration is complete
+     */
+    register?(registration: ServiceRegistration): Promise<void>;
+    /**
+     * Deregister a service instance
+     * @param serviceId Service instance ID
+     * @returns Promise resolving when deregistration is complete
+     */
+    deregister?(serviceId: string): Promise<void>;
+    /**
+     * Update service instance registration
+     * @param serviceId Service instance ID
+     * @param updates Registration updates
+     * @returns Promise resolving when update is complete
+     */
+    updateRegistration?(serviceId: string, updates: Partial<ServiceRegistration>): Promise<void>;
+    /**
+     * Perform health check on service instances
+     * @param serviceName Optional service name to check
+     * @returns Promise resolving to health check results
+     */
+    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>;
+    /**
+     * Start automatic discovery (for poll-based discoverers)
+     */
+    start?(): Promise<void>;
+    /**
+     * Stop automatic discovery
+     */
+    stop?(): Promise<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>;
+    /**
+     * Event emitter for service discovery events
+     */
+    readonly events?: {
+        /**
+         * Subscribe to service discovery events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        on(event: string | string[], listener: (event: ServiceDiscoveryEvent) => void): void;
+        /**
+         * Unsubscribe from service discovery events
+         * @param event Event name or array of events
+         * @param listener Event listener
+         */
+        off(event: string | string[], listener: (event: ServiceDiscoveryEvent) => void): void;
+    };
+}
+/**
+ * Service discovery factory interface
+ */
+export interface IServiceDiscoveryFactory {
+    /**
+     * Create a new service discoverer instance
+     * @param type Discovery type
+     * @param config Discovery configuration
+     * @returns New service discoverer instance
+     */
+    create(type: string, config: ServiceRegistryConfig): IServiceDiscoverer;
+    /**
+     * Get an existing service discoverer instance
+     * @param id Discoverer identifier
+     */
+    get(id: string): IServiceDiscoverer | undefined;
+    /**
+     * Get all service discoverer instances
+     */
+    getAll(): IServiceDiscoverer[];
+    /**
+     * Register a custom service discoverer type
+     * @param type Discoverer type name
+     * @param constructor Discoverer constructor
+     */
+    register(type: string, constructor: new (config: ServiceRegistryConfig) => IServiceDiscoverer): void;
+    /**
+     * Get available service discoverer types
+     */
+    getAvailableTypes(): string[];
+    /**
+     * Close all service discoverer instances
+     */
+    closeAll(): Promise<void>;
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Timeout interface for communication layer
+ * @packageDocumentation
+ */
+import type { TimeoutConfig } from '../types/config.js';
+/**
+ * Timeout options for individual operations
+ */
+export interface TimeoutOptions {
+    /** Operation timeout in milliseconds */
+    timeout?: number;
+    /** Operation name for logging */
+    name?: string;
+    /** Should throw on timeout */
+    throwOnTimeout?: boolean;
+    /** Cleanup function to call on timeout */
+    cleanup?: () => void | Promise<void>;
+    /** Custom error message */
+    errorMessage?: string;
+}
+/**
+ * Timeout manager interface
+ */
+export interface ITimeoutManager {
+    /** Timeout configuration */
+    readonly config: TimeoutConfig;
+    /**
+     * 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;
+    /**
+     * 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>;
+    };
+}
+/**
+ * Timeout manager factory interface
+ */
+export interface ITimeoutManagerFactory {
+    /**
+     * Create a new timeout manager instance
+     * @param name Timeout manager name
+     * @param config Timeout configuration
+     * @returns New timeout manager instance
+     */
+    create(name: string, config?: Partial<TimeoutConfig>): ITimeoutManager;
+    /**
+     * Get an existing timeout manager instance
+     * @param name Timeout manager name
+     */
+    get(name: string): ITimeoutManager | undefined;
+    /**
+     * Get all timeout manager instances
+     */
+    getAll(): ITimeoutManager[];
+    /**
+     * Register a custom timeout manager
+     * @param name Timeout manager name
+     * @param manager Timeout manager instance or constructor
+     */
+    register(name: string, manager: ITimeoutManager | (new (config: TimeoutConfig) => ITimeoutManager)): void;
+    /**
+     * Get available timeout manager names
+     */
+    getAvailableManagers(): string[];
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Interface definitions for communication layer
+ * @packageDocumentation
+ */
+export type { IProtocol, IProtocolFactory, } from './Protocol.interface.js';
+export type { IClient, IClientFactory, } from './Client.interface.js';
+export type { ICircuitBreaker, ICircuitBreakerFactory, } from './CircuitBreaker.interface.js';
+export type { IRetryStrategy, IRetryStrategyFactory, RetryDecision, RetryContext, } from './RetryStrategy.interface.js';
+export type { IServiceDiscoverer, IServiceDiscoveryFactory, } from './ServiceDiscovery.interface.js';
+export type { ILoadBalanceStrategy, ILoadBalancerFactory, } from './LoadBalancer.interface.js';
+export type { ISerializer, ISerializerFactory, SerializationContext, DeserializationContext, } from './Serializer.interface.js';
+export type { IInterceptor, IInterceptorChain, IInterceptorFactory, InterceptorOrder, } from './Interceptor.interface.js';
+export type { ITimeoutManager, ITimeoutManagerFactory, TimeoutOptions, } from './Timeout.interface.js';
+export type { IConnection, IConnectionPool, IConnectionPoolFactory, ConnectionAcquisition, } from './ConnectionPool.interface.js';
+export type { ICompressionManager, ICompressionManagerFactory, CompressionAlgorithm, CompressionOptions, CompressionResult, DecompressionResult, } from './Compression.interface.js';