xxf_react 0.8.5 → 0.8.7

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

@@ -0,0 +1,251 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit。
+ * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
+ *
+ * ## 类型安全特性
+ *
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
+ *
+ * @example
+ * ```ts
+ * interface CreateUserDTO { name: string; email: string }
+ *
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .get<User[]>('getUsers', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .build()
+ *
+ * // ✅ 类型正确推断
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
+ *
+ * // ❌ 类型错误会被捕获
+ * userApi.unknownMethod()  // Error: 方法不存在
+ * ```
+ */
+import ky, { type Options as KyOptions } from 'ky';
+import { HttpClient } from '../client/HttpClient';
+import { ApiStream } from '../client/ApiStream';
+import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '../types';
+/**
+ * 基础 API 调用选项（不含 body）
+ */
+type BaseApiOptions = Omit<ApiOptions, 'body'>;
+/**
+ * 强制 TypeScript 展开交叉类型为单一对象类型
+ * 用于用户自定义接口类型时使用
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * 带 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 ApiEndpointWithoutBody<TResponse> = {
+    (options?: WithoutBodyOptions): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * 检测是否为 unknown 类型
+ */
+type IsUnknown<T> = [unknown] extends [T] ? ([T] extends [unknown] ? true : false) : false;
+/**
+ * 检测是否为 void 类型
+ */
+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} 占位符 */
+    path: string;
+    /** 请求方法 */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 超时时间 (ms) */
+    timeout?: number;
+    /** 重试次数 */
+    retry?: number;
+    /** 缓存配置 */
+    cache?: CacheConfig;
+}
+/**
+ * 空 API 类型（空记录，不允许任意属性访问）
+ */
+type EmptyApi = {};
+/**
+ * API 构建器类
+ *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ * - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
+ *   来定义自己的接口类型，获得更精确的类型检查
+ *
+ * @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 object = EmptyApi> {
+    private client;
+    private endpoints;
+    private constructor();
+    /**
+     * 创建 API 构建器
+     *
+     * @param config HTTP 客户端配置
+     * @returns 新的 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<object>;
+    /**
+     * 定义 GET 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
+     */
+    get<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
+    /**
+     * 定义 POST 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    post<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
+    /**
+     * 定义 PUT 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    put<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
+    /**
+     * 定义 DELETE 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
+     */
+    delete<TResponse, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithoutBody<TResponse>;
+    }>;
+    /**
+     * 定义 PATCH 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    patch<TResponse, TBody = void, const K extends string = string>(name: K, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & {
+        [P in K]: ApiEndpointWithBody<TResponse, TBody>;
+    }>;
+    /**
+     * 通用端点定义（内部方法）
+     */
+    private endpoint;
+    /**
+     * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
+     */
+    extend(options: KyOptions): ApiBuilder<T>;
+    /**
+     * 构建 API 服务
+     *
+     * @returns 类型安全的 API 对象
+     */
+    build(): T;
+    /**
+     * 获取 HTTP 客户端实例（用于高级操作）
+     */
+    getClient(): HttpClient;
+}
+export {};
+//# sourceMappingURL=ApiBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,189 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit。
+ * 采用泛型累积模式，每次 .get() / .post() 调用都返回带有累积类型的新 Builder。
+ *
+ * ## 类型安全特性
+ *
+ * - **端点名称字面量**：每个端点名称保留字面量类型（如 `'getUser'`）
+ * - **泛型累积**：链式调用累积所有端点类型 `T & Record<K, ApiEndpoint<...>>`
+ * - **Body 类型约束**：POST/PUT/PATCH 支持指定请求体类型
+ *
+ * @example
+ * ```ts
+ * interface CreateUserDTO { name: string; email: string }
+ *
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', { path: '/users/{id}' })
+ *   .get<User[]>('getUsers', { path: '/users' })
+ *   .post<User, CreateUserDTO>('createUser', { path: '/users' })
+ *   .build()
+ *
+ * // ✅ 类型正确推断
+ * userApi.getUser({ pathParams: { id: '123' } })
+ * userApi.createUser({ body: { name: 'John', email: 'x' } })
+ *
+ * // ❌ 类型错误会被捕获
+ * userApi.unknownMethod()  // Error: 方法不存在
+ * ```
+ */
+import { HttpClient } from '../client/HttpClient';
+/**
+ * API 构建器类
+ *
+ * 使用链式调用定义类型安全的 API 端点。
+ *
+ * @template T 当前已定义的端点类型集合，通过链式调用累积
+ *
+ * @remarks
+ * **类型深度限制**：由于 TypeScript 对深层交叉类型的处理限制，
+ * 当单个 builder 链式调用超过 4 个端点时，类型推断可能不够精确。
+ *
+ * 建议：
+ * - 保持单个 builder 的端点数量在 4 个以内以获得最佳类型推断
+ * - 如需更多端点，功能仍然正常，但部分类型检查可能被放宽
+ * - 可以使用导出的 `ApiEndpointWithBody`、`ApiEndpointWithoutBody` 等类型
+ *   来定义自己的接口类型，获得更精确的类型检查
+ *
+ * @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) {
+        this.endpoints = new Map();
+        this.client = new HttpClient(config);
+    }
+    /**
+     * 创建 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({
+            baseUrl: '',
+            ...config,
+        });
+        builder.client.setKyInstance(kyInstance);
+        return builder;
+    }
+    /**
+     * 定义 GET 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称（自动推断）
+     */
+    get(name, options) {
+        return this.endpoint(name, { ...options, method: 'GET' });
+    }
+    /**
+     * 定义 POST 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    post(name, options) {
+        return this.endpoint(name, { ...options, method: 'POST' });
+    }
+    /**
+     * 定义 PUT 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    put(name, options) {
+        return this.endpoint(name, { ...options, method: 'PUT' });
+    }
+    /**
+     * 定义 DELETE 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template K 端点名称
+     */
+    delete(name, options) {
+        return this.endpoint(name, { ...options, method: 'DELETE' });
+    }
+    /**
+     * 定义 PATCH 请求
+     *
+     * @template TResponse 响应数据类型
+     * @template TBody 请求体类型
+     * @template K 端点名称
+     */
+    patch(name, options) {
+        return this.endpoint(name, { ...options, method: 'PATCH' });
+    }
+    /**
+     * 通用端点定义（内部方法）
+     */
+    endpoint(name, options) {
+        var _a;
+        const config = {
+            method: (_a = options.method) !== null && _a !== void 0 ? _a : 'GET',
+            path: options.path,
+            headers: options.headers,
+            timeout: options.timeout,
+            retry: options.retry,
+            cache: options.cache,
+        };
+        this.endpoints.set(name, config);
+        return this;
+    }
+    /**
+     * 扩展 ky 实例（添加 hooks 等）
+     *
+     * @param options Ky 配置选项
+     * @returns 当前 Builder 实例（保留累积的类型）
+     */
+    extend(options) {
+        this.client.extendKy(options);
+        return this;
+    }
+    /**
+     * 构建 API 服务
+     *
+     * @returns 类型安全的 API 对象
+     */
+    build() {
+        const api = {};
+        for (const [name, config] of this.endpoints) {
+            const endpoint = ((options) => {
+                return this.client.request(config, options);
+            });
+            endpoint.config = config;
+            api[name] = endpoint;
+        }
+        return api;
+    }
+    /**
+     * 获取 HTTP 客户端实例（用于高级操作）
+     */
+    getClient() {
+        return this.client;
+    }
+}

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

