@taicode/common-web 1.1.10 → 1.1.13

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

@@ -0,0 +1,137 @@
+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, runInAction } from 'mobx';
+function isPromiseLike(value) {
+    return value != null && typeof value.then === 'function';
+}
+let SideCache = (() => {
+    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 = [];
+    let _cache_decorators;
+    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() {
+                if (this.currentKey == null)
+                    return undefined;
+                const cacheItem = this.cache[this.currentKey];
+                return cacheItem ? cacheItem.data : undefined;
+            }
+            get empty() {
+                return this.emptyFlag;
+            }
+            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 = 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()
+                        } });
+                });
+                return funcReturn;
+            }
+            constructor() {
+                _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 });
+        })(),
+        _a;
+})();
+export { SideCache };

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

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

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

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

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

@@ -0,0 +1,179 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SideCache } from './side-cache';
+describe('SideCache', () => {
+    let cache;
+    beforeEach(() => {
+        cache = new SideCache();
+    });
+    describe('初始状态', () => {
+        it('应该初始化为空状态', () => {
+            expect(cache.empty).toBe(true);
+            expect(cache.value).toBe(undefined);
+        });
+    });
+    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');
+        });
+    });
+    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);
+        });
+    });
+    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');
+        });
+    });
+    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);
+        });
+    });
+    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);
+        });
+    });
+    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/output/helpers/use-observer/index.d.ts

@@ -0,0 +1,2 @@
+export { useObserver } from './use-observer';
+//# sourceMappingURL=index.d.ts.map

package/output/helpers/use-observer/index.d.ts.map

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

package/output/helpers/use-observer/index.js

@@ -0,0 +1 @@
+export { useObserver } from './use-observer';

package/output/helpers/use-observer/use-observer.d.ts

@@ -0,0 +1,3 @@
+export declare function useObserver<T>(initialValue: T): T;
+export declare function useObserver<T, U>(initialValue: T, selector: (v: T) => U): U;
+//# sourceMappingURL=use-observer.d.ts.map

package/output/helpers/use-observer/use-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-observer.d.ts","sourceRoot":"","sources":["../../../source/helpers/use-observer/use-observer.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAA;AAClD,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA"}

package/output/helpers/use-observer/use-observer.js

@@ -0,0 +1,16 @@
+import { reaction } from 'mobx';
+import React, { useState } from 'react';
+export function useObserver(initialValue, selector) {
+    const [, refresh] = useState({});
+    React.useEffect(() => {
+        if (initialValue == null)
+            return;
+        if (selector == null)
+            return;
+        return reaction(() => selector(initialValue), () => refresh({}));
+    }, [selector, initialValue]);
+    if (selector == null) {
+        return initialValue;
+    }
+    return selector(initialValue);
+}

package/output/helpers/use-observer/use-observer.test.d.ts

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

package/output/helpers/use-observer/use-observer.test.d.ts.map

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

package/output/helpers/use-observer/use-observer.test.jsx

