angular-mermaider

Static code analyser that produces Mermaid dataflow diagrams for Angular components

angular-mermaider statically analyzes Angular component source (TypeScript + inline/template HTML) and emits Mermaid-compatible charts that visualize component dataflow. It's focused on components that handle data reactively (observables, streams, signals) and produces clear graphs of how data moves through properties, streams and template bindings.

Key ideas

• Static-only: analyzes source code and templates without executing the app.
• Reactive-first: designed for components that express data flow using Observables, Signals or other stream-like primitives.
• Mermaid output: produces a markdown file containing a mermaid code block (file: <component>.dataflow.md).

Restrictions & Scope

• This tool intentionally targets purely reactive dataflows. It assumes components avoid in-place mutations and side-effects, and instead build streams/pipelines (Observables, Subjects, Signals, StatefulObservables, etc.).
• It will not (reliably) model imperative mutating code, direct DOM writes, or functions that perform side effects. If your component mixes mutation/imperative updates with reactive pipelines, results may be incomplete or misleading.
• Template analysis supports common binding forms (attribute bindings, event handlers, interpolation and expansion forms). Some tokenized expansion-form AST shapes require a conservative fallback; in rare cases this may yield extra fallback entries.

Example output

---
title: Component dataflow
---
graph LR
    subgraph Sources
        subgraph Injected
            direction LR
            Source_clientsApi["
                clientsApi
            "]
            Source_bucketApi["
                bucketApi
            "]
            Source_allProducts$("
                allProducts$
            ")
        end
        subgraph Inputs
            direction LR
            Source_clientId("
                clientId
            ")
            Source_showBucket("
                showBucket
            ")
        end
    end
    subgraph Processing
        Processing_clientId$("
            clientId$
        ")
        Processing_client$("
            client$
        ")
        Processing_bucket$("
            bucket$
        ")
        Processing_populatedBucket$("
            populatedBucket$
        ")
        Processing_showBucket@{ shape: f-circ, label: "Junction" }
    end
    subgraph Consumers
        subgraph TemplateRead
            direction LR
            Consumer_client$("
                client$
                x3
            ")
            Consumer_showBucket["
                showBucket
            "]
            Consumer_populatedBucket$("
                populatedBucket$
                x2
            ")
        end
    end
    Sources ~~~ Processing
    Processing ~~~ Consumers
    Source_showBucket --> Processing_showBucket
    Source_clientId --> Processing_clientId$
    Processing_clientId$ --> Processing_client$
    Source_clientsApi --> Processing_client$
    Processing_clientId$ --> Processing_bucket$
    Source_bucketApi --> Processing_bucket$
    Processing_bucket$ --> Processing_populatedBucket$
    Source_allProducts$ --> Processing_populatedBucket$
    Processing_showBucket --> Consumer_showBucket
    Processing_client$ --> Consumer_client$
    Processing_populatedBucket$ --> Consumer_populatedBucket$

• rounded nodes represent reactive properties (observables or signals)
• Not linked nodes represent entities managed outside of reactive dataflow.
• Red nodes represent mutable class members
• Yellow nodes represent readonly, but writable reactive sources: subjects or writable signals

Usage (CLI)

Quick usage via npx (recommended):

npx angular-mermaider "path/to/my-component.component.ts"

Type npx angular-mermaider and drag your file with component from IDE into the CLI.

If you built locally, you can also run the built CLI directly:

node ./dist/cli.js path/to/my-component.component.ts

On success the tool writes a file next to the component named my-component.component.dataflow.md containing a Mermaid chart. Open that file in any Markdown viewer that supports Mermaid or paste the chart into the Mermaid Live Editor.

Install

No special install is required for end users: prefer the quick npx usage described above in "Usage (CLI)".

If you want to run or develop locally, clone the repository and install dependencies, then build the CLI:

git clone https://github.com/earthdmitriy/angular-mermaider.git
cd angular-mermaider
npm install
npm run build

The built CLI is written to ./dist/cli.js and can be executed with node ./dist/cli.js as shown in the Usage section.

Programmatic API

You can also import and invoke the library from Node (example):

import { main } from "./dist/mermaider/mermaider.js";

// (The CLI entry simply calls `main()`, but you can require and call library functions as needed.)

See src/mermaider/mermaider.ts for the main flow: it extracts class properties, extracts template references, combines them, formats a mermaid graph and writes a .dataflow.md file.

What it recognizes

• Class properties (constructor-injected services, declared properties)
• Observable-like properties (detected via type text such as Observable, Subject, StatefulObservable, etc.)
• Signals (detected via Signal in the type)
• Template references from:
  • Attribute bindings: [attr]="...", (event)="...", [(ngModel)]="..."
  • Text interpolation: {{ ... }}
  • Expansion forms (e.g. @if, @for) including some tokenized forms (with conservative fallback)

Example

Given a component that declares a stream property and in the template binds [class.loading]="stream.pending$ | async", the analyzer detects stream.pending$ as a value node in the template and links it to the component's stream property in the generated dataflow chart.

Tests

Run unit tests with:

npm test

The repository includes unit tests for the template analyzer, class-property extraction, and other core modules.

Contributing

• Open issues for bugs and feature requests.
• Add focused unit tests for new template shapes or property patterns before implementing broad changes.

Limitations & future ideas

• Improve precision for tokenized expansion-form AST shapes so fallback heuristic can be removed.
• Add heuristics to better filter noisy fallback matches (control keywords, structural tokens).
• Support analysis across multiple files (component + service interactions) to build cross-component dataflow.

Changelog

• 0.3.0
  • legend added into generated dataflow.md files
  • treat setters as part of reactive dataflow (link setters to affected properties)
  • minor internal optimisations
  • ts-morph project being recreated after 100 processed files
• 0.2.0
  • reactive members (signals or observables) represented with rounded nodes
  • mutable nodes have red background
  • reactive writable nodes have yellow background
  • ts-morph project being reused across all files in batch
    • npx angular-mermaider "src/**/*.component.ts" work much faster
  • fixed few border-cases
  • internal logic streamlined with pipes

License

ISC