@taicode/common-web 1.1.0 → 1.1.1

package/output/helpers/cache-api/cache-api.d.ts

@@ -0,0 +1,13 @@
+type ApiFunc<P extends unknown[], R = unknown> = (...args: P) => Promise<R>;
+export declare class CacheApi<P extends unknown[], R> {
+    private func;
+    private cache;
+    private accessor pendingRequests;
+    constructor(func: ApiFunc<P, R>);
+    get loading(): boolean;
+    get empty(): boolean;
+    get value(): R | undefined;
+    send(...args: P): Promise<R>;
+}
+export {};
+//# sourceMappingURL=cache-api.d.ts.map

package/output/helpers/cache-api/cache-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.d.ts","sourceRoot":"","sources":["../../../source/helpers/cache-api/cache-api.ts"],"names":[],"mappings":"AAKA,KAAK,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAE3E,qBAAa,QAAQ,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC;IAO9B,OAAO,CAAC,IAAI;IANxB,OAAO,CAAC,KAAK,CAAqB;IAIlC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAI;gBAEhB,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAIvC,IACI,OAAO,IAAI,OAAO,CAErB;IAED,IACI,KAAK,IAAI,OAAO,CAEnB;IAED,IACI,KAAK,IAAI,CAAC,GAAG,SAAS,CAEzB;IAGK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmBnC"}

package/output/helpers/cache-api/cache-api.js

