Error

Об'єкти Error (помилка) викидаються, коли трапляється помилка часу виконання. Об'єкт Error також може використовуватися як базовий об'єкт для винятків, визначених користувачем.

Опис

Помилки часу виконання призводять до створення і викидання нових об'єктів Error.

Error – це серіалізовний об'єкт, тож він може бути клонований за допомогою structuredClone() і скопійований між воркерами за допомогою postMessage().

Типи помилок

Окрім узагальненого конструктора Error, ядро JavaScript містить інші конструктори помилок. Про помилки клієнтського боку читайте Інструкції обробки винятків.

EvalError

Створює примірник, що представляє помилку, котра трапляється відносно глобальної функції eval().

RangeError

Створює примірник, що представляє помилку, котра трапляється, коли числова змінна або параметр знаходяться поза своїм допустимим діапазоном.

ReferenceError

Створює примірник, що представляє помилку, котра трапляється при звертанні за недійсним посиланням.

SyntaxError

Створює примірник, що представляє помилку синтаксису.

TypeError

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

URIError

Створює примірник, що представляє помилку, котра трапляється, коли в encodeURI() або decodeURI() передано невідповідні параметри.

AggregateError

Створює примірник, що представляє кілька помилок, загорнутих в одну помилку, коли операція потребує звітування про декілька помилок, наприклад, Promise.any().

InternalError

Створює примірник, що представляє помилку, котра трапляється тоді, коли викидається внутрішня помилка рушія JavaScript. Наприклад, "забагато рекурсії".

Конструктор

Error()

Створює новий об'єкт Error.

Статичні методи

Error.captureStackTrace()

Нестандартна функція V8, що створює на примірнику Error властивість stack.

Error.stackTraceLimit

Нестандартна числова властивість V8, що обмежує те, скільки фреймів стека включається в трасування стека помилки.

Error.prepareStackTrace() Необов'язкове

Нестандартна функція V8, котра, якщо задана користувацьким кодом, викликається рушієм V8 для викинутих винятків, даючи користувачеві змогу задавати власне форматування трасувань стека.

Властивості примірника

Ці властивості означені на Error.prototype і є спільними для всіх примірників Error.

Error.prototype.constructor

Функція-конструктор, що створила об'єкт-примірник. Для примірників Error початковим значенням є конструктор Error.

Error.prototype.name

Представляє назву типу помилки. Для Error.prototype.name початковим значенням є "Error". Підкласи, наприклад, TypeError і SyntaxError, мають власні властивості name.

Error.prototype.stack

Нестандартна властивість для трасування стека.

Ці властивості є власними властивостями кожного окремого примірника Error.

cause

Причина помилки, що вказує на причину викидання помилки – зазвичай інша, перехоплена помилка. Для створених користувачем об'єктів Error, це значення, що задається властивістю cause другого аргументу конструктора.

columnNumber

Нестандартна властивість Mozilla для номера колонки в рядку, що спричинила помилку.

fileName

Нестандартна властивість Mozilla для шляху до файлу, що спричинив помилку.

lineNumber

Нестандартна властивість Mozilla для номера рядка у файлі, що спричинив помилку.

message

Повідомлення помилки. Для створених користувачем об'єктів Error це рядок, заданий як перший аргумент конструктора.

Методи примірника

Error.prototype.toString()

Повертає рядок, що представляє заданий об'єкт. Заміщує метод Object.prototype.toString().

Приклади

Викидання узагальненої помилки

Зазвичай об'єкт Error створюють з наміром викинути його за допомогою ключового слова throw. Обробити помилку можна за допомогою конструкції try...catch:

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

Обробка помилок конкретного типу

Обробляти помилки лише певного типу можна шляхом перевірки типу помилки за допомогою ключового слова instanceof:

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 {
    // Якшо жодна з перевірок не спрацювала – залишити Error без обробки
    throw e;
  }
}

Розрізнення подібних помилок

Іноді блок коду може зазнавати невдачі з причин, що потребують різної обробки, але викидають дуже подібні помилки (наприклад, з однаковими типом і повідомленням).

Якщо немає контролю над вихідними помилками, що викидаються, то один з варіантів – перехоплювати їх і викидати нові об'єкти Error, що мають конкретніші повідомлення. Вихідна помилка повинна бути передана в новий Error у параметр options конструктора як його властивість cause. Це дає впевненість щодо того, що блокам try-catch вищого рівня доступні вихідні помилка та трасування стека.

Приклад нижче показує це для двох методів, що інакше зазнавали б невдачі з подібними помилками (doFailSomeWay() і doFailAnotherWay()):

function doWork() {
  try {
    doFailSomeWay();
  } catch (err) {
    throw new Error("Якось не вийшло", { cause: err });
  }
  try {
    doFailAnotherWay();
  } catch (err) {
    throw new Error("Не вийшло якось інакше", { cause: err });
  }
}

try {
  doWork();
} catch (err) {
  switch (err.message) {
    case "Якось не вийшло":
      handleFailSomeWay(err.cause);
      break;
    case "Не вийшло якось інакше":
      handleFailAnotherWay(err.cause);
      break;
  }
}

[!NOTE] При написанні бібліотеки краще використовувати причину помилки для розрізнення різних помилок, що породжуються, а не просити користувачів бібліотеки розбирати повідомлення помилок. Шукайте приклад на сторінці причини помилки.

Власні типи помилок також можуть використовувати властивість cause, за умови, що конструктор підкласів передає параметр options при виклику super(). Конструктор базового класу Error() зчитає options.cause та означить на новому примірнику помилки властивість cause.

class MyError extends Error {
  constructor(message, options) {
    // Необхідно передавати `options` як другий параметр, аби встановити властивість "cause".
    super(message, options);
  }
}

console.log(new MyError("перевірка", { cause: new Error("причина") }).cause);
// Error: причина

Власні типи помилок

Може з'явитись потреба означити власні типи помилок, похідні від Error, аби мати змогу виконувати throw new MyError() і використовувати instanceof MyError для перевірки ґатунку помилки в обробнику помилок. Такий підхід призводить до чистішого та сталішого коду обробки помилок.

Читайте заглиблену дискусію на StackOverflow – "Що є добрим способом розширювати Error у JavaScript?".

[!WARNING] Вбудоване створення підкласів не може бути надійно трансльовано у код до ES6, тому що немає способу сконструювати базовий клас із конкретним значенням new.target без Reflect.construct(). Необхідне додаткове налаштування або ручний виклик Object.setPrototypeOf(this, CustomError.prototype) у кінці конструктора; без цього сконструйований примірник не буде примірником CustomError. Більше інформації – у ЧаПах TypeScript.

[!NOTE] Частина браузерів включає конструктор CustomError у трасування стека при використанні класів ES2015.

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
}

Специфікації

Сумісність із браузерами

Дивіться також

• Поліфіл Error з підтримкою cause у складі core-js
• throw
• try...catch
• API трасування стека в документації V8