@saga-bus/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1097 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConcurrencyError: () => ConcurrencyError,
+  DEFAULT_RETRY_POLICY: () => DEFAULT_RETRY_POLICY,
+  DEFAULT_TIMEOUT_BOUNDS: () => DEFAULT_TIMEOUT_BOUNDS,
+  DefaultErrorHandler: () => DefaultErrorHandler,
+  DefaultLogger: () => DefaultLogger,
+  RETRY_HEADERS: () => RETRY_HEADERS,
+  SagaMachineBuilder: () => SagaMachineBuilder,
+  SagaProcessingError: () => SagaProcessingError,
+  TransientError: () => TransientError,
+  ValidationError: () => ValidationError,
+  createBus: () => createBus,
+  createErrorHandler: () => createErrorHandler,
+  createSagaMachine: () => createSagaMachine,
+  defaultDlqNaming: () => defaultDlqNaming
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/index.ts
+var ConcurrencyError = class extends Error {
+  sagaId;
+  expectedVersion;
+  actualVersion;
+  constructor(sagaId, expectedVersion, actualVersion) {
+    const message = actualVersion !== void 0 ? `Concurrency conflict for saga ${sagaId}: expected version ${expectedVersion}, got ${actualVersion}` : `Concurrency conflict for saga ${sagaId}: expected version ${expectedVersion}`;
+    super(message);
+    this.name = "ConcurrencyError";
+    this.sagaId = sagaId;
+    this.expectedVersion = expectedVersion;
+    this.actualVersion = actualVersion;
+  }
+};
+var TransientError = class _TransientError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "TransientError";
+    this.cause = cause;
+  }
+  static wrap(error) {
+    return new _TransientError(error.message, error);
+  }
+};
+var ValidationError = class extends Error {
+  field;
+  value;
+  constructor(message, field, value) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+    this.value = value;
+  }
+};
+var SagaProcessingError = class _SagaProcessingError extends Error {
+  context;
+  cause;
+  constructor(cause, context) {
+    super(`Error processing message in ${context.sagaName}: ${cause.message}`);
+    this.name = "SagaProcessingError";
+    this.cause = cause;
+    this.context = context;
+  }
+  /**
+   * Check if an error is a SagaProcessingError and extract context.
+   */
+  static extractContext(error) {
+    if (error instanceof _SagaProcessingError) {
+      return error.context;
+    }
+    return null;
+  }
+};
+
+// src/dsl/HandlerBuilder.ts
+var HandlerBuilder = class {
+  constructor(parent, messageType) {
+    this.parent = parent;
+    this.messageType = messageType;
+  }
+  guard;
+  /**
+   * Add a state guard that must pass for the handler to execute.
+   * Multiple guards can be chained with multiple .when() calls.
+   */
+  when(guard) {
+    if (this.guard) {
+      const existingGuard = this.guard;
+      this.guard = (state) => existingGuard(state) && guard(state);
+    } else {
+      this.guard = guard;
+    }
+    return this;
+  }
+  /**
+   * Register the handler function and return to the parent builder.
+   */
+  handle(handler) {
+    const registration = {
+      messageType: this.messageType,
+      guard: this.guard,
+      handler
+    };
+    return this.parent._registerHandler(
+      registration
+    );
+  }
+};
+
+// src/dsl/SagaDefinitionImpl.ts
+var SagaDefinitionImpl = class {
+  name;
+  handledMessageTypes;
+  correlations;
+  wildcardCorrelation;
+  handlers;
+  initialFactory;
+  constructor(config) {
+    this.name = config.name;
+    this.correlations = config.correlations;
+    this.wildcardCorrelation = config.wildcardCorrelation;
+    this.handlers = config.handlers;
+    this.initialFactory = config.initialFactory;
+    const types = /* @__PURE__ */ new Set();
+    for (const type of this.correlations.keys()) {
+      types.add(type);
+    }
+    for (const type of this.handlers.keys()) {
+      types.add(type);
+    }
+    this.handledMessageTypes = Array.from(types);
+  }
+  getCorrelation(message) {
+    const specific = this.correlations.get(message.type);
+    if (specific) {
+      return {
+        canStart: specific.canStart,
+        getCorrelationId: (msg) => specific.getCorrelationId(msg)
+      };
+    }
+    if (this.wildcardCorrelation) {
+      return {
+        canStart: this.wildcardCorrelation.canStart,
+        getCorrelationId: (msg) => this.wildcardCorrelation.getCorrelationId(msg)
+      };
+    }
+    return {
+      canStart: false,
+      getCorrelationId: () => null
+    };
+  }
+  async createInitialState(message, ctx) {
+    if (!this.initialFactory) {
+      throw new Error(
+        `No initial state factory defined for saga "${this.name}"`
+      );
+    }
+    return this.initialFactory(message, ctx);
+  }
+  async handle(message, state, ctx) {
+    const registrations = this.handlers.get(message.type);
+    if (!registrations || registrations.length === 0) {
+      return { newState: state };
+    }
+    for (const registration of registrations) {
+      if (!registration.guard || registration.guard(state)) {
+        return registration.handler(message, state, ctx);
+      }
+    }
+    return { newState: state };
+  }
+};
+
+// src/dsl/SagaMachineBuilder.ts
+var SagaMachineBuilder = class {
+  sagaName;
+  correlations = /* @__PURE__ */ new Map();
+  wildcardCorrelation;
+  handlers = /* @__PURE__ */ new Map();
+  initialFactory;
+  /**
+   * Set the saga name.
+   */
+  name(sagaName) {
+    this.sagaName = sagaName;
+    return this;
+  }
+  /**
+   * Define how to correlate messages to saga instances.
+   *
+   * @param messageType - The message type to correlate, or "*" for wildcard
+   * @param getCorrelationId - Function to extract correlation ID from message
+   * @param options - Correlation options (e.g., canStart)
+   */
+  correlate(messageType, getCorrelationId, options = {}) {
+    const config = {
+      canStart: options.canStart ?? false,
+      getCorrelationId
+    };
+    if (messageType === "*") {
+      this.wildcardCorrelation = config;
+    } else {
+      this.correlations.set(messageType, config);
+    }
+    return this;
+  }
+  /**
+   * Define the initial state factory for new saga instances.
+   *
+   * @param factory - Function to create initial state from the starting message
+   */
+  initial(factory) {
+    this.initialFactory = factory;
+    return this;
+  }
+  /**
+   * Start defining a handler for a specific message type.
+   *
+   * @param messageType - The message type to handle
+   * @returns A HandlerBuilder for chaining .when() and .handle()
+   */
+  on(messageType) {
+    return new HandlerBuilder(this, messageType);
+  }
+  /**
+   * Internal method called by HandlerBuilder to register a handler.
+   * @internal
+   */
+  _registerHandler(registration) {
+    const existing = this.handlers.get(registration.messageType);
+    if (existing) {
+      existing.push(registration);
+    } else {
+      this.handlers.set(registration.messageType, [registration]);
+    }
+    return this;
+  }
+  /**
+   * Build the saga definition.
+   *
+   * @throws Error if required configuration is missing
+   */
+  build() {
+    if (!this.sagaName) {
+      throw new Error("Saga name is required. Call .name() before .build()");
+    }
+    let hasStartingCorrelation = false;
+    for (const config of this.correlations.values()) {
+      if (config.canStart) {
+        hasStartingCorrelation = true;
+        break;
+      }
+    }
+    if (this.wildcardCorrelation?.canStart) {
+      hasStartingCorrelation = true;
+    }
+    if (!hasStartingCorrelation) {
+      throw new Error(
+        `Saga "${this.sagaName}" has no correlation with canStart: true`
+      );
+    }
+    if (!this.initialFactory) {
+      throw new Error(
+        `Saga "${this.sagaName}" requires an initial state factory. Call .initial() before .build()`
+      );
+    }
+    return new SagaDefinitionImpl({
+      name: this.sagaName,
+      correlations: this.correlations,
+      wildcardCorrelation: this.wildcardCorrelation,
+      handlers: this.handlers,
+      initialFactory: this.initialFactory
+    });
+  }
+};
+function createSagaMachine() {
+  return new SagaMachineBuilder();
+}
+
+// src/types/messages.ts
+var SAGA_TIMEOUT_MESSAGE_TYPE = "SagaTimeoutExpired";
+
+// src/runtime/SagaContextImpl.ts
+var DEFAULT_TIMEOUT_BOUNDS = {
+  minMs: 1e3,
+  // 1 second minimum
+  maxMs: 6048e5
+  // 7 days maximum
+};
+var SagaContextImpl = class {
+  sagaName;
+  sagaId;
+  correlationId;
+  envelope;
+  metadata = {};
+  transport;
+  defaultEndpoint;
+  timeoutBounds;
+  _isCompleted = false;
+  _currentMetadata;
+  _pendingTimeoutChange;
+  constructor(options) {
+    this.sagaName = options.sagaName;
+    this.sagaId = options.sagaId;
+    this.correlationId = options.correlationId;
+    this.envelope = options.envelope;
+    this.transport = options.transport;
+    this.defaultEndpoint = options.defaultEndpoint;
+    this._currentMetadata = options.currentMetadata;
+    this.timeoutBounds = {
+      minMs: options.timeoutBounds?.minMs ?? DEFAULT_TIMEOUT_BOUNDS.minMs,
+      maxMs: options.timeoutBounds?.maxMs ?? DEFAULT_TIMEOUT_BOUNDS.maxMs
+    };
+  }
+  async publish(message, options) {
+    const endpoint = options?.endpoint ?? this.defaultEndpoint ?? message.type;
+    await this.transport.publish(message, {
+      endpoint,
+      ...options
+    });
+  }
+  async schedule(message, delayMs, options) {
+    const endpoint = options?.endpoint ?? this.defaultEndpoint ?? message.type;
+    await this.transport.publish(message, {
+      endpoint,
+      delayMs,
+      ...options
+    });
+  }
+  complete() {
+    this._isCompleted = true;
+  }
+  setMetadata(key, value) {
+    this.metadata[key] = value;
+  }
+  getMetadata(key) {
+    return this.metadata[key];
+  }
+  /**
+   * Check if complete() was called.
+   */
+  get isCompleted() {
+    return this._isCompleted;
+  }
+  setTimeout(delayMs) {
+    if (delayMs <= 0) {
+      throw new Error("Timeout delay must be positive");
+    }
+    if (delayMs < this.timeoutBounds.minMs) {
+      throw new Error(
+        `Timeout delay ${delayMs}ms is below minimum allowed (${this.timeoutBounds.minMs}ms)`
+      );
+    }
+    if (delayMs > this.timeoutBounds.maxMs) {
+      throw new Error(
+        `Timeout delay ${delayMs}ms exceeds maximum allowed (${this.timeoutBounds.maxMs}ms)`
+      );
+    }
+    const now2 = /* @__PURE__ */ new Date();
+    this._pendingTimeoutChange = {
+      type: "set",
+      timeoutMs: delayMs,
+      timeoutExpiresAt: new Date(now2.getTime() + delayMs)
+    };
+  }
+  clearTimeout() {
+    this._pendingTimeoutChange = {
+      type: "clear"
+    };
+  }
+  getTimeoutRemaining() {
+    if (this._pendingTimeoutChange) {
+      if (this._pendingTimeoutChange.type === "clear") {
+        return null;
+      }
+      if (this._pendingTimeoutChange.timeoutExpiresAt) {
+        const remaining = this._pendingTimeoutChange.timeoutExpiresAt.getTime() - Date.now();
+        return Math.max(0, remaining);
+      }
+    }
+    if (this._currentMetadata?.timeoutExpiresAt) {
+      const remaining = this._currentMetadata.timeoutExpiresAt.getTime() - Date.now();
+      return Math.max(0, remaining);
+    }
+    return null;
+  }
+  /**
+   * Get any pending timeout change to be applied to saga state.
+   * Used by SagaOrchestrator when updating state.
+   */
+  get pendingTimeoutChange() {
+    return this._pendingTimeoutChange;
+  }
+  /**
+   * Update the current metadata reference (called after state is loaded/created).
+   */
+  updateCurrentMetadata(metadata) {
+    this._currentMetadata = metadata;
+  }
+};
+
+// src/runtime/utils.ts
+var import_node_crypto = require("crypto");
+function generateSagaId() {
+  return (0, import_node_crypto.randomUUID)();
+}
+function now() {
+  return /* @__PURE__ */ new Date();
+}
+
+// src/runtime/SagaOrchestrator.ts
+var SagaOrchestrator = class {
+  definition;
+  store;
+  transport;
+  pipeline;
+  logger;
+  defaultEndpoint;
+  timeoutBounds;
+  onCorrelationFailure;
+  constructor(options) {
+    this.definition = options.definition;
+    this.store = options.store;
+    this.transport = options.transport;
+    this.pipeline = options.pipeline;
+    this.logger = options.logger;
+    this.defaultEndpoint = options.defaultEndpoint;
+    this.timeoutBounds = options.timeoutBounds;
+    this.onCorrelationFailure = options.onCorrelationFailure;
+  }
+  /**
+   * Process an incoming message.
+   * @returns CorrelationFailureResult if message failed correlation, undefined otherwise
+   */
+  async processMessage(envelope) {
+    const message = envelope.payload;
+    const correlation = this.definition.getCorrelation(message);
+    const correlationId = correlation.getCorrelationId(message);
+    if (!correlationId) {
+      this.logger.warn("Could not correlate message", {
+        sagaName: this.definition.name,
+        messageType: message.type,
+        messageId: envelope.id
+      });
+      let action = "drop";
+      if (this.onCorrelationFailure) {
+        action = await this.onCorrelationFailure({
+          envelope,
+          sagaName: this.definition.name,
+          messageType: message.type
+        });
+      }
+      return {
+        failed: true,
+        action,
+        messageType: message.type
+      };
+    }
+    const existingState = await this.store.getByCorrelationId(
+      this.definition.name,
+      correlationId
+    );
+    let traceContext;
+    const pipelineCtx = {
+      envelope,
+      sagaName: this.definition.name,
+      correlationId,
+      existingState,
+      // Provide existing state to middleware
+      metadata: {},
+      setTraceContext(traceParent, traceState) {
+        traceContext = { traceParent, traceState };
+        pipelineCtx.traceContext = traceContext;
+      }
+    };
+    try {
+      await this.pipeline.execute(pipelineCtx, async () => {
+        await this.handleMessage(envelope, correlationId, correlation.canStart, existingState, pipelineCtx);
+      });
+    } catch (error) {
+      pipelineCtx.error = error;
+      const wrappedError = new SagaProcessingError(
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          sagaName: this.definition.name,
+          correlationId,
+          sagaId: pipelineCtx.sagaId,
+          messageType: message.type,
+          messageId: envelope.id
+        }
+      );
+      throw wrappedError;
+    }
+  }
+  async handleMessage(envelope, correlationId, canStart, existingState, pipelineCtx) {
+    const message = envelope.payload;
+    let state = existingState;
+    let sagaId;
+    if (!state) {
+      if (!canStart) {
+        this.logger.debug("Message cannot start saga and no existing saga found", {
+          sagaName: this.definition.name,
+          messageType: message.type,
+          correlationId
+        });
+        return;
+      }
+      sagaId = generateSagaId();
+      const ctx2 = new SagaContextImpl({
+        sagaName: this.definition.name,
+        sagaId,
+        correlationId,
+        envelope,
+        transport: this.transport,
+        timeoutBounds: this.timeoutBounds
+      });
+      state = await this.definition.createInitialState(message, ctx2);
+      state = {
+        ...state,
+        metadata: {
+          ...state.metadata,
+          sagaId,
+          version: 0,
+          createdAt: now(),
+          updatedAt: now(),
+          isCompleted: false,
+          traceParent: pipelineCtx.traceContext?.traceParent ?? null,
+          traceState: pipelineCtx.traceContext?.traceState ?? null
+        }
+      };
+      await this.store.insert(this.definition.name, correlationId, state);
+      this.logger.info("Created new saga instance", {
+        sagaName: this.definition.name,
+        sagaId,
+        correlationId,
+        messageType: message.type
+      });
+    } else {
+      sagaId = state.metadata.sagaId;
+    }
+    pipelineCtx.sagaId = sagaId;
+    pipelineCtx.preState = state;
+    if (state.metadata.isCompleted) {
+      this.logger.debug("Ignoring message for completed saga", {
+        sagaName: this.definition.name,
+        sagaId,
+        messageType: message.type
+      });
+      return;
+    }
+    const ctx = new SagaContextImpl({
+      sagaName: this.definition.name,
+      sagaId,
+      correlationId,
+      envelope,
+      transport: this.transport,
+      defaultEndpoint: this.defaultEndpoint,
+      currentMetadata: state.metadata,
+      timeoutBounds: this.timeoutBounds
+    });
+    const result = await this.definition.handle(message, state, ctx);
+    const isCompleted = result.isCompleted ?? ctx.isCompleted;
+    const expectedVersion = state.metadata.version;
+    const pendingTimeout = ctx.pendingTimeoutChange;
+    let timeoutMs = state.metadata.timeoutMs;
+    let timeoutExpiresAt = state.metadata.timeoutExpiresAt;
+    if (pendingTimeout) {
+      if (pendingTimeout.type === "clear") {
+        timeoutMs = null;
+        timeoutExpiresAt = null;
+      } else if (pendingTimeout.type === "set") {
+        timeoutMs = pendingTimeout.timeoutMs ?? null;
+        timeoutExpiresAt = pendingTimeout.timeoutExpiresAt ?? null;
+      }
+    }
+    const newState = {
+      ...result.newState,
+      metadata: {
+        ...result.newState.metadata,
+        version: expectedVersion + 1,
+        updatedAt: now(),
+        isCompleted,
+        timeoutMs,
+        timeoutExpiresAt
+      }
+    };
+    pipelineCtx.postState = newState;
+    pipelineCtx.handlerResult = result;
+    try {
+      await this.store.update(this.definition.name, newState, expectedVersion);
+    } catch (error) {
+      if (error instanceof ConcurrencyError) {
+        this.logger.warn("Concurrency conflict, message will be retried", {
+          sagaName: this.definition.name,
+          sagaId,
+          expectedVersion,
+          actualVersion: error.actualVersion
+        });
+      }
+      throw error;
+    }
+    if (pendingTimeout?.type === "set" && !isCompleted && pendingTimeout.timeoutMs) {
+      await this.scheduleTimeoutMessage(
+        sagaId,
+        correlationId,
+        pendingTimeout.timeoutMs,
+        pendingTimeout.timeoutExpiresAt ?? /* @__PURE__ */ new Date()
+      );
+    }
+    if (isCompleted) {
+      this.logger.info("Saga completed", {
+        sagaName: this.definition.name,
+        sagaId,
+        correlationId
+      });
+    } else {
+      this.logger.debug("Saga state updated", {
+        sagaName: this.definition.name,
+        sagaId,
+        version: newState.metadata.version
+      });
+    }
+  }
+  /**
+   * Schedule a timeout message for delayed delivery.
+   */
+  async scheduleTimeoutMessage(sagaId, correlationId, timeoutMs, timeoutExpiresAt) {
+    const timeoutMessage = {
+      type: SAGA_TIMEOUT_MESSAGE_TYPE,
+      sagaId,
+      sagaName: this.definition.name,
+      correlationId,
+      timeoutMs,
+      timeoutSetAt: new Date(timeoutExpiresAt.getTime() - timeoutMs)
+    };
+    const endpoint = this.defaultEndpoint ?? SAGA_TIMEOUT_MESSAGE_TYPE;
+    await this.transport.publish(timeoutMessage, {
+      endpoint,
+      delayMs: timeoutMs,
+      key: correlationId
+      // Use correlation ID for ordering
+    });
+    this.logger.debug("Scheduled timeout message", {
+      sagaName: this.definition.name,
+      sagaId,
+      correlationId,
+      timeoutMs,
+      timeoutExpiresAt: timeoutExpiresAt.toISOString()
+    });
+  }
+  /**
+   * Get the saga name.
+   */
+  get name() {
+    return this.definition.name;
+  }
+  /**
+   * Get the handled message types.
+   */
+  get handledMessageTypes() {
+    return this.definition.handledMessageTypes;
+  }
+};
+
+// src/runtime/MiddlewarePipeline.ts
+var MiddlewarePipeline = class {
+  middleware;
+  constructor(middleware = []) {
+    this.middleware = middleware;
+  }
+  /**
+   * Execute the pipeline with a core handler at the end.
+   */
+  async execute(ctx, coreHandler) {
+    let index = 0;
+    const next = async () => {
+      if (index < this.middleware.length) {
+        const mw = this.middleware[index];
+        index++;
+        if (mw) {
+          await mw(ctx, next);
+        }
+      } else {
+        await coreHandler();
+      }
+    };
+    await next();
+  }
+};
+
+// src/runtime/DefaultLogger.ts
+var DefaultLogger = class {
+  prefix;
+  constructor(prefix = "[saga-bus]") {
+    this.prefix = prefix;
+  }
+  debug(message, meta) {
+    if (meta) {
+      console.debug(`${this.prefix} ${message}`, meta);
+    } else {
+      console.debug(`${this.prefix} ${message}`);
+    }
+  }
+  info(message, meta) {
+    if (meta) {
+      console.info(`${this.prefix} ${message}`, meta);
+    } else {
+      console.info(`${this.prefix} ${message}`);
+    }
+  }
+  warn(message, meta) {
+    if (meta) {
+      console.warn(`${this.prefix} ${message}`, meta);
+    } else {
+      console.warn(`${this.prefix} ${message}`);
+    }
+  }
+  error(message, meta) {
+    if (meta) {
+      console.error(`${this.prefix} ${message}`, meta);
+    } else {
+      console.error(`${this.prefix} ${message}`);
+    }
+  }
+};
+
+// src/runtime/DefaultErrorHandler.ts
+var TRANSIENT_ERROR_PATTERNS = [
+  /ECONNREFUSED/i,
+  /ECONNRESET/i,
+  /ETIMEDOUT/i,
+  /ENOTFOUND/i,
+  /timeout/i,
+  /connection.*refused/i,
+  /connection.*reset/i,
+  /network/i,
+  /socket hang up/i,
+  /EPIPE/i,
+  /EHOSTUNREACH/i
+];
+function isTransientError(error) {
+  if (error instanceof TransientError) {
+    return true;
+  }
+  if (error instanceof ConcurrencyError) {
+    return true;
+  }
+  if (error instanceof Error) {
+    const message = error.message;
+    return TRANSIENT_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+  }
+  return false;
+}
+var DefaultErrorHandler = class {
+  async handle(error, _ctx) {
+    if (isTransientError(error)) {
+      return "retry";
+    }
+    return "dlq";
+  }
+};
+function createErrorHandler(options) {
+  const additionalPatterns = options?.additionalTransientPatterns ?? [];
+  const customClassifier = options?.customClassifier;
+  return {
+    async handle(error, ctx) {
+      if (customClassifier) {
+        const result = customClassifier(error, ctx);
+        if (result !== null) {
+          return result;
+        }
+      }
+      if (isTransientError(error)) {
+        return "retry";
+      }
+      if (error instanceof Error) {
+        const message = error.message;
+        if (additionalPatterns.some((pattern) => pattern.test(message))) {
+          return "retry";
+        }
+      }
+      return "dlq";
+    }
+  };
+}
+
+// src/runtime/RetryHandler.ts
+var RETRY_HEADERS = {
+  ATTEMPT: "x-saga-attempt",
+  FIRST_SEEN: "x-saga-first-seen",
+  ORIGINAL_ENDPOINT: "x-saga-original-endpoint",
+  ERROR_MESSAGE: "x-saga-error-message",
+  ERROR_TYPE: "x-saga-error-type"
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  backoff: "exponential"
+};
+function defaultDlqNaming(endpoint) {
+  return `${endpoint}.dlq`;
+}
+function calculateDelay(policy, attempt) {
+  let delay;
+  if (policy.backoff === "linear") {
+    delay = policy.baseDelayMs * attempt;
+  } else {
+    delay = policy.baseDelayMs * Math.pow(2, attempt - 1);
+  }
+  return Math.min(delay, policy.maxDelayMs);
+}
+function getAttemptCount(envelope) {
+  const attempt = envelope.headers[RETRY_HEADERS.ATTEMPT];
+  if (attempt) {
+    const parsed = parseInt(attempt, 10);
+    return isNaN(parsed) ? 1 : parsed;
+  }
+  return 1;
+}
+function getFirstSeen(envelope) {
+  const firstSeen = envelope.headers[RETRY_HEADERS.FIRST_SEEN];
+  if (firstSeen) {
+    return new Date(firstSeen);
+  }
+  return envelope.timestamp;
+}
+var RetryHandler = class {
+  transport;
+  logger;
+  defaultPolicy;
+  dlqNaming;
+  constructor(options) {
+    this.transport = options.transport;
+    this.logger = options.logger;
+    this.defaultPolicy = options.defaultPolicy;
+    this.dlqNaming = options.dlqNaming;
+  }
+  /**
+   * Handle a failed message - either retry or send to DLQ.
+   *
+   * @returns true if message was retried, false if sent to DLQ
+   */
+  async handleFailure(envelope, endpoint, error, policy = this.defaultPolicy) {
+    const attempt = getAttemptCount(envelope);
+    const firstSeen = getFirstSeen(envelope);
+    if (attempt < policy.maxAttempts) {
+      const delay = calculateDelay(policy, attempt);
+      const nextAttempt = attempt + 1;
+      this.logger.info("Retrying message", {
+        messageId: envelope.id,
+        messageType: envelope.type,
+        endpoint,
+        attempt: nextAttempt,
+        maxAttempts: policy.maxAttempts,
+        delayMs: delay
+      });
+      const retryHeaders = {
+        ...envelope.headers,
+        [RETRY_HEADERS.ATTEMPT]: String(nextAttempt),
+        [RETRY_HEADERS.FIRST_SEEN]: firstSeen.toISOString(),
+        [RETRY_HEADERS.ORIGINAL_ENDPOINT]: envelope.headers[RETRY_HEADERS.ORIGINAL_ENDPOINT] ?? endpoint
+      };
+      await this.transport.publish(envelope.payload, {
+        endpoint,
+        headers: retryHeaders,
+        delayMs: delay,
+        key: envelope.partitionKey
+      });
+      return true;
+    }
+    await this.sendToDlq(envelope, endpoint, error);
+    return false;
+  }
+  /**
+   * Send a message to the dead-letter queue.
+   */
+  async sendToDlq(envelope, originalEndpoint, error) {
+    const dlqEndpoint = this.dlqNaming(originalEndpoint);
+    const attempt = getAttemptCount(envelope);
+    const firstSeen = getFirstSeen(envelope);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const errorType = error instanceof Error ? error.name : "UnknownError";
+    this.logger.warn("Sending message to DLQ", {
+      messageId: envelope.id,
+      messageType: envelope.type,
+      originalEndpoint,
+      dlqEndpoint,
+      attempts: attempt,
+      firstSeen: firstSeen.toISOString(),
+      error: errorMessage
+    });
+    const dlqHeaders = {
+      ...envelope.headers,
+      [RETRY_HEADERS.ATTEMPT]: String(attempt),
+      [RETRY_HEADERS.FIRST_SEEN]: firstSeen.toISOString(),
+      [RETRY_HEADERS.ORIGINAL_ENDPOINT]: envelope.headers[RETRY_HEADERS.ORIGINAL_ENDPOINT] ?? originalEndpoint,
+      [RETRY_HEADERS.ERROR_MESSAGE]: errorMessage,
+      [RETRY_HEADERS.ERROR_TYPE]: errorType
+    };
+    await this.transport.publish(envelope.payload, {
+      endpoint: dlqEndpoint,
+      headers: dlqHeaders,
+      key: envelope.partitionKey
+    });
+  }
+};
+
+// src/runtime/BusImpl.ts
+var BusImpl = class {
+  config;
+  logger;
+  errorHandler;
+  pipeline;
+  orchestrators;
+  retryHandler;
+  defaultRetryPolicy;
+  started = false;
+  constructor(config) {
+    this.config = config;
+    this.logger = config.logger ?? new DefaultLogger();
+    this.errorHandler = config.errorHandler ?? new DefaultErrorHandler();
+    this.pipeline = new MiddlewarePipeline(config.middleware ? [...config.middleware] : []);
+    this.defaultRetryPolicy = config.worker?.retryPolicy ?? DEFAULT_RETRY_POLICY;
+    const dlqNaming = config.worker?.dlqNaming ?? defaultDlqNaming;
+    this.retryHandler = new RetryHandler({
+      transport: config.transport,
+      logger: this.logger,
+      defaultPolicy: this.defaultRetryPolicy,
+      dlqNaming
+    });
+    this.orchestrators = config.sagas.map((registration) => {
+      const store = registration.store ?? config.store;
+      if (!store) {
+        throw new Error(
+          `Saga "${registration.definition.name}" has no store. Provide a store in the saga registration or set a default store in BusConfig.`
+        );
+      }
+      return new SagaOrchestrator({
+        definition: registration.definition,
+        store,
+        transport: config.transport,
+        pipeline: this.pipeline,
+        logger: this.logger,
+        timeoutBounds: config.worker?.timeoutBounds,
+        onCorrelationFailure: config.worker?.onCorrelationFailure
+      });
+    });
+  }
+  async start() {
+    if (this.started) {
+      return;
+    }
+    this.logger.info("Starting saga bus...");
+    await this.config.transport.start();
+    const subscribed = /* @__PURE__ */ new Set();
+    for (const orchestrator of this.orchestrators) {
+      for (const messageType of orchestrator.handledMessageTypes) {
+        const endpoint = messageType;
+        const subscriptionKey = endpoint;
+        if (subscribed.has(subscriptionKey)) {
+          continue;
+        }
+        subscribed.add(subscriptionKey);
+        const concurrency = this.config.worker?.sagas?.[orchestrator.name]?.concurrency ?? this.config.worker?.defaultConcurrency ?? 1;
+        await this.config.transport.subscribe(
+          { endpoint, concurrency },
+          async (envelope) => {
+            const handlers = this.orchestrators.filter(
+              (o) => o.handledMessageTypes.includes(envelope.type)
+            );
+            for (const handler of handlers) {
+              const retryPolicy = this.config.worker?.sagas?.[handler.name]?.retryPolicy ?? this.defaultRetryPolicy;
+              try {
+                const result = await handler.processMessage(envelope);
+                if (result?.failed) {
+                  if (result.action === "dlq") {
+                    await this.retryHandler.sendToDlq(
+                      envelope,
+                      endpoint,
+                      new Error(`Correlation failed for message type ${result.messageType}`)
+                    );
+                  }
+                  continue;
+                }
+              } catch (error) {
+                const errorContext = SagaProcessingError.extractContext(error);
+                const originalError = error instanceof SagaProcessingError ? error.cause : error;
+                this.logger.error("Error processing message", {
+                  sagaName: handler.name,
+                  messageType: envelope.type,
+                  messageId: envelope.id,
+                  correlationId: errorContext?.correlationId,
+                  sagaId: errorContext?.sagaId,
+                  attempt: getAttemptCount(envelope),
+                  error: originalError instanceof Error ? originalError.message : String(originalError)
+                });
+                const action = await this.errorHandler.handle(originalError, {
+                  envelope,
+                  sagaName: handler.name,
+                  correlationId: errorContext?.correlationId ?? "",
+                  metadata: {
+                    sagaId: errorContext?.sagaId
+                  },
+                  error: originalError,
+                  setTraceContext: () => {
+                  }
+                  // No-op for error context
+                });
+                if (action === "retry") {
+                  await this.retryHandler.handleFailure(
+                    envelope,
+                    endpoint,
+                    error,
+                    retryPolicy
+                  );
+                } else if (action === "dlq") {
+                  await this.retryHandler.sendToDlq(envelope, endpoint, error);
+                }
+              }
+            }
+          }
+        );
+        this.logger.debug("Subscribed to endpoint", {
+          endpoint,
+          messageType,
+          concurrency
+        });
+      }
+    }
+    this.started = true;
+    this.logger.info("Saga bus started", {
+      sagaCount: this.orchestrators.length,
+      endpointCount: subscribed.size
+    });
+  }
+  async stop() {
+    if (!this.started) {
+      return;
+    }
+    this.logger.info("Stopping saga bus...");
+    await this.config.transport.stop();
+    this.started = false;
+    this.logger.info("Saga bus stopped");
+  }
+  isRunning() {
+    return this.started;
+  }
+  async publish(message, options) {
+    const endpoint = options?.endpoint ?? message.type;
+    await this.config.transport.publish(message, {
+      endpoint,
+      ...options
+    });
+  }
+};
+function createBus(config) {
+  return new BusImpl(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConcurrencyError,
+  DEFAULT_RETRY_POLICY,
+  DEFAULT_TIMEOUT_BOUNDS,
+  DefaultErrorHandler,
+  DefaultLogger,
+  RETRY_HEADERS,
+  SagaMachineBuilder,
+  SagaProcessingError,
+  TransientError,
+  ValidationError,
+  createBus,
+  createErrorHandler,
+  createSagaMachine,
+  defaultDlqNaming
+});
+//# sourceMappingURL=index.cjs.map