@@ -0,0 +1,2 @@
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition, type ApiEndpointWithBody, type ApiEndpointWithoutBody, type ApiEndpointWithBodyRequired, type ApiEndpointWithBodyOptional, type Simplify, } from './ApiBuilder';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EAChC,KAAK,QAAQ,GAChB,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

@@ -0,0 +1 @@
+export { ApiBuilder, } from './ApiBuilder';

package/dist/http/cache/HttpCache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * HTTP 缓存（内存 + 磁盘双层）
+ *
+ * 策略：
+ * - 读取：先内存 -> 再磁盘 -> 若磁盘命中则回填内存
+ * - 写入：同时写入内存和磁盘
+ * - 容错：缓存操作失败不影响正常业务
+ * - 防污染：返回数据的深拷贝，防止上层修改影响缓存
+ */
+import { DiskLruCache } from '../../cache';
+import type { CacheEntry, HttpCacheConfig } from '../types';
+export declare class HttpCache {
+    private memoryCache;
+    private diskCache;
+    constructor(config: HttpCacheConfig);
+    /**
+     * 获取缓存
+     * @param key 缓存 key
+     * @returns 缓存条目的深拷贝，未命中或失败返回 null
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     * @param key 缓存 key
+     * @param data 数据
+     * @param ttl 过期时间 (ms)
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    clear(): Promise<void>;
+    /**
+     * 仅获取内存缓存（同步，失败返回 null）
+     * @returns 缓存条目的深拷贝
+     */
+    getFromMemory<T>(key: string): CacheEntry<T> | null;
+    /**
+     * 仅设置内存缓存（同步，失败静默忽略）
+     */
+    setToMemory<T>(key: string, data: T, ttl?: number): void;
+    /**
+     * 检查缓存是否存在（会检查过期，失败返回 false）
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 获取磁盘缓存实例（用于高级操作）
+     */
+    getDiskCache(): DiskLruCache;
+    /**
+     * 刷新磁盘缓存元数据（失败静默忽略）
+     */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=HttpCache.d.ts.map

package/dist/http/cache/HttpCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/HttpCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG3D,qBAAa,SAAS;IAClB,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,SAAS,CAAc;gBAEnB,MAAM,EAAE,eAAe;IAcnC;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAwCxD;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAgBnD;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,IAAI;IAc3D;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBxC;;OAEG;IACH,YAAY,IAAI,YAAY;IAI5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO/B"}