@naman_deep_singh/communication-core 1.0.0

package/dist/types/types/service.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Service discovery and instance types
+ * @packageDocumentation
+ */
+/**
+ * Service instance representation
+ */
+export interface ServiceInstance {
+    /** Unique instance identifier */
+    id: string;
+    /** Service name */
+    serviceName: string;
+    /** Host address */
+    host: string;
+    /** Port number */
+    port: number;
+    /** Protocol (http, https, grpc, etc.) */
+    protocol?: string;
+    /** Health status */
+    status: 'healthy' | 'unhealthy' | 'unknown';
+    /** Last health check timestamp */
+    lastHealthCheck?: number;
+    /** Instance metadata */
+    metadata?: Record<string, unknown>;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Weight for load balancing */
+    weight?: number;
+    /** Zone/region for locality-aware routing */
+    zone?: string;
+    /** Current load/connections */
+    load?: number;
+    /** Instance version */
+    version?: string;
+    /** Instance uptime in milliseconds */
+    uptime?: number;
+    /** Custom health check data */
+    healthData?: Record<string, unknown>;
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Service registration information
+ */
+export interface ServiceRegistration {
+    /** Service name */
+    name: string;
+    /** Service ID */
+    id: string;
+    /** Service address */
+    address: string;
+    /** Service port */
+    port: number;
+    /** Health check configuration */
+    healthCheck?: {
+        /** HTTP endpoint for health checks */
+        http?: string;
+        /** gRPC health check service */
+        grpc?: string;
+        /** TCP health check port */
+        tcp?: number;
+        /** Health check interval in seconds */
+        interval?: number;
+        /** Health check timeout in seconds */
+        timeout?: number;
+        /** Deregister after failed health checks */
+        deregisterAfter?: string;
+        /** Health check headers */
+        headers?: Record<string, string>;
+        /** Health check expected status */
+        expectedStatus?: number;
+    };
+    /** Service tags */
+    tags?: string[];
+    /** Service metadata */
+    meta?: Record<string, unknown>;
+    /** Service version */
+    version?: string;
+    /** Enable/disable service */
+    enabled?: boolean;
+    /** Custom registration data */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Service discovery watch callback
+ */
+export type WatchCallback = (instances: ServiceInstance[]) => void;
+/**
+ * Service discovery unwatch function
+ */
+export type UnwatchFunction = () => void;
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    /** Is the instance healthy? */
+    healthy: boolean;
+    /** Health check timestamp */
+    timestamp: number;
+    /** Response time in milliseconds */
+    responseTime?: number;
+    /** Error if health check failed */
+    error?: string;
+    /** HTTP status code if applicable */
+    statusCode?: number;
+    /** Additional health details */
+    details?: Record<string, unknown>;
+    /** Service instance ID */
+    instanceId?: string;
+}
+/**
+ * Service endpoint configuration
+ */
+export interface ServiceEndpoint {
+    /** Service name */
+    service: string;
+    /** Endpoint path */
+    endpoint: string;
+    /** HTTP method */
+    method?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        /** Maximum retry attempts */
+        attempts?: number;
+        /** Backoff delay in milliseconds */
+        backoff?: number;
+        /** Retry on specific status codes */
+        retryOnStatus?: number[];
+    };
+    /** Circuit breaker configuration */
+    circuitBreaker?: {
+        /** Enable circuit breaker */
+        enabled?: boolean;
+        /** Failure threshold */
+        failureThreshold?: number;
+        /** Reset timeout */
+        resetTimeout?: number;
+    };
+    /** Headers to include */
+    headers?: Record<string, string>;
+    /** Query parameters */
+    query?: Record<string, string | number | boolean>;
+}
+/**
+ * Service dependency configuration
+ */
+export interface ServiceDependency {
+    /** Dependent service name */
+    service: string;
+    /** Dependency type */
+    type: 'hard' | 'soft' | 'optional';
+    /** Required version (semver) */
+    version?: string;
+    /** Health check endpoint */
+    healthEndpoint?: string;
+    /** Timeout for dependency calls in milliseconds */
+    timeout?: number;
+    /** Circuit breaker configuration */
+    circuitBreaker?: {
+        enabled?: boolean;
+        failureThreshold?: number;
+    };
+    /** Fallback configuration */
+    fallback?: {
+        enabled?: boolean;
+        value?: unknown;
+        function?: () => Promise<unknown>;
+    };
+}
+/**
+ * Service metrics
+ */
+export interface ServiceMetrics {
+    /** Total request count */
+    requests: number;
+    /** Success request count */
+    successes: number;
+    /** Error count */
+    errors: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Average response time in milliseconds */
+    avgResponseTime: number;
+    /** P50 response time in milliseconds */
+    p50ResponseTime?: number;
+    /** P95 response time in milliseconds */
+    p95ResponseTime: number;
+    /** P99 response time in milliseconds */
+    p99ResponseTime: number;
+    /** Current active connections */
+    activeConnections: number;
+    /** Total connections handled */
+    totalConnections: number;
+    /** Error rate (0-1) */
+    errorRate: number;
+    /** Throughput (requests per second) */
+    throughput?: number;
+    /** Timestamp of last metrics collection */
+    lastUpdated: number;
+}
+/**
+ * Service registry configuration
+ */
+export interface ServiceRegistryConfig {
+    /** Registry type */
+    type: 'kubernetes' | 'consul' | 'eureka' | 'static' | 'custom';
+    /** Registry endpoint */
+    endpoint?: string;
+    /** Authentication configuration */
+    auth?: {
+        /** Authentication type */
+        type: 'token' | 'basic' | 'tls' | 'none';
+        /** Token for token auth */
+        token?: string;
+        /** Username for basic auth */
+        username?: string;
+        /** Password for basic auth */
+        password?: string;
+        /** TLS certificate */
+        tlsCert?: string | Buffer;
+        /** TLS key */
+        tlsKey?: string | Buffer;
+        /** CA certificate */
+        caCert?: string | Buffer;
+    };
+    /** Cache configuration */
+    cache?: {
+        /** Enable caching */
+        enabled: boolean;
+        /** Cache TTL in milliseconds */
+        ttl: number;
+        /** Maximum cache size */
+        maxSize?: number;
+    };
+    /** Watch for changes */
+    watch?: boolean;
+    /** Watch interval in milliseconds */
+    watchInterval?: number;
+    /** Custom configuration */
+    options?: Record<string, unknown>;
+}
+/**
+ * Service instance filter options
+ */
+export interface ServiceInstanceFilter {
+    /** Filter by status */
+    status?: 'healthy' | 'unhealthy' | 'unknown';
+    /** Filter by tags */
+    tags?: string[];
+    /** Filter by zone/region */
+    zone?: string;
+    /** Filter by version */
+    version?: string;
+    /** Maximum instances to return */
+    limit?: number;
+    /** Custom filter function */
+    filter?: (instance: ServiceInstance) => boolean;
+}
+/**
+ * Service discovery result
+ */
+export interface ServiceDiscoveryResult {
+    /** Service name */
+    serviceName: string;
+    /** Discovered instances */
+    instances: ServiceInstance[];
+    /** Total instances count */
+    total: number;
+    /** Healthy instances count */
+    healthy: number;
+    /** Timestamp of discovery */
+    timestamp: number;
+    /** Discovery source */
+    source: string;
+    /** Next refresh time */
+    nextRefresh?: number;
+}

