xxf_react 0.7.2 → 0.7.4

package/dist/http/api/ApiBuilder.d.ts

@@ -4,39 +4,30 @@
  * 使用 Builder 模式定义 API，类似 Android Retrofit。
  * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
  *
- * ## 类型安全
+ * ## 类型安全特性
  *
- * - 每个端点名称保留字面量类型（如 `'getUser'`）
- * - 链式调用累积所有端点类型：`T & Record<K, ApiEndpoint<TResponse>>`
- * - `build()` 后返回完整类型安全的 API 对象
- * - 调用不存在的端点会产生编译错误
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
  *
  * @example
  * ```ts
- * // 定义 API
+ * interface CreateUserDTO { name: string; email: string }
+ *
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
- *   .get<User>('getUser', {
- *     path: '/users/{id}',
- *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
- *   })
+ *   .get<User>('getUser', { path: '/users/{id}' })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User>('createUser', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })   // ApiStream<User>
- * userApi.getUsers()                               // ApiStream<User[]>
- * userApi.createUser({ body: { name: 'John' } })   // ApiStream<User>
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
  *
  * // ❌ 类型错误会被捕获
- * userApi.unknownMethod()  // Error: Property 'unknownMethod' does not exist
- *
- * // 多次响应
- * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
- *   console.log(data, fromCache)
- * }
+ * userApi.unknownMethod()  // Error: 方法不存在
  * ```
  */
 import ky, { type Options as KyOptions } from 'ky';
