Error: cause

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

Оно используется при перехвате и повторном возбуждении ошибки с более специфичным или полезным сообщением об ошибке, чтобы сохранить доступ к исходной ошибке.

Значение

Значение, которое было передано конструктору Error() в аргументе options.cause. Оно может отсутствовать.

Описание

Значение cause может иметь любой тип. Вы не должны предполагать, что перехваченная вами ошибка имеет Error в качестве своего cause, точно так же, как вы не можете быть уверены, что переменная, связанная в операторе catch, также является Error. Пример "Предоставление структурированных данных в качестве причины ошибки" ниже демонстрирует случай, когда в качестве причины намеренно предоставляется не-ошибка.

Подклассы SuppressedError и AggregateError оба служат для связывания нескольких ошибок. Оба они представляют несколько мест сбоя: SuppressedError представляет ошибку, возникшую при обработке другой ошибки, в то время как AggregateError представляет собой набор множественных, несвязанных ошибок, возникших во время одной и той же операции. Свойство cause представляет одно место сбоя, при этом ошибка-обертка только добавляет контекст к причине и не представляет собой дополнительный сбой.

Ниже представлено типичное использование cause. Имеется одно место сбоя, которое возникает внутри mainLogic(). Оператор throw new Error() просто оборачивает эту исходную ошибку, чтобы добавить контекст, и не является дополнительным сбоем.

try {
  mainLogic();
} catch (err) {
  throw new Error("Main logic failed", { cause: err });
}

Ниже представлено типичное использование SuppressedError. Есть два места сбоя: одно в mainLogic(), а другое в cleanup(). Экземпляр SuppressedError связывает эти две ошибки.

try {
  mainLogic();
} catch (primaryError) {
  try {
    cleanup();
  } catch (cleanupError) {
    throw new SuppressedError(
      cleanupError,
      primaryError,
      "Main logic failed; while handling that, cleanup also failed",
    );
  }
}

Ниже представлено типичное использование AggregateError. Имеется несколько мест сбоя в mainLogic(). Экземпляр AggregateError связывает все ошибки.

function mainLogic() {
  const errors = [];
  try {
    operation1();
  } catch (e1) {
    errors.push(e1);
  }
  try {
    operation2();
  } catch (e2) {
    errors.push(e2);
  }
  if (errors.length > 0) {
    throw new AggregateError(errors, "Multiple operations failed");
  }
}

Примеры

Повторное возбуждение ошибки с указанием причины

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

try {
  connectToDatabase();
} catch (err) {
  throw new Error("Connecting to database failed.", { cause: err });
}

Более подробный пример см. в разделе Error > Различия между похожими ошибками.

Предоставление структурированных данных в качестве причины ошибки

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

function makeRSA(p, q) {
  if (!Number.isInteger(p) || !Number.isInteger(q)) {
    throw new Error("RSA key generation requires integer inputs.", {
      cause: { code: "NonInteger", values: [p, q] },
    });
  }
  if (!areCoprime(p, q)) {
    throw new Error("RSA key generation requires two co-prime integers.", {
      cause: { code: "NonCoprime", values: [p, q] },
    });
  }
  // rsa algorithm…
}

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

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

См. также

• Error.prototype.message
• Error.prototype.toString()