xxf_react 0.6.6 → 0.6.8

package/dist/http/client/ApiStream.js

@@ -0,0 +1,190 @@
+/**
+ * ApiStream - AsyncGenerator 流式响应
+ *
+ * 支持三种消费方式：
+ * 1. await - 直接获取最后一个结果
+ * 2. for await - 迭代所有结果
+ * 3. subscribe - 安全消费（框架 try-catch）
+ */
+export class ApiStream {
+    constructor(generator) {
+        this.consumed = false;
+        this.generator = generator;
+    }
+    /**
+     * 实现 AsyncIterable，支持 for await
+     *
+     * 注意：每次迭代都会创建新的请求。如果需要缓存结果，请使用 toArray()
+     */
+    [Symbol.asyncIterator]() {
+        var _a;
+        if (this.consumed) {
+            // 开发环境下警告重复消费
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                if (typeof globalThis.process !== 'undefined' &&
+                    ((_a = globalThis.process.env) === null || _a === void 0 ? void 0 : _a.NODE_ENV) !== 'production') {
+                    console.warn('[ApiStream] Stream is being consumed multiple times. ' +
+                        'Each iteration creates a new request. ' +
+                        'Use toArray() if you need to reuse results.');
+                }
+            }
+            catch {
+                // 忽略环境检测错误
+            }
+        }
+        this.consumed = true;
+        return this.generator();
+    }
+    /**
+     * 实现 PromiseLike，支持直接 await（返回最后一个结果的 data）
+     */
+    then(onfulfilled, onrejected) {
+        return this.last()
+            .then((result) => result.data)
+            .then(onfulfilled, onrejected);
+    }
+    /**
+     * 实现 catch
+     */
+    catch(onrejected) {
+        return this.then(undefined, onrejected);
+    }
+    /**
+     * 实现 finally
+     */
+    finally(onfinally) {
+        return this.then((value) => {
+            onfinally === null || onfinally === void 0 ? void 0 : onfinally();
+            return value;
+        }, (reason) => {
+            onfinally === null || onfinally === void 0 ? void 0 : onfinally();
+            throw reason;
+        });
+    }
+    /**
+     * 获取第一个结果
+     * @throws 如果没有结果会抛出错误
+     */
+    async first() {
+        const result = await this.firstOrNull();
+        if (!result) {
+            throw new Error('No result available');
+        }
+        return result;
+    }
+    /**
+     * 获取第一个结果，没有则返回 null
+     */
+    async firstOrNull() {
+        for await (const result of this) {
+            return result;
+        }
+        return null;
+    }
+    /**
+     * 获取最后一个结果
+     * @throws 如果没有结果会抛出错误
+     */
+    async last() {
+        const result = await this.lastOrNull();
+        if (!result) {
+            throw new Error('No result available');
+        }
+        return result;
+    }
+    /**
+     * 获取最后一个结果，没有则返回 null
+     */
+    async lastOrNull() {
+        let lastResult = null;
+        for await (const result of this) {
+            lastResult = result;
+        }
+        return lastResult;
+    }
+    /**
+     * 获取所有结果
+     */
+    async toArray() {
+        const results = [];
+        for await (const result of this) {
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * 查找满足条件的第一个结果
+     */
+    async find(predicate) {
+        for await (const result of this) {
+            if (predicate(result)) {
+                return result;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 安全消费（框架 try-catch 隔离错误）
+     * onData 抛错不会影响后续 yield
+     */
+    async subscribe(callback) {
+        var _a, _b, _c, _d;
+        try {
+            for await (const result of this) {
+                try {
+                    callback.onData(result.data, result.fromCache);
+                }
+                catch (error) {
+                    // 捕获下游错误，不影响后续 yield
+                    (_a = callback.onError) === null || _a === void 0 ? void 0 : _a.call(callback, error);
+                }
+            }
+            (_b = callback.onComplete) === null || _b === void 0 ? void 0 : _b.call(callback);
+        }
+        catch (error) {
+            // 网络错误等
+            (_c = callback.onError) === null || _c === void 0 ? void 0 : _c.call(callback, error);
+            (_d = callback.onComplete) === null || _d === void 0 ? void 0 : _d.call(callback);
+        }
+    }
+    /**
+     * 映射结果
+     */
+    map(fn) {
+        const self = this;
+        return new ApiStream(async function* () {
+            for await (const result of self) {
+                yield {
+                    data: fn(result.data),
+                    fromCache: result.fromCache,
+                };
+            }
+        });
+    }
+    /**
+     * 过滤结果
+     */
+    filter(predicate) {
+        const self = this;
+        return new ApiStream(async function* () {
+            for await (const result of self) {
+                if (predicate(result)) {
+                    yield result;
+                }
+            }
+        });
+    }
+    /**
+     * 只获取缓存结果
+     */
+    cacheOnly() {
+        return this.filter((r) => r.fromCache);
+    }
+    /**
+     * 只获取网络结果
+     */
+    remoteOnly() {
+        return this.filter((r) => !r.fromCache);
+    }
+}

package/dist/http/client/HttpClient.d.ts

@@ -0,0 +1,88 @@
+/**
+ * HTTP 客户端
+ *
+ * 基于 ky 封装，支持：
+ * - 多种缓存模式
+ * - 自动重试
+ * - 超时处理
+ */
+import { type KyInstance, type Options as KyOptions } from 'ky';
+import { HttpCache } from '../cache/HttpCache';
+import { ApiStream } from './ApiStream';
+import { type HttpClientConfig, type RequestConfig, type ApiOptions } from '../types';
+export declare class HttpClient {
+    private client;
+    private cache;
+    private config;
+    constructor(config: HttpClientConfig);
+    /**
+     * 获取 ky 实例（用于扩展 hooks 等）
+     */
+    getKyInstance(): KyInstance;
+    /**
+     * 设置 ky 实例
+     */
+    setKyInstance(instance: KyInstance): void;
+    /**
+     * 扩展 ky 实例
+     */
+    extendKy(options: KyOptions): void;
+    /**
+     * 执行请求，返回 ApiStream
+     */
+    request<T>(requestConfig: RequestConfig, options?: ApiOptions): ApiStream<T>;
+    /**
+     * 根据缓存策略执行请求
+     */
+    private executeWithCacheStrategy;
+    /**
+     * 判断响应是否应该缓存
+     *
+     * 调用全局缓存拦截器，根据响应内容决定是否缓存。
+     * 如果没有配置拦截器，默认允许缓存。
+     *
+     * @param result 请求响应结果
+     * @param cacheKey 缓存 key
+     * @param request 请求信息
+     * @param defaultTtl 默认 TTL
+     * @returns 是否缓存及最终 TTL
+     */
+    private shouldCacheResponse;
+    /**
+     * 条件缓存：根据拦截器结果决定是否写入缓存
+     */
+    private conditionalCache;
+    /**
+     * OnlyRemote: 只从服务器拿
+     */
+    private strategyOnlyRemote;
+    /**
+     * OnlyCache: 只从缓存拿
+     */
+    private strategyOnlyCache;
+    /**
+     * IfCache: 有缓存返回缓存，否则请求网络
+     */
+    private strategyIfCache;
+    /**
+     * FirstRemote: 先从服务器获取，没网络则读缓存
+     */
+    private strategyFirstRemote;
+    /**
+     * FirstCache: 先从本地缓存拿，然后从服务器拿，可能 yield 两次
+     */
+    private strategyFirstCache;
+    /**
+     * LastCache: 读上次缓存，没有则返回网络并同步缓存；有缓存也会后台同步网络但不 yield
+     */
+    private strategyLastCache;
+    /**
+     * 获取缓存实例（用于高级操作）
+     */
+    getCache(): HttpCache;
+    /**
+     * 清空所有缓存
+     */
+    clearCache(): Promise<void>;
+}
+//# sourceMappingURL=HttpClient.d.ts.map

package/dist/http/client/HttpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClient.d.ts","sourceRoot":"","sources":["../../../src/http/client/HttpClient.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAW,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,IAAI,SAAS,EAAE,MAAM,IAAI,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAEH,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,UAAU,EAMlB,MAAM,UAAU,CAAA;AAyFjB,qBAAa,UAAU;IACnB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,MAAM,CAA4B;gBAE9B,MAAM,EAAE,gBAAgB;IA8BpC;;OAEG;IACH,aAAa,IAAI,UAAU;IAI3B;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI;IAIzC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI;IAIlC;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,GAAE,UAAe,GAAG,SAAS,CAAC,CAAC,CAAC;IAmFhF;;OAEG;YACY,wBAAwB;IAqCvC;;;;;;;;;;;OAWG;YACW,mBAAmB;IAwCjC;;OAEG;YACW,gBAAgB;IAY9B;;OAEG;YACY,kBAAkB;IAWjC;;OAEG;YACY,iBAAiB;IAQhC;;OAEG;YACY,eAAe;IAiB9B;;OAEG;YACY,mBAAmB;IAqBlC;;OAEG;YACY,kBAAkB;IA0BjC;;OAEG;YACY,iBAAiB;IA0BhC;;OAEG;IACH,QAAQ,IAAI,SAAS;IAIrB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGpC"}

package/dist/http/client/HttpClient.js

@@ -0,0 +1,381 @@
+/**
+ * HTTP 客户端
+ *
+ * 基于 ky 封装，支持：
+ * - 多种缓存模式
+ * - 自动重试
+ * - 超时处理
+ */
+import ky from 'ky';
+import { HttpCache } from '../cache/HttpCache';
+import { ApiStream } from './ApiStream';
+import { CacheMode, } from '../types';
+/**
+ * 对象 key 排序（用于生成稳定的缓存 key）
+ * 支持嵌套对象递归排序
+ */
+function sortKeys(obj) {
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        const value = obj[key];
+        // 递归处理嵌套对象（排除 null 和数组）
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            sorted[key] = sortKeys(value);
+        }
+        else {
+            sorted[key] = value;
+        }
+    }
+    return sorted;
+}
+/**
+ * 简单 hash 函数
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * 过滤对象中的 undefined 和 null 值
+ */
+function filterUndefined(obj) {
+    if (!obj)
+        return undefined;
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined && value !== null) {
+            result[key] = String(value);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * 默认缓存 key 生成
+ */
+function defaultGenerateCacheKey(request, keyHeaders) {
+    const parts = [request.method, request.path];
+    if (request.query && Object.keys(request.query).length > 0) {
+        parts.push(JSON.stringify(sortKeys(request.query)));
+    }
+    if (request.body) {
+        parts.push(simpleHash(JSON.stringify(request.body)));
+    }
+    if ((keyHeaders === null || keyHeaders === void 0 ? void 0 : keyHeaders.length) && request.headers) {
+        const headerParts = keyHeaders
+            .filter((k) => request.headers[k])
+            .map((k) => `${k}:${request.headers[k]}`)
+            .join('|');
+        if (headerParts) {
+            parts.push(headerParts);
+        }
+    }
+    return parts.join(':');
+}
+export class HttpClient {
+    constructor(config) {
+        this.config = {
+            headers: {},
+            timeout: 30000,
+            retry: 2,
+            memoryCacheMaxSize: 100,
+            diskCacheMaxSize: 500,
+            dbName: 'xxf-http-cache',
+            defaultKeyHeaders: ['Authorization'],
+            defaultCache: undefined, // 默认不缓存 (OnlyRemote)
+            cacheInterceptor: undefined, // 默认无拦截器
+            ...config,
+        };
+        // 初始化 ky 实例
+        this.client = ky.create({
+            prefixUrl: this.config.baseUrl,
+            timeout: this.config.timeout,
+            retry: this.config.retry,
+            headers: this.config.headers,
+        });
+        // 初始化双层缓存
+        this.cache = new HttpCache({
+            memoryMaxSize: this.config.memoryCacheMaxSize,
+            diskMaxSize: this.config.diskCacheMaxSize,
+            dbName: this.config.dbName,
+        });
+    }
+    /**
+     * 获取 ky 实例（用于扩展 hooks 等）
+     */
+    getKyInstance() {
+        return this.client;
+    }
+    /**
+     * 设置 ky 实例
+     */
+    setKyInstance(instance) {
+        this.client = instance;
+    }
+    /**
+     * 扩展 ky 实例
+     */
+    extendKy(options) {
+        this.client = this.client.extend(options);
+    }
+    /**
+     * 执行请求，返回 ApiStream
+     */
+    request(requestConfig, options = {}) {
+        const self = this;
+        return new ApiStream(async function* () {
+            const { method, path, headers: configHeaders, timeout, cache: cacheConfig, retry } = requestConfig;
+            const { pathParams, query, body, cache: overrideCache, headers: optionHeaders } = options;
+            // 替换路径参数（自动 URL 编码）
+            let url = path;
+            if (pathParams) {
+                for (const [key, value] of Object.entries(pathParams)) {
+                    url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
+                }
+            }
+            // 合并 headers
+            const mergedHeaders = {
+                ...self.config.headers,
+                ...configHeaders,
+                ...optionHeaders,
+            };
+            // 合并缓存配置（优先级：调用时覆盖 > 接口配置 > 全局默认 > 硬编码默认）
+            const finalCacheConfig = {
+                mode: CacheMode.OnlyRemote,
+                ttl: 5 * 60 * 1000, // 默认 5 分钟
+                keyHeaders: self.config.defaultKeyHeaders,
+                ...self.config.defaultCache, // 全局默认缓存配置
+                ...cacheConfig, // 接口级配置
+                ...overrideCache, // 调用时覆盖
+            };
+            // 生成缓存 key
+            const cacheKeyRequest = {
+                method,
+                path: url,
+                query: query,
+                body,
+                headers: mergedHeaders,
+                pathParams,
+            };
+            const cacheKey = finalCacheConfig.cacheKey
+                ? finalCacheConfig.cacheKey(cacheKeyRequest)
+                : defaultGenerateCacheKey(cacheKeyRequest, finalCacheConfig.keyHeaders);
+            // 过滤 query 参数中的 undefined/null
+            const filteredQuery = filterUndefined(query);
+            // 请求函数（返回完整响应信息，供缓存拦截器使用）
+            const doRequest = async () => {
+                const kyOptions = {
+                    method: method,
+                    headers: mergedHeaders,
+                    timeout,
+                    retry,
+                    searchParams: filteredQuery,
+                };
+                if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+                    kyOptions.json = body;
+                }
+                const response = await self.client(url, kyOptions);
+                const data = await response.json();
+                return {
+                    data,
+                    status: response.status,
+                    headers: response.headers,
+                };
+            };
+            // 根据缓存模式执行
+            yield* self.executeWithCacheStrategy(finalCacheConfig.mode, cacheKey, finalCacheConfig.ttl, doRequest, cacheKeyRequest);
+        });
+    }
+    /**
+     * 根据缓存策略执行请求
+     */
+    async *executeWithCacheStrategy(mode, cacheKey, ttl, fetchFn, request) {
+        switch (mode) {
+            case CacheMode.OnlyRemote:
+                yield* this.strategyOnlyRemote(cacheKey, ttl, fetchFn, request);
+                break;
+            case CacheMode.OnlyCache:
+                yield* this.strategyOnlyCache(cacheKey);
+                break;
+            case CacheMode.IfCache:
+                yield* this.strategyIfCache(cacheKey, ttl, fetchFn, request);
+                break;
+            case CacheMode.FirstRemote:
+                yield* this.strategyFirstRemote(cacheKey, ttl, fetchFn, request);
+                break;
+            case CacheMode.FirstCache:
+                yield* this.strategyFirstCache(cacheKey, ttl, fetchFn, request);
+                break;
+            case CacheMode.LastCache:
+                yield* this.strategyLastCache(cacheKey, ttl, fetchFn, request);
+                break;
+            default:
+                yield* this.strategyOnlyRemote(cacheKey, ttl, fetchFn, request);
+        }
+    }
+    /**
+     * 判断响应是否应该缓存
+     *
+     * 调用全局缓存拦截器，根据响应内容决定是否缓存。
+     * 如果没有配置拦截器，默认允许缓存。
+     *
+     * @param result 请求响应结果
+     * @param cacheKey 缓存 key
+     * @param request 请求信息
+     * @param defaultTtl 默认 TTL
+     * @returns 是否缓存及最终 TTL
+     */
+    async shouldCacheResponse(result, cacheKey, request, defaultTtl) {
+        var _a;
+        // 没有配置拦截器，默认允许缓存
+        if (!this.config.cacheInterceptor) {
+            return { shouldCache: true, ttl: defaultTtl };
+        }
+        // 构建拦截器上下文
+        const context = {
+            data: result.data,
+            status: result.status,
+            headers: result.headers,
+            request,
+            cacheKey,
+        };
+        try {
+            // 调用拦截器（支持同步和异步）
+            const interceptorResult = await this.config.cacheInterceptor(context);
+            // 处理返回结果
+            if (typeof interceptorResult === 'boolean') {
+                return { shouldCache: interceptorResult, ttl: defaultTtl };
+            }
+            return {
+                shouldCache: interceptorResult.shouldCache,
+                ttl: (_a = interceptorResult.ttl) !== null && _a !== void 0 ? _a : defaultTtl,
+            };
+        }
+        catch (error) {
+            // 拦截器执行出错，保守起见不缓存，但不影响正常响应
+            console.warn('[HttpClient] cacheInterceptor error:', error);
+            return { shouldCache: false, ttl: defaultTtl };
+        }
+    }
+    /**
+     * 条件缓存：根据拦截器结果决定是否写入缓存
+     */
+    async conditionalCache(result, cacheKey, request, defaultTtl) {
+        const { shouldCache, ttl } = await this.shouldCacheResponse(result, cacheKey, request, defaultTtl);
+        if (shouldCache) {
+            await this.cache.set(cacheKey, result.data, ttl);
+        }
+    }
+    /**
+     * OnlyRemote: 只从服务器拿
+     */
+    async *strategyOnlyRemote(cacheKey, ttl, fetchFn, request) {
+        const result = await fetchFn();
+        await this.conditionalCache(result, cacheKey, request, ttl);
+        yield { data: result.data, fromCache: false };
+    }
+    /**
+     * OnlyCache: 只从缓存拿
+     */
+    async *strategyOnlyCache(cacheKey) {
+        const cached = await this.cache.get(cacheKey);
+        if (cached) {
+            yield { data: cached.data, fromCache: true };
+        }
+        // 没有缓存就不 yield（类似 Observable.empty()）
+    }
+    /**
+     * IfCache: 有缓存返回缓存，否则请求网络
+     */
+    async *strategyIfCache(cacheKey, ttl, fetchFn, request) {
+        const cached = await this.cache.get(cacheKey);
+        if (cached) {
+            yield { data: cached.data, fromCache: true };
+            return;
+        }
+        const result = await fetchFn();
+        await this.conditionalCache(result, cacheKey, request, ttl);
+        yield { data: result.data, fromCache: false };
+    }
+    /**
+     * FirstRemote: 先从服务器获取，没网络则读缓存
+     */
+    async *strategyFirstRemote(cacheKey, ttl, fetchFn, request) {
+        try {
+            const result = await fetchFn();
+            await this.conditionalCache(result, cacheKey, request, ttl);
+            yield { data: result.data, fromCache: false };
+        }
+        catch (error) {
+            // 网络错误时尝试读取缓存
+            const cached = await this.cache.get(cacheKey);
+            if (cached) {
+                yield { data: cached.data, fromCache: true };
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * FirstCache: 先从本地缓存拿，然后从服务器拿，可能 yield 两次
+     */
+    async *strategyFirstCache(cacheKey, ttl, fetchFn, request) {
+        // 先尝试读取缓存
+        const cached = await this.cache.get(cacheKey);
+        if (cached) {
+            yield { data: cached.data, fromCache: true };
+        }
+        // 请求网络
+        try {
+            const result = await fetchFn();
+            await this.conditionalCache(result, cacheKey, request, ttl);
+            yield { data: result.data, fromCache: false };
+        }
+        catch (error) {
+            // 如果已有缓存，网络错误可以忽略
+            if (!cached) {
+                throw error;
+            }
+            // 有缓存时，网络错误静默处理
+        }
+    }
+    /**
+     * LastCache: 读上次缓存，没有则返回网络并同步缓存；有缓存也会后台同步网络但不 yield
+     */
+    async *strategyLastCache(cacheKey, ttl, fetchFn, request) {
+        const cached = await this.cache.get(cacheKey);
+        if (cached) {
+            // 有缓存，返回缓存，后台同步网络（不 yield）
+            yield { data: cached.data, fromCache: true };
+            // 后台静默更新（也会经过拦截器判断）
+            fetchFn()
+                .then((result) => this.conditionalCache(result, cacheKey, request, ttl))
+                .catch(() => {
+                /* 静默忽略错误 */
+            });
+        }
+        else {
+            // 无缓存，从网络获取
+            const result = await fetchFn();
+            await this.conditionalCache(result, cacheKey, request, ttl);
+            yield { data: result.data, fromCache: false };
+        }
+    }
+    /**
+     * 获取缓存实例（用于高级操作）
+     */
+    getCache() {
+        return this.cache;
+    }
+    /**
+     * 清空所有缓存
+     */
+    async clearCache() {
+        await this.cache.clear();
+    }
+}

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

@@ -0,0 +1,3 @@
+export { HttpClient } from './HttpClient';
+export { ApiStream } from './ApiStream';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/http/client/index.js

@@ -0,0 +1,2 @@
+export { HttpClient } from './HttpClient';
+export { ApiStream } from './ApiStream';