API Reference

Core API

Essential methods and types for defining and running workflows.

Step Options

Configuration options for individual workflow steps.

Retry Policies

Customizable retry behavior for handling failures.

Core API

Learn more in the Developing Workflows guide.

defineWorkflow

Creates a new workflow definition:

defineWorkflow(
  name: string,
  options?: WorkflowOptions,
  fn: WorkflowFunction
): Workflow

Basic Usage

export default defineWorkflow('hello-world', async (flow) => {
  await flow.do('greet', async () => {
    console.log('Hello, World!');
  });
});

With Options

export default defineWorkflow('process-order', {
  retries: {
    limit: 3,
    delay: '30 seconds',
    backoff: 'exponential'
  }
}, async (flow) => {
  await flow.do('process', async () => {
    return processOrder(flow.params);
  });
});

WorkflowContext

The context object passed to workflow functions:

params Input parameters passed to the workflow.

do() Execute a workflow step.

use() Access a binding (external service).

sleep() Pause workflow execution.

Step Options

interface StepOptions {
  // Number of retry attempts and strategy
  retries?: RetryPolicy;

  // Maximum execution time
  timeout?: string | number;

  // Unique key for idempotency
  idempotencyKey?: string;

  // Step-level validation
  schema?: Schema;

  // Circuit breaker configuration
  circuitBreaker?: CircuitBreakerOptions;

  // Result caching
  cache?: CacheOptions;
}

RetryPolicy

See Retry Policies for detailed configuration.

interface RetryPolicy {
  // Maximum retry attempts
  limit: number;

  // Delay between retries
  delay: string | number;

  // Retry delay pattern
  backoff: 'constant' | 'exponential' | 'linear';
}

CircuitBreakerOptions

interface CircuitBreakerOptions {
  // Failures before opening
  failureThreshold: number;

  // Time before retry
  resetTimeout: string | number;
}

CacheOptions

interface CacheOptions {
  // Cache duration
  ttl: string | number;

  // Cache key
  key: string;
}

Usage Examples

Step Execution

await flow.do('process payment', {
  retries: {
    limit: 3,
    delay: '30 seconds',
    backoff: 'exponential'
  },
  timeout: '5 minutes',
  idempotencyKey: orderId
}, async () => {
  return processPayment(flow.params);
});

Parallel Steps

See Parallel Processing for more details.

const [payment, inventory] = await Promise.all([
  flow.do('process payment', async () => {
    return processPayment(flow.params);
  }),
  flow.do('check inventory', async () => {
    return checkInventory(flow.params);
  })
]);

External Services

const client = flow.use(GraphqlClient);

await flow.do('fetch data', async () => {
return client.request(`     query GetUser($id: ID!) {
      user(id: $id) {
        id
        name
      }
    }
  `, { id: flow.params.userId });
});

Error Handling

See the main Error Handling guide for comprehensive strategies.

NonRetryableError

Use to indicate permanent failures that shouldn’t be retried:

await flow.do('process payment', async () => {
  try {
    return await processPayment(flow.params);
  } catch (error) {
    if (error.code === 'INVALID_CARD') {
      throw new NonRetryableError(error);
    }
    throw error;
  }
});

ValidationError

Thrown when input validation fails. See Data Validation.

await flow.do('validate input', { schema: InputSchema }, async (input) => {
  // Input is validated against schema
  return processInput(input);
});

Telemetry

Explore Observability Features and the Observability Deep Dive.

Tracing

await flow.do('process order', async ({ span }) => {
  // Add custom attributes
  span.setAttribute('order.id', flow.params.orderId);

  // Create nested span
  const validateSpan = span.createSpan('validate');
  try {
    await validateOrder(flow.params);
    validateSpan.setStatus({ code: SpanStatusCode.OK });
  } catch (error) {
    validateSpan.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
    throw error;
  } finally {
    validateSpan.end();
  }
});

Metrics

// Note: Collecting and exporting metrics requires integrating with an
// OpenTelemetry collector and backend system separately.
// See OpenTelemetry documentation for setup details.

Type Definitions

Complete Interface Reference

interface Workflow<TParams = any, TResult = any> {
  id: string;
  name: string;
  version: string;
  options?: WorkflowOptions;
  run(params: TParams): Promise<TResult>;
}

interface WorkflowOptions {
  retries?: RetryPolicy;
  timeout?: string | number;
  schema?: Schema;
  recovery?: RecoveryHandlers;
}

interface WorkflowContext<TParams = any> {
  params: TParams;
  instance: WorkflowInstance;
  definition: WorkflowDefinition;
  do<T>(name: string, options?: StepOptions, fn: StepFunction<T>): Promise<T>;
  use<T>(binding: Binding<T>): T;
  sleep(name: string, duration: string | number): Promise<void>;
}

interface StepFunction<T> {
  (context: StepContext): Promise<T>;
}

interface StepContext {
  span: Span;
  use<T>(binding: Binding<T>): T;
  log: Logger;
}

Next Steps

Workflow Rules

Learn essential guidelines for building reliable workflows.

Error Handling

Master error handling strategies.

TypeScript

Explore TypeScript integration for type-safe development.