@duckflux/core 0.6.8

package/src/engine/timeout.ts

@@ -0,0 +1,43 @@
+import { parseDuration } from "./errors";
+
+export class TimeoutError extends Error {
+  timeoutMs: number;
+  constructor(message: string, timeoutMs: number) {
+    super(message);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export async function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new TimeoutError(`operation timed out after ${timeoutMs}ms`, timeoutMs)), timeoutMs);
+  });
+  try {
+    return await Promise.race([fn(), timeoutPromise]) as T;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function resolveTimeout(
+  flowOverride?: { timeout?: string } | null,
+  participant?: { timeout?: string } | null,
+  defaults?: { timeout?: string } | null
+): number | undefined {
+  const t = (flowOverride && flowOverride.timeout) ?? (participant && participant.timeout) ?? (defaults && defaults.timeout);
+  if (!t) return undefined;
+  try {
+    return parseDuration(t);
+  } catch (err) {
+    // If parsing fails, rethrow as Error with context
+    throw new Error(`invalid timeout value '${t}': ${(err && (err as Error).message) || err}`);
+  }
+}
+
+export default {
+  TimeoutError,
+  withTimeout,
+  resolveTimeout,
+};

package/src/engine/wait.ts

@@ -0,0 +1,102 @@
+import { evaluateCel } from "../cel/index";
+import { parseDuration } from "./errors";
+import type { WorkflowState } from "./state";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function executeWait(
+  state: WorkflowState,
+  waitDef: {
+    event?: string;
+    match?: string;
+    until?: string;
+    poll?: string;
+    timeout?: string;
+    onTimeout?: string;
+  },
+  chain?: unknown,
+  hub?: { subscribe(event: string, signal?: AbortSignal): AsyncIterable<{ name: string; payload: unknown }> },
+  signal?: AbortSignal,
+): Promise<unknown> {
+  const timeoutMs = waitDef.timeout ? parseDuration(waitDef.timeout) : undefined;
+  const onTimeout = waitDef.onTimeout ?? "fail";
+
+  // Sleep mode: only timeout, no event or until
+  if (!waitDef.event && !waitDef.until && waitDef.timeout) {
+    await sleep(parseDuration(waitDef.timeout));
+    return chain;
+  }
+
+  // Polling mode: until + optional poll + optional timeout
+  if (waitDef.until) {
+    const pollMs = waitDef.poll ? parseDuration(waitDef.poll) : 1000;
+    const deadline = timeoutMs ? Date.now() + timeoutMs : undefined;
+
+    while (true) {
+      if (signal?.aborted) {
+        throw new Error("wait aborted");
+      }
+
+      const result = evaluateCel(waitDef.until, state.toCelContext());
+      if (result === true) {
+        return chain;
+      }
+
+      if (deadline && Date.now() >= deadline) {
+        if (onTimeout === "skip") return chain;
+        throw new Error(`wait polling timed out after ${waitDef.timeout}`);
+      }
+
+      await sleep(pollMs);
+    }
+  }
+
+  // Event mode: event + optional match + optional timeout
+  if (waitDef.event) {
+    if (!hub) {
+      throw new Error("wait.event requires an event hub but none was provided");
+    }
+
+    const controller = new AbortController();
+    const combinedSignal = signal
+      ? AbortSignal.any([signal, controller.signal])
+      : controller.signal;
+
+    let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs) {
+      timeoutTimer = setTimeout(() => controller.abort(), timeoutMs);
+    }
+
+    try {
+      for await (const envelope of hub.subscribe(waitDef.event, combinedSignal)) {
+        if (waitDef.match) {
+          // Evaluate match condition with event payload in context
+          const prevEvent = state.eventPayload;
+          state.eventPayload = envelope.payload;
+          const matched = evaluateCel(waitDef.match, state.toCelContext());
+          if (matched !== true) {
+            // Restore previous event payload on non-match
+            state.eventPayload = prevEvent;
+            continue;
+          }
+        }
+
+        // Event matched
+        state.eventPayload = envelope.payload;
+        return envelope.payload;
+      }
+    } catch (err) {
+      if ((err as Error)?.name === "AbortError" || controller.signal.aborted) {
+        if (onTimeout === "skip") return chain;
+        throw new Error(`wait.event timed out after ${waitDef.timeout}`);
+      }
+      throw err;
+    } finally {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+    }
+  }
+
+  return chain;
+}

package/src/eventhub/index.ts

@@ -0,0 +1,24 @@
+export type { EventHub, EventEnvelope, EventHubConfig } from "./types";
+export { MemoryHub } from "./memory";
+
+import type { EventHub, EventHubConfig } from "./types";
+import { MemoryHub } from "./memory";
+
+export async function createHub(config: EventHubConfig): Promise<EventHub> {
+  switch (config.backend) {
+    case "memory":
+      return new MemoryHub();
+    case "nats":
+      throw new Error(
+        "NATS backend has been moved to @duckflux/hub-nats. " +
+        "Install it and pass a NatsHub instance via ExecuteOptions.hub instead.",
+      );
+    case "redis":
+      throw new Error(
+        "Redis backend has been moved to @duckflux/hub-redis. " +
+        "Install it and pass a RedisHub instance via ExecuteOptions.hub instead.",
+      );
+    default:
+      throw new Error(`unknown event hub backend: ${(config as { backend: string }).backend}`);
+  }
+}

