@taicode/common-web 1.1.1 → 1.1.2

package/output/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/cache-api/cache-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-api.d.ts","sourceRoot":"","sources":["../../source/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/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/cache-api/cache-api.test.d.ts

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

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

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

package/output/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/cache-api/index.d.ts

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

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

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

package/output/cache-api/index.js

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

package/output/service/index.d.ts

@@ -0,0 +1,2 @@
+export { useService, ServiceProvider } from './service';
+//# sourceMappingURL=index.d.ts.map

package/output/service/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA"}

package/output/service/index.js

@@ -0,0 +1 @@
+export { useService, ServiceProvider } from './service';

package/output/service/service.d.ts

@@ -0,0 +1,114 @@
+/**
+ * React 服务层集成工具
+ *
+ * 本模块提供了在 React 应用中集成依赖注入（DI）和状态管理（Mobx）的工具函数和组件。
+ * 主要功能包括：
+ * - 通过 useService Hook 使用全局注册的服务，并自动响应状态变化
+ * - 通过 useLocalService Hook 创建局部服务实例，避免全局状态污染
+ * - 通过 ServiceProvider 组件提供服务容器上下文
+ * - 自动初始化服务实例
+ *
+ * @example
+ * ```tsx
+ * // 1. 定义服务
+ * class UserService extends Service {
+ *   @observable users: User[] = []
+ *   async init() { return true }
+ * }
+ *
+ * // 2. 在根组件提供服务
+ * function App() {
+ *   return (
+ *     <ServiceProvider services={[UserService]}>
+ *       <UserList />
+ *     </ServiceProvider>
+ *   )
+ * }
+ *
+ * // 3. 在组件中使用服务
+ * function UserList() {
+ *   const users = useService(UserService, s => s.users)
+ *   return <div>{users.map(user => <div key={user.id}>{user.name}</div>)}</div>
+ * }
+ * ```
+ */
+import { Token, Container, Provider } from '@needle-di/core';
+import React from 'react';
+/**
+ * 使用全局注册的服务 Hook
+ *
+ * 该 Hook 从 DI 容器中获取指定的服务实例，并通过 selector 函数选择需要的数据。
+ * 当选择的数据发生变化时，组件会自动重新渲染。
+ *
+ * @template T 服务类型
+ * @template U 选择器返回的数据类型
+ * @param target 服务的 Token，用于从容器中获取服务实例
+ * @param selector 选择器函数，从服务实例中选择需要的数据
+ * @returns 选择器函数的返回值
+ *
+ * @throws {Error} 当组件不在 ServiceProvider 内部时抛出错误
+ *
+ * @example
+ * ```tsx
+ * // 获取用户列表
+ * const users = useService(UserService, service => service.users)
+ *
+ * // 获取当前用户信息
+ * const currentUser = useService(UserService, service => service.currentUser)
+ *
+ * // 获取用户数量
+ * const userCount = useService(UserService, service => service.users.length)
+ * ```
+ */
+export declare function useService<T, U>(target: Token<T>, selector: (v: T) => U): U;
+/**
+ * ServiceProvider 组件的属性接口
+ */
+interface ServiceProviderProps {
+    /** 要注册到容器中的服务提供者数组 */
+    services: Provider<unknown>[];
+    /** 子组件 */
+    children: React.ReactNode;
+}
+/**
+ * 服务提供者组件
+ *
+ * 该组件为其子组件树提供依赖注入容器上下文。
+ * 它会自动复用父级容器（如果存在），并创建子容器来管理新的服务实例。
+ *
+ * 特性：
+ * - 自动复用父级容器，避免重复创建
+ * - 支持容器层级结构，子容器可以覆盖父容器的服务
+ * - 自动初始化实现了 Service 接口的服务
+ *
+ * @param props 组件属性
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ServiceProvider services={[UserService, ProductService]}>
+ *       <Router>
+ *         <Routes>
+ *           <Route path="/users" element={<UserPage />} />
+ *           <Route path="/products" element={<ProductPage />} />
+ *         </Routes>
+ *       </Router>
+ *     </ServiceProvider>
+ *   )
+ * }
+ *
+ * // 嵌套服务提供者
+ * function UserPage() {
+ *   return (
+ *     <ServiceProvider services={[LocalUserService]}>
+ *       <UserList />
+ *     </ServiceProvider>
+ *   )
+ * }
+ * ```
+ */
+/** 自动复用 Container，除非没有，否则不会重新创建 Container */
+export declare function ServiceProvider(props: ServiceProviderProps): React.FunctionComponentElement<React.ProviderProps<Container | undefined>>;
+export {};
+//# sourceMappingURL=service.d.ts.map

package/output/service/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../source/service/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC5D,OAAO,KAA2D,MAAM,OAAO,CAAA;AAQ/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAuB3E;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,sBAAsB;IACtB,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAA;IAC7B,UAAU;IACV,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,6CAA6C;AAE7C,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,8EAuB1D"}