@veloxts/router 0.7.9 → 0.8.1

package/dist/procedure/pipeline-executor.js

@@ -0,0 +1,134 @@
+/**
+ * Pipeline executor for .through() steps
+ *
+ * Executes pipeline steps in declaration order. Each step's output becomes
+ * the next step's input. On failure, runs revert actions for completed
+ * steps in reverse order (compensation pattern).
+ *
+ * When `.transactional()` is combined with `.through()`, the executor
+ * implements a two-phase model:
+ * - Phase A: DB steps (non-external) run inside the transaction
+ * - Phase B: External steps run after the transaction commits
+ *
+ * @module procedure/pipeline-executor
+ */
+import { ConfigurationError, createLogger } from '@veloxts/core';
+const log = createLogger('router');
+/**
+ * Splits pipeline steps into DB (non-external) and external phases
+ *
+ * Validates the ordering constraint: when transactional, all external steps
+ * must come AFTER all DB steps. If an external step appears before a DB step,
+ * a ConfigurationError is thrown.
+ *
+ * @param steps - Pipeline steps to split
+ * @returns Object with `dbSteps` and `externalSteps` arrays
+ * @throws ConfigurationError if an external step precedes a DB step
+ */
+export function splitPipelineSteps(steps) {
+    const dbSteps = [];
+    const externalSteps = [];
+    let seenExternal = false;
+    for (const step of steps) {
+        if (step.external) {
+            seenExternal = true;
+            externalSteps.push(step);
+        }
+        else {
+            if (seenExternal) {
+                throw new ConfigurationError(`Pipeline step "${step.name}" (DB) is declared after external step "${externalSteps[externalSteps.length - 1].name}". ` +
+                    'When using .transactional(), all external steps must come after all DB steps in the .through() declaration.');
+            }
+            dbSteps.push(step);
+        }
+    }
+    return { dbSteps, externalSteps };
+}
+/**
+ * Executes a sequence of pipeline steps
+ *
+ * Steps run in declaration order. Each step receives the previous step's
+ * output as its input (the first step receives the original validated input).
+ *
+ * If a step fails:
+ * 1. Collects all completed steps that have a revertAction
+ * 2. Runs their revert handlers in REVERSE order
+ * 3. Each revert receives the output of the step being reverted
+ * 4. Revert errors are logged but do not suppress the original error
+ * 5. Rethrows the original error
+ *
+ * @param steps - Pipeline steps to execute in order
+ * @param input - Initial input (typically the validated procedure input)
+ * @param ctx - Request context
+ * @returns The output of the last step
+ */
+export async function executePipeline(steps, input, ctx) {
+    const completedSteps = [];
+    let currentInput = input;
+    for (const step of steps) {
+        try {
+            const output = await step.handler({ input: currentInput, ctx });
+            completedSteps.push({ step, output });
+            currentInput = output;
+        }
+        catch (error) {
+            // Step failed — run reverts for completed steps in reverse order
+            await runReverts(completedSteps, ctx);
+            throw error;
+        }
+    }
+    return currentInput;
+}
+/**
+ * Executes external pipeline steps after a transaction has committed
+ *
+ * External steps run in declaration order. If a step fails, revert actions
+ * are run for all previously completed EXTERNAL steps in reverse order.
+ * The DB transaction is already committed — DB changes persist.
+ *
+ * @param steps - External pipeline steps to execute in order
+ * @param input - Input for the first external step (output of last DB step, or original input)
+ * @param ctx - Request context (with the ORIGINAL db, not the transactional client)
+ * @returns The output of the last external step (ignored by the caller, since handler already ran)
+ */
+export async function executeExternalSteps(steps, input, ctx) {
+    const completedSteps = [];
+    let currentInput = input;
+    for (const step of steps) {
+        try {
+            const output = await step.handler({ input: currentInput, ctx });
+            completedSteps.push({ step, output });
+            currentInput = output;
+        }
+        catch (error) {
+            // External step failed — revert only completed external steps
+            await runReverts(completedSteps, ctx);
+            throw error;
+        }
+    }
+}
+/**
+ * Runs revert actions for completed steps in reverse order
+ *
+ * Each revert receives the output of the step it is reverting.
+ * Revert errors are logged but never suppress the original error.
+ *
+ * @param completedSteps - Steps that completed successfully before the failure
+ * @param ctx - Request context (forwarded to revert handlers)
+ * @internal
+ */
+async function runReverts(completedSteps, ctx) {
+    // Process in reverse order
+    for (let i = completedSteps.length - 1; i >= 0; i--) {
+        const { step, output } = completedSteps[i];
+        if (!step.revertAction) {
+            continue;
+        }
+        try {
+            await step.revertAction.handler({ input: output, ctx });
+        }
+        catch (revertError) {
+            log.error(`Revert "${step.revertAction.name}" for step "${step.name}" failed:`, revertError);
+        }
+    }
+}

