# gvergnaud/ts-pattern architecture

> Architecture diagram of the GitHub repository gvergnaud/ts-pattern, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gvergnaud/ts-pattern
- Repository: https://github.com/gvergnaud/ts-pattern

## Overview

##### Main Components
- Core Library / Engine: Include a block for the “Pattern Matching Engine” that resides in the src/ folder. Here, the entry point (src/index.ts) directs to supporting modules like:
– Pattern and matcher functions (src/match.ts, src/is-matching.ts, src/patterns.ts)
– Helper utilities found in src/internals (helpers.ts and symbols.ts) that assist pattern checking and selection.
– Error management (src/errors.ts) which handles report or exhaustiveness errors.
- Testing and Verification: Include a node for the “Tests” module, showing that there is comprehensive test coverage in the tests/ directory. This node shows real usage scenarios—from simple literal matching to nested and union types—as well as exhaustive checking tests.
- Performance and Benchmarks: Create a smaller module for “Benchmarks” (benchmarks/ directory) that highlights how the library performance is measured, helping to compare different matching strategies.
- Documentation & Examples: Add nodes for “Documentation (docs/)” and “Examples (examples/)” which illustrate how the API is used in real projects (like the gif-fetcher and one-file demo) and guides for migration between major versions.

##### Relationships and Interactions
- That “Public API” also communicates with error handling (errors.ts) when mismatches, non-exhaustiveness or unexpected values occur.
- From “Client Code / Examples”, point to “Documentation” and “Testing”, highlighting that the library’s usage is validated via unit tests and documented through README and additional guides in the docs directory.
- That the “Benchmarks” and “Scripts” (like generate-cts.sh in scripts/) help maintain performance and type exports generation.

##### Architectural Patterns and Design Principles
- Modular Separation: Clearly, different responsibilities are separated into modules—core matching, type handling, testing, documentation, and auxiliary scripts.
- Type Safety & Exhaustiveness: Emphasize that the library utilizes advanced TypeScript generics and type guards for robust type inference. This core principle is supported by the “Types” modules.
- Test-Driven: Extensive testing, as shown by the tests folder, ensures robustness that can be represented as a ring around core modules.

##### Relevant Technologies and Tools
- TypeScript: The entire project is written in TypeScript. Note that the TypeScript compiler (and its configuration via tsconfig.json) plays a central role.
- Jest: Testing is configured via Jest (referenced by jest.config.cjs), which provides the testing framework.
- Tools like Prettier (.prettierrc) and GitHub metadata (e.g., .github/ISSUE_TEMPLATE) show that standard development tools are in use.
- Node/NPM: The project is published on npm (as seen by package.json and package-lock.json) and includes CLI tools (scripts).

##### Elements
- Clear labels for each component (e.g., “Public API (match, isMatching, etc.)”, “Pattern Matching Engine”, “Type Utilities”, “Internal Helpers”, “Error Handling”, “Testing Suite”, “Documentation & Examples”, “Benchmarks”).
– Core internal modules (engine, types, internals)
– Supporting components (tests, docs, examples, benchmarks).
- To annotate each connection (for instance, “Input processed”, “Type inferencing applied”, “Error thrown if non-exhaustive”) so that the architecture’s flow is explicit.

## Diagram (Mermaid)

```mermaid
flowchart TD
    API["Public API (match, isMatching, pattern factories)"]:::api

    subgraph "Pattern Matching Engine"
        M1["match.ts"]:::engine
        M2["is-matching.ts"]:::engine
        M3["patterns.ts"]:::engine
    end

    TYPES["Type Inference & Types Utilities"]:::types
    HELPERS["Internal Helpers (helpers.ts & symbols.ts)"]:::helpers
    ERROR["Error Handling (errors.ts)"]:::error

    TESTS["Testing Suite"]:::tests
    DOCS["Documentation"]:::docs
    EXAMPLES["Examples"]:::docs
    BENCH["Benchmarks"]:::bench
    SCRIPTS["Performance & Export Scripts"]:::scripts

    %% Core interactions
    API -->|"calls"| M1
    API -->|"calls"| M2
    API -->|"calls"| M3

    M1 -->|"applies-TypeInference"| TYPES
    M2 -->|"applies-TypeInference"| TYPES
    M3 -->|"applies-TypeInference"| TYPES

    M1 -->|"uses"| HELPERS
    M1 -->|"throws-errorIfNonExhaustive"| ERROR
    API -->|"routes-error"| ERROR

    %% Supporting modules interactions
    EXAMPLES -->|"documentedBy"| DOCS
    EXAMPLES -->|"validatedBy"| TESTS

    BENCH -->|"measures"| M1
    SCRIPTS -->|"generatesExports"| API
    SCRIPTS -->|"supports"| BENCH

    %% Click Events
    click API "https://github.com/gvergnaud/ts-pattern/blob/main/src/index.ts"
    click M1 "https://github.com/gvergnaud/ts-pattern/blob/main/src/match.ts"
    click M2 "https://github.com/gvergnaud/ts-pattern/blob/main/src/is-matching.ts"
    click M3 "https://github.com/gvergnaud/ts-pattern/blob/main/src/patterns.ts"
    click TYPES "https://github.com/gvergnaud/ts-pattern/tree/main/src/types"
    click HELPERS "https://github.com/gvergnaud/ts-pattern/tree/main/src/internals"
    click ERROR "https://github.com/gvergnaud/ts-pattern/blob/main/src/errors.ts"
    click TESTS "https://github.com/gvergnaud/ts-pattern/tree/main/tests"
    click BENCH "https://github.com/gvergnaud/ts-pattern/tree/main/benchmarks"
    click DOCS "https://github.com/gvergnaud/ts-pattern/tree/main/docs"
    click EXAMPLES "https://github.com/gvergnaud/ts-pattern/tree/main/examples"
    click SCRIPTS "https://github.com/gvergnaud/ts-pattern/blob/main/scripts/generate-cts.sh"

    %% Styles
    classDef api fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef engine fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef types fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef helpers fill:#ffc0cb,stroke:#333,stroke-width:2px;
    classDef error fill:#ff6666,stroke:#333,stroke-width:2px;
    classDef tests fill:#d2b48c,stroke:#333,stroke-width:2px;
    classDef docs fill:#cc99ff,stroke:#333,stroke-width:2px;
    classDef bench fill:#99ff99,stroke:#333,stroke-width:2px;
    classDef scripts fill:#ffcc99,stroke:#333,stroke-width:2px;
```
