Backend Interface

Abstract persistence layer for workflow orchestration.

Installation

bun install

Overview

Defines the Backend abstract class and schemas for event sourcing architecture.

Key Components

Abstract Backend Class

import { Backend } from "@cascade-flow/backend-interface";

class MyBackend extends Backend {
  // Implement abstract methods
  async registerWorkflow(registration: WorkflowRegistration) { ... }
  async appendEvent(workflowSlug: string, runId: string, event: Event) { ... }
  async loadEvents(workflowSlug: string, runId: string) { ... }
  // ... other methods
}

Schemas

Event Schemas (src/events.ts):

• Step events: StepScheduled, StepStarted, StepHeartbeat, StepCompleted, StepFailed, StepReclaimed, LogEntry
• Workflow events: WorkflowStarted, WorkflowInputValidation, WorkflowCompleted, WorkflowFailed, WorkflowResumed, WorkflowCancelled, RunSubmitted

State Schemas (src/schemas.ts):

• stepStateSchema - Step state (computed from events)
• runStateSchema - Run state (computed from events)
• workflowMetadataSchema - Backend-agnostic workflow metadata
• stepDefinitionSchema - Step structure (includes id field with full path for nested steps)

Projection Functions

import { projectStepState, projectRunStateFromEvents } from "@cascade-flow/backend-interface";

// Compute current state from events
const stepState = projectStepState(stepEvents);
const runState = projectRunStateFromEvents(workflowEvents);

Event Structure

Events use two-level discrimination:

1. Category: "workflow" or "step"
2. Type: Event-specific (e.g., "StepStarted", "WorkflowCompleted")

Implementations

• FileSystemBackend - Stores events in .runs/ directory
• Custom backends - Implement for databases, cloud storage, etc.

Exports

// Abstract class
export { Backend } from "./interface";

// Schemas
export * from "./schemas";
export * from "./events";

// Projection
export { projectStepState, projectRunStateFromEvents } from "./projection";

// Utilities
export * from "./serialization";