@@ -44,19 +35,73 @@ import { HttpClient } from '../client/HttpClient';
 import { ApiStream } from '../client/ApiStream';
 import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '../types';
 /**
- * API 端点函数类型
+ * 基础 API 调用选项（不含 body）
+ */
+type BaseApiOptions = Omit<ApiOptions, 'body'>;
+/**
+ * 带 body 的 API 调用选项（body 必需）
+ */
+type WithBodyRequired<TBody> = BaseApiOptions & {
+    body: TBody;
+};
+/**
+ * 带 body 的 API 调用选项（body 可选）
+ */
+type WithBodyOptional = BaseApiOptions & {
+    body?: unknown;
+};
+/**
+ * 无 body 的 API 调用选项（GET/DELETE）
+ */
+type WithoutBodyOptions = BaseApiOptions & {
+    body?: never;
+};
+/**
+ * API 端点函数类型（有 body 且必需 - POST/PUT/PATCH 指定了 TBody）
+ */
+export type ApiEndpointWithBodyRequired<TResponse, TBody> = {
+    (options: WithBodyRequired<TBody>): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * API 端点函数类型（有 body 但可选 - POST/PUT/PATCH 未指定 TBody）
+ */
+export type ApiEndpointWithBodyOptional<TResponse> = {
+    (options?: WithBodyOptional): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * API 端点函数类型（无 body - GET/DELETE）
  */
-export type ApiEndpoint<TResponse> = {
-    (options?: ApiOptions): ApiStream<TResponse>;
+export type ApiEndpointWithoutBody<TResponse> = {
+    (options?: WithoutBodyOptions): ApiStream<TResponse>;
     /** 请求配置 */
     config: RequestConfig;
 };
 /**
- * API 定义类型
+ * 检测是否为 unknown 类型
+ */
+type IsUnknown<T> = [unknown] extends [T] ? ([T] extends [unknown] ? true : false) : false;
+/**
+ * 检测是否为 void 类型
  */
-export type ApiDefinition = Record<string, ApiEndpoint<unknown>>;
+type IsVoid<T> = [T] extends [void] ? ([void] extends [T] ? true : false) : false;
 /**
- * 端点选项
+ * 有 body 的端点类型（根据 TBody 选择必需或可选）
+ */
+export type ApiEndpointWithBody<TResponse, TBody> = IsUnknown<TBody> extends true ? ApiEndpointWithBodyOptional<TResponse> : IsVoid<TBody> extends true ? ApiEndpointWithBodyOptional<TResponse> : ApiEndpointWithBodyRequired<TResponse, TBody>;
+/**
+ * API 端点函数类型（泛型版本，用于内部和类型导出）
+ */
+export type ApiEndpoint<TResponse, TBody = unknown, HasBody extends boolean = false> = HasBody extends true ? ApiEndpointWithBody<TResponse, TBody> : ApiEndpointWithoutBody<TResponse>;
+/**
+ * API 定义类型（端点集合）
+ */
+export type ApiDefinition = Record<string, ApiEndpoint<unknown, unknown, boolean>>;
+/**
+ * 端点选项（构建时配置）
  */
 interface EndpointOptions {
     /** 请求路径，支持 {param} 占位符 */
@@ -73,56 +118,119 @@ interface EndpointOptions {
     cache?: CacheConfig;
 }
 /**
- * API 构建器
+ * 空 API 类型（空记录，不允许任意属性访问）
+ */
+type EmptyApi = {};
+/**
+ * API 构建器类
+ *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({ baseUrl: '/api' })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .put<User, UpdateUserDTO>('updateUser', { path: '/users/{id}' })
+ *   .build()
+ *
+ * // 类型安全调用
+ * const user = await userApi.getUser({ pathParams: { id: '1' } })
+ * const newUser = await userApi.createUser({ body: { name: 'John', email: 'j@test.com' } })
+ * ```
  */
-export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>> {
+export declare class ApiBuilder<T extends object = EmptyApi> {
     private client;
     private endpoints;
     private constructor();
     /**
      * 创建 API 构建器
+     *
+     * @param config HTTP 客户端配置
+     * @returns 新的 ApiBuilder 实例
      */
-    static create(config: HttpClientConfig): ApiBuilder;
+    static create(config: HttpClientConfig): ApiBuilder<object>;
     /**
      * 从现有 ky 实例创建
+     *
+     * @param kyInstance 已配置的 ky 实例
+     * @param config 可选的额外配置
+     * @returns 新的 ApiBuilder 实例
      */
-    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder;
+    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder<object>;
     /**
      * 定义 GET 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
      */
-    get<K extends string, TResponse>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    get<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
     /**
      * 定义 POST 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    post<K extends string, TResponse>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    post<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
      * 定义 PUT 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    put<K extends string, TResponse>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    put<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
      * 定义 DELETE 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
      */
-    delete<K extends string, TResponse>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    delete<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
     /**
      * 定义 PATCH 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
-    patch<K extends string, TResponse>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<K, ApiEndpoint<TResponse>>>;
+    patch<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
     /**
-     * 通用端点定义
-     * K 放在前面，从 name 参数自动推断；TResponse 需要手动指定
+     * 通用端点定义（内部方法）
      */
     private endpoint;
     /**
      * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
      */
-    extend(options: KyOptions): this;
+    extend(options: KyOptions): ApiBuilder<T>;
     /**
      * 构建 API 服务
+     *
+     * @returns 类型安全的 API 对象
      */
     build(): T;
     /**

package/dist/http/api/ApiBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApiBuilder.d.ts","sourceRoot":"","sources":["../../../src/http/api/ApiBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/api/ApiBuilder.js

@@ -4,44 +4,60 @@
  * 使用 Builder 模式定义 API，类似 Android Retrofit。
  * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
  *
- * ## 类型安全
+ * ## 类型安全特性
  *
- * - 每个端点名称保留字面量类型（如 `'getUser'`）
- * - 链式调用累积所有端点类型：`T & Record<K, ApiEndpoint<TResponse>>`
- * - `build()` 后返回完整类型安全的 API 对象
- * - 调用不存在的端点会产生编译错误
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
  *
  * @example
  * ```ts
- * // 定义 API
+ * interface CreateUserDTO { name: string; email: string }
+ *
  * const userApi = ApiBuilder.create({
  *   baseUrl: 'https://api.example.com',
  * })
- *   .get<User>('getUser', {
- *     path: '/users/{id}',
- *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
- *   })
+ *   .get<User>('getUser', { path: '/users/{id}' })
  *   .get<User[]>('getUsers', { path: '/users' })
- *   .post<User>('createUser', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
  *   .build()
  *
  * // ✅ 类型正确推断
- * userApi.getUser({ pathParams: { id: '123' } })   // ApiStream<User>
- * userApi.getUsers()                               // ApiStream<User[]>
- * userApi.createUser({ body: { name: 'John' } })   // ApiStream<User>
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
  *
  * // ❌ 类型错误会被捕获
- * userApi.unknownMethod()  // Error: Property 'unknownMethod' does not exist
- *
- * // 多次响应
- * for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
- *   console.log(data, fromCache)
- * }
+ * userApi.unknownMethod()  // Error: 方法不存在
  * ```
  */
 import { HttpClient } from '../client/HttpClient';
 /**
- * API 构建器
+ * API 构建器类
+ *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({ baseUrl: '/api' })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .put<User, UpdateUserDTO>('updateUser', { path: '/users/{id}' })
+ *   .build()
+ *
+ * // 类型安全调用
+ * const user = await userApi.getUser({ pathParams: { id: '1' } })
+ * const newUser = await userApi.createUser({ body: { name: 'John', email: 'j@test.com' } })
+ * ```
  */
 export class ApiBuilder {
     constructor(config) {
@@ -50,12 +66,19 @@ export class ApiBuilder {
     }
     /**
      * 创建 API 构建器
+     *
+     * @param config HTTP 客户端配置
+     * @returns 新的 ApiBuilder 实例
      */
     static create(config) {
         return new ApiBuilder(config);
     }
     /**
      * 从现有 ky 实例创建
+     *
+     * @param kyInstance 已配置的 ky 实例
+     * @param config 可选的额外配置
+     * @returns 新的 ApiBuilder 实例
      */
     static from(kyInstance, config) {
         const builder = new ApiBuilder({
@@ -67,42 +90,54 @@ export class ApiBuilder {
     }
     /**
      * 定义 GET 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
      */
     get(name, options) {
         return this.endpoint(name, { ...options, method: 'GET' });
     }
     /**
      * 定义 POST 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     post(name, options) {
         return this.endpoint(name, { ...options, method: 'POST' });
     }
     /**
      * 定义 PUT 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     put(name, options) {
         return this.endpoint(name, { ...options, method: 'PUT' });
     }
     /**
      * 定义 DELETE 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
      */
     delete(name, options) {
         return this.endpoint(name, { ...options, method: 'DELETE' });
     }
     /**
      * 定义 PATCH 请求
-     * @param name 端点名称（K 从参数自动推断，无需手动指定）
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
      */
     patch(name, options) {
         return this.endpoint(name, { ...options, method: 'PATCH' });
     }
     /**
-     * 通用端点定义
-     * K 放在前面，从 name 参数自动推断；TResponse 需要手动指定
+     * 通用端点定义（内部方法）
      */
     endpoint(name, options) {
         var _a;
@@ -115,11 +150,13 @@ export class ApiBuilder {
             cache: options.cache,
         };
         this.endpoints.set(name, config);
-        // 关键：返回 this，但类型已经累积
         return this;
     }
     /**
      * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
      */
     extend(options) {
         this.client.extendKy(options);
@@ -127,6 +164,8 @@ export class ApiBuilder {
     }
     /**
      * 构建 API 服务
+     *
+     * @returns 类型安全的 API 对象
      */
     build() {
         const api = {};

package/dist/http/demo/api-builder.demo.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ApiBuilder 使用示例
+ *
+ * 此文件演示 ApiBuilder 的类型安全特性：
+ * 1. 泛型累积 - 链式调用自动累积端点类型
+ * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
+ * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ */
+/** 用户实体 */
+interface User {
+    id: string;
+    name: string;
+    email: string;
+    createdAt: string;
+}
+/** 创建用户 DTO */
+interface CreateUserDTO {
+    name: string;
+    email: string;
+}
+/** 更新用户 DTO */
+interface UpdateUserDTO {
+    name?: string;
+    email?: string;
+}
+/** 分页响应 */
+interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+export declare const userApi: object & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User[]>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<User>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<PaginatedResponse<User>>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, CreateUserDTO>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyOptional<void>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, UpdateUserDTO>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithBodyRequired<User, Partial<UpdateUserDTO>>;
+} & {
+    [x: string]: import("../api/ApiBuilder").ApiEndpointWithoutBody<void>;
+};
+declare function demo(): Promise<void>;
+declare function typeErrors(): void;
+export { demo, typeErrors };
+//# sourceMappingURL=api-builder.demo.d.ts.map

package/dist/http/demo/api-builder.demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-builder.demo.d.ts","sourceRoot":"","sources":["../../../src/http/demo/api-builder.demo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,WAAW;AACX,UAAU,IAAI;IACV,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACpB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,eAAe;AACf,UAAU,aAAa;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,WAAW;AACX,UAAU,iBAAiB,CAAC,CAAC;IACzB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACnB;AAMD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;CA8DR,CAAA;AAMZ,iBAAe,IAAI,kBAuElB;AAoBD,iBAAS,UAAU,SAYlB;AAMD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA"}

package/dist/http/demo/api-builder.demo.js

@@ -0,0 +1,163 @@
+/**
+ * ApiBuilder 使用示例
+ *
+ * 此文件演示 ApiBuilder 的类型安全特性：
+ * 1. 泛型累积 - 链式调用自动累积端点类型
+ * 2. Body 类型约束 - POST/PUT/PATCH 请求体类型检查
+ * 3. 端点名称字面量 - 调用不存在的端点会编译报错
+ */
+import { ApiBuilder } from '../api/ApiBuilder';
+import { CacheMode } from '../models/CacheMode';
+// ============================================================================
+// 创建 API 服务
+// ============================================================================
+export const userApi = ApiBuilder.create({
+    baseUrl: 'https://api.example.com',
+    timeout: 10000,
+    defaultCache: {
+        mode: CacheMode.FirstRemote,
+        ttl: 5 * 60 * 1000,
+    },
+})
+    // GET 请求 - 无路径参数
+    .get('getUsers', {
+    path: '/users',
+    cache: { mode: CacheMode.FirstCache },
+})
+    // GET 请求 - 有路径参数
+    .get('getUser', {
+    path: '/users/{id}',
+    cache: { mode: CacheMode.IfCache, ttl: 60000 },
+})
+    // GET 请求 - 分页
+    .get('getUsersPaginated', {
+    path: '/users/paginated',
+})
+    // POST 请求 - 有 body 类型
+    .post('createUser', {
+    path: '/users',
+})
+    // POST 请求 - 无 body 类型（触发器）
+    .post('activateUser', {
+    path: '/users/{id}/activate',
+})
+    // PUT 请求 - 完整更新
+    .put('updateUser', {
+    path: '/users/{id}',
+})
+    // PATCH 请求 - 部分更新
+    .patch('patchUser', {
+    path: '/users/{id}',
+})
+    // DELETE 请求
+    .delete('deleteUser', {
+    path: '/users/{id}',
+})
+    // 扩展 ky 实例（添加拦截器）
+    .extend({
+    hooks: {
+        beforeRequest: [
+            (request) => {
+                const token = 'mock-token';
+                request.headers.set('Authorization', `Bearer ${token}`);
+            },
+        ],
+    },
+})
+    .build();
+// ============================================================================
+// 使用示例 - 类型安全调用
+// ============================================================================
+async function demo() {
+    // ✅ GET 无路径参数
+    const users = await userApi.getUsers();
+    console.log('Users:', users);
+    // ✅ GET 有路径参数
+    const user = await userApi.getUser({
+        pathParams: { id: '123' },
+    });
+    console.log('User:', user);
+    // ✅ GET 带 query 参数
+    const paginatedUsers = await userApi.getUsersPaginated({
+        query: { page: 1, pageSize: 10 },
+    });
+    console.log('Paginated:', paginatedUsers);
+    // ✅ POST 有 body 类型约束
+    const newUser = await userApi.createUser({
+        body: { name: 'John', email: 'john@example.com' },
+    });
+    console.log('Created:', newUser);
+    // ✅ POST 无 body（触发器）
+    await userApi.activateUser({
+        pathParams: { id: '123' },
+    });
+    // ✅ PUT 完整更新
+    const updatedUser = await userApi.updateUser({
+        pathParams: { id: '123' },
+        body: { name: 'John Updated', email: 'john.updated@example.com' },
+    });
+    console.log('Updated:', updatedUser);
+    // ✅ PATCH 部分更新
+    const patchedUser = await userApi.patchUser({
+        pathParams: { id: '123' },
+        body: { name: 'John Patched' },
+    });
+    console.log('Patched:', patchedUser);
+    // ✅ DELETE
+    await userApi.deleteUser({
+        pathParams: { id: '123' },
+    });
+    // ✅ 覆盖缓存配置
+    const freshUser = await userApi.getUser({
+        pathParams: { id: '123' },
+        cache: { mode: CacheMode.OnlyRemote },
+    });
+    console.log('Fresh:', freshUser);
+    // ✅ 多次响应（for await）
+    for await (const { data, fromCache } of userApi.getUser({ pathParams: { id: '123' } })) {
+        console.log('Data:', data, 'FromCache:', fromCache);
+    }
+    // ✅ subscribe 方式
+    await userApi.getUser({ pathParams: { id: '123' } }).subscribe({
+        onData: (data, fromCache) => {
+            console.log('Subscribe data:', data, fromCache);
+        },
+        onError: (error) => {
+            console.error('Error:', error);
+        },
+        onComplete: () => {
+            console.log('Complete');
+        },
+    });
+}
+// ============================================================================
+// 类型错误示例
+// ============================================================================
+/**
+ * 类型安全验证
+ *
+ * 注意：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当链式调用超过 4 个端点时，类型推断可能不够精确。
+ * 建议：保持单个 builder 的端点数量在 4 个以内，或分批构建。
+ *
+ * 以下是简化版本的类型安全验证（2-3 个端点）
+ */
+const simpleApi = ApiBuilder.create({ baseUrl: 'http://test' })
+    .get('getUser', { path: '/users/{id}' })
+    .post('createUser', { path: '/users' })
+    .build();
+function typeErrors() {
+    // ❌ body 类型不匹配（缺少 email）
+    // @ts-expect-error email is required
+    simpleApi.createUser({ body: { name: 'John' } });
+    // ❌ body 类型不匹配（错误的属性）
+    // @ts-expect-error wrong property
+    simpleApi.createUser({ body: { wrong: 'x' } });
+    // ❌ GET 请求不应该有 body
+    // @ts-expect-error body not allowed for GET
+    simpleApi.getUser({ pathParams: { id: '1' }, body: {} });
+}
+// ============================================================================
+// 导出
+// ============================================================================
+export { demo, typeErrors };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": false,
   "type": "module",
   "main": "dist/index.js",