feat: add graph and MermaidJS builders

Signed-off-by: Jean-Baptiste Bianchi <[email protected]>

Author: JBBianchi

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
@@ -223,7 +247,7 @@ 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 workflowDefinition = /* <Your preferred method> */;
 try {
   if (workflowDefinition instanceof Classes.Workflow) {
     workflowDefinition.validate();
@@ -237,6 +261,91 @@ catch (ex) {
 }
 ```
 
+#### Generate a directed graph
+A [directed graph](https://en.wikipedia.org/wiki/Directed_graph) of a workflow can be generated using the `buildGraph` function:
+
+```typescript
+import { buildGraph } from '@serverlessworkflow/sdk';
+
+const workflowDefinition = {
+  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(workflowDefinition);
+/*{
+  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` or the legacy `MermaidDiagram` class.
+
+```typescript
+import { convertToMermaidCode, MermaidDiagram } from '@serverlessworkflow/sdk';
+
+const workflowDefinition = {
+  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(workflowDefinition) /* or new MermaidDiagram(workflowDefinition).sourceCode() */;
+/*
+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

@@ -9,41 +9,121 @@
 </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>
-  <pre class="mermaid" id="diagram-container"></div>
   <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',
-          name: 'using-plain-object',
-          version: '1.0.0',
-          namespace: 'default',
+  "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: [
+        "do": [
           {
-            step1: {
-              set: {
-                variable: 'my first workflow',
-              },
-            },
-          },
-        ],
-      }/* as Specification.Workflow // <-- If you're using TypeScript*/;
-      try {
-        validate('Workflow', workflowDefinition);
-        const diagramContainerEl = document.getElementById('diagram-container');
-        const mermaidCode = convertToMermaidCode(workflowDefinition);
-        diagramContainerEl.innerText = mermaidCode;
-        document.getElementById('output').innerHTML = `--- YAML ---\n${Classes.Workflow.serialize(workflowDefinition)}\n\n--- JSON ---\n${Classes.Workflow.serialize(workflowDefinition, 'json')}\n\n--- MERMAID ---\n${mermaidCode}`;
-        mermaid.initialize({ startOnLoad: true });
+            "callOrderService": {
+              "call": "openapi",
+              "with": {
+                "document": {
+                  "endpoint": "http://myorg.io/ordersservices.json"
+                },
+                "operationId": "logreading"
+              }
+            }
+          }
+        ]
       }
-      catch (ex) {
-        console.error('Invalid workflow', ex);
+    },
+    {
+      "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>

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",