@ahoo-wang/fetcher-decorator 0.6.0 → 0.6.5

package/README.md

@@ -6,6 +6,7 @@
 [![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)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher-decorator)](https://www.npmjs.com/package/@ahoo-wang/fetcher-decorator)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
 Decorator support for Fetcher HTTP client. Enables clean, declarative API service definitions using TypeScript
 decorators.
@@ -62,10 +63,7 @@ class UserService {
   }
 
   @get('/{id}')
-  getUser(
-    @path('id') id: number,
-    @query('include') include: string,
-  ): Promise<Response> {
+  getUser(@path() id: number, @query() include: string): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 }
@@ -147,7 +145,7 @@ Defines an OPTIONS endpoint.
 ```typescript
 class UserService {
   @get('/{id}', { timeout: 3000 })
-  getUser(@path('id') id: number): Promise<Response> {
+  getUser(@path() id: number): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 
@@ -162,31 +160,40 @@ class UserService {
 
 #### `@path(name)`
 
-Defines a path parameter.
+Defines a path parameter. The name is optional - if not provided, it will be automatically extracted from the method
+parameter name.
 
 **Parameters:**
 
-- `name`: Name of the parameter (used in the path template)
+- `name`: Name of the parameter (used in the path template, optional - auto-extracted if not provided)
 
 #### `@query(name)`
 
-Defines a query parameter.
+Defines a query parameter. The name is optional - if not provided, it will be automatically extracted from the method
+parameter name.
 
 **Parameters:**
 
-- `name`: Name of the parameter (used in the query string)
+- `name`: Name of the parameter (used in the query string, optional - auto-extracted if not provided)
 
 #### `@body()`
 
-Defines a request body.
+Defines a request body. Body parameters don't have names since there's only one body per request.
 
 #### `@header(name)`
 
-Defines a header parameter.
+Defines a header parameter. The name is optional - if not provided, it will be automatically extracted from the method
+parameter name.
 
 **Parameters:**
 
-- `name`: Name of the header
+- `name`: Name of the header (optional - auto-extracted if not provided)
+
+#### `@request()`
+
+Defines a request parameter that will be used as the base request object. This allows you to pass a complete
+FetcherRequest
+object to customize the request configuration.
 
 **Example:**
 
@@ -195,14 +202,19 @@ class UserService {
   @get('/search')
   searchUsers(
     @query('q') query: string,
-    @query('limit') limit: number,
+    @query() limit: number,
     @header('Authorization') auth: string,
   ): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 
+  @post('/users')
+  createUsers(@request() request: FetcherRequest): Promise<Response> {
+    throw new Error('Implementation will be generated automatically.');
+  }
+
   @put('/{id}')
-  updateUser(@path('id') id: number, @body() user: User): Promise<Response> {
+  updateUser(@path() id: number, @body() user: User): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 }
@@ -224,7 +236,7 @@ class BaseService {
 @api('/users')
 class UserService extends BaseService {
   @get('/{id}')
-  getUser(@path('id') id: number): Promise<Response> {
+  getUser(@path() id: number): Promise<Response> {
     throw new Error('Implementation will be generated automatically.');
   }
 }
@@ -239,8 +251,35 @@ class ComplexService {
   batchOperation(
     @body() items: Item[],
     @header('X-Request-ID') requestId: string,
-    @query('dryRun') dryRun: boolean = false,
+    @query() dryRun: boolean = false,
+  ): Promise<Response> {
+    throw new Error('Implementation will be generated automatically.');
+  }
+}
+```
+
+### Request Merging
+
+When using the `@request()` decorator, the provided `FetcherRequest` object is merged with endpoint-specific
+configuration using a sophisticated merging strategy:
+
+- **Nested objects** (path, query, headers) are recursively merged, with parameter values taking precedence
+- **Primitive values** (method, body, timeout, signal) from the parameter request override endpoint values
+- **Empty objects** are handled gracefully, falling back to endpoint configuration
+
+```typescript
+
+@api('/users')
+class UserService {
+  @post('/')
+  createUsers(
+    @body() user: User,
+    @request() request: FetcherRequest,
   ): Promise<Response> {
+    // The final request will merge:
+    // - Endpoint method (POST)
+    // - Body parameter (user object)
+    // - Any configuration from the request parameter
     throw new Error('Implementation will be generated automatically.');
   }
 }

package/README.zh-CN.md

@@ -6,6 +6,7 @@
 [![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)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/%40ahoo-wang%2Ffetcher-decorator)](https://www.npmjs.com/package/@ahoo-wang/fetcher-decorator)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Ahoo-Wang/fetcher)
 
 Fetcher HTTP 客户端的装饰器支持。使用 TypeScript 装饰器实现简洁、声明式的 API 服务定义。
 
@@ -61,10 +62,7 @@ class UserService {
   }
 
   @get('/{id}')
-  getUser(
-    @path('id') id: number,
-    @query('include') include: string,
-  ): Promise<Response> {
+  getUser(@path() id: number, @query() include: string): Promise<Response> {
     throw new Error('实现将自动生成');
   }
 }
@@ -146,7 +144,7 @@ class ApiService {
 ```typescript
 class UserService {
   @get('/{id}', { timeout: 3000 })
-  getUser(@path('id') id: number): Promise<Response> {
+  getUser(@path() id: number): Promise<Response> {
     throw new Error('实现将自动生成');
   }
 
@@ -161,31 +159,35 @@ class UserService {
 
 #### `@path(name)`
 
-定义路径参数。
+定义路径参数。名称是可选的 - 如果未提供，将使用反射从方法参数名自动提取。
 
 **参数：**
 
-- `name`: 参数名称（在路径模板中使用）
+- `name`: 参数名称（在路径模板中使用，可选 - 如果未提供则自动提取）
 
 #### `@query(name)`
 
-定义查询参数。
+定义查询参数。名称是可选的 - 如果未提供，将使用反射从方法参数名自动提取。
 
 **参数：**
 
-- `name`: 参数名称（在查询字符串中使用）
+- `name`: 参数名称（在查询字符串中使用，可选 - 如果未提供则自动提取）
 
 #### `@body()`
 
-定义请求体。
+定义请求体。请求体参数没有名称，因为每个请求只有一个请求体。
 
 #### `@header(name)`
 
-定义头部参数。
+定义头部参数。名称是可选的 - 如果未提供，将使用反射从方法参数名自动提取。
 
 **参数：**
 
-- `name`: 头部名称
+- `name`: 头部名称（可选 - 如果未提供则自动提取）
+
+#### `@request()`
+
+定义请求参数，将用作基础请求对象。这允许您传递一个完整的 FetcherRequest 对象来自定义请求配置。
 
 **示例：**
 
@@ -194,12 +196,17 @@ class UserService {
   @get('/search')
   searchUsers(
     @query('q') query: string,
-    @query('limit') limit: number,
+    @query() limit: number,
     @header('Authorization') auth: string,
   ): Promise<Response> {
     throw new Error('实现将自动生成');
   }
 
+  @post('/users')
+  createUsers(@request() request: FetcherRequest): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+
   @put('/{id}')
   updateUser(@path('id') id: number, @body() user: User): Promise<Response> {
     throw new Error('实现将自动生成');
@@ -223,7 +230,7 @@ class BaseService {
 @api('/users')
 class UserService extends BaseService {
   @get('/{id}')
-  getUser(@path('id') id: number): Promise<Response> {
+  getUser(@path() id: number): Promise<Response> {
     throw new Error('实现将自动生成');
   }
 }
@@ -238,8 +245,34 @@ class ComplexService {
   batchOperation(
     @body() items: Item[],
     @header('X-Request-ID') requestId: string,
-    @query('dryRun') dryRun: boolean = false,
+    @query() dryRun: boolean = false,
+  ): Promise<Response> {
+    throw new Error('实现将自动生成');
+  }
+}
+```
+
+### 请求合并
+
+当使用 `@request()` 装饰器时，提供的 `FetcherRequest` 对象会使用复杂的合并策略与端点特定配置进行合并：
+
+- **嵌套对象**（路径、查询、头部）会被递归合并，参数值优先
+- **基本值**（方法、请求体、超时、信号）来自参数请求的值会覆盖端点值
+- **空对象**会被优雅地处理，回退到端点配置
+
+```typescript
+
+@api('/users')
+class UserService {
+  @post('/')
+  createUsers(
+    @body() user: User,
+    @request() request: FetcherRequest,
   ): Promise<Response> {
+    // 最终请求将合并：
+    // - 端点方法（POST）
+    // - 请求体参数（user 对象）
+    // - 来自 request 参数的任何配置
     throw new Error('实现将自动生成');
   }
 }