API Overview

The Fetcher ecosystem exposes APIs across multiple packages, each addressing a specific concern in the HTTP client lifecycle. This page provides a summary of every public API surface with quick navigation links.

Package API Summary

Package	npm Name	Primary Exports	Description
Fetcher	@ahoo-wang/fetcher	Fetcher, NamedFetcher, FetcherRegistrar, InterceptorManager	Core HTTP client with interceptor pipeline
Decorator	@ahoo-wang/fetcher-decorator	@api, @get, @post, @put, @del, @patch, @path, @query, @header, @body	Declarative API client via decorators
React Hooks	@ahoo-wang/fetcher-react	useFetcher, useQuery, useExecutePromise, createQueryApiHooks	React hooks for data fetching
EventStream	@ahoo-wang/fetcher-eventstream	toJsonServerSentEventStream, EventStreamResultExtractor	SSE and LLM streaming support
EventBus	@ahoo-wang/fetcher-eventbus	EventBus, TypedEventBus, ParallelTypedEventBus, SerialTypedEventBus	Type-safe event bus
OpenAPI	@ahoo-wang/fetcher-openapi	TypeScript interfaces for OpenAPI 3.x	Spec type definitions
Storage	@ahoo-wang/fetcher-storage	Storage abstractions	Browser storage wrappers
CoSec	@ahoo-wang/fetcher-cosec	Security interceptors	Authentication and authorization
Wow	@ahoo-wang/fetcher-wow	CQRS command/query clients	DDD + Event Sourcing support
Viewer	@ahoo-wang/fetcher-viewer	React + Ant Design components	API documentation viewer
Generator	@ahoo-wang/fetcher-generator	fetcher-generator CLI	OpenAPI to TypeScript code generation

Import Patterns

Core Fetcher

import { Fetcher, NamedFetcher, fetcherRegistrar } from '@ahoo-wang/fetcher';
import { HttpMethod, ResultExtractors } from '@ahoo-wang/fetcher';
import type { FetchRequest, FetchExchange, FetcherOptions } from '@ahoo-wang/fetcher';

Decorator

import 'reflect-metadata'; // Required before any decorator usage
import { api, get, post, put, del, patch } from '@ahoo-wang/fetcher-decorator';
import { path, query, header, body, request, attribute } from '@ahoo-wang/fetcher-decorator';
import { autoGeneratedError } from '@ahoo-wang/fetcher-decorator';

React Hooks

import { useFetcher, useFetcherQuery } from '@ahoo-wang/fetcher-react';
import { useQuery, useExecutePromise, usePromiseState } from '@ahoo-wang/fetcher-react';
import { createQueryApiHooks } from '@ahoo-wang/fetcher-react';

EventStream (side-effect import)

// Importing this module patches Response.prototype with eventStream() and jsonEventStream()
import '@ahoo-wang/fetcher-eventstream';

EventBus

import { EventBus, ParallelTypedEventBus, SerialTypedEventBus } from '@ahoo-wang/fetcher-eventbus';
import type { EventHandler } from '@ahoo-wang/fetcher-eventbus';

Architecture Diagram

graph TB
    subgraph sg_1 ["Application Layer"]
        REACT["@ahoo-wang/fetcher-react"]
        VIEWER["@ahoo-wang/fetcher-viewer"]
        GENERATOR["@ahoo-wang/fetcher-generator"]
    end

    subgraph sg_2 ["Service Layer"]
        DECO["@ahoo-wang/fetcher-decorator"]
        WOW["@ahoo-wang/fetcher-wow"]
        OPENAI["@ahoo-wang/fetcher-openai"]
        COSEC["@ahoo-wang/fetcher-cosec"]
    end

    subgraph sg_3 ["Core Layer"]
        FETCHER["@ahoo-wang/fetcher"]
        ESTREAM["@ahoo-wang/fetcher-eventstream"]
        EBUS["@ahoo-wang/fetcher-eventbus"]
        STORAGE["@ahoo-wang/fetcher-storage"]
        OPENAPI["@ahoo-wang/fetcher-openapi"]
    end

    REACT --> FETCHER
    REACT --> ESTREAM
    REACT --> EBUS
    REACT --> STORAGE
    REACT --> WOW
    REACT --> COSEC
    VIEWER --> REACT
    VIEWER --> OPENAPI
    DECO --> FETCHER
    WOW --> FETCHER
    WOW --> ESTREAM
    WOW --> DECO
    OPENAI --> FETCHER
    OPENAI --> ESTREAM
    OPENAI --> DECO
    COSEC --> FETCHER
    COSEC --> EBUS
    COSEC --> STORAGE
    ESTREAM --> FETCHER
    EBUS --> FETCHER
    STORAGE --> EBUS

    style FETCHER fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style DECO fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style REACT fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style ESTREAM fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style EBUS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style STORAGE fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style OPENAPI fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style VIEWER fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style GENERATOR fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style WOW fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style OPENAI fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style COSEC fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

Request Lifecycle

sequenceDiagram
autonumber

    participant App as Application
    participant Fetcher as Fetcher
    participant IM as InterceptorManager
    participant ReqInt as Request Interceptors
    participant ResInt as Response Interceptors
    participant ErrInt as Error Interceptors

    App->>Fetcher: fetch(url, request, options)
    Fetcher->>Fetcher: resolveExchange()
    Fetcher->>IM: exchange(fetchExchange)
    IM->>ReqInt: intercept(exchange)
    ReqInt-->>IM: modified exchange
    IM->>ResInt: intercept(exchange)
    ResInt-->>IM: validated exchange
    IM-->>Fetcher: processed exchange
    Fetcher->>Fetcher: extractResult()
    Fetcher-->>App: result
    Note over IM,ErrInt: On error: error interceptors run
    IM->>ErrInt: intercept(exchange)
    ErrInt-->>IM: handled or re-thrown

Interceptor Pipeline Detail

graph LR
    subgraph sg_1 ["Request Phase"]
        R1["RequestBodyInterceptor<br>(order: MIN_SAFE + STEP)"]
        R2["UrlResolveInterceptor<br>(near MAX_SAFE)"]
        R3["FetchInterceptor<br>(MAX_SAFE - STEP)"]
    end

    subgraph sg_2 ["Response Phase"]
        S1["ValidateStatusInterceptor<br>(MAX_SAFE - STEP)"]
        S2["Custom Response<br>Interceptors"]
    end

    subgraph sg_3 ["Error Phase"]
        E1["Custom Error<br>Interceptors"]
    end

    R1 --> R2 --> R3
    R3 -->|"success"| S1
    S1 --> S2
    R3 -->|"error"| E1
    S1 -->|"validation error"| E1

    style R1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style R2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style R3 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style S1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style S2 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style E1 fill:#2d333b,stroke:#6d5dfc,color:#e6edf3

Related Pages

• Fetcher Client API -- Core HTTP client class and options
• Decorators API -- Declarative API service definitions
• React Hooks API -- Data fetching hooks for React
• Type Definitions -- TypeScript interfaces and types
• Testing Overview -- Testing strategy and tools