FetchX

A modern, lightweight HTTP client library built on the native fetch API with an axios-like interface. Perfect for TypeScript projects that need a reliable, type-safe HTTP client.

基于原生 fetch API 构建的现代化、轻量级 HTTP 客户端库，提供类似 axios 的接口。完美适用于需要可靠、类型安全的 HTTP 客户端的 TypeScript 项目。

🌐 Language / 语言

Choose your preferred language:

选择您偏好的语言：

🇺🇸 English

📖 Read English Documentation

A modern, lightweight HTTP client library built on the native fetch API with an axios-like interface. Perfect for TypeScript projects that need a reliable, type-safe HTTP client.

Key Features:

• 🚀 Modern: Built on native fetch API, no external dependencies
• 🔄 Axios Compatible: Easy migration from axios with familiar API
• 🛡️ Type Safe: Full TypeScript support with comprehensive type definitions
• 🔧 Interceptors: Powerful request/response interceptor system
• ⏱️ Timeout Control: Built-in timeout with AbortController
• 🚫 Request Cancellation: Full AbortController support with isCancel utility
• 📊 Progress Tracking: Upload/download progress monitoring (v0.2.0+)
• 🔌 Plugin System: Extensible plugin architecture for advanced features (v0.2.0+)
• 📦 Lightweight: Zero runtime dependencies, minimal bundle size

🇨🇳 中文

📖 阅读中文文档

基于原生 fetch API 构建的现代化、轻量级 HTTP 客户端库，提供类似 axios 的接口。完美适用于需要可靠、类型安全的 HTTP 客户端的 TypeScript 项目。

主要特性:

• 🚀 现代化: 基于原生 fetch API，无外部依赖
• 🔄 Axios 兼容: 从 axios 轻松迁移，熟悉的 API
• 🛡️ 类型安全: 完整的 TypeScript 支持，全面的类型定义
• 🔧 拦截器: 强大的请求/响应拦截器系统
• ⏱️ 超时控制: 基于 AbortController 的内置超时
• 🚫 请求取消: 完整的 AbortController 支持和 isCancel 工具函数
• 📊 进度追踪: 上传/下载进度监控 (v0.2.0+)
• 🔌 插件系统: 可扩展的插件架构，支持高级功能 (v0.2.0+)
• 📦 轻量级: 零运行时依赖，最小化包体积

📦 Installation / 安装

# Using pnpm (recommended) / 使用 pnpm（推荐）
pnpm add @petite-pluie/fetchx

# Using npm / 使用 npm
npm install @petite-pluie/fetchx

# Using yarn / 使用 yarn
yarn add @petite-pluie/fetchx

🚀 Quick Start / 快速开始

import { createFetchX, isCancel } from '@petite-pluie/fetchx';

// Create instance with configuration / 创建带配置的实例
const api = createFetchX({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Make requests with full TypeScript support / 使用完整的 TypeScript 支持发起请求
interface User {
  id: number;
  name: string;
  email: string;
}

const users = await api.get<User[]>('/users');
const newUser = await api.post<User>('/users', {
  name: 'John Doe', // 或 '张三'
  email: '[email protected]',
});

// Request cancellation / 请求取消
const controller = new AbortController();
try {
  const data = await api.get('/users', { signal: controller.signal });
} catch (error) {
  if (isCancel(error)) {
    console.log('Request cancelled / 请求已取消');
  }
}

📊 Progress Tracking / 进度追踪 (v0.2.0+)

import { createFetchX } from '@petite-pluie/fetchx';
import { uploadProgressPlugin } from '@petite-pluie/fetchx/plugins/upload-progress';

// Create instance with upload progress plugin / 创建带上传进度插件的实例
const api = createFetchX({
  baseURL: 'https://api.example.com',
  plugins: [uploadProgressPlugin()],
});

// Upload with progress / 带进度的上传
await api.post('/upload', fileData, {
  onUploadProgress: progress => {
    console.log(`Upload: ${progress.percentage}%`);
    console.log(`上传: ${progress.percentage}%`);
  },
});

// Download with progress / 带进度的下载（内置支持）
await api.get('/large-file', {
  onDownloadProgress: progress => {
    console.log(`Download: ${progress.percentage}%`);
    console.log(`下载: ${progress.percentage}%`);
  },
});

🤝 Contributing / 贡献

We welcome contributions! Please see our Contributing Guide for details.

我们欢迎贡献！详情请参阅我们的贡献指南。

Git Commit Convention / Git 提交规范

This project follows the Conventional Commits specification.

本项目遵循 Conventional Commits 规范。

Quick Start / 快速开始

# Use interactive commit (recommended) / 使用交互式提交（推荐）
pnpm commit

# Or use git commit directly / 或直接使用 git commit
git commit -m "feat(core): add request interceptor support"

For detailed information, see our Git Commit Guide.

详细信息请参阅我们的 Git 提交指南。

📄 License / 许可证

MIT License - see LICENSE file for details.

MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 Acknowledgments / 致谢

• Inspired by axios for its excellent API design

• Built on the modern fetch API

• Powered by TypeScript for type safety

• 感谢 axios 提供的优秀 API 设计灵感

• 基于现代化的 fetch API 构建

• 由 TypeScript 提供类型安全支持

📚 Documentation / 文档

• 📖 English Documentation
• 📖 中文文档
• ⚡ Quick Start / 快速入门
• 📚 User Guide / 使用指南
• 📋 API Reference
• 💡 Examples
• 🔌 Plugin System & Progress / 插件系统与进度追踪 (v0.2.0+)
• 🔧 Git Setup Guide
• 📝 Git Commit Guide
• 🤝 Contributing Guide
• 📋 Changelog