Workflows

Orchestrate multi-step DAGs in Node.js with the FlexiQ workflow builder.

Orchestrate multi-step DAGs (directed acyclic graphs — steps with dependencies and no cycles) where each step is a registered task and after declares its dependencies. The Rust core schedules steps in topological order; a worker advances the run as each step settles.

const handle = queue.workflows
  .define("etl")
  .step("extract", "extractTask", { args: ["s3://bucket/in"] })
  .step("transform", "transformTask", { after: "extract" })
  .step("load", "loadTask", { after: "transform", maxRetries: 5 })
  .submit();

queue.runWorker();

const run = await handle.wait();  // resolves when terminal
console.log(run.state);           // "completed" | "failed" | ...
handle.nodes();                   // per-step status snapshot

Requires the addon built with the workflows cargo feature (enabled by pnpm build:native).

Workflows need a running worker

.submit() enqueues the step jobs; they only execute while a worker (a process that claims and executes queued jobs) is consuming the queue. Start one first — queue.runWorker(), as above — otherwise handle.wait() blocks until it times out.

Coming from BullMQ?

BullMQ's closest equivalent is FlowProducer — .add({ name, queueName, data, children: [...] }) builds a parent/child job tree: one parent, many children, no joins. flexiq's workflow builder is a general DAG: a step's after can list multiple predecessors, so two branches can merge back into one step (a join FlowProducer can't express). Conditions, gates, sagas, and caching are also flexiq-only — there's no BullMQ equivalent for those.

Building WorkflowsEvery step option, the rules build() enforces, and the node status lifecycle.Fan-out / Fan-inSplit a step's result into parallel children and collect results.ConditionsRun a step only on success, on failure, or always.Approval GatesPause a run until a human or external system approves or rejects.Sub-WorkflowsCompose workflow runs hierarchically — delegate a step to a child workflow.Saga CompensationAutomatically roll back completed steps in reverse order when a run fails.Canvas Primitiveschain / group / chord shorthands for common DAG shapes.Incremental RunsCache a step's result and reuse it across runs with a dirty set.Analysis & VisualizationIntrospect a run's DAG — dependencies, levels, critical path, stats.