# dinhplus/typed-query-filter architecture

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

- Interactive diagram: https://gitdiagram.com/dinhplus/typed-query-filter
- Repository: https://github.com/dinhplus/typed-query-filter

## Overview

##### Project type and purpose
- This is an open-source TypeScript library (NPM package) called typed-query-filter.
- It provides a MongoDB-like, type-safe query engine for in-memory JS/TS arrays.
- It runs in both Node.js and browsers (with a planned WASM backend).

##### File structure
- Top-level:
- package.json / tsconfig.json / vitest.config.ts / README.md / LICENSE
- CI/CD configs in .github/workflows
- Husky / commitlint for pre-commit checks
- Core library under src:
- filterData.ts – main function export
- QueryBuilder.ts – chainable API
- core/ – compiler, fieldMatcher, getNestedValue, flatKey utilities
- types.ts – shared type definitions
- Entry point index.ts re-exports API
- Playground for manual experimentation (playground/index.ts + /data + /examples)
- Tests under src/__tests__ using Vitest

##### README for additional insights
- Describes API surfaces: filterData, QueryBuilder, projection, operators
- Details supported operators, nested queries, projection modes
- Mentions upcoming WASM backend
- Usage scenarios: frontend grid filtering, backend data processing, form builder integration

##### Main components
- API Layer
- filterData function
- QueryBuilder class
- Core Engine
- Compiler (parses query into predicate AST)
- FieldMatcher (maps operator to matching logic)
- getNestedValue (retrieves value by “a.b[0].c”)
- FlatKey helper (builds field-path autocomplete)
- Data Flow
- Input: arbitrary array of objects (User[])
- Query definition (object literal or builder chain)
- Query parsing → predicate generation
- Iteration over array → apply predicate → filtered subset
- Sorting / limiting
- Projection (three modes: field list, callback, template)
- Output: transformed array
- Environments
- Node.js runtime
- Browser runtime
- (Future) WASM backend
- Tooling & CI
- Vitest test runner
- GitHub Actions (test, lint, release, publish)
- Husky + commitlint

##### Relationships and interactions
- User code calls filterData or instantiates QueryBuilder
→ API Layer
→ Core Engine processes the query
→ Data Flow transforms input to output
- Core Engine utilities are loosely coupled:
- Compiler uses fieldMatcher & getNestedValue
- Projection logic uses FlatKey
- Playground imports the published library for manual demos
- CI/CD pipelines run tests & publish to NPM

##### Architectural patterns and design principles
- Modular separation: API layer vs. compiler vs. utilities
- Functional pipeline: parse → predicate → filter → sort/limit → project
- Type-safe generics for end-to-end TS support
- Single-responsibility modules (each file has one purpose)
- Extensible operator registry (operator implementations decoupled)

##### Detailed capture of architectural elements
- How core utilities plug into both filterData and QueryBuilder
- Optional WASM module hook replacing CPU-based filter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Host
    HostApp["Host Application"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        EntryPoint["index.ts (re-exports)"]:::library
        FilterData["filterData()"]:::library
        QueryBuilder["QueryBuilder"]:::library
    end

    %% Core Engine
    subgraph "Core Engine (src/core)"
        direction TB
        Compiler["Compiler"]:::library
        FieldMatcher["FieldMatcher"]:::library
        GetNestedValue["getNestedValue"]:::library
        FlatKey["flatKey"]:::library
    end

    %% Shared Types
    Types["types.ts"]:::library

    %% Data Flow Pipeline
    subgraph "Data Flow"
        direction TB
        InputArray["Input: Object[]"]
        QueryDef["Query Definition"] 
        AST["AST Generation"]
        Predicate["Predicate Function"]
        FilterLoop["Filter Loop"]
        SortLimit["Sort & Limit"]
        subgraph Projection["Projection"]
            direction TB
            ByFields["Field List"]
            ByCallback["Callback"]
            ByTemplate["Template"]
        end
        Output["Output: Transformed Array"]
    end

    %% Environments
    subgraph "Environments"
        direction TB
        NodeJS["Node.js"]:::env
        Browser["Browser"]:::env
        WASM["WASM Backend (future)"]:::env
    end

    %% Playground & Tests
    Playground["Playground"]:::external
    Tests["Vitest Tests"]:::external

    %% Tooling & CI/CD
    subgraph "Tooling & CI/CD"
        direction TB
        GitHubActions["GitHub Actions"]:::tooling
        Husky["Husky Hooks"]:::tooling
        CommitLint["Commitlint"]:::tooling
    end

    %% Connections
    HostApp -->|"uses API"| EntryPoint
    EntryPoint -->|re-export| FilterData
    EntryPoint --> QueryBuilder
    FilterData & QueryBuilder -->|"invoke core"| Compiler
    Compiler --> FieldMatcher
    Compiler --> GetNestedValue
    QueryBuilder --> Types
    FilterData --> Types
    FieldMatcher --> FlatKey
    GetNestedValue --> FlatKey
    Compiler --> AST
    AST --> Predicate
    Predicate --> FilterLoop
    FilterLoop --> SortLimit
    SortLimit --> Projection
    Projection --> Output
    HostApp --> NodeJS
    HostApp --> Browser
    HostApp --> WASM
    Playground --> EntryPoint
    Tests --> FilterData
    Tests --> QueryBuilder
    GitHubActions --> Tests
    GitHubActions -->|"publish"| EntryPoint
    Husky -->|"pre-commit"| CommitLint
    Husky -->|"pre-commit"| Tests

    %% Click Events
    click FilterData "https://github.com/dinhplus/typed-query-filter/blob/master/src/filterData.ts"
    click QueryBuilder "https://github.com/dinhplus/typed-query-filter/blob/master/src/QueryBuilder.ts"
    click EntryPoint "https://github.com/dinhplus/typed-query-filter/blob/master/src/index.ts"
    click Compiler "https://github.com/dinhplus/typed-query-filter/blob/master/src/core/compiler.ts"
    click FieldMatcher "https://github.com/dinhplus/typed-query-filter/blob/master/src/core/fieldMatcher.ts"
    click GetNestedValue "https://github.com/dinhplus/typed-query-filter/blob/master/src/core/getNestedValue.ts"
    click FlatKey "https://github.com/dinhplus/typed-query-filter/blob/master/src/core/flatKey.ts"
    click Types "https://github.com/dinhplus/typed-query-filter/blob/master/src/types.ts"
    click Tests "https://github.com/dinhplus/typed-query-filter/blob/master/src/__tests__/filterData.test.ts"
    click Playground "https://github.com/dinhplus/typed-query-filter/blob/master/playground/index.ts"

    %% Styles
    classDef library fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef env fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef tooling fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef external fill:#f0f0f0,stroke:#9e9e9e,color:#424242;
```
