Fetcher

🛠️ Prerequisites

• Node.js >= 16
• pnpm >= 8

Install dependencies

pnpm install

🚀 Getting Started

📦 Installation

```shell

Install the core package

npm install @ahoo-wang/fetcher

Or install with all extensions including LLM streaming support

npm install @ahoo-wang/fetcher @ahoo-wang/fetcher-decorator @ahoo-wang/fetcher-eventbus @ahoo-wang/fetcher-eventstream @ahoo-wang/fetcher-cosec

Global Installation Generator CLI

npm install -g @ahoo-wang/fetcher-generator

Build all packages

pnpm build

Clean build artifacts

pnpm clean

⚡ Quick Examples

Basic HTTP Client

import { Fetcher } from '@ahoo-wang/fetcher';

// Create a fetcher instance
const fetcher = new Fetcher({
  baseURL: 'https://api.example.com',
  timeout: 5000,
});

// GET request with path and query parameters
const response = await fetcher.get('/users/{id}', {
  urlParams: {
    path: { id: 123 },
    query: { include: 'profile' },
  },
});
const userData = await response.json<User>();

// POST request with automatic JSON conversion
const createUserResponse = await fetcher.post('/users', {
  body: { name: 'John Doe', email: 'john@example.com' },
});

Declarative API Services

import { NamedFetcher } from '@ahoo-wang/fetcher';
import {
  api,
  get,
  post,
  path,
  query,
  body,
} from '@ahoo-wang/fetcher-decorator';

// Register a named fetcher
const apiFetcher = new NamedFetcher('api', {
  baseURL: 'https://api.example.com',
});

// Define service with decorators
@api('/users', { fetcher: 'api' })
class UserService {
  @get('/')
  getUsers(@query('limit') limit?: number): Promise<User[]> {
    throw autoGeneratedError(limit);
  }

  @post('/')
  createUser(@body() user: User): Promise<User> {
    throw autoGeneratedError(user);
  }

  @get('/{id}')
  getUser(@path('id') id: number): Promise<User> {
    throw autoGeneratedError(id);
  }
}

// Use the service
const userService = new UserService();
const users = await userService.getUsers(10);

OpenAPI Code Generator

```shell

🎯 Integration Test Examples

Explore comprehensive, production-ready implementations in our integration-test directory:

💾 [`@ahoo-wang/fetcher-storage`](./packages/storage) - Cross-Environment Storage

A lightweight, cross-environment storage library with key-based storage and automatic environment detection:

• 🌐 Cross-Environment Support: Consistent API for browser localStorage/sessionStorage and in-memory storage
• 📦 Ultra-Lightweight: Only ~1KB gzip - minimal footprint
• 🔔 Storage Change Events: Listen for storage changes with event-driven architecture
• 🔄 Automatic Environment Detection: Automatically selects appropriate storage with fallback
• 🛠️ Key-Based Storage: Efficient key-based storage with built-in caching and serialization
• 🔧 Custom Serialization: Support for custom serialization strategies (JSON, Identity)
• 📝 TypeScript Support: Full TypeScript definitions for type-safe storage operations

🎨 [`@ahoo-wang/fetcher-decorator`](./packages/decorator) - Declarative APIs

Transform your API interactions with clean, declarative service definitions:

• 🎨 Clean API Definitions: Define HTTP services using intuitive decorators
• 🧭 Automatic Parameter Binding: Path, query, header, and body parameters automatically bound
• ⏱️ Configurable Timeouts: Per-method and per-class timeout settings
• 🔗 Fetcher Integration: Seamless integration with Fetcher's named fetcher system
• ⚡ Automatic Implementation: Methods automatically implemented with HTTP calls
• 📦 Metadata System: Rich metadata support for advanced customization

🔧 [`@ahoo-wang/fetcher-generator`](./packages/generator) - OpenAPI Code Generator

A powerful TypeScript code generation tool that automatically generates type-safe API client code based on OpenAPI specifications. It is designed for general use cases and is also deeply optimized for the Wow Domain-Driven Design framework, providing native support for the CQRS architectural pattern.

• 🎯 OpenAPI 3.0+ Support: Full support for OpenAPI 3.0+ specifications (JSON/YAML)
• 📦 TypeScript Code Generation: Generates type-safe TypeScript interfaces, enums, and classes
• 🔧 CLI Tool: Easy-to-use command-line interface for code generation
• 🎨 Decorator-Based APIs: Generates decorator-based client classes for clean API interactions
• 📋 Comprehensive Models: Handles complex schemas including unions, intersections, enums, and references
• 🚀 Fetcher Integration: Seamlessly integrates with the Fetcher ecosystem packages
• 📊 Progress Logging: Friendly logging with progress indicators during generation
• 📁 Auto Index Generation: Automatically generates index.ts files for clean module organization
• 🌐 Remote Spec Support: Load OpenAPI specs directly from HTTP/HTTPS URLs
• 🎭 Event Streaming: Generates both regular and event-stream command clients
• 🏗️ Domain-Driven Design Support: Specialized support for Wow framework with aggregates, commands, queries, and events (CQRS patterns)

