@taicode/common-base 1.5.1 → 1.6.1

package/output/catch/catch.d.ts

@@ -1,9 +1,45 @@
 type CatchType<F extends () => unknown> = F extends () => PromiseLike<infer R> ? R : F extends () => infer R ? R : never;
+/**
+ * 成功结果类型
+ * 只包含 value 字段，error 字段为 undefined
+ */
+export interface CatchSuccess<T> {
+    value: T;
+}
+/**
+ * 失败结果类型
+ * error 字段类型永远为 unknown（或用户自定义），这样最安全，防止误用。
+ * 推荐在 error 分支内用 instanceof/typeof 等类型守卫自行收窄类型。
+ */
+export interface CatchFailure<E> {
+    error: E;
+}
+/**
+ * 捕获结果联合类型，使用判别联合类型以支持类型守卫
+ *
+ * 设计说明：
+ * - 通过 isError 方法进行类型守卫，推荐始终用 result.isError() 判断是否为错误分支。
+ * - isError 方法为 function 写法（而非箭头函数），以支持类型谓词，且 this 不会被转移。
+ * - 不建议直接用 error !== undefined 判断错误分支，该方式依赖 error 的值，推荐统一用 isError()。
+ */
+export type CatchResult<T, E = unknown> = (CatchSuccess<T> | CatchFailure<E>) & {
+    /**
+     * 类型守卫方法，判断当前对象是否为 CatchFailure。
+     * function 写法，返回类型谓词，保证类型收窄。
+     * 推荐用法：if (result.isError()) { ... }
+     */
+    isError: (this: unknown) => this is CatchFailure<E>;
+};
 /**
  * 通用错误捕获函数，支持 PromiseLike 和函数执行
- * 将结果转换成 [result, error] 的形式
+ * 返回 { value, error } 的对象格式，便于类型判断
+ *
+ * 设计说明：
+ * - 支持同步/异步/thenable 场景
+ * - 推荐通过 isError() 进行类型守卫
+ * - error 字段类型为 unknown，需用户自行收窄
  */
-export declare function catchIt<T>(input: PromiseLike<T>): Promise<[T | undefined, unknown]>;
-export declare function catchIt<F extends () => unknown>(input: F): Promise<[CatchType<F> | undefined, unknown]>;
+export declare function catchIt<T, E = unknown>(input: PromiseLike<T>): Promise<CatchResult<T, E>>;
+export declare function catchIt<F extends () => unknown, E = unknown>(input: F): Promise<CatchResult<CatchType<F>, E>>;
 export {};
 //# sourceMappingURL=catch.d.ts.map

package/output/catch/catch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catch.d.ts","sourceRoot":"","sources":["../../source/catch/catch.ts"],"names":[],"mappings":"AAKA,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,OAAO,IAAI,CAAC,SAAS,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAExH;;;GAGG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;AAC1F,wBAAsB,OAAO,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA"}
+{"version":3,"file":"catch.d.ts","sourceRoot":"","sources":["../../source/catch/catch.ts"],"names":[],"mappings":"AAMA,KAAK,SAAS,CAAC,CAAC,SAAS,MAAM,OAAO,IAAI,CAAC,SAAS,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAExH;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,CAAA;CACT;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,CAAA;CACT;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG;IAC9E;;;;OAIG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;CACpD,CAAA;AA0BD;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAChG,wBAAsB,OAAO,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA"}

package/output/catch/catch.js

@@ -2,29 +2,47 @@
 function isPromiseLike(value) {
     return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
 }
