@stravigor/workflow 0.4.6

package/README.md

@@ -0,0 +1,122 @@
+# @stravigor/workflow
+
+Workflow orchestration for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Build multi-step processes with sequential, parallel, conditional, and looping steps — plus saga-style compensation on failure.
+
+## Install
+
+```bash
+bun add @stravigor/workflow
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Usage
+
+```ts
+import { workflow } from '@stravigor/workflow'
+
+const result = await workflow('order-process')
+  .step('validate', async (ctx) => {
+    return validateOrder(ctx.input.orderId)
+  })
+  .step('charge', async (ctx) => {
+    return await chargeCard(ctx.results.validate.total)
+  })
+  .step('notify', async (ctx) => {
+    return await sendConfirmation(ctx.results.charge.id)
+  })
+  .run({ orderId: 123 })
+
+result.results.charge  // { id: 'ch_123', amount: 99.99 }
+result.duration        // 342 (ms)
+```
+
+## Step Types
+
+### Sequential
+
+Steps run in order. Each step's return value is stored in `ctx.results[name]`.
+
+```ts
+workflow('pipeline')
+  .step('fetch', async (ctx) => fetchData(ctx.input.url))
+  .step('transform', async (ctx) => transform(ctx.results.fetch))
+  .step('save', async (ctx) => save(ctx.results.transform))
+  .run({ url: 'https://...' })
+```
+
+### Parallel
+
+Run multiple handlers concurrently. Each result is stored under its name.
+
+```ts
+workflow('notify')
+  .parallel('send', [
+    { name: 'email', handler: async (ctx) => sendEmail(ctx) },
+    { name: 'sms', handler: async (ctx) => sendSMS(ctx) },
+    { name: 'push', handler: async (ctx) => sendPush(ctx) },
+  ])
+  .run({ userId: 1 })
+```
+
+### Route
+
+Conditionally dispatch to a branch based on a resolver function.
+
+```ts
+workflow('support')
+  .step('classify', async (ctx) => classifyTicket(ctx.input.text))
+  .route(
+    'handle',
+    (ctx) => ctx.results.classify.category,
+    {
+      billing: async (ctx) => handleBilling(ctx),
+      shipping: async (ctx) => handleShipping(ctx),
+      technical: async (ctx) => handleTechnical(ctx),
+    }
+  )
+  .run({ text: 'My payment failed' })
+```
+
+### Loop
+
+Repeat a handler until a condition is met or max iterations reached.
+
+```ts
+workflow('refine')
+  .loop('improve', async (input, ctx) => {
+    return await improveQuality(input)
+  }, {
+    maxIterations: 5,
+    until: (result) => result.score >= 0.95,
+    feedback: (result) => result.data,
+    mapInput: (ctx) => ctx.input.rawData,
+  })
+  .run({ rawData: '...' })
+```
+
+## Compensation (Saga Pattern)
+
+Define rollback functions for steps. If a downstream step fails, compensation runs in reverse order.
+
+```ts
+workflow('order-saga')
+  .step('reserve', async (ctx) => reserveInventory(ctx.input), {
+    compensate: async (ctx) => releaseInventory(ctx.results.reserve),
+  })
+  .step('charge', async (ctx) => chargePayment(ctx.input), {
+    compensate: async (ctx) => refundPayment(ctx.results.charge),
+  })
+  .step('ship', async (ctx) => scheduleShipping(ctx.input))
+  .run({ orderId: 123 })
+
+// If 'ship' fails → refundPayment → releaseInventory
+```
+
+## Documentation
+
+See the full [Workflow guide](../../guides/workflow.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@stravigor/workflow",
+  "version": "0.4.6",
+  "type": "module",
+  "description": "Workflow orchestration for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@stravigor/core": "0.4.5"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import { StravError } from '@stravigor/core/exceptions'
+
+/** Thrown when a workflow step fails during execution. */
+export class WorkflowError extends StravError {
+  constructor(
+    public readonly step: string,
+    public readonly cause: Error
+  ) {
+    super(`Workflow step "${step}" failed: ${cause.message}`)
+  }
+}
+
+/** Thrown when compensation fails. Contains the original step error and all compensation errors. */
+export class CompensationError extends StravError {
+  constructor(
+    public readonly originalError: Error,
+    public readonly compensationErrors: { step: string; error: Error }[]
+  ) {
+    const failures = compensationErrors.map(e => `${e.step}: ${e.error.message}`).join(', ')
+    super(
+      `Compensation failed for ${compensationErrors.length} step(s) [${failures}]. ` +
+        `Original error: ${originalError.message}`
+    )
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,6 @@
+import { Workflow } from './workflow.ts'
+
+/** Create a new workflow instance. */
+export function workflow(name: string): Workflow {
+  return new Workflow(name)
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { Workflow } from './workflow.ts'
+export { workflow } from './helpers.ts'
+export { WorkflowError, CompensationError } from './errors.ts'
+export type {
+  WorkflowContext,
+  WorkflowResult,
+  StepHandler,
+  LoopHandler,
+  RouteResolver,
+  StepOptions,
+  ParallelEntry,
+  LoopOptions,
+} from './types.ts'

package/src/types.ts

@@ -0,0 +1,77 @@
+// ── Workflow Context ─────────────────────────────────────────────────────────
+
+export interface WorkflowContext {
+  input: Record<string, unknown>
+  results: Record<string, unknown>
+}
+
+// ── Workflow Result ─────────────────────────────────────────────────────────
+
+export interface WorkflowResult {
+  results: Record<string, unknown>
+  duration: number
+}
+
+// ── Handlers ────────────────────────────────────────────────────────────────
+
+/** Handler for sequential, parallel, and route steps. Receives full context. */
+export type StepHandler = (ctx: WorkflowContext) => Promise<unknown>
+
+/** Handler for loop steps. Receives current iteration input + full context. */
+export type LoopHandler = (input: unknown, ctx: WorkflowContext) => Promise<unknown>
+
+/** Route resolver. Returns the branch key to dispatch to. */
+export type RouteResolver = (ctx: WorkflowContext) => string | Promise<string>
+
+// ── Step Options ────────────────────────────────────────────────────────────
+
+export interface StepOptions {
+  compensate?: (ctx: WorkflowContext) => Promise<void>
+}
+
+export interface ParallelEntry {
+  name: string
+  handler: StepHandler
+  compensate?: (ctx: WorkflowContext) => Promise<void>
+}
+
+export interface LoopOptions<T = unknown> {
+  maxIterations: number
+  until?: (result: T, iteration: number) => boolean
+  feedback?: (result: T) => unknown
+  mapInput?: (ctx: WorkflowContext) => unknown
+}
+
+// ── Internal Step Definitions ───────────────────────────────────────────────
+
+export interface SequentialStep {
+  type: 'step'
+  name: string
+  handler: StepHandler
+  compensate?: (ctx: WorkflowContext) => Promise<void>
+}
+
+export interface ParallelStep {
+  type: 'parallel'
+  name: string
+  entries: ParallelEntry[]
+}
+
+export interface RouteStep {
+  type: 'route'
+  name: string
+  resolver: RouteResolver
+  branches: Record<string, StepHandler>
+}
+
+export interface LoopStep {
+  type: 'loop'
+  name: string
+  handler: LoopHandler
+  maxIterations: number
+  until?: (result: unknown, iteration: number) => boolean
+  feedback?: (result: unknown) => unknown
+  mapInput?: (ctx: WorkflowContext) => unknown
+}
+
+export type WorkflowStep = SequentialStep | ParallelStep | RouteStep | LoopStep

package/src/workflow.ts

@@ -0,0 +1,210 @@
+import type {
+  WorkflowContext,
+  WorkflowResult,
+  WorkflowStep,
+  StepHandler,
+  StepOptions,
+  ParallelEntry,
+  RouteResolver,
+  LoopHandler,
+  LoopOptions,
+  SequentialStep,
+  ParallelStep,
+  RouteStep,
+  LoopStep,
+} from './types.ts'
+import { CompensationError } from './errors.ts'
+
+/**
+ * General-purpose workflow orchestrator.
+ *
+ * Supports sequential steps, parallel fan-out, conditional routing, and loops.
+ * Each step is an arbitrary async function that receives and extends a shared context.
+ * Steps can optionally define compensation functions for saga-style rollback.
+ *
+ * @example
+ * const result = await new Workflow('order-process')
+ *   .step('validate', async (ctx) => validateOrder(ctx.input.orderId))
+ *   .step('charge', async (ctx) => chargeCard(ctx.results.validate.total), {
+ *     compensate: async (ctx) => refundCharge(ctx.results.charge.id),
+ *   })
+ *   .parallel('notify', [
+ *     { name: 'email', handler: async (ctx) => sendEmail(ctx) },
+ *     { name: 'slack', handler: async (ctx) => notifySlack(ctx) },
+ *   ])
+ *   .run({ orderId: 123 })
+ */
+export class Workflow {
+  private steps: WorkflowStep[] = []
+
+  constructor(private name: string) {}
+
+  /**
+   * Add a sequential step. Runs after all previous steps complete.
+   * The handler receives the workflow context and its return value is stored in `ctx.results[name]`.
+   */
+  step(name: string, handler: StepHandler, options?: StepOptions): this {
+    this.steps.push({
+      type: 'step',
+      name,
+      handler,
+      compensate: options?.compensate,
+    })
+    return this
+  }
+
+  /**
+   * Run multiple handlers in parallel. Each handler's result is stored under its name.
+   */
+  parallel(name: string, entries: ParallelEntry[]): this {
+    this.steps.push({ type: 'parallel', name, entries })
+    return this
+  }
+
+  /**
+   * Route to a branch based on a resolver function's return value.
+   * The resolver returns a string key that maps to one of the branches.
+   * If no branch matches, the step completes silently with no result.
+   */
+  route(name: string, resolver: RouteResolver, branches: Record<string, StepHandler>): this {
+    this.steps.push({ type: 'route', name, resolver, branches })
+    return this
+  }
+
+  /**
+   * Run a handler in a loop until a condition is met or max iterations reached.
+   * Use `feedback` to transform the result into the next iteration's input.
+   * Use `mapInput` to derive the initial input from context.
+   */
+  loop(name: string, handler: LoopHandler, options: LoopOptions): this {
+    this.steps.push({
+      type: 'loop',
+      name,
+      handler,
+      maxIterations: options.maxIterations,
+      until: options.until,
+      feedback: options.feedback,
+      mapInput: options.mapInput,
+    })
+    return this
+  }
+
+  /** Execute the workflow. */
+  async run(input: Record<string, unknown>): Promise<WorkflowResult> {
+    const start = performance.now()
+    const ctx: WorkflowContext = { input, results: {} }
+    const completed: WorkflowStep[] = []
+
+    try {
+      for (const step of this.steps) {
+        switch (step.type) {
+          case 'step':
+            await this.runStep(step, ctx)
+            break
+          case 'parallel':
+            await this.runParallel(step, ctx)
+            break
+          case 'route':
+            await this.runRoute(step, ctx)
+            break
+          case 'loop':
+            await this.runLoop(step, ctx)
+            break
+        }
+        completed.push(step)
+      }
+    } catch (error) {
+      await this.compensate(completed, ctx, error as Error)
+      throw error
+    }
+
+    return { results: ctx.results, duration: performance.now() - start }
+  }
+
+  // ── Step Executors ─────────────────────────────────────────────────────────
+
+  private async runStep(step: SequentialStep, ctx: WorkflowContext): Promise<void> {
+    const result = await step.handler(ctx)
+    ctx.results[step.name] = result
+  }
+
+  private async runParallel(step: ParallelStep, ctx: WorkflowContext): Promise<void> {
+    const promises = step.entries.map(async entry => {
+      const result = await entry.handler(ctx)
+      ctx.results[entry.name] = result
+    })
+    await Promise.all(promises)
+  }
+
+  private async runRoute(step: RouteStep, ctx: WorkflowContext): Promise<void> {
+    const routeKey = await step.resolver(ctx)
+    const branchHandler = step.branches[routeKey]
+
+    if (branchHandler) {
+      const result = await branchHandler(ctx)
+      ctx.results[step.name] = result
+    }
+  }
+
+  private async runLoop(step: LoopStep, ctx: WorkflowContext): Promise<void> {
+    let currentInput: unknown = step.mapInput ? step.mapInput(ctx) : ctx.input
+    let lastResult: unknown
+
+    for (let i = 0; i < step.maxIterations; i++) {
+      lastResult = await step.handler(currentInput, ctx)
+
+      if (step.until?.(lastResult, i + 1)) break
+
+      if (step.feedback) {
+        currentInput = step.feedback(lastResult)
+      }
+    }
+
+    if (lastResult !== undefined) {
+      ctx.results[step.name] = lastResult
+    }
+  }
+
+  // ── Compensation ───────────────────────────────────────────────────────────
+
+  private async compensate(
+    completed: WorkflowStep[],
+    ctx: WorkflowContext,
+    originalError: Error
+  ): Promise<void> {
+    const compensationErrors: { step: string; error: Error }[] = []
+
+    // Run compensation in reverse order
+    for (let i = completed.length - 1; i >= 0; i--) {
+      const step = completed[i]!
+      const compensators = this.getCompensators(step)
+
+      for (const { name, compensate } of compensators) {
+        try {
+          await compensate(ctx)
+        } catch (err) {
+          compensationErrors.push({ step: name, error: err as Error })
+        }
+      }
+    }
+
+    if (compensationErrors.length > 0) {
+      throw new CompensationError(originalError, compensationErrors)
+    }
+  }
+
+  private getCompensators(
+    step: WorkflowStep
+  ): { name: string; compensate: (ctx: WorkflowContext) => Promise<void> }[] {
+    switch (step.type) {
+      case 'step':
+        return step.compensate ? [{ name: step.name, compensate: step.compensate }] : []
+      case 'parallel':
+        return step.entries
+          .filter(e => e.compensate)
+          .map(e => ({ name: e.name, compensate: e.compensate! }))
+      default:
+        return []
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"]
+}