@crashbytes/diagrams

Programmatic text-to-diagram generation with a fluent TypeScript API. Renders to Mermaid markdown. Zero dependencies.

Installation

npm install @crashbytes/diagrams

Features

• Fluent, chainable TypeScript API
• Flowchart diagrams with nodes, edges, subgraphs, and styling
• Sequence diagrams with participants, messages, loops, and alt/else blocks
• Renders to Mermaid-compatible markdown
• Full type safety with TypeScript strict mode
• Zero runtime dependencies
• CJS and ESM support

Usage

Flowchart

import { Flowchart } from '@crashbytes/diagrams'

const diagram = Flowchart.create('TB')
  .node('A', 'Start', 'stadium')
  .node('B', 'Process', 'box')
  .node('C', 'Decision', 'diamond')
  .node('D', 'End', 'stadium')
  .edge('A', 'B')
  .edge('B', 'C')
  .edge('C', 'D', '-->', 'yes')
  .edge('C', 'B', '-..->', 'no')
  .render()

console.log(diagram)

Output:

graph TB
    A(["Start"])
    B["Process"]
    C{"Decision"}
    D(["End"])
    A --> B
    B --> C
    C -->|"yes"| D
    C -..->|"no"| B

Node Shapes

| Shape | Syntax | Example | |------------|-------------|------------------| | box | [text] | Rectangle | | round | (text) | Rounded | | stadium | ([text]) | Stadium | | cylinder | [(text)] | Cylinder | | circle | ((text)) | Circle | | diamond | {text} | Diamond | | hexagon | {{text}} | Hexagon |

Arrow Types

| Type | Description | |---------|-------------------| | --> | Solid arrow | | --- | Solid line | | -..-> | Dotted arrow | | ==> | Thick arrow | | --o | Circle end | | --x | Cross end |

Styled Nodes

Flowchart.create()
  .styledNode('A', 'Important', 'box', { fill: '#f00', stroke: '#000', color: '#fff' })
  .render()

Subgraphs

Flowchart.create()
  .node('A', 'Service A')
  .node('B', 'Service B')
  .subgraph('backend', 'Backend Services', ['A', 'B'])
  .render()

Markdown Output

const markdown = Flowchart.create()
  .node('A', 'Hello')
  .toMarkdown()

// Returns:
// ```mermaid
// graph TB
//     A["Hello"]
// ```

Sequence Diagram

import { Sequence } from '@crashbytes/diagrams'

const diagram = Sequence.create('Authentication Flow')
  .participant('C', 'Client')
  .participant('S', 'Server')
  .participant('DB', 'Database')
  .message('C', 'S', 'POST /login')
  .activate('S')
  .message('S', 'DB', 'Query user')
  .reply('DB', 'S', 'User data')
  .alt('Valid credentials', (s) => {
    s.reply('S', 'C', '200 OK + token')
    s.elseBlock('Invalid', (s2) => {
      s2.reply('S', 'C', '401 Unauthorized')
    })
  })
  .deactivate('S')
  .render()

Output:

sequenceDiagram
    title Authentication Flow
    participant C as Client
    participant S as Server
    participant DB as Database
    C->>S: POST /login
    activate S
    S->>DB: Query user
    DB-->>S: User data
    alt Valid credentials
    S-->>C: 200 OK + token
    else Invalid
    S-->>C: 401 Unauthorized
    end
    deactivate S

Participants and Actors

Sequence.create()
  .actor('U', 'User')        // Stick figure
  .participant('S', 'System') // Box

Loops

Sequence.create()
  .participant('A')
  .participant('B')
  .loop('Every 5s', (s) => {
    s.message('A', 'B', 'heartbeat')
    s.reply('B', 'A', 'ack')
  })

Notes

Sequence.create()
  .participant('A')
  .note('over', 'A', 'This is important')
  .note('right of', 'A', 'Side note')

API Reference

Flowchart

| Method | Description | |--------|-------------| | Flowchart.create(direction?) | Create a new flowchart ('TB', 'BT', 'LR', 'RL') | | .node(id, label?, shape?) | Add a node | | .styledNode(id, label, shape, style) | Add a styled node | | .edge(from, to, arrow?, label?) | Add an edge | | .subgraph(id, label, nodes) | Add a subgraph | | .render() | Render as Mermaid string | | .toMarkdown() | Render wrapped in markdown code fence |

Sequence

| Method | Description | |--------|-------------| | Sequence.create(title?) | Create a new sequence diagram | | .participant(id, label?) | Add a participant | | .actor(id, label?) | Add an actor | | .message(from, to, text, arrow?) | Add a message | | .reply(from, to, text) | Add a reply (dashed async arrow) | | .note(position, participant, text) | Add a note | | .activate(participant) | Activate a participant | | .deactivate(participant) | Deactivate a participant | | .loop(label, buildFn) | Add a loop block | | .alt(label, buildFn) | Add an alt block | | .elseBlock(label, buildFn) | Add an else branch (inside alt) | | .render() | Render as Mermaid string | | .toMarkdown() | Render wrapped in markdown code fence |

License

MIT - see LICENSE