@ahoo-wang/fetcher-decorator 0.5.0

package/README.zh-CN.md

@@ -0,0 +1,272 @@
+# @ahoo-wang/fetcher-decorator
+
+[![npm version](https://img.shields.io/npm/v/@ahoo-wang/fetcher-decorator.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-decorator)
+[![Build Status](https://github.com/Ahoo-Wang/fetcher/actions/workflows/ci.yml/badge.svg)](https://github.com/Ahoo-Wang/fetcher/actions)
+[![codecov](https://codecov.io/gh/Ahoo-Wang/fetcher/graph/badge.svg?token=JGiWZ52CvJ)](https://codecov.io/gh/Ahoo-Wang/fetcher)
+[![License](https://img.shields.io/npm/l/@ahoo-wang/fetcher-decorator.svg)](https://github.com/Ahoo-Wang/fetcher/blob/main/LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/@ahoo-wang/fetcher-decorator.svg)](https://www.npmjs.com/package/@ahoo-wang/fetcher-decorator)
+
+Fetcher HTTP 客户端的装饰器支持。使用 TypeScript 装饰器实现简洁、声明式的 API 服务定义。
+
+## 🌟 功能特性
+
+- **🎨 简洁的 API 定义**：使用直观的装饰器定义 HTTP 服务
+- **🧭 自动参数绑定**：路径、查询、头部和请求体参数自动绑定
+- **⏱️ 可配置超时**：支持每方法和每类的超时设置
+- **🔗 Fetcher 集成**：与 Fetcher 的命名 fetcher 系统无缝集成
+- **🛡️ TypeScript 支持**：完整的 TypeScript 类型定义
+- **⚡ 自动实现**：方法自动实现为 HTTP 调用
+- **📦 元数据系统**：丰富的元数据支持，用于高级定制
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 使用 npm
+npm install @ahoo-wang/fetcher-decorator
+
+# 使用 pnpm
+pnpm add @ahoo-wang/fetcher-decorator
+
+# 使用 yarn
+yarn add @ahoo-wang/fetcher-decorator
+```
+
+### 基本用法
+
+```typescript
+import { NamedFetcher, fetcherRegistrar } from '@ahoo-wang/fetcher';
+import {
+  api,
+  get,
+  post,
+  path,
+  query,
+  body,
+} from '@ahoo-wang/fetcher-decorator';
+
+// 创建并注册 fetcher
+const userFetcher = new NamedFetcher('user', {
+  baseURL: 'https://api.user-service.com',
+});
+
+// 使用装饰器定义服务类
+@api('/users', { fetcher: 'user', timeout: 10000 })
+class UserService {
+  @post('/', { timeout: 5000 })
+  createUser(@body() user: User): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+
+  @get('/{id}')
+  getUser(
+    @path('id') id: number,
+    @query('include') include: string,
+  ): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+
+// 使用服务
+const userService = new UserService();
+const response = await userService.createUser({ name: 'John' });
+```
+
+## 📚 API 参考
+
+### 类装饰器
+
+#### `@api(basePath, metadata)`
+
+为类定义 API 元数据。
+
+**参数：**
+
+- `basePath`: 类中所有端点的基础路径
+- `metadata`: API 的额外元数据
+  - `headers`: 类中所有请求的默认头部
+  - `timeout`: 类中所有请求的默认超时时间
+  - `fetcher`: 要使用的 fetcher 实例名称（默认：'default'）
+
+**示例：**
+
+```typescript
+
+@api('/api/v1', {
+  headers: { 'X-API-Version': '1.0' },
+  timeout: 5000,
+  fetcher: 'api',
+})
+class ApiService {
+  // ...
+}
+```
+
+### 方法装饰器
+
+#### `@get(path, metadata)`
+
+定义 GET 端点。
+
+#### `@post(path, metadata)`
+
+定义 POST 端点。
+
+#### `@put(path, metadata)`
+
+定义 PUT 端点。
+
+#### `@del(path, metadata)`
+
+定义 DELETE 端点。
+
+#### `@patch(path, metadata)`
+
+定义 PATCH 端点。
+
+#### `@head(path, metadata)`
+
+定义 HEAD 端点。
+
+#### `@options(path, metadata)`
+
+定义 OPTIONS 端点。
+
+**通用参数：**
+
+- `path`: 端点路径（相对于类基础路径）
+- `metadata`: 端点的额外元数据
+  - `headers`: 请求的头部
+  - `timeout`: 请求的超时时间
+  - `fetcher`: 要使用的 fetcher 实例名称
+
+**示例：**
+
+```typescript
+class UserService {
+  @get('/{id}', { timeout: 3000 })
+  getUser(@path('id') id: number): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+
+  @post('/', { headers: { 'Content-Type': 'application/json' } })
+  createUser(@body() user: User): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
+### 参数装饰器
+
+#### `@path(name)`
+
+定义路径参数。
+
+**参数：**
+
+- `name`: 参数名称（在路径模板中使用）
+
+#### `@query(name)`
+
+定义查询参数。
+
+**参数：**
+
+- `name`: 参数名称（在查询字符串中使用）
+
+#### `@body()`
+
+定义请求体。
+
+#### `@header(name)`
+
+定义头部参数。
+
+**参数：**
+
+- `name`: 头部名称
+
+**示例：**
+
+```typescript
+class UserService {
+  @get('/search')
+  searchUsers(
+    @query('q') query: string,
+    @query('limit') limit: number,
+    @header('Authorization') auth: string,
+  ): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+
+  @put('/{id}')
+  updateUser(@path('id') id: number, @body() user: User): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
+## 🛠️ 高级用法
+
+### 继承支持
+
+```typescript
+
+@api('/base')
+class BaseService {
+  @get('/status')
+  getStatus(): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+
+@api('/users')
+class UserService extends BaseService {
+  @get('/{id}')
+  getUser(@path('id') id: number): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
+### 复杂参数处理
+
+```typescript
+
+@api('/api')
+class ComplexService {
+  @post('/batch')
+  batchOperation(
+    @body() items: Item[],
+    @header('X-Request-ID') requestId: string,
+    @query('dryRun') dryRun: boolean = false,
+  ): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
+## 🧪 测试
+
+```bash
+# 运行测试
+pnpm test
+
+# 运行带覆盖率的测试
+pnpm test --coverage
+```
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [贡献指南](https://github.com/Ahoo-Wang/fetcher/blob/main/CONTRIBUTING.md) 了解更多详情。
+
+## 📄 许可证
+
+Apache-2.0
+
+---
+
+<p align="center">
+  Fetcher 生态系统的一部分
+</p>

package/dist/apiDecorator.d.ts

@@ -0,0 +1,42 @@
+import { HeadersCapable, TimeoutCapable } from '@ahoo-wang/fetcher';
+/**
+ * Metadata for class-level API configuration
+ *
+ * This interface defines the configuration options that can be applied to an entire API class.
+ * These settings will be used as defaults for all endpoints within the class unless overridden
+ * at the method level.
+ */
+export interface ApiMetadata extends TimeoutCapable, HeadersCapable {
+    /**
+     * Base path for all endpoints in the class
+     *
+     * This path will be prepended to all endpoint paths defined in the class.
+     * For example, if basePath is '/api/v1' and an endpoint has path '/users',
+     * the full path will be '/api/v1/users'.
+     */
+    basePath?: string;
+    /**
+     * Default headers for all requests in the class
+     *
+     * These headers will be included in every request made by methods in this class.
+     * They can be overridden or extended at the method level.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Default timeout for all requests in the class (in milliseconds)
+     *
+     * This timeout value will be applied to all requests made by methods in this class.
+     * Individual methods can specify their own timeout values to override this default.
+     */
+    timeout?: number;
+    /**
+     * Name of the fetcher instance to use, default: 'default'
+     *
+     * This allows you to specify which fetcher instance should be used for requests
+     * from this API class. The fetcher must be registered with the FetcherRegistrar.
+     */
+    fetcher?: string;
+}
+export declare const API_METADATA_KEY: unique symbol;
+export declare function api(basePath?: string, metadata?: Omit<ApiMetadata, 'basePath'>): (constructor: Function) => void;
+//# sourceMappingURL=apiDecorator.d.ts.map

package/dist/apiDecorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiDecorator.d.ts","sourceRoot":"","sources":["../src/apiDecorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpE,OAAO,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc,EAAE,cAAc;IACjE;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,gBAAgB,eAAyB,CAAC;AAgEvD,wBAAgB,GAAG,CACjB,QAAQ,GAAE,MAAW,EACrB,QAAQ,GAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAM,IAE5B,aAAa,QAAQ,UActC"}

package/dist/endpointDecorator.d.ts

@@ -0,0 +1,58 @@
+import { HttpMethod } from '@ahoo-wang/fetcher';
+import { ApiMetadata } from './apiDecorator';
+/**
+ * Metadata for HTTP endpoints
+ *
+ * This interface defines the configuration options for individual HTTP endpoints (methods).
+ * These settings will override any corresponding class-level settings from ApiMetadata.
+ */
+export interface EndpointMetadata extends ApiMetadata {
+    /**
+     * HTTP method for the endpoint
+     *
+     * Specifies the HTTP verb to be used for this endpoint (GET, POST, PUT, DELETE, etc.)
+     */
+    method: HttpMethod;
+    /**
+     * Path for the endpoint (relative to class base path)
+     *
+     * This path will be appended to the class's base path to form the complete URL.
+     * Path parameters can be specified using curly braces, e.g., '/users/{id}'
+     */
+    path?: string;
+}
+export declare const ENDPOINT_METADATA_KEY: unique symbol;
+export type MethodEndpointMetadata = Omit<EndpointMetadata, 'method' | 'path'>;
+/**
+ * Decorator factory for defining HTTP endpoints
+ *
+ * This function creates a decorator that can be used to define HTTP endpoints
+ * on class methods. It stores metadata about the endpoint that will be used
+ * to generate the actual HTTP request.
+ *
+ * @param method - The HTTP method for this endpoint
+ * @param path - The path for this endpoint (relative to class base path)
+ * @param metadata - Additional endpoint metadata (headers, timeout, etc.)
+ * @returns A method decorator function
+ *
+ * @example
+ * ```typescript
+ * @api('/api/v1')
+ * class UserService {
+ *   @endpoint(HttpMethod.GET, '/users/{id}')
+ *   getUser(@path('id') id: string): Promise<Response> {
+ *     // Implementation will be generated automatically
+ *     throw autoGeneratedError();
+ *   }
+ * }
+ * ```
+ */
+export declare function endpoint(method: HttpMethod, path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function get(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function post(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function put(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function del(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function patch(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function head(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+export declare function options(path?: string, metadata?: MethodEndpointMetadata): (target: any, propertyKey: string) => void;
+//# sourceMappingURL=endpointDecorator.d.ts.map

package/dist/endpointDecorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpointDecorator.d.ts","sourceRoot":"","sources":["../src/endpointDecorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,qBAAqB,eAA8B,CAAC;AAEjE,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,MAAW,EACjB,QAAQ,GAAE,sBAA2B,IAErB,QAAQ,GAAG,EAAE,aAAa,MAAM,KAAG,IAAI,CAcxD;AAED,wBAAgB,GAAG,CAAC,IAAI,GAAE,MAAW,EAAE,QAAQ,GAAE,sBAA2B,YAhBlD,GAAG,eAAe,MAAM,KAAG,IAAI,CAkBxD;AAED,wBAAgB,IAAI,CAAC,IAAI,GAAE,MAAW,EAAE,QAAQ,GAAE,sBAA2B,YApBnD,GAAG,eAAe,MAAM,KAAG,IAAI,CAsBxD;AAED,wBAAgB,GAAG,CAAC,IAAI,GAAE,MAAW,EAAE,QAAQ,GAAE,sBAA2B,YAxBlD,GAAG,eAAe,MAAM,KAAG,IAAI,CA0BxD;AAED,wBAAgB,GAAG,CAAC,IAAI,GAAE,MAAW,EAAE,QAAQ,GAAE,sBAA2B,YA5BlD,GAAG,eAAe,MAAM,KAAG,IAAI,CA8BxD;AAED,wBAAgB,KAAK,CACnB,IAAI,GAAE,MAAW,EACjB,QAAQ,GAAE,sBAA2B,YAlCb,GAAG,eAAe,MAAM,KAAG,IAAI,CAqCxD;AAED,wBAAgB,IAAI,CAAC,IAAI,GAAE,MAAW,EAAE,QAAQ,GAAE,sBAA2B,YAvCnD,GAAG,eAAe,MAAM,KAAG,IAAI,CAyCxD;AAED,wBAAgB,OAAO,CACrB,IAAI,GAAE,MAAW,EACjB,QAAQ,GAAE,sBAA2B,YA7Cb,GAAG,eAAe,MAAM,KAAG,IAAI,CAgDxD"}

package/dist/generated.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AutoGenerated is a custom error class that indicates
+ * a method implementation will be automatically generated.
+ *
+ * @example
+ * ```
+ *     @post()
+ *     createUser(@body() user: User):Promise<Response> {
+ *         throw autoGeneratedError();
+ *     }
+ * ```
+ */
+/**
+ * AutoGenerated is a custom error class that indicates
+ * a method implementation will be automatically generated.
+ */
+export declare class AutoGenerated extends Error {
+    constructor();
+}
+/**
+ * Factory function to create an AutoGenerated instance.
+ *
+ * @returns {AutoGenerated} A new AutoGenerated instance
+ */
+export declare const autoGeneratedError: () => AutoGenerated;
+//# sourceMappingURL=generated.d.ts.map

package/dist/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../src/generated.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;;CAKvC;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,aAErC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './apiDecorator';
+export * from './endpointDecorator';
+export * from './parameterDecorator';
+export * from './reflection';
+export * from './requestExecutor';
+export * from './generated';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC"}