API Reference
Flow API

Flow API Reference

The Flow API allows you to define, compose, and execute workflows in ZoopFlow.

Core Functions

defineFlow

Creates a flow definition with input/output validation and error handling.

import { defineFlow } from '@zoopflow/core';
 
const myFlow = defineFlow({
  id: 'namespace.my-flow',
  version: '1.0.0',
  description: 'Example flow definition',
  input_schema: {
    type: 'object',
    properties: {
      userId: { type: 'string' },
      options: { type: 'object' }
    },
    required: ['userId']
  },
  output_schema: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      data: { type: 'object' }
    },
    required: ['success']
  },
  steps: async (input, context) => {
    // Flow implementation
    const result = await context.executeStep(userStep, { id: input.userId });
    return { success: true, data: result };
  },
  errorHandler: async (error, context) => {
    // Error handling logic
    return { success: false, error: error.message };
  }
});

Parameters

  • id (string) - Unique identifier for the flow, following the format namespace.name
  • version (string) - Semantic version of the flow
  • description (string, optional) - Human-readable description of the flow
  • input_schema (JSONSchema) - JSON Schema for validating flow inputs
  • output_schema (JSONSchema) - JSON Schema for validating flow outputs
  • steps (function) - Async function containing the flow implementation
  • errorHandler (function, optional) - Async function for handling errors

executeFlow

Executes a flow with the provided input.

import { executeFlow } from '@zoopflow/core';
import { myFlow } from './flows/my-flow';
 
async function runFlow() {
  const result = await executeFlow(myFlow, {
    userId: 'user-123',
    options: { includeDetails: true }
  });
  
  console.log('Flow result:', result);
}

Parameters

  • flow (FlowDefinition) - The flow definition to execute
  • input (any) - Input data for the flow, validated against input_schema
  • options (object, optional) - Execution options
    • context (FlowContext, optional) - Custom execution context
    • timeout (number, optional) - Maximum execution time in milliseconds

registerFlow

Registers a flow with the flow registry for later lookup and execution.

import { registerFlow } from '@zoopflow/core';
import { myFlow } from './flows/my-flow';
 
// Register the flow
registerFlow(myFlow);

Parameters

  • flow (FlowDefinition) - The flow definition to register

getFlow

Retrieves a flow from the registry by ID and version.

import { getFlow } from '@zoopflow/core';
 
// Get specific version
const flow = getFlow('namespace.my-flow', '1.0.0');
 
// Get latest version
const latestFlow = getFlow('namespace.my-flow');

Parameters

  • id (string) - Flow ID
  • version (string, optional) - Flow version, defaults to latest

Flow Context API

The Flow Context provides utilities and services during flow execution.

executeStep

Executes a step as part of a flow with validation and error handling.

// Inside a flow's steps function
const result = await context.executeStep(userStep, {
  id: 'user-123'
});

Parameters

  • step (StepDefinition) - The step definition to execute
  • input (any) - Input data for the step
  • options (object, optional) - Execution options
    • retryConfig (RetryConfig, optional) - Custom retry configuration

createCheckpoint

Creates a checkpoint to persist the flow's state for recovery.

// Inside a flow's steps function
await context.createCheckpoint({
  orderId: 'order-123',
  status: 'processing'
});

Parameters

  • state (object) - The state to persist

executeParallel

Executes multiple steps in parallel and waits for all to complete.

// Inside a flow's steps function
const [userData, orderData] = await context.executeParallel([
  { step: userStep, input: { id: 'user-123' } },
  { step: orderStep, input: { id: 'order-456' } }
]);

Parameters

  • steps (array) - Array of step execution configurations
    • step (StepDefinition) - The step definition to execute
    • input (any) - Input data for the step
    • options (object, optional) - Execution options
OverviewStep API