🤖 [`@ahoo-wang/fetcher-openai`](./packages/openai) - OpenAI API Client

Type-safe OpenAI API client with native streaming support for chat completions:

• 🎯 Type-Safe OpenAI Integration: Complete TypeScript support for OpenAI Chat Completions API
• 📡 Native Streaming Support: Built-in support for streaming chat completions with Server-Sent Events
• 🔧 Declarative API: Clean, decorator-based API for OpenAI interactions
• ⚡ Fetcher Integration: Seamlessly integrates with the Fetcher ecosystem

Generate TypeScript code from OpenAPI specifications

fetcher-generator generate -i ./openapi-spec.json -o ./src/generated

🎯 [`@ahoo-wang/fetcher`](./packages/fetcher) - The Foundation

The lightweight core that powers the entire ecosystem:

- ⚡ Ultra-Lightweight: Only 3KiB min+gzip - smaller than most alternatives - 🧭 Path & Query Parameters: Built-in support for path ({id}/:id) and query parameters - 🔗 Interceptor System: Request, response, and error interceptors with ordered execution for flexible middleware patterns - ⏱️ Timeout Control: Configurable request timeouts with proper error handling - 🔄 Fetch API Compatible: Fully compatible with the native Fetch API - 🛡️ TypeScript Support: Complete TypeScript definitions for type-safe development - 🧩 Modular Architecture: Lightweight core with optional extension packages - 📦 Named Fetcher Support: Automatic registration and retrieval of fetcher instances - ⚙️ Default Fetcher: Pre-configured default fetcher instance for quick start

🎯 [`@ahoo-wang/fetcher-eventbus`](./packages/eventbus) - Event Bus System

A TypeScript event bus library providing multiple implementations for handling events: serial execution, parallel execution, and cross-tab broadcasting.

• 🔄 Serial Execution: Execute event handlers in order of priority
• ⚡ Parallel Execution: Run event handlers concurrently for better performance
• 🌐 Cross-Tab Broadcasting: Broadcast events across browser tabs using BroadcastChannel API or localStorage fallback
• 💾 Storage Messenger: Direct cross-tab messaging with TTL and cleanup
• 📦 Generic Event Bus: Manage multiple event types with lazy loading
• 🔧 Type-Safe: Full TypeScript support with strict typing
• 🧵 Async Support: Handle both synchronous and asynchronous event handlers
• 🔄 Once Handlers: Support for one-time event handlers
• 🛡️ Error Handling: Robust error handling with logging
• 🔌 Auto Fallback: Automatically selects best available cross-tab communication method

📡 [`@ahoo-wang/fetcher-eventstream`](./packages/eventstream) - Real-Time Streaming & LLM Support

Power your real-time applications with Server-Sent Events support, specially designed for Large Language Model streaming APIs:

- 📡 Event Stream Conversion: Converts text/event-stream responses to async generators of ServerSentEvent objects - 🔌 Side-Effect Module Import: Automatically adds eventStream() and jsonEventStream() methods to the global Response.prototype for responses with text/event-stream content type - 📋 SSE Parsing: Parses Server-Sent Events according to the specification, including data, event, id, and retry fields - 🔄 Streaming Support: Handles chunked data and multi-line events correctly - 💬 Comment Handling: Properly ignores comment lines (lines starting with :) as per SSE specification - 🛡️ TypeScript Support: Complete TypeScript type definitions - ⚡ Performance Optimized: Efficient parsing and streaming for high-performance applications - 🤖 LLM Streaming Ready: Native support for streaming responses from popular LLM APIs like OpenAI GPT, Claude, etc.

🧩 [`@ahoo-wang/fetcher-wow`](./packages/wow) - CQRS/DDD Framework Support

First-class integration with the Wow CQRS/DDD framework:

- 🔄 CQRS Pattern Implementation: First-class support for Command Query Responsibility Segregation architectural pattern - 🧱 DDD Primitives: Essential Domain-Driven Design building blocks including aggregates, events, and value objects - 📦 Complete TypeScript Support: Full type definitions for all Wow framework entities including commands, events, and queries - 📡 Real-time Event Streaming: Built-in support for Server-Sent Events to receive real-time command results and data updates - 🚀 Command Client: High-level client for sending commands to Wow services with both synchronous and streaming responses - 🔍 Powerful Query DSL: Rich query condition builder with comprehensive operator support for complex querying - 🔍 Query Clients: Specialized clients for querying snapshot and event stream data with comprehensive query operations: - Counting resources - Listing resources - Streaming resources as Server-Sent Events - Paging resources - Retrieving single resources

🔐 [`@ahoo-wang/fetcher-cosec`](./packages/cosec) - Enterprise Security

Secure your applications with integrated authentication:

• 🔐 Automatic Authentication: Automatic CoSec authentication headers
• 📱 Device Management: Device ID management with localStorage persistence
• 🔄 Token Refresh: Automatic token refresh based on response codes (401)
• 🌈 Request Tracking: Unique request ID generation for tracking
• 💾 Token Storage: Secure token storage management

📦 Package Ecosystem

Run integration tests

#pnpm test:it ```