mermaid-event-model

Event Model

A small DSL and SVG renderer for Event Modeling diagrams. You describe a system as a sequence of UIs, commands, domain events, read models, and automations; the renderer lays it out as a strict horizontal timeline with swimlanes — actors on top, aggregates on the bottom, commands and read models on the central time axis — so every element in the same causal step lines up vertically across all lanes.

Installation

As an npm package

npm install @howarddierking/mermaid-event-model d3 mermaid

d3 and mermaid are peer dependencies. mermaid is optional — you only need it if you use the Mermaid adapter (the default export); the ./core subpath entry (for standalone SVG rendering) only requires d3.

The default export is an array of every diagram definition this package ships (eventModel and sliceTests), ready to register with Mermaid in one call:

import mermaid from 'mermaid';
import diagramDefinitions from '@howarddierking/mermaid-event-model';

await mermaid.registerExternalDiagrams(diagramDefinitions);
mermaid.initialize({ startOnLoad: true });

Any fenced block whose first line is eventModel or sliceTests will now be routed to the right renderer. To register only one of them, pull the named export:

import { eventModelDefinition, sliceTestsDefinition }
  from '@howarddierking/mermaid-event-model';

await mermaid.registerExternalDiagrams([eventModelDefinition]); // event-model only

For standalone use without Mermaid:

import { renderEventModel } from '@howarddierking/mermaid-event-model/core';
import { renderSliceTests } from '@howarddierking/mermaid-event-model/slice-tests-core';

renderEventModel(dslSource, document.getElementById('diagram'));
renderSliceTests(testSource, document.getElementById('tests'));

Via CDN (no build step)

The package is mirrored on jsDelivr. Pair it with an importmap so the bare d3 and mermaid imports resolve:

<script type="importmap">
{
  "imports": {
    "d3": "https://cdn.jsdelivr.net/npm/d3@7/+esm",
    "mermaid": "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs",
    "@howarddierking/mermaid-event-model": "https://cdn.jsdelivr.net/npm/@howarddierking/mermaid-event-model/index.js"
  }
}
</script>
<script type="module">
  import mermaid from 'mermaid';
  import diagramDefinitions from '@howarddierking/mermaid-event-model';

  await mermaid.registerExternalDiagrams(diagramDefinitions);
  mermaid.initialize({ startOnLoad: true });
</script>

Running the examples

Two demo pages, served as static HTML with no build step (mermaid, d3, and marked are loaded from a CDN at runtime):

Page	What it shows
model-viewer.html	Canonical demo. Renders a .md model file (markdown prose + the embedded eventModel diagram), with a sidebar that lists every slice spec under the matching <model>-slices/ directory. Switch models with ?model=<basename>.
core-playground.html	Standalone DSL textarea + Render button, exercising the core renderer directly without Mermaid. Useful for diagnosing whether a layout bug is in the renderer or in the Mermaid integration.

Start a local server and open the viewer:

# from the repo root
python3 -m http.server 8000

Then open http://localhost:8000/model-viewer.html.

A local HTTP server is required because the JS files are ES modules and most browsers block module imports over file://. The Python server's directory listing is also what powers the slice-spec sidebar.

The viewer loads blueprint_dsl_fanin.md by default and polls for changes every 1.5s — edit any .md and the open page re-renders. Try other models with ?model=blueprint_dsl, ?model=blueprint_dsl_dcb, or ?model=blueprint_sliceTests.

The rendered diagram scrolls horizontally — each element gets its own column, so wide models overflow the right edge rather than compressing.

The DSL

DSL files are markdown — each one is a .md file whose DSL lives inside a fenced ```mermaid block. See blueprint_dsl.md for a full aggregate-based example (a hotel booking system) and blueprint_dsl_dcb.md for the same model rewritten in DCB style (no aggregates, with reads clauses on commands). The renderer's parser tolerates either raw DSL or markdown wrappers, so anywhere this README shows raw eventModel ... syntax, that's the body of the fenced block. The grammar:

eventModel
    actor <Name>
    aggregate <Name>                                        (optional — DCB models omit aggregates)

    ui:<Actor>            <id>["Label"]
    command               <id>["Label"] [reads [<event>, ...]]
    domainEvent[:<Agg>]   <id>["Label"]
    externalEvent         <id>["Label"]
    readModel             <id>["Label"]
    automation:<Actor>    <id>["Label"]

    <id> --> <id>