@naman_deep_singh/communication-core

Version - 1.2.2

> Core interfaces and abstract classes for building a comprehensive service-to-service communication layer in TypeScript

Overview

This package provides the foundational interfaces, abstract base classes, types, and utilities needed to build a complete microservices communication ecosystem. It serves as the architectural foundation for 5 specialized subpackages that handle different aspects of service communication.

Features

- 🔌 Protocol Abstraction: Unified interface for HTTP, gRPC, WebSocket protocols
- 🛡️ Resilience Patterns: Circuit breaker and retry strategy interfaces
- 🔍 Service Discovery: Dynamic service location and health monitoring
- ⚖️ Load Balancing: Traffic distribution strategies
- 🎯 Unified Client: Composable client that orchestrates all components
- 🔧 Connection Pooling: Built-in connection management with health checks
- 📊 Observability: Metrics, events, and health monitoring
- 🚦 Interceptors: Request/response middleware system
- ⚡ TypeScript First: Full type safety with strict import/export patterns

Installation

``bash
npm install @naman_deep_singh/communication-core
`

Core Interfaces

$3


- IProtocol: Base interface for all communication protocols
- IConnectionPool: Connection pooling and lifecycle management
- IInterceptor: Request/response middleware

$3

- ICircuitBreaker: Circuit breaker pattern for fault tolerance
- IRetryStrategy: Configurable retry mechanisms with backoff

$3

- IServiceDiscoverer: Dynamic service instance discovery
- ILoadBalanceStrategy: Traffic distribution algorithms

$3

- IClient: Main client interface that composes all components
- IClientFactory: Factory for creating and managing client instances

Abstract Base Classes

These classes provide common functionality and enforce consistent patterns:

$3

- BaseProtocol: Common protocol functionality (connection pooling, metrics, error handling)
- BaseConnectionPool: Connection lifecycle, health checks, and resource management

$3

- BaseServiceDiscoverer: Caching, health monitoring, and event-driven updates

Type System

$3

- Request/Response: Standardized request/response objects
- ServiceInstance: Service endpoint representation
- ClientConfig: Comprehensive client configuration
- ConnectionPoolConfig: Connection pool settings

$3

- ProtocolConfig: Protocol-specific settings
- CircuitBreakerConfig: Circuit breaker thresholds and timeouts
- RetryConfig: Retry policies and backoff strategies
- LoadBalancerConfig: Load balancing algorithms and weights

$3

- CommunicationError: Base error class with error codes and context
- ConnectionError: Connection-specific errors
- TimeoutError: Request timeout errors
- ServiceUnavailableError: Service discovery errors

Subpackage Architecture

This core package enables building 5 specialized subpackages:

$3

Purpose: Protocol-specific implementations (HTTP, gRPC, WebSocket)

`
communication-protocols/
├── src/
│ ├── http/
│ │ ├── HTTPProtocol.ts # extends BaseProtocol
│ │ ├── HTTPConnectionPool.ts # extends BaseConnectionPool
│ │ └── HTTPInterceptor.ts # implements BaseInterceptor
| | └── index.ts
│ ├── grpc/
│ │ ├── GRPCProtocol.ts # extends BaseProtocol
│ │ ├── GRPCConnectionPool.ts # extends BaseConnectionPool
│ │ └── GRPCInterceptor.ts # implements IInterceptor
| | └── index.ts
│ ├── websocket/
│ │ ├── WebSocketProtocol.ts # extends BaseProtocol
│ │ ├── WebSocketConnectionPool.ts
│ │ └── WebSocketInterceptor.ts
| | └── index.ts
│ └── index.ts
├── package.json
└── README.md
`

Key Dependencies: axios, @grpc/grpc-js, ws

Usage:
`typescript
import { HTTPProtocol } from '@naman_deep_singh/communication-protocols/http';
import { GRPCProtocol } from '@naman_deep_singh/communication-protocols/grpc';
`

$3

Purpose: Fault tolerance patterns (Circuit Breaker, Retry Strategies)

`
communication-resilience/
├── src/
│ ├── circuit-breaker/
│ │ ├── CircuitBreakerImpl.ts # implements ICircuitBreaker
│ │ ├── CircuitBreakerState.ts # State management
│ │ └── CircuitBreakerMetrics.ts # Failure tracking
| | └── index.ts
│ ├── retry/
│ │ ├── ExponentialBackoffRetry.ts # implements IRetryStrategy
│ │ ├── LinearBackoffRetry.ts # implements IRetryStrategy
│ │ ├── FixedDelayRetry.ts # implements IRetryStrategy
│ │ └── JitterRetry.ts # implements IRetryStrategy
| | └── index.ts
│ ├── policies/
│ │ ├── RetryPolicy.ts
│ │ └── CircuitBreakerPolicy.ts
| | └── index.ts
│ └── index.ts
├── package.json
└── README.md
`

Usage:
`typescript
import { CircuitBreakerImpl } from '@naman_deep_singh/communication-resilience/circuit-breaker';
import { ExponentialBackoffRetry } from '@naman_deep_singh/communication-resilience/retry';
`

$3

Purpose: Service discovery implementations (Consul, etcd, Kubernetes)

`
communication-discovery/
├── src/
│ ├── consul/
│ │ ├── ConsulServiceDiscoverer.ts # extends BaseServiceDiscoverer
│ │ ├── ConsulHealthChecker.ts
│ │ └── ConsulWatcher.ts
| | └── index.ts
│ ├── etcd/
│ │ ├── EtcdServiceDiscoverer.ts # extends BaseServiceDiscoverer
│ │ ├── EtcdHealthChecker.ts
│ │ └── EtcdWatcher.ts
| | └── index.ts
│ ├── kubernetes/
│ │ ├── K8sServiceDiscoverer.ts # extends BaseServiceDiscoverer
│ │ ├── K8sHealthChecker.ts
│ │ └── K8sWatcher.ts
| | └── index.ts
│ ├── static/
│ │ └── StaticServiceDiscoverer.ts # For testing/development
| | └── index.ts
│ └── index.ts
├── package.json
└── README.md
`

Key Dependencies: consul, etcd3, @kubernetes/client-node

Usage:
`typescript
import { ConsulServiceDiscoverer } from '@naman_deep_singh/communication-discovery/consul';
import { K8sServiceDiscoverer } from '@naman_deep_singh/communication-discovery/kubernetes';
`

$3

Purpose: Load balancing strategies for traffic distribution

`
communication-load-balancing/
├── src/
│ ├── strategies/
│ │ ├── RoundRobinStrategy.ts # implements ILoadBalanceStrategy
│ │ ├── WeightedRoundRobinStrategy.ts # implements ILoadBalanceStrategy
│ │ ├── LeastConnectionsStrategy.ts # implements ILoadBalanceStrategy
│ │ ├── RandomStrategy.ts # implements ILoadBalanceStrategy
│ │ └── ConsistentHashStrategy.ts # implements ILoadBalanceStrategy
| | └── index.ts
│ ├── health/
│ │ ├── HealthAwareLoadBalancer.ts
│ │ └── HealthScorer.ts
| | └── index.ts
│ ├── metrics/
│ │ ├── LoadBalancerMetrics.ts
│ │ └── ConnectionTracker.ts
| | └── index.ts
│ └── index.ts
├── package.json
└── README.md
`

Usage:
`typescript
import { RoundRobinStrategy } from '@naman_deep_singh/communication-load-balancing/strategies';
import { WeightedRoundRobinStrategy } from '@naman_deep_singh/communication-load-balancing/strategies';
`

$3

Purpose: Unified client that orchestrates all components

`
communication-client/
├── src/
│ ├── client/
│ │ ├── CommunicationClient.ts # implements IClient
│ │ ├── ClientFactory.ts # implements IClientFactory
│ │ └── ClientBuilder.ts # Fluent builder pattern
| | └── index.ts
│ ├── pipeline/
│ │ ├── RequestPipeline.ts
│ │ ├── ResponsePipeline.ts
│ │ └── InterceptorChain.ts
| | └── index.ts
│ ├── middleware/
│ │ ├── LoggingInterceptor.ts
│ │ ├── MetricsInterceptor.ts
│ │ ├── TracingInterceptor.ts
│ │ └── AuthInterceptor.ts
| | └── index.ts
│ ├── events/
│ │ ├── ClientEventEmitter.ts
│ │ └── ClientEvents.ts
| | └── index.ts
│ └── index.ts
├── package.json
└── README.md
`

Usage:
`typescript
import { CommunicationClient, ClientBuilder } from '@naman_deep_singh/communication-client';

