new AggregateError() — Methode · JavaScript-Referenz

Signatur

new AggregateError(errors, message, options)

Beschreibung

Mit new AggregateError() erzeugen Sie ein Fehlerobjekt, das mehrere Fehler gleichzeitig enthält. Die einzelnen Fehler liegen danach als Array in der Eigenschaft errors. Das ist praktisch, wenn mehrere unabhängige Vorgänge fehlschlagen können und Sie nicht nur den ersten Fehler melden möchten, zum Beispiel bei der Validierung von Formularen, bei Stapelverarbeitung oder bei parallelen Netzwerkanfragen.

Die Sprache selbst verwendet AggregateError in Promise.any(). Werden alle übergebenen Promises abgelehnt, wird das Ergebnis-Promise mit einem AggregateError abgelehnt, der alle Ablehnungsgründe enthält.

Der erste Parameter muss ein iterierbares Objekt sein, etwa ein Array, ein Set oder ein Generator. Er wird in ein echtes Array umgewandelt. Der Konstruktor lässt sich auch ohne new aufrufen und liefert dann dasselbe Ergebnis. AggregateError erbt von Error. Deshalb gibt instanceof Error ebenfalls true zurück.

Parameter

Name	Typ	Default	Beschreibung
$errors Pflicht	Iterable<any>		Iterierbares Objekt mit den einzelnen Fehlern, meist `Error`-Instanzen. Es sind aber beliebige Werte erlaubt. Der Inhalt landet als Array in `errors`.
$message	string	""	Lesbare Beschreibung des Gesamtfehlers. Sie wird in `message` gespeichert. Andere Werte als Zeichenketten werden in eine Zeichenkette umgewandelt.
$options	{ cause?: any }		Objekt mit der optionalen Eigenschaft `cause`. Sie gibt die ursprüngliche Ursache an und wird in `error.cause` gespeichert.

Rückgabewert

Typ

AggregateError

Beschreibung

Eine neue AggregateError-Instanz mit den Eigenschaften errors (Array), message, name ("AggregateError") und, falls angegeben, cause.

Beispiele

Einfache Instanziierung

const err = new AggregateError(
  [new TypeError('Ungültiger Typ'), new RangeError('Wert zu groß')],
  'Mehrere Fehler aufgetreten'
);

console.log(err.name);
console.log(err.message);
console.log(err.errors.length);
console.log(err.errors.map(e => e.message));
console.log(err instanceof Error);

AggregateError Mehrere Fehler aufgetreten 2 [ 'Ungültiger Typ', 'Wert zu groß' ] true

Formularvalidierung: alle Fehler auf einmal melden

const validateUser = (user) => {
  const errors = [];
  if (!user.name) errors.push(new Error('Name fehlt'));
  if (!/^[^@]+@[^@]+$/.test(user.email ?? '')) errors.push(new Error('E-Mail ungültig'));
  if (user.age < 18) errors.push(new RangeError('Mindestalter 18'));

  if (errors.length > 0) {
    throw new AggregateError(errors, `Validierung fehlgeschlagen (${errors.length} Fehler)`);
  }
  return true;
};

try {
  validateUser({ name: '', email: 'foo', age: 16 });
} catch (e) {
  if (e instanceof AggregateError) {
    console.log(e.message);
    e.errors.forEach(err => console.log('-', err.message));
  }
}

Validierung fehlgeschlagen (3 Fehler) - Name fehlt - E-Mail ungültig - Mindestalter 18

Parallele Anfragen mit Fehlersammlung und cause

const tasks = [
  Promise.reject(new Error('Server A nicht erreichbar')),
  Promise.resolve('OK von B'),
  Promise.reject(new Error('Server C Timeout'))
];

const runAll = async () => {
  const results = await Promise.allSettled(tasks);
  const failures = results
    .filter(r => r.status === 'rejected')
    .map(r => r.reason);

  if (failures.length) {
    throw new AggregateError(failures, 'Synchronisation teilweise fehlgeschlagen', {
      cause: { job: 'nightly-sync' }
    });
  }
};

runAll().catch(e => {
  console.log(e.message, e.cause.job);
  console.log(e.errors.map(x => x.message));
});

Synchronisation teilweise fehlgeschlagen nightly-sync [ 'Server A nicht erreichbar', 'Server C Timeout' ]

Von Promise.any() erzeugter AggregateError

const run = async () => {
  try {
    await Promise.any([
      Promise.reject(new Error('Mirror 1 down')),
      Promise.reject(new Error('Mirror 2 down'))
    ]);
  } catch (e) {
    console.log(e.constructor.name);
    console.log(e.errors.map(x => x.message));
  }
};
run();

AggregateError [ 'Mirror 1 down', 'Mirror 2 down' ]

// Wichtig · Fallstricke

Die Reihenfolge der Parameter ist anders als bei Error: Die Fehlerliste steht an erster Stelle, die Nachricht an zweiter. Mit new AggregateError('Nachricht') wird die Zeichenkette als iterierbares Objekt behandelt. Jeder Buchstabe wird dann zu einem eigenen Eintrag in errors.
Ist errors nicht iterierbar, zum Beispiel undefined oder eine Zahl, wirft der Konstruktor einen TypeError.
Das Array errors ist eine Kopie. Spätere Änderungen am übergebenen Array wirken sich nicht auf den Fehler aus.
Nicht alle Umgebungen geben die enthaltenen Fehler aus. Viele Konsolen und Logging-Bibliotheken zeigen nur message und den Stacktrace an. Geben Sie error.errors deshalb bei Bedarf selbst aus.
Kompatibilität: Die Funktion wird von allen aktuellen Browsern unterstützt (Chrome 85+, Firefox 79+, Safari 14+) sowie von Node.js 15+. Die Option cause gibt es erst seit ES2022 (Chrome 93+, Node.js 16.9+). Ältere Umgebungen brauchen ein Polyfill, etwa aus core-js.

Siehe auch

AggregateError AggregateError.prototype.errors Promise.any() Promise.allSettled() Error Error.prototype.cause try...catch