@lokative/messaging 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lokative (https://lokative.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# @lokative/messaging
+
+A transport-agnostic messaging module for NestJS. Ships with built-in NATS JetStream, Kafka, and Redis transports. Swap transports with a single config change — your handlers and publishers stay the same.
+
+## Installation
+
+```bash
+npm install @lokative/messaging
+```
+
+Install the peer dependency for your chosen transport:
+
+```bash
+# NATS JetStream
+npm install nats
+
+# Kafka
+npm install kafkajs
+
+# Redis
+npm install redis
+```
+
+---
+
+## Quick Start
+
+### NATS JetStream
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MessagingModule, NatsTransport } from '@lokative/messaging';
+
+@Module({
+  imports: [
+    MessagingModule.register({
+      transport: NatsTransport,
+      transportOptions: {
+        servers: ['nats://localhost:4222'],
+      },
+      streams: [
+        { name: 'ORDERS', subjects: ['order.created', 'order.updated'] },
+      ],
+      consumers: {
+        group: 'order-service',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Kafka
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MessagingModule, KafkaTransport } from '@lokative/messaging';
+
+@Module({
+  imports: [
+    MessagingModule.register({
+      transport: KafkaTransport,
+      transportOptions: {
+        brokers: ['localhost:9092'],
+        clientId: 'order-service',
+      },
+      consumers: {
+        group: 'order-service-group',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Redis
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MessagingModule, RedisTransport } from '@lokative/messaging';
+
+@Module({
+  imports: [
+    MessagingModule.register({
+      transport: RedisTransport,
+      transportOptions: {
+        url: 'redis://localhost:6379',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Redis can also be configured with `host` and `port` instead of `url`:
+
+```typescript
+transportOptions: {
+  host: '10.0.0.5',
+  port: 6380,
+}
+```
+
+---
+
+## Configuration
+
+`MessagingModule.register()` accepts a `MessagingConfig` object:
+
+| Property           | Type                        | Required | Description                                      |
+| ------------------ | --------------------------- | -------- | ------------------------------------------------ |
+| `transport`        | `Type<MessagingTransport>`  | Yes      | The transport class to use                       |
+| `transportOptions` | `Record<string, any>`       | No       | Transport-specific connection options             |
+| `streams`          | `{ name, subjects[] }[]`    | No       | Stream/topic definitions (used by NATS transport) |
+| `consumers`        | `ConsumerOptions`           | No       | Consumer group configuration                      |
+
+### Consumer Options
+
+| Property | Type      | Description                                  |
+| -------- | --------- | -------------------------------------------- |
+| `group`  | `string`  | Consumer group / durable name                |
+| `retry`  | `number`  | Number of retry attempts on failure          |
+| `dlq`    | `boolean` | Enable dead-letter queue for failed messages |
+
+### Transport Options
+
+#### `NatsTransportOptions`
+
+| Property  | Type                        | Required | Description                          |
+| --------- | --------------------------- | -------- | ------------------------------------ |
+| `servers` | `string[]`                  | Yes      | NATS server URLs                     |
+| `streams` | `{ name, subjects[] }[]`    | No       | Overrides top-level `streams` config |
+
+#### `KafkaTransportOptions`
+
+| Property   | Type       | Required | Description                        |
+| ---------- | ---------- | -------- | ---------------------------------- |
+| `brokers`  | `string[]` | Yes      | Kafka broker addresses             |
+| `clientId` | `string`   | No       | Client identifier (default: `nestjs-app`) |
+
+#### `RedisTransportOptions`
+
+| Property | Type     | Required | Description                                  |
+| -------- | -------- | -------- | -------------------------------------------- |
+| `url`    | `string` | No       | Redis connection URL (e.g. `redis://localhost:6379`) |
+| `host`   | `string` | No       | Redis host (default: `localhost`)            |
+| `port`   | `number` | No       | Redis port (default: `6379`)                 |
+
+Provide either `url` or `host`/`port`. If both are given, `url` takes precedence.
+
+---
+
+## Decorators
+
+### `@Incoming(subject: string)`
+
+Marks a method as a message handler. The module auto-discovers decorated methods at startup and subscribes them to the given subject.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Incoming } from '@lokative/messaging';
+
+@Injectable()
+export class OrderHandler {
+
+  @Incoming('order.created')
+  async handleOrderCreated(data: any) {
+    console.log('New order:', data);
+    // Auto-acked on success, nak'd on thrown error
+  }
+
+}
+```
+
+### `@Outgoing(subject: string)`
+
+Wraps a method so its return value is automatically published to the given subject. The decorated class must have a `publisher` property (typically injected).
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Outgoing, MessagingPublisher } from '@lokative/messaging';
+
+@Injectable()
+export class OrderService {
+
+  constructor(public publisher: MessagingPublisher) {}
+
+  @Outgoing('order.confirmed')
+  async confirmOrder(orderId: string) {
+    const order = await this.processConfirmation(orderId);
+    return order; // automatically published to 'order.confirmed'
+  }
+
+}
+```
+
+---
+
+## Publishing Messages
+
+Inject `MessagingPublisher` to publish messages manually:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MessagingPublisher } from '@lokative/messaging';
+
+@Injectable()
+export class NotificationService {
+
+  constructor(private publisher: MessagingPublisher) {}
+
+  async notifyUser(userId: string, event: string) {
+    await this.publisher.publish('notification.send', {
+      userId,
+      event,
+      timestamp: Date.now(),
+    });
+  }
+
+}
+```
+
+---
+
+## Transport Comparison
+
+| Feature              | NATS JetStream       | Kafka                | Redis Pub/Sub        |
+| -------------------- | -------------------- | -------------------- | -------------------- |
+| Message persistence  | Yes (streams)        | Yes (log)            | No                   |
+| Consumer groups      | Yes (durable)        | Yes (group id)       | No                   |
+| Ack/Nak              | Yes                  | Auto-commit          | N/A                  |
+| Ordering             | Per-subject          | Per-partition         | Per-channel          |
+| Best for             | Microservices, CQRS  | Event streaming, ETL | Real-time, fire-and-forget |
+
+---
+
+## Custom Transports
+
+Implement the `MessagingTransport` interface to add support for any broker:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import type {
+  MessagingTransport,
+  MessageEnvelope,
+  Subscription,
+  SubscribeOptions,
+  MessagingConfig,
+} from '@lokative/messaging';
+
+@Injectable()
+export class MyCustomTransport implements MessagingTransport {
+
+  constructor(@Inject('MSG_CONFIG') private config: MessagingConfig) {}
+
+  async connect(): Promise<void> {
+    // establish connection using this.config.transportOptions
+  }
+
+  async publish(subject: string, payload: any): Promise<void> {
+    // publish serialized payload to subject/topic
+  }
+
+  async subscribe(subject: string, options?: SubscribeOptions): Promise<Subscription> {
+    // return an async-iterable of MessageEnvelope
+  }
+
+}
+```
+
+Then register it:
+
+```typescript
+MessagingModule.register({
+  transport: MyCustomTransport,
+  transportOptions: { /* ... */ },
+})
+```
+
+### Interface Reference
+
+```typescript
+interface MessagingTransport {
+  connect(): Promise<void>;
+  publish(subject: string, payload: any): Promise<void>;
+  subscribe(subject: string, options?: SubscribeOptions): Promise<Subscription>;
+}
+
+interface MessageEnvelope {
+  subject: string;
+  data: any;
+  ack(): void;
+  nak(): void;
+}
+
+interface Subscription {
+  [Symbol.asyncIterator](): AsyncIterator<MessageEnvelope>;
+}
+
+interface SubscribeOptions {
+  group?: string;
+}
+```
+
+---
+
+## Full Application Example
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { MessagingModule, NatsTransport } from '@lokative/messaging';
+import { OrderModule } from './order/order.module';
+
+@Module({
+  imports: [
+    MessagingModule.register({
+      transport: NatsTransport,
+      transportOptions: {
+        servers: ['nats://localhost:4222'],
+      },
+      streams: [
+        { name: 'ORDERS', subjects: ['order.*'] },
+        { name: 'NOTIFICATIONS', subjects: ['notification.*'] },
+      ],
+      consumers: { group: 'api-service' },
+    }),
+    OrderModule,
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+// order/order.module.ts
+import { Module } from '@nestjs/common';
+import { OrderService } from './order.service';
+import { OrderHandler } from './order.handler';
+
+@Module({
+  providers: [OrderService, OrderHandler],
+  exports: [OrderService],
+})
+export class OrderModule {}
+```
+
+```typescript
+// order/order.service.ts
+import { Injectable } from '@nestjs/common';
+import { MessagingPublisher, Outgoing } from '@lokative/messaging';
+
+@Injectable()
+export class OrderService {
+
+  constructor(public publisher: MessagingPublisher) {}
+
+  @Outgoing('order.created')
+  async createOrder(dto: any) {
+    return { id: '123', ...dto, status: 'created' };
+  }
+
+  async cancelOrder(orderId: string) {
+    await this.publisher.publish('order.cancelled', { orderId });
+  }
+
+}
+```
+
+```typescript
+// order/order.handler.ts
+import { Injectable } from '@nestjs/common';
+import { Incoming } from '@lokative/messaging';
+
+@Injectable()
+export class OrderHandler {
+
+  @Incoming('order.created')
+  async onOrderCreated(data: any) {
+    console.log('Processing new order:', data.id);
+  }
+
+  @Incoming('order.cancelled')
+  async onOrderCancelled(data: any) {
+    console.log('Order cancelled:', data.orderId);
+  }
+
+}
+```
+
+To switch this app to Kafka, change only the module registration:
+
+```typescript
+import { KafkaTransport } from '@lokative/messaging';
+
+MessagingModule.register({
+  transport: KafkaTransport,
+  transportOptions: {
+    brokers: ['localhost:9092'],
+    clientId: 'api-service',
+  },
+  consumers: { group: 'api-service' },
+})
+```
+
+Or to Redis:
+
+```typescript
+import { RedisTransport } from '@lokative/messaging';
+
+MessagingModule.register({
+  transport: RedisTransport,
+  transportOptions: { url: 'redis://localhost:6379' },
+})
+```
+
+No changes needed in services or handlers.
+
+---
+
+## API Reference
+
+### Exports
+
+| Export                     | Type        | Description                                    |
+| -------------------------- | ----------- | ---------------------------------------------- |
+| `MessagingModule`          | Module      | NestJS dynamic module                          |
+| `MessagingPublisher`       | Injectable  | Service for publishing messages                |
+| `MessagingConsumerRegistry`| Injectable  | Auto-discovers and starts `@Incoming` handlers |
+| `MessagingConfig`          | Interface   | Configuration shape for `register()`           |
+| `MessagingTransport`       | Interface   | Contract for custom transports                 |
+| `MessageEnvelope`          | Interface   | Incoming message wrapper                       |
+| `Subscription`             | Interface   | Async-iterable subscription                    |
+| `SubscribeOptions`         | Interface   | Options passed to `subscribe()`                |
+| `MESSAGING_TRANSPORT`      | Token       | DI token for the transport provider            |
+| `NatsTransport`            | Injectable  | Built-in NATS JetStream transport              |
+| `NatsTransportOptions`     | Interface   | Options for `NatsTransport`                    |
+| `KafkaTransport`           | Injectable  | Built-in Kafka transport                       |
+| `KafkaTransportOptions`    | Interface   | Options for `KafkaTransport`                   |
+| `RedisTransport`           | Injectable  | Built-in Redis Pub/Sub transport               |
+| `RedisTransportOptions`    | Interface   | Options for `RedisTransport`                   |
+| `Incoming`                 | Decorator   | Subscribe a method to a subject                |
+| `Outgoing`                 | Decorator   | Auto-publish a method's return value           |
+
+### Injection
+
+```typescript
+// Inject the publisher
+constructor(private publisher: MessagingPublisher) {}
+
+// Inject the raw transport (advanced)
+constructor(@Inject(MESSAGING_TRANSPORT) private transport: MessagingTransport) {}
+```
+
+---
+
+## License
+
+MIT — Made with care by [Lokative](https://lokative.com)

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { MessagingConfig } from './messaging.config';
+export { MessagingTransport, MessageEnvelope, Subscription, SubscribeOptions, MESSAGING_TRANSPORT } from './transport.interface';
+export { Incoming, Outgoing } from './messaging.decorator';
+export { MessagingModule } from './messaging.module';
+export { MessagingPublisher } from './messaging.publisher';
+export { MessagingConsumerRegistry } from './messaging.registry';
+export { NatsTransport, NatsTransportOptions } from './transports/nats.transport';
+export { KafkaTransport, KafkaTransportOptions } from './transports/kafka.transport';
+export { RedisTransport, RedisTransportOptions } from './transports/redis.transport';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { MESSAGING_TRANSPORT } from './transport.interface';
+export { Incoming, Outgoing } from './messaging.decorator';
+export { MessagingModule } from './messaging.module';
+export { MessagingPublisher } from './messaging.publisher';
+export { MessagingConsumerRegistry } from './messaging.registry';
+export { NatsTransport } from './transports/nats.transport';
+export { KafkaTransport } from './transports/kafka.transport';
+export { RedisTransport } from './transports/redis.transport';

package/dist/messaging.config.d.ts

@@ -0,0 +1,15 @@
+import type { Type } from '@nestjs/common';
+import type { MessagingTransport } from './transport.interface';
+export interface MessagingConfig {
+    transport: Type<MessagingTransport>;
+    transportOptions?: Record<string, any>;
+    streams?: {
+        name: string;
+        subjects: string[];
+    }[];
+    consumers?: {
+        group?: string;
+        retry?: number;
+        dlq?: boolean;
+    };
+}

package/dist/messaging.config.js

@@ -0,0 +1 @@
+export {};

package/dist/messaging.decorator.d.ts

@@ -0,0 +1,2 @@
+export declare function Incoming(subject: string): MethodDecorator;
+export declare function Outgoing(subject: string): MethodDecorator;

package/dist/messaging.decorator.js

@@ -0,0 +1,16 @@
+export function Incoming(subject) {
+    return (target, key) => {
+        Reflect.defineMetadata("msg:incoming", { subject }, target[key]);
+    };
+}
+export function Outgoing(subject) {
+    return (target, key, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const result = await original.apply(this, args);
+            const publisher = this.publisher;
+            await publisher.publish(subject, result);
+            return result;
+        };
+    };
+}

package/dist/messaging.module.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from "@nestjs/common";
+import { MessagingConfig } from "./messaging.config";
+export declare class MessagingModule {
+    static register(config: MessagingConfig): DynamicModule;
+}

package/dist/messaging.module.js

@@ -0,0 +1,31 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var MessagingModule_1;
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import { MESSAGING_TRANSPORT } from "./transport.interface";
+import { MessagingPublisher } from "./messaging.publisher";
+import { MessagingConsumerRegistry } from "./messaging.registry";
+let MessagingModule = MessagingModule_1 = class MessagingModule {
+    static register(config) {
+        return {
+            module: MessagingModule_1,
+            imports: [DiscoveryModule],
+            providers: [
+                { provide: "MSG_CONFIG", useValue: config },
+                { provide: MESSAGING_TRANSPORT, useClass: config.transport },
+                MessagingPublisher,
+                MessagingConsumerRegistry,
+            ],
+            exports: [MessagingPublisher],
+        };
+    }
+};
+MessagingModule = MessagingModule_1 = __decorate([
+    Module({})
+], MessagingModule);
+export { MessagingModule };

package/dist/messaging.publisher.d.ts

@@ -0,0 +1,6 @@
+import { MessagingTransport } from "./transport.interface";
+export declare class MessagingPublisher {
+    private transport;
+    constructor(transport: MessagingTransport);
+    publish(subject: string, payload: any): Promise<void>;
+}

package/dist/messaging.publisher.js

@@ -0,0 +1,29 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { MESSAGING_TRANSPORT } from "./transport.interface";
+let MessagingPublisher = class MessagingPublisher {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async publish(subject, payload) {
+        await this.transport.publish(subject, payload);
+    }
+};
+MessagingPublisher = __decorate([
+    Injectable(),
+    __param(0, Inject(MESSAGING_TRANSPORT)),
+    __metadata("design:paramtypes", [Object])
+], MessagingPublisher);
+export { MessagingPublisher };

package/dist/messaging.registry.d.ts

@@ -0,0 +1,12 @@
+import { OnModuleInit } from "@nestjs/common";
+import { DiscoveryService } from "@nestjs/core/discovery";
+import { MessagingTransport } from "./transport.interface";
+import type { MessagingConfig } from "./messaging.config";
+export declare class MessagingConsumerRegistry implements OnModuleInit {
+    private transport;
+    private discovery;
+    private config;
+    constructor(transport: MessagingTransport, discovery: DiscoveryService, config: MessagingConfig);
+    onModuleInit(): Promise<void>;
+    private startConsumer;
+}

package/dist/messaging.registry.js

@@ -0,0 +1,64 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { DiscoveryService } from "@nestjs/core/discovery";
+import { MESSAGING_TRANSPORT } from "./transport.interface";
+let MessagingConsumerRegistry = class MessagingConsumerRegistry {
+    transport;
+    discovery;
+    config;
+    constructor(transport, discovery, config) {
+        this.transport = transport;
+        this.discovery = discovery;
+        this.config = config;
+    }
+    async onModuleInit() {
+        await this.transport.connect();
+        const providers = this.discovery.getProviders();
+        for (const provider of providers) {
+            const instance = provider.instance;
+            if (!instance)
+                continue;
+            const proto = Object.getPrototypeOf(instance);
+            for (const key of Object.getOwnPropertyNames(proto)) {
+                const handler = instance[key];
+                if (typeof handler !== 'function')
+                    continue;
+                const meta = Reflect.getMetadata("msg:incoming", handler);
+                if (!meta)
+                    continue;
+                this.startConsumer(instance, handler, meta);
+            }
+        }
+    }
+    async startConsumer(instance, handler, meta) {
+        const group = this.config.consumers?.group;
+        const sub = await this.transport.subscribe(meta.subject, { group });
+        for await (const msg of sub) {
+            try {
+                await handler.call(instance, msg.data);
+                msg.ack();
+            }
+            catch {
+                msg.nak();
+            }
+        }
+    }
+};
+MessagingConsumerRegistry = __decorate([
+    Injectable(),
+    __param(0, Inject(MESSAGING_TRANSPORT)),
+    __param(2, Inject("MSG_CONFIG")),
+    __metadata("design:paramtypes", [Object, DiscoveryService, Object])
+], MessagingConsumerRegistry);
+export { MessagingConsumerRegistry };

package/dist/transport.interface.d.ts

@@ -0,0 +1,18 @@
+export interface MessageEnvelope {
+    subject: string;
+    data: any;
+    ack(): void;
+    nak(): void;
+}
+export interface Subscription {
+    [Symbol.asyncIterator](): AsyncIterator<MessageEnvelope>;
+}
+export interface MessagingTransport {
+    connect(): Promise<void>;
+    publish(subject: string, payload: any): Promise<void>;
+    subscribe(subject: string, options?: SubscribeOptions): Promise<Subscription>;
+}
+export interface SubscribeOptions {
+    group?: string;
+}
+export declare const MESSAGING_TRANSPORT = "MESSAGING_TRANSPORT";

package/dist/transport.interface.js

@@ -0,0 +1 @@
+export const MESSAGING_TRANSPORT = 'MESSAGING_TRANSPORT';

package/dist/transports/kafka.transport.d.ts

@@ -0,0 +1,15 @@
+import type { MessagingTransport, Subscription, SubscribeOptions } from '../transport.interface';
+import type { MessagingConfig } from '../messaging.config';
+export interface KafkaTransportOptions {
+    brokers: string[];
+    clientId?: string;
+}
+export declare class KafkaTransport implements MessagingTransport {
+    private config;
+    private kafka;
+    private producer;
+    constructor(config: MessagingConfig);
+    connect(): Promise<void>;
+    publish(subject: string, payload: any): Promise<void>;
+    subscribe(subject: string, options?: SubscribeOptions): Promise<Subscription>;
+}

package/dist/transports/kafka.transport.js

@@ -0,0 +1,79 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { Kafka } from 'kafkajs';
+let KafkaTransport = class KafkaTransport {
+    config;
+    kafka;
+    producer;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        const opts = this.config.transportOptions;
+        this.kafka = new Kafka({
+            clientId: opts.clientId ?? 'nestjs-app',
+            brokers: opts.brokers,
+        });
+        this.producer = this.kafka.producer();
+        await this.producer.connect();
+    }
+    async publish(subject, payload) {
+        await this.producer.send({
+            topic: subject,
+            messages: [{ value: JSON.stringify(payload) }],
+        });
+    }
+    async subscribe(subject, options) {
+        const consumer = this.kafka.consumer({
+            groupId: options?.group ?? 'nest-consumer',
+        });
+        await consumer.connect();
+        await consumer.subscribe({ topic: subject, fromBeginning: false });
+        const buffer = [];
+        let waiting = null;
+        await consumer.run({
+            eachMessage: async ({ topic, message }) => {
+                const envelope = {
+                    subject: topic,
+                    data: JSON.parse(message.value?.toString() ?? '{}'),
+                    ack: () => { }, // kafkajs auto-commits offsets
+                    nak: () => { },
+                };
+                if (waiting) {
+                    const resolve = waiting;
+                    waiting = null;
+                    resolve({ done: false, value: envelope });
+                }
+                else {
+                    buffer.push(envelope);
+                }
+            },
+        });
+        const iterator = {
+            next() {
+                if (buffer.length > 0) {
+                    return Promise.resolve({ done: false, value: buffer.shift() });
+                }
+                return new Promise(r => { waiting = r; });
+            },
+        };
+        return { [Symbol.asyncIterator]: () => iterator };
+    }
+};
+KafkaTransport = __decorate([
+    Injectable(),
+    __param(0, Inject('MSG_CONFIG')),
+    __metadata("design:paramtypes", [Object])
+], KafkaTransport);
+export { KafkaTransport };

package/dist/transports/nats.transport.d.ts

@@ -0,0 +1,20 @@
+import type { MessagingTransport, Subscription, SubscribeOptions } from '../transport.interface';
+import type { MessagingConfig } from '../messaging.config';
+export interface NatsTransportOptions {
+    servers: string[];
+    streams?: {
+        name: string;
+        subjects: string[];
+    }[];
+}
+export declare class NatsTransport implements MessagingTransport {
+    private config;
+    private nc;
+    private js;
+    private jsm;
+    constructor(config: MessagingConfig);
+    connect(): Promise<void>;
+    publish(subject: string, payload: any): Promise<void>;
+    subscribe(subject: string, options?: SubscribeOptions): Promise<Subscription>;
+    private ensureStreams;
+}

package/dist/transports/nats.transport.js

@@ -0,0 +1,87 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { connect, consumerOpts } from 'nats';
+let NatsTransport = class NatsTransport {
+    config;
+    nc;
+    js;
+    jsm;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        const opts = this.config.transportOptions;
+        this.nc = await connect({ servers: opts.servers });
+        this.js = this.nc.jetstream();
+        this.jsm = await this.nc.jetstreamManager();
+        await this.ensureStreams(opts.streams ?? this.config.streams ?? []);
+    }
+    async publish(subject, payload) {
+        await this.js.publish(subject, Buffer.from(JSON.stringify(payload)));
+    }
+    async subscribe(subject, options) {
+        const durable = options?.group ?? 'nest-consumer';
+        const opts = consumerOpts();
+        opts.durable(durable);
+        opts.ackExplicit();
+        opts.deliverTo(durable);
+        const sub = await this.js.subscribe(subject, opts);
+        const iterator = {
+            async next() {
+                const result = await sub[Symbol.asyncIterator]().next();
+                if (result.done)
+                    return { done: true, value: undefined };
+                const msg = result.value;
+                return {
+                    done: false,
+                    value: {
+                        subject: msg.subject,
+                        data: JSON.parse(msg.data.toString()),
+                        ack: () => msg.ack(),
+                        nak: () => msg.nak(),
+                    },
+                };
+            },
+        };
+        return { [Symbol.asyncIterator]: () => iterator };
+    }
+    async ensureStreams(streams) {
+        for (const stream of streams) {
+            try {
+                const info = await this.jsm.streams.info(stream.name);
+                const existing = info.config.subjects ?? [];
+                const missing = stream.subjects.filter(s => !existing.includes(s));
+                if (missing.length > 0) {
+                    info.config.subjects = [...existing, ...missing];
+                    await this.jsm.streams.update(stream.name, info.config);
+                }
+            }
+            catch {
+                try {
+                    await this.jsm.streams.add({ name: stream.name, subjects: stream.subjects });
+                }
+                catch (addErr) {
+                    if (addErr?.api_error?.err_code !== 10065)
+                        throw addErr;
+                }
+            }
+        }
+    }
+};
+NatsTransport = __decorate([
+    Injectable(),
+    __param(0, Inject('MSG_CONFIG')),
+    __metadata("design:paramtypes", [Object])
+], NatsTransport);
+export { NatsTransport };

package/dist/transports/redis.transport.d.ts

@@ -0,0 +1,16 @@
+import type { MessagingTransport, Subscription, SubscribeOptions } from '../transport.interface';
+import type { MessagingConfig } from '../messaging.config';
+export interface RedisTransportOptions {
+    url?: string;
+    host?: string;
+    port?: number;
+}
+export declare class RedisTransport implements MessagingTransport {
+    private config;
+    private pub;
+    private sub;
+    constructor(config: MessagingConfig);
+    connect(): Promise<void>;
+    publish(subject: string, payload: any): Promise<void>;
+    subscribe(subject: string, _options?: SubscribeOptions): Promise<Subscription>;
+}

package/dist/transports/redis.transport.js

@@ -0,0 +1,68 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { createClient } from 'redis';
+let RedisTransport = class RedisTransport {
+    config;
+    pub;
+    sub;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        const opts = this.config.transportOptions;
+        const url = opts.url ?? `redis://${opts.host ?? 'localhost'}:${opts.port ?? 6379}`;
+        this.pub = createClient({ url });
+        this.sub = this.pub.duplicate();
+        await this.pub.connect();
+        await this.sub.connect();
+    }
+    async publish(subject, payload) {
+        await this.pub.publish(subject, JSON.stringify(payload));
+    }
+    async subscribe(subject, _options) {
+        const buffer = [];
+        let waiting = null;
+        await this.sub.subscribe(subject, (message, channel) => {
+            const envelope = {
+                subject: channel,
+                data: JSON.parse(message),
+                ack: () => { }, // redis pub/sub has no ack mechanism
+                nak: () => { },
+            };
+            if (waiting) {
+                const resolve = waiting;
+                waiting = null;
+                resolve({ done: false, value: envelope });
+            }
+            else {
+                buffer.push(envelope);
+            }
+        });
+        const iterator = {
+            next() {
+                if (buffer.length > 0) {
+                    return Promise.resolve({ done: false, value: buffer.shift() });
+                }
+                return new Promise(r => { waiting = r; });
+            },
+        };
+        return { [Symbol.asyncIterator]: () => iterator };
+    }
+};
+RedisTransport = __decorate([
+    Injectable(),
+    __param(0, Inject('MSG_CONFIG')),
+    __metadata("design:paramtypes", [Object])
+], RedisTransport);
+export { RedisTransport };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lokative/messaging",
+  "version": "0.1.0",
+  "description": "",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "nats": "^2.0.0",
+    "kafkajs": "^2.0.0",
+    "redis": "^4.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "nats": {
+      "optional": true
+    },
+    "kafkajs": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@types/node": "^25.5.0",
+    "kafkajs": "^2.0.0",
+    "nats": "^2.0.0",
+    "redis": "^4.0.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}