package/dist/types/utils.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Utilities integration with @naman_deep_singh/utils package
+ * @packageDocumentation
+ */
+import { GenericPool, type Connection as UtilsConnection } from '@naman_deep_singh/utils';
+import type { IConnection } from './interfaces/ConnectionPool.interface.js';
+/**
+ * Connection interface compatible with both packages
+ * Note: The utils package expects isHealthy as a function, not a property
+ */
+export interface Connection extends IConnection, UtilsConnection {
+    /** Is connection healthy? - must be a function in utils package */
+    isHealthy: () => boolean;
+    /** Connection ID */
+    id: string;
+    /** Connection creation time */
+    createdAt: number;
+    /** Last used time */
+    lastUsedAt: number;
+    /** Usage count */
+    usageCount: number;
+    /** Connection metadata */
+    metadata: Record<string, unknown>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+    /**
+     * Health check for connection
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Reset connection state
+     */
+    reset(): Promise<void>;
+}
+/**
+ * Base connection implementation that satisfies both interfaces
+ */
+export declare abstract class BaseConnection implements Connection {
+    abstract readonly id: string;
+    abstract readonly createdAt: number;
+    abstract readonly lastUsedAt: number;
+    abstract readonly usageCount: number;
+    abstract readonly metadata: Record<string, unknown>;
+    abstract isHealthy(): boolean;
+    abstract close(): Promise<void>;
+    abstract healthCheck(): Promise<boolean>;
+    abstract reset(): Promise<void>;
+}
+/**
+ * Timeout utilities wrapper
+ */
+export declare class TimeoutUtils {
+    /**
+     * Execute with timeout
+     */
+    static withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage?: string): Promise<T>;
+    /**
+     * Create delay
+     */
+    static delay(ms: number): Promise<void>;
+    /**
+     * Retry with timeout
+     */
+    static retryWithTimeout<T>(fn: () => Promise<T>, options?: {
+        maxAttempts?: number;
+        timeoutPerAttempt?: number;
+        backoffMultiplier?: number;
+    }): Promise<T>;
+    /**
+     * Create a timeout promise
+     */
+    static createTimeout(timeoutMs: number, message?: string): Promise<never>;
+    /**
+     * Create an abort signal for timeout
+     */
+    static createAbortSignal(timeoutMs: number): AbortSignal;
+    /**
+     * Race promises with timeout
+     */
+    static raceWithTimeout<T>(promises: Promise<T>[], timeoutMs: number, errorMessage?: string): Promise<T>;
+}
+/**
+ * Connection pool configuration
+ */
+export interface ConnectionPoolConfig<T extends Connection> {
+    /** Pool name */
+    name: string;
+    /** Minimum connections in pool */
+    minConnections?: number;
+    /** Maximum connections in pool */
+    maxConnections?: number;
+    /** Connection idle timeout in milliseconds */
+    idleTimeout?: number;
+    /** Connection lifetime in milliseconds */
+    maxLifetime?: number;
+    /** Connection acquisition timeout in milliseconds */
+    acquireTimeout?: number;
+    /** Connection validation interval in milliseconds */
+    validationInterval?: number;
+    /** Enable connection warmup */
+    warmup?: boolean;
+    /** Connection factory function */
+    createConnection: () => Promise<T>;
+    /** Connection validation function */
+    validateConnection?: (connection: T) => boolean;
+}
+/**
+ * Connection pool wrapper
+ */
+export declare class ConnectionPoolUtils {
+    /**
+     * Create a generic connection pool
+     */
+    static createPool<T extends Connection>(config: ConnectionPoolConfig<T>): GenericPool<T>;
+    /**
+     * Create a simple pool with basic configuration
+     */
+    static createSimplePool<T extends Connection>(name: string, createConnection: () => Promise<T>, options?: {
+        minConnections?: number;
+        maxConnections?: number;
+        idleTimeout?: number;
+    }): GenericPool<T>;
+    /**
+     * Create an adapter to convert property-based isHealthy to function-based
+     */
+    static createConnectionAdapter<T extends Record<string, any>>(connection: T & {
+        isHealthy?: boolean | (() => boolean);
+    }, closeFn?: () => Promise<void>, healthCheckFn?: () => Promise<boolean>, resetFn?: () => Promise<void>): Connection;
+}
+/**
+ * Compression utilities wrapper
+ */
+export declare class CompressionUtils {
+    /**
+     * Compression algorithm type
+     */
+    static readonly Algorithm: {
+        readonly GZIP: "gzip";
+        readonly DEFLATE: "deflate";
+        readonly BROTLI: "brotli";
+        readonly NONE: "none";
+    };
+    /**
+     * Compress data
+     */
+    static compress(data: Buffer | string | Uint8Array, options?: {
+        algorithm?: 'gzip' | 'deflate' | 'brotli' | 'none';
+        level?: number;
+    }): Promise<Buffer>;
+    /**
+     * Decompress data
+     */
+    static decompress(data: Buffer | Uint8Array, options?: {
+        algorithm?: 'gzip' | 'deflate' | 'brotli';
+    }): Promise<Buffer>;
+    /**
+     * Compress data with metrics
+     */
+    static compressWithMetrics(data: Buffer | string | Uint8Array, options?: {
+        algorithm?: 'gzip' | 'deflate' | 'brotli';
+        level?: number;
+    }): Promise<{
+        data: Buffer;
+        originalSize: number;
+        compressedSize: number;
+        compressionRatio: number;
+        compressionTime: number;
+    }>;
+    /**
+     * Get optimal compression level based on data size
+     */
+    static getOptimalLevel(dataSize: number): number;
+    /**
+     * Estimate compression ratio for data type
+     */
+    static estimateCompressionRatio(contentType?: string): number;
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@naman_deep_singh/communication-core",
+  "version": "1.0.0",
+  "description": "Core interfaces and abstract classes for building a comprehensive service-to-service communication layer with protocols, resilience patterns, service discovery, and load balancing",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./interfaces": {
+      "import": "./dist/esm/interfaces/index.js",
+      "require": "./dist/cjs/interfaces/index.js",
+      "types": "./dist/types/interfaces/index.d.ts"
+    },
+    "./abstract": {
+      "import": "./dist/esm/abstract/index.js",
+      "require": "./dist/cjs/abstract/index.js",
+      "types": "./dist/types/abstract/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/esm/types/index.js",
+      "require": "./dist/cjs/types/index.js",
+      "types": "./dist/types/types/index.d.ts"
+    },
+    "./errors": {
+      "import": "./dist/esm/errors/index.js",
+      "require": "./dist/cjs/errors/index.js",
+      "types": "./dist/types/errors/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "microservices",
+    "communication",
+    "service-discovery",
+    "load-balancing",
+    "circuit-breaker",
+    "retry",
+    "http",
+    "grpc",
+    "websocket",
+    "resilience",
+    "typescript",
+    "interfaces",
+    "abstract-classes",
+    "connection-pooling",
+    "interceptors"
+  ],
+  "author": "Naman Deep Singh",
+  "license": "MIT",
+  "homepage": "https://github.com/naman_deep_singh/ts-packages/tree/main/packages/communication/core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/naman_deep_singh/ts-packages.git",
+    "directory": "packages/communication/core"
+  },
+  "bugs": {
+    "url": "https://github.com/naman_deep_singh/ts-packages/issues"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@naman_deep_singh/errors": "^2.3.0",
+    "@naman_deep_singh/http-response": "^3.3.1",
+    "@naman_deep_singh/utils": "^2.6.1",
+    "@types/node": "^25.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:types && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rimraf dist",
+    "clean:js": "find src -type f -name \"*.js\" -delete"
+  }
+}