# eugef/node-mocks-http architecture

> Architecture diagram of the GitHub repository eugef/node-mocks-http, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eugef/node-mocks-http
- Repository: https://github.com/eugef/node-mocks-http

## Overview

##### Project Type and Purpose
- This is an open-source Node.js library (node-mocks-http) whose sole purpose is to provide lightweight mock HTTP `Request` and `Response` objects for testing Express, Next.js, Koa, or any Node.js-based web server code.
- It does not spin up a real server—rather it supplies factory functions (`createRequest()`, `createResponse()`, `createMocks()`) that produce in-memory, inspectable mock objects.

##### High-Level File Structure and Architectural Indicators
- Top-level folders:
- **lib/** – actual implementation modules, subdivided into:
– **express/** – Express-specific mock adapters (mock Express application, request, response).
– **node/** – low-level mocks built on Node’s native `http` internals (`_http_incoming.js`, `_http_server.js`, `http.js`).
– **utils** (define-getter, header parsers, generic utilities).
– root of **lib/** also holds generic mocks: `mockRequest.js`, `mockResponse.js`, `mockEventEmitter.js`, `mockWritableStream.js`, plus a central `http-mock.js` and TypeScript definitions.
- **examples/** – usage scenarios (ignored in the runtime architecture but good to show consumer code).
- **test/** – unit tests (illustrate how the public API is consumed).
- Public entrypoint (package.json `main`) points to `lib/http-mock.js`, which exports the factory methods.

##### Relevant README Insights
- Clearly describes public API methods: `.createRequest()`, `.createResponse()`, `.createMocks()`.
- Emphasizes support for multiple frameworks via generic type parameters.
- Mentions internal mock event emitter and writable stream, and that users can inject their own `EventEmitter`.

##### Diagramming the Architecture
a. Main Components to Represent
1) Public API Layer (http-mock.js) – exports `createRequest`, `createResponse`, `createMocks`.
2) Request Factory Module (`mockRequest.js`)
3) Response Factory Module (`mockResponse.js`)
4) Express Adapter Submodule (`lib/express/*`)
5) Node-core Adapter Submodule (`lib/node/*`)
6) Utilities (`lib/utils.js`, `lib/headers.js`, `define-getter.js`)
7) Supporting Streams & Events (`mockEventEmitter.js`, `mockWritableStream.js`)
8) External Dependencies:
- Node.js `http` module (IncomingMessage, ServerResponse)
- Express / Next.js / Koa frameworks (via type extensions)
b. Relationships & Interactions
- The **Public API** calls the **Request Factory** and **Response Factory**.
- **Request Factory** composes or extends Node’s `IncomingMessage` prototypes (through `node/_http_incoming.js`) and wires in utilities (headers, getters).
- **Response Factory** composes or extends Node’s `ServerResponse` (`node/_http_server.js`), injecting a `mockEventEmitter` and `mockWritableStream`.
- **Express Adapter** wraps the generic mocks to supply Express-flavored `.params()`, `.accepts()`, etc.
- Utility modules provide shared functionality (parsing headers, defining getters, merging options).
- Consumer code (tests or examples) invokes the Public API → obtains `req`/`res` → passes into application code (Express route handlers) → inspects returned data via helper methods (`_getData()`, `_isEndCalled()`, etc.).
c. Architectural Patterns
- **Factory Pattern** – for creating request/response mocks with customizable options.
- **Adapter Pattern** – express-specific submodule adapts the generic mock to Express semantics.
- **Dependency Injection** – users can inject a real `EventEmitter` implementation or custom writable streams.
d. Key Technologies & Libraries
- Node.js HTTP internals (`http`, `_http_incoming`, `_http_server`)
- Express / Next.js / Koa types & behaviors
- TypeScript type definitions (bundled `.d.ts`)
- EventEmitter, Streams API

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Public API Layer"
        API["http-mock.js"]:::public
        API_TS["http-mock.d.ts"]:::public
    end

    subgraph "Factories"
        Req["mockRequest.js"]:::core
        Res["mockResponse.js"]:::core
    end

    subgraph "Adapters"
        subgraph "Express Adapter"
            EXP_MAIN["mock-express.js"]:::adapter
            EXP_APP["mock-application.js"]:::adapter
            EXP_REQ["mock-request.js"]:::adapter
        end
        subgraph "Node-core Adapter"
            NC_MAIN["http.js"]:::adapter
            NC_IN["_http_incoming.js"]:::adapter
            NC_SR["_http_server.js"]:::adapter
        end
    end

    subgraph "Utilities"
        HEAD["headers.js"]:::util
        UTIL["utils.js"]:::util
        DEF["define-getter.js"]:::util
    end

    subgraph "Supporting Components"
        EM["mockEventEmitter.js"]:::util
        WS["mockWritableStream.js"]:::util
    end

    External["Node.js http module"]:::ext

    %% Connections
    API -->|"calls"| Req
    API -->|"calls"| Res

    Req -->|"extends prototype"| NC_IN
    Req -->|"uses"| HEAD
    Req -->|"uses"| DEF

    Res -->|"extends prototype"| NC_SR
    Res -->|"injects"| EM
    Res -->|"injects"| WS

    EXP_MAIN -->|"wraps generic mocks"| Req
    EXP_MAIN -->|"wraps generic mocks"| Res
    EXP_APP -->|"enhances"| EXP_MAIN
    EXP_REQ -->|"enhances"| EXP_MAIN

    NC_MAIN -->|"aggregates"| NC_IN
    NC_MAIN -->|"aggregates"| NC_SR

    NC_IN -->|"relies on"| External
    NC_SR -->|"relies on"| External
    NC_MAIN -->|"relies on"| External

    %% Click Events
    click API "https://github.com/eugef/node-mocks-http/blob/master/lib/http-mock.js"
    click API_TS "https://github.com/eugef/node-mocks-http/blob/master/lib/http-mock.d.ts"
    click Req "https://github.com/eugef/node-mocks-http/blob/master/lib/mockRequest.js"
    click Res "https://github.com/eugef/node-mocks-http/blob/master/lib/mockResponse.js"
    click EXP_MAIN "https://github.com/eugef/node-mocks-http/blob/master/lib/express/mock-express.js"
    click EXP_APP "https://github.com/eugef/node-mocks-http/blob/master/lib/express/mock-application.js"
    click EXP_REQ "https://github.com/eugef/node-mocks-http/blob/master/lib/express/mock-request.js"
    click DEF "https://github.com/eugef/node-mocks-http/blob/master/lib/express/utils/define-getter.js"
    click NC_IN "https://github.com/eugef/node-mocks-http/blob/master/lib/node/_http_incoming.js"
    click NC_SR "https://github.com/eugef/node-mocks-http/blob/master/lib/node/_http_server.js"
    click NC_MAIN "https://github.com/eugef/node-mocks-http/blob/master/lib/node/http.js"
    click HEAD "https://github.com/eugef/node-mocks-http/blob/master/lib/headers.js"
    click UTIL "https://github.com/eugef/node-mocks-http/blob/master/lib/utils.js"
    click EM "https://github.com/eugef/node-mocks-http/blob/master/lib/mockEventEmitter.js"
    click WS "https://github.com/eugef/node-mocks-http/blob/master/lib/mockWritableStream.js"

    %% Styles
    classDef public fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef adapter fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef util fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