package/src/eventhub/memory.ts

@@ -0,0 +1,106 @@
+import type { EventEnvelope, EventHub } from "./types";
+
+type Listener = (envelope: EventEnvelope) => void;
+
+export class MemoryHub implements EventHub {
+  private listeners = new Map<string, Set<Listener>>();
+  private buffer = new Map<string, EventEnvelope[]>();
+  private closed = false;
+
+  async publish(event: string, payload: unknown): Promise<void> {
+    if (this.closed) throw new Error("hub is closed");
+
+    const envelope: EventEnvelope = { name: event, payload };
+
+    // Buffer for replay
+    let buf = this.buffer.get(event);
+    if (!buf) {
+      buf = [];
+      this.buffer.set(event, buf);
+    }
+    buf.push(envelope);
+
+    // Fan-out to current listeners
+    const listeners = this.listeners.get(event);
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(envelope);
+      }
+    }
+  }
+
+  async publishAndWaitAck(event: string, payload: unknown, _timeoutMs: number): Promise<void> {
+    // In-memory delivery is synchronous, so ack is immediate
+    await this.publish(event, payload);
+  }
+
+  async *subscribe(event: string, signal?: AbortSignal): AsyncIterable<EventEnvelope> {
+    if (this.closed) return;
+
+    // Replay buffered events first
+    const buffered = this.buffer.get(event);
+    if (buffered) {
+      for (const envelope of buffered) {
+        if (signal?.aborted) return;
+        yield envelope;
+      }
+    }
+
+    // Then listen for new events
+    const queue: EventEnvelope[] = [];
+    let resolve: (() => void) | null = null;
+
+    const listener: Listener = (envelope) => {
+      queue.push(envelope);
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    };
+
+    let listeners = this.listeners.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.listeners.set(event, listeners);
+    }
+    listeners.add(listener);
+
+    const onAbort = () => {
+      listeners!.delete(listener);
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener("abort", onAbort);
+    }
+
+    try {
+      while (!this.closed && !signal?.aborted) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else {
+          await new Promise<void>((r) => {
+            resolve = r;
+          });
+        }
+      }
+    } finally {
+      listeners.delete(listener);
+      if (signal) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    // Wake up all waiting subscribers
+    for (const listeners of this.listeners.values()) {
+      listeners.clear();
+    }
+    this.listeners.clear();
+  }
+}

package/src/eventhub/types.ts