@@ -0,0 +1,134 @@
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { observable, action } from 'mobx';
+import { useObserver } from './use-observer';
+describe('useObserver', () => {
+    it('应该返回初始值当没有selector时', () => {
+        const initialValue = '初始值';
+        const { result } = renderHook(() => useObserver(initialValue));
+        expect(result.current).toBe(initialValue);
+    });
+    it('应该使用selector转换值', () => {
+        const initialValue = { count: 5 };
+        const selector = (value) => value.count * 2;
+        const { result } = renderHook(() => useObserver(initialValue, selector));
+        expect(result.current).toBe(10);
+    });
+    it('应该在观察对象变化时重新渲染', async () => {
+        const observableStore = observable({
+            count: 0,
+            increment: action(() => {
+                observableStore.count++;
+            })
+        });
+        const { result } = renderHook(() => useObserver(observableStore, (store) => store.count));
+        expect(result.current).toBe(0);
+        // 改变observable的值
+        act(() => {
+            observableStore.increment();
+        });
+        // 等待React更新
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(result.current).toBe(1);
+    });
+    it('应该处理复杂的selector函数', () => {
+        const store = observable({
+            users: [
+                { id: 1, name: '张三', active: true },
+                { id: 2, name: '李四', active: false },
+                { id: 3, name: '王五', active: true }
+            ]
+        });
+        const selector = (store) => store.users.filter((user) => user.active).map((user) => user.name);
+        const { result } = renderHook(() => useObserver(store, selector));
+        expect(result.current).toEqual(['张三', '王五']);
+    });
+    it('应该在observable数组变化时重新渲染', async () => {
+        const store = observable({
+            items: ['项目1', '项目2'],
+            addItem: action((item) => {
+                store.items.push(item);
+            })
+        });
+        const { result } = renderHook(() => useObserver(store, (store) => store.items.length));
+        expect(result.current).toBe(2);
+        act(() => {
+            store.addItem('项目3');
+        });
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(result.current).toBe(3);
+    });
+    it('应该处理null值的初始值', () => {
+        const { result } = renderHook(() => useObserver(null));
+        expect(result.current).toBeNull();
+    });
+    it('应该处理undefined值的初始值', () => {
+        const { result } = renderHook(() => useObserver(undefined));
+        expect(result.current).toBeUndefined();
+    });
+    it('应该在selector为null时返回原值', () => {
+        const initialValue = { data: '测试数据' };
+        const { result } = renderHook(() => useObserver(initialValue, null));
+        expect(result.current).toBe(initialValue);
+    });
+    it('应该处理嵌套observable对象', async () => {
+        const store = observable({
+            user: {
+                profile: {
+                    name: '测试用户',
+                    email: 'test@example.com'
+                }
+            },
+            updateName: action((name) => {
+                store.user.profile.name = name;
+            })
+        });
+        const { result } = renderHook(() => useObserver(store, (store) => store.user.profile.name));
+        expect(result.current).toBe('测试用户');
+        act(() => {
+            store.updateName('新用户名');
+        });
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(result.current).toBe('新用户名');
+    });
+    it('应该处理多个observable属性的变化', async () => {
+        const store = observable({
+            firstName: '张',
+            lastName: '三',
+            updateFirstName: action((name) => {
+                store.firstName = name;
+            }),
+            updateLastName: action((name) => {
+                store.lastName = name;
+            })
+        });
+        const { result } = renderHook(() => useObserver(store, (store) => `${store.firstName}${store.lastName}`));
+        expect(result.current).toBe('张三');
+        act(() => {
+            store.updateFirstName('李');
+        });
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(result.current).toBe('李三');
+        act(() => {
+            store.updateLastName('四');
+        });
+        await new Promise(resolve => setTimeout(resolve, 0));
+        expect(result.current).toBe('李四');
+    });
+    it('应该在组件卸载时清理reaction', () => {
+        const store = observable({ count: 0 });
+        const { unmount } = renderHook(() => useObserver(store, (store) => store.count));
+        // 卸载组件应该不会抛出错误
+        expect(() => unmount()).not.toThrow();
+    });
+    it('应该处理boolean类型的返回值', () => {
+        const store = observable({ isActive: true });
+        const { result } = renderHook(() => useObserver(store, (store) => store.isActive));
+        expect(result.current).toBe(true);
+    });
+    it('应该处理数字类型的返回值', () => {
+        const store = observable({ count: 42 });
+        const { result } = renderHook(() => useObserver(store, (store) => store.count));
+        expect(result.current).toBe(42);
+    });
+});

package/output/service/service.d.ts

@@ -35,13 +35,18 @@
 import { Token, Container, Provider } from '@needle-di/core';
 import React from 'react';
 /**
- * 使用全局注册的服务 Hook
+ * 使用服务 Hook
  *
  * 该 Hook 从 DI 容器中获取指定的服务实例，支持可选的 selector 函数来选择需要的数据。
  * 当选择的数据发生变化时，组件会自动重新渲染。
  *
+ * 该 Hook 可以获取三种类型的服务：
+ * 1. 全局服务：通过 ServiceProvider 类注入的服务
+ * 2. 值注入服务：通过 ServiceProvider 值注入（{ provide, useValue }）的服务实例
+ * 3. 父级容器中的任何服务：支持多层嵌套的 ServiceProvider
+ *
  * 特性：
- * - 从全局容器获取服务实例
+ * - 从容器获取服务实例
  * - 支持 Mobx 响应式更新
  * - 支持可选 selector，不传时监听整个服务的所有变化
  * - 智能检测 selector 返回值，优化响应式监听策略
@@ -56,19 +61,49 @@ import React from 'react';
  *
  * @example
  * ```tsx
- * // 使用选择器，只监听特定属性
+ * // 场景 1: 使用全局服务（类注入）
+ * // App.tsx
+ * <ServiceProvider services={[UserService]}>
+ *   <UserList />
+ * </ServiceProvider>
+ *
+ * // UserList.tsx
  * const users = useService(UserService, service => service.users)
+ * const userService = useService(UserService) // 监听整个服务的所有变化
  *
- * // 不使用选择器，监听整个服务的所有变化
- * const userService = useService(UserService)
+ * // 场景 2: 使用值注入的共享服务实例
+ * // UserPage.tsx
+ * function UserPage() {
+ *   const localService = useMemo(() => {
+ *     const service = new LocalUserService()
+ *     service.init()
+ *     return service
+ *   }, [])
  *
- * // 选择器返回服务实例本身（智能检测，自动优化响应式监听）
- * const service = useService(UserService, s => s)
+ *   return (
+ *     <ServiceProvider services={[
+ *       { provide: LocalUserService, useValue: localService }
+ *     ]}>
+ *       <UserList />
+ *       <UserDetail />
+ *     </ServiceProvider>
+ *   )
+ * }
  *
- * // 获取当前用户信息
- * const currentUser = useService(UserService, service => service.currentUser)
+ * // UserList.tsx 和 UserDetail.tsx 共享同一个 localService 实例
+ * function UserList() {
+ *   const users = useService(LocalUserService, s => s.users)
+ *   return <div>{users.length} users</div>
+ * }
+ *
+ * function UserDetail() {
+ *   const service = useService(LocalUserService)
+ *   return <div>{service.currentUser?.name}</div>
+ * }
  *
- * // 获取用户数量
+ * // 场景 3: 其他 selector 使用方式
+ * const service = useService(UserService, s => s) // 智能检测，自动优化响应式监听
+ * const currentUser = useService(UserService, service => service.currentUser)
  * const userCount = useService(UserService, service => service.users.length)
  * ```
  */
