# supermacro/neverthrow architecture

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

- Interactive diagram: https://gitdiagram.com/supermacro/neverthrow
- Repository: https://github.com/supermacro/neverthrow

## Overview

The neverthrow project is a TypeScript library designed to provide an expressive “Result” type to encode failures without throwing exceptions. It exposes both synchronous (Result) and asynchronous (ResultAsync) APIs, along with a set of utility functions (such as fromThrowable, safeTry, etc.) that allow library consumers to work with error handling in a more controlled, composable way.

##### Main Library Interface
- At the top level, show a “NeverThrow Library” component that represents the public API.
- That the library is intended for error handling alternatives by wrapping values in Ok/Err constructs.

##### Synchronous API Components
- A “Result” component (with sub-components “Ok” and “Err”).
- Utility methods like Result.fromThrowable and Result.combine as functions attached to the Result component.
- That the “Result” API encapsulates error and value handling for synchronous use cases.

##### Asynchronous API Components
- A “ResultAsync” component that wraps asynchronous operations in a thenable object.
- Within that component, list its methods (map, mapErr, unwrapOr, andThen, orElse, match, andTee/orTee variants, asyncAndThrough, and its combine functions).
- Make it clear that ResultAsync is built to mirror the synchronous API but works with Promises, bridging native async behavior.

##### Internal and Utility Modules
- An “_internals” component (or module) that contains helper modules (error.ts, utils.ts). This is the backbone that supports the implementation of the Result logic.
- Optionally link the Utility functions to both the synchronous and asynchronous components, indicating that these are common helper functions used internally or available for consumers.

##### Testing and Build Infrastructure
- A note on the supporting configuration files (like package.json, tsconfig.json, Rollup, ESLint, etc.) that assist with linting, testing, and bundling, even though they are not “runtime” components in the library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top level Public API and Consumer
    A["NeverThrow Library (Public API)"]:::public
    M["Consumer Code"]:::public

    %% Synchronous API Subgraph
    subgraph "Synchronous API"
        B["Result (Sync)"]:::sync
        C["Ok & Err"]:::sync
        D["Methods: map, mapErr, unwrapOr, andThen, orElse, match, asyncAndThen"]:::sync
        E["Utilities: fromThrowable, combine"]:::sync
        B --> C
        B --> D
        B --> E
    end

    %% Asynchronous API Subgraph
    subgraph "Asynchronous API"
        F["ResultAsync (Async)"]:::async
        G["Methods: map, mapErr, unwrapOr, andThen, orElse, match, andTee, asyncAndThrough, combine"]:::async
    end

    %% Internal Helpers Subgraph
    subgraph "Internal Helpers"
        H["Error Internals"]:::internal
        I["Utility Functions"]:::internal
    end

    %% Common Utilities for Consumers & Internals
    J["Utilities Functions (safeTry, fromPromise, fromSafePromise, fromAsyncThrowable)"]:::internal

    %% Testing Suite and Build/Config
    K["Tests Suite"]:::test
    L["Build & Config (package.json, tsconfig.json, rollup.config.mjs, .eslintrc.js)"]:::config

    %% Data Flow Connections
    M -->|"imports"| A
    A -->|"exposes"| B
    A -->|"exposes"| F
    M -->|"creates Ok/Err"| B
    M -->|"handles async"| F

    %% Internal Utilization and Data Flow within APIs
    B -->|"calls internal"| H
    F -->|"calls internal"| I
    B -->|"utilizes"| J
    F -->|"utilizes"| J
    J -->|"supports"| H
    J -->|"supports"| I

    %% Method chaining flows
    D -->|"chains andThen"| B
    G -->|"chains andThen"| F

    %% External validations and configurations
    A -->|"validated by"| K
    A -->|"configured by"| L

    %% Click Events for Component Mapping
    click A "https://github.com/supermacro/neverthrow/blob/master/src/index.ts"
    click B "https://github.com/supermacro/neverthrow/blob/master/src/result.ts"
    click F "https://github.com/supermacro/neverthrow/blob/master/src/result-async.ts"
    click H "https://github.com/supermacro/neverthrow/blob/master/src/_internals/error.ts"
    click I "https://github.com/supermacro/neverthrow/blob/master/src/_internals/utils.ts"
    click K "https://github.com/supermacro/neverthrow/tree/master/tests"

    %% Style Classes
    classDef public fill:#FCECC9,stroke:#000,stroke-width:2px;
    classDef sync fill:#C2E7DA,stroke:#000,stroke-width:2px;
    classDef async fill:#B5D6FF,stroke:#000,stroke-width:2px;
    classDef internal fill:#E3B7EB,stroke:#000,stroke-width:2px;
    classDef test fill:#D9EAD3,stroke:#000,stroke-width:2px;
    classDef config fill:#F9CB9C,stroke:#000,stroke-width:2px;
```
