@fbsm/saga-nestjs 0.0.1-beta.0

package/README.md

@@ -0,0 +1,506 @@
+# @fbsm/saga-nestjs
+
+NestJS integration for the saga choreography library. Provides a dynamic module, decorators for auto-discovery, and injectable providers.
+
+## Installation
+
+```bash
+npm install @fbsm/saga-nestjs @fbsm/saga-core @fbsm/saga-transport-kafka
+```
+
+## API Reference
+
+### `SagaModule`
+
+Dynamic NestJS module. Register once globally.
+
+```typescript
+// Synchronous
+SagaModule.forRoot(options: SagaModuleOptions): DynamicModule
+
+// Asynchronous (e.g., with ConfigService)
+SagaModule.forRootAsync(options: SagaModuleAsyncOptions): DynamicModule
+```
+
+**`SagaModuleOptions`** (extends `RunnerOptions`):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `serviceName` | `string` | — | Consumer group prefix (`${serviceName}-group`) |
+| `transport` | `SagaTransport` | — | Transport implementation (e.g., `KafkaTransport`) |
+| `retryPolicy.maxRetries` | `number` | `3` | Max retry attempts for `SagaRetryableError` |
+| `retryPolicy.initialDelayMs` | `number` | `200` | Initial retry delay in ms (doubles each attempt) |
+| `fromBeginning` | `boolean` | `false` | Read from beginning of topics |
+| `topicPrefix` | `string` | `''` | Prefix prepended to eventType for topic names |
+| `otel.enabled` | `boolean` | `false` | Enable OpenTelemetry tracing and W3C context propagation |
+| `otel.exporterUrl` | `string` | — | OTel exporter URL |
+| `logger` | `SagaLogger` | `ConsoleSagaLogger` | Custom logger |
+
+**Async configuration**:
+```typescript
+SagaModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    serviceName: config.get('SERVICE_NAME'),
+    transport: new KafkaTransport({
+      brokers: config.get('KAFKA_BROKERS').split(','),
+    }),
+  }),
+})
+```
+
+### `@SagaParticipant()`
+
+Class decorator. Marks a class for auto-discovery by the saga runner. Must extend `SagaParticipantBase`.
+
+```typescript
+@Injectable()
+@SagaParticipant()
+export class PaymentParticipant extends SagaParticipantBase {
+  readonly serviceId = 'payment-service';
+}
+```
+
+### `@SagaHandler(...eventTypes, options?)`
+
+Method decorator. Registers a method as the handler for one or more event types. Accepts an optional options object as the last argument.
+
+```typescript
+// Single event type
+@SagaHandler('order.created')
+async handleOrderCreated(event: IncomingEvent, emit: Emit) {}
+
+// Multiple event types
+@SagaHandler('inventory.failed', 'inventory.compensated')
+async handleInventoryIssue(event: IncomingEvent, emit: Emit) {}
+```
+
+**`SagaHandlerOptions`**:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `final` | `boolean` | Marks the handler as the last step. Auto-adds `hint: 'final'` to all emitted events. |
+| `fork` | `boolean \| ForkConfig` | Every `emit()` inside the handler creates a new sub-saga. The framework generates a new `sagaId`, adds `hint: 'fork'`, and propagates `parentSagaId`/`rootSagaId`. |
+
+`final` and `fork` are **mutually exclusive** — using both throws `SagaInvalidHandlerConfigError`.
+
+**Constraint**: Each event type must have exactly one handler across all participants. Duplicate registrations throw `SagaDuplicateHandlerError`.
+
+### `SagaParticipantBase`
+
+Abstract base class for saga participants.
+
+| Property / Method | Type | Description |
+|-------------------|------|-------------|
+| `serviceId` | `string` (abstract) | Unique service identifier |
+| `on` | `Record<string, EventHandler>` | Auto-populated handler registry |
+| `onRetryExhausted?()` | `(event, error, emit) => Promise<void>` | Called when `SagaRetryableError` exceeds `maxRetries` |
+
+### `SagaPublisherProvider`
+
+Injectable service to initiate sagas or emit events. See [Core Functions](../doc/core-functions.md) for detailed semantics.
+
+| Method | Description |
+|--------|-------------|
+| `start(fn, opts?)` | Start a new root saga |
+| `startChild(fn, opts?)` | Start a child saga linked to the current context |
+| `emit(params)` | Emit an event in the current saga context |
+| `emitToParent(params \| fn)` | Emit to the parent saga |
+| `forSaga(sagaId, parentCtx?, causationId?)` | Get a bound `Emit` function for manual use |
+
+### Types
+
+```typescript
+type Emit = <T extends object>(params: EmitParams<T>) => Promise<void>;
+
+interface EmitParams<T extends object = Record<string, unknown>> {
+  eventType: string;       // Event type (also used as topic name)
+  stepName: string;        // Logical step name for tracing
+  stepDescription?: string;
+  payload: T;              // Event payload
+  hint?: EventHint;        // 'compensation' | 'final' | 'fork'
+  key?: string;            // Optional partition key
+}
+
+interface IncomingEvent<T = Record<string, unknown>> {
+  eventId: string;
+  sagaId: string;
+  parentSagaId?: string;
+  rootSagaId: string;
+  causationId: string;
+  eventType: string;
+  sagaName?: string;
+  sagaDescription?: string;
+  stepName: string;
+  stepDescription?: string;
+  occurredAt: string;
+  payload: T;
+  key?: string;
+}
+```
+
+See [Concepts](../doc/concepts.md) for detailed explanations of each field.
+
+---
+
+## Examples
+
+### 1. Simple Handler + Emit
+
+A basic participant that handles one event and emits another.
+
+```typescript
+// payment.participant.ts
+import { Injectable } from '@nestjs/common';
+import {
+  SagaParticipant,
+  SagaParticipantBase,
+  SagaHandler,
+} from '@fbsm/saga-nestjs';
+import type { IncomingEvent, Emit } from '@fbsm/saga-core';
+
+@Injectable()
+@SagaParticipant()
+export class PaymentParticipant extends SagaParticipantBase {
+  readonly serviceId = 'payment-service';
+
+  @SagaHandler('order.created')
+  async handleOrderCreated(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { orderId, amount } = event.payload as {
+      orderId: string;
+      amount: number;
+    };
+
+    // Process payment...
+    const transactionId = `txn-${Date.now()}`;
+
+    await emit({
+      eventType: 'payment.completed',
+      stepName: 'process-payment',
+      payload: { orderId, transactionId, amount },
+    });
+  }
+}
+```
+
+```typescript
+// orders.controller.ts
+import { Controller, Post, Body } from '@nestjs/common';
+import { SagaPublisherProvider } from '@fbsm/saga-nestjs';
+
+@Controller('orders')
+export class OrdersController {
+  constructor(private readonly sagaPublisher: SagaPublisherProvider) {}
+
+  @Post()
+  async create(@Body() body: { amount: number }) {
+    const { sagaId } = await this.sagaPublisher.start(async () => {
+      await this.sagaPublisher.emit({
+        eventType: 'order.created',
+        stepName: 'create-order',
+        payload: { orderId: `order-${Date.now()}`, amount: body.amount },
+      });
+    });
+
+    return { sagaId };
+  }
+}
+```
+
+**Flow**: `POST /orders` → `order.created` → `PaymentParticipant` → `payment.completed`
+
+### 2. Complex: Fork + Fan-Out
+
+A handler that forks N sub-sagas and coordinates their completion via `emitToParent()`.
+
+```typescript
+// bulk-orchestration.participant.ts
+import { Injectable } from '@nestjs/common';
+import {
+  SagaParticipant,
+  SagaParticipantBase,
+  SagaHandler,
+  SagaPublisherProvider,
+} from '@fbsm/saga-nestjs';
+import type { IncomingEvent, Emit } from '@fbsm/saga-core';
+
+@Injectable()
+@SagaParticipant()
+export class BulkOrchestrationParticipant extends SagaParticipantBase {
+  readonly serviceId = 'bulk-orchestration';
+
+  private completionCount = new Map<string, { total: number; done: number }>();
+
+  constructor(private readonly sagaPublisher: SagaPublisherProvider) {
+    super();
+  }
+
+  // Each emit() inside this handler creates a separate sub-saga
+  @SagaHandler('bulk.requested', { fork: true })
+  async handleBulkRequested(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { batchId, items } = event.payload as {
+      batchId: string;
+      items: string[];
+    };
+
+    this.completionCount.set(batchId, { total: items.length, done: 0 });
+
+    // N emits = N sub-sagas (each gets its own sagaId)
+    for (const item of items) {
+      await emit({
+        eventType: 'item.processing.requested',
+        stepName: 'request-item-processing',
+        payload: { batchId, item },
+      });
+    }
+  }
+
+  // Called when each sub-saga completes
+  @SagaHandler('item.processing.completed')
+  async handleItemCompleted(event: IncomingEvent): Promise<void> {
+    const { batchId } = event.payload as { batchId: string };
+
+    const counter = this.completionCount.get(batchId);
+    if (!counter) return;
+
+    counter.done++;
+
+    // Fan-in: when all sub-sagas complete, notify parent
+    if (counter.done >= counter.total) {
+      this.completionCount.delete(batchId);
+
+      await this.sagaPublisher.emitToParent({
+        eventType: 'bulk.completed',
+        stepName: 'complete-bulk',
+        payload: { batchId, totalProcessed: counter.total },
+        hint: 'final',
+      });
+    }
+  }
+}
+```
+
+```typescript
+// item-processor.participant.ts
+@Injectable()
+@SagaParticipant()
+export class ItemProcessorParticipant extends SagaParticipantBase {
+  readonly serviceId = 'item-processor';
+
+  @SagaHandler('item.processing.requested', { final: true })
+  async handleProcessing(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { batchId, item } = event.payload as {
+      batchId: string;
+      item: string;
+    };
+
+    // Process item...
+
+    await emit({
+      eventType: 'item.processing.completed',
+      stepName: 'process-item',
+      payload: { batchId, item, status: 'done' },
+    });
+    // hint: 'final' auto-added by framework
+  }
+}
+```
+
+**Flow**:
+```
+POST /bulk → bulk.requested [fork x N]
+  Sub-saga 1: item.processing.requested → item.processing.completed [final]
+  Sub-saga 2: item.processing.requested → item.processing.completed [final]
+  Sub-saga N: item.processing.requested → item.processing.completed [final]
+  ← emitToParent() when all complete
+→ bulk.completed [final]
+```
+
+### 3. AsyncLocalStorage Context (Fork + Final)
+
+Full flow showing how AsyncLocalStorage context propagates through `start()` → handler → fork → final → `emitToParent()`.
+
+```typescript
+// orchestration.participant.ts
+@Injectable()
+@SagaParticipant()
+export class OrchestrationParticipant extends SagaParticipantBase {
+  readonly serviceId = 'orchestration';
+
+  // Fork: each emit creates a sub-saga with its own context
+  // Inside the handler, SagaContext.current() returns the PARENT saga context
+  // The framework wraps each emit in a NEW context for the sub-saga
+  @SagaHandler('task.requested', { fork: true })
+  async handleTaskRequested(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { taskId } = event.payload as { taskId: string };
+
+    // This emit runs in a sub-saga context automatically:
+    // - New sagaId generated
+    // - parentSagaId = event.sagaId (the parent)
+    // - rootSagaId inherited
+    // - hint: 'fork' auto-added
+    await emit({
+      eventType: 'validation.requested',
+      stepName: 'request-validation',
+      payload: { taskId },
+    });
+  }
+
+  // Parent receives the result when sub-saga calls emitToParent()
+  @SagaHandler('task.completed', { final: true })
+  async handleTaskCompleted(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { taskId, result } = event.payload as {
+      taskId: string;
+      result: string;
+    };
+
+    await emit({
+      eventType: 'task.done',
+      stepName: 'finish-task',
+      payload: { taskId, result },
+    });
+    // hint: 'final' auto-added
+  }
+}
+```
+
+```typescript
+// validator.participant.ts
+@Injectable()
+@SagaParticipant()
+export class ValidatorParticipant extends SagaParticipantBase {
+  readonly serviceId = 'validator';
+
+  constructor(private readonly sagaPublisher: SagaPublisherProvider) {
+    super();
+  }
+
+  // Final handler in the sub-saga
+  @SagaHandler('validation.requested', { final: true })
+  async handleValidation(event: IncomingEvent, emit: Emit): Promise<void> {
+    const { taskId } = event.payload as { taskId: string };
+
+    // Emit within the sub-saga (hint: 'final' auto-added)
+    await emit({
+      eventType: 'validation.completed',
+      stepName: 'validate',
+      payload: { taskId, valid: true },
+    });
+
+    // Report back to parent saga
+    // emitToParent reads parentSagaId from AsyncLocalStorage
+    await this.sagaPublisher.emitToParent({
+      eventType: 'task.completed',
+      stepName: 'report-to-parent',
+      payload: { taskId, result: 'validated' },
+    });
+  }
+}
+```
+
+```typescript
+// controller
+@Post('tasks')
+async createTask() {
+  // start() creates a root saga context in AsyncLocalStorage
+  const { sagaId } = await this.sagaPublisher.start(async () => {
+    // emit() reads sagaId from ALS automatically
+    await this.sagaPublisher.emit({
+      eventType: 'task.requested',
+      stepName: 'create-task',
+      payload: { taskId: `task-${Date.now()}` },
+    });
+  });
+  return { sagaId };
+}
+```
+
+**Context flow**:
+```
+start() → ALS context: { sagaId: A, rootSagaId: A }
+  → task.requested (handler runs in context A)
+    → fork creates: { sagaId: B, rootSagaId: A, parentSagaId: A }
+      → validation.requested (handler runs in context B)
+        → emit() reads from ALS → publishes on saga B
+        → emitToParent() reads parentSagaId from ALS → publishes on saga A
+  → task.completed (handler runs in context A, { final: true })
+    → task.done [final]
+```
+
+### 4. Manual Mode (Without AsyncLocalStorage)
+
+For when you need full control or can't use callbacks (e.g., Express middleware, testing).
+
+```typescript
+import { Controller, Post, Body } from '@nestjs/common';
+import { v7 as uuidv7 } from 'uuid';
+import { SagaPublisherProvider } from '@fbsm/saga-nestjs';
+
+@Controller('orders')
+export class ManualOrdersController {
+  constructor(private readonly sagaPublisher: SagaPublisherProvider) {}
+
+  @Post()
+  async create(@Body() body: { amount: number }) {
+    // Generate your own saga ID
+    const sagaId = uuidv7();
+
+    // Get a bound emit function (no ALS needed)
+    const emit = this.sagaPublisher.forSaga(sagaId);
+
+    await emit({
+      eventType: 'order.created',
+      stepName: 'create-order',
+      payload: { orderId: `order-${Date.now()}`, amount: body.amount },
+    });
+
+    return { sagaId };
+  }
+
+  @Post('with-child')
+  async createWithChild(@Body() body: { amount: number }) {
+    const sagaId = uuidv7();
+    const rootEmit = this.sagaPublisher.forSaga(sagaId);
+
+    await rootEmit({
+      eventType: 'order.created',
+      stepName: 'create-order',
+      payload: { orderId: `order-${Date.now()}`, amount: body.amount },
+    });
+
+    // Manually create a child saga
+    const childSagaId = uuidv7();
+    const childEmit = this.sagaPublisher.forSaga(childSagaId, {
+      parentSagaId: sagaId,
+      rootSagaId: sagaId,
+    }, sagaId); // causationId
+
+    await childEmit({
+      eventType: 'fulfillment.started',
+      stepName: 'start-fulfillment',
+      payload: { orderId: `order-${Date.now()}` },
+    });
+
+    return { sagaId, childSagaId };
+  }
+}
+```
+
+**When to use manual mode**:
+- Testing: create emit functions with known saga IDs
+- Non-callback patterns: when wrapping in a callback is impractical
+- Migration: gradually adopting the library in existing code
+- External triggers: when the saga ID is provided externally
+
+> **Tip**: Prefer the callback style (`start(fn)`) for new code — it handles context propagation automatically and is less error-prone.
+
+---
+
+## Further Reading
+
+- [Concepts](../doc/concepts.md) — sagaId, hint, eventType, and other domain terms
+- [Core Functions](../doc/core-functions.md) — detailed semantics of emit, emitToParent, etc.
+- [@fbsm/saga-core API](../saga-core/README.md) — framework-agnostic core reference
+- [@fbsm/saga-transport-kafka API](../saga-transport-kafka/README.md) — Kafka transport options
+- [Example Projects](../../examples/README.md) — production-realistic demo applications

