ts-packages 5.0.0 → 5.1.0

package/createTSPackage.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import fs from 'fs'
+import path from 'path'
+
+const fullPkgName = process.argv[2]
+
+if (!fullPkgName) {
+    console.error('❌ Please provide a package name')
+    console.error('👉 Example: node create-ts-package.mjs @naman_deep_singh/utils')
+    process.exit(1)
+}
+
+/**
+ * @scope/pkg -> pkg
+ * pkg -> pkg
+ */
+let pkgFolder = fullPkgName.includes('/')
+    ? fullPkgName.split('/').pop()
+    : fullPkgName
+
+if (pkgFolder.includes('-')) {
+    pkgFolder = pkgFolder.split('-').pop()
+}
+
+const rootDir = path.join(process.cwd(), pkgFolder)
+const srcDir = path.join(rootDir, 'src')
+
+/* -----------------------------
+ * package.json
+ * ---------------------------- */
+const packageJson = {
+    name: fullPkgName,
+    version: '1.0.0',
+    description: `${fullPkgName} package`,
+    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"
+        }
+    },
+    sideEffects: false,
+    files: ['dist', 'README.md'],
+    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',
+        prepublishOnly: 'npm run clean && npm run build',
+        'clean:js': 'find src -type f -name "*.js" -delete',
+    },
+    keywords: [],
+    author: 'Naman Deep Singh',
+    license: 'ISC',
+    packageManager: 'pnpm@10.20.0',
+    devDependencies: {
+        rimraf: '^5.0.5',
+        typescript: '^5.9.3',
+    },
+    dependencies: {
+        '@types/node': '^25.0.1',
+    },
+    publishConfig: {
+        access: 'public',
+    },
+}
+
+/* -----------------------------
+ * README.md
+ * ---------------------------- */
+const readme = `# ${fullPkgName}
+
+> Generated TypeScript package
+
+## Installation
+
+\`\`\`sh
+npm install ${fullPkgName}
+\`\`\`
+
+## Usage
+
+\`\`\`ts
+import '${fullPkgName}'
+\`\`\`
+`
+
+/* -----------------------------
+ * src/index.ts
+ * ---------------------------- */
+const indexTs = `console.log('📦 ${fullPkgName} loaded')\n`
+
+/* -----------------------------
+ * TS Configs
+ * ---------------------------- */
+const tsConfigs = {
+    'tsconfig.types.json': {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: false,
+            declaration: true,
+            emitDeclarationOnly: true,
+            outDir: 'dist/types',
+        },
+        include: ['src'],
+    },
+
+    'tsconfig.cjs.json': {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'CommonJS',
+            moduleResolution: 'Node',
+            strict: true,
+            esModuleInterop: true,
+            outDir: 'dist/cjs',
+        },
+        include: ['src'],
+    },
+
+    'tsconfig.esm.json': {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            strict: true,
+            outDir: 'dist/esm',
+        },
+        include: ['src'],
+    },
+
+    'tsconfig.json': {
+        compilerOptions: {
+            target: 'ES2020',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ['src'],
+        exclude: ['dist', 'node_modules'],
+    },
+}
+
+/* -----------------------------
+ * Create folders
+ * ---------------------------- */
+if (!fs.existsSync(rootDir)) {
+    fs.mkdirSync(rootDir, { recursive: true })
+    console.log(`📁 Created ${pkgFolder}/`)
+}
+
+if (!fs.existsSync(srcDir)) {
+    fs.mkdirSync(srcDir, { recursive: true })
+    console.log('📁 Created src/')
+}
+
+/* -----------------------------
+ * Write base files
+ * ---------------------------- */
+const baseFiles = [
+    { name: 'package.json', content: JSON.stringify(packageJson, null, 2) },
+    { name: 'README.md', content: readme },
+    { name: 'src/index.ts', content: indexTs },
+]
+
+for (const file of baseFiles) {
+    const filePath = path.join(rootDir, file.name)
+
+    if (fs.existsSync(filePath)) {
+        console.log(`⏭️  ${pkgFolder}/${file.name} already exists, skipping`)
+        continue
+    }
+
+    fs.writeFileSync(filePath, file.content, 'utf8')
+    console.log(`✅ Created ${pkgFolder}/${file.name}`)
+}
+
+/* -----------------------------
+ * Write TS configs
+ * ---------------------------- */
+for (const [file, config] of Object.entries(tsConfigs)) {
+    const filePath = path.join(rootDir, file)
+
+    if (fs.existsSync(filePath)) {
+        console.log(`⏭️  ${pkgFolder}/${file} already exists, skipping`)
+        continue
+    }
+
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2), 'utf8')
+    console.log(`✅ Created ${pkgFolder}/${file}`)
+}
+
+console.log('🎉 TypeScript package scaffold complete')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-packages",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "",
   "main": "index.js",
   "type": "module",
