@saga-bus/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,650 @@
+/**
+ * Base interface for all messages in the saga bus.
+ * Every message must have a `type` discriminator.
+ */
+interface BaseMessage {
+    readonly type: string;
+}
+/**
+ * Envelope wrapping a message with metadata for transport.
+ */
+interface MessageEnvelope<T extends BaseMessage = BaseMessage> {
+    /** Unique identifier for this message instance */
+    readonly id: string;
+    /** Message type discriminator (mirrors payload.type) */
+    readonly type: T["type"];
+    /** The actual message payload */
+    readonly payload: T;
+    /** Transport and application headers */
+    readonly headers: Readonly<Record<string, string>>;
+    /** When the message was created */
+    readonly timestamp: Date;
+    /** Optional partition key for ordered delivery */
+    readonly partitionKey?: string;
+}
+
+/**
+ * Options for subscribing to messages on a transport.
+ */
+interface TransportSubscribeOptions {
+    /** The endpoint/topic/queue to subscribe to */
+    readonly endpoint: string;
+    /** Maximum concurrent message handlers (default: 1) */
+    readonly concurrency?: number;
+    /** Consumer group name for competing consumers */
+    readonly group?: string;
+}
+/**
+ * Options for publishing messages on a transport.
+ */
+interface TransportPublishOptions {
+    /** The endpoint/topic/exchange to publish to */
+    readonly endpoint: string;
+    /** Routing/partition key */
+    readonly key?: string;
+    /** Additional headers to include */
+    readonly headers?: Record<string, string>;
+    /** Delay delivery by this many milliseconds */
+    readonly delayMs?: number;
+}
+/**
+ * Transport interface for sending and receiving messages.
+ * Implementations include in-memory, RabbitMQ, Kafka, etc.
+ */
+interface Transport {
+    /**
+     * Start the transport (connect, initialize resources).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the transport (disconnect, cleanup).
+     */
+    stop(): Promise<void>;
+    /**
+     * Subscribe to messages on an endpoint.
+     */
+    subscribe<TMessage extends BaseMessage>(options: TransportSubscribeOptions, handler: (envelope: MessageEnvelope<TMessage>) => Promise<void>): Promise<void>;
+    /**
+     * Publish a message to an endpoint.
+     */
+    publish<TMessage extends BaseMessage>(message: TMessage, options: TransportPublishOptions): Promise<void>;
+}
+
+/**
+ * Metadata tracked for every saga instance.
+ */
+interface SagaStateMetadata {
+    /** Unique identifier for this saga instance */
+    readonly sagaId: string;
+    /** Optimistic concurrency version */
+    readonly version: number;
+    /** When the saga was created */
+    readonly createdAt: Date;
+    /** When the saga was last updated */
+    readonly updatedAt: Date;
+    /** Whether the saga has completed */
+    readonly isCompleted: boolean;
+    /** When the saga was archived (if applicable) */
+    readonly archivedAt?: Date | null;
+    /** W3C traceparent header for distributed tracing correlation */
+    readonly traceParent?: string | null;
+    /** W3C tracestate header for distributed tracing */
+    readonly traceState?: string | null;
+    /** Configured timeout duration in milliseconds */
+    readonly timeoutMs?: number | null;
+    /** When the timeout expires (if set) */
+    readonly timeoutExpiresAt?: Date | null;
+}
+/**
+ * Base interface for saga state. All saga states must include metadata.
+ */
+interface SagaState {
+    readonly metadata: SagaStateMetadata;
+}
+/**
+ * Storage interface for saga instances.
+ * Implementations include in-memory, Postgres, Prisma, etc.
+ */
+interface SagaStore<TState extends SagaState> {
+    /**
+     * Get a saga instance by its ID.
+     */
+    getById(sagaName: string, sagaId: string): Promise<TState | null>;
+    /**
+     * Get a saga instance by correlation ID.
+     */
+    getByCorrelationId(sagaName: string, correlationId: string): Promise<TState | null>;
+    /**
+     * Insert a new saga instance.
+     * @throws if a saga with the same ID already exists
+     */
+    insert(sagaName: string, correlationId: string, state: TState): Promise<void>;
+    /**
+     * Update an existing saga instance with optimistic concurrency.
+     * @param expectedVersion - The version the state should be at before update
+     * @throws ConcurrencyError if version mismatch
+     */
+    update(sagaName: string, state: TState, expectedVersion: number): Promise<void>;
+    /**
+     * Delete a saga instance.
+     */
+    delete(sagaName: string, sagaId: string): Promise<void>;
+}
+/**
+ * Context available to saga handlers.
+ */
+interface SagaContext {
+    /** Name of the saga being executed */
+    readonly sagaName: string;
+    /** Unique ID of this saga instance */
+    readonly sagaId: string;
+    /** Correlation ID for this saga */
+    readonly correlationId: string;
+    /** The message envelope being processed */
+    readonly envelope: MessageEnvelope;
+    /** Arbitrary metadata for middleware/handlers */
+    readonly metadata: Record<string, unknown>;
+    /**
+     * Publish a message to another endpoint.
+     */
+    publish<TMessage extends BaseMessage>(message: TMessage, options?: Partial<TransportPublishOptions>): Promise<void>;
+    /**
+     * Schedule a message for delayed delivery.
+     */
+    schedule<TMessage extends BaseMessage>(message: TMessage, delayMs: number, options?: Partial<TransportPublishOptions>): Promise<void>;
+    /**
+     * Mark the saga as complete.
+     */
+    complete(): void;
+    /**
+     * Set a metadata value.
+     */
+    setMetadata(key: string, value: unknown): void;
+    /**
+     * Get a metadata value.
+     */
+    getMetadata<T = unknown>(key: string): T | undefined;
+    /**
+     * Set a timeout for this saga. When the timeout expires, a SagaTimeoutExpired
+     * message will be published to the saga. Calling this again resets the timeout.
+     * @param delayMs - Timeout duration in milliseconds
+     */
+    setTimeout(delayMs: number): void;
+    /**
+     * Clear any pending timeout for this saga.
+     */
+    clearTimeout(): void;
+    /**
+     * Get the remaining time until timeout expires.
+     * @returns Milliseconds remaining, or null if no timeout is set
+     */
+    getTimeoutRemaining(): number | null;
+}
+/**
+ * Result returned from a saga handler.
+ */
+interface SagaHandlerResult<TState extends SagaState> {
+    /** The updated saga state */
+    readonly newState: TState;
+    /** Whether the saga should be marked as complete */
+    readonly isCompleted?: boolean;
+}
+/**
+ * Correlation configuration for a message type.
+ */
+interface SagaCorrelation<TMessage extends BaseMessage> {
+    /** Whether this message can start a new saga instance */
+    readonly canStart: boolean;
+    /**
+     * Extract the correlation ID from a message.
+     * @returns null if the message cannot be correlated
+     */
+    getCorrelationId(message: TMessage): string | null;
+}
+/**
+ * A complete saga definition produced by the DSL builder.
+ */
+interface SagaDefinition<TState extends SagaState, TMessageUnion extends BaseMessage> {
+    /** Unique name for this saga */
+    readonly name: string;
+    /** All message types this saga handles */
+    readonly handledMessageTypes: ReadonlyArray<TMessageUnion["type"]>;
+    /**
+     * Get correlation configuration for a message.
+     */
+    getCorrelation<T extends TMessageUnion>(message: T): SagaCorrelation<T>;
+    /**
+     * Create initial state for a new saga instance.
+     */
+    createInitialState<T extends TMessageUnion>(message: T, ctx: SagaContext): Promise<TState>;
+    /**
+     * Handle a message and return the updated state.
+     */
+    handle<T extends TMessageUnion>(message: T, state: TState, ctx: SagaContext): Promise<SagaHandlerResult<TState>>;
+}
+
+/**
+ * Context passed through the middleware pipeline.
+ */
+interface SagaPipelineContext {
+    /** The message being processed */
+    readonly envelope: MessageEnvelope;
+    /** Name of the saga */
+    readonly sagaName: string;
+    /** Correlation ID */
+    readonly correlationId: string;
+    /** Saga instance ID (set after state is loaded/created) */
+    sagaId?: string;
+    /** Existing state loaded from store (null if new saga) */
+    existingState?: SagaState | null;
+    /** State before handler execution */
+    preState?: SagaState;
+    /** State after handler execution */
+    postState?: SagaState;
+    /** Result from the handler */
+    handlerResult?: SagaHandlerResult<SagaState>;
+    /** Arbitrary metadata */
+    readonly metadata: Record<string, unknown>;
+    /** Error if one occurred */
+    error?: unknown;
+    /** Trace context to store with saga (set by tracing middleware) */
+    traceContext?: {
+        traceParent: string;
+        traceState: string | null;
+    };
+    /**
+     * Set trace context to be stored with the saga state.
+     * Called by tracing middleware for new sagas.
+     */
+    setTraceContext(traceParent: string, traceState: string | null): void;
+}
+/**
+ * Middleware function for the saga pipeline.
+ */
+type SagaMiddleware = (ctx: SagaPipelineContext, next: () => Promise<void>) => Promise<void>;
+
+/**
+ * Logger interface for saga bus.
+ */
+interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Metrics interface for saga bus.
+ */
+interface Metrics {
+    /**
+     * Increment a counter.
+     */
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    /**
+     * Record a duration/timing.
+     */
+    recordDuration(name: string, ms: number, tags?: Record<string, string>): void;
+    /**
+     * Set a gauge value.
+     */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+}
+/**
+ * Tracer interface for distributed tracing.
+ */
+interface Tracer {
+    /**
+     * Execute a function within a named span.
+     */
+    withSpan<T>(name: string, ctx: SagaPipelineContext, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Error handler for determining retry behavior.
+ */
+interface ErrorHandler {
+    /**
+     * Handle an error and determine the action.
+     * @returns "retry" to retry, "dlq" to send to DLQ, "drop" to discard
+     */
+    handle(error: unknown, ctx: SagaPipelineContext): Promise<"retry" | "dlq" | "drop">;
+}
+
+/**
+ * Registration of a saga with its store.
+ */
+interface SagaRegistration<TState extends SagaState, TMessageUnion extends BaseMessage> {
+    readonly definition: SagaDefinition<TState, TMessageUnion>;
+    /** Store for this saga. If not provided, uses the default store from BusConfig. */
+    readonly store?: SagaStore<TState>;
+}
+/**
+ * Retry policy configuration.
+ */
+interface WorkerRetryPolicy {
+    /** Maximum number of attempts before sending to DLQ */
+    readonly maxAttempts: number;
+    /** Base delay between retries in milliseconds */
+    readonly baseDelayMs: number;
+    /** Maximum delay between retries in milliseconds */
+    readonly maxDelayMs: number;
+    /** Backoff strategy */
+    readonly backoff: "linear" | "exponential";
+}
+/**
+ * Timeout bounds configuration to prevent accidental extreme values.
+ */
+interface TimeoutBounds {
+    /** Minimum allowed timeout in milliseconds (default: 1000 = 1 second) */
+    readonly minMs?: number;
+    /** Maximum allowed timeout in milliseconds (default: 604800000 = 7 days) */
+    readonly maxMs?: number;
+}
+/**
+ * Context provided when a message fails correlation.
+ */
+interface CorrelationFailureContext {
+    /** The message envelope that failed correlation */
+    readonly envelope: MessageEnvelope;
+    /** Name of the saga that couldn't correlate the message */
+    readonly sagaName: string;
+    /** The message type */
+    readonly messageType: string;
+}
+/**
+ * Handler for messages that fail correlation.
+ */
+type CorrelationFailureHandler = (ctx: CorrelationFailureContext) => Promise<"drop" | "dlq"> | "drop" | "dlq";
+/**
+ * Worker configuration for message processing.
+ */
+interface WorkerConfig {
+    /** Default concurrency for all subscriptions */
+    readonly defaultConcurrency?: number;
+    /** Timeout for graceful shutdown in milliseconds */
+    readonly shutdownTimeoutMs?: number;
+    /** Default retry policy */
+    readonly retryPolicy?: WorkerRetryPolicy;
+    /** Per-saga configuration overrides */
+    readonly sagas?: Record<string, {
+        readonly concurrency?: number;
+        readonly retryPolicy?: WorkerRetryPolicy;
+    }>;
+    /** Function to generate DLQ endpoint names */
+    readonly dlqNaming?: (endpoint: string) => string;
+    /** Timeout bounds to prevent accidental extreme values */
+    readonly timeoutBounds?: TimeoutBounds;
+    /** Handler for messages that fail correlation (default: "drop") */
+    readonly onCorrelationFailure?: CorrelationFailureHandler;
+}
+/**
+ * Configuration for creating a bus instance.
+ */
+interface BusConfig {
+    /** Transport implementation */
+    readonly transport: Transport;
+    /** Default store for all sagas. Can be overridden per-saga in the registration. */
+    readonly store?: SagaStore<SagaState>;
+    /** Registered sagas */
+    readonly sagas: ReadonlyArray<SagaRegistration<SagaState, BaseMessage>>;
+    /** Middleware pipeline */
+    readonly middleware?: ReadonlyArray<SagaMiddleware>;
+    /** Logger implementation */
+    readonly logger?: Logger;
+    /** Metrics implementation */
+    readonly metrics?: Metrics;
+    /** Tracer implementation */
+    readonly tracer?: Tracer;
+    /** Error handler implementation */
+    readonly errorHandler?: ErrorHandler;
+    /** Worker configuration */
+    readonly worker?: WorkerConfig;
+}
+/**
+ * The main bus interface for publishing messages.
+ */
+interface Bus {
+    /**
+     * Start the bus (connect transport, subscribe to endpoints).
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the bus (graceful shutdown).
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the bus is running.
+     */
+    isRunning(): boolean;
+    /**
+     * Publish a message.
+     */
+    publish<TMessage extends BaseMessage>(message: TMessage, options?: Partial<TransportPublishOptions>): Promise<void>;
+}
+
+/**
+ * Thrown when optimistic concurrency check fails.
+ */
+declare class ConcurrencyError extends Error {
+    readonly sagaId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion?: number;
+    constructor(sagaId: string, expectedVersion: number, actualVersion?: number);
+}
+/**
+ * Marker class for transient errors that should be retried.
+ */
+declare class TransientError extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+    static wrap(error: Error): TransientError;
+}
+/**
+ * Thrown when message validation fails.
+ */
+declare class ValidationError extends Error {
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(message: string, field?: string, value?: unknown);
+}
+/**
+ * Context attached to processing errors for better observability.
+ */
+interface SagaErrorContext {
+    readonly sagaName: string;
+    readonly correlationId: string;
+    readonly sagaId?: string;
+    readonly messageType: string;
+    readonly messageId: string;
+}
+/**
+ * Wraps errors that occur during saga processing with context.
+ * Used by BusImpl to provide richer error context to error handlers.
+ */
+declare class SagaProcessingError extends Error {
+    readonly context: SagaErrorContext;
+    readonly cause: Error;
+    constructor(cause: Error, context: SagaErrorContext);
+    /**
+     * Check if an error is a SagaProcessingError and extract context.
+     */
+    static extractContext(error: unknown): SagaErrorContext | null;
+}
+
+/**
+ * Options for correlating a message type.
+ */
+interface CorrelateOptions {
+    /** Whether this message type can start a new saga instance */
+    canStart?: boolean;
+}
+/**
+ * Handler function signature.
+ */
+type SagaHandler<TState extends SagaState, TMessage extends BaseMessage> = (message: TMessage, state: TState, ctx: SagaContext) => Promise<SagaHandlerResult<TState>>;
+/**
+ * State guard function.
+ */
+type StateGuard<TState extends SagaState> = (state: TState) => boolean;
+/**
+ * Handler registration with optional state guard.
+ */
+interface HandlerRegistration<TState extends SagaState, TMessage extends BaseMessage> {
+    messageType: string;
+    guard?: StateGuard<TState>;
+    handler: SagaHandler<TState, TMessage>;
+}
+/**
+ * Initial state factory function.
+ */
+type InitialStateFactory<TState extends SagaState, TMessage extends BaseMessage> = (message: TMessage, ctx: SagaContext) => TState | Promise<TState>;
+
+/**
+ * Builder for configuring a message handler with optional state guards.
+ */
+declare class HandlerBuilder<TState extends SagaState, TMessages extends BaseMessage, TCurrentMessage extends TMessages> {
+    private readonly parent;
+    private readonly messageType;
+    private guard?;
+    constructor(parent: SagaMachineBuilder<TState, TMessages>, messageType: TCurrentMessage["type"]);
+    /**
+     * Add a state guard that must pass for the handler to execute.
+     * Multiple guards can be chained with multiple .when() calls.
+     */
+    when(guard: StateGuard<TState>): HandlerBuilder<TState, TMessages, TCurrentMessage>;
+    /**
+     * Register the handler function and return to the parent builder.
+     */
+    handle(handler: SagaHandler<TState, TCurrentMessage>): SagaMachineBuilder<TState, TMessages>;
+}
+
+/**
+ * Fluent builder for creating saga definitions.
+ *
+ * @example
+ * ```typescript
+ * const saga = createSagaMachine<OrderState, OrderMessages>()
+ *   .name("OrderSaga")
+ *   .correlate("OrderSubmitted", msg => msg.orderId, { canStart: true })
+ *   .correlate("*", msg => msg.orderId)
+ *   .initial<OrderSubmitted>((msg, ctx) => ({ ... }))
+ *   .on("PaymentCaptured").when(s => s.status === "pending").handle(...)
+ *   .build();
+ * ```
+ */
+declare class SagaMachineBuilder<TState extends SagaState, TMessages extends BaseMessage> {
+    private sagaName?;
+    private readonly correlations;
+    private wildcardCorrelation?;
+    private readonly handlers;
+    private initialFactory?;
+    /**
+     * Set the saga name.
+     */
+    name(sagaName: string): 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<TType extends TMessages["type"] | "*">(messageType: TType, getCorrelationId: TType extends "*" ? (message: TMessages) => string | null : (message: Extract<TMessages, {
+        type: TType;
+    }>) => string | null, options?: CorrelateOptions): this;
+    /**
+     * Define the initial state factory for new saga instances.
+     *
+     * @param factory - Function to create initial state from the starting message
+     */
+    initial<TStartMessage extends TMessages>(factory: InitialStateFactory<TState, TStartMessage>): 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<TType extends TMessages["type"]>(messageType: TType): HandlerBuilder<TState, TMessages, Extract<TMessages, {
+        type: TType;
+    }>>;
+    /**
+     * Internal method called by HandlerBuilder to register a handler.
+     * @internal
+     */
+    _registerHandler(registration: HandlerRegistration<TState, TMessages>): this;
+    /**
+     * Build the saga definition.
+     *
+     * @throws Error if required configuration is missing
+     */
+    build(): SagaDefinition<TState, TMessages>;
+}
+/**
+ * Create a new saga machine builder.
+ *
+ * @example
+ * ```typescript
+ * const saga = createSagaMachine<OrderState, OrderMessages>()
+ *   .name("OrderSaga")
+ *   .correlate("OrderSubmitted", msg => msg.orderId, { canStart: true })
+ *   .initial<OrderSubmitted>((msg, ctx) => ({ ... }))
+ *   .on("PaymentCaptured").handle(...)
+ *   .build();
+ * ```
+ */
+declare function createSagaMachine<TState extends SagaState, TMessages extends BaseMessage>(): SagaMachineBuilder<TState, TMessages>;
+
+/**
+ * Create a new bus instance.
+ */
+declare function createBus(config: BusConfig): Bus;
+
+/** Default timeout bounds */
+declare const DEFAULT_TIMEOUT_BOUNDS: Required<TimeoutBounds>;
+
+/**
+ * Default console-based logger implementation.
+ */
+declare class DefaultLogger implements Logger {
+    private readonly prefix;
+    constructor(prefix?: string);
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * Default error handler implementation.
+ * Classifies errors as transient (retry) or permanent (DLQ).
+ */
+declare class DefaultErrorHandler implements ErrorHandler {
+    handle(error: unknown, _ctx: SagaPipelineContext): Promise<"retry" | "dlq" | "drop">;
+}
+/**
+ * Create a custom error handler with additional transient patterns.
+ */
+declare function createErrorHandler(options?: {
+    additionalTransientPatterns?: RegExp[];
+    customClassifier?: (error: unknown, ctx: SagaPipelineContext) => "retry" | "dlq" | "drop" | null;
+}): ErrorHandler;
+
+/**
+ * Header names for retry tracking.
+ */
+declare const RETRY_HEADERS: {
+    readonly ATTEMPT: "x-saga-attempt";
+    readonly FIRST_SEEN: "x-saga-first-seen";
+    readonly ORIGINAL_ENDPOINT: "x-saga-original-endpoint";
+    readonly ERROR_MESSAGE: "x-saga-error-message";
+    readonly ERROR_TYPE: "x-saga-error-type";
+};
+/**
+ * Default retry policy.
+ */
+declare const DEFAULT_RETRY_POLICY: WorkerRetryPolicy;
+/**
+ * Default DLQ naming function.
+ */
+declare function defaultDlqNaming(endpoint: string): string;
+
+export { type BaseMessage, type Bus, type BusConfig, ConcurrencyError, type CorrelateOptions, type CorrelationFailureContext, type CorrelationFailureHandler, DEFAULT_RETRY_POLICY, DEFAULT_TIMEOUT_BOUNDS, DefaultErrorHandler, DefaultLogger, type ErrorHandler, type InitialStateFactory, type Logger, type MessageEnvelope, type Metrics, RETRY_HEADERS, type SagaContext, type SagaCorrelation, type SagaDefinition, type SagaErrorContext, type SagaHandler, type SagaHandlerResult, SagaMachineBuilder, type SagaMiddleware, type SagaPipelineContext, SagaProcessingError, type SagaRegistration, type SagaState, type SagaStateMetadata, type SagaStore, type StateGuard, type TimeoutBounds, type Tracer, TransientError, type Transport, type TransportPublishOptions, type TransportSubscribeOptions, ValidationError, type WorkerConfig, type WorkerRetryPolicy, createBus, createErrorHandler, createSagaMachine, defaultDlqNaming };