yaml-flow 1.0.0

package/dist/types-BoWndaAJ.d.ts

@@ -0,0 +1,237 @@
+/**
+ * yaml-flow - Core Types
+ *
+ * All type definitions for the workflow engine.
+ */
+/**
+ * Root flow configuration - maps to YAML file structure
+ */
+interface FlowConfig {
+    /** Optional flow identifier */
+    id?: string;
+    /** Flow settings */
+    settings: FlowSettings;
+    /** Step definitions */
+    steps: Record<string, StepConfig>;
+    /** Terminal state definitions */
+    terminal_states: Record<string, TerminalStateConfig>;
+}
+/**
+ * Flow-level settings
+ */
+interface FlowSettings {
+    /** Step to start execution from */
+    start_step: string;
+    /** Maximum steps before forced termination (default: 100) */
+    max_total_steps?: number;
+    /** Flow timeout in milliseconds (optional) */
+    timeout_ms?: number;
+}
+/**
+ * Individual step configuration
+ */
+interface StepConfig {
+    /** Human-readable description */
+    description?: string;
+    /** Data keys this step expects as input */
+    expects_data?: string[];
+    /** Data keys this step produces as output */
+    produces_data?: string[];
+    /** Transition mapping: result -> next step name */
+    transitions: Record<string, string>;
+    /** Retry configuration for failures */
+    retry?: RetryConfig;
+    /** Circuit breaker for loops */
+    circuit_breaker?: CircuitBreakerConfig;
+}
+/**
+ * Retry configuration for step failures
+ */
+interface RetryConfig {
+    /** Maximum retry attempts */
+    max_attempts: number;
+    /** Delay between retries in ms */
+    delay_ms?: number;
+    /** Backoff multiplier (e.g., 2 for exponential) */
+    backoff_multiplier?: number;
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Maximum iterations before circuit opens */
+    max_iterations: number;
+    /** Step to transition to when circuit opens */
+    on_open: string;
+}
+/**
+ * Terminal state configuration
+ */
+interface TerminalStateConfig {
+    /** Human-readable description */
+    description?: string;
+    /** Intent/status to return (e.g., 'success', 'error', 'cancelled') */
+    return_intent: string;
+    /** Data key(s) to include in result, or false to exclude */
+    return_artifacts?: string | string[] | false;
+    /** Data keys this terminal state expects */
+    expects_data?: string[];
+}
+/**
+ * Step handler function signature
+ */
+type StepHandler = (input: StepInput, context: StepContext) => StepResult | Promise<StepResult>;
+/**
+ * Input passed to step handlers
+ */
+interface StepInput {
+    /** Data from previous steps based on expects_data */
+    [key: string]: unknown;
+}
+/**
+ * Context available to step handlers
+ */
+interface StepContext {
+    /** Run identifier */
+    runId: string;
+    /** Current step name */
+    stepName: string;
+    /** Injected components (DB, API clients, etc.) */
+    components: Record<string, unknown>;
+    /** Store instance for direct access if needed */
+    store: FlowStore;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Emit events for UI updates */
+    emit: (event: string, data: unknown) => void;
+}
+/**
+ * Result returned from step handlers
+ */
+interface StepResult {
+    /** Result key for transition routing (e.g., 'success', 'failure', 'retry') */
+    result: string;
+    /** Data to merge into flow state (must match produces_data) */
+    data?: Record<string, unknown>;
+}
+/**
+ * Engine configuration options
+ */
+interface EngineOptions {
+    /** Persistence store (default: MemoryStore) */
+    store?: FlowStore;
+    /** Injected components available to handlers */
+    components?: Record<string, unknown>;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Callback on each step execution */
+    onStep?: (stepName: string, result: StepResult) => void;
+    /** Callback on step transition */
+    onTransition?: (from: string, to: string) => void;
+    /** Callback on flow completion */
+    onComplete?: (result: FlowResult) => void;
+    /** Callback on flow error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Final result of flow execution
+ */
+interface FlowResult {
+    /** Run identifier */
+    runId: string;
+    /** Completion status */
+    status: 'completed' | 'failed' | 'cancelled' | 'timeout' | 'max_iterations';
+    /** Return intent from terminal state */
+    intent?: string;
+    /** Returned artifacts/data */
+    data: Record<string, unknown>;
+    /** Final step name */
+    finalStep: string;
+    /** Steps executed (in order) */
+    stepHistory: string[];
+    /** Total execution time in ms */
+    durationMs: number;
+    /** Error if failed */
+    error?: Error;
+}
+/**
+ * Pluggable store interface for persistence
+ */
+interface FlowStore {
+    /**
+     * Save run state
+     */
+    saveRunState(runId: string, state: RunState): Promise<void>;
+    /**
+     * Load run state
+     */
+    loadRunState(runId: string): Promise<RunState | null>;
+    /**
+     * Delete run state
+     */
+    deleteRunState(runId: string): Promise<void>;
+    /**
+     * Set a data value for a run
+     */
+    setData(runId: string, key: string, value: unknown): Promise<void>;
+    /**
+     * Get a data value for a run
+     */
+    getData(runId: string, key: string): Promise<unknown>;
+    /**
+     * Get all data for a run
+     */
+    getAllData(runId: string): Promise<Record<string, unknown>>;
+    /**
+     * Clear all data for a run
+     */
+    clearData(runId: string): Promise<void>;
+    /**
+     * List all active run IDs (optional - for management)
+     */
+    listRuns?(): Promise<string[]>;
+}
+/**
+ * Persisted run state
+ */
+interface RunState {
+    /** Run identifier */
+    runId: string;
+    /** Flow identifier */
+    flowId: string;
+    /** Current step name */
+    currentStep: string;
+    /** Execution status */
+    status: 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+    /** Ordered list of executed steps */
+    stepHistory: string[];
+    /** Iteration count per step (for circuit breakers) */
+    iterationCounts: Record<string, number>;
+    /** Retry counts per step */
+    retryCounts: Record<string, number>;
+    /** Timestamp when run started (ms since epoch) */
+    startedAt: number;
+    /** Timestamp of last update (ms since epoch) */
+    updatedAt: number;
+    /** Timestamp when paused (if applicable) */
+    pausedAt?: number;
+}
+/**
+ * Event types emitted by the engine
+ */
+type FlowEventType = 'step:start' | 'step:complete' | 'step:error' | 'transition' | 'flow:start' | 'flow:complete' | 'flow:error' | 'flow:paused' | 'flow:resumed';
+/**
+ * Event payload structure
+ */
+interface FlowEvent {
+    type: FlowEventType;
+    runId: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+/**
+ * Event listener function
+ */
+type FlowEventListener = (event: FlowEvent) => void;
+
+export type { CircuitBreakerConfig as C, EngineOptions as E, FlowConfig as F, RetryConfig as R, StepConfig as S, TerminalStateConfig as T, FlowEvent as a, FlowEventListener as b, FlowEventType as c, FlowResult as d, FlowSettings as e, FlowStore as f, RunState as g, StepContext as h, StepHandler as i, StepInput as j, StepResult as k };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "yaml-flow",
+  "version": "1.0.0",
+  "description": "Isomorphic workflow engine with declarative YAML flows, pluggable storage, and pure function handlers",
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./stores/memory": {
+      "types": "./dist/stores/memory.d.ts",
+      "import": "./dist/stores/memory.js",
+      "require": "./dist/stores/memory.cjs"
+    },
+    "./stores/localStorage": {
+      "types": "./dist/stores/localStorage.d.ts",
+      "import": "./dist/stores/localStorage.js",
+      "require": "./dist/stores/localStorage.cjs"
+    },
+    "./stores/file": {
+      "types": "./dist/stores/file.d.ts",
+      "import": "./dist/stores/file.js",
+      "require": "./dist/stores/file.cjs"
+    }
+  },
+  "browser": {
+    "./stores/file": false
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "dependencies": {
+    "yaml": "^2.3.4"
+  },
+  "optionalDependencies": {
+    "ajv": "^8.12.0"
+  },
+  "keywords": [
+    "workflow",
+    "state-machine",
+    "yaml",
+    "flow",
+    "isomorphic",
+    "browser",
+    "nodejs",
+    "declarative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nsreehari/yaml-flow.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/schema/flow.schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/yaml-flow/schema/flow.json",
+  "title": "YamlFlow Configuration",
+  "description": "Schema for yaml-flow workflow definitions",
+  "type": "object",
+  "required": ["settings", "steps", "terminal_states"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Optional flow identifier"
+    },
+    "settings": {
+      "type": "object",
+      "description": "Flow-level settings",
+      "required": ["start_step"],
+      "properties": {
+        "start_step": {
+          "type": "string",
+          "description": "Step to start execution from"
+        },
+        "max_total_steps": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 100,
+          "description": "Maximum steps before forced termination"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Flow timeout in milliseconds"
+        }
+      },
+      "additionalProperties": false
+    },
+    "steps": {
+      "type": "object",
+      "description": "Step definitions",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/definitions/step"
+      }
+    },
+    "terminal_states": {
+      "type": "object",
+      "description": "Terminal state definitions",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/definitions/terminal_state"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "step": {
+      "type": "object",
+      "description": "Individual step configuration",
+      "required": ["transitions"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "expects_data": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data keys this step expects as input"
+        },
+        "produces_data": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data keys this step produces as output"
+        },
+        "transitions": {
+          "type": "object",
+          "description": "Mapping of result -> next step name",
+          "additionalProperties": { "type": "string" },
+          "minProperties": 1
+        },
+        "retry": {
+          "$ref": "#/definitions/retry_config"
+        },
+        "circuit_breaker": {
+          "$ref": "#/definitions/circuit_breaker_config"
+        }
+      },
+      "additionalProperties": false
+    },
+    "terminal_state": {
+      "type": "object",
+      "description": "Terminal state configuration",
+      "required": ["return_intent"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Human-readable description"
+        },
+        "return_intent": {
+          "type": "string",
+          "description": "Intent/status to return (e.g., 'success', 'error')"
+        },
+        "return_artifacts": {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } },
+            { "type": "boolean", "const": false }
+          ],
+          "description": "Data key(s) to include in result, or false to exclude"
+        },
+        "expects_data": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Data keys this terminal state expects"
+        }
+      },
+      "additionalProperties": false
+    },
+    "retry_config": {
+      "type": "object",
+      "description": "Retry configuration for step failures",
+      "required": ["max_attempts"],
+      "properties": {
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum retry attempts"
+        },
+        "delay_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Delay between retries in ms"
+        },
+        "backoff_multiplier": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Backoff multiplier (e.g., 2 for exponential)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "circuit_breaker_config": {
+      "type": "object",
+      "description": "Circuit breaker configuration for loops",
+      "required": ["max_iterations", "on_open"],
+      "properties": {
+        "max_iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum iterations before circuit opens"
+        },
+        "on_open": {
+          "type": "string",
+          "description": "Step to transition to when circuit opens"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}