package/dist/index.cjs

@@ -0,0 +1,290 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SAGA_OPTIONS_TOKEN: () => SAGA_OPTIONS_TOKEN,
+  SAGA_TRANSPORT_TOKEN: () => SAGA_TRANSPORT_TOKEN,
+  SagaDuplicateHandlerError: () => import_saga_core4.SagaDuplicateHandlerError,
+  SagaError: () => import_saga_core4.SagaError,
+  SagaHandler: () => SagaHandler,
+  SagaModule: () => SagaModule,
+  SagaParseError: () => import_saga_core4.SagaParseError,
+  SagaParticipant: () => SagaParticipant,
+  SagaParticipantBase: () => SagaParticipantBase,
+  SagaPublisherProvider: () => SagaPublisherProvider,
+  SagaRetryableError: () => import_saga_core4.SagaRetryableError,
+  SagaTransportNotConnectedError: () => import_saga_core4.SagaTransportNotConnectedError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/saga.module.ts
+var import_common3 = require("@nestjs/common");
+var import_core2 = require("@nestjs/core");
+var import_saga_core3 = require("@fbsm/saga-core");
+
+// src/constants.ts
+var SAGA_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("SAGA_OPTIONS_TOKEN");
+var SAGA_TRANSPORT_TOKEN = /* @__PURE__ */ Symbol("SAGA_TRANSPORT_TOKEN");
+var SAGA_PARTICIPANT_METADATA = /* @__PURE__ */ Symbol("SAGA_PARTICIPANT_METADATA");
+var SAGA_HANDLER_METADATA = /* @__PURE__ */ Symbol("SAGA_HANDLER_METADATA");
+var SAGA_HANDLER_OPTIONS_METADATA = /* @__PURE__ */ Symbol("SAGA_HANDLER_OPTIONS_METADATA");
+
+// src/providers/saga-runner.provider.ts
+var import_common = require("@nestjs/common");
+var import_core = require("@nestjs/core");
+var import_saga_core = require("@fbsm/saga-core");
+var SagaRunnerProvider = class {
+  constructor(discoveryService, registry, runner) {
+    this.discoveryService = discoveryService;
+    this.registry = registry;
+    this.runner = runner;
+  }
+  logger = new import_common.Logger("SagaRunner");
+  async onModuleInit() {
+    const providers = this.discoveryService.getProviders();
+    for (const wrapper of providers) {
+      const instance = wrapper.instance;
+      if (!instance || !instance.constructor) {
+        continue;
+      }
+      const isParticipant = Reflect.getMetadata(
+        SAGA_PARTICIPANT_METADATA,
+        instance.constructor
+      );
+      if (!isParticipant) {
+        continue;
+      }
+      const handlesMap = Reflect.getMetadata(SAGA_HANDLER_METADATA, instance.constructor);
+      if (!handlesMap || handlesMap.size === 0) {
+        continue;
+      }
+      const on = {};
+      for (const [eventType, methodName] of handlesMap.entries()) {
+        const method = instance[methodName];
+        if (typeof method === "function") {
+          on[eventType] = method.bind(instance);
+        }
+      }
+      if ("on" in instance && typeof instance.on === "object") {
+        Object.assign(instance.on, on);
+      }
+      const handlerOptionsMap = Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, instance.constructor);
+      const handlerOptions = {};
+      if (handlerOptionsMap) {
+        for (const [eventType, opts] of handlerOptionsMap.entries()) {
+          handlerOptions[eventType] = { final: opts.final, fork: !!opts.fork };
+        }
+      }
+      const serviceId = instance.serviceId ?? "unknown";
+      this.logger.log(
+        `Registered participant "${serviceId}" handling: [${Object.keys(on).join(", ")}]`
+      );
+      this.registry.register({
+        serviceId,
+        on,
+        handlerOptions: Object.keys(handlerOptions).length > 0 ? handlerOptions : void 0,
+        onRetryExhausted: typeof instance.onRetryExhausted === "function" ? instance.onRetryExhausted.bind(instance) : void 0
+      });
+    }
+    await this.runner.start();
+  }
+  async onModuleDestroy() {
+    await this.runner.stop();
+  }
+};
+SagaRunnerProvider = __decorateClass([
+  (0, import_common.Injectable)(),
+  __decorateParam(0, (0, import_common.Inject)(import_core.DiscoveryService)),
+  __decorateParam(1, (0, import_common.Inject)(import_saga_core.SagaRegistry)),
+  __decorateParam(2, (0, import_common.Inject)(import_saga_core.SagaRunner))
+], SagaRunnerProvider);
+
+// src/providers/saga-publisher.provider.ts
+var import_common2 = require("@nestjs/common");
+var import_saga_core2 = require("@fbsm/saga-core");
+var SagaPublisherProvider = class {
+  constructor(publisher) {
+    this.publisher = publisher;
+  }
+  start(fn, opts) {
+    return this.publisher.start(fn, opts);
+  }
+  startChild(fn, opts) {
+    return this.publisher.startChild(fn, opts);
+  }
+  emit(params) {
+    return this.publisher.emit(params);
+  }
+  emitToParent(paramsOrFn) {
+    return this.publisher.emitToParent(paramsOrFn);
+  }
+  forSaga(sagaId, parentCtx, causationId) {
+    return this.publisher.forSaga(sagaId, parentCtx, causationId);
+  }
+};
+SagaPublisherProvider = __decorateClass([
+  (0, import_common2.Injectable)(),
+  __decorateParam(0, (0, import_common2.Inject)(import_saga_core2.SagaPublisher))
+], SagaPublisherProvider);
+
+// src/saga.module.ts
+var SagaModule = class {
+  static forRoot(options) {
+    const otelCtx = (0, import_saga_core3.createOtelContext)(options.otel?.enabled ?? false);
+    const registry = new import_saga_core3.SagaRegistry();
+    const parser = new import_saga_core3.SagaParser(otelCtx);
+    const publisher = new import_saga_core3.SagaPublisher(options.transport, otelCtx, options.topicPrefix);
+    const runner = new import_saga_core3.SagaRunner(registry, options.transport, publisher, parser, options, otelCtx, options.logger);
+    return {
+      module: SagaModule,
+      imports: [import_core2.DiscoveryModule],
+      global: true,
+      providers: [
+        { provide: SAGA_OPTIONS_TOKEN, useValue: options },
+        { provide: SAGA_TRANSPORT_TOKEN, useValue: options.transport },
+        { provide: import_saga_core3.SagaRegistry, useValue: registry },
+        { provide: import_saga_core3.SagaParser, useValue: parser },
+        { provide: import_saga_core3.SagaPublisher, useValue: publisher },
+        { provide: import_saga_core3.SagaRunner, useValue: runner },
+        SagaRunnerProvider,
+        SagaPublisherProvider
+      ],
+      exports: [SagaPublisherProvider, import_saga_core3.SagaPublisher, SAGA_OPTIONS_TOKEN]
+    };
+  }
+  static forRootAsync(options) {
+    const asyncProviders = [
+      {
+        provide: SAGA_OPTIONS_TOKEN,
+        useFactory: options.useFactory,
+        inject: options.inject ?? []
+      },
+      {
+        provide: SAGA_TRANSPORT_TOKEN,
+        useFactory: (opts) => opts.transport,
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: import_saga_core3.SagaRegistry,
+        useFactory: () => new import_saga_core3.SagaRegistry()
+      },
+      {
+        provide: import_saga_core3.SagaParser,
+        useFactory: (opts) => {
+          const otelCtx = (0, import_saga_core3.createOtelContext)(opts.otel?.enabled ?? false);
+          return new import_saga_core3.SagaParser(otelCtx);
+        },
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: import_saga_core3.SagaPublisher,
+        useFactory: (opts) => {
+          const otelCtx = (0, import_saga_core3.createOtelContext)(opts.otel?.enabled ?? false);
+          return new import_saga_core3.SagaPublisher(opts.transport, otelCtx, opts.topicPrefix);
+        },
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: import_saga_core3.SagaRunner,
+        useFactory: (registry, publisher, parser, opts) => {
+          const otelCtx = (0, import_saga_core3.createOtelContext)(opts.otel?.enabled ?? false);
+          return new import_saga_core3.SagaRunner(registry, opts.transport, publisher, parser, opts, otelCtx, opts.logger);
+        },
+        inject: [import_saga_core3.SagaRegistry, import_saga_core3.SagaPublisher, import_saga_core3.SagaParser, SAGA_OPTIONS_TOKEN]
+      }
+    ];
+    return {
+      module: SagaModule,
+      imports: [...options.imports ?? [], import_core2.DiscoveryModule],
+      global: true,
+      providers: [...asyncProviders, SagaRunnerProvider, SagaPublisherProvider],
+      exports: [SagaPublisherProvider, import_saga_core3.SagaPublisher, SAGA_OPTIONS_TOKEN]
+    };
+  }
+};
+SagaModule = __decorateClass([
+  (0, import_common3.Module)({})
+], SagaModule);
+
+// src/decorators/saga-handler.decorator.ts
+function SagaHandler(...args) {
+  let eventTypes;
+  let options = {};
+  const lastArg = args[args.length - 1];
+  if (typeof lastArg === "object" && lastArg !== null) {
+    options = lastArg;
+    eventTypes = args.slice(0, -1);
+  } else {
+    eventTypes = args;
+  }
+  return (target, propertyKey) => {
+    const existingMap = Reflect.getMetadata(SAGA_HANDLER_METADATA, target.constructor) ?? /* @__PURE__ */ new Map();
+    const existingOptions = Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, target.constructor) ?? /* @__PURE__ */ new Map();
+    for (const eventType of eventTypes) {
+      existingMap.set(eventType, propertyKey);
+      if (options.final || options.fork) {
+        existingOptions.set(eventType, options);
+      }
+    }
+    Reflect.defineMetadata(SAGA_HANDLER_METADATA, existingMap, target.constructor);
+    Reflect.defineMetadata(SAGA_HANDLER_OPTIONS_METADATA, existingOptions, target.constructor);
+  };
+}
+
+// src/decorators/saga-participant.decorator.ts
+function SagaParticipant() {
+  return (target) => {
+    Reflect.defineMetadata(SAGA_PARTICIPANT_METADATA, true, target);
+  };
+}
+
+// src/saga-participant-base.ts
+var SagaParticipantBase = class {
+  on = {};
+};
+
+// src/index.ts
+var import_saga_core4 = require("@fbsm/saga-core");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SAGA_OPTIONS_TOKEN,
+  SAGA_TRANSPORT_TOKEN,
+  SagaDuplicateHandlerError,
+  SagaError,
+  SagaHandler,
+  SagaModule,
+  SagaParseError,
+  SagaParticipant,
+  SagaParticipantBase,
+  SagaPublisherProvider,
+  SagaRetryableError,
+  SagaTransportNotConnectedError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/saga.module.ts","../src/constants.ts","../src/providers/saga-runner.provider.ts","../src/providers/saga-publisher.provider.ts","../src/decorators/saga-handler.decorator.ts","../src/decorators/saga-participant.decorator.ts","../src/saga-participant-base.ts"],"sourcesContent":["// Module\nexport { SagaModule } from './saga.module';\n\n// Provider\nexport { SagaPublisherProvider } from './providers/saga-publisher.provider';\n\n// Decorators\nexport { SagaHandler } from './decorators/saga-handler.decorator';\nexport type { SagaHandlerOptions } from './decorators/saga-handler.decorator';\nexport { SagaParticipant } from './decorators/saga-participant.decorator';\n\n// Base class\nexport { SagaParticipantBase } from './saga-participant-base';\n\n// Constants (tokens for advanced usage)\nexport { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN } from './constants';\n\n// Options\nexport type { SagaModuleOptions, SagaModuleAsyncOptions } from './saga-module-options.interface';\n\n// Re-exports from core for consumer convenience\nexport {\n  SagaError,\n  SagaRetryableError,\n  SagaDuplicateHandlerError,\n  SagaParseError,\n  SagaTransportNotConnectedError,\n} from '@fbsm/saga-core';\nexport type {\n  SagaEvent,\n  IncomingEvent,\n  Emit,\n  EmitParams,\n  EventHint,\n  EventHandler,\n  ParentSagaContext,\n  HandlerConfig,\n  SagaTransport,\n} from '@fbsm/saga-core';\n","import { Module, DynamicModule, type Provider } from '@nestjs/common';\nimport { DiscoveryModule } from '@nestjs/core';\nimport {\n  SagaRunner,\n  SagaRegistry,\n  SagaPublisher,\n  SagaParser,\n  createOtelContext,\n} from '@fbsm/saga-core';\nimport { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN } from './constants';\nimport type { SagaModuleOptions, SagaModuleAsyncOptions } from './saga-module-options.interface';\nimport { SagaRunnerProvider } from './providers/saga-runner.provider';\nimport { SagaPublisherProvider } from './providers/saga-publisher.provider';\n\n@Module({})\nexport class SagaModule {\n  static forRoot(options: SagaModuleOptions): DynamicModule {\n    const otelCtx = createOtelContext(options.otel?.enabled ?? false);\n    const registry = new SagaRegistry();\n    const parser = new SagaParser(otelCtx);\n    const publisher = new SagaPublisher(options.transport, otelCtx, options.topicPrefix);\n    const runner = new SagaRunner(registry, options.transport, publisher, parser, options, otelCtx, options.logger);\n\n    return {\n      module: SagaModule,\n      imports: [DiscoveryModule],\n      global: true,\n      providers: [\n        { provide: SAGA_OPTIONS_TOKEN, useValue: options },\n        { provide: SAGA_TRANSPORT_TOKEN, useValue: options.transport },\n        { provide: SagaRegistry, useValue: registry },\n        { provide: SagaParser, useValue: parser },\n        { provide: SagaPublisher, useValue: publisher },\n        { provide: SagaRunner, useValue: runner },\n        SagaRunnerProvider,\n        SagaPublisherProvider,\n      ],\n      exports: [SagaPublisherProvider, SagaPublisher, SAGA_OPTIONS_TOKEN],\n    };\n  }\n\n  static forRootAsync(options: SagaModuleAsyncOptions): DynamicModule {\n    const asyncProviders: Provider[] = [\n      {\n        provide: SAGA_OPTIONS_TOKEN,\n        useFactory: options.useFactory,\n        inject: options.inject ?? [],\n      },\n      {\n        provide: SAGA_TRANSPORT_TOKEN,\n        useFactory: (opts: SagaModuleOptions) => opts.transport,\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaRegistry,\n        useFactory: () => new SagaRegistry(),\n      },\n      {\n        provide: SagaParser,\n        useFactory: (opts: SagaModuleOptions) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaParser(otelCtx);\n        },\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaPublisher,\n        useFactory: (opts: SagaModuleOptions) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaPublisher(opts.transport, otelCtx, opts.topicPrefix);\n        },\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaRunner,\n        useFactory: (\n          registry: SagaRegistry,\n          publisher: SagaPublisher,\n          parser: SagaParser,\n          opts: SagaModuleOptions,\n        ) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaRunner(registry, opts.transport, publisher, parser, opts, otelCtx, opts.logger);\n        },\n        inject: [SagaRegistry, SagaPublisher, SagaParser, SAGA_OPTIONS_TOKEN],\n      },\n    ];\n\n    return {\n      module: SagaModule,\n      imports: [...(options.imports ?? []), DiscoveryModule],\n      global: true,\n      providers: [...asyncProviders, SagaRunnerProvider, SagaPublisherProvider],\n      exports: [SagaPublisherProvider, SagaPublisher, SAGA_OPTIONS_TOKEN],\n    };\n  }\n}\n","export const SAGA_OPTIONS_TOKEN = Symbol('SAGA_OPTIONS_TOKEN');\nexport const SAGA_TRANSPORT_TOKEN = Symbol('SAGA_TRANSPORT_TOKEN');\nexport const SAGA_PARTICIPANT_METADATA = Symbol('SAGA_PARTICIPANT_METADATA');\nexport const SAGA_HANDLER_METADATA = Symbol('SAGA_HANDLER_METADATA');\nexport const SAGA_HANDLER_OPTIONS_METADATA = Symbol('SAGA_HANDLER_OPTIONS_METADATA');\n","import { Inject, Injectable, Logger, OnModuleInit, OnModuleDestroy } from '@nestjs/common';\nimport { DiscoveryService } from '@nestjs/core';\nimport { SagaRunner, SagaRegistry } from '@fbsm/saga-core';\nimport type { EventHandler } from '@fbsm/saga-core';\nimport { SAGA_PARTICIPANT_METADATA, SAGA_HANDLER_METADATA, SAGA_HANDLER_OPTIONS_METADATA } from '../constants';\nimport type { SagaHandlerOptions } from '../decorators/saga-handler.decorator';\nimport type { HandlerConfig } from '@fbsm/saga-core';\n\n@Injectable()\nexport class SagaRunnerProvider implements OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger('SagaRunner');\n\n  constructor(\n    @Inject(DiscoveryService) private readonly discoveryService: DiscoveryService,\n    @Inject(SagaRegistry) private readonly registry: SagaRegistry,\n    @Inject(SagaRunner) private readonly runner: SagaRunner,\n  ) {}\n\n  async onModuleInit(): Promise<void> {\n    const providers = this.discoveryService.getProviders();\n\n    for (const wrapper of providers) {\n      const instance = wrapper.instance;\n      if (!instance || !instance.constructor) {\n        continue;\n      }\n\n      const isParticipant = Reflect.getMetadata(\n        SAGA_PARTICIPANT_METADATA,\n        instance.constructor,\n      );\n\n      if (!isParticipant) {\n        continue;\n      }\n\n      const handlesMap: Map<string, string | symbol> | undefined =\n        Reflect.getMetadata(SAGA_HANDLER_METADATA, instance.constructor);\n\n      if (!handlesMap || handlesMap.size === 0) {\n        continue;\n      }\n\n      const on: Record<string, EventHandler<any>> = {};\n      \n      for (const [eventType, methodName] of handlesMap.entries()) {\n        const method = (instance as any)[methodName];\n        if (typeof method === 'function') {\n          on[eventType] = method.bind(instance);\n        }\n      }\n\n      // Populate the `on` property if instance extends SagaParticipantBase\n      if ('on' in instance && typeof instance.on === 'object') {\n        Object.assign(instance.on, on);\n      }\n\n      // Extract handler options (final, fork, etc.) from decorator metadata\n      const handlerOptionsMap: Map<string, SagaHandlerOptions> | undefined =\n        Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, instance.constructor);\n\n      const handlerOptions: Record<string, HandlerConfig> = {};\n      if (handlerOptionsMap) {\n        for (const [eventType, opts] of handlerOptionsMap.entries()) {\n          handlerOptions[eventType] = { final: opts.final, fork: !!opts.fork };\n        }\n      }\n\n      const serviceId = (instance as any).serviceId ?? 'unknown';\n      this.logger.log(\n        `Registered participant \"${serviceId}\" handling: [${Object.keys(on).join(', ')}]`,\n      );\n\n      this.registry.register({\n        serviceId,\n        on,\n        handlerOptions: Object.keys(handlerOptions).length > 0 ? handlerOptions : undefined,\n        onRetryExhausted:\n          typeof (instance as any).onRetryExhausted === 'function'\n            ? (instance as any).onRetryExhausted.bind(instance)\n            : undefined,\n      });\n    }\n\n    await this.runner.start();\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    await this.runner.stop();\n  }\n}\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { Emit, EmitParams, ParentSagaContext, SagaStartOptions } from '@fbsm/saga-core';\nimport { SagaPublisher } from '@fbsm/saga-core';\n\n@Injectable()\nexport class SagaPublisherProvider {\n  constructor(@Inject(SagaPublisher) private readonly publisher: SagaPublisher) {}\n\n  start<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{ sagaId: string; result: Awaited<R> }> {\n    return this.publisher.start(fn, opts);\n  }\n\n  startChild<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{ sagaId: string; result: Awaited<R> }> {\n    return this.publisher.startChild(fn, opts);\n  }\n\n  emit<T extends object>(params: EmitParams<T>): Promise<void> {\n    return this.publisher.emit(params);\n  }\n\n  emitToParent<T extends object>(paramsOrFn: EmitParams<T> | (() => void | Promise<void>)): Promise<void> {\n    return this.publisher.emitToParent(paramsOrFn);\n  }\n\n  forSaga(sagaId: string, parentCtx?: ParentSagaContext, causationId?: string): Emit {\n    return this.publisher.forSaga(sagaId, parentCtx, causationId);\n  }\n}\n","import { SAGA_HANDLER_METADATA, SAGA_HANDLER_OPTIONS_METADATA } from '../constants';\n\nimport type { ForkConfig } from '@fbsm/saga-core';\n\nexport interface SagaHandlerOptions {\n  final?: boolean;\n  fork?: boolean | ForkConfig;\n}\n\nexport function SagaHandler(\n  ...args: [...string[]] | [...string[], SagaHandlerOptions]\n): MethodDecorator {\n  let eventTypes: string[];\n  let options: SagaHandlerOptions = {};\n\n  const lastArg = args[args.length - 1];\n  if (typeof lastArg === 'object' && lastArg !== null) {\n    options = lastArg as SagaHandlerOptions;\n    eventTypes = args.slice(0, -1) as string[];\n  } else {\n    eventTypes = args as string[];\n  }\n\n  return (target, propertyKey) => {\n    const existingMap: Map<string, string | symbol> =\n      Reflect.getMetadata(SAGA_HANDLER_METADATA, target.constructor) ?? new Map();\n    const existingOptions: Map<string, SagaHandlerOptions> =\n      Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, target.constructor) ?? new Map();\n\n    for (const eventType of eventTypes) {\n      existingMap.set(eventType, propertyKey);\n      if (options.final || options.fork) {\n        existingOptions.set(eventType, options);\n      }\n    }\n\n    Reflect.defineMetadata(SAGA_HANDLER_METADATA, existingMap, target.constructor);\n    Reflect.defineMetadata(SAGA_HANDLER_OPTIONS_METADATA, existingOptions, target.constructor);\n  };\n}\n","import { SAGA_PARTICIPANT_METADATA } from '../constants';\n\nexport function SagaParticipant(): ClassDecorator {\n  return (target) => {\n    Reflect.defineMetadata(SAGA_PARTICIPANT_METADATA, true, target);\n  };\n}\n","import type {\n  SagaParticipant,\n  EventHandler,\n  IncomingEvent,\n  Emit,\n} from '@fbsm/saga-core';\nimport { SagaRetryableError } from '@fbsm/saga-core';\n\nexport abstract class SagaParticipantBase implements SagaParticipant {\n  abstract readonly serviceId: string;\n\n  readonly on: Record<string, EventHandler<any>> = {};\n\n  onRetryExhausted?(\n    event: IncomingEvent,\n    error: SagaRetryableError,\n    emit: Emit,\n  ): Promise<void>;\n}\n"],"mappings":"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","names":["import_common","import_core","import_saga_core","import_common","import_saga_core","import_saga_core"]}

