@fbsm/saga-core 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -10,20 +10,20 @@ npm install @fbsm/saga-core
 
 ## Overview
 
-| Export | Description |
-|--------|-------------|
-| `SagaPublisher` | Creates sagas and publishes events |
-| `SagaRunner` | Consumes events, dispatches to handlers with retry logic |
-| `SagaRegistry` | Stores participant and handler mappings |
-| `SagaParser` | Parses inbound messages (3-layer fallback) |
-| `SagaContext` | AsyncLocalStorage-based context propagation |
+| Export          | Description                                              |
+| --------------- | -------------------------------------------------------- |
+| `SagaPublisher` | Creates sagas and publishes events                       |
+| `SagaRunner`    | Consumes events, dispatches to handlers with retry logic |
+| `SagaRegistry`  | Stores participant and handler mappings                  |
+| `SagaParser`    | Parses inbound messages (3-layer fallback)               |
+| `SagaContext`   | AsyncLocalStorage-based context propagation              |
 
 ## SagaContext
 
 Uses `AsyncLocalStorage` to propagate saga metadata through async call chains.
 
 ```typescript
-import { SagaContext } from '@fbsm/saga-core';
+import { SagaContext } from "@fbsm/saga-core";
 
 // Read current context (or undefined)
 const ctx = SagaContext.current();
@@ -34,6 +34,7 @@ const ctx = SagaContext.require();
 ```
 
 **`SagaContextData`**:
+
 ```typescript
 interface SagaContextData {
   sagaId: string;
@@ -47,6 +48,7 @@ interface SagaContextData {
 ```
 
 Context is set automatically by:
+
 1. **`SagaRunner`** — wraps every handler execution with `SagaContext.run()`
 2. **`SagaPublisher.start(fn)` / `startChild(fn)` / `emitToParent(fn)`** — wraps callbacks with `SagaContext.run()`
 
@@ -55,20 +57,21 @@ Context is set automatically by:
 Creates sagas and publishes events. See [Core Functions](../doc/core-functions.md) for detailed usage of each method.
 
 ```typescript
-import { SagaPublisher } from '@fbsm/saga-core';
+import { SagaPublisher } from "@fbsm/saga-core";
 
 const publisher = new SagaPublisher(transport, otelContext, topicPrefix);
 ```
 
-| Method | Description |
-|--------|-------------|
-| `start(fn, opts?)` | Create a root saga with ALS context |
-| `startChild(fn, opts?)` | Create a child saga linked to current |
-| `emit(params)` | Publish event in current context |
-| `emitToParent(params \| fn)` | Emit to parent saga |
-| `forSaga(sagaId, parentCtx?, causationId?, key?)` | Get bound `Emit` function (no ALS) |
+| Method                                            | Description                           |
+| ------------------------------------------------- | ------------------------------------- |
+| `start(fn, opts?)`                                | Create a root saga with ALS context   |
+| `startChild(fn, opts?)`                           | Create a child saga linked to current |
+| `emit(params)`                                    | Publish event in current context      |
+| `emitToParent(params \| fn)`                      | Emit to parent saga                   |
+| `forSaga(sagaId, parentCtx?, causationId?, key?)` | Get bound `Emit` function (no ALS)    |
 
 **`SagaStartOptions`**:
+
 ```typescript
 interface SagaStartOptions {
   sagaName?: string;
@@ -82,36 +85,42 @@ interface SagaStartOptions {
 Consumes events from transport, routes to handlers, and applies retry logic.
 
 ```typescript
-import { SagaRunner } from '@fbsm/saga-core';
+import { SagaRunner } from "@fbsm/saga-core";
 
 const runner = new SagaRunner(
-  registry,    // SagaRegistry
-  transport,   // SagaTransport
-  publisher,   // SagaPublisher
-  parser,      // SagaParser
-  options,     // RunnerOptions
-  otelContext,  // OtelContext (optional)
-  logger,      // SagaLogger (optional)
+  registry, // SagaRegistry
+  transport, // SagaTransport
+  publisher, // SagaPublisher
+  parser, // SagaParser
+  options, // RunnerOptions
+  otelContext, // OtelContext (optional)
+  logger, // SagaLogger (optional)
 );
 
 await runner.start(); // Subscribe and begin consuming
