# creativogee/masq architecture

> Architecture diagram of the GitHub repository creativogee/masq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/creativogee/masq
- Repository: https://github.com/creativogee/masq

## Overview

Masq is a dependency-free TypeScript library for selecting and masking object fields and producing allow-listed query projections and relation joins. The main workflow is to parse a requested field mask, optionally validate it against an allow-list, then apply it to data; separate helpers turn field and relation specifications into query-builder descriptors. The runtime is contained in `src/index.ts`; the excerpts are partial, so links between unsampled helpers are shown only where documented.

Main entry points: [`src/index.ts`](https://github.com/creativogee/masq/blob/main/src/index.ts) (applyMask)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_consumer(("API consumer"))
node_data["Object data"]
node_spec["Field spec"]
node_allow["Field allow-list"]
node_maskparse["parseFieldsSpec<br/>[index.ts]"]
node_validate["isValidMask<br/>[index.ts]"]
node_applymask["applyMask<br/>[index.ts]"]
node_applyfield["applyFieldMask<br/>[index.ts]"]
node_masked["Filtered data"]
node_flatparse["parseFlatFieldsSpec<br/>[index.ts]"]
node_columns["SELECT columns"]
node_relationspec["Relation spec"]
node_relationparse["parseRelationsSpec<br/>[index.ts]"]
node_joins["Join descriptors"]
node_columnhelper["Column projection<br/>[index.ts]"]
node_relationhelper["projectRelation<br/>[index.ts]"]
node_relationallow["Relation allow-list"]
node_approvedcolumns["Validated columns"]
node_approvedjoins["Validated joins"]

node_consumer -->|"parses fields"| node_maskparse
node_spec -->|"supplies spec"| node_maskparse
node_consumer -->|"validates mask"| node_validate
node_maskparse -->|"provides mask"| node_validate
node_allow -->|"constrains fields"| node_validate
node_consumer -->|"requests filtering"| node_applymask
node_spec -->|"supplies mask"| node_applymask
node_applymask -->|"parses string"| node_maskparse
node_applymask -->|"applies mask"| node_applyfield
node_consumer -->|"applies parsed mask"| node_applyfield
node_data -->|"filters source"| node_applyfield
node_applyfield -->|"returns subset"| node_masked
node_consumer -->|"requests paths"| node_flatparse
node_spec -->|"supplies spec"| node_flatparse
node_allow -->|"limits paths"| node_flatparse
node_flatparse -->|"emits paths"| node_columns
node_consumer -->|"requests joins"| node_relationparse
node_relationspec -->|"supplies spec"| node_relationparse
node_relationparse -->|"emits descriptors"| node_joins
node_consumer -->|"requests projection"| node_columnhelper
node_columnhelper -->|"validates columns"| node_approvedcolumns
node_consumer -->|"requests projection"| node_relationhelper
node_relationallow -->|"constrains joins"| node_relationhelper
node_relationhelper -->|"parses requested joins"| node_relationparse
node_relationhelper -->|"validates paths"| node_approvedjoins

click node_maskparse "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_validate "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_applymask "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_applyfield "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_flatparse "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_relationparse "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_columnhelper "https://github.com/creativogee/masq/blob/main/src/index.ts"
click node_relationhelper "https://github.com/creativogee/masq/blob/main/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer toneMint
class node_data,node_spec,node_allow,node_masked,node_columns,node_relationspec,node_joins,node_relationallow,node_approvedcolumns,node_approvedjoins toneIndigo
class node_maskparse,node_validate,node_applymask,node_applyfield,node_flatparse,node_relationparse,node_columnhelper,node_relationhelper toneTeal
```

## Components

### Other components

- **API consumer**
- **Object data**
- **Field spec**
- **Field allow-list**
- [parseFieldsSpec](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- [isValidMask](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- [applyMask](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- [applyFieldMask](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- **Filtered data**
- [parseFlatFieldsSpec](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- **SELECT columns**
- **Relation spec**
- [parseRelationsSpec](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- **Join descriptors**
- [Column projection](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- [projectRelation](https://github.com/creativogee/masq/blob/main/src/index.ts): `src/index.ts`
- **Relation allow-list**
- **Validated columns**
- **Validated joins**

## Connections

- API consumer → parseFieldsSpec: parses fields
- Field spec → parseFieldsSpec: supplies spec
- API consumer → isValidMask: validates mask
- parseFieldsSpec → isValidMask: provides mask
- Field allow-list → isValidMask: constrains fields
- API consumer → applyMask: requests filtering
- Field spec → applyMask: supplies mask
- applyMask → parseFieldsSpec: parses string
- applyMask → applyFieldMask: applies mask
- API consumer → applyFieldMask: applies parsed mask
- Object data → applyFieldMask: filters source
- applyFieldMask → Filtered data: returns subset
- API consumer → parseFlatFieldsSpec: requests paths
- Field spec → parseFlatFieldsSpec: supplies spec
- Field allow-list → parseFlatFieldsSpec: limits paths
- parseFlatFieldsSpec → SELECT columns: emits paths
- API consumer → parseRelationsSpec: requests joins
- Relation spec → parseRelationsSpec: supplies spec
- parseRelationsSpec → Join descriptors: emits descriptors
- API consumer → Column projection: requests projection
- Column projection → Validated columns: validates columns
- API consumer → projectRelation: requests projection
- Relation allow-list → projectRelation: constrains joins
- projectRelation → parseRelationsSpec: parses requested joins
- projectRelation → Validated joins: validates paths