Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/earthdmitriy/angular-mermaider

Static code analyser that produces Mermaid dataflow diagrams for Angular components
https://github.com/earthdmitriy/angular-mermaider

Last synced: about 18 hours ago
JSON representation

Static code analyser that produces Mermaid dataflow diagrams for Angular components

Awesome Lists containing this project

README 

          
# 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: `.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

```mermaid

---

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):



```bash

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:



```bash

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:



```bash

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):



```ts

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:



```bash

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.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