Backend Filesystem

Filesystem-based implementation of the Backend interface.

Installation

bun install

Usage

import { FileSystemBackend } from "@cascade-flow/backend-filesystem";

const backend = new FileSystemBackend("./.runs");

Storage Structure

.runs/
├── .registry/                    # Workflow registry
│   └── {workflow-slug}/
│       ├── metadata.json         # Workflow metadata
│       └── steps.json            # Step definitions
└── {workflow-slug}/              # Execution state
    └── {runId}/
        ├── step-events/          # Step lifecycle events
        │   └── {timestamp}-{stepName}-{eventType}.json
        └── workflow-events/      # Workflow lifecycle events
            └── {timestamp}-{eventType}.json

Features

• Event storage - Individual JSON files per event
• Chronological ordering - Events sorted by timestamp
• Git-friendly - Human-readable JSON files
• No database required - Simple filesystem-based storage

Implementation

Extends Backend abstract class from backend-interface:

• Registry storage in .runs/.registry/{slug}/
• Event storage in .runs/{slug}/{runId}/
• State computed via event projection (no materialized views)
• Atomic file writes using Bun's filesystem API

Constructor

new FileSystemBackend(baseDir?: string)

• baseDir - Base directory for storage (default: ./.runs)