xxf_react 0.6.6 → 0.6.8

package/README.md

@@ -18,55 +18,21 @@ This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com)
 
 ## 模块文档
 
-| 模块 | 说明 |
-|------|------|
-| [event-bus](./src/event-bus/README.md) | 事件总线，支持跨 Tab 通信 |
-| [fetch](./src/fetch/README.md) | 带超时控制的 fetch 封装 |
-| [flow](./src/flow/README.md) | Promise 扩展，全局错误处理 |
-| [foundation](./src/foundation/README.md) | 基础工具，性能监控 |
-| [layout](./src/layout/README.md) | 布局组件，悬浮交互 |
-| [media](./src/media/README.md) | 媒体组件，视频播放 |
-| [models](./src/models/README.md) | 数据模型，API 响应类型 |
-| [refresh](./src/refresh/README.md) | 刷新加载，分页加载更多 |
-| [responsive](./src/responsive/README.md) | 响应式布局，设备检测 |
-| [sse](./src/sse/README.md) | Server-Sent Events 连接管理 |
-| [utils](./src/utils/README.md) | 工具函数，滚动定位、组件刷新 |
+| 模块                                       | 说明                      |
+|------------------------------------------|-------------------------|
+| [event-bus](./src/event-bus/README.md)   | 事件总线，支持跨 Tab 通信         |
+| [fetch](./src/fetch/README.md)           | 带超时控制的 fetch 封装         |
+| [http](./src/http/README.md)             | 超强网络框架设计                |
+| [flow](./src/flow/README.md)             | Promise 扩展，全局错误处理       |
+| [foundation](./src/foundation/README.md) | 基础工具，性能监控               |
+| [layout](./src/layout/README.md)         | 布局组件，悬浮交互               |
+| [media](./src/media/README.md)           | 媒体组件，视频播放               |
+| [models](./src/models/README.md)         | 数据模型，API 响应类型           |
+| [refresh](./src/refresh/README.md)       | 刷新加载，分页加载更多             |
+| [responsive](./src/responsive/README.md) | 响应式布局，设备检测              |
+| [sse](./src/sse/README.md)               | Server-Sent Events 连接管理 |
+| [utils](./src/utils/README.md)           | 工具函数，滚动定位、组件刷新          |
 
 ## 详细文档
 
 - [PlaybackQueue 播放队列状态管理](./src/media/playback-queue-store.md)
-
-### VideoPlaySafe 视频安全播放
-
-处理移动端自动播放限制，自动降级为静音播放。
-
-#### 功能特性
-
-- 按当前 `video.muted` 状态尝试播放
-- 如果非静音播放失败（`NotAllowedError` / `AbortError`），自动降级为静音重试
-- 支持扩展 `HTMLVideoElement` 原型，直接调用 `video.playSafe()`
-
-#### 使用方式
-
-```typescript
-import { playSafe, extendVideoElement } from '@xxf/react/media/video-play-safe';
-
-// 方式一：直接调用函数
-await playSafe(videoElement, {
-    mutedRetry: true,           // 是否在非静音播放失败时降级为静音重试，默认 true
-    onMutedChange: () => {      // 从有声降级为静音时回调
-        console.log('已降级为静音播放');
-    }
-});
-
-// 方式二：扩展原型后调用
-extendVideoElement();
-await videoElement.playSafe({ mutedRetry: true });
-```
-
-#### API
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `mutedRetry` | `boolean` | `true` | 是否在非静音播放失败时降级为静音重试 |
-| `onMutedChange` | `() => void` | - | 从有声降级为静音时的回调函数 |

package/dist/foundation/Copy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 深拷贝
+ *
+ * 业务层只调用 copy()
+ * 不感知具体实现
+ */
+export declare function copy<T>(value: T): T;
+//# sourceMappingURL=Copy.d.ts.map

package/dist/foundation/Copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Copy.d.ts","sourceRoot":"","sources":["../../src/foundation/Copy.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEnC"}

package/dist/foundation/Copy.js

@@ -0,0 +1,21 @@
+// utils/copy.ts
+import rfdc from 'rfdc';
+/**
+ * 内部深拷贝实现
+ *
+ * proto: false  -> 不拷贝原型链（更安全）
+ * circles: true -> 支持循环引用
+ */
+const deepCloneImpl = rfdc({
+    proto: false,
+    circles: true,
+});
+/**
+ * 深拷贝
+ *
+ * 业务层只调用 copy()
+ * 不感知具体实现
+ */
+export function copy(value) {
+    return deepCloneImpl(value);
+}

package/dist/foundation/index.d.ts

@@ -1,3 +1,5 @@
 export * from './Debug';
 export * from './PerformanceMonitor';
+export * from './LayoutSize';
+export * from './Copy';
 //# sourceMappingURL=index.d.ts.map

package/dist/foundation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,sBAAsB,CAAA;AACpC,cAAc,cAAc,CAAA;AAC5B,cAAc,QAAQ,CAAA"}

package/dist/foundation/index.js

@@ -1,2 +1,4 @@
 export * from './Debug';
 export * from './PerformanceMonitor';
+export * from './LayoutSize';
+export * from './Copy';

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

