yaml-flow 1.0.0

package/dist/index.cjs

@@ -0,0 +1,742 @@
+'use strict';
+
+// src/stores/memory.ts
+var MemoryStore = class {
+  runs = /* @__PURE__ */ new Map();
+  data = /* @__PURE__ */ new Map();
+  async saveRunState(runId, state) {
+    this.runs.set(runId, { ...state });
+  }
+  async loadRunState(runId) {
+    const state = this.runs.get(runId);
+    return state ? { ...state } : null;
+  }
+  async deleteRunState(runId) {
+    this.runs.delete(runId);
+    this.data.delete(runId);
+  }
+  async setData(runId, key, value) {
+    if (!this.data.has(runId)) {
+      this.data.set(runId, {});
+    }
+    const runData = this.data.get(runId);
+    runData[key] = value;
+  }
+  async getData(runId, key) {
+    return this.data.get(runId)?.[key];
+  }
+  async getAllData(runId) {
+    return { ...this.data.get(runId) ?? {} };
+  }
+  async clearData(runId) {
+    this.data.delete(runId);
+  }
+  async listRuns() {
+    return Array.from(this.runs.keys());
+  }
+  /**
+   * Clear all data (useful for testing)
+   */
+  clear() {
+    this.runs.clear();
+    this.data.clear();
+  }
+};
+
+// src/core/engine.ts
+function generateRunId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var FlowEngine = class {
+  flow;
+  handlers;
+  store;
+  components;
+  options;
+  listeners = /* @__PURE__ */ new Map();
+  aborted = false;
+  constructor(flow, handlers, options = {}) {
+    this.flow = flow;
+    this.handlers = new Map(Object.entries(handlers));
+    this.store = options.store ?? new MemoryStore();
+    this.components = options.components ?? {};
+    this.options = options;
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => {
+        this.aborted = true;
+      });
+    }
+    this.validateFlow();
+  }
+  /**
+   * Validate the flow configuration
+   */
+  validateFlow() {
+    const { settings, steps, terminal_states } = this.flow;
+    if (!settings?.start_step) {
+      throw new Error("Flow must have settings.start_step defined");
+    }
+    if (!steps || Object.keys(steps).length === 0) {
+      throw new Error("Flow must have at least one step defined");
+    }
+    if (!terminal_states || Object.keys(terminal_states).length === 0) {
+      throw new Error("Flow must have at least one terminal_state defined");
+    }
+    if (!steps[settings.start_step] && !terminal_states[settings.start_step]) {
+      throw new Error(`Start step "${settings.start_step}" not found in steps or terminal_states`);
+    }
+    for (const [stepName, stepConfig] of Object.entries(steps)) {
+      for (const [result, target] of Object.entries(stepConfig.transitions)) {
+        if (!steps[target] && !terminal_states[target]) {
+          throw new Error(
+            `Step "${stepName}" transition "${result}" points to unknown step "${target}"`
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Run the flow from the start
+   */
+  async run(initialData) {
+    const runId = generateRunId();
+    const startedAt = Date.now();
+    const runState = {
+      runId,
+      flowId: this.flow.id ?? "unnamed",
+      currentStep: this.flow.settings.start_step,
+      status: "running",
+      stepHistory: [],
+      iterationCounts: {},
+      retryCounts: {},
+      startedAt,
+      updatedAt: startedAt
+    };
+    await this.store.saveRunState(runId, runState);
+    if (initialData) {
+      for (const [key, value] of Object.entries(initialData)) {
+        await this.store.setData(runId, key, value);
+      }
+    }
+    this.emit({
+      type: "flow:start",
+      runId,
+      timestamp: startedAt,
+      data: { initialData }
+    });
+    try {
+      return await this.executeLoop(runId, runState, startedAt);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit({
+        type: "flow:error",
+        runId,
+        timestamp: Date.now(),
+        data: { error: err.message }
+      });
+      this.options.onError?.(err);
+      runState.status = "failed";
+      runState.updatedAt = Date.now();
+      await this.store.saveRunState(runId, runState);
+      return {
+        runId,
+        status: "failed",
+        data: await this.store.getAllData(runId),
+        finalStep: runState.currentStep,
+        stepHistory: runState.stepHistory,
+        durationMs: Date.now() - startedAt,
+        error: err
+      };
+    }
+  }
+  /**
+   * Resume a paused or interrupted flow
+   */
+  async resume(runId) {
+    const runState = await this.store.loadRunState(runId);
+    if (!runState) {
+      throw new Error(`No run found with ID: ${runId}`);
+    }
+    if (runState.status === "completed" || runState.status === "failed") {
+      throw new Error(`Cannot resume a ${runState.status} run`);
+    }
+    const startedAt = runState.startedAt;
+    runState.status = "running";
+    runState.pausedAt = void 0;
+    runState.updatedAt = Date.now();
+    await this.store.saveRunState(runId, runState);
+    this.emit({
+      type: "flow:resumed",
+      runId,
+      timestamp: Date.now(),
+      data: { currentStep: runState.currentStep }
+    });
+    return this.executeLoop(runId, runState, startedAt);
+  }
+  /**
+   * Pause a running flow
+   */
+  async pause(runId) {
+    const runState = await this.store.loadRunState(runId);
+    if (!runState) {
+      throw new Error(`No run found with ID: ${runId}`);
+    }
+    runState.status = "paused";
+    runState.pausedAt = Date.now();
+    runState.updatedAt = Date.now();
+    await this.store.saveRunState(runId, runState);
+    this.emit({
+      type: "flow:paused",
+      runId,
+      timestamp: Date.now(),
+      data: { currentStep: runState.currentStep }
+    });
+  }
+  /**
+   * Main execution loop
+   */
+  async executeLoop(runId, runState, startedAt) {
+    const maxSteps = this.flow.settings.max_total_steps ?? 100;
+    const timeoutMs = this.flow.settings.timeout_ms;
+    let iterations = 0;
+    while (iterations < maxSteps) {
+      if (this.aborted) {
+        runState.status = "cancelled";
+        runState.updatedAt = Date.now();
+        await this.store.saveRunState(runId, runState);
+        return {
+          runId,
+          status: "cancelled",
+          data: await this.store.getAllData(runId),
+          finalStep: runState.currentStep,
+          stepHistory: runState.stepHistory,
+          durationMs: Date.now() - startedAt
+        };
+      }
+      if (timeoutMs && Date.now() - startedAt > timeoutMs) {
+        runState.status = "completed";
+        runState.updatedAt = Date.now();
+        await this.store.saveRunState(runId, runState);
+        return {
+          runId,
+          status: "timeout",
+          intent: "timeout",
+          data: await this.store.getAllData(runId),
+          finalStep: runState.currentStep,
+          stepHistory: runState.stepHistory,
+          durationMs: Date.now() - startedAt
+        };
+      }
+      const currentStep = runState.currentStep;
+      const terminalState = this.flow.terminal_states[currentStep];
+      if (terminalState) {
+        runState.status = "completed";
+        runState.updatedAt = Date.now();
+        await this.store.saveRunState(runId, runState);
+        const allData = await this.store.getAllData(runId);
+        const returnData = this.extractReturnData(terminalState.return_artifacts, allData);
+        const result = {
+          runId,
+          status: "completed",
+          intent: terminalState.return_intent,
+          data: returnData,
+          finalStep: currentStep,
+          stepHistory: runState.stepHistory,
+          durationMs: Date.now() - startedAt
+        };
+        this.emit({
+          type: "flow:complete",
+          runId,
+          timestamp: Date.now(),
+          data: { ...result }
+        });
+        this.options.onComplete?.(result);
+        return result;
+      }
+      const stepConfig = this.flow.steps[currentStep];
+      if (!stepConfig) {
+        throw new Error(`Step "${currentStep}" not found in flow configuration`);
+      }
+      if (stepConfig.circuit_breaker) {
+        const count = runState.iterationCounts[currentStep] ?? 0;
+        if (count >= stepConfig.circuit_breaker.max_iterations) {
+          runState.currentStep = stepConfig.circuit_breaker.on_open;
+          runState.updatedAt = Date.now();
+          await this.store.saveRunState(runId, runState);
+          iterations++;
+          continue;
+        }
+      }
+      runState.iterationCounts[currentStep] = (runState.iterationCounts[currentStep] ?? 0) + 1;
+      const stepResult = await this.executeStep(runId, currentStep, stepConfig);
+      if (stepResult.result === "failure" && stepConfig.retry) {
+        const retryCount = runState.retryCounts[currentStep] ?? 0;
+        if (retryCount < stepConfig.retry.max_attempts) {
+          runState.retryCounts[currentStep] = retryCount + 1;
+          if (stepConfig.retry.delay_ms) {
+            const delay = stepConfig.retry.backoff_multiplier ? stepConfig.retry.delay_ms * Math.pow(stepConfig.retry.backoff_multiplier, retryCount) : stepConfig.retry.delay_ms;
+            await this.sleep(delay);
+          }
+          iterations++;
+          continue;
+        }
+      }
+      const nextStep = stepConfig.transitions[stepResult.result];
+      if (!nextStep) {
+        throw new Error(
+          `No transition defined for result "${stepResult.result}" in step "${currentStep}"`
+        );
+      }
+      runState.stepHistory.push(currentStep);
+      runState.currentStep = nextStep;
+      runState.updatedAt = Date.now();
+      runState.retryCounts[currentStep] = 0;
+      await this.store.saveRunState(runId, runState);
+      this.emit({
+        type: "transition",
+        runId,
+        timestamp: Date.now(),
+        data: { from: currentStep, to: nextStep, result: stepResult.result }
+      });
+      this.options.onTransition?.(currentStep, nextStep);
+      iterations++;
+    }
+    runState.status = "completed";
+    runState.updatedAt = Date.now();
+    await this.store.saveRunState(runId, runState);
+    return {
+      runId,
+      status: "max_iterations",
+      intent: "max_iterations",
+      data: await this.store.getAllData(runId),
+      finalStep: runState.currentStep,
+      stepHistory: runState.stepHistory,
+      durationMs: Date.now() - startedAt
+    };
+  }
+  /**
+   * Execute a single step
+   */
+  async executeStep(runId, stepName, stepConfig) {
+    const handler = this.handlers.get(stepName);
+    if (!handler) {
+      throw new Error(`No handler registered for step "${stepName}"`);
+    }
+    const allData = await this.store.getAllData(runId);
+    const input = {};
+    if (stepConfig.expects_data) {
+      for (const key of stepConfig.expects_data) {
+        input[key] = allData[key];
+      }
+    } else {
+      Object.assign(input, allData);
+    }
+    const context = {
+      runId,
+      stepName,
+      components: this.components,
+      store: this.store,
+      signal: this.options.signal,
+      emit: (event, data) => {
+        this.emit({
+          type: "step:complete",
+          // Custom events map to step:complete
+          runId,
+          timestamp: Date.now(),
+          data: { event, payload: data }
+        });
+      }
+    };
+    this.emit({
+      type: "step:start",
+      runId,
+      timestamp: Date.now(),
+      data: { step: stepName, input }
+    });
+    try {
+      const result = await handler(input, context);
+      if (result.data) {
+        for (const [key, value] of Object.entries(result.data)) {
+          await this.store.setData(runId, key, value);
+        }
+      }
+      this.emit({
+        type: "step:complete",
+        runId,
+        timestamp: Date.now(),
+        data: { step: stepName, result: result.result, outputKeys: Object.keys(result.data ?? {}) }
+      });
+      this.options.onStep?.(stepName, result);
+      return result;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit({
+        type: "step:error",
+        runId,
+        timestamp: Date.now(),
+        data: { step: stepName, error: err.message }
+      });
+      return { result: "failure", data: { error: err.message } };
+    }
+  }
+  /**
+   * Extract data to return based on return_artifacts configuration
+   */
+  extractReturnData(returnArtifacts, allData) {
+    if (returnArtifacts === false || returnArtifacts === void 0) {
+      return {};
+    }
+    if (typeof returnArtifacts === "string") {
+      return { [returnArtifacts]: allData[returnArtifacts] };
+    }
+    if (Array.isArray(returnArtifacts)) {
+      const result = {};
+      for (const key of returnArtifacts) {
+        result[key] = allData[key];
+      }
+      return result;
+    }
+    return allData;
+  }
+  /**
+   * Sleep helper
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Subscribe to flow events
+   */
+  on(type, listener) {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(type).add(listener);
+    return () => {
+      this.listeners.get(type)?.delete(listener);
+    };
+  }
+  /**
+   * Emit an event
+   */
+  emit(event) {
+    const typeListeners = this.listeners.get(event.type);
+    if (typeListeners) {
+      for (const listener of typeListeners) {
+        try {
+          listener(event);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Get the current store instance
+   */
+  getStore() {
+    return this.store;
+  }
+};
+function createEngine(flow, handlers, options) {
+  return new FlowEngine(flow, handlers, options);
+}
+
+// src/core/loader.ts
+async function parseYaml(yamlString) {
+  const yaml = await import('yaml');
+  return yaml.parse(yamlString);
+}
+async function loadFlowFromUrl(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to load flow from ${url}: ${response.statusText}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  const text = await response.text();
+  if (contentType.includes("json") || url.endsWith(".json")) {
+    return JSON.parse(text);
+  }
+  return parseYaml(text);
+}
+async function loadFlowFromFile(filePath) {
+  const fs = await import('fs/promises');
+  const text = await fs.readFile(filePath, "utf-8");
+  if (filePath.endsWith(".json")) {
+    return JSON.parse(text);
+  }
+  return parseYaml(text);
+}
+function validateFlowConfig(flow) {
+  const errors = [];
+  if (!flow || typeof flow !== "object") {
+    return ["Flow must be an object"];
+  }
+  const f = flow;
+  if (!f.settings || typeof f.settings !== "object") {
+    errors.push('Flow must have a "settings" object');
+  } else {
+    const settings = f.settings;
+    if (typeof settings.start_step !== "string") {
+      errors.push("settings.start_step must be a string");
+    }
+    if (settings.max_total_steps !== void 0 && typeof settings.max_total_steps !== "number") {
+      errors.push("settings.max_total_steps must be a number");
+    }
+    if (settings.timeout_ms !== void 0 && typeof settings.timeout_ms !== "number") {
+      errors.push("settings.timeout_ms must be a number");
+    }
+  }
+  if (!f.steps || typeof f.steps !== "object") {
+    errors.push('Flow must have a "steps" object');
+  } else {
+    const steps = f.steps;
+    for (const [stepName, stepConfig] of Object.entries(steps)) {
+      if (!stepConfig || typeof stepConfig !== "object") {
+        errors.push(`Step "${stepName}" must be an object`);
+        continue;
+      }
+      const step = stepConfig;
+      if (!step.transitions || typeof step.transitions !== "object") {
+        errors.push(`Step "${stepName}" must have a "transitions" object`);
+      }
+    }
+  }
+  if (!f.terminal_states || typeof f.terminal_states !== "object") {
+    errors.push('Flow must have a "terminal_states" object');
+  } else {
+    const terminals = f.terminal_states;
+    for (const [name, config] of Object.entries(terminals)) {
+      if (!config || typeof config !== "object") {
+        errors.push(`Terminal state "${name}" must be an object`);
+        continue;
+      }
+      const terminal = config;
+      if (typeof terminal.return_intent !== "string") {
+        errors.push(`Terminal state "${name}" must have a "return_intent" string`);
+      }
+    }
+  }
+  return errors;
+}
+async function loadFlow(source) {
+  let flow;
+  if (typeof source === "string") {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+      flow = await loadFlowFromUrl(source);
+    } else if (source.includes("{")) {
+      flow = JSON.parse(source);
+    } else {
+      flow = await loadFlowFromFile(source);
+    }
+  } else {
+    flow = source;
+  }
+  const errors = validateFlowConfig(flow);
+  if (errors.length > 0) {
+    throw new Error(`Invalid flow configuration:
+- ${errors.join("\n- ")}`);
+  }
+  return flow;
+}
+
+// src/stores/localStorage.ts
+var LocalStorageStore = class {
+  prefix;
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "yamlflow";
+    if (typeof localStorage === "undefined") {
+      throw new Error("LocalStorageStore requires localStorage (browser environment)");
+    }
+  }
+  runKey(runId) {
+    return `${this.prefix}:run:${runId}`;
+  }
+  dataKey(runId) {
+    return `${this.prefix}:data:${runId}`;
+  }
+  indexKey() {
+    return `${this.prefix}:runs`;
+  }
+  async saveRunState(runId, state) {
+    localStorage.setItem(this.runKey(runId), JSON.stringify(state));
+    const runs = await this.listRuns();
+    if (!runs.includes(runId)) {
+      runs.push(runId);
+      localStorage.setItem(this.indexKey(), JSON.stringify(runs));
+    }
+  }
+  async loadRunState(runId) {
+    const raw = localStorage.getItem(this.runKey(runId));
+    return raw ? JSON.parse(raw) : null;
+  }
+  async deleteRunState(runId) {
+    localStorage.removeItem(this.runKey(runId));
+    localStorage.removeItem(this.dataKey(runId));
+    const runs = await this.listRuns();
+    const filtered = runs.filter((id) => id !== runId);
+    localStorage.setItem(this.indexKey(), JSON.stringify(filtered));
+  }
+  async setData(runId, key, value) {
+    const allData = await this.getAllData(runId);
+    allData[key] = value;
+    localStorage.setItem(this.dataKey(runId), JSON.stringify(allData));
+  }
+  async getData(runId, key) {
+    const allData = await this.getAllData(runId);
+    return allData[key];
+  }
+  async getAllData(runId) {
+    const raw = localStorage.getItem(this.dataKey(runId));
+    return raw ? JSON.parse(raw) : {};
+  }
+  async clearData(runId) {
+    localStorage.removeItem(this.dataKey(runId));
+  }
+  async listRuns() {
+    const raw = localStorage.getItem(this.indexKey());
+    return raw ? JSON.parse(raw) : [];
+  }
+  /**
+   * Clear all flow data from localStorage
+   */
+  clearAll() {
+    const keysToRemove = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(this.prefix + ":")) {
+        keysToRemove.push(key);
+      }
+    }
+    keysToRemove.forEach((key) => localStorage.removeItem(key));
+  }
+};
+
+// src/stores/file.ts
+var FileStore = class {
+  directory;
+  fs = null;
+  path = null;
+  constructor(options) {
+    this.directory = options.directory;
+  }
+  async ensureModules() {
+    if (!this.fs || !this.path) {
+      this.fs = await import('fs/promises');
+      this.path = await import('path');
+      await this.fs.mkdir(this.directory, { recursive: true });
+    }
+  }
+  runPath(runId) {
+    return this.path.join(this.directory, `${runId}.run.json`);
+  }
+  dataPath(runId) {
+    return this.path.join(this.directory, `${runId}.data.json`);
+  }
+  async saveRunState(runId, state) {
+    await this.ensureModules();
+    await this.fs.writeFile(
+      this.runPath(runId),
+      JSON.stringify(state, null, 2),
+      "utf-8"
+    );
+  }
+  async loadRunState(runId) {
+    await this.ensureModules();
+    try {
+      const raw = await this.fs.readFile(this.runPath(runId), "utf-8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async deleteRunState(runId) {
+    await this.ensureModules();
+    try {
+      await this.fs.unlink(this.runPath(runId));
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+    try {
+      await this.fs.unlink(this.dataPath(runId));
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  async setData(runId, key, value) {
+    await this.ensureModules();
+    const allData = await this.getAllData(runId);
+    allData[key] = value;
+    await this.fs.writeFile(
+      this.dataPath(runId),
+      JSON.stringify(allData, null, 2),
+      "utf-8"
+    );
+  }
+  async getData(runId, key) {
+    const allData = await this.getAllData(runId);
+    return allData[key];
+  }
+  async getAllData(runId) {
+    await this.ensureModules();
+    try {
+      const raw = await this.fs.readFile(this.dataPath(runId), "utf-8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return {};
+      }
+      throw err;
+    }
+  }
+  async clearData(runId) {
+    await this.ensureModules();
+    try {
+      await this.fs.unlink(this.dataPath(runId));
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
+  async listRuns() {
+    await this.ensureModules();
+    try {
+      const files = await this.fs.readdir(this.directory);
+      return files.filter((f) => f.endsWith(".run.json")).map((f) => f.replace(".run.json", ""));
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return [];
+      }
+      throw err;
+    }
+  }
+  /**
+   * Clear all flow data from directory
+   */
+  async clearAll() {
+    await this.ensureModules();
+    const runs = await this.listRuns();
+    await Promise.all(runs.map((runId) => this.deleteRunState(runId)));
+  }
+};
+
+exports.FileStore = FileStore;
+exports.FlowEngine = FlowEngine;
+exports.LocalStorageStore = LocalStorageStore;
+exports.MemoryStore = MemoryStore;
+exports.createEngine = createEngine;
+exports.loadFlow = loadFlow;
+exports.loadFlowFromFile = loadFlowFromFile;
+exports.loadFlowFromUrl = loadFlowFromUrl;
+exports.parseYaml = parseYaml;
+exports.validateFlowConfig = validateFlowConfig;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map