tcdona_unilib 1.0.1 → 1.0.3

package/staticMeta/eff.test.ts

@@ -0,0 +1,858 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { Eff, EffContext } from './eff';
+import { err, ok, Result, ResultAsync } from 'neverthrow';
+
+describe('eff', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    // ============================================================
+    // Eff.root
+    // ============================================================
+    describe('eff.root', () => {
+        test('基础用法：返回成功结果', async () => {
+            const result = await Eff.root<string, Error>(async () => {
+                return ok('hello');
+            });
+
+            expect(result.isOk()).toBe(true);
+            expect(result._unsafeUnwrap()).toBe('hello');
+        });
+
+        test('基础用法：返回错误结果', async () => {
+            const result = await Eff.root<string, Error>(async () => {
+                return err(new Error('something went wrong'));
+            });
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr().message).toBe('something went wrong');
+        });
+
+        test('异常捕获：executor 抛出异常会被转为 err', async () => {
+            const result = await Eff.root<string, Error>(async () => {
+                throw new Error('unexpected error');
+            });
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr().message).toBe('unexpected error');
+        });
+
+        test('async executor', async () => {
+            const result = await Eff.root<number, string>(async () => {
+                return ok(42);
+            });
+
+            expect(result._unsafeUnwrap()).toBe(42);
+        });
+
+        test('提供 signal 用于取消检查', async () => {
+            let receivedSignal: AbortSignal | null = null;
+
+            await Eff.root<void, never>(async ({ signal }) => {
+                receivedSignal = signal;
+                return ok(undefined);
+            });
+
+            expect(receivedSignal).toBeInstanceOf(AbortSignal);
+        });
+    });
+
+    // ============================================================
+    // Eff.create
+    // ============================================================
+    describe('eff.create', () => {
+        test('基础用法：在父任务中创建子任务', async () => {
+            const result = await Eff.root<number, Error>(async ({ signal }) => {
+                // 创建子任务
+                const childResult = await Eff.create<number, Error>(
+                    async () => ok(100),
+                    signal,
+                );
+                return childResult;
+            });
+
+            expect(result._unsafeUnwrap()).toBe(100);
+        });
+
+        test('父 signal abort 时子任务能感知', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            let childSignalAborted = false;
+            let listenerSetup = false;
+
+            // 启动子任务
+            const childPromise = Eff.create<string, Error>(async ({ signal }) => {
+                // 监听 abort
+                signal.addEventListener('abort', () => {
+                    childSignalAborted = true;
+                });
+                listenerSetup = true;
+
+                // 等待一段时间让外部有机会 abort
+                await delay(100);
+
+                return signal.aborted ? ok('aborted') : ok('done');
+            }, controller.signal);
+
+            // 等待监听器设置完成
+            await vi.waitFor(() => {
+                if (!listenerSetup) throw new Error('waiting');
+            });
+
+            // abort 父 signal
+            controller.abort();
+
+            // 等待子任务
+            await childPromise;
+
+            expect(childSignalAborted).toBe(true);
+            vi.useFakeTimers();
+        });
+
+        test('响应式取消示例：fetch 请求', async () => {
+            vi.useRealTimers();
+
+            const mockFetch = vi.fn().mockImplementation(async (_url, options) => {
+                // 检查是否被 abort
+                if (options?.signal?.aborted) {
+                    throw new DOMException('Aborted', 'AbortError');
+                }
+                return { ok: true, json: () => Promise.resolve({ data: 'test' }) };
+            });
+            globalThis.fetch = mockFetch;
+
+            const controller = new AbortController();
+
+            const result = await Eff.create<{ data: string }, Error>(
+                async ({ signal }) => {
+                    try {
+                        const response = await fetch('/api/data', { signal });
+                        const data = await response.json();
+                        return ok(data);
+                    } catch (e) {
+                        return err(e as Error);
+                    }
+                },
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toEqual({ data: 'test' });
+            expect(mockFetch).toHaveBeenCalledWith('/api/data', {
+                signal: expect.any(AbortSignal),
+            });
+
+            vi.useFakeTimers();
+        });
+    });
+
+    // ============================================================
+    // Eff.all
+    // ============================================================
+    describe('eff.all', () => {
+        test('全部成功：返回所有结果数组', async () => {
+            const controller = new AbortController();
+
+            const result = await Eff.all<number, Error>(
+                [async () => ok(1), async () => ok(2), async () => ok(3)],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toEqual([1, 2, 3]);
+        });
+
+        test('结果顺序与 executor 顺序一致（即使完成顺序不同）', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.all<string, Error>(
+                [
+                    async () => {
+                        await delay(30);
+                        return ok('slow');
+                    },
+                    async () => {
+                        await delay(10);
+                        return ok('fast');
+                    },
+                    async () => {
+                        await delay(20);
+                        return ok('medium');
+                    },
+                ],
+                controller.signal,
+            );
+
+            // 顺序应该是 executor 顺序，不是完成顺序
+            expect(result._unsafeUnwrap()).toEqual(['slow', 'fast', 'medium']);
+
+            vi.useFakeTimers();
+        });
+
+        test('任一失败：立即返回错误并 abort 其他', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            const abortedTasks: number[] = [];
+
+            const result = await Eff.all<number, string>(
+                [
+                    async ({ signal }) => {
+                        signal.addEventListener('abort', () => abortedTasks.push(1));
+                        await delay(100);
+                        return ok(1);
+                    },
+                    async () => {
+                        await delay(10);
+                        return err('task 2 failed');
+                    },
+                    async ({ signal }) => {
+                        signal.addEventListener('abort', () => abortedTasks.push(3));
+                        await delay(100);
+                        return ok(3);
+                    },
+                ],
+                controller.signal,
+            );
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr()).toBe('task 2 failed');
+            // 其他任务应该收到 abort 信号
+            expect(abortedTasks).toContain(1);
+            expect(abortedTasks).toContain(3);
+
+            vi.useFakeTimers();
+        });
+
+        test('实际应用：并行获取多个资源', async () => {
+            const controller = new AbortController();
+
+            // 模拟并行获取用户信息和订单信息
+            const result = await Eff.all<
+                { type: string; data: string },
+                { code: number; message: string }
+            >(
+                [
+                    async () => ok({ type: 'user', data: 'John' }),
+                    async () => ok({ type: 'orders', data: '3 items' }),
+                    async () => ok({ type: 'notifications', data: '5 unread' }),
+                ],
+                controller.signal,
+            );
+
+            const [user, orders, notifications] = result._unsafeUnwrap();
+            expect(user.data).toBe('John');
+            expect(orders.data).toBe('3 items');
+            expect(notifications.data).toBe('5 unread');
+        });
+    });
+
+    // ============================================================
+    // Eff.any
+    // ============================================================
+    describe('eff.any', () => {
+        test('任一成功：返回第一个成功的结果', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.any<string, Error>(
+                [
+                    async () => {
+                        await delay(50);
+                        return ok('slow winner');
+                    },
+                    async () => {
+                        await delay(10);
+                        return ok('fast winner');
+                    },
+                    async () => err(new Error('loser')),
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe('fast winner');
+
+            vi.useFakeTimers();
+        });
+
+        test('成功后 abort 其他任务', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            let slowTaskAborted = false;
+
+            const result = await Eff.any<string, Error>(
+                [
+                    async ({ signal }) => {
+                        signal.addEventListener('abort', () => {
+                            slowTaskAborted = true;
+                        });
+                        await delay(100);
+                        return ok('slow');
+                    },
+                    async () => ok('fast'),
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe('fast');
+            expect(slowTaskAborted).toBe(true);
+
+            vi.useFakeTimers();
+        });
+
+        test('全部失败：返回所有错误数组', async () => {
+            const controller = new AbortController();
+
+            const result = await Eff.any<string, string>(
+                [async () => err('error 1'), async () => err('error 2'), async () => err('error 3')],
+                controller.signal,
+            );
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr()).toEqual(['error 1', 'error 2', 'error 3']);
+        });
+
+        test('实际应用：多源数据获取（任一成功即可）', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            // 模拟从多个 CDN 获取资源，任一成功即可
+            const result = await Eff.any<string, string>(
+                [
+                    async () => {
+                        await delay(100);
+                        return ok('cdn1-data');
+                    },
+                    async () => {
+                        await delay(10); // 最快
+                        return ok('cdn2-data');
+                    },
+                    async () => err('cdn3-unavailable'),
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe('cdn2-data');
+
+            vi.useFakeTimers();
+        });
+    });
+
+    // ============================================================
+    // Eff.race
+    // ============================================================
+    describe('eff.race', () => {
+        test('第一个完成的是成功', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.race<number, Error>(
+                [
+                    async () => {
+                        await delay(10);
+                        return ok(1);
+                    },
+                    async () => {
+                        await delay(50);
+                        return ok(2);
+                    },
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe(1);
+
+            vi.useFakeTimers();
+        });
+
+        test('第一个完成的是失败', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.race<number, string>(
+                [
+                    async () => {
+                        await delay(10);
+                        return err('fast error');
+                    },
+                    async () => {
+                        await delay(50);
+                        return ok(2);
+                    },
+                ],
+                controller.signal,
+            );
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr()).toBe('fast error');
+
+            vi.useFakeTimers();
+        });
+
+        test('实际应用：超时控制', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.race<string, string>(
+                [
+                    // 实际任务
+                    async () => {
+                        await delay(100);
+                        return ok('task completed');
+                    },
+                    // 超时控制
+                    async () => {
+                        await delay(50);
+                        return err('timeout');
+                    },
+                ],
+                controller.signal,
+            );
+
+            expect(result.isErr()).toBe(true);
+            expect(result._unsafeUnwrapErr()).toBe('timeout');
+
+            vi.useFakeTimers();
+        });
+    });
+
+    // ============================================================
+    // Eff.allSettled
+    // ============================================================
+    describe('eff.allSettled', () => {
+        test('收集所有结果（无论成功失败）', async () => {
+            const controller = new AbortController();
+
+            const result = await Eff.allSettled<number, string>(
+                [async () => ok(1), async () => err('failed'), async () => ok(3)],
+                controller.signal,
+            );
+
+            const results = result._unsafeUnwrap();
+            expect(results).toHaveLength(3);
+            expect(results[0]._unsafeUnwrap()).toBe(1);
+            expect(results[1].isErr()).toBe(true);
+            expect(results[1]._unsafeUnwrapErr()).toBe('failed');
+            expect(results[2]._unsafeUnwrap()).toBe(3);
+        });
+
+        test('不会因为某个失败而 abort 其他', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            const taskExecuted = [false, false, false];
+
+            const result = await Eff.allSettled<number, string>(
+                [
+                    async () => {
+                        await delay(10);
+                        taskExecuted[0] = true;
+                        return ok(1);
+                    },
+                    async () => {
+                        taskExecuted[1] = true;
+                        return err('failed early');
+                    },
+                    async () => {
+                        await delay(20);
+                        taskExecuted[2] = true;
+                        return ok(3);
+                    },
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toHaveLength(3);
+            expect(taskExecuted).toEqual([true, true, true]);
+
+            vi.useFakeTimers();
+        });
+
+        test('实际应用：批量操作并报告结果', async () => {
+            const controller = new AbortController();
+
+            // 模拟批量发送邮件
+            const result = await Eff.allSettled<string, string>(
+                [
+                    async () => ok('email1@test.com: sent'),
+                    async () => err('email2@test.com: invalid address'),
+                    async () => ok('email3@test.com: sent'),
+                ],
+                controller.signal,
+            );
+
+            const results = result._unsafeUnwrap();
+            const successes = results.filter((r) => r.isOk()).length;
+            const failures = results.filter((r) => r.isErr()).length;
+
+            expect(successes).toBe(2);
+            expect(failures).toBe(1);
+        });
+    });
+
+    // ============================================================
+    // Signal 传播
+    // ============================================================
+    describe('signal 传播', () => {
+        test('父 abort 自动传播到子', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            let childAborted = false;
+            let listenerSetup = false;
+
+            const taskPromise = Eff.create<string, Error>(async ({ signal }) => {
+                signal.addEventListener('abort', () => {
+                    childAborted = true;
+                });
+                listenerSetup = true;
+
+                await delay(100);
+                return signal.aborted ? ok('aborted') : ok('done');
+            }, controller.signal);
+
+            // 等待监听器设置完成
+            await vi.waitFor(() => {
+                if (!listenerSetup) throw new Error('waiting');
+            });
+
+            // abort 父
+            controller.abort();
+
+            await taskPromise;
+
+            expect(childAborted).toBe(true);
+            vi.useFakeTimers();
+        });
+
+        test('提前 abort 时返回 ok([])', async () => {
+            const controller = new AbortController();
+            controller.abort(); // 提前 abort
+
+            const result = await Eff.all<number, Error>(
+                [async () => ok(1), async () => ok(2)],
+                controller.signal,
+            );
+
+            // 取消是流程控制，不是失败
+            expect(result.isOk()).toBe(true);
+            expect(result._unsafeUnwrap()).toEqual([]);
+        });
+
+        test('executor 应主动检查 signal.aborted 并提前返回', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            let iterationCount = 0;
+
+            const taskPromise = Eff.create<number, Error>(async ({ signal }) => {
+                // 模拟长时间循环任务
+                for (let i = 0; i < 100; i++) {
+                    // 关键：检查 abort 状态
+                    if (signal.aborted) {
+                        return ok(iterationCount); // 提前返回当前进度
+                    }
+                    iterationCount++;
+                    await delay(10);
+                }
+                return ok(iterationCount);
+            }, controller.signal);
+
+            // 让任务运行一段时间
+            await delay(50);
+            controller.abort();
+
+            const result = await taskPromise;
+            // 应该在某个中间点停止
+            expect(result._unsafeUnwrap()).toBeLessThan(100);
+            expect(result._unsafeUnwrap()).toBeGreaterThan(0);
+
+            vi.useFakeTimers();
+        });
+    });
+
+    // ============================================================
+    // 嵌套任务
+    // ============================================================
+    describe('嵌套任务', () => {
+        test('多层嵌套：祖父 → 父 → 子', async () => {
+            const result = await Eff.root<string, Error>(async ({ signal }) => {
+                const parentResult = await Eff.create<string, Error>(
+                    async ({ signal: parentSignal }) => {
+                        const childResult = await Eff.create<string, Error>(
+                            async () => ok('deep value'),
+                            parentSignal,
+                        );
+                        return childResult.map((v) => `parent(${v})`);
+                    },
+                    signal,
+                );
+                return parentResult.map((v) => `root(${v})`);
+            });
+
+            expect(result._unsafeUnwrap()).toBe('root(parent(deep value))');
+        });
+
+        test('嵌套的 all 调用', async () => {
+            const controller = new AbortController();
+
+            const result = await Eff.all<number[], Error>(
+                [
+                    ({ signal }) =>
+                        Eff.all<number, Error>(
+                            [async () => ok(1), async () => ok(2)],
+                            signal,
+                        ),
+                    ({ signal }) =>
+                        Eff.all<number, Error>(
+                            [async () => ok(3), async () => ok(4)],
+                            signal,
+                        ),
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toEqual([
+                [1, 2],
+                [3, 4],
+            ]);
+        });
+    });
+
+    // ============================================================
+    // 错误处理
+    // ============================================================
+    describe('错误处理模式', () => {
+        test('使用 Result 的 map/mapErr 链式处理', async () => {
+            const result = await Eff.root<number, { code: string; message: string }>(
+                async () => {
+                    return err({ code: 'NOT_FOUND', message: 'Resource not found' });
+                },
+            );
+
+            const handled = result
+                .map((v) => v * 2) // 不会执行
+                .mapErr((e) => `Error ${e.code}: ${e.message}`);
+
+            expect(handled._unsafeUnwrapErr()).toBe('Error NOT_FOUND: Resource not found');
+        });
+
+        test('使用 match 进行分支处理', async () => {
+            const result = await Eff.root<number, string>(async () => {
+                return ok(42);
+            });
+
+            const message = result.match(
+                (value) => `Success: ${value}`,
+                (error) => `Failed: ${error}`,
+            );
+
+            expect(message).toBe('Success: 42');
+        });
+
+        test('使用 andThen 进行链式异步操作', async () => {
+            const result = await Eff.root<number, string>(async () => {
+                return ok(10);
+            });
+
+            const finalResult = await result.asyncAndThen((value) => {
+                // 可以在这里做进一步的异步处理
+                return new ResultAsync(Promise.resolve(ok(value * 2)));
+            });
+
+            expect(finalResult._unsafeUnwrap()).toBe(20);
+        });
+    });
+
+    // ============================================================
+    // 实际应用场景
+    // ============================================================
+    describe('实际应用', () => {
+        test('场景：带重试的 API 调用', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            let attempts = 0;
+
+            const fetchWithRetry = async (
+                maxRetries: number,
+                signal: AbortSignal,
+            ): Promise<Result<string, string>> => {
+                for (let i = 0; i < maxRetries; i++) {
+                    if (signal.aborted) {
+                        return err('cancelled');
+                    }
+
+                    attempts++;
+                    // 模拟前两次失败，第三次成功
+                    if (attempts >= 3) {
+                        return ok(`success on attempt ${attempts}`);
+                    }
+
+                    await delay(10); // 重试间隔
+                }
+                return err('max retries exceeded');
+            };
+
+            const result = await Eff.create<string, string>(
+                ({ signal }) => fetchWithRetry(5, signal),
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe('success on attempt 3');
+
+            vi.useFakeTimers();
+        });
+
+        test('场景：并行请求 + 超时控制', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            // 使用 race 实现超时
+            const withTimeout = <T, E>(
+                executor: (ctx: EffContext) => Promise<Result<T, E>>,
+                timeoutMs: number,
+                signal: AbortSignal,
+            ) =>
+                Eff.race<T, E | 'timeout'>(
+                    [
+                        executor,
+                        async () => {
+                            await delay(timeoutMs);
+                            return err('timeout' as const);
+                        },
+                    ],
+                    signal,
+                );
+
+            const result = await withTimeout(
+                async () => {
+                    await delay(10);
+                    return ok('fast response');
+                },
+                100,
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toBe('fast response');
+
+            vi.useFakeTimers();
+        });
+
+        test('场景：并发限制（简化版）', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            const runningTasks = new Set<number>();
+            let maxConcurrent = 0;
+
+            const tasks = Array.from({ length: 6 }, (_, i) => async () => {
+                runningTasks.add(i);
+                maxConcurrent = Math.max(maxConcurrent, runningTasks.size);
+                await delay(20);
+                runningTasks.delete(i);
+                return ok(i);
+            });
+
+            // 分批执行，每批 2 个
+            const batchSize = 2;
+            const results: number[] = [];
+
+            for (let i = 0; i < tasks.length; i += batchSize) {
+                const batch = tasks.slice(i, i + batchSize) as [
+                    typeof tasks[0],
+                    ...typeof tasks,
+                ];
+                const batchResult = await Eff.all<number, never>(
+                    batch,
+                    controller.signal,
+                );
+                results.push(...batchResult._unsafeUnwrap());
+            }
+
+            expect(results).toEqual([0, 1, 2, 3, 4, 5]);
+            expect(maxConcurrent).toBeLessThanOrEqual(2);
+
+            vi.useFakeTimers();
+        });
+
+        test('场景：资源获取与清理', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+            const cleanupCalled: string[] = [];
+
+            const acquireResource = (name: string): Promise<Result<string, Error>> =>
+                Promise.resolve(ok(`resource:${name}`));
+
+            const releaseResource = (name: string): void => {
+                cleanupCalled.push(name);
+            };
+
+            const result = await Eff.create<string, Error>(async ({ signal }) => {
+                // 获取资源
+                const resource = await acquireResource('db-connection');
+                if (resource.isErr()) return resource;
+
+                // 注册清理（通过 signal abort 事件或 finally）
+                const cleanup = () => releaseResource('db-connection');
+                signal.addEventListener('abort', cleanup);
+
+                try {
+                    // 使用资源
+                    await delay(10);
+                    return ok(`done with ${resource._unsafeUnwrap()}`);
+                } finally {
+                    // 确保清理
+                    signal.removeEventListener('abort', cleanup);
+                    cleanup();
+                }
+            }, controller.signal);
+
+            expect(result._unsafeUnwrap()).toBe('done with resource:db-connection');
+            expect(cleanupCalled).toContain('db-connection');
+
+            vi.useFakeTimers();
+        });
+    });
+
+    // ============================================================
+    // 边界情况
+    // ============================================================
+    describe('边界情况', () => {
+        test('单个 executor 的 all', async () => {
+            const controller = new AbortController();
+
+            const result = await Eff.all<number, Error>(
+                [async () => ok(42)],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toEqual([42]);
+        });
+
+        test('混合快慢 executor', async () => {
+            vi.useRealTimers();
+            const controller = new AbortController();
+
+            const result = await Eff.all<number, Error>(
+                [
+                    async () => ok(1), // 快
+                    async () => {
+                        await delay(10);
+                        return ok(2);
+                    }, // 慢
+                    async () => ok(3), // 快
+                ],
+                controller.signal,
+            );
+
+            expect(result._unsafeUnwrap()).toEqual([1, 2, 3]);
+
+            vi.useFakeTimers();
+        });
+    });
+});
+
+// 辅助函数
+function delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}