type-mermaid

A library for writing Mermaid code in TypeScript. With this library, you can easily write Mermaid code using TypeScript and IDE IntelliSense.

Currently, only sequence diagrams are supported.

Try it out for yourself!

Installing

For the latest stable version, run:

1# NPM
2npm i type-mermaid
3
4# or Yarn
5yarn add type-mermaid
6

Requirements

• Typescript >=4.9

Be careful with the TypeScript version because it uses the satisfies operator.

Usage

Simple Mermaid code output

1import { SequenceDiagram, MemberObject } from 'type-mermaid'
2
3const member = {
4  Alice: 'participant',
5  Bob: 'participant',
6} satisfies MemberObject
7
8const { d, render } = SequenceDiagram<keyof typeof member>(member)
9
10// Morning greetings
11d.Alice.call.Bob.activate('Good morning, Bob!')
12d.Bob.response.Alice.msg('Morning, Alice')
13
14// console output
15console.log(render.toString())

The basic flow is to use a d object (which stands for diagram) to create flow, and then use a render instance to output mermaid code or image.

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Good morning, Bob!
    Bob-->>Alice: Morning, Alice

and Mermaid preview.

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>Bob: Good morning, Bob!
5    Bob-->>Alice: Morning, Alice

SVG output

Using render instance, SVG files can also be output.

1const svgPath = path.join(__dirname, './test.svg')
2render.toSvg(svgPath)

MMD file output

1const mmdPath = path.join(__dirname, './test.mmd')
2render.toMmd(mmdPath)

Options

Options for auto numbering(autonumber) and indentation can be specified as a string. By default, indentation is four spaces.

Example

1import { SequenceDiagram } from '../SequenceDiagram'
2import { MemberObject } from '../SequenceDiagram/types'
3
4import path from 'path'
5
6const member = {
7  Alice: 'participant',
8  Bob: 'participant',
9} satisfies MemberObject
10
11const options = {
12  autoNumber: true,
13  indent: '  ',  //two spaces
14}
15
16const { d, render } = SequenceDiagram<keyof typeof member>(member, options)
17
18// Morning greetings
19d.Alice.call.Bob.activate('Good morning, Bob!')
20d.Bob.response.Alice.msg('Morning, Alice')
21
22console.log(render.toString())
23

Output

sequenceDiagram
  autonumber
  participant Alice
  participant Bob
  Alice->>+Bob: Good morning, Bob!
  Bob-->>Alice: Morning, Alice

by Mermaid

1sequenceDiagram
2  autonumber
3  participant Alice
4  participant Bob
5  Alice->>+Bob: Good morning, Bob!
6  Bob-->>Alice: Morning, Alice

Activation

There are two ways to express Activation.

1. Declare activate first and code the sequence of events in then().

In this case, this code will automatically output without writing deactivate.

Example

1d.Alice.call.Bob.msg('Do you have the documents?')
2d.activate.Bob.then(() => {
3  d.Bob.call.Bob.msg('Thinking...')
4  d.Bob.response.Alice.msg('I have it!')
5})

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Do you have the documents?
    activate Bob
    Bob->>Bob: Thinking...
    Bob-->>Alice: I have it!
    deactivate Bob

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>Bob: Do you have the documents?
5    activate Bob
6    Bob->>Bob: Thinking...
7    Bob-->>Alice: I have it!
8    deactivate Bob

2. Send a message and activate at the same time.

In this case, use the activate() to send a message. Then you must always use the deactivate() to terminate the activation.

Example

1d.Alice.call.Bob.activate('Do you have the documents?')
2d.Bob.call.Bob.msg('Thinking...')
3d.Bob.response.Alice.deactivate("I've got it!")

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>+Bob: Do you have the documents?
    Bob->>Bob: Thinking...
    Bob-->>-Alice: I've got it!

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>+Bob: Do you have the documents?
5    Bob->>Bob: Thinking...
6    Bob-->>-Alice: I've got it!

Notes

It is possible to add notes to a sequence diagram.

Example

1d.note.rightOf.Alice.msg('Text in note')

Output

sequenceDiagram
    participant Alice
    Note right of Alice: Text in note

1sequenceDiagram
2    participant Alice
3    Note right of Alice: Text in note

To create notes spanning two participants.

d.Alice.call.Bob.msg('Hello Bob, how are you?')
d.note.over.Alice.Bob.msg('A typical interaction')

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Note over Alice,Bob: A typical interaction

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>Bob: Hello Bob, how are you?
5    Note over Alice,Bob: A typical interaction

Loops

It is possible to express loops in a sequence diagram.

Example

