JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1294
  • Score
    100M100P100Q112638F
  • License MIT

Core workflow execution engine for CascadeFlow with dependency-aware parallel task execution

Package Exports

  • @cascade-flow/runner

Readme

Runner

Core workflow execution engine for direct (non-queue) execution.

Installation

bun install

Usage

import { runAll, defineStep, baseDefineStep } from "runner";

// Execute workflow
const results = await runAll({
  workflow: "my-workflow",
  input: { userId: "123" },
  only: ["step1", "step2"],  // Optional: run subset
  resume: true,              // Optional: resume from previous run
  runId: "previous-run-id",  // Optional: specific run to resume
});

Defining Steps

Basic Step

// workflows/my-workflow/steps/my-step/step.ts
import { defineStep } from "runner";
import { step as dependency } from "../other-step/step.ts";

export const step = defineStep({
  dependencies: { dependency },
  exportOutput: true,
  fn: async ({ dependencies, ctx }) => {
    return { result: dependencies.dependency.value * 2 };
  }
});

Typed Workflow Input

// workflows/my-workflow/input-schema.ts
import { z } from "zod";
export const inputSchema = z.object({
  userId: z.string(),
  count: z.number()
});
export type WorkflowInput = z.infer<typeof inputSchema>;

// workflows/my-workflow/defineStep.ts
import { baseDefineStep } from "runner";
import type { WorkflowInput } from "./input-schema";
export const defineStep = baseDefineStep<WorkflowInput>();

// workflows/my-workflow/steps/my-step/step.ts
import { defineStep } from "../../defineStep";

export const step = defineStep({
  fn: async ({ ctx }) => {
    const userId = ctx.input.userId;  // Fully typed!
    return { processed: true };
  }
});

Workflow Structure

workflows/my-workflow/
├── workflow.json       # {"name": "My Workflow"}
├── input-schema.ts     # Optional: Zod schema
├── defineStep.ts       # Optional: Typed helper
└── steps/
    ├── step-1/step.ts                    # Flat step
    ├── step-2/step.ts                    # Flat step
    └── data-processing/                  # Optional: Group directory
        ├── extract/
        │   └── fetch-data/step.ts       # Nested step
        └── transform/
            └── normalize/step.ts         # Nested step

Key Features

  • Promise caching - Automatic parallelization via cached promises
  • Type-safe dependencies - Import step objects for full TypeScript inference
  • Cycle detection - DFS validation prevents circular dependencies
  • Resume capability - Continue from previous runs
  • Pluggable backend - Abstract persistence layer
  • Nested step groups - Organize steps in arbitrary directory hierarchies (purely organizational)

Exports

// Main execution
runAll(options: RunAllOptions): Promise<WorkflowOutput>;

// Step helpers
defineStep(config: StepConfig): StepDefinition;
baseDefineStep<TInput>(): typeof defineStep;

// Discovery
discoverWorkflows(dir?: string): Promise<WorkflowMetadata[]>;
discoverSteps(workflowDir: string): Promise<LoadedStep[]>;