-await runner.stop();  // Disconnect
+await runner.stop(); // Disconnect
+
+// Health check (delegates to transport if it implements HealthCheckable)
+const health = await runner.healthCheck();
+// { status: 'up' | 'down', details?: { consumerGroupState, groupId, memberCount } }
 ```
 
 **`RunnerOptions`**:
+
 ```typescript
 interface RunnerOptions {
-  serviceName: string;
+  groupId: string;
   fromBeginning?: boolean;
   topicPrefix?: string;
   retryPolicy?: {
-    maxRetries?: number;      // default: 3
-    initialDelayMs?: number;  // default: 200
+    maxRetries?: number; // default: 3
+    initialDelayMs?: number; // default: 200
   };
 }
 ```
 
 **Handler execution flow**:
+
 1. Parse inbound message via `SagaParser`
 2. Look up handler in route map
 3. Wrap emit with `final` hint (if `{ final: true }`)
@@ -132,51 +141,56 @@ Parses inbound messages using a 3-layer fallback strategy:
 
 When using the header-based format (default with `@fbsm/saga-transport-kafka`):
 
-| Header | Description |
-|--------|-------------|
-| `saga-id` | Saga instance ID |
-| `saga-event-id` | Unique event ID |
-| `saga-causation-id` | ID of the event that caused this one |
-| `saga-step-name` | Logical step name |
-| `saga-published-at` | ISO timestamp of publication |
-| `saga-schema-version` | Schema version (currently `1`) |
-| `saga-root-id` | Root saga ID (top-level ancestor) |
-| `saga-parent-id` | Parent saga ID (for sub-sagas, optional) |
-| `saga-event-hint` | Event hint: `compensation`, `final`, `fork` (optional) |
-| `saga-name` | Saga name (optional) |
-| `saga-description` | Saga description (optional) |
-| `saga-step-description` | Step description (optional) |
-| `saga-key` | Partition key (optional) |
+| Header                  | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `saga-id`               | Saga instance ID                                       |
+| `saga-event-id`         | Unique event ID                                        |
+| `saga-causation-id`     | ID of the event that caused this one                   |
+| `saga-step-name`        | Logical step name                                      |
+| `saga-published-at`     | ISO timestamp of publication                           |
+| `saga-schema-version`   | Schema version (currently `1`)                         |
+| `saga-root-id`          | Root saga ID (top-level ancestor)                      |
+| `saga-parent-id`        | Parent saga ID (for sub-sagas, optional)               |
+| `saga-event-hint`       | Event hint: `compensation`, `final`, `fork` (optional) |
+| `saga-name`             | Saga name (optional)                                   |
+| `saga-description`      | Saga description (optional)                            |
+| `saga-step-description` | Step description (optional)                            |
+| `saga-key`              | Partition key (optional)                               |
 
 ## Errors
 
-| Error | Description |
-|-------|-------------|
-| `SagaError` | Base error class for all saga errors |
-| `SagaRetryableError` | Throw in handlers to trigger retry with exponential backoff. `new SagaRetryableError(message, maxRetries?)` |
-| `SagaDuplicateHandlerError` | Two handlers registered for the same event type |
-| `SagaParseError` | Message parsing failed |
-| `SagaTransportNotConnectedError` | Publishing to a disconnected transport |
-| `SagaContextNotFoundError` | `emit()`/`startChild()`/`emitToParent()` called outside a saga context |
-| `SagaNoParentError` | `emitToParent()` called in a saga without `parentSagaId` |
-| `SagaInvalidHandlerConfigError` | Handler has conflicting options (e.g., both `final` and `fork`) |
+| Error                            | Description                                                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `SagaError`                      | Base error class for all saga errors                                                                        |
+| `SagaRetryableError`             | Throw in handlers to trigger retry with exponential backoff. `new SagaRetryableError(message, maxRetries?)` |
+| `SagaDuplicateHandlerError`      | Two handlers registered for the same event type                                                             |
+| `SagaParseError`                 | Message parsing failed                                                                                      |
+| `SagaTransportNotConnectedError` | Publishing to a disconnected transport                                                                      |
+| `SagaContextNotFoundError`       | `emit()`/`startChild()`/`emitToParent()` called outside a saga context                                      |
+| `SagaNoParentError`              | `emitToParent()` called in a saga without `parentSagaId`                                                    |
+| `SagaInvalidHandlerConfigError`  | Handler has conflicting options (e.g., both `final` and `fork`)                                             |
 
 **Retry behavior**: `SagaRetryableError` triggers exponential backoff: `initialDelayMs * 2^attempt`. After `maxRetries` attempts, `onRetryExhausted()` is called if defined. Non-retryable errors are logged and skipped.
 
 ## OTel Integration
 
 ```typescript
