GroupBuilder

GroupBuilder is the fluent interface returned by topology.createGroup(...). It provides methods for adding nodes, controlling layout, and nesting sub-groups.

You never instantiate GroupBuilder directly — you always get one from createGroup.

const group = topology.createGroup('my-group', { label: 'My Group' });
// group is a GroupBuilder instance

All methods return this (the same GroupBuilder), enabling method chaining.

addProcess

Adds a node to the group.

group.addProcess(config: ProcessConfig): GroupBuilder

ProcessConfig

Property	Type	Default	Description
`id`	`string`	—	Required. Unique node identifier across the entire topology
`label`	`string`	—	Required. Display name
`state`	`'running' \| 'stopped' \| 'error' \| 'warning'`	`'running'`	Visual state indicator dot
`shape`	`string`	`'default'`	Node shape. See Node Types & Shapes
`layer`	`string`	—	Layer name for visibility toggling
`replicas`	`number`	—	Creates N nodes with IDs `id-1` … `id-N` automatically
`shardId`	`string`	—	Shard identifier badge (e.g. `'shard-0'`)
`shardRole`	`'primary' \| 'replica' \| 'arbiter'`	—	Shard role badge
`external`	`boolean`	`false`	Orange border styling for external dependencies

Usage

group
  .addProcess({ id: 'api',   label: 'API Server',  state: 'running' })
  .addProcess({ id: 'cache', label: 'Redis',        shape: 'cylinder', state: 'running' })
  .addProcess({ id: 'db',    label: 'PostgreSQL',   shape: 'cylinder', state: 'running' });

Replica shorthand

Instead of calling addProcess three times for three identical pods:

// Long form
group
  .addProcess({ id: 'api-1', label: 'API Pod 1', state: 'running' })
  .addProcess({ id: 'api-2', label: 'API Pod 2', state: 'running' })
  .addProcess({ id: 'api-3', label: 'API Pod 3', state: 'running' });
 
// Shorthand — equivalent result
group.addProcess({ id: 'api', label: 'API Pod', state: 'running', replicas: 3 });

The shorthand creates nodes with IDs api-1, api-2, api-3 automatically.

newRow

Inserts a row break in the group’s grid layout. Subsequent nodes are placed on the next row.

group.newRow(): GroupBuilder

By default, nodes are placed left-to-right in a single row. Call newRow() to start a new row:

group
  .addProcess({ id: 'master', label: 'Master', state: 'running' })
  .newRow()
  .addProcess({ id: 'slave-1', label: 'Slave 1', state: 'running' })
  .addProcess({ id: 'slave-2', label: 'Slave 2', state: 'running' })
  .autoResize();

autoResize

Recalculates the group’s width and height to fit all nodes with proper padding.

group.autoResize(): GroupBuilder

⚠️

Always call autoResize() after adding all nodes to a group. Without it, the group rectangle may be too small and nodes will overflow or overlap visually.

group
  .addProcess({ id: 'a', label: 'Service A' })
  .addProcess({ id: 'b', label: 'Service B' })
  .addProcess({ id: 'c', label: 'Service C' })
  .autoResize(); // must be last

addGroup

Adds a nested sub-group inside the current group.

group.addGroup(id: string, config: GroupConfig): GroupBuilder

Returns the parent GroupBuilder, not the child. To configure the child group’s nodes, use a separate variable:

const outerGroup = topology.createGroup('cluster', { label: 'Cluster' });
 
const innerGroup = topology.createGroup('shard-0', { label: 'Shard 0' });
innerGroup
  .addProcess({ id: 'primary', label: 'Primary', shardRole: 'primary' })
  .addProcess({ id: 'replica', label: 'Replica', shardRole: 'replica' })
  .autoResize();
 
outerGroup.addGroup('shard-0', { label: 'Shard 0' });
outerGroup.autoResize();

addCloud

Adds a cloud-shape external service placeholder inside the group.

group.addCloud(config: ProcessConfig): GroupBuilder

Equivalent to addProcess({ ...config, shape: 'cloud', external: true }) — a convenience shorthand for representing external cloud services.

group.addCloud({ id: 's3', label: 'Amazon S3', state: 'running' });

skip

Inserts an empty cell in the grid layout — equivalent to a spacer. Useful for aligning nodes in a grid when some positions should be empty.

group.skip(): GroupBuilder

group
  .addProcess({ id: 'a', label: 'Node A' })
  .skip()                                    // empty cell
  .addProcess({ id: 'b', label: 'Node B' }) // placed in column 3
  .autoResize();

Chaining example

chaining-example.ts

const topology = new TopologyBuilder(true);
 
topology.createGroup('kafka-cluster', {
  label: 'Kafka Cluster',
  color: '#f59e0b',
})
  .addProcess({ id: 'broker-1', label: 'Broker 1', state: 'running', shardId: 'p0', shardRole: 'primary' })
  .addProcess({ id: 'broker-2', label: 'Broker 2', state: 'running', shardId: 'p0', shardRole: 'replica' })
  .addProcess({ id: 'broker-3', label: 'Broker 3', state: 'running', shardId: 'p1', shardRole: 'primary' })
  .newRow()
  .addProcess({ id: 'zk-1', label: 'ZooKeeper 1', state: 'running' })
  .addProcess({ id: 'zk-2', label: 'ZooKeeper 2', state: 'running' })
  .addProcess({ id: 'zk-3', label: 'ZooKeeper 3', state: 'running' })
  .autoResize();
 
await topology.apply();
return null;

TopologyBuilder FlowBuilder