# salmon42/ts-data-objects architecture

> Architecture diagram of the GitHub repository salmon42/ts-data-objects, 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/salmon42/ts-data-objects
- Repository: https://github.com/salmon42/ts-data-objects

## Overview

##### Project Type and Purpose
- This is a TypeScript library (not a full-stack application) called **ts-data-objects**.
- Its purpose is to provide a lightweight, modular toolkit for runtime type-safe data objects, guards, parsers, and default-filled constructors.
- There are three main logical modules: **common**, **core**, and **deep** (experimental deep validation).

##### File Structure
- Top-Level Files
- package.json, tsconfig.json, vitest.config.ts, vite.config.ts – build, test, and bundling configurations
- scripts/ – automation for cleaning, deploying, and generating docs
- Source Code
- lib/ – compiled output (mirrors src/)
- src/ – authorative TypeScript source modules
– src/core, src/deep, plus example files and an entrypoint main.ts
- Documentation
- docs/ – the generated static site (via typedoc)
- readme/ – changelog, development notes, scaffolding guidelines
- Tests
- tests/ – unit tests for each assertion, core, and performance tests

##### README for Additional Insights
- The library exports multiple entry points:
– `ts-data-objects/common` – basic type-checking predicates (isStr, isNum, etc.)
– `ts-data-objects/core` – dataGuard, dataObject, defineObject, dataParser
– `ts-data-objects/deep` – experimental deep-nested validation
- Scripts:
– `scripts/doc.ts` invokes TypeDoc to generate docs into docs/
– `scripts/deploy.ts` publishes to NPM / GitHub Pages

##### Main Components & Their Interactions
a. **Modules**
- Common Module: array.ts, boolean.ts, number.ts, object.ts, string.ts → exports primitive guards
- Core Module: dataGuard, dataObject, dataParser, defineObject → composes common predicates
- Deep Module: dataDeepGuard, dataDeepParser → builds upon core for recursive structures
- Examples: ExampleDataSimple, ExampleDataDeep – illustrate usage
- Tests: validate each module’s public API
- Build & Publish: TypeScript compiler → lib/, then bundle for NPM; TypeDoc → docs/
b. **Relationships**
- src/**/* → compiles to lib/**/*
- core depends on common; deep depends on core
- test suites import from src or lib for unit and performance tests
- scripts invoke CLI tools (tsc, typedoc, vitest, rimraf)
c. **Architectural Patterns**
- Modular, layered design:
1. Primitive Guards (common)
2. Composite Guards & Parsers (core)
3. Deep/Recursive Validation (deep)
- Separation of concerns: validation logic vs object construction
- Build pipeline: source → compile → test → doc → publish
d. **Key Technologies**
- TypeScript (tsc), Vitest for testing, TypeDoc for documentation, ESBuild/Vite for bundling (if used), Node.js scripts

##### Detailed Elements
- Labels: module names, build steps, external services
- Annotations:
- Modular entry points (common, core, deep)
- “experimental” on deep module
- versioning and changelog (readme/CHANGELOG.md)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Modules
    subgraph "Source (src)" 
        direction TB
        src_common["Common Module\n(src/common)"]:::code
        src_core["Core Module\n(src/core)"]:::code
        src_deep["Deep Module\n(src/deep)"]:::code
        src_examples["Examples\n(src/*.ts)"]:::code
        src_main["Entrypoint\n(src/main.ts)"]:::code
    end

    %% Compilation
    src_common -->|tsc| lib_common_asserts
    src_core -->|tsc| lib_core
    src_deep -->|tsc| lib_deep
    src_examples -->|tsc| lib_main
    src_main -->|tsc| lib_main

    %% Compiled Output
    subgraph "Compiled Output (lib)" 
        direction TB
        lib_common_asserts["Common Asserts\n(lib/common/asserts)"]:::code
        lib_core["Core Module\n(lib/core)"]:::code
        lib_deep["Deep Module\n(lib/deep)"]:::code
        lib_main["Main Entry\n(lib/main.ts)"]:::code
        lib_types["Helpers & Types\n(lib/types.ts)"]:::code
    end

    %% Testing
    tests["Tests\n(vitest)"]:::script
    src_common -->|vitest| tests
    src_core -->|vitest| tests
    src_deep -->|vitest| tests
    src_examples -->|vitest| tests

    %% Documentation
    lib_common_asserts -->|typedoc| docs
    lib_core -->|typedoc| docs
    lib_deep -->|typedoc| docs
    lib_main -->|typedoc| docs

    docs["Docs\n(docs/)"]:::output
    docs -->|deploy docs| gh_pages["GitHub Pages"]:::external

    %% Publishing
    lib_common_asserts -->|npm publish| npm_registry["NPM Registry"]:::external
    lib_core -->|npm publish| npm_registry
    lib_deep -->|npm publish| npm_registry
    lib_main -->|npm publish| npm_registry

    %% Scripts
    subgraph "Scripts" 
        direction TB
        clean["clean.ts"]:::script
        doc_script["doc.ts"]:::script
        deploy_script["deploy.ts"]:::script
    end
    clean -->|rimraf| lib_common_asserts
    clean --> lib_core
    clean --> lib_deep
    doc_script --> docs
    deploy_script --> npm_registry
    deploy_script --> gh_pages

    %% Click Events
    click lib_common_asserts "https://github.com/salmon42/ts-data-objects/tree/master/lib/common/asserts"
    click lib_core "https://github.com/salmon42/ts-data-objects/tree/master/lib/core"
    click lib_deep "https://github.com/salmon42/ts-data-objects/tree/master/lib/deep"
    click lib_main "https://github.com/salmon42/ts-data-objects/blob/master/lib/main.ts"
    click src_main "https://github.com/salmon42/ts-data-objects/blob/master/src/main.ts"
    click example_simple "https://github.com/salmon42/ts-data-objects/blob/master/src/ExampleDataSimple.ts"
    click example_deep "https://github.com/salmon42/ts-data-objects/blob/master/src/ExampleDataDeep.ts"
    click tests "https://github.com/salmon42/ts-data-objects/blob/master/tests/assertions/array.unit.test.ts"
    click tests "https://github.com/salmon42/ts-data-objects/blob/master/tests/core/dataGuard.unit.test.ts"
    click tests "https://github.com/salmon42/ts-data-objects/blob/master/tests/performance/assertions.perf.test.ts"
    click docs "https://github.com/salmon42/ts-data-objects/tree/master/docs"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#005B9F,color:#003F6B
    classDef output fill:#DFFFE0,stroke:#2E7D32,color:#1B5E20,stroke-width:2px
    classDef script fill:#FFF4C1,stroke:#FFB300,color:#E65100,stroke-dasharray: 5 5
    classDef external fill:#F0F0F0,stroke:#888888,color:#444444,stroke-dasharray: 2 2
```
