@taicode/common-web 1.1.0 → 1.1.2

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/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"}

package/output/service/service.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { reaction, runInAction } from 'mobx';
+import { catchIt } from '@taicode/common-base';
+import { Container } from '@needle-di/core';
+import React, { useContext, useEffect, useMemo, useState } from 'react';
+/**
+ * React Context 用于传递 DI 容器实例
+ * 通过上下文在组件树中共享依赖注入容器
+ */
+const ctx = React.createContext(undefined);
+/**
+ * 使用全局注册的服务 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)
+ * ```
+ */
+// DI + Mobx 自动
+export function useService(target, selector) {
+    const container = useContext(ctx);
+    // 使用 useState 强制组件重新渲染
+    const [, refresh] = useState({});
+    React.useEffect(() => {
+        if (container == null)
+            return;
+        // 从容器中获取服务实例
+        const service = container.get(target);
+        // 设置 Mobx reaction，当 selector 返回的数据变化时触发重新渲染
+        return reaction(() => selector(service), () => refresh({}) // 触发组件重新渲染
+        );
+    }, [container, selector, target]);
+    if (container == null) {
+        throw new Error('Must be a child of ServiceProvider.');
+    }
+    return selector(container.get(target));
+}
+/**
+ * 服务提供者组件
+ *
+ * 该组件为其子组件树提供依赖注入容器上下文。
+ * 它会自动复用父级容器（如果存在），并创建子容器来管理新的服务实例。
+ *
+ * 特性：
+ * - 自动复用父级容器，避免重复创建
+ * - 支持容器层级结构，子容器可以覆盖父容器的服务
+ * - 自动初始化实现了 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 */
+// di 实现也有限制 https://needle-di.io/advanced/child-containers.html
+export function ServiceProvider(props) {
+    const parentContainer = useContext(ctx);
+    const { children, services } = props;
+    // 创建子容器，复用父容器的服务配置
+    const container = useMemo(() => {
+        const currentContainer = new Container(parentContainer);
+        const typed = services;
+        currentContainer.bindAll(...typed); // 批量绑定服务到容器
+        // bindAll 要求参数必须是元组类型
+        return currentContainer;
+    }, [parentContainer, services]);
+    // 使用 React.createElement 避免将文件改为 .tsx
+    const init = React.createElement(InitService, { services, children });
+    return React.createElement(ctx.Provider, { value: container, children: container ? init : null });
+}
+/**
+ * 服务初始化组件
+ *
+ * 该组件负责自动初始化实现了 Service 接口的服务实例。
+ * 它会在组件挂载时检查每个服务是否需要初始化，并调用其 init 方法。
+ *
+ * 初始化流程：
+ * 1. 从容器中获取服务实例
+ * 2. 检查服务是否实现了 Service 接口（有 init 方法）
+ * 3. 检查服务是否已经初始化（inited 属性）
+ * 4. 如果未初始化，则调用 init 方法并更新状态
+ *
+ * @param props 组件属性，与 ServiceProviderProps 相同
+ */
+function InitService(props) {
+    const { services, children } = props;
+    const container = useContext(ctx);
+    useEffect(() => {
+        if (container == null)
+            return;
+        if (services.length == 0)
+            return;
+        // 异步初始化所有服务
+        (async () => {
+            const initPromises = services.map(async (service) => {
+                // 尝试从容器中获取服务实例（可选的，避免未注册时报错）
+                const instance = container.get(service, { optional: true });
+                if (instance != null && typeof instance === 'object') {
+                    // 检查实例是否实现了 Service 接口
+                    if ('init' in instance && typeof instance.init === 'function') {
+                        // 检查是否已经初始化
+                        if (instance.inited == false) {
+                            // 安全地调用 init 方法，捕获可能的异常
+                            const result = await catchIt(() => instance.init());
+                            // 使用 runInAction 确保状态更新被 Mobx 正确跟踪
+                            runInAction(() => instance.inited = !result.isError());
+                        }
+                    }
+                }
+            });
+            // 等待所有服务初始化完成
+            await Promise.all(initPromises);
+        })();
+    }, [container, services]);
+    return children;
+}

package/output/service/service.test.d.ts

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

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

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