@@ -0,0 +1,114 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+import { action, computed, observable } from 'mobx';
+import { catchIt } from '@taicode/common-base';
+import { SideCache } from '../side-cache';
+let CacheApi = (() => {
+    var _a, _CacheApi_pendingRequests_accessor_storage;
+    var _b;
+    let _instanceExtraInitializers = [];
+    let _pendingRequests_decorators;
+    let _pendingRequests_initializers = [];
+    let _pendingRequests_extraInitializers = [];
+    let _get_loading_decorators;
+    let _get_empty_decorators;
+    let _get_value_decorators;
+    let _send_decorators;
+    return _a = class CacheApi {
+            // 记录当前正在进行的请求数量
+            get pendingRequests() { return __classPrivateFieldGet(this, _CacheApi_pendingRequests_accessor_storage, "f"); }
+            set pendingRequests(value) { __classPrivateFieldSet(this, _CacheApi_pendingRequests_accessor_storage, value, "f"); }
+            constructor(func) {
+                this.func = (__runInitializers(this, _instanceExtraInitializers), func);
+                this.cache = new SideCache();
+                _CacheApi_pendingRequests_accessor_storage.set(this, __runInitializers(this, _pendingRequests_initializers, 0));
+                __runInitializers(this, _pendingRequests_extraInitializers);
+                this.func = func;
+                this.send = this.send.bind(this);
+            }
+            get loading() {
+                return this.pendingRequests > 0;
+            }
+            get empty() {
+                return this.cache.empty;
+            }
+            get value() {
+                return this.cache.value;
+            }
+            async send(...args) {
+                // 增加待处理请求计数
+                this.pendingRequests++;
+                const result = await catchIt(async () => {
+                    return await this.cache.handle(args, async () => {
+                        return await this.func(...args);
+                    });
+                });
+                // 减少待处理请求计数
+                this.pendingRequests--;
+                if (result.isError()) {
+                    throw result.error;
+                }
+                return result.value;
+            }
+        },
+        _CacheApi_pendingRequests_accessor_storage = new WeakMap(),
+        (() => {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _pendingRequests_decorators = [observable];
+            _get_loading_decorators = [computed];
+            _get_empty_decorators = [computed];
+            _get_value_decorators = [computed];
+            _send_decorators = [(_b = action).bound.bind(_b)];
+            __esDecorate(_a, null, _pendingRequests_decorators, { kind: "accessor", name: "pendingRequests", static: false, private: false, access: { has: obj => "pendingRequests" in obj, get: obj => obj.pendingRequests, set: (obj, value) => { obj.pendingRequests = value; } }, metadata: _metadata }, _pendingRequests_initializers, _pendingRequests_extraInitializers);
+            __esDecorate(_a, null, _get_loading_decorators, { kind: "getter", name: "loading", static: false, private: false, access: { has: obj => "loading" in obj, get: obj => obj.loading }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(_a, null, _get_empty_decorators, { kind: "getter", name: "empty", static: false, private: false, access: { has: obj => "empty" in obj, get: obj => obj.empty }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(_a, null, _get_value_decorators, { kind: "getter", name: "value", static: false, private: false, access: { has: obj => "value" in obj, get: obj => obj.value }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(_a, null, _send_decorators, { kind: "method", name: "send", static: false, private: false, access: { has: obj => "send" in obj, get: obj => obj.send }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        })(),
+        _a;
+})();
+export { CacheApi };

package/output/helpers/cache-api/cache-api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache-api.test.d.ts.map

package/output/helpers/cache-api/cache-api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.test.d.ts","sourceRoot":"","sources":["../../../source/helpers/cache-api/cache-api.test.ts"],"names":[],"mappings":""}

package/output/helpers/cache-api/cache-api.test.js

@@ -0,0 +1,348 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { runInAction, configure } from 'mobx';
+import { CacheApi } from './cache-api';
+// 配置 MobX 在测试环境中的行为
+configure({
+    enforceActions: 'never',
+    computedRequiresReaction: false,
+    reactionRequiresObservable: false,
+    observableRequiresReaction: false,
+    disableErrorBoundaries: true
+});
+describe('CacheApi', () => {
+    let mockApiFunc;
+    let cacheApi;
+    beforeEach(() => {
+        mockApiFunc = vi.fn();
+        cacheApi = new CacheApi(mockApiFunc);
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('构造函数', () => {
+        it('应该正确初始化 CacheApi 实例', () => {
+            expect(cacheApi).toBeInstanceOf(CacheApi);
+            expect(cacheApi.value).toBeUndefined();
+        });
+        it('应该正确绑定 send 方法', () => {
+            const { send } = cacheApi;
+            expect(typeof send).toBe('function');
+        });
+    });
+    describe('value getter', () => {
+        it('初始状态下应该返回 undefined', () => {
+            expect(cacheApi.value).toBeUndefined();
+        });
+        it('应该在成功调用后返回缓存的值', async () => {
+            const expectedResult = 'test-result';
+            mockApiFunc.mockResolvedValue(expectedResult);
+            await cacheApi.send('param1', 123);
+            expect(cacheApi.value).toBe(expectedResult);
+        });
+        it('应该在多次调用后返回最新的缓存值', async () => {
+            const result1 = 'result-1';
+            const result2 = 'result-2';
+            mockApiFunc.mockResolvedValueOnce(result1);
+            await cacheApi.send('param1', 123);
+            expect(cacheApi.value).toBe(result1);
+            mockApiFunc.mockResolvedValueOnce(result2);
+            await cacheApi.send('param2', 456);
+            expect(cacheApi.value).toBe(result2);
+        });
+    });
+    describe('empty getter', () => {
+        it('初始状态下应该返回 true', () => {
+            expect(cacheApi.empty).toBe(true);
+        });
+        it('成功调用后应该返回 false', async () => {
+            mockApiFunc.mockResolvedValue('test-result');
+            await cacheApi.send('param1', 123);
+            expect(cacheApi.empty).toBe(false);
+        });
+        it('即使调用失败也应该保持 true', async () => {
+            const error = new Error('API Error');
+            mockApiFunc.mockRejectedValue(error);
+            try {
+                await cacheApi.send('param1', 123);
+            }
+            catch (e) {
+                // 忽略错误
+            }
+            expect(cacheApi.empty).toBe(true);
+        });
+        it('empty 应该是一个 computed 属性', () => {
+            const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(cacheApi), 'empty');
+            expect(descriptor).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.get).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.set).toBeUndefined();
+        });
+    });
+    describe('send 方法', () => {
+        it('应该调用传入的 API 函数', async () => {
+            const expectedResult = 'api-result';
+            mockApiFunc.mockResolvedValue(expectedResult);
+            const result = await cacheApi.send('test', 42);
+            expect(mockApiFunc).toHaveBeenCalledTimes(1);
+            expect(mockApiFunc).toHaveBeenCalledWith('test', 42);
+            expect(result).toBe(expectedResult);
+        });
+        it('应该正确传递多个参数', async () => {
+            const params = ['hello', 999];
+            mockApiFunc.mockResolvedValue('success');
+            await cacheApi.send(...params);
+            expect(mockApiFunc).toHaveBeenCalledWith(...params);
+        });
+        it('应该返回 API 函数的结果', async () => {
+            const expectedResult = { data: 'test', status: 'ok' };
+            mockApiFunc.mockResolvedValue(expectedResult);
+            const result = await cacheApi.send('param', 1);
+            expect(result).toEqual(expectedResult);
+        });
+        it('应该处理 API 函数抛出的异常', async () => {
+            const error = new Error('API Error');
+            mockApiFunc.mockRejectedValue(error);
+            await expect(cacheApi.send('param', 1)).rejects.toThrow('API Error');
+        });
+    });
+    describe('缓存功能', () => {
+        it('相同参数应该使用缓存', async () => {
+            const result = 'cached-result';
+            mockApiFunc.mockResolvedValue(result);
+            // 第一次调用
+            const firstResult = await cacheApi.send('same', 123);
+            expect(firstResult).toBe(result);
+            expect(cacheApi.value).toBe(result);
+            // 第二次调用相同参数，应该从缓存返回
+            const secondResult = await cacheApi.send('same', 123);
+            expect(secondResult).toBe(result);
+            expect(cacheApi.value).toBe(result);
+            // API 函数应该被调用两次（SideCache 的 handle 方法会每次都调用）
+            expect(mockApiFunc).toHaveBeenCalledTimes(2);
+        });
+        it('不同参数应该触发新的 API 调用', async () => {
+            mockApiFunc.mockResolvedValueOnce('result1');
+            mockApiFunc.mockResolvedValueOnce('result2');
+            await cacheApi.send('param1', 1);
+            await cacheApi.send('param2', 2);
+            expect(mockApiFunc).toHaveBeenCalledTimes(2);
+            expect(mockApiFunc).toHaveBeenNthCalledWith(1, 'param1', 1);
+            expect(mockApiFunc).toHaveBeenNthCalledWith(2, 'param2', 2);
+        });
+        it('应该正确更新当前缓存的 key', async () => {
+            mockApiFunc.mockResolvedValueOnce('value1');
+            mockApiFunc.mockResolvedValueOnce('value2');
+            await cacheApi.send('key1', 1);
+            expect(cacheApi.value).toBe('value1');
+            await cacheApi.send('key2', 2);
+            expect(cacheApi.value).toBe('value2');
+        });
+    });
+    describe('异步操作', () => {
+        it('应该正确处理并发调用', async () => {
+            let resolveCount = 0;
+            mockApiFunc.mockImplementation(async (param) => {
+                await new Promise(resolve => setTimeout(resolve, 10));
+                return `result-${param}-${++resolveCount}`;
+            });
+            const [result1, result2, result3] = await Promise.all([
+                cacheApi.send('param1', 1),
+                cacheApi.send('param2', 2),
+                cacheApi.send('param3', 3)
+            ]);
+            expect(result1).toMatch(/result-param1-\d/);
+            expect(result2).toMatch(/result-param2-\d/);
+            expect(result3).toMatch(/result-param3-\d/);
+            expect(mockApiFunc).toHaveBeenCalledTimes(3);
+        });
+        it('应该在异步操作完成后更新 value', async () => {
+            const delay = 50;
+            mockApiFunc.mockImplementation(async () => {
+                await new Promise(resolve => setTimeout(resolve, delay));
+                return 'delayed-result';
+            });
+            // 开始异步操作，此时 value 应该还是之前的值
+            const promise = cacheApi.send('test', 1);
+            // 等待一小段时间，但还没完成
+            await new Promise(resolve => setTimeout(resolve, delay / 2));
+            // 完成异步操作
+            const result = await promise;
+            expect(result).toBe('delayed-result');
+            expect(cacheApi.value).toBe('delayed-result');
+        });
+    });
+    describe('边缘情况', () => {
+        it('应该处理 null 返回值', async () => {
+            mockApiFunc.mockResolvedValue(null);
+            const result = await cacheApi.send('test', 1);
+            expect(result).toBeNull();
+            expect(cacheApi.value).toBeNull();
+        });
+        it('应该处理 undefined 返回值', async () => {
+            mockApiFunc.mockResolvedValue(undefined);
+            const result = await cacheApi.send('test', 1);
+            expect(result).toBeUndefined();
+            expect(cacheApi.value).toBeUndefined();
+        });
+        it('应该处理复杂对象参数', async () => {
+            const complexParam = { nested: { value: 'test' }, array: [1, 2, 3] };
+            const complexMockFunc = vi.fn();
+            complexMockFunc.mockResolvedValue('complex-result');
+            // 创建一个接受复杂参数的 CacheApi
+            const complexCacheApi = new CacheApi(complexMockFunc);
+            const result = await complexCacheApi.send(complexParam);
+            expect(result).toBe('complex-result');
+            expect(complexMockFunc).toHaveBeenCalledWith(complexParam);
+        });
+        it('should handle no parameters', async () => {
+            const noParamApi = new CacheApi(() => Promise.resolve('no-param-result'));
+            const result = await noParamApi.send();
+            expect(result).toBe('no-param-result');
+        });
+    });
+    describe('MobX 集成', () => {
+        it('value 应该是一个 computed 属性', () => {
+            // 通过检查属性描述符来验证这是一个 computed 属性
+            const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(cacheApi), 'value');
+            expect(descriptor).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.get).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.set).toBeUndefined();
+        });
+        it('value 变化应该触发 MobX 反应', async () => {
+            let reactionCount = 0;
+            let lastValue = undefined;
+            // 创建一个简单的反应来监听 value 变化
+            const disposer = runInAction(() => {
+                const reaction = () => {
+                    reactionCount++;
+                    lastValue = cacheApi.value;
+                };
+                // 初始调用
+                reaction();
+                return reaction;
+            });
+            mockApiFunc.mockResolvedValue('new-value');
+            await cacheApi.send('test', 1);
+            // 清理
+            if (typeof disposer === 'function') {
+                disposer();
+            }
+            expect(lastValue).toBe('new-value');
+        });
+    });
+    describe('类型安全', () => {
+        it('应该保持参数类型安全', () => {
+            // 这个测试主要是在编译时进行类型检查
+            // 如果类型不匹配，TypeScript 编译器会报错
+            const typedApi = new CacheApi((str, num, bool) => {
+                return Promise.resolve({ result: `${str}-${num}-${bool}` });
+            });
+            // 正确的调用
+            expect(() => typedApi.send('test', 42, true)).not.toThrow();
+            // 以下调用在 TypeScript 中会产生编译错误（在运行时测试中跳过）
+            // typedApi.send('test', 'wrong-type', true)  // 第二个参数应该是 number
+            // typedApi.send('test', 42)  // 缺少第三个参数
+        });
+    });
+    describe('loading 状态', () => {
+        it('初始状态下 loading 应该为 false', () => {
+            expect(cacheApi.loading).toBe(false);
+        });
+        it('发送请求时 loading 应该为 true', async () => {
+            let resolveFn;
+            const promise = new Promise((resolve) => {
+                resolveFn = resolve;
+            });
+            mockApiFunc.mockReturnValue(promise);
+            // 开始请求
+            const sendPromise = cacheApi.send('test', 1);
+            // 此时应该是 loading 状态
+            expect(cacheApi.loading).toBe(true);
+            // 完成请求
+            resolveFn('result');
+            await sendPromise;
+            // 请求完成后 loading 应该为 false
+            expect(cacheApi.loading).toBe(false);
+        });
+        it('请求失败后 loading 应该为 false', async () => {
+            const error = new Error('API Error');
+            mockApiFunc.mockRejectedValue(error);
+            try {
+                await cacheApi.send('test', 1);
+            }
+            catch (e) {
+                // 忽略错误
+            }
+            expect(cacheApi.loading).toBe(false);
+        });
+        it('并发请求时 loading 状态应该正确处理', async () => {
+            const resolvers = [];
+            mockApiFunc.mockImplementation((param) => {
+                return new Promise((resolve) => {
+                    resolvers.push((value) => resolve(`${param}-${value}`));
+                });
+            });
+            // 启动三个并发请求
+            const promise1 = cacheApi.send('req1', 1);
+            const promise2 = cacheApi.send('req2', 2);
+            const promise3 = cacheApi.send('req3', 3);
+            // 此时应该有三个请求正在进行，loading 为 true
+            expect(cacheApi.loading).toBe(true);
+            // 完成第一个请求
+            resolvers[0]('result1');
+            await promise1;
+            // 还有两个请求在进行，loading 仍为 true
+            expect(cacheApi.loading).toBe(true);
+            // 完成第二个请求
+            resolvers[1]('result2');
+            await promise2;
+            // 还有一个请求在进行，loading 仍为 true
+            expect(cacheApi.loading).toBe(true);
+            // 完成第三个请求
+            resolvers[2]('result3');
+            await promise3;
+            // 所有请求完成，loading 为 false
+            expect(cacheApi.loading).toBe(false);
+        });
+        it('部分并发请求失败时 loading 状态应该正确', async () => {
+            let resolveSuccess;
+            let rejectError;
+            mockApiFunc.mockImplementation((param) => {
+                if (param === 'success') {
+                    return new Promise((resolve) => {
+                        resolveSuccess = resolve;
+                    });
+                }
+                else {
+                    return new Promise((_, reject) => {
+                        rejectError = reject;
+                    });
+                }
+            });
+            // 启动两个请求，一个成功一个失败
+            const successPromise = cacheApi.send('success', 1);
+            const errorPromise = cacheApi.send('error', 2);
+            expect(cacheApi.loading).toBe(true);
+            // 先让失败的请求完成
+            rejectError(new Error('Failed'));
+            try {
+                await errorPromise;
+            }
+            catch (e) {
+                // 忽略错误
+            }
+            // 还有一个成功的请求在进行，loading 仍为 true
+            expect(cacheApi.loading).toBe(true);
+            // 完成成功的请求
+            resolveSuccess('success-result');
+            await successPromise;
+            // 所有请求完成，loading 为 false
+            expect(cacheApi.loading).toBe(false);
+        });
+        it('loading 应该是一个 computed 属性', () => {
+            const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(cacheApi), 'loading');
+            expect(descriptor).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.get).toBeDefined();
+            expect(descriptor === null || descriptor === void 0 ? void 0 : descriptor.set).toBeUndefined();
+        });
+    });
+});

package/output/helpers/cache-api/index.d.ts

@@ -0,0 +1,2 @@
+export { CacheApi } from './cache-api';
+//# sourceMappingURL=index.d.ts.map

package/output/helpers/cache-api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/helpers/cache-api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA"}

package/output/helpers/cache-api/index.js

@@ -0,0 +1 @@
+export { CacheApi } from './cache-api';

package/output/helpers/side-cache/side-cache.d.ts

@@ -1,7 +1,10 @@
 export declare class SideCache<T> {
+    private accessor emptyFlag;
     private accessor currentKey;
     private accessor cache;
-    get value(): T | null;
-    handle<F extends ((...args: unknown[]) => Promise<T | null>)>(key: unknown, func: F): Promise<T | null>;
+    get value(): T | undefined;
+    get empty(): boolean;
+    handle<F extends ((...args: unknown[]) => T)>(key: unknown, func: F): T;
+    handle<F extends ((...args: unknown[]) => Promise<T> | T)>(key: unknown, func: F): Promise<T> | T;
 }
 //# sourceMappingURL=side-cache.d.ts.map

package/output/helpers/side-cache/side-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"side-cache.d.ts","sourceRoot":"","sources":["../../../source/helpers/side-cache/side-cache.ts"],"names":[],"mappings":"AAOA,qBAAa,SAAS,CAAC,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IAGjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,IACW,KAAK,IAAI,CAAC,GAAG,IAAI,CAG3B;IAGY,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAiBrH"}
+{"version":3,"file":"side-cache.d.ts","sourceRoot":"","sources":["../../../source/helpers/side-cache/side-cache.ts"],"names":[],"mappings":"AAWA,qBAAa,SAAS,CAAC,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAG1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAG/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,IACW,KAAK,IAAI,CAAC,GAAG,SAAS,CAIhC;IAED,IACW,KAAK,IAAI,OAAO,CAE1B;IAED,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC;IACvE,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;CAuClG"}

package/output/helpers/side-cache/side-cache.js

@@ -44,10 +44,16 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 import { action, computed, observable, runInAction } from 'mobx';
+function isPromiseLike(value) {
+    return value != null && typeof value.then === 'function';
+}
 let SideCache = (() => {
-    var _a, _SideCache_currentKey_accessor_storage, _SideCache_cache_accessor_storage;
+    var _a, _SideCache_emptyFlag_accessor_storage, _SideCache_currentKey_accessor_storage, _SideCache_cache_accessor_storage;
     var _b, _c;
     let _instanceExtraInitializers = [];
+    let _emptyFlag_decorators;
+    let _emptyFlag_initializers = [];
+    let _emptyFlag_extraInitializers = [];
     let _currentKey_decorators;
     let _currentKey_initializers = [];
     let _currentKey_extraInitializers = [];
@@ -55,25 +61,44 @@ let SideCache = (() => {
     let _cache_initializers = [];
     let _cache_extraInitializers = [];
     let _get_value_decorators;
+    let _get_empty_decorators;
     let _handle_decorators;
     return _a = class SideCache {
+            get emptyFlag() { return __classPrivateFieldGet(this, _SideCache_emptyFlag_accessor_storage, "f"); }
+            set emptyFlag(value) { __classPrivateFieldSet(this, _SideCache_emptyFlag_accessor_storage, value, "f"); }
             get currentKey() { return __classPrivateFieldGet(this, _SideCache_currentKey_accessor_storage, "f"); }
             set currentKey(value) { __classPrivateFieldSet(this, _SideCache_currentKey_accessor_storage, value, "f"); }
             get cache() { return __classPrivateFieldGet(this, _SideCache_cache_accessor_storage, "f"); }
             set cache(value) { __classPrivateFieldSet(this, _SideCache_cache_accessor_storage, value, "f"); }
             get value() {
-                var _b;
                 if (this.currentKey == null)
-                    return null;
-                return ((_b = this.cache[this.currentKey]) === null || _b === void 0 ? void 0 : _b.data) || null;
+                    return undefined;
+                const cacheItem = this.cache[this.currentKey];
+                return cacheItem ? cacheItem.data : undefined;
+            }
+            get empty() {
+                return this.emptyFlag;
             }
-            async handle(key, func) {
-                const keyStringify = JSON.stringify(key); // 不需要跨设备、软件一致，所以直接用 JSON.stringify
+            handle(key, func) {
+                var _b;
+                // 不需要跨设备、软件一致，所以直接用 JSON.stringify
+                // 但需要处理 JSON.stringify(undefined) 返回 undefined 的情况
+                const keyStringify = (_b = JSON.stringify(key)) !== null && _b !== void 0 ? _b : 'undefined';
+                // 这会让外面立马可以拿到之前缓存的值，如果存在的话
                 runInAction(() => this.currentKey = keyStringify);
-                const funcReturn = await func();
-                if (funcReturn == null)
-                    return funcReturn;
+                const funcReturn = func();
+                if (isPromiseLike(funcReturn)) {
+                    return funcReturn.then(result => runInAction(() => {
+                        this.emptyFlag = false;
+                        this.cache = Object.assign(Object.assign({}, this.cache), { [keyStringify]: {
+                                data: result,
+                                createTime: new Date().toISOString()
+                            } });
+                        return result;
+                    }));
+                }
                 runInAction(() => {
+                    this.emptyFlag = false;
                     this.cache = Object.assign(Object.assign({}, this.cache), { [keyStringify]: {
                             data: funcReturn,
                             createTime: new Date().toISOString()
@@ -82,22 +107,28 @@ let SideCache = (() => {
                 return funcReturn;
             }
             constructor() {
-                _SideCache_currentKey_accessor_storage.set(this, (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _currentKey_initializers, null)));
+                _SideCache_emptyFlag_accessor_storage.set(this, (__runInitializers(this, _instanceExtraInitializers), __runInitializers(this, _emptyFlag_initializers, true)));
+                _SideCache_currentKey_accessor_storage.set(this, (__runInitializers(this, _emptyFlag_extraInitializers), __runInitializers(this, _currentKey_initializers, void 0)));
                 _SideCache_cache_accessor_storage.set(this, (__runInitializers(this, _currentKey_extraInitializers), __runInitializers(this, _cache_initializers, {})));
                 __runInitializers(this, _cache_extraInitializers);
             }
         },
+        _SideCache_emptyFlag_accessor_storage = new WeakMap(),
         _SideCache_currentKey_accessor_storage = new WeakMap(),
         _SideCache_cache_accessor_storage = new WeakMap(),
         (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _emptyFlag_decorators = [observable];
             _currentKey_decorators = [observable];
             _cache_decorators = [(_b = observable).ref.bind(_b)];
             _get_value_decorators = [computed];
+            _get_empty_decorators = [computed];
             _handle_decorators = [(_c = action).bound.bind(_c)];
+            __esDecorate(_a, null, _emptyFlag_decorators, { kind: "accessor", name: "emptyFlag", static: false, private: false, access: { has: obj => "emptyFlag" in obj, get: obj => obj.emptyFlag, set: (obj, value) => { obj.emptyFlag = value; } }, metadata: _metadata }, _emptyFlag_initializers, _emptyFlag_extraInitializers);
             __esDecorate(_a, null, _currentKey_decorators, { kind: "accessor", name: "currentKey", static: false, private: false, access: { has: obj => "currentKey" in obj, get: obj => obj.currentKey, set: (obj, value) => { obj.currentKey = value; } }, metadata: _metadata }, _currentKey_initializers, _currentKey_extraInitializers);
             __esDecorate(_a, null, _cache_decorators, { kind: "accessor", name: "cache", static: false, private: false, access: { has: obj => "cache" in obj, get: obj => obj.cache, set: (obj, value) => { obj.cache = value; } }, metadata: _metadata }, _cache_initializers, _cache_extraInitializers);
             __esDecorate(_a, null, _get_value_decorators, { kind: "getter", name: "value", static: false, private: false, access: { has: obj => "value" in obj, get: obj => obj.value }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(_a, null, _get_empty_decorators, { kind: "getter", name: "empty", static: false, private: false, access: { has: obj => "empty" in obj, get: obj => obj.empty }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(_a, null, _handle_decorators, { kind: "method", name: "handle", static: false, private: false, access: { has: obj => "handle" in obj, get: obj => obj.handle }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         })(),

package/output/helpers/side-cache/side-cache.test.js

@@ -1,89 +1,179 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { SideCache } from './side-cache';
 describe('SideCache', () => {
-    let sideCache;
+    let cache;
     beforeEach(() => {
-        sideCache = new SideCache();
+        cache = new SideCache();
     });
-    it('应该创建一个新的SideCache实例', () => {
-        expect(sideCache).toBeInstanceOf(SideCache);
-        expect(sideCache.value).toBeNull();
+    describe('初始状态', () => {
+        it('应该初始化为空状态', () => {
+            expect(cache.empty).toBe(true);
+            expect(cache.value).toBe(undefined);
+        });
     });
-    it('应该处理异步函数并缓存结果', async () => {
-        const mockFunc = vi.fn().mockResolvedValue('测试数据');
-        const key = { id: 1, name: '测试键' };
-        const result = await sideCache.handle(key, mockFunc);
-        expect(result).toBe('测试数据');
-        expect(sideCache.value).toBe('测试数据');
-        expect(mockFunc).toHaveBeenCalledTimes(1);
+    describe('同步缓存', () => {
+        it('应该能够缓存同步函数的结果', () => {
+            const mockFunc = vi.fn(() => 'test-result');
+            const key = 'test-key';
+            const result = cache.handle(key, mockFunc);
+            expect(result).toBe('test-result');
+            expect(mockFunc).toHaveBeenCalledTimes(1);
+            expect(cache.empty).toBe(false);
+            expect(cache.value).toBe('test-result');
+        });
+        it('应该对相同 key 返回缓存的结果', () => {
+            const mockFunc = vi.fn(() => 'cached-result');
+            const key = 'same-key';
+            // 第一次调用
+            const result1 = cache.handle(key, mockFunc);
+            expect(result1).toBe('cached-result');
+            expect(mockFunc).toHaveBeenCalledTimes(1);
+            // 第二次调用相同 key，应该直接返回缓存
+            const result2 = cache.handle(key, mockFunc);
+            expect(result2).toBe('cached-result');
+            expect(mockFunc).toHaveBeenCalledTimes(2); // 函数仍会被调用，但会更新缓存
+            expect(cache.value).toBe('cached-result');
+        });
+        it('应该对不同 key 分别缓存', () => {
+            const mockFunc1 = vi.fn(() => 'result1');
+            const mockFunc2 = vi.fn(() => 'result2');
+            cache.handle('key1', mockFunc1);
+            expect(cache.value).toBe('result1');
+            cache.handle('key2', mockFunc2);
+            expect(cache.value).toBe('result2');
+            // 切换回 key1
+            cache.handle('key1', mockFunc1);
+            expect(cache.value).toBe('result1');
+        });
     });
-    it('应该为不同的键缓存不同的值', async () => {
-        const mockFunc1 = vi.fn().mockResolvedValue('数据1');
-        const mockFunc2 = vi.fn().mockResolvedValue('数据2');
-        const key1 = { id: 1 };
-        const key2 = { id: 2 };
-        await sideCache.handle(key1, mockFunc1);
-        expect(sideCache.value).toBe('数据1');
-        await sideCache.handle(key2, mockFunc2);
-        expect(sideCache.value).toBe('数据2');
+    describe('异步缓存', () => {
+        it('应该能够缓存异步函数的结果', async () => {
+            const mockAsyncFunc = vi.fn(async () => 'async-result');
+            const key = 'async-key';
+            const promise = cache.handle(key, mockAsyncFunc);
+            expect(promise).toBeInstanceOf(Promise);
+            const result = await promise;
+            expect(result).toBe('async-result');
+            expect(mockAsyncFunc).toHaveBeenCalledTimes(1);
+            expect(cache.empty).toBe(false);
+            expect(cache.value).toBe('async-result');
+        });
+        it('应该在异步函数执行期间立即设置 currentKey', async () => {
+            const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+            const mockAsyncFunc = vi.fn(async () => {
+                await delay(10);
+                return 'delayed-result';
+            });
+            const key = 'delayed-key';
+            // 在异步函数开始执行时，currentKey 应该已经设置
+            const promise = cache.handle(key, mockAsyncFunc);
+            // 此时异步函数还在执行，但 currentKey 已设置
+            // 如果之前有缓存，value 应该能立即获取到
+            const result = await promise;
+            expect(result).toBe('delayed-result');
+            expect(cache.value).toBe('delayed-result');
+        });
+        it('应该处理异步函数的错误', async () => {
+            const error = new Error('Async error');
+            const mockAsyncFunc = vi.fn(async () => {
+                throw error;
+            });
+            const key = 'error-key';
+            await expect(cache.handle(key, mockAsyncFunc)).rejects.toThrow('Async error');
+            expect(mockAsyncFunc).toHaveBeenCalledTimes(1);
+        });
     });
-    it('应该在函数返回null时不缓存结果', async () => {
-        const mockFunc = vi.fn().mockResolvedValue(null);
-        const key = { id: 1 };
-        const result = await sideCache.handle(key, mockFunc);
-        expect(result).toBeNull();
-        expect(sideCache.value).toBeNull();
+    describe('key 序列化', () => {
+        it('应该正确处理不同类型的 key', () => {
+            const mockFunc = vi.fn(() => 'result');
+            // 字符串 key
+            cache.handle('string-key', mockFunc);
+            expect(cache.value).toBe('result');
+            // 数字 key
+            cache.handle(123, mockFunc);
+            expect(cache.value).toBe('result');
+            // 对象 key
+            cache.handle({ id: 1, name: 'test' }, mockFunc);
+            expect(cache.value).toBe('result');
+            // 数组 key
+            cache.handle([1, 2, 3], mockFunc);
+            expect(cache.value).toBe('result');
+        });
+        it('相同内容的对象 key 应该被视为相同', () => {
+            const mockFunc = vi.fn(() => 'object-result');
+            const key1 = { id: 1, name: 'test' };
+            const key2 = { id: 1, name: 'test' };
+            cache.handle(key1, mockFunc);
+            const result1 = cache.value;
+            cache.handle(key2, mockFunc);
+            const result2 = cache.value;
+            expect(result1).toBe(result2);
+            expect(result1).toBe('object-result');
+        });
     });
-    it('应该正确处理相同键的多次调用', async () => {
-        const mockFunc = vi.fn().mockResolvedValue('缓存数据');
-        const key = { id: 1, name: '相同键' };
-        // 第一次调用
-        await sideCache.handle(key, mockFunc);
-        expect(sideCache.value).toBe('缓存数据');
-        // 第二次调用相同键
-        const mockFunc2 = vi.fn().mockResolvedValue('新数据');
-        await sideCache.handle(key, mockFunc2);
-        expect(sideCache.value).toBe('新数据');
-        // 验证两个函数都被调用了
-        expect(mockFunc).toHaveBeenCalledTimes(1);
-        expect(mockFunc2).toHaveBeenCalledTimes(1);
+    describe('缓存时间戳', () => {
+        it('应该为缓存项添加创建时间', () => {
+            const mockFunc = vi.fn(() => 'timestamped-result');
+            const key = 'timestamp-key';
+            const beforeTime = new Date().toISOString();
+            cache.handle(key, mockFunc);
+            const afterTime = new Date().toISOString();
+            // 访问私有属性进行测试（仅用于测试目的）
+            const cacheData = cache.cache;
+            const cachedItem = cacheData[JSON.stringify(key)];
+            expect(cachedItem).toBeDefined();
+            expect(cachedItem.data).toBe('timestamped-result');
+            expect(cachedItem.createTime).toBeDefined();
+            expect(typeof cachedItem.createTime).toBe('string');
+            // 验证时间戳在合理范围内
+            expect(cachedItem.createTime >= beforeTime).toBe(true);
+            expect(cachedItem.createTime <= afterTime).toBe(true);
+        });
     });
-    it('应该正确序列化复杂的键对象', async () => {
-        const mockFunc = vi.fn().mockResolvedValue('复杂键数据');
-        const complexKey = {
-            nested: {
-                array: [1, 2, 3],
-                string: '测试',
-                boolean: true
-            }
-        };
-        await sideCache.handle(complexKey, mockFunc);
-        expect(sideCache.value).toBe('复杂键数据');
-    });
-    it('应该处理异步函数抛出的错误', async () => {
-        const mockFunc = vi.fn().mockRejectedValue(new Error('测试错误'));
-        const key = { id: 1 };
-        await expect(() => sideCache.handle(key, mockFunc)).rejects.toThrow('测试错误');
-        expect(sideCache.value).toBeNull();
-    });
-    it('应该在没有设置当前键时返回null', () => {
-        expect(sideCache.value).toBeNull();
+    describe('边界情况', () => {
+        it('应该处理 null 和 undefined key', () => {
+            const mockFunc1 = vi.fn(() => 'null-key-result');
+            const mockFunc2 = vi.fn(() => 'undefined-key-result');
+            cache.handle(null, mockFunc1);
+            expect(cache.value).toBe('null-key-result');
+            cache.handle(undefined, mockFunc2);
+            expect(cache.value).toBe('undefined-key-result');
+        });
+        it('应该处理返回 null 或 undefined 的函数', () => {
+            const nullFunc = vi.fn(() => null);
+            const undefinedFunc = vi.fn(() => undefined);
+            cache.handle('null-key', nullFunc);
+            expect(cache.value).toBe(null);
+            expect(cache.empty).toBe(false);
+            cache.handle('undefined-key', undefinedFunc);
+            expect(cache.value).toBe(undefined);
+            expect(cache.empty).toBe(false);
+        });
+        it('应该处理返回 Promise.resolve(null) 的异步函数', async () => {
+            const nullAsyncFunc = vi.fn(async () => null);
+            const result = await cache.handle('async-null', nullAsyncFunc);
+            expect(result).toBe(null);
+            expect(cache.value).toBe(null);
+            expect(cache.empty).toBe(false);
+        });
     });
-    it('应该处理数字类型的缓存数据', async () => {
-        const numberCache = new SideCache();
-        const mockFunc = vi.fn().mockResolvedValue(42);
-        const key = 'number-key';
-        const result = await numberCache.handle(key, mockFunc);
-        expect(result).toBe(42);
-        expect(numberCache.value).toBe(42);
-    });
-    it('应该处理对象类型的缓存数据', async () => {
-        const objectCache = new SideCache();
-        const testData = { id: 1, name: '测试对象' };
-        const mockFunc = vi.fn().mockResolvedValue(testData);
-        const key = 'object-key';
-        const result = await objectCache.handle(key, mockFunc);
-        expect(result).toEqual(testData);
-        expect(objectCache.value).toEqual(testData);
+    describe('类型检查', () => {
+        it('应该正确识别 Promise-like 对象', async () => {
+            let thenCallback;
+            const promiseLike = {
+                then: vi.fn((callback) => {
+                    thenCallback = callback;
+                    return promiseLike;
+                })
+            };
+            const mockFunc = vi.fn(() => promiseLike);
+            const result = cache.handle('promise-like', mockFunc);
+            expect(result).toBe(promiseLike);
+            expect(promiseLike.then).toHaveBeenCalled();
+            // 模拟 Promise 完成
+            if (thenCallback) {
+                thenCallback('resolved-value');
+            }
+        });
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-web",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -18,6 +18,7 @@
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",
+    "prepublishOnly": "npm run build",
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch"
   },