@@ -0,0 +1,17 @@
+export interface EventEnvelope {
+  name: string;
+  payload: unknown;
+}
+
+export interface EventHubConfig {
+  backend: "memory" | "nats" | "redis";
+  nats?: { url: string; stream?: string };
+  redis?: { addr?: string; db?: number; consumerGroup?: string };
+}
+
+export interface EventHub {
+  publish(event: string, payload: unknown): Promise<void>;
+  publishAndWaitAck(event: string, payload: unknown, timeoutMs: number): Promise<void>;
+  subscribe(event: string, signal?: AbortSignal): AsyncIterable<EventEnvelope>;
+  close(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Parser
+export { parseWorkflow, parseWorkflowFile } from "./parser/parser";
+export { validateSchema } from "./parser/schema";
+export { validateSemantic } from "./parser/validate";
+export { validateInputs } from "./parser/validate_inputs";
+
+// CEL
+export { validateCelExpression, evaluateCel, evaluateCelStrict, buildCelContext, evalMaybeCel } from "./cel/index";
+
+// Engine
+export { executeWorkflow, runWorkflowFromFile } from "./engine/engine";
+export type { EventHub as EngineEventHub, ExecuteOptions } from "./engine/engine";
+export { WorkflowState } from "./engine/state";
+export { mergeChainedInput } from "./engine/sequential";
+export { executeWait } from "./engine/wait";
+
+// Event Hub
+export { MemoryHub } from "./eventhub/memory";
+export { createHub } from "./eventhub/index";
+export type { EventHub, EventEnvelope, EventHubConfig } from "./eventhub/types";
+
+// Participants
+export { executeEmit } from "./participant/emit";
+
+// Types
+export type {
+  Workflow,
+  Participant,
+  ParticipantBase,
+  FlowStep,
+  ExecParticipant,
+  HttpParticipant,
+  McpParticipant,
+  WorkflowParticipant,
+  EmitParticipant,
+  InlineParticipant,
+  WaitStep,
+  LoopStep,
+  ParallelStep,
+  IfStep,
+  FlowStepOverride,
+  StepResult,
+  WorkflowResult,
+  WorkflowOutput,
+  ValidationResult,
+  ValidationError,
+  WorkflowDefaults,
+  ErrorStrategy,
+  RetryConfig,
+  InputDefinition,
+} from "./model/index";

package/src/model/index.ts

@@ -0,0 +1,183 @@
+export interface Workflow {
+  id?: string;
+  name?: string;
+  version?: string | number;
+  defaults?: WorkflowDefaults;
+  inputs?: Record<string, InputDefinition | null>;
+  participants?: Record<string, Participant>;
+  flow: FlowStep[];
+  output?: WorkflowOutput;
+}
+
+export interface WorkflowDefaults {
+  timeout?: string;
+  cwd?: string;
+  onError?: ErrorStrategy;
+}
+
+export type ErrorStrategy = "fail" | "skip" | "retry" | string;
+
+export interface RetryConfig {
+  max: number;
+  backoff?: string;
+  factor?: number;
+}
+
+export interface ParticipantBase {
+  type: string;
+  as?: string;
+  timeout?: string;
+  onError?: ErrorStrategy;
+  retry?: RetryConfig;
+  input?: string | Record<string, string>;
+  output?: Record<string, unknown>;
+  when?: string;
+}
+
+export interface ExecParticipant extends ParticipantBase {
+  type: "exec";
+  run?: string;
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export interface HttpParticipant extends ParticipantBase {
+  type: "http";
+  method?: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: string | Record<string, unknown>;
+}
+
+export interface McpParticipant extends ParticipantBase {
+  type: "mcp";
+  server?: string;
+  tool?: string;
+}
+
+export interface WorkflowParticipant extends ParticipantBase {
+  type: "workflow";
+  path: string;
+}
+
+export interface EmitParticipant extends ParticipantBase {
+  type: "emit";
+  event: string;
+  payload?: string | Record<string, unknown>;
+  ack?: boolean;
+  onTimeout?: "fail" | "skip";
+}
+
+export type Participant =
+  | ExecParticipant
+  | HttpParticipant
+  | McpParticipant
+  | WorkflowParticipant
+  | EmitParticipant;
+
+export type InlineParticipant = Participant & {
+  as?: string;
+  when?: string;
+};
+
+export interface WaitStep {
+  wait: {
+    event?: string;
+    match?: string;
+    until?: string;
+    poll?: string;
+    timeout?: string;
+    onTimeout?: string;
+  };
+}
+
+export interface SetStep {
+  set: Record<string, string>;
+}
+
+export type FlowStep = string | FlowStepOverride | LoopStep | ParallelStep | IfStep | WaitStep | SetStep | InlineParticipant;
+
+export interface FlowStepOverride {
+  [participantName: string]: {
+    timeout?: string;
+    onError?: ErrorStrategy;
+    when?: string;
+    input?: string | Record<string, string>;
+    retry?: RetryConfig;
+    workflow?: string;
+  };
+}
+
+export interface LoopStep {
+  loop: {
+    as?: string;
+    until?: string;
+    max?: number | string;
+    steps: FlowStep[];
+  };
+}
+
+export interface ParallelStep {
+  parallel: FlowStep[];
+}
+
+export interface IfStep {
+  if: {
+    condition: string;
+    then: FlowStep[];
+    else?: FlowStep[];
+  };
+}
+
+export interface InputDefinition {
+  type?: string;
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+  format?: string;
+  enum?: unknown[];
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  items?: InputDefinition;
+}
+
+export type WorkflowOutput =
+  | string
+  | Record<string, string>
+  | { schema: Record<string, InputDefinition>; map: Record<string, string> };
+
+export interface StepResult {
+  status: "success" | "failure" | "skipped";
+  output: string;
+  parsedOutput?: unknown;
+  error?: string;
+  duration: number;
+  startedAt?: string;
+  finishedAt?: string;
+  retries?: number;
+  cwd?: string;
+  /** HTTP status code on HTTP participant failure */
+  httpStatus?: number;
+  /** HTTP response body on HTTP participant failure */
+  responseBody?: string;
+}
+
+export interface WorkflowResult {
+  success: boolean;
+  output: unknown;
+  steps: Record<string, StepResult>;
+  duration: number;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+
+export interface ValidationError {
+  path: string;
+  message: string;
+}

package/src/parser/index.ts

@@ -0,0 +1,4 @@
+export { parseWorkflow, parseWorkflowFile } from "./parser";
+export { validateSchema } from "./schema";
+export { validateSemantic } from "./validate";
+export { validateInputs } from "./validate_inputs";

package/src/parser/parser.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+import yaml from "yaml";
+import type { Workflow } from "../model/index";
+
+export function parseWorkflow(yamlContent: string): Workflow {
+  const parsed = yaml.parse(yamlContent) as Workflow;
+  return parsed;
+}
+
+export async function parseWorkflowFile(filePath: string): Promise<Workflow> {
+  const content = await readFile(filePath, "utf-8");
+  return parseWorkflow(content);
+}