@@ -153,7 +188,12 @@ export declare function useLocalService<T, U>(ServiceClass: new (...args: any[])
  * ServiceProvider 组件的属性接口
  */
 interface ServiceProviderProps {
-    /** 要注册到容器中的服务提供者数组 */
+    /**
+     * 要注册到容器中的服务提供者数组
+     * 支持两种注入方式：
+     * 1. 类注入：直接传入服务类，ServiceProvider 会自动实例化并初始化
+     * 2. 值注入：传入 { provide: Token, useValue: instance }，直接注入已有实例
+     */
     services: Provider<unknown>[];
     /** 子组件 */
     children: React.ReactNode;
@@ -167,12 +207,14 @@ interface ServiceProviderProps {
  * 特性：
  * - 自动复用父级容器，避免重复创建
  * - 支持容器层级结构，子容器可以覆盖父容器的服务
- * - 自动初始化实现了 Service 接口的服务
+ * - 支持两种注入方式：类注入和值注入
+ * - 自动初始化实现了 Service 接口的服务（仅限类注入）
  *
  * @param props 组件属性
  *
  * @example
  * ```tsx
+ * // 方式 1: 类注入 - 自动实例化和初始化
  * function App() {
  *   return (
  *     <ServiceProvider services={[UserService, ProductService]}>
@@ -186,11 +228,53 @@ interface ServiceProviderProps {
  *   )
  * }
  *
- * // 嵌套服务提供者
+ * // 方式 2: 值注入 - 在多个组件间共享局部服务实例
  * function UserPage() {
+ *   // 创建局部服务实例
+ *   const localUserService = useMemo(() => {
+ *     const service = new LocalUserService()
+ *     service.init() // 手动初始化
+ *     return service
+ *   }, [])
+ *
  *   return (
- *     <ServiceProvider services={[LocalUserService]}>
+ *     <ServiceProvider
+ *       services={[
+ *         { provide: LocalUserService, useValue: localUserService }
+ *       ]}
+ *     >
  *       <UserList />
+ *       <UserDetail />
+ *     </ServiceProvider>
+ *   )
+ * }
+ *
+ * // UserList 和 UserDetail 共享同一个 localUserService 实例
+ * function UserList() {
+ *   const users = useService(LocalUserService, s => s.users)
+ *   return <div>{users.length} users</div>
+ * }
+ *
+ * function UserDetail() {
+ *   const service = useService(LocalUserService)
+ *   return <div>{service.currentUser?.name}</div>
+ * }
+ *
+ * // 方式 3: 混合使用类注入和值注入
+ * function App() {
+ *   const configService = useMemo(() => {
+ *     const config = new ConfigService()
+ *     config.loadConfig() // 预配置
+ *     return config
+ *   }, [])
+ *
+ *   return (
+ *     <ServiceProvider services={[
+ *       UserService,  // 类注入 - 自动实例化和初始化
+ *       ApiService,   // 类注入
+ *       { provide: ConfigService, useValue: configService }  // 值注入 - 使用预配置的实例
+ *     ]}>
+ *       <Router />
  *     </ServiceProvider>
  *   )
  * }