package/dist/procedure/pipeline.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pipeline step and revert action factories
+ *
+ * Provides `defineStep` and `defineRevert` for building pipeline steps
+ * that execute in sequence via `.through()` on the procedure builder.
+ * Each step's output becomes the next step's input. External steps run
+ * outside DB transactions and can have revert actions for compensation.
+ *
+ * @module procedure/pipeline
+ */
+import type { BaseContext } from '@veloxts/core';
+/**
+ * Options for configuring a pipeline step
+ */
+export interface StepOptions {
+    /** Step name used for logging and error reporting */
+    readonly name: string;
+    /** Whether this step runs outside the DB transaction (default: false) */
+    readonly external?: boolean;
+}
+/**
+ * A revert action that undoes the effect of an external step
+ *
+ * Revert actions are invoked when a later step in the pipeline fails,
+ * allowing compensation for steps that ran outside the DB transaction.
+ */
+export interface RevertAction<TInput = unknown> {
+    readonly name: string;
+    readonly handler: (params: {
+        input: TInput;
+        ctx: BaseContext;
+    }) => void | Promise<void>;
+}
+/**
+ * A single step in a procedure pipeline
+ *
+ * Steps execute in order, each one's output becoming the next one's input.
+ * External steps run outside DB transactions and may have revert actions
+ * for compensation when a later step fails.
+ */
+export interface PipelineStep<TInput = unknown, TOutput = unknown> {
+    readonly name: string;
+    readonly external: boolean;
+    readonly handler: (params: {
+        input: TInput;
+        ctx: BaseContext;
+    }) => TOutput | Promise<TOutput>;
+    readonly revertAction?: RevertAction;
+    /** Attach a revert action to this step, returning a new step (immutable) */
+    onRevert(revert: RevertAction): PipelineStep<TInput, TOutput>;
+}
+/** Handler function signature for pipeline steps */
+type StepHandler<TInput, TOutput> = (params: {
+    input: TInput;
+    ctx: BaseContext;
+}) => TOutput | Promise<TOutput>;
+/**
+ * Define a pipeline step with a string name (external defaults to false)
+ *
+ * @example
+ * ```typescript
+ * const validate = defineStep('validateInventory', async ({ input, ctx }) => {
+ *   return { ...input, validated: true };
+ * });
+ * ```
+ */
+export declare function defineStep<TInput = unknown, TOutput = unknown>(name: string, handler: StepHandler<TInput, TOutput>): PipelineStep<TInput, TOutput>;
+/**
+ * Define a pipeline step with options (name + external flag)
+ *
+ * @example
+ * ```typescript
+ * const charge = defineStep(
+ *   { name: 'chargePayment', external: true },
+ *   async ({ input, ctx }) => {
+ *     return { ...input, chargeId: 'ch_123' };
+ *   },
+ * );
+ * ```
+ */
+export declare function defineStep<TInput = unknown, TOutput = unknown>(options: StepOptions, handler: StepHandler<TInput, TOutput>): PipelineStep<TInput, TOutput>;
+/**
+ * Define a revert action for compensating an external pipeline step
+ *
+ * Revert handlers receive the same `{ input, ctx }` shape but return void.
+ *
+ * @example
+ * ```typescript
+ * const refund = defineRevert('refundPayment', async ({ input, ctx }) => {
+ *   await gateway.refund(input.chargeId);
+ * });
+ * ```
+ */
+export declare function defineRevert<TInput = unknown>(name: string, handler: (params: {
+    input: TInput;
+    ctx: BaseContext;
+}) => void | Promise<void>): RevertAction<TInput>;
+export {};

package/dist/procedure/pipeline.js

@@ -0,0 +1,50 @@
+/**
+ * Pipeline step and revert action factories
+ *
+ * Provides `defineStep` and `defineRevert` for building pipeline steps
+ * that execute in sequence via `.through()` on the procedure builder.
+ * Each step's output becomes the next step's input. External steps run
+ * outside DB transactions and can have revert actions for compensation.
+ *
+ * @module procedure/pipeline
+ */
+/** @internal */
+export function defineStep(nameOrOptions, handler) {
+    const resolved = typeof nameOrOptions === 'string'
+        ? { name: nameOrOptions, external: false }
+        : { name: nameOrOptions.name, external: nameOrOptions.external ?? false };
+    return createStep(resolved.name, resolved.external, handler, undefined);
+}
+// ============================================================================
+// defineRevert
+// ============================================================================
+/**
+ * Define a revert action for compensating an external pipeline step
+ *
+ * Revert handlers receive the same `{ input, ctx }` shape but return void.
+ *
+ * @example
+ * ```typescript
+ * const refund = defineRevert('refundPayment', async ({ input, ctx }) => {
+ *   await gateway.refund(input.chargeId);
+ * });
+ * ```
+ */
+export function defineRevert(name, handler) {
+    return { name, handler };
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/** @internal Create a PipelineStep object with onRevert method */
+function createStep(name, external, handler, revertAction) {
+    return {
+        name,
+        external,
+        handler,
+        revertAction,
+        onRevert(revert) {
+            return createStep(name, external, handler, revert);
+        },
+    };
+}