1d.Alice.call.Bob.msg('Hello Bob, how are you?')
2d.loop.then('Every minute', () => {
3  d.Bob.response.Alice.msg('Great!')
4})

In then(), enter a label and a sequence to repeat. If no label is needed, the first argument will be an empty character ('').

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    loop Every minute
        Bob-->>Alice: Great!
    end

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>Bob: Hello Bob, how are you?
5    loop Every minute
6        Bob-->>Alice: Great!
7    end

Alt and Opt

It is possible to express alternative paths in a sequence diagram.

Example

1// Alt
2d.Alice.call.Bob.msg('Hello Bob, how are you?')
3d.alt.then('is sick', () => {
4  d.Bob.response.Alice.msg('Not so good :(')
5  d.else.then('is well', () => {
6    d.Bob.response.Alice.msg('Feeling fresh like a daisy')
7  })
8})
9
10// Opt
11d.opt.then('Extra response', () => {
12  d.Bob.response.Alice.msg('Thanks for asking')
13})

Output

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    alt is sick
        Bob-->>Alice: Not so good :(
    else is well
        Bob-->>Alice: Feeling fresh like a daisy
    end
    opt Extra response
        Bob-->>Alice: Thanks for asking
    end

1sequenceDiagram
2    participant Alice
3    participant Bob
4    Alice->>Bob: Hello Bob, how are you?
5    alt is sick
6        Bob-->>Alice: Not so good :(
7    else is well
8        Bob-->>Alice: Feeling fresh like a daisy
9    end
10    opt Extra response
11        Bob-->>Alice: Thanks for asking
12    end

Parallel

It is possible to show actions that are happening in parallel.

Example

1// add John
2const member = {
3  Alice: 'participant',
4  Bob: 'participant',
5  John: 'participant',
6} satisfies MemberObject
7
8const { d, render } = SequenceDiagram<keyof typeof member>(member)
9
10d.par.then('Alice to Bob', () => {
11  d.Alice.call.Bob.msg('Hello guys!')
12  d.and.then('Alice to John', () => {
13    d.Alice.call.John.msg('Hello guys!')
14  })
15})
16d.Bob.response.Alice.msg('Hi Alice!')
17d.John.response.Alice.msg('Hi Alice!')

and.then() should be used within a callback function for then()'s second argument.

Multiple and.then() can be used.

Output

sequenceDiagram
    participant Alice
    participant Bob
    participant John
    par Alice to Bob
        Alice->>Bob: Hello guys!
    and Alice to John
        Alice->>John: Hello guys!
    end
    Bob-->>Alice: Hi Alice!
    John-->>Alice: Hi Alice!

1sequenceDiagram
2    participant Alice
3    participant Bob
4    participant John
5    par Alice to Bob
6        Alice->>Bob: Hello guys!
7    and Alice to John
8        Alice->>John: Hello guys!
9    end
10    Bob-->>Alice: Hi Alice!
11    John-->>Alice: Hi Alice!

It is also possible to nest parallel blocks.

Example

1const member = {
2  Alice: 'participant',
3  Bob: 'participant',
4  John: 'participant',
5  Charlie: 'participant',
6  Diana: 'participant',
7} satisfies MemberObject
8
9const { d, render } = SequenceDiagram<keyof typeof member>(member)
10
11d.par.then('Alice to Bob', () => {
12  d.Alice.call.Bob.msg('Go help John')
13  d.and.then('Alice to John', () => {
14    d.Alice.call.John.msg('I want this done today')
15    d.par.then('John to Charlie', () => {
16      d.John.call.Charlie.msg('Can we do this today?')
17      d.and.then('John to Diana', () => {
18        d.John.call.Diana.msg('Can you help us today?')
19      })
20    })
21  })
22})

All participants must be defined by member. Otherwise, an error will occur.

(Because this is TypeScript!).

Output

sequenceDiagram
    participant Alice
    participant Bob
    participant John
    participant Charlie
    participant Diana
    par Alice to Bob
        Alice->>Bob: Go help John
    and Alice to John
        Alice->>John: I want this done today
        par John to Charlie
            John->>Charlie: Can we do this today?
        and John to Diana
            John->>Diana: Can you help us today?
        end
    end

1sequenceDiagram
2    participant Alice
3    participant Bob
4    participant John
5    participant Charlie
6    participant Diana
7    par Alice to Bob
8        Alice->>Bob: Go help John
9    and Alice to John
10        Alice->>John: I want this done today
11        par John to Charlie
12            John->>Charlie: Can we do this today?
13        and John to Diana
14            John->>Diana: Can you help us today?
15        end
16    end