diff --git a/benchmarks/performance/isError.bench.ts b/benchmarks/performance/isError.bench.ts new file mode 100644 index 00000000..ad187a10 --- /dev/null +++ b/benchmarks/performance/isError.bench.ts @@ -0,0 +1,19 @@ +import { bench, describe } from 'vitest'; +import { isError as isErrorToolkit } from 'es-toolkit'; +import { isError as isErrorLodash } from 'lodash'; + +describe('isError', () => { + bench('es-toolkit/isError', () => { + isErrorToolkit(new Error()); + isErrorToolkit(1); + isErrorToolkit('Error'); + isErrorToolkit({ name: 'Error', message: '' }); + }); + + bench('lodash/isError', () => { + isErrorLodash(new Error()); + isErrorLodash(1); + isErrorLodash('Error'); + isErrorLodash({ name: 'Error', message: '' }); + }); +}); diff --git a/docs/ja/reference/predicate/isError.md b/docs/ja/reference/predicate/isError.md new file mode 100644 index 00000000..f0b45e74 --- /dev/null +++ b/docs/ja/reference/predicate/isError.md @@ -0,0 +1,27 @@ +# isError + +`value`がErrorオブジェクトであるかどうかを確認します。 + +この関数はTypeScriptの型ガードとしても使用できます。引数に与えた値の型を`Error`に絞り込みます。 + +## インターフェース + +```typescript +function isError(value: unknown): value is Error; +``` + +### パラメータ + +- `value` (`unknown`): 確認する値です。 + +### 戻り値 + +(`value is Error`): `value`がErrorオブジェクトであれば`true`を、それ以外の場合は`false`を返します。 + +## 例 + +```typescript +isError(new Error()); // true +isError('error'); // false +isError({ name: 'Error', message: '' }); // false +``` diff --git a/docs/ko/reference/predicate/isError.md b/docs/ko/reference/predicate/isError.md new file mode 100644 index 00000000..1d763055 --- /dev/null +++ b/docs/ko/reference/predicate/isError.md @@ -0,0 +1,27 @@ +# isError + +주어진 값이 Error 객체인지 확인해요. + +TypeScript의 타입 가드로 사용할 수 있어요. 파라미터로 주어진 값의 타입을 `Error`로 좁혀요. + +## 인터페이스 + +```typescript +function isError(value: unknown): value is Error; +``` + +### 파라미터 + +- `value`(`unknown`): Error 객체인지 테스트할 값. + +### 반환 값 + +(`value is Error`): 값이 Error 객체이면 `true`, 아니면 `false`. + +## 예시 + +```typescript +isError(new Error()); // true +isError('error'); // false +isError({ name: 'Error', message: '' }); // false +``` diff --git a/docs/reference/predicate/isError.md b/docs/reference/predicate/isError.md new file mode 100644 index 00000000..5b92d0a2 --- /dev/null +++ b/docs/reference/predicate/isError.md @@ -0,0 +1,27 @@ +# isError + +Check if the given value is an Error object. + +This function can also serve as a type predicate in TypeScript, narrowing the type of the argument to Error. + +## Signature + +```typescript +function isError(value: unknown): value is Error; +``` + +### Parameters + +- `value`(`unknown`): The value to test if it is an Error object. + +### Returns + +(`value is Error`): True if the value is an Error object, otherwise false. + +## Examples + +```typescript +isError(new Error()); // true +isError('error'); // false +isError({ name: 'Error', message: '' }); // false +``` diff --git a/docs/zh_hans/reference/predicate/isError.md b/docs/zh_hans/reference/predicate/isError.md new file mode 100644 index 00000000..992eb220 --- /dev/null +++ b/docs/zh_hans/reference/predicate/isError.md @@ -0,0 +1,27 @@ +# isError + +检查 `value` 是否是 Error 对象。 + +此函数还可以作为 TypeScript 中的类型谓词,将参数的类型缩小为 `Error`。 + +## 签名 + +```typescript +function isError(value: unknown): value is Error; +``` + +### 参数 + +- `value` (`unknown`): 要检查的值。 + +### 返回值 + +(`value is Error`): 如果 `value` 是 Error 对象,则返回 `true`,否则返回 `false`。 + +## 示例 + +```typescript +isError(new Error()); // true +isError('error'); // false +isError({ name: 'Error', message: '' }); // false +``` diff --git a/src/compat/index.ts b/src/compat/index.ts index a4339d2a..a7ddaa4f 100644 --- a/src/compat/index.ts +++ b/src/compat/index.ts @@ -78,6 +78,7 @@ export { isSymbol } from './predicate/isSymbol.ts'; export { isObject } from './predicate/isObject.ts'; export { isObjectLike } from './predicate/isObjectLike.ts'; export { isBoolean } from './predicate/isBoolean.ts'; +export { isError } from './predicate/isError.ts'; export { isTypedArray } from './predicate/isTypedArray.ts'; export { isMatch } from './predicate/isMatch.ts'; export { isRegExp } from './predicate/isRegExp.ts'; diff --git a/src/compat/predicate/isError.spec.ts b/src/compat/predicate/isError.spec.ts new file mode 100644 index 00000000..423bfb21 --- /dev/null +++ b/src/compat/predicate/isError.spec.ts @@ -0,0 +1,36 @@ +import { describe, expect, it } from 'vitest'; +import { isError } from './isError'; + +describe('isError', () => { + it('should return `true` for error objects', () => { + expect(isError(new Error())).toBe(true); + }); + + it("should return 'true' for subclassed values", () => { + class CustomError extends Error {} + expect(isError(new CustomError())).toBe(true); + }); + + it("should return 'false' for non-error objects", () => { + expect(isError({})).toBe(false); + expect(isError(null)).toBe(false); + expect(isError(undefined)).toBe(false); + expect(isError('')).toBe(false); + expect(isError(1)).toBe(false); + expect(isError(true)).toBe(false); + expect(isError(Symbol())).toBe(false); + expect(isError(() => {})).toBe(false); + expect(isError(new Date())).toBe(false); + expect(isError(new Map())).toBe(false); + expect(isError(new Set())).toBe(false); + }); + + it("should return 'false' for plain objects", () => { + expect(isError({ name: 'Error', message: '' })).toBe(false); + }); + + it('should work with an error object from another realm', () => { + const realm = { error: new Error() }; + expect(isError(realm.error)).toBe(true); + }); +}); diff --git a/src/compat/predicate/isError.ts b/src/compat/predicate/isError.ts new file mode 100644 index 00000000..0856d898 --- /dev/null +++ b/src/compat/predicate/isError.ts @@ -0,0 +1,18 @@ +import { getTag } from '../_internal/getTag'; + +/** + * Checks if `value` is an Error object. + * + * @param {unknown} value The value to check. + * @returns {value is Error} Returns `true` if `value` is an Error object, `false` otherwise. + * + * @example + * ```typescript + * console.log(isError(new Error())); // true + * console.log(isError('Error')); // false + * console.log(isError({ name: 'Error', message: '' })); // false + * ``` + */ +export function isError(value?: unknown): value is Error { + return getTag(value) === '[object Error]'; +} diff --git a/src/predicate/index.ts b/src/predicate/index.ts index 7c92db5c..08faed4e 100644 --- a/src/predicate/index.ts +++ b/src/predicate/index.ts @@ -1,5 +1,6 @@ export { isDate } from './isDate.ts'; export { isEqual } from './isEqual.ts'; +export { isError } from './isError.ts'; export { isNil } from './isNil.ts'; export { isNotNil } from './isNotNil.ts'; export { isNull } from './isNull.ts'; diff --git a/src/predicate/isError.spec.ts b/src/predicate/isError.spec.ts new file mode 100644 index 00000000..423bfb21 --- /dev/null +++ b/src/predicate/isError.spec.ts @@ -0,0 +1,36 @@ +import { describe, expect, it } from 'vitest'; +import { isError } from './isError'; + +describe('isError', () => { + it('should return `true` for error objects', () => { + expect(isError(new Error())).toBe(true); + }); + + it("should return 'true' for subclassed values", () => { + class CustomError extends Error {} + expect(isError(new CustomError())).toBe(true); + }); + + it("should return 'false' for non-error objects", () => { + expect(isError({})).toBe(false); + expect(isError(null)).toBe(false); + expect(isError(undefined)).toBe(false); + expect(isError('')).toBe(false); + expect(isError(1)).toBe(false); + expect(isError(true)).toBe(false); + expect(isError(Symbol())).toBe(false); + expect(isError(() => {})).toBe(false); + expect(isError(new Date())).toBe(false); + expect(isError(new Map())).toBe(false); + expect(isError(new Set())).toBe(false); + }); + + it("should return 'false' for plain objects", () => { + expect(isError({ name: 'Error', message: '' })).toBe(false); + }); + + it('should work with an error object from another realm', () => { + const realm = { error: new Error() }; + expect(isError(realm.error)).toBe(true); + }); +}); diff --git a/src/predicate/isError.ts b/src/predicate/isError.ts new file mode 100644 index 00000000..313f1922 --- /dev/null +++ b/src/predicate/isError.ts @@ -0,0 +1,16 @@ +/** + * Checks if `value` is an Error object. + * + * @param {unknown} value The value to check. + * @returns {value is Error} Returns `true` if `value` is an Error object, `false` otherwise. + * + * @example + * ```typescript + * console.log(isError(new Error())); // true + * console.log(isError('Error')); // false + * console.log(isError({ name: 'Error', message: '' })); // false + * ``` + */ +export function isError(value: unknown): value is Error { + return value instanceof Error; +}