# gabrieljmj/matchee architecture

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

- Interactive diagram: https://gitdiagram.com/gabrieljmj/matchee
- Repository: https://github.com/gabrieljmj/matchee

## Overview

##### Project type and purpose
- This is an open-source, TypeScript-based NPM library (“matchee”) that provides a type-safe, functional match expression engine (sync and async) and a helper to match object paths.
- There is no frontend or persistent store—this is purely a utility/tool that client code will import and invoke.

##### File structure
- Top-level files: package.json, README.md, tsconfig.json, CI workflow, lint/prettier configs → build & release setup.
- src/
- index.ts → public API exports (match, asyncMatch, objectPaths, isMatchError, types)
- match.ts → core synchronous matching engine
- comparison-handlers.ts → type-dispatch of expression comparisons (number, string, boolean, RegExp, objectPaths, Symbol)
- object-paths.ts → builds and evaluates nested‐property matchers
- helpers.ts → shared utilities (type guards, path parsing, array/object checks)
- constants.ts → configuration constants (error messages, default case identifier)
- exceptions/ → custom Error classes (UnhandledMatchExpression, InvalidExpressionType)
- tests/ → unit and async tests covering all features and error cases
- .changeset/ → release note mechanism

##### README for additional insights
- Public API functions: match, asyncMatch, objectPaths, isMatchingError
- Core concepts: passing arrays of cases, default case, lazy evaluation (functions/promises), objectPaths helper, TypeScript generics
- Supported expression types listed; error behavior when no match found

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Code
    Consumer["Consumer Code"]:::consumer

    %% Public API Layer
    API["src/index.ts: Public API"]:::publicapi

    %% Core Engine
    Sync["src/match.ts: Core Engine"]:::core
    Async["asyncMatch (in src/index.ts)"]:::core

    %% Utilities
    CH["src/comparison-handlers.ts"]:::util
    OP["src/object-paths.ts"]:::util
    Helpers["src/helpers.ts"]:::util
    Const["src/constants.ts"]:::util

    %% Exceptions
    EX1["invalid-expression-type.ts"]:::exception
    EX2["unhandled-match-expression.ts"]:::exception

    %% Test Suite
    subgraph "Test Suite"
        T1["tests/match.test.ts"]:::test
        T2["tests/asyncMatch.test.ts"]:::test
        T3["tests/isMatchingError.test.ts"]:::test
    end

    %% CI Pipeline
    subgraph "CI Pipeline"
        CI1[".github/workflows/main.yml"]:::ci
        CI2["tsconfig.json"]:::ci
        CI3[".eslintrc"]:::ci
        CI4[".prettierrc.json"]:::ci
        CI5["package.json"]:::ci
    end

    %% Relationships
    Consumer -->|imports| API
    API -->|calls sync match| Sync
    API -->|calls asyncMatch| Async
    API -->|uses objectPaths| OP
    Sync -->|uses handlers| CH
    Sync -->|uses objectPaths| OP
    CH -->|uses helpers| Helpers
    CH -->|uses constants| Const
    OP -->|uses helpers| Helpers
    Helpers -->|throws| EX1
    CH -->|throws| EX2
    OP -->|throws| EX2
    T1 -->|tests| API
    T2 -->|tests| API
    T3 -->|tests| API
    CI1 -->|runs tests| T1
    CI1 -->|runs tests| T2
    CI1 -->|runs tests| T3
    CI2 -->|config for| Sync
    CI3 -->|lints| Sync
    CI4 -->|formats| Sync
    CI5 -->|pkg config| API

    %% Click Events
    click API "https://github.com/gabrieljmj/matchee/blob/main/src/index.ts"
    click Sync "https://github.com/gabrieljmj/matchee/blob/main/src/match.ts"
    click Async "https://github.com/gabrieljmj/matchee/blob/main/src/index.ts"
    click CH "https://github.com/gabrieljmj/matchee/blob/main/src/comparison-handlers.ts"
    click OP "https://github.com/gabrieljmj/matchee/blob/main/src/object-paths.ts"
    click Helpers "https://github.com/gabrieljmj/matchee/blob/main/src/helpers.ts"
    click Const "https://github.com/gabrieljmj/matchee/blob/main/src/constants.ts"
    click EX1 "https://github.com/gabrieljmj/matchee/blob/main/src/exceptions/invalid-expression-type.ts"
    click EX2 "https://github.com/gabrieljmj/matchee/blob/main/src/exceptions/unhandled-match-expression.ts"
    click T1 "https://github.com/gabrieljmj/matchee/blob/main/tests/match.test.ts"
    click T2 "https://github.com/gabrieljmj/matchee/blob/main/tests/asyncMatch.test.ts"
    click T3 "https://github.com/gabrieljmj/matchee/blob/main/tests/isMatchingError.test.ts"
    click CI1 "https://github.com/gabrieljmj/matchee/blob/main/.github/workflows/main.yml"
    click CI2 "https://github.com/gabrieljmj/matchee/blob/main/tsconfig.json"
    click CI3 "https://github.com/gabrieljmj/matchee/blob/main/.eslintrc"
    click CI4 "https://github.com/gabrieljmj/matchee/blob/main/.prettierrc.json"
    click CI5 "https://github.com/gabrieljmj/matchee/blob/main/package.json"

    %% Styles
    classDef publicapi fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#145A32;
    classDef util fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef exception fill:#F5B7B1,stroke:#C0392B,color:#78281F;
    classDef test fill:#D5D8DC,stroke:#566573,color:#1B2631;
    classDef ci fill:#F2F4F4,stroke:#7B7D7D,color:#17202A;
    classDef consumer stroke:#999,stroke-dasharray: 5 5,fill:none;
```