package/dist/index.d.cts

@@ -0,0 +1,57 @@
+import { DynamicModule } from '@nestjs/common';
+import { RunnerOptions, SagaTransport, SagaLogger, SagaPublisher, SagaStartOptions, EmitParams, ParentSagaContext, Emit, ForkConfig, SagaParticipant as SagaParticipant$1, EventHandler, IncomingEvent, SagaRetryableError } from '@fbsm/saga-core';
+export { Emit, EmitParams, EventHandler, EventHint, HandlerConfig, IncomingEvent, ParentSagaContext, SagaDuplicateHandlerError, SagaError, SagaEvent, SagaParseError, SagaRetryableError, SagaTransport, SagaTransportNotConnectedError } from '@fbsm/saga-core';
+
+interface SagaModuleOptions extends RunnerOptions {
+    transport: SagaTransport;
+    otel?: {
+        enabled: boolean;
+        exporterUrl?: string;
+    };
+    logger?: SagaLogger;
+}
+interface SagaModuleAsyncOptions {
+    useFactory: (...args: any[]) => Promise<SagaModuleOptions> | SagaModuleOptions;
+    inject?: any[];
+    imports?: any[];
+}
+
+declare class SagaModule {
+    static forRoot(options: SagaModuleOptions): DynamicModule;
+    static forRootAsync(options: SagaModuleAsyncOptions): DynamicModule;
+}
+
+declare class SagaPublisherProvider {
+    private readonly publisher;
+    constructor(publisher: SagaPublisher);
+    start<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{
+        sagaId: string;
+        result: Awaited<R>;
+    }>;
+    startChild<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{
+        sagaId: string;
+        result: Awaited<R>;
+    }>;
+    emit<T extends object>(params: EmitParams<T>): Promise<void>;
+    emitToParent<T extends object>(paramsOrFn: EmitParams<T> | (() => void | Promise<void>)): Promise<void>;
+    forSaga(sagaId: string, parentCtx?: ParentSagaContext, causationId?: string): Emit;
+}
+
+interface SagaHandlerOptions {
+    final?: boolean;
+    fork?: boolean | ForkConfig;
+}
+declare function SagaHandler(...args: [...string[]] | [...string[], SagaHandlerOptions]): MethodDecorator;
+
+declare function SagaParticipant(): ClassDecorator;
+
+declare abstract class SagaParticipantBase implements SagaParticipant$1 {
+    abstract readonly serviceId: string;
+    readonly on: Record<string, EventHandler<any>>;
+    onRetryExhausted?(event: IncomingEvent, error: SagaRetryableError, emit: Emit): Promise<void>;
+}
+
+declare const SAGA_OPTIONS_TOKEN: unique symbol;
+declare const SAGA_TRANSPORT_TOKEN: unique symbol;
+
+export { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN, SagaHandler, type SagaHandlerOptions, SagaModule, type SagaModuleAsyncOptions, type SagaModuleOptions, SagaParticipant, SagaParticipantBase, SagaPublisherProvider };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { DynamicModule } from '@nestjs/common';
+import { RunnerOptions, SagaTransport, SagaLogger, SagaPublisher, SagaStartOptions, EmitParams, ParentSagaContext, Emit, ForkConfig, SagaParticipant as SagaParticipant$1, EventHandler, IncomingEvent, SagaRetryableError } from '@fbsm/saga-core';
+export { Emit, EmitParams, EventHandler, EventHint, HandlerConfig, IncomingEvent, ParentSagaContext, SagaDuplicateHandlerError, SagaError, SagaEvent, SagaParseError, SagaRetryableError, SagaTransport, SagaTransportNotConnectedError } from '@fbsm/saga-core';
+
+interface SagaModuleOptions extends RunnerOptions {
+    transport: SagaTransport;
+    otel?: {
+        enabled: boolean;
+        exporterUrl?: string;
+    };
+    logger?: SagaLogger;
+}
+interface SagaModuleAsyncOptions {
+    useFactory: (...args: any[]) => Promise<SagaModuleOptions> | SagaModuleOptions;
+    inject?: any[];
+    imports?: any[];
+}
+
+declare class SagaModule {
+    static forRoot(options: SagaModuleOptions): DynamicModule;
+    static forRootAsync(options: SagaModuleAsyncOptions): DynamicModule;
+}
+
+declare class SagaPublisherProvider {
+    private readonly publisher;
+    constructor(publisher: SagaPublisher);
+    start<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{
+        sagaId: string;
+        result: Awaited<R>;
+    }>;
+    startChild<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{
+        sagaId: string;
+        result: Awaited<R>;
+    }>;
+    emit<T extends object>(params: EmitParams<T>): Promise<void>;
+    emitToParent<T extends object>(paramsOrFn: EmitParams<T> | (() => void | Promise<void>)): Promise<void>;
+    forSaga(sagaId: string, parentCtx?: ParentSagaContext, causationId?: string): Emit;
+}
+
+interface SagaHandlerOptions {
+    final?: boolean;
+    fork?: boolean | ForkConfig;
+}
+declare function SagaHandler(...args: [...string[]] | [...string[], SagaHandlerOptions]): MethodDecorator;
+
+declare function SagaParticipant(): ClassDecorator;
+
+declare abstract class SagaParticipantBase implements SagaParticipant$1 {
+    abstract readonly serviceId: string;
+    readonly on: Record<string, EventHandler<any>>;
+    onRetryExhausted?(event: IncomingEvent, error: SagaRetryableError, emit: Emit): Promise<void>;
+}
+
+declare const SAGA_OPTIONS_TOKEN: unique symbol;
+declare const SAGA_TRANSPORT_TOKEN: unique symbol;
+
+export { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN, SagaHandler, type SagaHandlerOptions, SagaModule, type SagaModuleAsyncOptions, type SagaModuleOptions, SagaParticipant, SagaParticipantBase, SagaPublisherProvider };