@@ -14,13 +14,14 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "publish-cache-pkg": "pnpm --filter ./packages/cache build && pnpm --filter ./packages/cache publish",
+    "publish-communication-core-pkg": "pnpm --filter ./packages/communication/core build && pnpm --filter ./packages/communication/core publish",
     "publish-error-pkg": "pnpm --filter ./packages/errors build && pnpm --filter ./packages/errors publish",
     "publish-utils-pkg": "pnpm --filter ./packages/utils build && pnpm --filter ./packages/utils publish",
     "publish-response-pkg": "pnpm --filter ./packages/http-response build && pnpm --filter ./packages/http-response publish",
     "publish-server-pkg": "pnpm --filter ./packages/server build && pnpm --filter ./packages/server publish",
     "publish-security-pkg": "pnpm --filter ./packages/security build && pnpm --filter ./packages/security publish",
-    "build": "pnpm --filter ./packages/cache build && pnpm --filter ./packages/errors build && pnpm --filter ./packages/utils build && pnpm --filter ./packages/http-response build && pnpm --filter ./packages/server build && pnpm --filter ./packages/security build",
-    "publish-all-pkg": "pnpm publish-server-pkg && pnpm publish-response-pkg && pnpm publish-error-pkg && pnpm publish-utils-pkg && pnpm publish-security-pkg && pnpm publish-cache-pkg",
+    "build": "pnpm --filter ./packages/cache build && pnpm --filter ./packages/communication/core build && pnpm --filter ./packages/errors build && pnpm --filter ./packages/utils build && pnpm --filter ./packages/http-response build && pnpm --filter ./packages/server build && pnpm --filter ./packages/security build",
+    "publish-all-pkg": "pnpm publish-server-pkg && pnpm publish-response-pkg && pnpm publish-error-pkg && pnpm publish-utils-pkg && pnpm publish-security-pkg && pnpm publish-cache-pkg && pnpm publish-communication-core-pkg",
     "clear-cache": "pnpm store prune",
     "organize": "biome check packages/*/src --write",
     "organize-imports": "biome check packages/*/src --write",

package/packages/communication/core/README.md

