Merge pull request #192 from neuroglia-io/feat-mermaid-diagram

feat: add graph and MermaidJS flowchart

Author: ricardozanini

README.md

@@ -1,5 +1,26 @@
 ![Node CI](https://github.com/serverlessworkflow/sdk-typescript/workflows/Node%20CI/badge.svg) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/serverlessworkflow/sdk-typescript)
 
+- [Serverless Workflow Specification - TypeScript SDK](#serverless-workflow-specification---typescript-sdk)
+  - [Status](#status)
+  - [SDK Structure](#sdk-structure)
+    - [Types and Interfaces](#types-and-interfaces)
+    - [Classes](#classes)
+    - [Fluent Builders](#fluent-builders)
+    - [Validation Function](#validation-function)
+    - [Other tools](#other-tools)
+  - [Getting Started](#getting-started)
+    - [Installation](#installation)
+    - [Usage](#usage)
+      - [Create a Workflow Definition from YAML or JSON](#create-a-workflow-definition-from-yaml-or-json)
+      - [Create a Workflow Definition by Casting an Object](#create-a-workflow-definition-by-casting-an-object)
+      - [Create a Workflow Definition Using a Class Constructor](#create-a-workflow-definition-using-a-class-constructor)
+      - [Create a Workflow Definition Using the Builder API](#create-a-workflow-definition-using-the-builder-api)
+      - [Serialize a Workflow Definition to YAML or JSON](#serialize-a-workflow-definition-to-yaml-or-json)
+      - [Validate Workflow Definitions](#validate-workflow-definitions)
+      - [Generate a directed graph](#generate-a-directed-graph)
+      - [Generate a MermaidJS flowchart](#generate-a-mermaidjs-flowchart)
+    - [Building Locally](#building-locally)
+
 # Serverless Workflow Specification - TypeScript SDK
 
 This SDK provides a TypeScript API for working with the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification).
@@ -14,7 +35,7 @@ The npm [`@serverlessworkflow/sdk`](https://www.npmjs.com/package/@serverlesswor
 
 | Latest Releases | Conformance to Spec Version |
 | :---: | :---: |
-| [v1.0.0.\*](https://github.com/serverlessworkflow/sdk-typescript/releases/) | [v1.0.0](https://github.com/serverlessworkflow/specification) |
+| [v1.0.\*](https://github.com/serverlessworkflow/sdk-typescript/releases/) | [v1.0.0](https://github.com/serverlessworkflow/specification) |
 
 > [!WARNING]
 > Previous versions of the SDK were published with a typo in the scope:
@@ -56,6 +77,9 @@ The SDK includes a validation function to check if objects conform to the expect
 
 The `validate` function is directly exported and can be used as `validate('Workflow', workflowObject)`.
 
+### Other Tools
+The SDK also ships tools to build directed graph and MermaidJS flowcharts from a workflow.
+
 ## Getting Started
 
 ### Installation
@@ -86,7 +110,7 @@ do:
     set:
       variable: 'my first workflow'
 `;
-const workflowDefinition = Classes.Workflow.deserialize(text);
+const workflow = Classes.Workflow.deserialize(text);
 ```
 
 #### Create a Workflow Definition by Casting an Object
@@ -96,7 +120,7 @@ You can type-cast an object to match the structure of a workflow definition:
 import { Classes, Specification, validate } from '@serverlessworkflow/sdk';
 
 // Simply cast an object:
-const workflowDefinition = {
+const workflow = {
   document: {
     dsl: '1.0.0',
     name: 'test',
@@ -116,9 +140,9 @@ const workflowDefinition = {
 
 // Validate it
 try {
-  validate('Workflow', workflowDefinition);
+  validate('Workflow', workflow);
   // Serialize it
-  const definitionTxt = Classes.Workflow.serialize(workflowDefinition);
+  const definitionTxt = Classes.Workflow.serialize(workflow);
 }
 catch (ex) {
   // Invalid workflow definition
@@ -132,7 +156,7 @@ You can create a workflow definition by calling a constructor:
 import { Classes, validate } from '@serverlessworkflow/sdk';
 
 // Simply use the constructor
-const workflowDefinition = new Classes.Workflow({
+const workflow = new Classes.Workflow({
   document: {
     dsl: '1.0.0',
     name: 'test',
@@ -149,7 +173,7 @@ const workflowDefinition = new Classes.Workflow({
     },
   */],
 });
-workflowDefinition.do.push({
+workflow.do.push({
   step1: new Classes.SetTask({
     set: {
       variable: 'my first workflow',
@@ -159,9 +183,9 @@ workflowDefinition.do.push({
 
 // Validate it
 try {
-  workflowDefinition.validate();
+  workflow.validate();
   // Serialize it
-  const definitionTxt = workflowDefinition.serialize();
+  const definitionTxt = workflow.serialize();
 }
 catch (ex) {
   // Invalid workflow definition
@@ -174,7 +198,7 @@ You can use the fluent API to build a validated and normalized workflow definiti
 ```typescript
 import { documentBuilder, setTaskBuilder, taskListBuilder, workflowBuilder } from '@serverlessworkflow/sdk';
 
-const workflowDefinition = workflowBuilder(/*workflowDefinitionObject*/)
+const workflow = workflowBuilder(/*workflowObject*/)
   .document(
     documentBuilder()
     .dsl('1.0.0')
@@ -206,12 +230,12 @@ You can serialize a workflow definition either by using its `serialize` method i
 ```typescript
 import { Classes } from '@serverlessworkflow/sdk';
 
-// const workflowDefinition = <Your preferred method>;
-if (workflowDefinition instanceof Classes.Workflow) {
-  const yaml = workflowDefinition.serialize(/*'yaml' | 'json' */);
+// const workflow = <Your preferred method>;
+if (workflow instanceof Classes.Workflow) {
+  const yaml = workflow.serialize(/*'yaml' | 'json' */);
 }
 else {
-  const json = Classes.Workflow.serialize(workflowDefinition, 'json');
+  const json = Classes.Workflow.serialize(workflow, 'json');
 }
 ```
 > [!NOTE]
@@ -223,20 +247,114 @@ Validation can be achieved in two ways: via the `validate` function or the insta
 ```typescript
 import { Classes, validate } from '@serverlessworkflow/sdk';
 
-// const workflowDefinition = <Your preferred method>;
+const workflow = /* <Your preferred method> */;
 try {
-  if (workflowDefinition instanceof Classes.Workflow) {
-    workflowDefinition.validate();
+  if (workflow instanceof Classes.Workflow) {
+    workflow.validate();
   }
   else {
-    validate('Workflow', workflowDefinition);
+    validate('Workflow', workflow);
   }
 }
 catch (ex) {
   // Workflow definition is invalid
 }
 ```
 
+#### Generate a directed graph
+A [directed graph](https://en.wikipedia.org/wiki/Directed_graph) of a workflow can be generated using the `buildGraph` function, or alternatives:
+- Workflow instance `.toGraph();`
+- Static `Classes.Workflow.toGraph(workflow)`
+
+```typescript
+import { buildGraph } from '@serverlessworkflow/sdk';
+
+const workflow = {
+  document: {
+    dsl: '1.0.0',
+    name: 'using-plain-object',
+    version: '1.0.0',
+    namespace: 'default',
+  },
+  do: [
+    {
+      step1: {
+        set: {
+          variable: 'my first workflow',
+        },
+      },
+    },
+  ],
+};
+const graph = buildGraph(workflow);
+// const workflow = new Classes.Workflow({...}); const graph = workflow.toGraph();
+// const graph = Classes.Workflow.toGraph(workflow);
+/*{
+  id: 'root',
+  type: 'root',
+  label: undefined,
+  parent: null,
+  nodes: [...], // length 3 - root entry node, step1 node, root exit node
+  edges: [...], // length 2 - entry to step1, step1 to exit
+  entryNode: {...}, // root entry node
+  exitNode: {...} // root exit node
+}*/
+```
+
+#### Generate a MermaidJS flowchart
+Generating a [MermaidJS](https://mermaid.js.org/) flowchart can be achieved in two ways: using the `convertToMermaidCode`, the legacy `MermaidDiagram` class, or alternatives:
+- Workflow instance `.toMermaidCode();`
+- Static `Classes.Workflow.toMermaidCode(workflow)`
+
+```typescript
+import { convertToMermaidCode, MermaidDiagram } from '@serverlessworkflow/sdk';
+
+const workflow = {
+  document: {
+    dsl: '1.0.0',
+    name: 'using-plain-object',
+    version: '1.0.0',
+    namespace: 'default',
+  },
+  do: [
+    {
+      step1: {
+        set: {
+          variable: 'my first workflow',
+        },
+      },
+    },
+  ],
+};
+const mermaidCode = convertToMermaidCode(workflow) /* or  */;
+// const mermaidCode = new MermaidDiagram(workflow).sourceCode();
+// const workflow = new Classes.Workflow({...}); const mermaidCode = workflow.toMermaidCode();
+// const mermaidCode = Classes.Workflow.toMermaidCode(workflow);
+/*
+flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/step1["step1"]
+    /do/0/step1 --> root-exit-node
+    root-entry-node --> /do/0/step1
+
+
+classDef hidden display: none;
+*/
+```
+
+```mermaid
+flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/step1["step1"]
+    /do/0/step1 --> root-exit-node
+    root-entry-node --> /do/0/step1
+
+
+classDef hidden display: none;
+```
+
 ### Building Locally
 
 To build the project and run tests locally, use the following commands:

examples/browser/mermaid.html

@@ -0,0 +1,131 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Serveless Workflow</title>
+  <base href="/">
+  <meta content="width=device-width, initial-scale=1" name="viewport">
+</head>
+
+<body>
+  <p>YAML or JSON:</p>
+  <textarea id="input" rows="50" cols="100"></textarea>
+  <div id="diagram-container"></div>
+  <pre id="output"></pre>
+  <script src="../../dist/umd/index.umd.js"></script>
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    (async () => {
+      const { Classes, Specification, validate, convertToMermaidCode } = serverWorkflowSdk;
+      const workflowDefinition = {
+  "document": {
+    "dsl": "1.0.0",
+    "namespace": "examples",
+    "name": "accumulate-room-readings",
+    "version": "0.1.0"
+  },
+  "do": [
+    {
+      "consumeReading": {
+        "listen": {
+          "to": {
+            "all": [
+              {
+                "with": {
+                  "source": "https://my.home.com/sensor",
+                  "type": "my.home.sensors.temperature"
+                },
+                "correlate": {
+                  "roomId": {
+                    "from": ".roomid"
+                  }
+                }
+              },
+              {
+                "with": {
+                  "source": "https://my.home.com/sensor",
+                  "type": "my.home.sensors.humidity"
+                },
+                "correlate": {
+                  "roomId": {
+                    "from": ".roomid"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "output": {
+          "as": ".data.reading"
+        }
+      }
+    },
+    {
+      "logReading": {
+        "for": {
+          "each": "reading",
+          "in": ".readings"
+        },
+        "do": [
+          {
+            "callOrderService": {
+              "call": "openapi",
+              "with": {
+                "document": {
+                  "endpoint": "http://myorg.io/ordersservices.json"
+                },
+                "operationId": "logreading"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "generateReport": {
+        "call": "openapi",
+        "with": {
+          "document": {
+            "endpoint": "http://myorg.io/ordersservices.json"
+          },
+          "operationId": "produceReport"
+        }
+      }
+    }
+  ],
+  "timeout": {
+    "after": {
+      "hours": 1
+    }
+  }
+}/* as Specification.Workflow // <-- If you're using TypeScript*/;
+      const diagramContainerEl = document.getElementById('diagram-container');  
+      const inputTextarea = document.getElementById('input');
+      const processWorkflow = async () => {
+        try {
+            const workflow = Classes.Workflow.deserialize(inputTextarea.value);
+            const mermaidCode = convertToMermaidCode(workflow);
+            document.getElementById('output').innerHTML = `--- YAML ---\n${Classes.Workflow.serialize(workflow)}\n\n--- JSON ---\n${Classes.Workflow.serialize(workflow, 'json')}\n\n--- MERMAID ---\n${mermaidCode}`;
+            mermaid.initialize({ startOnLoad: false });
+            const { svg, bindFunctions } = await mermaid.render('sw-diagram', mermaidCode);
+            diagramContainerEl.innerHTML = svg;
+          }
+          catch (ex) {
+            console.error('Invalid workflow', ex);
+          }
+      };
+      let debounceHandle;
+      inputTextarea.addEventListener('keyup', () => {
+        if (debounceHandle) {
+          clearTimeout(debounceHandle);
+        }
+        debounceHandle = setTimeout(processWorkflow, 300);
+      });
+      inputTextarea.value = JSON.stringify(workflowDefinition, null, 4);
+      await processWorkflow();
+    })();
+  </script>
+</body>
+
+</html>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverlessworkflow/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "schemaVersion": "1.0.0",
   "description": "Typescript SDK for Serverless Workflow Specification",
   "main": "umd/index.umd.min.js",

src/lib/generated/classes/workflow.ts

@@ -33,6 +33,8 @@ import { getLifecycleHooks } from '../../lifecycle-hooks';
 import { validate } from '../../validation';
 import { isObject } from '../../utils';
 import * as yaml from 'js-yaml';
+import { buildGraph, Graph } from '../../graph-builder';
+import { convertToMermaidCode } from '../../mermaid-converter';
 
 /**
  * Represents the intersection between the Workflow class and type
@@ -112,6 +114,14 @@ export class Workflow extends ObjectHydrator<Specification.Workflow> {
     return yaml.dump(normalized);
   }
 
+  static toGraph(model: Partial<WorkflowIntersection>): Graph {
+    return buildGraph(model as unknown as WorkflowIntersection);
+  }
+
+  static toMermaidCode(model: Partial<WorkflowIntersection>): string {
+    return convertToMermaidCode(model as unknown as WorkflowIntersection);
+  }
+
   /**
    * Serializes the workflow to YAML or JSON
    * @param format The format, 'yaml' or 'json', default is 'yaml'
@@ -121,6 +131,22 @@ export class Workflow extends ObjectHydrator<Specification.Workflow> {
   serialize(format: 'yaml' | 'json' = 'yaml', normalize: boolean = true): string {
     return Workflow.serialize(this as unknown as WorkflowIntersection, format, normalize);
   }
+
+  /**
+   * Creates a directed graph representation of the workflow
+   * @returns A directed graph of the workflow
+   */
+  toGraph(): Graph {
+    return Workflow.toGraph(this as unknown as WorkflowIntersection);
+  }
+
+  /**
+   * Generates the MermaidJS code corresponding to the workflow
+   * @returns The MermaidJS code
+   */
+  toMermaidCode(): string {
+    return Workflow.toMermaidCode(this as unknown as WorkflowIntersection);
+  }
 }
 
 export const _Workflow = Workflow as WorkflowConstructor & {
@@ -139,4 +165,18 @@ export const _Workflow = Workflow as WorkflowConstructor & {
    * @returns A string representation of the workflow
    */
   serialize(workflow: Partial<WorkflowIntersection>, format?: 'yaml' | 'json', normalize?: boolean): string;
+
+  /**
+   * Creates a directed graph representation of the provided workflow
+   * @param workflow The workflow to convert
+   * @returns A directed graph of the provided workflow
+   */
+  toGraph(workflow: Partial<WorkflowIntersection>): Graph;
+
+  /**
+   * Generates the MermaidJS code corresponding to the provided workflow
+   * @param workflow The workflow to convert
+   * @returns The MermaidJS code
+   */
+  toMermaidCode(workflow: Partial<WorkflowIntersection>): string;
 };

src/lib/graph-builder.ts

@@ -0,0 +1,100 @@
+import { Workflow } from './generated/definitions/specification';
+import { buildGraph, Graph, GraphEdge, GraphNode, GraphNodeType } from './graph-builder';
+
+/**
+ * Adds indentation to each line of the provided code
+ * @param code The code to indent
+ * @returns The indented code
+ */
+const indent = (code: string) =>
+  code
+    .split('\n')
+    .map((line) => `    ${line}`)
+    .join('\n');
+
+/**
+ * Converts a graph to Mermaid code
+ * @param graph The graph to convert
+ * @returns The converted graph
+ */
+function convertGraphToCode(graph: Graph): string {
+  const isRoot: boolean = graph.id === 'root';
+  const code = `${isRoot ? 'flowchart TD' : `subgraph ${graph.id} ["${graph.label || graph.id}"]`}
+${indent(graph.nodes.map((node) => convertNodeToCode(node)).join('\n'))}
+${indent(graph.edges.map((edge) => convertEdgeToCode(edge)).join('\n'))}
+${isRoot ? '' : 'end'}`;
+  return code;
+}
+
+/**
+ * Converts a node to Mermaid code
+ * @param node The node to convert
+ * @returns The converted node
+ */
+function convertNodeToCode(node: GraphNode | Graph): string {
+  let code = '';
+  if ((node as Graph).nodes?.length) {
+    code = convertGraphToCode(node as Graph);
+  } else {
+    code = node.id;
+    switch (node.type) {
+      case GraphNodeType.Entry:
+      case GraphNodeType.Exit:
+        code += ':::hidden';
+        break;
+      case GraphNodeType.Start:
+        code += '(( ))'; // alt '@{ shape: circle, label: " "}';
+        break;
+      case GraphNodeType.End:
+        code += '((( )))'; // alt '@{ shape: dbl-circ, label: " "}';
+        break;
+      default:
+        code += `["${node.label}"]`; // alt `@{ label: "${node.label}" }`
+    }
+  }
+  return code;
+}
+
+/**
+ * Converts an edge to Mermaid code
+ * @param edge The edge to convert
+ * @returns The converted edge
+ */
+function convertEdgeToCode(edge: GraphEdge): string {
+  const ignoreEndArrow =
+    !edge.destinationId.startsWith('root') &&
+    (edge.destinationId.endsWith('-entry-node') || edge.destinationId.endsWith('-exit-node'));
+  const code = `${edge.sourceId} ${edge.label ? `--"${edge.label}"` : ''}--${ignoreEndArrow ? '-' : '>'} ${edge.destinationId}`;
+  return code;
+}
+
+/**
+ * Converts the provided workflow to Mermaid code
+ * @param workflow The workflow to convert
+ * @returns The Mermaid diagram
+ */
+export function convertToMermaidCode(workflow: Workflow): string {
+  const graph = buildGraph(workflow);
+  return (
+    convertGraphToCode(graph) +
+    `
+
+classDef hidden display: none;`
+  );
+}
+
+/**
+ * Represents a Mermaid diagram generator for a given workflow.
+ * This class takes a workflow definition and converts it into a Mermaid.js-compatible diagram.
+ */
+export class MermaidDiagram {
+  constructor(private workflow: Workflow) {}
+
+  /**
+   * Generates the Mermaid code representation of the workflow.
+   * @returns The Mermaid diagram source code as a string.
+   */
+  sourceCode(): string {
+    return convertToMermaidCode(this.workflow);
+  }
+}

src/lib/mermaid-converter.ts

@@ -2,3 +2,5 @@ export * from './lib/generated/builders';
 export * from './lib/generated/classes';
 export * from './lib/generated/definitions';
 export * from './lib/validation';
+export * from './lib/graph-builder';
+export * from './lib/mermaid-converter';

src/serverless-workflow-sdk.ts

@@ -0,0 +1,139 @@
+import { Specification } from '../../src';
+import { Classes } from '../../src/lib/generated/classes';
+import { buildGraph, Graph } from '../../src/lib/graph-builder';
+
+describe('Workflow to Graph', () => {
+  it('should build a graph for a workflow with a Set task, using the buildGraph function', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      set:
+        foo: bar`);
+    const graph = buildGraph(workflow);
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(3); // start --> initialize --> end
+    expect(graph.edges.length).toBe(2);
+  });
+
+  it('should build a graph for a workflow with a Set task, using the instance method', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      set:
+        foo: bar`);
+    const graph = workflow.toGraph();
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(3); // start --> initialize --> end
+    expect(graph.edges.length).toBe(2);
+  });
+
+  it('should build a graph for a workflow with a Set task, using the static method', () => {
+    const workflow = {
+      document: {
+        dsl: '1.0.0',
+        name: 'set',
+        version: '1.0.0',
+        namespace: 'test',
+      },
+      do: [
+        {
+          initialize: {
+            set: {
+              foo: 'bar',
+            },
+          },
+        },
+      ],
+    } as Specification.Workflow;
+    const graph = Classes.Workflow.toGraph(workflow);
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(3); // start --> initialize --> end
+    expect(graph.edges.length).toBe(2);
+  });
+
+  it('should build a graph for a workflow with multiple Set tasks', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - step1:
+      set:
+        foo: bar
+  - step2:
+      set:
+        foo2: bar
+  - step3:
+      set:
+        foo3: bar`);
+    const graph = buildGraph(workflow);
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(5); // start --> step1 --> step2 --> step3 --> end
+    expect(graph.edges.length).toBe(4);
+  });
+
+  it('should build a graph for a workflow with a task containing an If clause, producing an alternative edge', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      if: \${ input.data == true }
+      set:
+        foo: bar`);
+    const graph = buildGraph(workflow);
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(3); // start --> initialize --> end
+    expect(graph.edges.length).toBe(3); //       ----------------->
+    expect(graph.edges.filter((e) => e.label === '${ input.data == true }').length).toBe(1);
+  });
+
+  it('should build a graph for a workflow with a For task, producing a subgraph', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: for-example
+  version: '0.1.0'
+do:
+  - checkup:
+      for:
+        each: pet
+        in: .pets
+        at: index
+      while: .vet != null
+      do:
+        - waitForCheckup:
+            listen:
+              to:
+                one:
+                  with:
+                    type: com.fake.petclinic.pets.checkup.completed.v2
+            output:
+              as: '.pets + [{ "id": $pet.id }]'`);
+    const graph = buildGraph(workflow);
+    const forSubgraph = graph.nodes.find((node) => node.label === 'checkup') as Graph;
+    expect(graph).toBeDefined();
+    expect(graph.nodes.length).toBe(3); // start --> checkup --> end
+    expect(graph.edges.length).toBe(2);
+
+    expect(forSubgraph).toBeDefined();
+    expect(forSubgraph.nodes.length).toBe(3); // entry --> waitForCheckup --> exit
+    expect(forSubgraph.edges.length).toBe(2);
+  });
+});

tests/graph/graph.spec.ts

@@ -0,0 +1,182 @@
+import { Classes } from '../../src/lib/generated/classes';
+import { Specification } from '../../src/lib/generated/definitions';
+import { convertToMermaidCode, MermaidDiagram } from '../../src/lib/mermaid-converter';
+
+describe('Workflow to MermaidJS Flowchart', () => {
+  it('should build a Mermaid diagram for a workflow with a Set task, using the convertToMermaidCode function', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      set:
+        foo: bar`);
+    const mermaidCode = convertToMermaidCode(workflow).trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/initialize["initialize"]
+    /do/0/initialize --> root-exit-node
+    root-entry-node --> /do/0/initialize
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+
+  it('should build a Mermaid diagram for a workflow with a Set task, using the instance method', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      set:
+        foo: bar`);
+    const mermaidCode = workflow.toMermaidCode().trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/initialize["initialize"]
+    /do/0/initialize --> root-exit-node
+    root-entry-node --> /do/0/initialize
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+
+  it('should build a Mermaid diagram for a workflow with a Set task, using the static method', () => {
+    const workflow = {
+      document: {
+        dsl: '1.0.0',
+        name: 'set',
+        version: '1.0.0',
+        namespace: 'test',
+      },
+      do: [
+        {
+          initialize: {
+            set: {
+              foo: 'bar',
+            },
+          },
+        },
+      ],
+    } as Specification.Workflow;
+    const mermaidCode = Classes.Workflow.toMermaidCode(workflow).trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/initialize["initialize"]
+    /do/0/initialize --> root-exit-node
+    root-entry-node --> /do/0/initialize
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+
+  it('should build a Mermaid diagram for a workflow with a Set task, using the legacy MermaidDiagram class', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      set:
+        foo: bar`);
+    const mermaidCode = new MermaidDiagram(workflow).sourceCode().trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/initialize["initialize"]
+    /do/0/initialize --> root-exit-node
+    root-entry-node --> /do/0/initialize
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+
+  it('should build a Mermaid diagram with an alternative, labelled, edge', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: set
+  version: '0.1.0'
+do:
+  - initialize:
+      if: \${ input.data == true }
+      set:
+        foo: bar`);
+    const mermaidCode = convertToMermaidCode(workflow).trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    /do/0/initialize["initialize"]
+    /do/0/initialize --> root-exit-node
+    root-entry-node --"\${ input.data == true }"--> /do/0/initialize
+    root-entry-node --> root-exit-node
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+
+  it('should build a Mermaid diagram for a workflow with a For task', () => {
+    const workflow = Classes.Workflow.deserialize(`
+document:
+  dsl: '1.0.0'
+  namespace: test
+  name: for-example
+  version: '0.1.0'
+do:
+  - checkup:
+      for:
+        each: pet
+        in: .pets
+        at: index
+      while: .vet != null
+      do:
+        - waitForCheckup:
+            listen:
+              to:
+                one:
+                  with:
+                    type: com.fake.petclinic.pets.checkup.completed.v2
+            output:
+              as: '.pets + [{ "id": $pet.id }]'`);
+    const mermaidCode = convertToMermaidCode(workflow).trim();
+    expect(mermaidCode).toBe(
+      `flowchart TD
+    root-entry-node(( ))
+    root-exit-node((( )))
+    subgraph /do/0/checkup ["checkup"]
+        /do/0/checkup-entry-node:::hidden
+        /do/0/checkup-exit-node:::hidden
+        /do/0/checkup/for/do/0/waitForCheckup["waitForCheckup"]
+        /do/0/checkup/for/do/0/waitForCheckup --- /do/0/checkup-exit-node
+        /do/0/checkup-entry-node --> /do/0/checkup/for/do/0/waitForCheckup
+    end
+    /do/0/checkup-exit-node --> root-exit-node
+    root-entry-node --- /do/0/checkup-entry-node
+
+
+classDef hidden display: none;`.trim(),
+    );
+  });
+});

tests/mermaid/mermaid.spec.ts

@@ -46,7 +46,13 @@ import { Specification } from '../definitions';
 import { getLifecycleHooks } from '../../lifecycle-hooks';
 import { validate } from '../../validation';
 ${hydrationResult.code ? `import { isObject } from '../../utils';` : ''}
-${name === 'Workflow' ? `import * as yaml from 'js-yaml';` : ''}
+${
+  name === 'Workflow'
+    ? `import * as yaml from 'js-yaml';
+import { buildGraph, Graph } from '../../graph-builder';
+import { convertToMermaidCode } from '../../mermaid-converter';`
+    : ''
+}
 
 /**
  * Represents the intersection between the ${name} class and type
@@ -125,6 +131,14 @@ export class ${name} extends ${baseClass ? '_' + baseClass : `ObjectHydrator<Spe
     }
     return yaml.dump(normalized);
   }
+
+  static toGraph(model: Partial<WorkflowIntersection>): Graph {
+    return buildGraph(model as unknown as WorkflowIntersection);
+  }
+
+  static toMermaidCode(model: Partial<WorkflowIntersection>): string {
+    return convertToMermaidCode(model as unknown as WorkflowIntersection);
+  }
   
   /**
    * Serializes the workflow to YAML or JSON
@@ -134,6 +148,22 @@ export class ${name} extends ${baseClass ? '_' + baseClass : `ObjectHydrator<Spe
    */
   serialize(format: 'yaml' | 'json' = 'yaml', normalize: boolean = true): string {
     return Workflow.serialize(this as unknown as WorkflowIntersection, format, normalize);
+  }
+
+  /**
+   * Creates a directed graph representation of the workflow
+   * @returns A directed graph of the workflow
+   */
+  toGraph(): Graph {
+    return Workflow.toGraph(this as unknown as WorkflowIntersection);
+  }
+
+  /**
+   * Generates the MermaidJS code corresponding to the workflow
+   * @returns The MermaidJS code
+   */
+  toMermaidCode(): string {
+    return Workflow.toMermaidCode(this as unknown as WorkflowIntersection);
   }`
       : ''
   }
@@ -156,7 +186,21 @@ export const _${name} = ${name} as ${name}Constructor${
    * @param normalize If the workflow should be normalized before serialization, default true
    * @returns A string representation of the workflow
    */
-  serialize(workflow: Partial<WorkflowIntersection>, format?: 'yaml' | 'json', normalize?: boolean): string 
+  serialize(workflow: Partial<WorkflowIntersection>, format?: 'yaml' | 'json', normalize?: boolean): string;
+
+  /**
+   * Creates a directed graph representation of the provided workflow
+   * @param workflow The workflow to convert
+   * @returns A directed graph of the provided workflow
+   */
+  toGraph(workflow: Partial<WorkflowIntersection>): Graph;
+
+  /**
+   * Generates the MermaidJS code corresponding to the provided workflow
+   * @param workflow The workflow to convert
+   * @returns The MermaidJS code
+   */
+  toMermaidCode(workflow: Partial<WorkflowIntersection>): string;
 }`
       : ''
   };`;