+/**
+ * 构造成功结果对象
+ * isError 始终返回 false
+ */
+function createSuccess(value) {
+    return {
+        value,
+        error: undefined,
+        isError() { return false; }
+    };
+}
+/**
+ * 构造失败结果对象
+ * isError 始终返回 true
+ */
+function createFailure(error) {
+    return {
+        error,
+        value: undefined,
+        isError() { return true; }
+    };
+}
 export async function catchIt(input) {
-    const returned = [undefined, undefined];
     try {
         if (isPromiseLike(input)) {
-            // 处理 PromiseLike
-            await Promise.resolve(input)
-                .then((result) => (returned[0] = result))
-                .catch((error) => (returned[1] = error));
+            const result = await Promise.resolve(input);
+            return createSuccess(result);
         }
         else if (typeof input === 'function') {
-            // 处理函数
             const result = input();
             if (isPromiseLike(result)) {
-                // 如果函数返回 PromiseLike，递归调用
                 return catchIt(result);
             }
             else {
-                returned[0] = result;
+                return createSuccess(result);
             }
         }
     }
     catch (error) {
-        returned[1] = error;
+        return createFailure(error);
     }
-    return returned;
+    // 理论上不会到达这里，兜底类型安全
+    return createFailure(new Error('Unexpected input type'));
 }

package/output/catch/catch.test.js

