@riaskov/nevo-messaging 1.1.1 → 1.1.2

package/README.md

@@ -1,23 +1,23 @@
 # Nevo Messaging
 
-A powerful microservices messaging framework for NestJS 11+ with Kafka 4+ transport, designed for building scalable distributed systems with type-safe inter-service communication.
+A powerful microservices messaging framework for NestJS 11+ with multi-transport support (NATS, Kafka, Socket.IO, HTTP/SSE), designed for building scalable distributed systems with type-safe inter-service communication.
 
 ## Features
 
-- 🚀 **Type-safe messaging** - Full TypeScript support with auto-completion
-- 🔄 **Dual communication patterns** - Both request-response (query) and fire-and-forget (emit)
-- 📡 **Subscriptions** - Publish/subscribe updates without direct requests
-- 📢 **Broadcast** - System-wide messages for all connected consumers
-- 🎯 **Signal-based routing** - Declarative method mapping with `@Signal` decorator
-- 📡 **Kafka transport** - Production-ready Apache Kafka integration
-- 🧭 **Service discovery** - Heartbeat-based registry topic
-- 🔐 **Access control** - Topic + method + service-level ACLs
-- 🔌 **Multiple transports** - Kafka, NATS, HTTP (SSE), Socket.IO
-- 🔧 **Auto-configuration** - Automatic topic creation and client setup
-- 🛡️ **Error handling** - Comprehensive error propagation and timeout management
-- 📊 **BigInt support** - Native handling of large integers across services
-- 🪝 **Lifecycle hooks** - Before/after message processing hooks
-- 🔍 **Debug mode** - Built-in logging for development and troubleshooting
+- 🚀 **Type-safe messaging** - Full TypeScript support with auto-completion
+- 🔄 **Dual communication patterns** - Both request-response (query) and fire-and-forget (emit)
+- 📡 **Subscriptions** - Publish/subscribe updates without direct requests
+- 📢 **Broadcast** - System-wide messages for all connected consumers
+- 🎯 **Signal-based routing** - Declarative method mapping with `@Signal` decorator
+- 📡 **Kafka transport** - Production-ready Apache Kafka integration
+- 🧭 **Service discovery** - Heartbeat-based registry topic
+- 🔐 **Access control** - Topic + method + service-level ACLs
+- 🔌 **Multiple transports** - NATS, Kafka, Socket.IO, HTTP (SSE)
+- 🔧 **Auto-configuration** - Automatic topic creation and client setup
+- 🛡️ **Error handling** - Comprehensive error propagation and timeout management
+- 📊 **BigInt support** - Native handling of large integers across services
+- 🪝 **Lifecycle hooks** - Before/after message processing hooks
+- 🔍 **Debug mode** - Built-in logging for development and troubleshooting
 
 ## Installation
 
@@ -28,23 +28,23 @@ npm install @riaskov/nevo-messaging
 ### Peer Dependencies
 
 ```bash
-npm install @nestjs/common @nestjs/core @nestjs/microservices @nestjs/config @nestjs/platform-fastify kafkajs nats socket.io socket.io-client rxjs reflect-metadata
+npm install @nestjs/common @nestjs/core @nestjs/microservices @nestjs/config @nestjs/platform-fastify kafkajs nats socket.io socket.io-client rxjs reflect-metadata
 ```
 
 ## Quick Start
 
-### 1. Basic Service Setup
+### 1. Basic Service Setup (NATS)
 
 Create a simple microservice that responds to messages:
 
 ```typescript
 // user.service.ts
 import { Injectable, Inject } from "@nestjs/common"
-import { KafkaClientBase, NevoKafkaClient } from "@riaskov/nevo-messaging"
+import { NatsClientBase, NevoNatsClient } from "@riaskov/nevo-messaging"
 
 @Injectable()
-export class UserService extends KafkaClientBase {
-  constructor(@Inject("NEVO_KAFKA_CLIENT") nevoClient: NevoKafkaClient) {
+export class UserService extends NatsClientBase {
+  constructor(@Inject("NEVO_NATS_CLIENT") nevoClient: NevoNatsClient) {
     super(nevoClient)
   }
 
@@ -66,11 +66,11 @@ Map service methods to external signals using the `@Signal` decorator:
 ```typescript
 // user.controller.ts
 import { Controller, Inject } from "@nestjs/common"