@@ -0,0 +1,345 @@
+# @naman_deep_singh/communication-core
+
+> 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
+
+### Communication Protocols
+- **`IProtocol`**: Base interface for all communication protocols
+- **`IConnectionPool`**: Connection pooling and lifecycle management
+- **`IInterceptor`**: Request/response middleware
+
+### Resilience & Reliability
+- **`ICircuitBreaker`**: Circuit breaker pattern for fault tolerance
+- **`IRetryStrategy`**: Configurable retry mechanisms with backoff
+
+### Service Discovery & Load Balancing
+- **`IServiceDiscoverer`**: Dynamic service instance discovery
+- **`ILoadBalanceStrategy`**: Traffic distribution algorithms
+
+### Client Orchestration
+- **`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:
+
+### Protocol Layer
+- **`BaseProtocol`**: Common protocol functionality (connection pooling, metrics, error handling)
+- **`BaseConnectionPool`**: Connection lifecycle, health checks, and resource management
+
+### Service Discovery
+- **`BaseServiceDiscoverer`**: Caching, health monitoring, and event-driven updates
+
+## Type System
+
+### Core Types
+- **`Request/Response`**: Standardized request/response objects
+- **`ServiceInstance`**: Service endpoint representation
+- **`ClientConfig`**: Comprehensive client configuration
+- **`ConnectionPoolConfig`**: Connection pool settings
+
+### Configuration Types
+- **`ProtocolConfig`**: Protocol-specific settings
+- **`CircuitBreakerConfig`**: Circuit breaker thresholds and timeouts
+- **`RetryConfig`**: Retry policies and backoff strategies
+- **`LoadBalancerConfig`**: Load balancing algorithms and weights
+
+### Error Handling
+- **`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:
+
+### 1. **@naman_deep_singh/communication-protocols**
+
+**Purpose**: Protocol-specific implementations (HTTP, gRPC, WebSocket)
+
+```
+communication-protocols/
+├── src/
+│   ├── http/
+│   │   ├── HttpProtocol.ts          # extends BaseProtocol
+│   │   ├── HttpConnectionPool.ts    # extends BaseConnectionPool
+│   │   └── HttpInterceptor.ts       # implements IInterceptor
+│   ├── grpc/
+│   │   ├── GrpcProtocol.ts          # extends BaseProtocol
+│   │   ├── GrpcConnectionPool.ts    # extends BaseConnectionPool
+│   │   └── GrpcInterceptor.ts       # implements IInterceptor
+│   ├── websocket/
+│   │   ├── WebSocketProtocol.ts     # extends BaseProtocol
+│   │   ├── WebSocketConnectionPool.ts
+│   │   └── WebSocketInterceptor.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';
+```
+
+### 2. **@naman_deep_singh/communication-resilience**
+
+**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
+│   ├── retry/
+│   │   ├── ExponentialBackoffRetry.ts   # implements IRetryStrategy
+│   │   ├── LinearBackoffRetry.ts        # implements IRetryStrategy
+│   │   ├── FixedDelayRetry.ts           # implements IRetryStrategy
+│   │   └── JitterRetry.ts               # implements IRetryStrategy
+│   ├── policies/
+│   │   ├── RetryPolicy.ts
+│   │   └── CircuitBreakerPolicy.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. **@naman_deep_singh/communication-discovery**
+
+**Purpose**: Service discovery implementations (Consul, etcd, Kubernetes)
+
+```
+communication-discovery/
+├── src/
+│   ├── consul/
+│   │   ├── ConsulServiceDiscoverer.ts   # extends BaseServiceDiscoverer
+│   │   ├── ConsulHealthChecker.ts
+│   │   └── ConsulWatcher.ts
+│   ├── etcd/
+│   │   ├── EtcdServiceDiscoverer.ts     # extends BaseServiceDiscoverer
+│   │   ├── EtcdHealthChecker.ts
+│   │   └── EtcdWatcher.ts
+│   ├── kubernetes/
+│   │   ├── K8sServiceDiscoverer.ts      # extends BaseServiceDiscoverer
+│   │   ├── K8sHealthChecker.ts
+│   │   └── K8sWatcher.ts
+│   ├── static/
+│   │   └── StaticServiceDiscoverer.ts   # For testing/development
+│   └── 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';
+```
+
+### 4. **@naman_deep_singh/communication-load-balancing**
+
+**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
+│   ├── health/
+│   │   ├── HealthAwareLoadBalancer.ts
+│   │   └── HealthScorer.ts
+│   ├── metrics/
+│   │   ├── LoadBalancerMetrics.ts
+│   │   └── ConnectionTracker.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';
+```
+
+### 5. **@naman_deep_singh/communication-client**
+
+**Purpose**: Unified client that orchestrates all components
+
+```
+communication-client/
+├── src/
+│   ├── client/
+│   │   ├── CommunicationClient.ts       # implements IClient
+│   │   ├── ClientFactory.ts             # implements IClientFactory
+│   │   └── ClientBuilder.ts             # Fluent builder pattern
+│   ├── pipeline/
+│   │   ├── RequestPipeline.ts
+│   │   ├── ResponsePipeline.ts
+│   │   └── InterceptorChain.ts
+│   ├── middleware/
+│   │   ├── LoggingInterceptor.ts
+│   │   ├── MetricsInterceptor.ts
+│   │   ├── TracingInterceptor.ts
+│   │   └── AuthInterceptor.ts
+│   ├── events/
+│   │   ├── ClientEventEmitter.ts
+│   │   └── ClientEvents.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
+
+### Phase 1: Protocols Foundation (Week 1-2)
+- Implement `HttpProtocol` with connection pooling
+- Add basic interceptor support
+- Create comprehensive tests
+
+### Phase 2: Resilience Layer (Week 3)
+- Implement `CircuitBreakerImpl` with state management
+- Add `ExponentialBackoffRetry` strategy
+- Integration testing with HTTP protocol
+
+### Phase 3: Service Discovery (Week 4)
+- Implement `ConsulServiceDiscoverer`
+- Add health checking and caching
+- Event-driven service updates
+
+### Phase 4: Load Balancing (Week 5)
+- Implement `RoundRobinStrategy`
+- Add health-aware load balancing
+- Performance benchmarking
+
+### Phase 5: Client Orchestration (Week 6)
+- 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