feat(isError): append isError (#579)

* feat: add isError to predicate

Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

* test: isError


Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

* docs: isError


Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

* feat: isError at compat


Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

* feat: export to compat

* fix: format

Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

---------

Co-authored-by: leeminhee119 <mhl98@dgu.ac.kr>

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: '' });
+  });
+});

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
+```

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
+```

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
+```

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
+```

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';

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);
+  });
+});

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]';
+}

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';

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);
+  });
+});

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;
+}