|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Structure |
| 6 | + |
| 7 | +This is a TypeScript monorepo for **HTTP Service** - a unified HTTP request library for browser and server environments. Uses pnpm workspaces with the following key packages: |
| 8 | + |
| 9 | +- `packages/http-svc/` - Main HTTP service library |
| 10 | +- `packages/middleware/` - Base middleware interfaces |
| 11 | +- `packages/server-fetch/` - Server-side fetch implementation |
| 12 | +- `packages/xhr/` - XHR-based middleware |
| 13 | +- `docs/` - VitePress documentation |
| 14 | +- `server/` - Test server (Koa-based) |
| 15 | + |
| 16 | +## Development Commands |
| 17 | + |
| 18 | +### Interactive Development |
| 19 | + |
| 20 | +- `pnpm start` - Interactive package selector for running dev scripts |
| 21 | +- `pnpm dev` - Run development server for selected package |
| 22 | +- `pnpm build` - Build selected package |
| 23 | + |
| 24 | +### Core Package (http-svc) |
| 25 | + |
| 26 | +- `pnpm test` - Run Jest tests |
| 27 | +- `pnpm build` - Dual build (modern ES2018+ and legacy ES2015+) |
| 28 | +- `pnpm build:modern` - Modern ES build only |
| 29 | +- `pnpm build:legacy` - Legacy ES2015 build only |
| 30 | + |
| 31 | +### Documentation |
| 32 | + |
| 33 | +- `pnpm docs:dev` - Start VitePress development server |
| 34 | +- `pnpm docs:build` - Build documentation site |
| 35 | + |
| 36 | +### Package Management |
| 37 | + |
| 38 | +- `pnpm create` - Create new packages |
| 39 | +- `pnpm pub` - Interactive publishing workflow |
| 40 | + |
| 41 | +## Architecture |
| 42 | + |
| 43 | +The HTTP Service follows a **middleware-based request pipeline** pattern similar to Koa.js: |
| 44 | + |
| 45 | +### Core Components |
| 46 | + |
| 47 | +- **HttpService** (`/packages/http-svc/src/core.ts`) - Main service class with three control units: |
| 48 | + - `AssembleControl` - Middleware assembly and dispatch |
| 49 | + - `ConfigControl` - Per-request configuration context |
| 50 | + - `RequestControl` - Request execution management |
| 51 | + |
| 52 | +### Built-in Middleware Stack |
| 53 | + |
| 54 | +Located in `/packages/http-svc/src/built-in/`: |
| 55 | + |
| 56 | +- `HttpSvcFetch` - Core fetch implementation |
| 57 | +- `HttpSvcSpray` - Request optimization |
| 58 | +- `HttpSvcRetry` - Retry logic |
| 59 | +- `HttpSvcCache` - Caching mechanism |
| 60 | +- `HttpSvcXsrf` - CSRF protection |
| 61 | +- Plus utility middlewares for timeout, body processing, logging |
| 62 | + |
| 63 | +### Key Features |
| 64 | + |
| 65 | +- Fetch API-based core with fallback to XHR |
| 66 | +- Dual environment support (browser/Node.js) |
| 67 | +- TypeScript-first with comprehensive type definitions |
| 68 | +- Extensible middleware system |
| 69 | +- Dual module builds (ESM/CJS) |
| 70 | + |
| 71 | +## Build System |
| 72 | + |
| 73 | +- **Build Tool**: Vite with dual-target configuration |
| 74 | +- **Output**: Modern (.mjs) and legacy (.cjs) builds for maximum compatibility |
| 75 | +- **TypeScript**: Strict mode enabled with comprehensive type checking |
| 76 | +- **Module Formats**: Both ESM and CommonJS supported |
| 77 | + |
| 78 | +## Testing |
| 79 | + |
| 80 | +- **Framework**: Jest with ts-jest preset |
| 81 | +- **Location**: `/packages/http-svc/src/__tests__/` |
| 82 | +- **Pattern**: `**/*.spec.ts` |
| 83 | +- Run tests with `pnpm test` in the http-svc package |
| 84 | + |
| 85 | +## Code Quality |
| 86 | + |
| 87 | +- **ESLint**: TypeScript configuration with Prettier integration |
| 88 | +- **Line Length**: 140 characters maximum |
| 89 | +- **Formatting**: Prettier for consistent code style |
0 commit comments