package/dist/index.js

@@ -0,0 +1,267 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/saga.module.ts
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+import {
+  SagaRunner as SagaRunner2,
+  SagaRegistry as SagaRegistry2,
+  SagaPublisher as SagaPublisher2,
+  SagaParser,
+  createOtelContext
+} from "@fbsm/saga-core";
+
+// src/constants.ts
+var SAGA_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("SAGA_OPTIONS_TOKEN");
+var SAGA_TRANSPORT_TOKEN = /* @__PURE__ */ Symbol("SAGA_TRANSPORT_TOKEN");
+var SAGA_PARTICIPANT_METADATA = /* @__PURE__ */ Symbol("SAGA_PARTICIPANT_METADATA");
+var SAGA_HANDLER_METADATA = /* @__PURE__ */ Symbol("SAGA_HANDLER_METADATA");
+var SAGA_HANDLER_OPTIONS_METADATA = /* @__PURE__ */ Symbol("SAGA_HANDLER_OPTIONS_METADATA");
+
+// src/providers/saga-runner.provider.ts
+import { Inject, Injectable, Logger } from "@nestjs/common";
+import { DiscoveryService } from "@nestjs/core";
+import { SagaRunner, SagaRegistry } from "@fbsm/saga-core";
+var SagaRunnerProvider = class {
+  constructor(discoveryService, registry, runner) {
+    this.discoveryService = discoveryService;
+    this.registry = registry;
+    this.runner = runner;
+  }
+  logger = new Logger("SagaRunner");
+  async onModuleInit() {
+    const providers = this.discoveryService.getProviders();
+    for (const wrapper of providers) {
+      const instance = wrapper.instance;
+      if (!instance || !instance.constructor) {
+        continue;
+      }
+      const isParticipant = Reflect.getMetadata(
+        SAGA_PARTICIPANT_METADATA,
+        instance.constructor
+      );
+      if (!isParticipant) {
+        continue;
+      }
+      const handlesMap = Reflect.getMetadata(SAGA_HANDLER_METADATA, instance.constructor);
+      if (!handlesMap || handlesMap.size === 0) {
+        continue;
+      }
+      const on = {};
+      for (const [eventType, methodName] of handlesMap.entries()) {
+        const method = instance[methodName];
+        if (typeof method === "function") {
+          on[eventType] = method.bind(instance);
+        }
+      }
+      if ("on" in instance && typeof instance.on === "object") {
+        Object.assign(instance.on, on);
+      }
+      const handlerOptionsMap = Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, instance.constructor);
+      const handlerOptions = {};
+      if (handlerOptionsMap) {
+        for (const [eventType, opts] of handlerOptionsMap.entries()) {
+          handlerOptions[eventType] = { final: opts.final, fork: !!opts.fork };
+        }
+      }
+      const serviceId = instance.serviceId ?? "unknown";
+      this.logger.log(
+        `Registered participant "${serviceId}" handling: [${Object.keys(on).join(", ")}]`
+      );
+      this.registry.register({
+        serviceId,
+        on,
+        handlerOptions: Object.keys(handlerOptions).length > 0 ? handlerOptions : void 0,
+        onRetryExhausted: typeof instance.onRetryExhausted === "function" ? instance.onRetryExhausted.bind(instance) : void 0
+      });
+    }
+    await this.runner.start();
+  }
+  async onModuleDestroy() {
+    await this.runner.stop();
+  }
+};
+SagaRunnerProvider = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(DiscoveryService)),
+  __decorateParam(1, Inject(SagaRegistry)),
+  __decorateParam(2, Inject(SagaRunner))
+], SagaRunnerProvider);
+
+// src/providers/saga-publisher.provider.ts
+import { Inject as Inject2, Injectable as Injectable2 } from "@nestjs/common";
+import { SagaPublisher } from "@fbsm/saga-core";
+var SagaPublisherProvider = class {
+  constructor(publisher) {
+    this.publisher = publisher;
+  }
+  start(fn, opts) {
+    return this.publisher.start(fn, opts);
+  }
+  startChild(fn, opts) {
+    return this.publisher.startChild(fn, opts);
+  }
+  emit(params) {
+    return this.publisher.emit(params);
+  }
+  emitToParent(paramsOrFn) {
+    return this.publisher.emitToParent(paramsOrFn);
+  }
+  forSaga(sagaId, parentCtx, causationId) {
+    return this.publisher.forSaga(sagaId, parentCtx, causationId);
+  }
+};
+SagaPublisherProvider = __decorateClass([
+  Injectable2(),
+  __decorateParam(0, Inject2(SagaPublisher))
+], SagaPublisherProvider);
+
+// src/saga.module.ts
+var SagaModule = class {
+  static forRoot(options) {
+    const otelCtx = createOtelContext(options.otel?.enabled ?? false);
+    const registry = new SagaRegistry2();
+    const parser = new SagaParser(otelCtx);
+    const publisher = new SagaPublisher2(options.transport, otelCtx, options.topicPrefix);
+    const runner = new SagaRunner2(registry, options.transport, publisher, parser, options, otelCtx, options.logger);
+    return {
+      module: SagaModule,
+      imports: [DiscoveryModule],
+      global: true,
+      providers: [
+        { provide: SAGA_OPTIONS_TOKEN, useValue: options },
+        { provide: SAGA_TRANSPORT_TOKEN, useValue: options.transport },
+        { provide: SagaRegistry2, useValue: registry },
+        { provide: SagaParser, useValue: parser },
+        { provide: SagaPublisher2, useValue: publisher },
+        { provide: SagaRunner2, useValue: runner },
+        SagaRunnerProvider,
+        SagaPublisherProvider
+      ],
+      exports: [SagaPublisherProvider, SagaPublisher2, SAGA_OPTIONS_TOKEN]
+    };
+  }
+  static forRootAsync(options) {
+    const asyncProviders = [
+      {
+        provide: SAGA_OPTIONS_TOKEN,
+        useFactory: options.useFactory,
+        inject: options.inject ?? []
+      },
+      {
+        provide: SAGA_TRANSPORT_TOKEN,
+        useFactory: (opts) => opts.transport,
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: SagaRegistry2,
+        useFactory: () => new SagaRegistry2()
+      },
+      {
+        provide: SagaParser,
+        useFactory: (opts) => {
+          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);
+          return new SagaParser(otelCtx);
+        },
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: SagaPublisher2,
+        useFactory: (opts) => {
+          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);
+          return new SagaPublisher2(opts.transport, otelCtx, opts.topicPrefix);
+        },
+        inject: [SAGA_OPTIONS_TOKEN]
+      },
+      {
+        provide: SagaRunner2,
+        useFactory: (registry, publisher, parser, opts) => {
+          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);
+          return new SagaRunner2(registry, opts.transport, publisher, parser, opts, otelCtx, opts.logger);
+        },
+        inject: [SagaRegistry2, SagaPublisher2, SagaParser, SAGA_OPTIONS_TOKEN]
+      }
+    ];
+    return {
+      module: SagaModule,
+      imports: [...options.imports ?? [], DiscoveryModule],
+      global: true,
+      providers: [...asyncProviders, SagaRunnerProvider, SagaPublisherProvider],
+      exports: [SagaPublisherProvider, SagaPublisher2, SAGA_OPTIONS_TOKEN]
+    };
+  }
+};
+SagaModule = __decorateClass([
+  Module({})
+], SagaModule);
+
+// src/decorators/saga-handler.decorator.ts
+function SagaHandler(...args) {
+  let eventTypes;
+  let options = {};
+  const lastArg = args[args.length - 1];
+  if (typeof lastArg === "object" && lastArg !== null) {
+    options = lastArg;
+    eventTypes = args.slice(0, -1);
+  } else {
+    eventTypes = args;
+  }
+  return (target, propertyKey) => {
+    const existingMap = Reflect.getMetadata(SAGA_HANDLER_METADATA, target.constructor) ?? /* @__PURE__ */ new Map();
+    const existingOptions = Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, target.constructor) ?? /* @__PURE__ */ new Map();
+    for (const eventType of eventTypes) {
+      existingMap.set(eventType, propertyKey);
+      if (options.final || options.fork) {
+        existingOptions.set(eventType, options);
+      }
+    }
+    Reflect.defineMetadata(SAGA_HANDLER_METADATA, existingMap, target.constructor);
+    Reflect.defineMetadata(SAGA_HANDLER_OPTIONS_METADATA, existingOptions, target.constructor);
+  };
+}
+
+// src/decorators/saga-participant.decorator.ts
+function SagaParticipant() {
+  return (target) => {
+    Reflect.defineMetadata(SAGA_PARTICIPANT_METADATA, true, target);
+  };
+}
+
+// src/saga-participant-base.ts
+var SagaParticipantBase = class {
+  on = {};
+};
+
+// src/index.ts
+import {
+  SagaError,
+  SagaRetryableError,
+  SagaDuplicateHandlerError,
+  SagaParseError,
+  SagaTransportNotConnectedError
+} from "@fbsm/saga-core";
+export {
+  SAGA_OPTIONS_TOKEN,
+  SAGA_TRANSPORT_TOKEN,
+  SagaDuplicateHandlerError,
+  SagaError,
+  SagaHandler,
+  SagaModule,
+  SagaParseError,
+  SagaParticipant,
+  SagaParticipantBase,
+  SagaPublisherProvider,
+  SagaRetryableError,
+  SagaTransportNotConnectedError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/saga.module.ts","../src/constants.ts","../src/providers/saga-runner.provider.ts","../src/providers/saga-publisher.provider.ts","../src/decorators/saga-handler.decorator.ts","../src/decorators/saga-participant.decorator.ts","../src/saga-participant-base.ts","../src/index.ts"],"sourcesContent":["import { Module, DynamicModule, type Provider } from '@nestjs/common';\nimport { DiscoveryModule } from '@nestjs/core';\nimport {\n  SagaRunner,\n  SagaRegistry,\n  SagaPublisher,\n  SagaParser,\n  createOtelContext,\n} from '@fbsm/saga-core';\nimport { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN } from './constants';\nimport type { SagaModuleOptions, SagaModuleAsyncOptions } from './saga-module-options.interface';\nimport { SagaRunnerProvider } from './providers/saga-runner.provider';\nimport { SagaPublisherProvider } from './providers/saga-publisher.provider';\n\n@Module({})\nexport class SagaModule {\n  static forRoot(options: SagaModuleOptions): DynamicModule {\n    const otelCtx = createOtelContext(options.otel?.enabled ?? false);\n    const registry = new SagaRegistry();\n    const parser = new SagaParser(otelCtx);\n    const publisher = new SagaPublisher(options.transport, otelCtx, options.topicPrefix);\n    const runner = new SagaRunner(registry, options.transport, publisher, parser, options, otelCtx, options.logger);\n\n    return {\n      module: SagaModule,\n      imports: [DiscoveryModule],\n      global: true,\n      providers: [\n        { provide: SAGA_OPTIONS_TOKEN, useValue: options },\n        { provide: SAGA_TRANSPORT_TOKEN, useValue: options.transport },\n        { provide: SagaRegistry, useValue: registry },\n        { provide: SagaParser, useValue: parser },\n        { provide: SagaPublisher, useValue: publisher },\n        { provide: SagaRunner, useValue: runner },\n        SagaRunnerProvider,\n        SagaPublisherProvider,\n      ],\n      exports: [SagaPublisherProvider, SagaPublisher, SAGA_OPTIONS_TOKEN],\n    };\n  }\n\n  static forRootAsync(options: SagaModuleAsyncOptions): DynamicModule {\n    const asyncProviders: Provider[] = [\n      {\n        provide: SAGA_OPTIONS_TOKEN,\n        useFactory: options.useFactory,\n        inject: options.inject ?? [],\n      },\n      {\n        provide: SAGA_TRANSPORT_TOKEN,\n        useFactory: (opts: SagaModuleOptions) => opts.transport,\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaRegistry,\n        useFactory: () => new SagaRegistry(),\n      },\n      {\n        provide: SagaParser,\n        useFactory: (opts: SagaModuleOptions) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaParser(otelCtx);\n        },\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaPublisher,\n        useFactory: (opts: SagaModuleOptions) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaPublisher(opts.transport, otelCtx, opts.topicPrefix);\n        },\n        inject: [SAGA_OPTIONS_TOKEN],\n      },\n      {\n        provide: SagaRunner,\n        useFactory: (\n          registry: SagaRegistry,\n          publisher: SagaPublisher,\n          parser: SagaParser,\n          opts: SagaModuleOptions,\n        ) => {\n          const otelCtx = createOtelContext(opts.otel?.enabled ?? false);\n          return new SagaRunner(registry, opts.transport, publisher, parser, opts, otelCtx, opts.logger);\n        },\n        inject: [SagaRegistry, SagaPublisher, SagaParser, SAGA_OPTIONS_TOKEN],\n      },\n    ];\n\n    return {\n      module: SagaModule,\n      imports: [...(options.imports ?? []), DiscoveryModule],\n      global: true,\n      providers: [...asyncProviders, SagaRunnerProvider, SagaPublisherProvider],\n      exports: [SagaPublisherProvider, SagaPublisher, SAGA_OPTIONS_TOKEN],\n    };\n  }\n}\n","export const SAGA_OPTIONS_TOKEN = Symbol('SAGA_OPTIONS_TOKEN');\nexport const SAGA_TRANSPORT_TOKEN = Symbol('SAGA_TRANSPORT_TOKEN');\nexport const SAGA_PARTICIPANT_METADATA = Symbol('SAGA_PARTICIPANT_METADATA');\nexport const SAGA_HANDLER_METADATA = Symbol('SAGA_HANDLER_METADATA');\nexport const SAGA_HANDLER_OPTIONS_METADATA = Symbol('SAGA_HANDLER_OPTIONS_METADATA');\n","import { Inject, Injectable, Logger, OnModuleInit, OnModuleDestroy } from '@nestjs/common';\nimport { DiscoveryService } from '@nestjs/core';\nimport { SagaRunner, SagaRegistry } from '@fbsm/saga-core';\nimport type { EventHandler } from '@fbsm/saga-core';\nimport { SAGA_PARTICIPANT_METADATA, SAGA_HANDLER_METADATA, SAGA_HANDLER_OPTIONS_METADATA } from '../constants';\nimport type { SagaHandlerOptions } from '../decorators/saga-handler.decorator';\nimport type { HandlerConfig } from '@fbsm/saga-core';\n\n@Injectable()\nexport class SagaRunnerProvider implements OnModuleInit, OnModuleDestroy {\n  private readonly logger = new Logger('SagaRunner');\n\n  constructor(\n    @Inject(DiscoveryService) private readonly discoveryService: DiscoveryService,\n    @Inject(SagaRegistry) private readonly registry: SagaRegistry,\n    @Inject(SagaRunner) private readonly runner: SagaRunner,\n  ) {}\n\n  async onModuleInit(): Promise<void> {\n    const providers = this.discoveryService.getProviders();\n\n    for (const wrapper of providers) {\n      const instance = wrapper.instance;\n      if (!instance || !instance.constructor) {\n        continue;\n      }\n\n      const isParticipant = Reflect.getMetadata(\n        SAGA_PARTICIPANT_METADATA,\n        instance.constructor,\n      );\n\n      if (!isParticipant) {\n        continue;\n      }\n\n      const handlesMap: Map<string, string | symbol> | undefined =\n        Reflect.getMetadata(SAGA_HANDLER_METADATA, instance.constructor);\n\n      if (!handlesMap || handlesMap.size === 0) {\n        continue;\n      }\n\n      const on: Record<string, EventHandler<any>> = {};\n      \n      for (const [eventType, methodName] of handlesMap.entries()) {\n        const method = (instance as any)[methodName];\n        if (typeof method === 'function') {\n          on[eventType] = method.bind(instance);\n        }\n      }\n\n      // Populate the `on` property if instance extends SagaParticipantBase\n      if ('on' in instance && typeof instance.on === 'object') {\n        Object.assign(instance.on, on);\n      }\n\n      // Extract handler options (final, fork, etc.) from decorator metadata\n      const handlerOptionsMap: Map<string, SagaHandlerOptions> | undefined =\n        Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, instance.constructor);\n\n      const handlerOptions: Record<string, HandlerConfig> = {};\n      if (handlerOptionsMap) {\n        for (const [eventType, opts] of handlerOptionsMap.entries()) {\n          handlerOptions[eventType] = { final: opts.final, fork: !!opts.fork };\n        }\n      }\n\n      const serviceId = (instance as any).serviceId ?? 'unknown';\n      this.logger.log(\n        `Registered participant \"${serviceId}\" handling: [${Object.keys(on).join(', ')}]`,\n      );\n\n      this.registry.register({\n        serviceId,\n        on,\n        handlerOptions: Object.keys(handlerOptions).length > 0 ? handlerOptions : undefined,\n        onRetryExhausted:\n          typeof (instance as any).onRetryExhausted === 'function'\n            ? (instance as any).onRetryExhausted.bind(instance)\n            : undefined,\n      });\n    }\n\n    await this.runner.start();\n  }\n\n  async onModuleDestroy(): Promise<void> {\n    await this.runner.stop();\n  }\n}\n","import { Inject, Injectable } from '@nestjs/common';\nimport type { Emit, EmitParams, ParentSagaContext, SagaStartOptions } from '@fbsm/saga-core';\nimport { SagaPublisher } from '@fbsm/saga-core';\n\n@Injectable()\nexport class SagaPublisherProvider {\n  constructor(@Inject(SagaPublisher) private readonly publisher: SagaPublisher) {}\n\n  start<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{ sagaId: string; result: Awaited<R> }> {\n    return this.publisher.start(fn, opts);\n  }\n\n  startChild<R>(fn: () => R | Promise<R>, opts?: SagaStartOptions): Promise<{ sagaId: string; result: Awaited<R> }> {\n    return this.publisher.startChild(fn, opts);\n  }\n\n  emit<T extends object>(params: EmitParams<T>): Promise<void> {\n    return this.publisher.emit(params);\n  }\n\n  emitToParent<T extends object>(paramsOrFn: EmitParams<T> | (() => void | Promise<void>)): Promise<void> {\n    return this.publisher.emitToParent(paramsOrFn);\n  }\n\n  forSaga(sagaId: string, parentCtx?: ParentSagaContext, causationId?: string): Emit {\n    return this.publisher.forSaga(sagaId, parentCtx, causationId);\n  }\n}\n","import { SAGA_HANDLER_METADATA, SAGA_HANDLER_OPTIONS_METADATA } from '../constants';\n\nimport type { ForkConfig } from '@fbsm/saga-core';\n\nexport interface SagaHandlerOptions {\n  final?: boolean;\n  fork?: boolean | ForkConfig;\n}\n\nexport function SagaHandler(\n  ...args: [...string[]] | [...string[], SagaHandlerOptions]\n): MethodDecorator {\n  let eventTypes: string[];\n  let options: SagaHandlerOptions = {};\n\n  const lastArg = args[args.length - 1];\n  if (typeof lastArg === 'object' && lastArg !== null) {\n    options = lastArg as SagaHandlerOptions;\n    eventTypes = args.slice(0, -1) as string[];\n  } else {\n    eventTypes = args as string[];\n  }\n\n  return (target, propertyKey) => {\n    const existingMap: Map<string, string | symbol> =\n      Reflect.getMetadata(SAGA_HANDLER_METADATA, target.constructor) ?? new Map();\n    const existingOptions: Map<string, SagaHandlerOptions> =\n      Reflect.getMetadata(SAGA_HANDLER_OPTIONS_METADATA, target.constructor) ?? new Map();\n\n    for (const eventType of eventTypes) {\n      existingMap.set(eventType, propertyKey);\n      if (options.final || options.fork) {\n        existingOptions.set(eventType, options);\n      }\n    }\n\n    Reflect.defineMetadata(SAGA_HANDLER_METADATA, existingMap, target.constructor);\n    Reflect.defineMetadata(SAGA_HANDLER_OPTIONS_METADATA, existingOptions, target.constructor);\n  };\n}\n","import { SAGA_PARTICIPANT_METADATA } from '../constants';\n\nexport function SagaParticipant(): ClassDecorator {\n  return (target) => {\n    Reflect.defineMetadata(SAGA_PARTICIPANT_METADATA, true, target);\n  };\n}\n","import type {\n  SagaParticipant,\n  EventHandler,\n  IncomingEvent,\n  Emit,\n} from '@fbsm/saga-core';\nimport { SagaRetryableError } from '@fbsm/saga-core';\n\nexport abstract class SagaParticipantBase implements SagaParticipant {\n  abstract readonly serviceId: string;\n\n  readonly on: Record<string, EventHandler<any>> = {};\n\n  onRetryExhausted?(\n    event: IncomingEvent,\n    error: SagaRetryableError,\n    emit: Emit,\n  ): Promise<void>;\n}\n","// Module\nexport { SagaModule } from './saga.module';\n\n// Provider\nexport { SagaPublisherProvider } from './providers/saga-publisher.provider';\n\n// Decorators\nexport { SagaHandler } from './decorators/saga-handler.decorator';\nexport type { SagaHandlerOptions } from './decorators/saga-handler.decorator';\nexport { SagaParticipant } from './decorators/saga-participant.decorator';\n\n// Base class\nexport { SagaParticipantBase } from './saga-participant-base';\n\n// Constants (tokens for advanced usage)\nexport { SAGA_OPTIONS_TOKEN, SAGA_TRANSPORT_TOKEN } from './constants';\n\n// Options\nexport type { SagaModuleOptions, SagaModuleAsyncOptions } from './saga-module-options.interface';\n\n// Re-exports from core for consumer convenience\nexport {\n  SagaError,\n  SagaRetryableError,\n  SagaDuplicateHandlerError,\n  SagaParseError,\n  SagaTransportNotConnectedError,\n} from '@fbsm/saga-core';\nexport type {\n  SagaEvent,\n  IncomingEvent,\n  Emit,\n  EmitParams,\n  EventHint,\n  EventHandler,\n  ParentSagaContext,\n  HandlerConfig,\n  SagaTransport,\n} from '@fbsm/saga-core';\n"],"mappings":"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","names":["SagaRunner","SagaRegistry","SagaPublisher","Inject","Injectable","Injectable","Inject","SagaRegistry","SagaPublisher","SagaRunner"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@fbsm/saga-nestjs",
+  "version": "0.0.1-beta.0",
+  "description": "NestJS integration for saga choreography: dynamic module, decorators, auto-discovery",
+  "license": "MIT",
+  "author": "fbsm",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fbsm/saga-library",
+    "directory": "packages/saga-nestjs"
+  },
+  "keywords": [
+    "saga",
+    "nestjs",
+    "choreography",
+    "microservices",
+    "event-driven"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fbsm/saga-core": "0.0.1-beta.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/testing": "^10.0.0",
+    "reflect-metadata": "^0.2.0",
+    "rxjs": "^7.8.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}