Flows Cheatsheet

One-screen lookup. Cite: Flows, Continue Parent, Fail Parent, Get Flow Tree.

Mental model

Tree of jobs. Parent in waiting-children → runs only after all children complete.

FlowProducer — the only entry point

import { FlowProducer } from 'bullmq';
const flow = new FlowProducer({ connection });

const tree = await flow.add({
  name: 'finalize', queueName: 'pipeline', data: {},
  children: [
    { name: 'resize', data: { size: 200 }, queueName: 'images', opts: { attempts: 3 } },
    { name: 'resize', data: { size: 800 }, queueName: 'images' },
  ],
});   // atomic: all jobs or none

Node field	Notes
`name` / `queueName`	Required. Each node picks its own queue → cross-queue deps.
`data`	Payload.
`opts`	`JobsOptions` minus `repeat`/`debounce`/`deduplication`/`parent`.
`children`	Array of child nodes (arbitrary depth).
`prefix`	Redis key prefix per node.

No repeat on flow nodes. Want a recurring pipeline? Schedule the producer via a Job Scheduler (Lesson 3).

Failure policies — pick ONE per fallible child

Default = orphan. A child that fails never "completes," so the parent hangs in waiting-children forever. Always set a policy on any child that can fail.

Child opt	Behavior	Use
`continueParentOnFailure: true`	Parent proceeds immediately; cancel siblings with `job.removeUnprocessedChildren()`; inspect `job.getFailedChildrenValues()`.	Best-effort — partial results OK.
`failParentOnFailure: true`	Parent → `failed` at once. Selective + recursive up the tree (if ancestors also set it).	Fail-fast — mandatory step.

Inspection

const sub = await flow.getFlow({ id, queueName, depth: 1, maxChildren: 50 });
const vals = await job.getChildrenValues();      // { childKey: returnvalue }
const cnt  = await job.getDependenciesCount();  // processed/unprocessed
const pk   = job.parentKey;                     // parent's fq key (or undefined)

Removal cascades

Action	Effect
Remove parent	All children removed too.
Remove last child	Parent completes (no worker runs).
Any job locked	Nothing removed; exception thrown.

Mental model — when to reach for flows

Shape	Use
Fan-out / fan-in	N parallel children → 1 aggregate parent.
Multi-stage pipeline	resize → upload → notify as a tree.
Cross-queue work	CPU-bound children on one queue, light parent on another.