@orcish/dag-mermaid

A Mermaid flowchart renderer for @orcish/dag. Pure DagRaw → string — no DOM, no runtime, no other dependencies. Pipe the output to any Mermaid integration (CLI, IDE preview, mermaid.live, the mermaid browser package, etc.).

Install

pnpm add @orcish/dag @orcish/dag-mermaid

Usage

import { Dag } from '@orcish/dag';
import { renderMermaid } from '@orcish/dag-mermaid';

const dag = new Dag({ idOf: n => n.id })
  .addNode({ id: 'a', label: 'Alpha', kind: 'source' })
  .addNode({ id: 'b', label: 'Beta', kind: 'work' })
  .addNode({ id: 'c', label: 'Gamma', kind: 'sink' })
  .addEdge('a', 'b')
  .addEdge('b', 'c');

const out = renderMermaid(dag.toRaw(), {
  direction: 'LR',
  label: n => n.label,
});

console.log(out);
// flowchart LR
//   a["Alpha"]
//   b["Beta"]
//   c["Gamma"]
//   a --> b
//   b --> c

dag.toRaw() is @orcish/dag's interop boundary — it returns the immutable DagRaw snapshot the renderer consumes. If you already work with the pure-function API, you can pass your DagRaw directly.

Options

All options are optional and operate on the user's own node type N — the package has no opinion about what labels, classes, or shapes mean.

| Option | Type | Default | | ----------- | ------------------------------------------------------------------------- | -------------- | | direction | 'TB' \| 'TD' \| 'BT' \| 'LR' \| 'RL' | 'TD' | | label | (node, id) => string | String(id) | | shape | (node, id) => 'rect' \| 'rounded' \| 'stadium' \| 'circle' \| 'diamond' | 'rect' | | classOf | (node, id) => string \| undefined | no class | | classDefs | Record<string, string> — Mermaid style strings per class | none | | edgeLabel | (from, to, fromId, toId) => string \| undefined | no edge labels | | indent | string — indentation per non-header line | ' ' |

Only classDef entries referenced by at least one node are emitted, and class assignments are grouped per class for compact output.

Output guarantees

• Deterministic. Same DagRaw + same options → same string. Node lines follow state.nodes insertion order; edges follow state.out insertion order.
• Mermaid-safe ids. Keys matching ^[A-Za-z_][A-Za-z0-9_]*$ pass through unchanged; anything else (and any collisions) becomes a synthetic n<i>.
• Escaped labels. In both node and edge labels, " becomes #quot; and \n becomes <br/>; edge labels additionally escape | (the Mermaid label delimiter) as #124;.

Quickstart example

A runnable example covering every option lives at examples/quickstart.mjs. After installing and building the workspace:

node examples/quickstart.mjs               # prints the Mermaid source
node examples/quickstart.mjs | pbcopy      # macOS — paste into mermaid.live