# anningui/kaia-fp-deno architecture

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

- Interactive diagram: https://gitdiagram.com/anningui/kaia-fp-deno
- Repository: https://github.com/anningui/kaia-fp-deno

## Overview

##### Project Type and Purpose
- Type: An open‑source, zero‑dependency TypeScript library for functional programming.
- Purpose: Provide composable, type‑safe FP primitives (HKT, type classes), concrete instances (Option, Task, IO, etc.), and helper utilities (pipe, match, lens).

##### File Structure
- Top‑level entry:
- `mod.ts` (aggregates and re‑exports public API)
- Core abstractions (`src/core`):
- `hkt.ts` – higher‑kinded type support
- `typeClass.ts` – type‑class definitions
- `utils.ts` – core helpers
- Concrete instances (`src/instances`):
- `option.ts`, `io.ts`, `task.ts`, `reader.ts`, `state.ts`, `writer.ts`, `asyncResult.ts`
- `index.ts` re‑exports all instances
- Utility modules (`src/utils`):
- `either.ts`, `lens.ts`, `schema.ts`
- `match/*` – pattern‑matching builder, matcher, predicates
- `pipe/*` – function pipelining, tryCatch
- Config & CI:
- `deno.json`, `jsr.json` – build/config for Deno & JSR
- `.github/workflows/publish.yml` – CI pipeline

##### Extract Insights from the README
- Emphasis on zero dependencies, TypeScript support, pure FP primitives, algebraic data types, immutable transformations.

##### Main Components
a. **Core Layer**
b. **Instances Layer** (depends on Core)
c. **Utilities Layer** (depends on Core and Instances)
d. **Public API**
e. **External Integrations**
f. **Build & CI**

##### Architectural Patterns & Design Principles
- **Layered architecture**: Core at the foundation, concrete instances built atop abstractions, utilities on top.
- **Modularization**: Each instance and utility lives in its own module for tree‑shaking.
- **Extensibility points**: Users can write new instances by implementing type classes from Core.
- **Functional purity**: No side‐effectful modules; immutability enforced by TypeScript types.

##### Technologies & Frameworks
- Language: TypeScript targeting Deno/JSR environments
- Build/config: `deno.json`, `jsr.json`
- CI/CD: GitHub Actions (`publish.yml`)

##### Final Checklist
- [ ] All modules represented (core, instances, utils, mod.ts).
- [ ] External user interaction shown.
- [ ] Build/CI config noted as side component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumer
    UserCode["User Code"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        Mod["mod.ts"]:::api
        SrcIndex["src/index.ts"]:::api
    end

    %% Utilities Layer
    subgraph "Utilities Layer" 
        direction TB
        UtilsIndex["src/utils/index.ts"]:::utils
        Either["Either"]:::utils
        Lens["Lens"]:::utils
        Schema["Schema"]:::utils
        subgraph "Match Sub-module"
            Builder["builder.ts"]:::utils
            Predicates["is.ts"]:::utils
            Matcher["match.ts"]:::utils
            MatchIndex["index.ts"]:::utils
        end
        subgraph "Pipe Sub-module"
            PipeFn["pipe.ts"]:::utils
            TryCatch["tryCatch.ts"]:::utils
            PipeIndex["index.ts"]:::utils
        end
    end

    %% Instances Layer
    subgraph "Instances Layer"
        direction TB
        InstancesIndex["src/instances/index.ts"]:::instances
        Option["Option"]:::instances
        IO["IO"]:::instances
        Task["Task"]:::instances
        Reader["Reader"]:::instances
        State["State"]:::instances
        Writer["Writer"]:::instances
        AsyncResult["AsyncResult"]:::instances
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        CoreIndex["src/core/index.ts"]:::core
        HKT["hkt.ts"]:::core
        TypeClass["typeClass.ts"]:::core
        CoreUtils["utils.ts"]:::core
    end

    %% Build & CI
    subgraph "Build & CI" 
        direction TB
        DenoConfig["deno.json"]:::config
        JSRConfig["jsr.json"]:::config
        PublishYml[".github/workflows/publish.yml"]:::config
    end

    %% Relationships
    UserCode -->|"imports"| Mod
    Mod -->|"re-exports"| CoreIndex
    Mod -->|"re-exports"| InstancesIndex
    Mod -->|"re-exports"| UtilsIndex
    SrcIndex -->|"mirrors"| Mod

    InstancesIndex -->|"imports"| HKT
    InstancesIndex -->|"imports"| TypeClass
    Option -->|"implements"| TypeClass
    IO -->|"implements"| TypeClass
    Task -->|"implements"| TypeClass
    Reader -->|"implements"| TypeClass
    State -->|"implements"| TypeClass
    Writer -->|"implements"| TypeClass
    AsyncResult -->|"implements"| TypeClass

    UtilsIndex -->|"imports"| CoreUtils
    UtilsIndex -->|"imports"| HKT
    Either -->|"depends on"| CoreUtils
    Lens -->|"depends on"| CoreUtils
    Schema -->|"depends on"| CoreUtils
    MatchIndex -->|"depends on"| Builder
    Builder -->|"uses"| Predicates
    Builder -->|"uses"| Matcher
    PipeIndex -->|"depends on"| PipeFn
    PipeFn -->|"uses"| TryCatch

    UtilsIndex -->|"may use"| Option
    UtilsIndex -->|"may use"| Task

    %% Layer Dependencies
    InstancesIndex -->|"dep on core"| CoreIndex
    UtilsIndex -->|"dep on core"| CoreIndex
    UtilsIndex -->|"dep on instances"| InstancesIndex

    %% Click Events
    click HKT "https://github.com/anningui/kaia-fp-deno/blob/main/src/core/hkt.ts"
    click TypeClass "https://github.com/anningui/kaia-fp-deno/blob/main/src/core/typeClass.ts"
    click CoreUtils "https://github.com/anningui/kaia-fp-deno/blob/main/src/core/utils.ts"
    click CoreIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/core/index.ts"
    click Option "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/option.ts"
    click IO "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/io.ts"
    click Task "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/task.ts"
    click Reader "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/reader.ts"
    click State "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/state.ts"
    click Writer "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/writer.ts"
    click AsyncResult "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/asyncResult.ts"
    click InstancesIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/instances/index.ts"
    click Either "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/either.ts"
    click Lens "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/lens.ts"
    click Schema "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/schema.ts"
    click Builder "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/match/builder.ts"
    click Predicates "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/match/is.ts"
    click Matcher "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/match/match.ts"
    click MatchIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/match/index.ts"
    click PipeFn "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/pipe/pipe.ts"
    click TryCatch "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/pipe/tryCatch.ts"
    click PipeIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/pipe/index.ts"
    click UtilsIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/utils/index.ts"
    click Mod "https://github.com/anningui/kaia-fp-deno/blob/main/mod.ts"
    click SrcIndex "https://github.com/anningui/kaia-fp-deno/blob/main/src/index.ts"
    click DenoConfig "https://github.com/anningui/kaia-fp-deno/blob/main/deno.json"
    click JSRConfig "https://github.com/anningui/kaia-fp-deno/blob/main/jsr.json"
    click PublishYml "https://github.com/anningui/kaia-fp-deno/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef core fill:#ffe0b2,stroke:#ff9800,stroke-width:2px
    classDef instances fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px
    classDef utils fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    classDef api fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px
    classDef external fill:#ffebee,stroke:#f44336,stroke-width:2px
    classDef config fill:#eceff1,stroke:#607d8b,stroke-width:2px
```
