Proposal: Add types & typeguards to Diagram & DiagramDb

[Quatton]

Objective

I would like to achieve something like:

const diagram = await mermaidAPI.getDiagramFromText(text);
      // ^? const diagram: Diagram
if (isFlowchartDiagram(diagram)) {
      const { db, text } = diagram;
           // ^? const db: FlowchartDb
            
      // type-safety & auto-completion ✅
      const vertices = db.getVertices();
      const edges = db.getEdges();
      
      // do something with it
}

Furthermore, it would be a nice addition if the diagram DB can import JavaScript objects like what's discussed in #518 and #3100.

Motivation

Currently, mermaid-js has been underutilized due to the absence of specific types on Diagram and DiagramDb. It's true that you can getAccTitle with the current interface

export interface DiagramDb {
    clear?: () => void;
    setDiagramTitle?: (title: string) => void;
    setDisplayMode?: (title: string) => void;
    getAccTitle?: () => string;
    getAccDescription?: () => string;
    bindFunctions?: (element: Element) => void;
}

However, if we take a look at flowDb.js, the internal API is more capable than it is!

export default {
  // ...
  getDirection,
  getVertices,
  getEdges,
  getClasses,
  // ...
};

Here we can get the vertices or edges without rendering the SVG. This enables us to apply some manipulations to it before rendering the SVG back.

All in all, the usage of mermaidAPI is limited, but merely because the Diagram is any typed. If we have type guards to check the diagram type, we can access each property of the diagram DBs.

Workarounds

Although the solution above would greatly improve overall developer experience, it does not mean that we could not manipulate the nodes right now.

The following code makes every node adds another node connecting to it without any configuration. Here, pre is the Ref object in Vue.js.

const nodes = document.querySelector("g.nodes");

if (!nodes) return;
for (const node of nodes.children) {
  const nodeId = node.id.match(/^flowchart-(\w+)-\d+$/)?.at(1);
  node.addEventListener("click", () => {
    pre.value += `\n\t${nodeId} --> node${Math.floor(
      Math.random() * 100000
    )}("✏️")`;
  });
  node.classList.add("cursor-pointer");
}

However, this is a post-render processing. It would be nice if we could manipulate something after parsing but before rendering to add custom "add-ons" or "middlewares".