// Fluent builder pattern
const client = new ClientBuilder()
.withProtocol(new HTTPProtocol())
.withServiceDiscovery(new ConsulServiceDiscoverer(consulConfig))
.withLoadBalancer(new RoundRobinStrategy())
.withCircuitBreaker(new CircuitBreakerImpl(cbConfig))
.withRetryStrategy(new ExponentialBackoffRetry(retryConfig))
.build('user-service');
`

Development Roadmap

$3


- Implement HTTPProtocol with connection pooling
- Add basic interceptor support
- Create comprehensive tests

$3

- Implement CircuitBreakerImpl with state management
- Add ExponentialBackoffRetry strategy
- Integration testing with HTTP protocol

$3

- Implement ConsulServiceDiscoverer
- Add health checking and caching
- Event-driven service updates

$3

- Implement RoundRobinStrategy
- Add health-aware load balancing
- Performance benchmarking

$3

- Create unified CommunicationClient
- Implement request pipeline
- End-to-end integration testing

Usage Example

`typescript
import {
IClient,
IProtocol,
IServiceDiscoverer,
ILoadBalanceStrategy,
ICircuitBreaker,
IRetryStrategy
} from '@naman_deep_singh/communication-core';

// This core package provides the contracts
// Implementations come from subpackages:

// From communication-protocols
const protocol: IProtocol = new HTTPProtocol({
timeout: 5000,
maxConnections: 100
});

// From communication-discovery
const discovery: IServiceDiscoverer = new ConsulServiceDiscoverer({
host: 'localhost',
port: 8500
});

// From communication-load-balancing
const loadBalancer: ILoadBalanceStrategy = new RoundRobinStrategy();

// From communication-resilience
const circuitBreaker: ICircuitBreaker = new CircuitBreakerImpl({
failureThreshold: 5,
timeout: 60000
});

// From communication-client
const client: IClient = new CommunicationClient({
serviceName: 'user-service',
protocol,
serviceDiscoverer: discovery,
loadBalancer,
circuitBreaker
});

// Make requests
const response = await client.call('/users/123');
``

Key Benefits

- 🔧 Modular Architecture: Use only the components you need
- 🔄 Consistent Patterns: All implementations follow the same interfaces
- 🧪 Easy Testing: Mock interfaces for comprehensive unit testing
- 📈 Extensible: Add new protocols/strategies without breaking changes
- ⚡ Performance: Built-in connection pooling and caching
- 🛡️ Reliable: Circuit breakers and retry mechanisms
- 📊 Observable: Built-in metrics and event system

Contributing

This package follows strict TypeScript patterns:
- No wildcard exports (except root index)
- Type keyword for all type imports
- .js extensions in imports
- Barrel exports in all directories

License

MIT