-import { createOtelContext, W3cOtelContext, NoopOtelContext } from '@fbsm/saga-core';
+import {
+  createOtelContext,
+  W3cOtelContext,
+  NoopOtelContext,
+} from "@fbsm/saga-core";
 
 // Auto-detect: uses W3cOtelContext if @opentelemetry/api is available, NoopOtelContext otherwise
 const otelCtx = createOtelContext();
 
 // Or explicitly:
-const otelCtx = new W3cOtelContext();   // requires @opentelemetry/api
-const otelCtx = new NoopOtelContext();  // no-op (no tracing)
+const otelCtx = new W3cOtelContext(); // requires @opentelemetry/api
+const otelCtx = new NoopOtelContext(); // no-op (no tracing)
 ```
 
 The OTel context:
+
 - Injects W3C baggage with saga context into outgoing messages
 - Extracts trace context from incoming message headers
 - Creates spans for publish and handle operations
@@ -199,6 +213,27 @@ interface SagaTransport {
 }
 ```
 
+## Health Checks
+
+Transports can optionally implement the `HealthCheckable` interface to support health checks.
+
+```typescript
+import { isHealthCheckable } from "@fbsm/saga-core";
+import type { HealthCheckable, TransportHealthResult } from "@fbsm/saga-core";
+
+// Check if a transport supports health checks
+if (isHealthCheckable(transport)) {
+  const result: TransportHealthResult = await transport.healthCheck();
+  // result.status: 'up' | 'down'
+  // result.details: transport-specific details
+}
+
+// Or use SagaRunner.healthCheck() which delegates automatically
+const health = await runner.healthCheck();
+```
+
+`KafkaTransport` from `@fbsm/saga-transport-kafka` implements `HealthCheckable` using `consumer.describeGroup()`. Healthy states: `Stable`, `CompletingRebalance`, `PreparingRebalance`.
+
 ## SagaLogger
 
 ```typescript

package/dist/index.cjs

@@ -36,10 +36,16 @@ __export(index_exports, {
   SagaRunner: () => SagaRunner,
   SagaTransportNotConnectedError: () => SagaTransportNotConnectedError,
   W3cOtelContext: () => W3cOtelContext,
-  createOtelContext: () => createOtelContext
+  createOtelContext: () => createOtelContext,
+  isHealthCheckable: () => isHealthCheckable
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/transport/transport.interface.ts
+function isHealthCheckable(transport) {
+  return typeof transport.healthCheck === "function";
+}
+
 // src/errors/saga.error.ts
 var SagaError = class extends Error {
   isSagaError = true;
@@ -118,26 +124,41 @@ var SagaRunner = class {
   async start() {
     this.routeMap = this.registry.buildRouteMap();
     const prefix = this.options.topicPrefix ?? "";
-    const topics = Array.from(this.routeMap.keys()).map((et) => `${prefix}${et}`);
+    const topics = Array.from(this.routeMap.keys()).map(
+      (et) => `${prefix}${et}`
+    );
     await this.transport.connect();
     if (topics.length > 0) {
-      this.logger.info(`[SagaRunner] Subscribing to ${topics.length} topic(s): [${topics.join(", ")}]`);
+      this.logger.info(
+        `[SagaRunner] Subscribing to ${topics.length} topic(s): [${topics.join(", ")}]`
+      );
       await this.transport.subscribe(
         topics,
         (message) => this.handleMessage(message),
         {
           fromBeginning: this.options.fromBeginning,
-          groupId: `${this.options.serviceName}-group`
+          groupId: this.options.groupId
         }
       );
       this.logger.info("[SagaRunner] Consumer running");
     } else {
-      this.logger.warn("[SagaRunner] No handlers registered \u2014 nothing to subscribe");
+      this.logger.warn(
+        "[SagaRunner] No handlers registered \u2014 nothing to subscribe"
+      );
     }
   }
   async stop() {
     await this.transport.disconnect();
   }
+  async healthCheck() {
+    if (isHealthCheckable(this.transport)) {
+      return this.transport.healthCheck();
+    }
+    return {
+      status: "up",
+      details: { reason: "Transport does not support health checks" }
+    };
+  }
   async handleMessage(message) {
     const event = this.parser.parse(message);
     if (!event) return;
@@ -159,10 +180,15 @@ var SagaRunner = class {
       sagaName: event.sagaName,
       sagaDescription: event.sagaDescription
     };
-    const emit = this.publisher.forSaga(event.sagaId, {
-      parentSagaId: event.parentSagaId,
-      rootSagaId: event.rootSagaId
-    }, event.eventId, event.key);
+    const emit = this.publisher.forSaga(
+      event.sagaId,
+      {
+        parentSagaId: event.parentSagaId,
+        rootSagaId: event.rootSagaId
+      },
+      event.eventId,
+      event.key
+    );
     const wrappedEmit = async (params) => {
       const finalParams = isFinalHandler ? { ...params, hint: "final" } : params;
       return emit(finalParams);
@@ -170,10 +196,15 @@ var SagaRunner = class {
     const forkConfig = route.options?.fork;
     const finalEmit = forkConfig ? async (params) => {
       const subSagaId = (0, import_uuid.v7)();
-      const subEmit = this.publisher.forSaga(subSagaId, {
-        parentSagaId: event.sagaId,
-        rootSagaId: event.rootSagaId
-      }, event.eventId, event.key);
+      const subEmit = this.publisher.forSaga(
+        subSagaId,
+        {
+          parentSagaId: event.sagaId,
+          rootSagaId: event.rootSagaId
+        },
+        event.eventId,
+        event.key
+      );
       const forkMeta = typeof forkConfig === "object" ? forkConfig : {};
       const forkCtx = {
         sagaId: subSagaId,
@@ -184,7 +215,10 @@ var SagaRunner = class {
         sagaName: forkMeta.sagaName,
         sagaDescription: forkMeta.sagaDescription
       };
-      await SagaContext.run(forkCtx, () => subEmit({ ...params, hint: "fork" }));
+      await SagaContext.run(
+        forkCtx,
+        () => subEmit({ ...params, hint: "fork" })
+      );
     } : wrappedEmit;
     const spanAttrs = {
       "saga.id": event.sagaId,
@@ -195,8 +229,10 @@ var SagaRunner = class {
       "saga.handler.service": route.participant.serviceId
     };
     if (event.sagaName) spanAttrs["saga.name"] = event.sagaName;
-    if (event.sagaDescription) spanAttrs["saga.description"] = event.sagaDescription;
-    if (event.stepDescription) spanAttrs["saga.step.description"] = event.stepDescription;
+    if (event.sagaDescription)
+      spanAttrs["saga.description"] = event.sagaDescription;
+    if (event.stepDescription)
+      spanAttrs["saga.step.description"] = event.stepDescription;
     if (event.parentSagaId) spanAttrs["saga.parent.id"] = event.parentSagaId;
     const sagaCtxData = {
       sagaId: event.sagaId,
@@ -209,10 +245,20 @@ var SagaRunner = class {
     };
     const runHandler = () => SagaContext.run(
       sagaCtxData,
-      () => this.runWithRetry(route.handler, route.participant, incoming, finalEmit)
+      () => this.runWithRetry(
+        route.handler,
+        route.participant,
+        incoming,
+        finalEmit
+      )
     );
     if (this.otelCtx) {
-      await this.otelCtx.withExtractedSpan(`saga.handle ${event.eventType}`, spanAttrs, message.headers, runHandler);
+      await this.otelCtx.withExtractedSpan(
+        `saga.handle ${event.eventType}`,
+        spanAttrs,
+        message.headers,
+        runHandler
+      );
     } else {
       await runHandler();
     }
@@ -321,10 +367,15 @@ var SagaPublisher = class {
   }
   async emit(params) {
     const ctx = SagaContext.require();
-    const boundEmit = this.forSaga(ctx.sagaId, {
-      parentSagaId: ctx.parentSagaId,
-      rootSagaId: ctx.rootSagaId
-    }, ctx.causationId, ctx.key);
+    const boundEmit = this.forSaga(
+      ctx.sagaId,
+      {
+        parentSagaId: ctx.parentSagaId,
+        rootSagaId: ctx.rootSagaId
+      },
+      ctx.causationId,
+      ctx.key
+    );
     return boundEmit(params);
   }
   async startChild(fn, opts) {
@@ -358,10 +409,15 @@ var SagaPublisher = class {
       await SagaContext.run(parentCtx, paramsOrFn);
       return;
     }
-    const parentEmit = this.forSaga(ctx.parentSagaId, {
-      parentSagaId: ctx.parentSagaId,
-      rootSagaId: ctx.rootSagaId
-    }, ctx.causationId, ctx.key);
+    const parentEmit = this.forSaga(
+      ctx.parentSagaId,
+      {
+        parentSagaId: ctx.parentSagaId,
+        rootSagaId: ctx.rootSagaId
+      },
+      ctx.causationId,
+      ctx.key
+    );
     return parentEmit(paramsOrFn);
   }
   forSaga(sagaId, parentCtx, causationId, baseKey) {
@@ -401,7 +457,11 @@ var SagaPublisher = class {
     };
   }
   async publish(event) {
-    this.otelCtx.injectBaggage(event.sagaId, event.rootSagaId, event.parentSagaId);
+    this.otelCtx.injectBaggage(
+      event.sagaId,
+      event.rootSagaId,
+      event.parentSagaId
+    );
     const attrs = {
       "saga.id": event.sagaId,
       "saga.event.type": event.eventType,
@@ -627,7 +687,10 @@ var W3cOtelContext = class {
       entries["saga.parent.id"] = { value: parentSagaId };
     }
     const baggage = this.api.propagation.createBaggage(entries);
-    const ctx = this.api.propagation.setBaggage(this.api.context.active(), baggage);
+    const ctx = this.api.propagation.setBaggage(
+      this.api.context.active(),
+      baggage
+    );
     this.api.context.with(ctx, () => {
     });
   }
@@ -659,7 +722,9 @@ var W3cOtelContext = class {
           code: this.api.SpanStatusCode.ERROR,
           message: error instanceof Error ? error.message : String(error)
         });
-        span.recordException(error instanceof Error ? error : new Error(String(error)));
+        span.recordException(
+          error instanceof Error ? error : new Error(String(error))
+        );
         throw error;
       } finally {
         span.end();
@@ -670,27 +735,36 @@ var W3cOtelContext = class {
     this.api.propagation.inject(this.api.context.active(), headers);
   }
   async withExtractedSpan(name, attrs, headers, fn) {
-    const parentCtx = this.api.propagation.extract(this.api.ROOT_CONTEXT, headers);
+    const parentCtx = this.api.propagation.extract(
+      this.api.ROOT_CONTEXT,
+      headers
+    );
     const tracer = this.api.trace.getTracer("@fbsm/saga-core");
     return this.api.context.with(
       parentCtx,
-      () => tracer.startActiveSpan(name, { kind: this.api.SpanKind.CONSUMER }, async (span) => {
-        span.setAttributes(attrs);
-        try {
-          const result = await fn();
-          span.setStatus({ code: this.api.SpanStatusCode.OK });
-          return result;
-        } catch (error) {
-          span.setStatus({
-            code: this.api.SpanStatusCode.ERROR,
-            message: error instanceof Error ? error.message : String(error)
-          });
-          span.recordException(error instanceof Error ? error : new Error(String(error)));
-          throw error;
-        } finally {
-          span.end();
+      () => tracer.startActiveSpan(
+        name,
+        { kind: this.api.SpanKind.CONSUMER },
+        async (span) => {
+          span.setAttributes(attrs);
+          try {
+            const result = await fn();
+            span.setStatus({ code: this.api.SpanStatusCode.OK });
+            return result;
+          } catch (error) {
+            span.setStatus({
+              code: this.api.SpanStatusCode.ERROR,
+              message: error instanceof Error ? error.message : String(error)
+            });
+            span.recordException(
+              error instanceof Error ? error : new Error(String(error))
+            );
+            throw error;
+          } finally {
+            span.end();
+          }
         }
-      })
+      )
     );
   }
 };
@@ -721,6 +795,7 @@ function createOtelContext(enabled) {
   SagaRunner,
   SagaTransportNotConnectedError,
   W3cOtelContext,
-  createOtelContext
+  createOtelContext,
+  isHealthCheckable
 });
 //# sourceMappingURL=index.cjs.map