Error
=====

Экземпляры объекта `Error` выбрасываются при возникновении ошибок во время выполнения. Объект `Error` также может использоваться в качестве базового для пользовательских исключений. Смотрите ниже стандартные встроенные типы ошибок.

Описание
--------

Во время выполнения кода ошибки приводят к созданию и выбрасыванию новых объектов `Error`.

`Error` является сериализуемым объектом (en-US), поэтому он может быть клонирован с помощью `structuredClone()` (en-US) или передан между воркерами с использованием `postMessage()`.

### Типы ошибок

Кроме общего конструктора `Error`, в JavaScript существуют другие встроенные конструкторы ошибок, смотрите раздел Выражения обработки исключений.

`EvalError`

Создаёт экземпляр, представляющий ошибку, возникающую в глобальной функции `eval()`.

`RangeError`

Создаёт экземпляр, представляющий ошибку, возникающую при выходе числовой переменной или параметра за пределы допустимого диапазона.

`ReferenceError`

Создаёт экземпляр, представляющий ошибку, возникающую при разыменовывании недопустимой ссылки.

`SyntaxError`

Создаёт экземпляр, представляющий синтаксическую ошибку, возникающую при разборе исходного кода в функции `eval()`.

`TypeError`

Создаёт экземпляр, представляющий ошибку, возникающую при недопустимом типе для переменной или параметра.

`URIError`

Создаёт экземпляр, представляющий ошибку, возникающую при передаче в функции `encodeURI()` или `decodeURI()` недопустимых параметров.

`AggregateError` (en-US)

Создаёт экземпляр, представляющий несколько ошибок, обёрнутых в одну. Может быть полезно, например, при работе с `Promise.any()`.

`InternalError` 
Non-standard

Создаёт экземпляр, представляющий ошибку, возникающую при выбрасывании внутренней ошибки в движке JavaScript. К примеру, ошибки «слишком глубокая рекурсия» («too much recursion»).

Конструктор
-----------

`Error()` (en-US)

Создаёт новый объект `Error`.

Статические методы
------------------

`Error.captureStackTrace()` 
Non-standard

Нестандартная функция V8, которая создаёт свойство `stack` у экземпляра `Error`.

`Error.stackTraceLimit` 
Non-standard

Нестандартное числовое свойство V8, которое ограничивает количество уровней ошибок, включаемых в трассировку стека.

`Error.prepareStackTrace()` 
Non-standard
 Необязательный

Нестандартная функция V8, которая (если задана в пользовательском коде) вызывается JavaScript-движком V8 для выбрасывание исключений, позволяя определять нестандартное форматирование трассировки стека.

Свойства экземпляра
-------------------

Эти свойства определены в `Error.prototype` и есть у всех экземпляров `Error`.

`Error.prototype.constructor`

Функция-конструктор, создающая экземпляр объекта. Для экземпляров `Error` начальным значением является конструктор `Error` (en-US).

`Error.prototype.name`

Представляет название типа ошибки. Начальным значением `Error.prototype.name` является `"Error"`. Подклассы (например, `TypeError` и `SyntaxError`) имеют собственные значения свойства `name`.

`Error.prototype.stack` 
Non-standard

Нестандартное свойство, содержащее трассировку стека.

Эти свойства являются собственными свойствами каждого экземпляра `Error`.

* `cause` (en-US)
    + : Причина возникновения текущей ошибки — обычно это другая обнаруженная ошибка. Для созданных пользователем объектов `Error` это значение свойства `cause` второго аргумента конструктора.
    + : Нестандартное свойство Mozilla, определяющее номер символа в строке, в которой возникла ошибка.
* `fileName` 
Non-standard

    + : Нестандартное свойство Mozilla, определяющее путь к файлу, в котором возникла ошибка.
* `lineNumber` 
Non-standard

    + : Нестандартное свойство Mozilla, определяющее номер строки в файле, где возникла ошибка.
* `message`
    + : Сообщение об ошибке. Для созданных пользователем объектов `Error` это строка, передаваемая в качестве первого аргумента конструктора.
Методы экземпляра
-----------------

`Error.prototype.toString()`

Возвращает строку, представляющую указанный объект. Переопределяет метод `Object.prototype.toString()`.

Примеры
-------

### Выбрасывание обычной ошибки

Обычно, вы создаёте объект `Error` с намерением возбудить ошибку с помощью ключевого слова `throw`. Вы можете обработать ошибку с помощью конструкции `try...catch`:


```js
try {
  throw new Error("Ой!");
} catch (e) {
  console.error(`${e.name}: ${e.message}`);
}
```

### Обработка ошибки конкретного типа

Для обработки только определённых типов ошибок можно делать проверку типа с помощью ключевого слова `instanceof`:


```js
try {
  foo.bar();
} catch (e) {
  if (e instanceof EvalError) {
    console.error(`${e.name}: ${e.message}`);
  } else if (e instanceof RangeError) {
    console.error(`${e.name}: ${e.message}`);
  }
  // и так далее
  else {
    // Если ни один из типов не совпал, то оставляем ошибку необработанной
    throw e;
  }
}
```

### Пользовательские типы ошибок

Вы можете захотеть определить свои собственные типы ошибок, унаследованные от `Error`, чтобы иметь возможность возбуждать их с помощью `throw new MyError()` и использовать `instanceof MyError` для проверки вида ошибки в обработчике исключений. Это помогает делать обработку ошибок более понятной.

Также смотрите обсуждение «Какой способ расширения Error в JavaScript более предпочтителен?» на StackOverflow.

**Предупреждение:** Встроенные подклассы не могут быть надёжно преобразованы в ES6 код, потому что нет возможности создать базовый класс со специфичным `new.target` без `Reflect.construct()`. Требуется дополнительная конфигурация или ручной вызов `Object.setPrototypeOf(this, CustomError.prototype)` в конце конструктора, иначе создаваемый экземпляр не будет экземпляром `CustomError`. Смотрите TypeScript FAQ для получения дополнительной информации.

**Примечание:** Некоторые браузеры включают конструктор `CustomError` в трассировку стека при использовании классов ES2015.


```js
class CustomError extends Error {
  constructor(foo = "bar", ...params) {
    // Передаём все аргументы (включая специфичные для производителя движка) родительскому конструктору
    super(...params);

    // Поддерживаем соответствующую трассировку стека с указанием места возникновения ошибки (доступно только в V8)
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, CustomError);
    }

    this.name = "CustomError";
    // Дополнительная отладочная информация
    this.foo = foo;
    this.date = new Date();
  }
}

try {
  throw new CustomError("baz", "bazMessage");
} catch (e) {
  console.error(e.name); // CustomError
  console.error(e.foo); // baz
  console.error(e.message); // bazMessage
  console.error(e.stack); // stacktrace
}
```

Спецификации
------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-error-objects |

Совместимость с браузерами
--------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Смотрите также
--------------

* Полифил `Error` с поддержкой `cause` в `core-js`
* `throw`
* `try...catch`
* Stack trace API в документации V8