Builder API reference

The TypeScript DSL exported by @diagc/core. Every method returns something chainable, and toJSON() validates.

Source of truth: packages/core/src/builder/, with each notation's builder in packages/core/src/notations/<notation>/builder.ts and the activity builder in packages/core/src/activity/builder.ts.

import { model } from '@diagc/core';

model(id, opts?) → ModelBuilder

m.node(id, opts?) → NodeRef

Declares an entity and returns a handle for containment and relations.

Undefined options are pruned, so the emitted JSON has no key: undefined noise.

m.table(id, opts) → NodeRef

Shorthand for m.node(id, { type: 'db-table', ...opts }). columns is required.

const users = m.table('users', {
  columns: [
    { name: 'id', type: 'uuid', pk: true },
    { name: 'email', type: 'text' },
  ],
});

ref.contains(...children, opts?) → ref

Nests nodes. Accepts any number of NodeRefs, optionally followed by an options object.

platform.contains(comms, identity, billing);
k8s.contains(mail, push, { plane: 'infra' });

Duplicate parent/child/plane triples are ignored, so calling it twice is safe. A node may be contained by several parents — containment is a DAG.

Omitting plane does not mean "every plane". An untagged edge belongs to the model's default plane — whichever you declared first. In a diagram with several planes, tag containment explicitly, or reordering your m.plane(...) calls changes what the diagram means. See Use planes and layers.

m.relate(from, to, opts) → m

Relation ids are generated as from->to#n, with n counting per ordered pair — so two relations between the same nodes never collide. Pass id to name one explicitly instead.

m.fk(from, fromColumn, to, toColumn?, opts?) → m

A kind: 'fk' relation between two tables. toColumn defaults to the target's single primary-key column.

m.fk(orders, 'user_id', users);

Throws if toColumn is omitted and the target has zero or several primary-key columns. Declare the target table, with its PK, before calling.

It does not set fk: true on the source column — that flag only prints the FK marker, so set it on the column yourself. See Draw an ER diagram.

m.layer(id, opts?) → m

m.plane(id, opts?) → m

The first plane declared is the default and owns untagged containment.

m.gitGraph(opts?) → GitGraphBuilder