@@ -0,0 +1,115 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .post<User, CreateUserDTO>('createUser', {
+ *     path: '/users',
+ *   })
+ *   .build()
+ *
+ * // 使用 API
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 多次响应
+ * for await (const { data, fromCache } of userApi.getUserList()) {
+ *   console.log(data, fromCache)
+ * }
+ * ```
+ */
+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 端点函数类型
+ */
+export type ApiEndpoint<TResponse> = {
+    (options?: ApiOptions): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * API 定义类型
+ */
+export type ApiDefinition = Record<string, ApiEndpoint<unknown>>;
+/**
+ * 端点选项
+ */
+interface EndpointOptions {
+    /** 请求路径，支持 {param} 占位符 */
+    path: string;
+    /** 请求方法 */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 超时时间 (ms) */
+    timeout?: number;
+    /** 重试次数 */
+    retry?: number;
+    /** 缓存配置 */
+    cache?: CacheConfig;
+}
+/**
+ * API 构建器
+ */
+export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>> {
+    private client;
+    private endpoints;
+    private constructor();
+    /**
+     * 创建 API 构建器
+     */
+    static create(config: HttpClientConfig): ApiBuilder;
+    /**
+     * 从现有 ky 实例创建
+     */
+    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder;
+    /**
+     * 定义 GET 请求
+     */
+    get<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 POST 请求
+     */
+    post<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 PUT 请求
+     */
+    put<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 DELETE 请求
+     */
+    delete<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 PATCH 请求
+     */
+    patch<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 通用端点定义
+     */
+    private endpoint;
+    /**
+     * 扩展 ky 实例（添加 hooks 等）
+     */
+    extend(options: KyOptions): this;
+    /**
+     * 构建 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,128 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .post<User, CreateUserDTO>('createUser', {
+ *     path: '/users',
+ *   })
+ *   .build()
+ *
+ * // 使用 API
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 多次响应
+ * for await (const { data, fromCache } of userApi.getUserList()) {
+ *   console.log(data, fromCache)
+ * }
+ * ```
+ */
+import { HttpClient } from '../client/HttpClient';
+/**
+ * API 构建器
+ */
+export class ApiBuilder {
+    constructor(config) {
+        this.endpoints = new Map();
+        this.client = new HttpClient(config);
+    }
+    /**
+     * 创建 API 构建器
+     */
+    static create(config) {
+        return new ApiBuilder(config);
+    }
+    /**
+     * 从现有 ky 实例创建
+     */
+    static from(kyInstance, config) {
+        const builder = new ApiBuilder({
+            baseUrl: '',
+            ...config,
+        });
+        builder.client.setKyInstance(kyInstance);
+        return builder;
+    }
+    /**
+     * 定义 GET 请求
+     */
+    get(name, options) {
+        return this.endpoint(name, { ...options, method: 'GET' });
+    }
+    /**
+     * 定义 POST 请求
+     */
+    post(name, options) {
+        return this.endpoint(name, { ...options, method: 'POST' });
+    }
+    /**
+     * 定义 PUT 请求
+     */
+    put(name, options) {
+        return this.endpoint(name, { ...options, method: 'PUT' });
+    }
+    /**
+     * 定义 DELETE 请求
+     */
+    delete(name, options) {
+        return this.endpoint(name, { ...options, method: 'DELETE' });
+    }
+    /**
+     * 定义 PATCH 请求
+     */
+    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 等）
+     */
+    extend(options) {
+        this.client.extendKy(options);
+        return this;
+    }
+    /**
+     * 构建 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 } 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,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

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

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

@@ -0,0 +1,66 @@
+/**
+ * 基于 IndexedDB 的 LRU 磁盘缓存
+ *
+ * 特点：
+ * - 使用 idb-keyval 简化 IndexedDB 操作
+ * - 维护 LRU 元数据实现淘汰策略
+ * - 支持 TTL 过期
+ * - 批量清理优化性能
+ * - 防污染：返回数据的深拷贝
+ */
+import type { CacheEntry, DiskLruCacheConfig } from '../types';
+export declare class DiskLruCache {
+    private store;
+    private config;
+    private metadata;
+    private metadataDirty;
+    private flushTimer;
+    private evicting;
+    constructor(config: DiskLruCacheConfig);
+    /**
+     * 加载或初始化 LRU 元数据（失败返回空元数据）
+     */
+    private loadMetadata;
+    /**
+     * 保存元数据到磁盘 (批量优化，延迟写入)
+     */
+    private scheduleFlushMetadata;
+    /**
+     * 立即刷新元数据到磁盘（失败静默忽略）
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取缓存（失败返回 null，不影响业务）
+     * @returns 缓存条目的深拷贝
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 检查缓存是否存在（不更新访问时间，失败返回 false）
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 淘汰最旧的缓存条目（失败静默忽略）
+     */
+    private evict;
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    clear(): Promise<void>;
+    /**
+     * 获取缓存数量（失败返回 0）
+     */
+    size(): Promise<number>;
+    /**
+     * 获取所有缓存 key（失败返回空数组）
+     */
+    keys(): Promise<string[]>;
+}
+//# sourceMappingURL=DiskLruCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DiskLruCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/DiskLruCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAe,MAAM,UAAU,CAAA;AAK3E,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,kBAAkB;IAQtC;;OAEG;YACW,YAAY;IAiB1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCxD;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC;;OAEG;YACW,KAAK;IAsCnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAS7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAQlC"}