@@ -1,363 +1,43 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { catchIt } from './catch';
 describe('catchIt', () => {
-    describe('处理 Promise', () => {
-        it('应该正确处理成功的 Promise', async () => {
-            const successValue = 'success';
-            const promise = Promise.resolve(successValue);
-            const [result, error] = await catchIt(promise);
-            expect(result).toBe(successValue);
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理失败的 Promise', async () => {
-            const errorValue = new Error('test error');
-            const promise = Promise.reject(errorValue);
-            const [result, error] = await catchIt(promise);
-            expect(result).toBeUndefined();
-            expect(error).toBe(errorValue);
-        });
-        it('应该正确处理返回不同数据类型的 Promise', async () => {
-            // 数字类型
-            const [numberResult, numberError] = await catchIt(Promise.resolve(42));
-            expect(numberResult).toBe(42);
-            expect(numberError).toBeUndefined();
-            // 对象类型
-            const obj = { key: 'value' };
-            const [objectResult, objectError] = await catchIt(Promise.resolve(obj));
-            expect(objectResult).toBe(obj);
-            expect(objectError).toBeUndefined();
-            // 数组类型
-            const arr = [1, 2, 3];
-            const [arrayResult, arrayError] = await catchIt(Promise.resolve(arr));
-            expect(arrayResult).toBe(arr);
-            expect(arrayError).toBeUndefined();
-            // null 和 undefined
-            const [nullResult, nullError] = await catchIt(Promise.resolve(null));
-            expect(nullResult).toBeNull();
-            expect(nullError).toBeUndefined();
-            const [undefinedResult, undefinedError] = await catchIt(Promise.resolve(undefined));
-            expect(undefinedResult).toBeUndefined();
-            expect(undefinedError).toBeUndefined();
-        });
-        it('应该正确处理不同类型的错误', async () => {
-            // Error 对象
-            const error = new Error('test error');
-            const [, caughtError1] = await catchIt(Promise.reject(error));
-            expect(caughtError1).toBe(error);
-            // 字符串错误
-            const [, caughtError2] = await catchIt(Promise.reject('string error'));
-            expect(caughtError2).toBe('string error');
-            // 数字错误
-            const [, caughtError3] = await catchIt(Promise.reject(404));
-            expect(caughtError3).toBe(404);
-            // 对象错误
-            const objError = { code: 500, message: 'server error' };
-            const [, caughtError4] = await catchIt(Promise.reject(objError));
-            expect(caughtError4).toBe(objError);
-        });
+    it('同步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(() => 123);
+        expect(result.value).toBe(123);
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
     });
-    describe('处理同步函数', () => {
-        it('应该正确处理返回值的同步函数', async () => {
-            const syncFn = () => 'sync result';
-            const [result, error] = await catchIt(syncFn);
-            expect(result).toBe('sync result');
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理抛出错误的同步函数', async () => {
-            const errorValue = new Error('sync error');
-            const syncFn = () => {
-                throw errorValue;
-            };
-            const [result, error] = await catchIt(syncFn);
-            expect(result).toBeUndefined();
-            expect(error).toBe(errorValue);
-        });
-        it('应该正确处理返回不同数据类型的同步函数', async () => {
-            // 数字
-            const [numberResult] = await catchIt(() => 42);
-            expect(numberResult).toBe(42);
-            // 字符串
-            const [stringResult] = await catchIt(() => 'hello');
-            expect(stringResult).toBe('hello');
-            // 对象
-            const obj = { test: true };
-            const [objectResult] = await catchIt(() => obj);
-            expect(objectResult).toBe(obj);
-            // 数组
-            const arr = [1, 2, 3];
-            const [arrayResult] = await catchIt(() => arr);
-            expect(arrayResult).toBe(arr);
-            // boolean
-            const [boolResult] = await catchIt(() => true);
-            expect(boolResult).toBe(true);
-            // null
-            const [nullResult] = await catchIt(() => null);
-            expect(nullResult).toBeNull();
-            // undefined
-            const [undefinedResult] = await catchIt(() => undefined);
-            expect(undefinedResult).toBeUndefined();
-        });
-        it('应该确保同步函数被调用', async () => {
-            const mockFn = vi.fn(() => 'test');
-            await catchIt(mockFn);
-            expect(mockFn).toHaveBeenCalledOnce();
-        });
+    it('异步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(async () => 456);
+        expect(result.value).toBe(456);
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
     });
-    describe('处理返回 Promise 的函数', () => {
-        it('应该正确处理返回成功 Promise 的函数', async () => {
-            const asyncFn = () => Promise.resolve('async result');
-            const [result, error] = await catchIt(asyncFn);
-            expect(result).toBe('async result');
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理返回失败 Promise 的函数', async () => {
-            const errorValue = new Error('async error');
-            const asyncFn = () => Promise.reject(errorValue);
-            const [result, error] = await catchIt(asyncFn);
-            expect(result).toBeUndefined();
-            expect(error).toBe(errorValue);
-        });
-        it('应该正确处理返回不同数据类型 Promise 的函数', async () => {
-            // 数字
-            const [numberResult] = await catchIt(() => Promise.resolve(123));
-            expect(numberResult).toBe(123);
-            // 对象
-            const obj = { async: true };
-            const [objectResult] = await catchIt(() => Promise.resolve(obj));
-            expect(objectResult).toBe(obj);
-        });
-        it('应该确保返回 Promise 的函数被调用', async () => {
-            const mockAsyncFn = vi.fn(() => Promise.resolve('test'));
-            await catchIt(mockAsyncFn);
-            expect(mockAsyncFn).toHaveBeenCalledOnce();
-        });
+    it('同步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('fail');
+        const result = await catchIt(() => { throw error; });
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
     });
-    describe('边界情况', () => {
-        it('应该正确处理函数中抛出的同步错误', async () => {
-            const syncError = new Error('sync throw error');
-            const errorFn = () => {
-                throw syncError;
-            };
-            const [result, error] = await catchIt(errorFn);
-            expect(result).toBeUndefined();
-            expect(error).toBe(syncError);
-        });
-        it('应该正确处理 Promise 链中的错误', async () => {
-            const chainError = new Error('chain error');
-            const promise = Promise.resolve()
-                .then(() => {
-                throw chainError;
-            });
-            const [result, error] = await catchIt(promise);
-            expect(result).toBeUndefined();
-            expect(error).toBe(chainError);
-        });
-        it('应该正确处理延迟的 Promise', async () => {
-            const delayedPromise = new Promise((resolve) => {
-                setTimeout(() => resolve('delayed result'), 10);
-            });
-            const [result, error] = await catchIt(delayedPromise);
-            expect(result).toBe('delayed result');
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理返回 falsy 值的函数', async () => {
-            // 返回 0
-            const [zeroResult] = await catchIt(() => 0);
-            expect(zeroResult).toBe(0);
-            // 返回空字符串
-            const [emptyStringResult] = await catchIt(() => '');
-            expect(emptyStringResult).toBe('');
-            // 返回 false
-            const [falseResult] = await catchIt(() => false);
-            expect(falseResult).toBe(false);
-            // 返回 null
-            const [nullResult] = await catchIt(() => null);
-            expect(nullResult).toBeNull();
-            // 返回 undefined
-            const [undefinedResult] = await catchIt(() => undefined);
-            expect(undefinedResult).toBeUndefined();
-        });
+    it('异步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('fail-async');
+        const result = await catchIt(() => Promise.reject(error));
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
     });
-    describe('类型安全性', () => {
-        it('应该保持正确的类型推导 - Promise', async () => {
-            // TypeScript 编译时应该能正确推导类型
-            const stringPromise = Promise.resolve('string');
-            const [stringResult] = await catchIt(stringPromise);
-            // stringResult 应该被推导为 string | undefined
-            const numberPromise = Promise.resolve(42);
-            const [numberResult] = await catchIt(numberPromise);
-            // numberResult 应该被推导为 number | undefined
-            // 运行时验证
-            expect(typeof stringResult).toBe('string');
-            expect(typeof numberResult).toBe('number');
-        });
-        it('应该保持正确的类型推导 - 同步函数', async () => {
-            const stringFn = () => 'hello';
-            const [stringResult] = await catchIt(stringFn);
-            const numberFn = () => 42;
-            const [numberResult] = await catchIt(numberFn);
-            // 运行时验证
-            expect(typeof stringResult).toBe('string');
-            expect(typeof numberResult).toBe('number');
-        });
-        it('应该保持正确的类型推导 - 异步函数', async () => {
-            const asyncStringFn = () => Promise.resolve('async hello');
-            const [asyncStringResult] = await catchIt(asyncStringFn);
-            const asyncNumberFn = () => Promise.resolve(100);
-            const [asyncNumberResult] = await catchIt(asyncNumberFn);
-            // 运行时验证
-            expect(typeof asyncStringResult).toBe('string');
-            expect(typeof asyncNumberResult).toBe('number');
-        });
+    it('PromiseLike resolve 时应返回 value，error 为 undefined，isError 为 false', async () => {
+        const result = await catchIt(Promise.resolve('ok'));
+        expect(result.value).toBe('ok');
+        expect(result.error).toBeUndefined();
+        expect(result.isError()).toBe(false);
     });
-    describe('实际使用场景', () => {
-        it('应该适用于 API 调用场景', async () => {
-            // 模拟成功的 API 调用
-            const mockApiCall = () => Promise.resolve({
-                data: { id: 1, name: 'test' },
-                status: 200
-            });
-            const [result, error] = await catchIt(mockApiCall);
-            expect(result).toEqual({ data: { id: 1, name: 'test' }, status: 200 });
-            expect(error).toBeUndefined();
-            // 模拟失败的 API 调用
-            const failedApiCall = () => Promise.reject({
-                status: 404,
-                message: 'Not Found'
-            });
-            const [failedResult, apiError] = await catchIt(failedApiCall);
-            expect(failedResult).toBeUndefined();
-            expect(apiError).toEqual({ status: 404, message: 'Not Found' });
-        });
-        it('应该适用于文件操作场景', async () => {
-            // 模拟成功的文件读取
-            const mockFileRead = () => Promise.resolve('file content');
-            const [content, error] = await catchIt(mockFileRead);
-            expect(content).toBe('file content');
-            expect(error).toBeUndefined();
-            // 模拟失败的文件读取
-            const failedFileRead = () => Promise.reject(new Error('File not found'));
-            const [failedContent, fileError] = await catchIt(failedFileRead);
-            expect(failedContent).toBeUndefined();
-            expect(fileError).toBeInstanceOf(Error);
-            expect(fileError.message).toBe('File not found');
-        });
-        it('应该适用于数据解析场景', async () => {
-            // 模拟成功的 JSON 解析
-            const jsonParseSuccess = () => JSON.parse('{"key": "value"}');
-            const [parsed, parseError] = await catchIt(jsonParseSuccess);
-            expect(parsed).toEqual({ key: 'value' });
-            expect(parseError).toBeUndefined();
-            // 模拟失败的 JSON 解析
-            const jsonParseFailed = () => JSON.parse('invalid json');
-            const [failedParsed, jsonError] = await catchIt(jsonParseFailed);
-            expect(failedParsed).toBeUndefined();
-            expect(jsonError).toBeInstanceOf(SyntaxError);
-        });
-    });
-    describe('处理 PromiseLike 对象', () => {
-        it('应该正确处理自定义的 PromiseLike 对象', async () => {
-            // 创建自定义的 PromiseLike 对象
-            const customPromiseLike = {
-                then(onfulfilled, onrejected) {
-                    try {
-                        const result = onfulfilled?.('custom promise result');
-                        return Promise.resolve(result);
-                    }
-                    catch (error) {
-                        return onrejected ? Promise.resolve(onrejected(error)) : Promise.reject(error);
-                    }
-                }
-            };
-            const [result, error] = await catchIt(customPromiseLike);
-            expect(result).toBe('custom promise result');
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理失败的 PromiseLike 对象', async () => {
-            const customError = new Error('custom promise error');
-            const failingPromiseLike = {
-                then(onfulfilled, onrejected) {
-                    if (onrejected) {
-                        return Promise.resolve(onrejected(customError));
-                    }
-                    return Promise.reject(customError);
-                }
-            };
-            const [result, error] = await catchIt(failingPromiseLike);
-            expect(result).toBeUndefined();
-            expect(error).toBe(customError);
-        });
-        it('应该正确处理返回 PromiseLike 的函数', async () => {
-            const customPromiseLike = {
-                then(onfulfilled, onrejected) {
-                    try {
-                        const result = onfulfilled?.(42);
-                        return Promise.resolve(result);
-                    }
-                    catch (error) {
-                        return onrejected ? Promise.resolve(onrejected(error)) : Promise.reject(error);
-                    }
-                }
-            };
-            const fn = () => customPromiseLike;
-            const [result, error] = await catchIt(fn);
-            expect(result).toBe(42);
-            expect(error).toBeUndefined();
-        });
-        it('应该正确处理第三方库的 PromiseLike 对象', async () => {
-            // 模拟第三方库的 PromiseLike 实现 (如 jQuery.Deferred, Bluebird 等)
-            class CustomPromise {
-                value;
-                isResolved = false;
-                isRejected = false;
-                rejectionReason;
-                constructor(executor) {
-                    const resolve = (value) => {
-                        this.value = value;
-                        this.isResolved = true;
-                    };
-                    const reject = (reason) => {
-                        this.rejectionReason = reason;
-                        this.isRejected = true;
-                    };
-                    try {
-                        executor(resolve, reject);
-                    }
-                    catch (error) {
-                        reject(error);
-                    }
-                }
-                then(onfulfilled, onrejected) {
-                    if (this.isResolved && onfulfilled) {
-                        try {
-                            const result = onfulfilled(this.value);
-                            return Promise.resolve(result);
-                        }
-                        catch (error) {
-                            return Promise.reject(error);
-                        }
-                    }
-                    else if (this.isRejected && onrejected) {
-                        try {
-                            const result = onrejected(this.rejectionReason);
-                            return Promise.resolve(result);
-                        }
-                        catch (error) {
-                            return Promise.reject(error);
-                        }
-                    }
-                    else if (this.isRejected) {
-                        return Promise.reject(this.rejectionReason);
-                    }
-                    return Promise.resolve(this.value);
-                }
-            }
-            const customPromise = new CustomPromise((resolve) => {
-                resolve('third party promise');
-            });
-            const [result, error] = await catchIt(customPromise);
-            expect(result).toBe('third party promise');
-            expect(error).toBeUndefined();
-        });
+    it('PromiseLike reject 时应返回 error，value 为 undefined，isError 为 true', async () => {
+        const error = new Error('promise-fail');
+        const result = await catchIt(Promise.reject(error));
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-base",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "author": "Alain",
   "license": "ISC",
   "description": "",