Declares the model a git branching diagram: a plane with the git-graph notation that must be the first plane declared (it owns the lanes' containment). Throws if a plane already exists or if called twice.

g.branch(id, opts?) → BranchRef

A lane. Lanes are drawn top to bottom in declaration order. BranchRef is a NodeRef (type branch).

branch.commit(tag?) / branch.commit(opts) → CommitRef

A commit on the lane, linked from the lane's previous commit — or, with from, the first commit of a new run branched off a commit on another lane. CommitRef is a NodeRef (type commit) with a branch field.

branch.merge(src, opts?) → CommitRef

A commit on the lane that absorbs src (a commit on another lane): a merge link from src, plus the usual link from the lane's previous commit. Same options as commit minus from.

g.stage(id, opts) → NodeRef

A named frame across every lane, covering the columns from from's to to's (inclusive, either way round) — a phase of the history. A node of type git-stage with its span in metadata; declare it after the commits it names.

m.activity(id, opts?) → ActivityBuilder

Declares an activity frame: a UML swimlane flow. Repeatable — each call is one frame, and frames are ordinary containers on whatever plane the model uses (no notation, no plane creation), so several can share a canvas. ActivityBuilder is the frame's NodeRef (type activity-frame).

act.lane(id, opts?) → LaneRef

A lane. Lanes are drawn top to bottom in declaration order. LaneRef is a NodeRef (type activity-lane).

lane.region(id?, name?) → RegionRef

An interruptible region: a dashed sub-area nested in the lane, hosting the same element helpers below. RegionRef is a NodeRef (type activity-region). id defaults to ${lane}-region, ${lane}-region-2, ….

Element helpers (LaneRef and RegionRef)

Both extend ActivityScope, so a lane and a region expose the same leaf-creating methods; every helper contains the new node in the scope it's called on and returns a plain NodeRef.

action, object, send and receive take opts: { color?: string }.

act.flow(from, to, label?) → act

A kind: 'control' relation — the ordinary solid arrow between two elements. label is a plain relation label; a guard is just a label like [order accepted].

act.objectFlow(from, to, label?) → act

A kind: 'object-flow' relation — dashed, for data (an object) passing between actions.

act.interrupt(from, to, label?) → act

A kind: 'interrupt' relation — a zigzag jog at the midpoint, for a signal that interrupts a region.

act.noteLink(note, target) → act

A kind: 'note-link' relation from a note to what it annotates — dashed, no arrowhead.

const m = model('flow');
const act = m.activity('actors', { name: 'Actors' });
const orders = act.lane('orders', { name: 'Orders' });
const start = orders.start();
const submit = orders.action('submit', 'Submit order');
const note = orders.note('n1', 'Validated client-side first');
act.flow(start, submit).noteLink(note, submit);

m.secondOrder(opts?) → SecondOrderBuilder

Declares the model a second-order thinking diagram: a consequence tree read off ordinary nodes and a leads-to relation. Throws if called twice. With no plane, the notation is model-wide (nothing about it needs a plane — the notation is flat); name a plane to keep it beside other views of the same model.

ConsequenceRef (returned by both decision and then) extends NodeRef, so it composes with the rest of the builder (relate, layer, contains).

const m = model('splitting-the-monolith');
const so = m.secondOrder();
const split = so.decision('split', 'Split the monolith');
const deploys = split.then('deploys', 'Teams deploy independently', { valence: '+' });
const oncall = split.then('oncall-risk', 'More on-call load', { valence: '-' });
deploys.leadsTo(oncall);

m.fishbone(id, name?, opts?) → FishboneBuilder

Declares the model a fishbone (Ishikawa) diagram: the effect at the head, cause categories as bones, causes and sub-causes hung on them. Throws if called twice ('fishbone() already declared'). With no plane, the notation is model-wide; name a plane to keep it beside other views of the same model — its name defaults to Causes.

FishboneOpts { description?: string; color?: string } — the same shape at every level.

The three presets, in bone order:

const m = model('checkout-outage');
const fb = m.fishbone('outage', 'Checkout outage on release day');
const { people, process } = fb.categories('Software');
people!.cause('on-call', 'On-call engineer new to checkout');
process!.cause('review', 'Migration merged without review').cause('single-approver', 'One approver for the whole repo');

m.threatModel(opts?) → ThreatModelBuilder

Declares a threat model: a STRIDE data-flow diagram of external entities, processes, data stores, flows and trust boundaries. Throws if called twice ('threatModel() already declared'). With no plane, the notation is model-wide; name a plane to threat-model an existing architecture beside its other views — that plane then holds its own boundary containment over the same nodes.

opts on the four element helpers is m.node's options minus type and name. Each hands back a plain NodeRef, so contains, relate, layer and the rest of the builder compose with them unchanged.

FlowRef { readonly id: string; threat(opts) } — the relation's id, and the same threat() a NodeRef has.

const m = model('checkout');
const tm = m.threatModel();
const customer = tm.entity('customer', 'Customer');
const web = tm.process('web', 'Web app');
tm.boundary('edge', 'Internet-facing').contains(web);
tm.flow(customer, web, 'HTTPS: cart, card details').threat({ category: 'S', title: 'Credential stuffing on login', severity: 'high' });

ref.threat(opts) → ref

Appends one STRIDE finding to a node or a flow. On every NodeRef, not just the four DFD ones, and on every FlowRef — threats are a generic field, so an existing C4 or ER diagram can be annotated where it stands.

Chainable, so a second finding on the same element is another .threat(...). See Model reference and Draw a threat model.

ref.comment(text, opts?) → ref

A remark on the element, shown in its bubble. On every NodeRef and every FlowRef — the same generic-field pattern as ref.threat().

Chainable, so a second remark is another .comment(...). A plain relation with no FlowRef (an m.relate() call on its own) takes comments through RelateOpts.comments instead, or the public m.addComment({ relation: id }, text, opts). See Model reference.

ref.link(label, url) → ref

A resource this node points at — a ticket, a design doc — listed in its bubble under the comments. NodeRef only; a relation's resources go in a comment. See Link, which distinguishes this from the node's single navigation target.

m.plan(id?, opts?) → PlanBuilder

Declares a plan (schedule) plane — always a plane, id plan by default, name Plan — with notation: 'plan'. Throws if called twice ('plan() already declared'). It need not be the first plane: add it to an existing model and schedule that model's nodes inside its zones. Every node the plan builder creates is scoped to the plan plane (plane: <id>), so bars never appear on the other planes; nodes you contains() stay shared.

A ZoneBuilder is a NodeRef, so .comment(), .link() and .threat() chain on it.

const m = model('launch');
const plan = m.plan();
const alice = plan.person('alice', 'Alice Ng');
plan.zone('build', { name: 'Build', start: '2026-01-26', end: '2026-03-06' })
  .owner(alice)
  .zone('api', { name: 'API', start: '2026-01-26', end: '2026-02-13' });

m.legend(opts?) → m

Opt this diagram into an on-canvas key. Calling it at all is the switch — a diagram that never does has no legend in its image, and on the canvas only the hidden, on-demand one that wordless shapes get. A bare m.legend() derives every row.

m.legend({ items: [{ label: 'Fire-and-forget', kind: 'flow' }] });

Calling it twice replaces the config. See Add a legend and DiagramLegend.

m.typeColors(map) → m

A colour convention for the whole diagram: a default accent colour per node type, with * as the fallback for every type without an entry.

m.typeColors({ 'c4-person': '#c62828', 'c4-container-spa': '#f9a825', '*': '#1565c0' });

This is the only way to colour nodes the diagram did not author — an umbrella that composes a dozen includes cannot reach into the grafted nodes, but it can say what a c4-container looks like here. Precedence, highest first: the node's own color, the entry for its type, *. An untyped node with no * entry keeps the registry look.

Successive calls merge (last wins per key). typeColors is presentation, so it does NOT travel through include: the host's convention is kept and every child's is dropped — the diagram you are looking at owns the look.

m.layerRules(rules) → m

Put relations that carry no layer of their own onto layers by class. Each rule names a kind and/or a color (matched against style.color) and the layer to assign; every field a rule names must match; first match wins.

m.layer('http', { name: 'HTTP', tint: '#ef6c00' });
m.layer('sql', { name: 'SQL', tint: '#2e7d32' });
m.layerRules([
  { color: '#ef6c00', layer: 'http' },
  { kind: 'sql', layer: 'sql' },
  { kind: 'fk', layer: 'sql' },
]);

This is the one way a composed diagram can layer relations an include brought in: the umbrella cannot edit grafted relations, but it can say "everything orange is HTTP here". A relation's own layer always beats the rules; a relation no rule matches stays on the base sheet. Combine with a plane's layers presets and baseRelations: false to draw exactly one class.

Successive calls append. Like typeColors, rules are presentation and do NOT travel through include: the host's are kept, every child's dropped. A rule naming an undeclared layer fails validation (unknown-layer).

m.notation(id) → m

Pin the whole diagram's visual language — the model-level fallback a plane's own notation overrides (see m.plane). The one way to opt a planeless diagram into a built-in look without declaring a plane purely to carry it.

m.notation('c4');

id must be one of BUILTIN_NOTATIONS; an unknown id fails validation with unknown-notation, same as an unknown plane.notation. Calling it twice replaces the value.

m.style(id) → m

Pin the model-level renderer style preset (see Model reference) — the one way to make a diagram always render in a preset like hand-drawn, rather than following whatever the viewer's own header picker is set to.

m.style('hand-drawn');

An unknown preset id is legal — the renderer falls back to the app-level preference. Calling it twice replaces the value.

m.toJSON() → DiagramModel

Validates and returns the model. Throws DiagramValidationError carrying the full issue list if anything is wrong.

You rarely call this — export default m and the compiler calls it for you.

Gotchas

• m.relate takes NodeRefs, not ids. Keep the handles that m.node returns.
• m.node is not idempotent. Calling it twice with the same id creates two nodes and fails validation with duplicate-node.
• A trailing plain object in contains is always read as options, never as a child. That is only ambiguous if you try to pass something that is not a NodeRef.
• description does not render on the canvas. Put anything the reader must see in name.

See also

• Author diagrams in TypeScript — worked examples.
• Model reference — the JSON this produces.