# victor141516/pledge architecture

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

- Interactive diagram: https://gitdiagram.com/victor141516/pledge
- Repository: https://github.com/victor141516/pledge

## Overview

##### Project type and purpose
- This is an open-source, TypeScript-based library (“@victor141516/pledge”) that enables streaming of JavaScript objects containing promises over HTTP using the JSON Lines format.
- It provides both a server-side component (to serialize promises into a progressive stream) and a client-side component (to reconstruct the object and resolve promises as data arrives).

##### File structure
- Top-level folders:
- src/common: shared utilities (type definitions, identifier generation, type checking)
- src/server: server implementation (core logic, Express adapter, response creation)
- src/client: client implementation (readResponse entry point, items handler)
- dist/: compiled output mirroring src structure for publish
- tests/: unit, integration, and end-to-end specs covering both client and server code
- Key configuration artefacts: package.json, tsconfig.json, .gitignore
- Build scripts not explicit—bun.lock suggests Bun support but npm scripts live in package.json

##### README for insights
- Core flow described in “How It Works”:
a. Server replaces promises in the object with placeholders and streams a skeleton JSON line
b. As each promise resolves, it streams an individual JSON line with its resolved value
c. Client reconstructs the original object, inserting placeholder promises that resolve when their corresponding stream item arrives
- The library is framework-agnostic but ships with an Express middleware adapter

##### Main components and their relationships
a. Application (e.g., Express app)
b. pledgeMiddleware (server adapter) ← part of src/server/adapters/express
c. Server core:
- items-handler.ts: traverses object, extracts promises, assigns placeholder IDs
- create-response.ts: orchestrates JSON Lines streaming over HTTP
d. HTTP Layer: chunked transfer encoding, newline-delimited JSON
e. Client core:
- read-response.ts: reads incoming JSON Lines, reconstructs object skeleton, wires placeholder promises
- items-handler.ts: resolves individual promises in the reconstructed object
f. Common utilities (src/common): type definitions, identifier generation, validation of payloads

##### Architectural patterns and design principles
- Streaming pipeline: backpressure-safe, chunked JSON Lines
- Adapter pattern: Express middleware abstracts over any HTTP framework
- Separation of concerns: common logic separated from server/client specifics
- Type safety: full TS definitions ensure correct usage and inference

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Server Side"
        App["Express App"]:::external
        srvIndex["server/index.ts"]:::server
        pledgeMiddleware["pledgeMiddleware (Express adapter)"]:::server
        srvItems["itemsHandler (extract & tag promises)"]:::server
        srvCreate["createResponse (stream skeleton + promise resolutions)"]:::server
        App --> pledgeMiddleware
        srvIndex --> pledgeMiddleware
        pledgeMiddleware --> srvItems
        srvItems --> srvCreate
        srvCreate --> HTTP
    end

    HTTP["HTTP JSON Lines Stream"]:::transport

    subgraph "Client Side"
        fetch["fetch()"]:::external
        cliIndex["client/index.ts"]:::client
        readResp["readResponse"]:::client
        cliItems["itemsHandler (merge resolved items)"]:::client
        returned["Returned Object with Live Promises"]:::clientDashed
        fetch --> readResp
        cliIndex --> readResp
        readResp --> cliItems
        cliItems --> returned
        HTTP --> readResp
    end

    subgraph "Common Utilities"
        ident["identifier"]:::common
        typechk["typecheck"]:::common
        types["types"]:::common
        srvItems --> ident
        readResp --> ident
        srvItems --> typechk
        cliItems --> typechk
        srvItems --> types
        cliItems --> types
    end

    click pledgeMiddleware "https://github.com/victor141516/pledge/blob/master/src/server/adapters/express.ts"
    click srvItems "https://github.com/victor141516/pledge/blob/master/src/server/items-handler.ts"
    click srvCreate "https://github.com/victor141516/pledge/blob/master/src/server/create-response.ts"
    click srvIndex "https://github.com/victor141516/pledge/blob/master/src/server/index.ts"
    click readResp "https://github.com/victor141516/pledge/blob/master/src/client/read-response.ts"
    click cliItems "https://github.com/victor141516/pledge/blob/master/src/client/items-handler.ts"
    click cliIndex "https://github.com/victor141516/pledge/blob/master/src/client/index.ts"
    click ident "https://github.com/victor141516/pledge/blob/master/src/common/identifier.ts"
    click typechk "https://github.com/victor141516/pledge/blob/master/src/common/typecheck.ts"
    click types "https://github.com/victor141516/pledge/blob/master/src/common/types.ts"

    classDef server fill:#D0E1F9,stroke:#4C78A8
    classDef client fill:#D1F7C4,stroke:#4CAF50
    classDef common fill:#F5F5F5,stroke:#AAA
    classDef external fill:#FFE0B2,stroke:#FF9800
    classDef transport fill:#E1E1E1,stroke:#757575,stroke-dasharray:5 5
    classDef clientDashed fill:#D1F7C4,stroke:#4CAF50,stroke-dasharray:5 5
```
