@fbsm/saga-core 0.0.1-beta.0

package/dist/index.js

@@ -0,0 +1,690 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/errors/saga.error.ts
+var SagaError = class extends Error {
+  isSagaError = true;
+  constructor(message) {
+    super(message);
+    this.name = "SagaError";
+  }
+};
+
+// src/errors/saga-retryable.error.ts
+var SagaRetryableError = class extends SagaError {
+  constructor(message, maxRetries = 3) {
+    super(message);
+    this.maxRetries = maxRetries;
+    this.name = "SagaRetryableError";
+  }
+};
+
+// src/logger/saga-logger.ts
+var ConsoleSagaLogger = class {
+  info(message, ...args) {
+    console.log(message, ...args);
+  }
+  warn(message, ...args) {
+    console.warn(message, ...args);
+  }
+  error(message, ...args) {
+    console.error(message, ...args);
+  }
+};
+
+// src/context/saga-context.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/errors/saga-context-not-found.error.ts
+var SagaContextNotFoundError = class extends SagaError {
+  constructor() {
+    super(
+      "No saga context found. Ensure you are inside a saga handler or after sagaPublisher.start()."
+    );
+    this.name = "SagaContextNotFoundError";
+  }
+};
+
+// src/context/saga-context.ts
+var SagaContext = class _SagaContext {
+  static storage = new AsyncLocalStorage();
+  static run(data, fn) {
+    return _SagaContext.storage.run(data, fn);
+  }
+  static current() {
+    return _SagaContext.storage.getStore();
+  }
+  static require() {
+    const ctx = _SagaContext.current();
+    if (!ctx) {
+      throw new SagaContextNotFoundError();
+    }
+    return ctx;
+  }
+};
+
+// src/runner/saga-runner.ts
+import { v7 as uuidv7 } from "uuid";
+var SagaRunner = class {
+  constructor(registry, transport, publisher, parser, options, otelCtx, logger = new ConsoleSagaLogger()) {
+    this.registry = registry;
+    this.transport = transport;
+    this.publisher = publisher;
+    this.parser = parser;
+    this.options = options;
+    this.otelCtx = otelCtx;
+    this.logger = logger;
+  }
+  routeMap;
+  async start() {
+    this.routeMap = this.registry.buildRouteMap();
+    const prefix = this.options.topicPrefix ?? "";
+    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(", ")}]`);
+      await this.transport.subscribe(
+        topics,
+        (message) => this.handleMessage(message),
+        {
+          fromBeginning: this.options.fromBeginning,
+          groupId: `${this.options.serviceName}-group`
+        }
+      );
+      this.logger.info("[SagaRunner] Consumer running");
+    } else {
+      this.logger.warn("[SagaRunner] No handlers registered \u2014 nothing to subscribe");
+    }
+  }
+  async stop() {
+    await this.transport.disconnect();
+  }
+  async handleMessage(message) {
+    const event = this.parser.parse(message);
+    if (!event) return;
+    const route = this.routeMap.get(event.eventType);
+    if (!route) return;
+    const isFinalHandler = route.options?.final === true;
+    const incoming = {
+      sagaId: event.sagaId,
+      eventId: event.eventId,
+      causationId: event.causationId,
+      eventType: event.eventType,
+      stepName: event.stepName,
+      stepDescription: event.stepDescription,
+      occurredAt: event.occurredAt,
+      parentSagaId: event.parentSagaId,
+      rootSagaId: event.rootSagaId,
+      payload: event.payload,
+      key: event.key,
+      sagaName: event.sagaName,
+      sagaDescription: event.sagaDescription
+    };
+    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);
+    };
+    const forkConfig = route.options?.fork;
+    const finalEmit = forkConfig ? async (params) => {
+      const subSagaId = uuidv7();
+      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,
+        rootSagaId: event.rootSagaId,
+        parentSagaId: event.sagaId,
+        causationId: event.eventId,
+        key: event.key,
+        sagaName: forkMeta.sagaName,
+        sagaDescription: forkMeta.sagaDescription
+      };
+      await SagaContext.run(forkCtx, () => subEmit({ ...params, hint: "fork" }));
+    } : wrappedEmit;
+    const spanAttrs = {
+      "saga.id": event.sagaId,
+      "saga.event.type": event.eventType,
+      "saga.step.name": event.stepName,
+      "saga.event.id": event.eventId,
+      "saga.root.id": event.rootSagaId,
+      "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.parentSagaId) spanAttrs["saga.parent.id"] = event.parentSagaId;
+    const sagaCtxData = {
+      sagaId: event.sagaId,
+      rootSagaId: event.rootSagaId,
+      parentSagaId: event.parentSagaId,
+      causationId: event.eventId,
+      key: event.key,
+      sagaName: event.sagaName,
+      sagaDescription: event.sagaDescription
+    };
+    const runHandler = () => SagaContext.run(
+      sagaCtxData,
+      () => this.runWithRetry(route.handler, route.participant, incoming, finalEmit)
+    );
+    if (this.otelCtx) {
+      await this.otelCtx.withExtractedSpan(`saga.handle ${event.eventType}`, spanAttrs, message.headers, runHandler);
+    } else {
+      await runHandler();
+    }
+  }
+  async runWithRetry(handler, participant, event, emit) {
+    const maxRetries = this.options.retryPolicy?.maxRetries ?? 3;
+    const initialDelayMs = this.options.retryPolicy?.initialDelayMs ?? 200;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await handler(event, emit);
+        return;
+      } catch (error) {
+        if (error instanceof SagaRetryableError) {
+          if (attempt < maxRetries) {
+            const delay = initialDelayMs * Math.pow(2, attempt);
+            await this.sleep(delay);
+            continue;
+          }
+          if (participant.onRetryExhausted) {
+            await participant.onRetryExhausted(event, error, emit);
+          }
+          return;
+        }
+        this.logger.error(
+          `[SagaRunner] Non-retryable error in handler for ${event.eventType}:`,
+          error
+        );
+        return;
+      }
+    }
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/publisher/saga-publisher.ts
+import { v7 as uuidv72 } from "uuid";
+
+// src/errors/saga-no-parent.error.ts
+var SagaNoParentError = class extends SagaError {
+  constructor() {
+    super("No parentSagaId in current saga context.");
+    this.name = "SagaNoParentError";
+  }
+};
+
+// src/publisher/message-builder.ts
+function buildOutboundMessage(event, topicPrefix = "") {
+  const topic = `${topicPrefix}${event.eventType}`;
+  const key = event.key ?? event.rootSagaId;
+  const headers = {
+    "saga-id": event.sagaId,
+    "saga-causation-id": event.causationId,
+    "saga-event-id": event.eventId,
+    "saga-step-name": event.stepName,
+    "saga-published-at": event.publishedAt,
+    "saga-schema-version": String(event.schemaVersion),
+    "saga-root-id": event.rootSagaId
+  };
+  if (event.parentSagaId) {
+    headers["saga-parent-id"] = event.parentSagaId;
+  }
+  if (event.hint) {
+    headers["saga-event-hint"] = event.hint;
+  }
+  if (event.sagaName) {
+    headers["saga-name"] = event.sagaName;
+  }
+  if (event.sagaDescription) {
+    headers["saga-description"] = event.sagaDescription;
+  }
+  if (event.stepDescription) {
+    headers["saga-step-description"] = event.stepDescription;
+  }
+  if (event.key) {
+    headers["saga-key"] = event.key;
+  }
+  const value = JSON.stringify({
+    eventType: event.eventType,
+    occurredAt: event.occurredAt,
+    payload: event.payload
+  });
+  return { topic, key, value, headers };
+}
+
+// src/publisher/saga-publisher.ts
+var SagaPublisher = class {
+  constructor(transport, otelCtx, topicPrefix = "") {
+    this.transport = transport;
+    this.otelCtx = otelCtx;
+    this.topicPrefix = topicPrefix;
+  }
+  async start(fn, opts) {
+    const sagaId = uuidv72();
+    const ctxData = {
+      sagaId,
+      rootSagaId: sagaId,
+      causationId: sagaId,
+      key: opts?.key,
+      sagaName: opts?.sagaName,
+      sagaDescription: opts?.sagaDescription
+    };
+    const result = await SagaContext.run(ctxData, fn);
+    return { sagaId, result };
+  }
+  async emit(params) {
+    const ctx = SagaContext.require();
+    const boundEmit = this.forSaga(ctx.sagaId, {
+      parentSagaId: ctx.parentSagaId,
+      rootSagaId: ctx.rootSagaId
+    }, ctx.causationId, ctx.key);
+    return boundEmit(params);
+  }
+  async startChild(fn, opts) {
+    const ctx = SagaContext.require();
+    const sagaId = uuidv72();
+    const childCtx = {
+      sagaId,
+      rootSagaId: ctx.rootSagaId,
+      parentSagaId: ctx.sagaId,
+      causationId: ctx.causationId,
+      key: opts?.key ?? ctx.key,
+      sagaName: opts?.sagaName ?? ctx.sagaName,
+      sagaDescription: opts?.sagaDescription ?? ctx.sagaDescription
+    };
+    const result = await SagaContext.run(childCtx, fn);
+    return { sagaId, result };
+  }
+  async emitToParent(paramsOrFn) {
+    const ctx = SagaContext.require();
+    if (!ctx.parentSagaId) {
+      throw new SagaNoParentError();
+    }
+    if (typeof paramsOrFn === "function") {
+      const parentCtx = {
+        sagaId: ctx.parentSagaId,
+        rootSagaId: ctx.rootSagaId,
+        parentSagaId: ctx.parentSagaId,
+        causationId: ctx.causationId,
+        key: ctx.key
+      };
+      await SagaContext.run(parentCtx, paramsOrFn);
+      return;
+    }
+    const parentEmit = this.forSaga(ctx.parentSagaId, {
+      parentSagaId: ctx.parentSagaId,
+      rootSagaId: ctx.rootSagaId
+    }, ctx.causationId, ctx.key);
+    return parentEmit(paramsOrFn);
+  }
+  forSaga(sagaId, parentCtx, causationId, baseKey) {
+    const rootSagaId = parentCtx?.rootSagaId ?? sagaId;
+    const parentSagaId = parentCtx?.parentSagaId;
+    const baseCausationId = causationId ?? sagaId;
+    return async ({
+      eventType,
+      stepName,
+      stepDescription,
+      payload,
+      hint,
+      key
+    }) => {
+      const ctx = SagaContext.current();
+      const resolvedKey = key ?? baseKey ?? ctx?.key;
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const event = {
+        sagaId,
+        causationId: baseCausationId,
+        eventId: uuidv72(),
+        eventType,
+        stepName,
+        stepDescription,
+        occurredAt: now,
+        publishedAt: now,
+        schemaVersion: 1,
+        rootSagaId,
+        parentSagaId,
+        payload,
+        hint,
+        key: resolvedKey,
+        sagaName: ctx?.sagaName,
+        sagaDescription: ctx?.sagaDescription
+      };
+      await this.publish(event);
+    };
+  }
+  async publish(event) {
+    this.otelCtx.injectBaggage(event.sagaId, event.rootSagaId, event.parentSagaId);
+    const attrs = {
+      "saga.id": event.sagaId,
+      "saga.event.type": event.eventType,
+      "saga.step.name": event.stepName,
+      "saga.root.id": event.rootSagaId
+    };
+    if (event.sagaName) {
+      attrs["saga.name"] = event.sagaName;
+    }
+    if (event.sagaDescription) {
+      attrs["saga.description"] = event.sagaDescription;
+    }
+    if (event.stepDescription) {
+      attrs["saga.step.description"] = event.stepDescription;
+    }
+    if (event.parentSagaId) {
+      attrs["saga.parent.id"] = event.parentSagaId;
+    }
+    this.otelCtx.enrichSpan(attrs);
+    const message = buildOutboundMessage(event, this.topicPrefix);
+    this.otelCtx.injectTraceContext(message.headers);
+    await this.otelCtx.withSpan(
+      `saga.publish ${event.eventType}`,
+      attrs,
+      () => this.transport.publish(message)
+    );
+  }
+};
+
+// src/parser/saga-parser.ts
+import { v7 as uuidv73 } from "uuid";
+var SagaParser = class {
+  constructor(otelCtx) {
+    this.otelCtx = otelCtx;
+  }
+  parse(message) {
+    try {
+      if (message.headers["saga-id"]) {
+        return this.parseFromHeaders(message);
+      }
+      const baggageResult = this.parseFromBaggage(message);
+      if (baggageResult) return baggageResult;
+      const body = JSON.parse(message.value);
+      if (body && body.sagaId) {
+        return body;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  parseFromHeaders(message) {
+    const headers = message.headers;
+    const body = JSON.parse(message.value);
+    const sagaId = headers["saga-id"];
+    if (!sagaId) {
+      return null;
+    }
+    return {
+      sagaId,
+      causationId: headers["saga-causation-id"] ?? sagaId,
+      eventId: headers["saga-event-id"] ?? uuidv73(),
+      eventType: body.eventType,
+      stepName: headers["saga-step-name"] ?? "",
+      occurredAt: body.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      publishedAt: headers["saga-published-at"] ?? (/* @__PURE__ */ new Date()).toISOString(),
+      schemaVersion: 1,
+      rootSagaId: headers["saga-root-id"] ?? sagaId,
+      parentSagaId: headers["saga-parent-id"] || void 0,
+      payload: body.payload,
+      sagaName: headers["saga-name"] || void 0,
+      sagaDescription: headers["saga-description"] || void 0,
+      stepDescription: headers["saga-step-description"] || void 0,
+      key: headers["saga-key"] || void 0
+    };
+  }
+  parseFromBaggage(message) {
+    let sagaId;
+    let rootSagaId;
+    let parentSagaId;
+    const baggageHeader = message.headers["baggage"];
+    if (baggageHeader) {
+      const entries = this.parseBaggageHeader(baggageHeader);
+      sagaId = entries["saga.id"];
+      rootSagaId = entries["saga.root.id"];
+      parentSagaId = entries["saga.parent.id"];
+    }
+    if (!sagaId) {
+      const extracted = this.otelCtx.extractBaggage();
+      sagaId = extracted.sagaId;
+      rootSagaId = extracted.rootSagaId;
+      parentSagaId = extracted.parentSagaId;
+    }
+    if (!sagaId) return null;
+    const body = JSON.parse(message.value);
+    return {
+      sagaId,
+      causationId: sagaId,
+      eventId: uuidv73(),
+      eventType: body.eventType,
+      stepName: "",
+      occurredAt: body.occurredAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+      publishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      schemaVersion: 1,
+      rootSagaId: rootSagaId ?? sagaId,
+      parentSagaId: parentSagaId || void 0,
+      payload: body.payload
+    };
+  }
+  parseBaggageHeader(baggage) {
+    const result = {};
+    for (const entry of baggage.split(",")) {
+      const [key, value] = entry.trim().split("=");
+      if (key && value) {
+        result[key.trim()] = decodeURIComponent(value.trim());
+      }
+    }
+    return result;
+  }
+};
+
+// src/errors/saga-duplicate-handler.error.ts
+var SagaDuplicateHandlerError = class extends SagaError {
+  constructor(eventType, existingServiceId, newServiceId) {
+    super(
+      `Duplicate handler for event type "${eventType}": registered by "${existingServiceId}" and "${newServiceId}"`
+    );
+    this.name = "SagaDuplicateHandlerError";
+  }
+};
+
+// src/errors/saga-invalid-handler-config.error.ts
+var SagaInvalidHandlerConfigError = class extends SagaError {
+  constructor(eventType, serviceId, reason) {
+    super(
+      `Invalid handler config for "${eventType}" in "${serviceId}": ${reason}`
+    );
+    this.name = "SagaInvalidHandlerConfigError";
+  }
+};
+
+// src/registry/saga-registry.ts
+var SagaRegistry = class {
+  participants = [];
+  register(participant) {
+    this.participants.push(participant);
+  }
+  getAll() {
+    return [...this.participants];
+  }
+  buildRouteMap() {
+    const map = /* @__PURE__ */ new Map();
+    for (const participant of this.participants) {
+      for (const [eventType, handler] of Object.entries(participant.on)) {
+        if (map.has(eventType)) {
+          const existing = map.get(eventType);
+          throw new SagaDuplicateHandlerError(
+            eventType,
+            existing.participant.serviceId,
+            participant.serviceId
+          );
+        }
+        const options = participant.handlerOptions?.[eventType];
+        if (options?.final && options?.fork) {
+          throw new SagaInvalidHandlerConfigError(
+            eventType,
+            participant.serviceId,
+            "cannot have both final and fork options"
+          );
+        }
+        map.set(eventType, { participant, handler, options });
+      }
+    }
+    return map;
+  }
+};
+
+// src/errors/saga-parse.error.ts
+var SagaParseError = class extends SagaError {
+  constructor(message) {
+    super(message);
+    this.name = "SagaParseError";
+  }
+};
+
+// src/errors/saga-transport-not-connected.error.ts
+var SagaTransportNotConnectedError = class extends SagaError {
+  constructor() {
+    super("Transport not connected");
+    this.name = "SagaTransportNotConnectedError";
+  }
+};
+
+// src/otel/otel-context.ts
+var NoopOtelContext = class {
+  injectBaggage() {
+  }
+  extractBaggage() {
+    return {};
+  }
+  enrichSpan() {
+  }
+  async withSpan(_name, _attrs, fn) {
+    return fn();
+  }
+  injectTraceContext() {
+  }
+  async withExtractedSpan(_name, _attrs, _headers, fn) {
+    return fn();
+  }
+};
+var W3cOtelContext = class {
+  api;
+  constructor(api) {
+    this.api = api;
+  }
+  injectBaggage(sagaId, rootSagaId, parentSagaId) {
+    const entries = {
+      "saga.id": { value: sagaId },
+      "saga.root.id": { value: rootSagaId }
+    };
+    if (parentSagaId) {
+      entries["saga.parent.id"] = { value: parentSagaId };
+    }
+    const baggage = this.api.propagation.createBaggage(entries);
+    const ctx = this.api.propagation.setBaggage(this.api.context.active(), baggage);
+    this.api.context.with(ctx, () => {
+    });
+  }
+  extractBaggage() {
+    const baggage = this.api.propagation.getBaggage(this.api.context.active());
+    if (!baggage) return {};
+    return {
+      sagaId: baggage.getEntry("saga.id")?.value,
+      rootSagaId: baggage.getEntry("saga.root.id")?.value,
+      parentSagaId: baggage.getEntry("saga.parent.id")?.value
+    };
+  }
+  enrichSpan(attrs) {
+    const span = this.api.trace.getActiveSpan();
+    if (span) {
+      span.setAttributes(attrs);
+    }
+  }
+  async withSpan(name, attrs, fn) {
+    const tracer = this.api.trace.getTracer("@fbsm/saga-core");
+    return tracer.startActiveSpan(name, 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();
+      }
+    });
+  }
+  injectTraceContext(headers) {
+    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 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();
+        }
+      })
+    );
+  }
+};
+function createOtelContext(enabled) {
+  if (!enabled) return new NoopOtelContext();
+  try {
+    const api = __require("@opentelemetry/api");
+    return new W3cOtelContext(api);
+  } catch {
+    return new NoopOtelContext();
+  }
+}
+export {
+  ConsoleSagaLogger,
+  NoopOtelContext,
+  SagaContext,
+  SagaContextNotFoundError,
+  SagaDuplicateHandlerError,
+  SagaError,
+  SagaInvalidHandlerConfigError,
+  SagaNoParentError,
+  SagaParseError,
+  SagaParser,
+  SagaPublisher,
+  SagaRegistry,
+  SagaRetryableError,
+  SagaRunner,
+  SagaTransportNotConnectedError,
+  W3cOtelContext,
+  createOtelContext
+};
+//# sourceMappingURL=index.js.map