-import { KafkaSignalRouter, Signal } from "@riaskov/nevo-messaging"
+import { NatsSignalRouter, Signal } from "@riaskov/nevo-messaging"
 import { UserService } from "./user.service"
 
 @Controller()
-@KafkaSignalRouter([UserService])
+@NatsSignalRouter([UserService])
 export class UserController {
   constructor(@Inject(UserService) private readonly userService: UserService) {}
 
@@ -84,13 +84,13 @@ export class UserController {
 
 ### 3. Module Configuration
 
-Configure the module with Kafka client:
+Configure the module with the NATS client:
 
 ```typescript
 // user.module.ts
 import { Module } from "@nestjs/common"
 import { ConfigModule } from "@nestjs/config"
-import { createNevoKafkaClient } from "@riaskov/nevo-messaging"
+import { createNevoNatsClient } from "@riaskov/nevo-messaging"
 import { UserController } from "./user.controller"
 import { UserService } from "./user.service"
 
@@ -99,8 +99,9 @@ import { UserService } from "./user.service"
   controllers: [UserController],
   providers: [
     UserService,
-    createNevoKafkaClient(["COORDINATOR"], {
-      clientIdPrefix: "user"
+    createNevoNatsClient(["COORDINATOR"], {
+      clientIdPrefix: "user",
+      servers: ["nats://127.0.0.1:4222"]
     })
   ]
 })
@@ -109,20 +110,20 @@ export class UserModule {}
 
 ### 4. Application Bootstrap
 
-Start your microservice:
+Start your service:
 
 ```typescript
 // main.ts
-import { createKafkaMicroservice } from "@riaskov/nevo-messaging"
+import { NestFactory } from "@nestjs/core"
 import { AppModule } from "./app.module"
 
-createKafkaMicroservice({
-  microserviceName: "user",
-  module: AppModule,
-  port: 8086
-}).then()
-```
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+  await app.listen(8086)
+}
 
+bootstrap()
+```
 ## Core Concepts
 
 ### Signal Routing
@@ -142,44 +143,44 @@ Use for operations that need a response:
 const user = await this.query("user", "user.getById", { id: 123n })
 ```
 
-#### Emit Pattern (Fire-and-Forget)
-Use for events and notifications:
-
-```typescript
-await this.emit("notifications", "user.created", { userId: 123n, email: "user@example.com" })
-```
-
-#### Subscription Pattern (Publish/Subscribe)
-Use when you want to receive updates without requesting:
-
-```typescript
-const sub = await this.subscribe("user", "user.updated", { ack: true }, async (msg, ctx) => {
-  await ctx.ack()
-})
-
-await sub.unsubscribe()
-```
-
-Publish updates:
-
-```typescript
-await this.publish("user", "user.updated", { userId: 123n })
-```
-
-#### Broadcast Pattern (System-Wide)
-Send to everyone connected to the broker:
-
-```typescript
-await this.broadcast("system.status", { ok: true })
-```
-
-Receive broadcast:
-
-```typescript
-await this.subscribe("__broadcast", "system.status", {}, (msg) => {
-  console.log("System status:", msg)
-})
-```
+#### Emit Pattern (Fire-and-Forget)
+Use for events and notifications:
+
+```typescript
+await this.emit("notifications", "user.created", { userId: 123n, email: "user@example.com" })
+```
+
+#### Subscription Pattern (Publish/Subscribe)
+Use when you want to receive updates without requesting:
+
+```typescript
+const sub = await this.subscribe("user", "user.updated", { ack: true }, async (msg, ctx) => {
+  await ctx.ack()
+})
+
+await sub.unsubscribe()
+```
+
+Publish updates:
+
+```typescript
+await this.publish("user", "user.updated", { userId: 123n })
+```
+
+#### Broadcast Pattern (System-Wide)
+Send to everyone connected to the broker:
+
+```typescript
+await this.broadcast("system.status", { ok: true })
+```
+
+Receive broadcast:
+
+```typescript
+await this.subscribe("__broadcast", "system.status", {}, (msg) => {
+  console.log("System status:", msg)
+})
+```
 
 ## Advanced Usage
 
@@ -295,7 +296,7 @@ export class UserController {
 }
 ```
 
-### Error Handling
+### Error Handling
 
 The framework provides comprehensive error handling:
 
@@ -316,69 +317,69 @@ export class UserService extends KafkaClientBase {
     
     return user
   }
-}
-```
-
-### Method Suggestions (Did You Mean)
-
-If you call a method that doesn't exist, the framework returns a helpful error:
-
-```
-Invalid method name 'user.getByI', did you mean 'user.getById'?
-```
-
-This works for all transports.
-
-### Exponential Backoff (Client-Side)
-
-Clients apply a backoff for **in-flight requests** to avoid sending a duplicate query while the previous one is still being processed.
-
-```typescript
-createNevoKafkaClient(["USER"], {
-  clientIdPrefix: "frontend",
-  backoff: {
-    enabled: true,
-    baseMs: 100,
-    maxMs: 2000,
-    maxAttempts: 0, // 0 = wait until slot is free
-    jitter: true
-  }
-})
-```
-
-This prevents repeated sending of the same request while the service is busy (e.g., stopped on a breakpoint).
-
-### Access Control (ACL)
-
-Restrict who can read messages by topic + method + service:
-
-```typescript
-@KafkaSignalRouter([UserService], {
-  accessControl: {
-    rules: [
-      { topic: "user-events", method: "*", allow: ["frontend", "coordinator"] },
-      { topic: "user-events", method: "user.delete", deny: ["frontend"] }
-    ],
-    logDenied: true
-  }
-})
-export class UserController {}
-```
-
-By default, all services are allowed.
-
-### Service Discovery (Registry Topic)
-
-Each client sends heartbeats to `__nevo.discovery`. You can read the registry:
-
-```typescript
-const services = this.getDiscoveredServices()
-const isUserAvailable = this.isServiceAvailable("user")
-```
-
-Discovery is enabled by default for Kafka/NATS. HTTP and Socket.IO discovery are currently disabled.
-
-## Configuration
+}
+```
+
+### Method Suggestions (Did You Mean)
+
+If you call a method that doesn't exist, the framework returns a helpful error:
+
+```
+Invalid method name 'user.getByI', did you mean 'user.getById'?
+```
+
+This works for all transports.
+
+### Exponential Backoff (Client-Side)
+
+Clients apply a backoff for **in-flight requests** to avoid sending a duplicate query while the previous one is still being processed.
+
+```typescript
+createNevoKafkaClient(["USER"], {
+  clientIdPrefix: "frontend",
+  backoff: {
+    enabled: true,
+    baseMs: 100,
+    maxMs: 2000,
+    maxAttempts: 0, // 0 = wait until slot is free
+    jitter: true
+  }
+})
+```
+
+This prevents repeated sending of the same request while the service is busy (e.g., stopped on a breakpoint).
+
+### Access Control (ACL)
+
+Restrict who can read messages by topic + method + service:
+
+```typescript
+@KafkaSignalRouter([UserService], {
+  accessControl: {
+    rules: [
+      { topic: "user-events", method: "*", allow: ["frontend", "coordinator"] },
+      { topic: "user-events", method: "user.delete", deny: ["frontend"] }
+    ],
+    logDenied: true
+  }
+})
+export class UserController {}
+```
+
+By default, all services are allowed.
+
+### Service Discovery (Registry Topic)
+
+Each client sends heartbeats to `__nevo.discovery`. You can read the registry:
+
+```typescript
+const services = this.getDiscoveredServices()
+const isUserAvailable = this.isServiceAvailable("user")
+```
+
+Discovery is enabled by default for Kafka/NATS. HTTP and Socket.IO discovery are available when enabled (HTTP requires `discoveryUrl`).
+
+## Configuration
 
 ### Environment Variables
 
@@ -392,102 +393,108 @@ NODE_ENV=production
 ### Kafka Client Options
 
 ```typescript
-createNevoKafkaClient(["USER", "INVENTORY", "NOTIFICATIONS"], {
-  clientIdPrefix: "order-service",
-  groupIdPrefix: "order-consumer",
-  sessionTimeout: 30000,
-  allowAutoTopicCreation: true,
-  retryAttempts: 5,
-  brokerRetryTimeout: 2000,
-  timeoutMs: 25000,
-  debug: false,
-  discovery: {
-    enabled: true,
-    heartbeatIntervalMs: 5000,
-    ttlMs: 15000
-  }
-})
-```
+createNevoKafkaClient(["USER", "INVENTORY", "NOTIFICATIONS"], {
+  clientIdPrefix: "order-service",
+  groupIdPrefix: "order-consumer",
+  sessionTimeout: 30000,
+  allowAutoTopicCreation: true,
+  retryAttempts: 5,
+  brokerRetryTimeout: 2000,
+  timeoutMs: 25000,
+  debug: false,
+  discovery: {
+    enabled: true,
+    heartbeatIntervalMs: 5000,
+    ttlMs: 15000
+  }
+})
+```
 
 ### Microservice Startup Options
 
 ```typescript
-createKafkaMicroservice({
-  microserviceName: "user",
-  module: AppModule,
-  port: 8086,
-  host: "0.0.0.0",
-  debug: true,
-  onInit: async (app) => {
-    // Custom initialization logic
-    await app.get(DatabaseService).runMigrations()
-  }
-})
-```
-
-## Transports
-
-### Kafka (default)
-Use `createKafkaMicroservice` + `KafkaSignalRouter` as before.
-
-### NATS
-Client factory:
-
-```typescript
-createNevoNatsClient(["USER", "COORDINATOR"], {
-  clientIdPrefix: "user",
-  servers: ["nats://127.0.0.1:4222"]
-})
-```
-
-Controller decorator:
-
-```typescript
-@NatsSignalRouter([UserService])
-export class UserController {}
-```
-
-### HTTP (SSE)
-HTTP uses plain POST for `query/emit` and SSE for `subscribe`.
-
-```typescript
-@HttpSignalRouter([UserService])
-export class UserController {}
-```
-
-Include transport controller to enable SSE + publish endpoints:
-
-```typescript
-controllers: [UserController, HttpTransportController]
-```
-
-Client:
-
-```typescript
-createNevoHttpClient(
-  { coordinator: "http://127.0.0.1:8091" },
-  { clientIdPrefix: "user" }
-)
-```
-
-### Socket.IO
-Socket.IO server is started inside the router decorator:
-
-```typescript
-@SocketSignalRouter([UserService], { serviceName: "user", port: 8093 })
-export class UserController {}
-```
-
-Client:
-
-```typescript
-createNevoSocketClient(
-  { coordinator: "http://127.0.0.1:8094" },
-  { clientIdPrefix: "user" }
-)
-```
-
-## BigInt Support
+createKafkaMicroservice({
+  microserviceName: "user",
+  module: AppModule,
+  port: 8086,
+  host: "0.0.0.0",
+  debug: true,
+  onInit: async (app) => {
+    // Custom initialization logic
+    await app.get(DatabaseService).runMigrations()
+  }
+})
+```
+
+## Transports
+
+| Transport | Patterns | Discovery | Infra | Notes |
+| --- | --- | --- | --- | --- |
+| NATS | query/emit/publish/subscribe/broadcast | on by default | NATS server | Lowest latency, simple ops |
+| Kafka | query/emit/publish/subscribe/broadcast | on by default | Kafka broker | Durable log, topic setup |
+| Socket.IO | query/emit/publish/subscribe/broadcast | optional | Socket.IO server | WebSocket-friendly apps |
+| HTTP (SSE) | query/emit + SSE subscribe/broadcast | optional | HTTP server | Simple HTTP/SSE integration |
+
+### NATS (priority)
+Client factory:
+
+```typescript
+createNevoNatsClient(["USER", "COORDINATOR"], {
+  clientIdPrefix: "user",
+  servers: ["nats://127.0.0.1:4222"]
+})
+```
+
+Controller decorator:
+
+```typescript
+@NatsSignalRouter([UserService])
+export class UserController {}
+```
+
+### Kafka
+Use `createKafkaMicroservice` + `KafkaSignalRouter` as before.
+
+### Socket.IO
+Socket.IO server is started inside the router decorator:
+
+```typescript
+@SocketSignalRouter([UserService], { serviceName: "user", port: 8093 })
+export class UserController {}
+```
+
+Client:
+
+```typescript
+createNevoSocketClient(
+  { coordinator: "http://127.0.0.1:8094" },
+  { clientIdPrefix: "user" }
+)
+```
+
+### HTTP (SSE)
+HTTP uses plain POST for `query/emit` and SSE for `subscribe`.
+
+```typescript
+@HttpSignalRouter([UserService])
+export class UserController {}
+```
+
+Include transport controller to enable SSE + publish endpoints:
+
+```typescript
+controllers: [UserController, HttpTransportController]
+```
+
+Client:
+
+```typescript
+createNevoHttpClient(
+  { coordinator: "http://127.0.0.1:8091" },
+  { clientIdPrefix: "user" }
+)
+```
+## BigInt Support
 
 The framework automatically handles BigInt serialization across service boundaries:
 
@@ -860,79 +867,22 @@ createNevoKafkaClient(["HIGH_VOLUME_SERVICE"], {
 
 ## API Reference
 
-### Decorators
-
-#### `@Signal(signalName, methodName?, paramTransformer?, resultTransformer?)`
-
-Maps external signals to service methods.
-
-**Parameters:**
-- `signalName` (string): External signal identifier
-- `methodName` (string, optional): Service method name (defaults to signalName)
-- `paramTransformer` (function, optional): Transform incoming parameters
-- `resultTransformer` (function, optional): Transform outgoing results
-
-#### `@KafkaSignalRouter(serviceTypes, options?)`
-
-Class decorator for signal routing setup.
-
-**Parameters:**
-- `serviceTypes` (Type<any> | Type<any>[]): Service classes to route to
-- `options` (object, optional): Configuration options
-
-### Classes
-
-#### `KafkaClientBase`
-
-Base class for services that need to communicate with other microservices.
-
-**Methods:**
-- `query<T>(serviceName, method, params): Promise<T>` - Request-response communication
-- `emit(serviceName, method, params): Promise<void>` - Fire-and-forget communication
-- `publish(serviceName, method, params): Promise<void>` - Publish to subscriptions
-- `subscribe(serviceName, method, options, handler): Promise<Subscription>` - Subscribe to updates
-- `broadcast(method, params): Promise<void>` - System-wide broadcast
-- `getAvailableServices(): string[]` - List registered services
-- `getDiscoveredServices(): DiscoveryEntry[]` - Service registry snapshot
-- `isServiceAvailable(serviceName): boolean` - Availability check
-
-#### `NevoKafkaClient`
-
-Universal Kafka client for multi-service communication.
-
-**Methods:**
-- `query<T>(serviceName, method, params): Promise<T>` - Send query to service
-- `emit(serviceName, method, params): Promise<void>` - Emit event to service
-- `publish(serviceName, method, params): Promise<void>` - Publish to subscriptions
-- `subscribe(serviceName, method, options, handler): Promise<Subscription>` - Subscribe to updates
-- `broadcast(method, params): Promise<void>` - System-wide broadcast
-- `getAvailableServices(): string[]` - Get list of available services
-
-### Functions
+See `API.md`.
 
-#### `createNevoKafkaClient(serviceNames, options)`
+## Examples
 
-Factory function for creating Kafka client providers.
+### NATS
+- `examples/nats-user` - NATS request/response + publish/subscribe + broadcast
 
-#### `createKafkaMicroservice(options)`
+### Kafka
+- `examples/user` - standard Kafka microservice
 
-Bootstrap function for starting NestJS microservices with Kafka transport.
+### Socket.IO
+- `examples/socket-user` - Socket.IO transport with subscribe/broadcast
 
-## Examples
-
-### Kafka
-- `examples/user` - standard Kafka microservice
-
-### NATS
-- `examples/nats-user` - NATS request/response + publish/subscribe + broadcast
-
-### HTTP (SSE)
-- `examples/http-user` - HTTP query/emit + SSE subscribe + broadcast + discovery
-
-### Socket.IO
-- `examples/socket-user` - Socket.IO transport with subscribe/broadcast
-
-## Troubleshooting
+### HTTP (SSE)
+- `examples/http-user` - HTTP query/emit + SSE subscribe + broadcast + discovery
+## Troubleshooting
 
 ### Common Issues
 
@@ -1013,4 +963,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - Examples: Check the `examples/` directory for complete working examples
 
 ## Aux
-There are many anys in core code - the simple temporary solution for changeable Nest.js microservices API.
+There are many anys in core code - the simple temporary solution for changeable Nest.js microservices API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riaskov/nevo-messaging",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Microservices messaging framework for NestJS with NATS/Kafka/SocketIO transport",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",