@cascadeflow/client

Type-safe programmatic client for submitting and managing workflow runs.

Installation

The client requires a backend implementation to persist workflow state. Install the client along with your chosen backend:

With Filesystem Backend (Recommended for Development)

npm install @cascadeflow/client @cascadeflow/backend-filesystem

With PostgreSQL Backend (Production)

npm install @cascadeflow/client @cascadeflow/backend-postgres

Usage

import { WorkflowClient } from "@cascadeflow/client";
import { FileSystemBackend } from "@cascadeflow/backend-filesystem";

const client = new WorkflowClient(new FileSystemBackend("./.runs"));

// Submit run
const { runId } = await client.submit({
  workflow: "my-workflow",
  input: { userId: "123", count: 42 },
  priority: 10,
  timeout: 300000
});

// Wait for completion
const output = await client.waitForCompletion(runId, {
  timeout: 60000,
  exponentialBackoff: true
});

// Check status
const info = await client.getRun(runId);

// Cancel
await client.cancel(runId, "reason");

Type Safety

interface MyInput { userId: string; count: number; }
interface MyOutput { results: string[]; }

const { runId } = await client.submit<MyInput>({
  workflow: "my-workflow",
  input: { userId: "123", count: 42 }  // Type-checked
});

const output = await client.waitForCompletion<MyOutput>(runId);
console.log(output.results);  // Type-safe access

Methods

// Submit run
submit<TInput>(params: {
  workflow: string;
  input?: TInput;
  priority?: number;
  timeout?: number;
  idempotencyKey?: string;
  metadata?: Record<string, unknown>;
  tags?: string[];
}): Promise<{ runId: string; isNew: boolean }>;

// Get status
getStatus(runId: string): Promise<RunStatus>;

// Get detailed info
getRun(runId: string): Promise<RunState | null>;

// Wait for completion
waitForCompletion<TOutput>(runId: string, options?: {
  interval?: number;
  exponentialBackoff?: boolean;
  maxBackoff?: number;
  timeout?: number;
}): Promise<TOutput>;

// List runs
listRuns(options?: { status?: RunStatus; limit?: number }): Promise<RunState[]>;

// Cancel run
cancel(runId: string, reason?: string): Promise<void>;

Timeouts

3-tier fallback for step execution:

1. Step-level: defineStep({ timeoutMs })
2. Submission-level: submit({ timeout }) ← This package
3. System default: 300000ms (5 min)

Submission timeout sets workflow-wide execution limit for steps without their own timeoutMs.

CLI Integration

Used internally by:

• cf submit → client.submit()
• cf status → client.getRun()
• cf cancel → client.cancel()