Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• Core Concepts
• Control Flow
• Event Interception
• Tech Stack
• License

Overview

@yaos-git/flow solves the problem of "Callback/Promise Hell" in complex business logic by treating workflows as a Directed Graph of Validated Transitions. By using JavaScript Generators, it provides a clean, readable syntax for handling jumps (GOTO), subroutines (CALL/BACK), and robust error recovery without recursive nesting.

Key Features

• Deterministic State Machine: Explicitly manage linear and global transitions.
• Generator Powered: Use yield to signal transitions while keeping logic readable.
• Schema-First: Built-in Zod validation for every step input.
• Immutable Context: Strictly enforced immutable state snapshots for pure logical transitions.
• Event Lifecycle: Intercept failure, yields, and interruptions with .on() handlers.

Installation

npm install @yaos-git/flow-lib

Quick Start

import { createFlow, z } from '@yaos-git/flow';

const flow = createFlow({ count: 0 })
  .step('start', function* (_, { step }) {
    yield step.next(10);
  })
  .step('double', {
    input: z.number(),
    action: function* (n, { step, updateContext, context }) {
      updateContext({ count: context.count + 1 });
      yield step.next(n * 2);
    }
  });

const result = await flow.run();
// result: { ok: true, data: 20 }

Core Concepts

FlowBuilder

The fluent API used to define your workflow.

• .step(name, action): Adds a linear step to the main execution chain.
• .global(name, action): Adds a named step available for .jump() from anywhere.
• .on(event, handler): Attaches a lifecycle listener.

FlowApi

Every step action receives an API object:

• step: Factory for signals (next, jump, back, halt, fail, retry).
• context: Readonly access to the current state.
• updateContext(patch): Returns a new frozen context snapshot.

Control Flow

Jumps & Subroutines

• yield step.jump('linearStep', data): A GOTO transition. Terminates the current step and moves the execution pointer.
• yield step.jump('globalStep', data): A CALL transition. Pushes the global step onto the call stack.
• yield step.back(data): Returns from a global step, injecting data back into the caller.

Event Interception

Recover from failures or handle interruptions gracefully:

flow.on('fail', async (err, { step }) => {
  if (err.message === 'RETRY_ME') {
    return step.jump('recovery_step', null);
  }
});

Tech Stack

• TypeScript 5.9 (ESM only)
• Zod (Validation)
• Vitest (Unit & E2E Testing)
• esbuild (Bundling)
• Biome (Linting & Formatting)

Project Structure

flow-lib/
├── dist/                # Compiled ESM bundle and declarations
├── examples/            # Standardized usage examples
│   ├── basic/           # Simple linear flows
│   ├── custom/          # Custom handlers and recovery
│   └── integration/     # Subroutines and complex logic
├── src/                 # Core source code
│   ├── core/            # Modular engine components
│   │   ├── FlowBuilder/
│   │   ├── FlowRunner/
│   │   ├── StepRegistry/
│   │   └── StepResolver/
│   ├── types/           # Granular type definitions
│   │   ├── FlowSignal/
│   │   ├── FlowAction/
│   │   └── ...
│   └── index.ts         # Main entry point
├── package.json         # Project metadata
└── README.md            # Documentation

Versioning

YAOS standard: MAJORYY.MINOR.PATCH (e.g., 126.0.0).

Style Guide

Follows YAOS-Git AGENTS.md conventions.

License

ISC