new RangeError() — Methode · JavaScript-Referenz

Signatur

new RangeError(message, options)

Beschreibung

Mit new RangeError() erzeugt man ein Fehlerobjekt, das anzeigt: Ein Wert hat zwar den richtigen Typ, liegt aber außerhalb des zulässigen Bereichs. Die JavaScript-Engine selbst wirft RangeError zum Beispiel bei new Array(-1), bei Number.prototype.toFixed(101), bei String.prototype.repeat(-1) oder bei zu tiefer Rekursion (Maximum call stack size exceeded).

In eigenem Code eignet sich RangeError, um Argumente zu prüfen, deren Typ stimmt, deren Wert aber ungültig ist, etwa eine negative Seitenzahl, ein Prozentwert über 100 oder ein unbekannter Enum-Wert. Ist dagegen der Typ falsch, passt TypeError besser.

Der Konstruktor kann mit oder ohne new aufgerufen werden; beide Varianten liefern eine neue RangeError-Instanz. Sie erbt von Error und hat daher die Eigenschaften name ("RangeError"), message, stack (nicht standardisiert, aber überall vorhanden) und gegebenenfalls cause.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Für Menschen lesbare Fehlerbeschreibung. Werte, die keine Strings sind, werden mit `String()` umgewandelt.
$options	{ cause?: any }		Objekt mit der Eigenschaft `cause`, die den ursprünglichen Fehler bzw. die Ursache angibt (ES2022). Sie wird als Eigenschaft `cause` an der Instanz gespeichert.

Rückgabewert

Typ

RangeError

Beschreibung

Eine neue RangeError-Instanz mit gesetzten Eigenschaften message und gegebenenfalls cause.

Beispiele

Argument-Validierung in einer Funktion

const setVolume = (level) => {
  if (typeof level !== 'number') {
    throw new TypeError('level muss eine Zahl sein');
  }
  if (level < 0 || level > 100) {
    throw new RangeError(`level muss zwischen 0 und 100 liegen, erhalten: ${level}`);
  }
  return `Lautstärke: ${level}%`;
};

try {
  setVolume(150);
} catch (err) {
  console.log(err.name);
  console.log(err.message);
  console.log(err instanceof RangeError, err instanceof Error);
}

RangeError level muss zwischen 0 und 100 liegen, erhalten: 150 true true

Von der Engine geworfene RangeErrors abfangen

const tryIt = (fn) => {
  try {
    fn();
  } catch (err) {
    if (err instanceof RangeError) {
      console.log(`RangeError: ${err.message}`);
    } else {
      throw err;
    }
  }
};

tryIt(() => new Array(-1));
tryIt(() => 'ab'.repeat(-1));
tryIt(() => (3.14).toFixed(200));

RangeError: Invalid array length RangeError: Invalid count value: -1 RangeError: toFixed() digits argument must be between 0 and 100 (Meldungstexte je nach Engine unterschiedlich)

Fehlerursache mit options.cause weitergeben

const parsePage = (input) => {
  const page = Number.parseInt(input, 10);
  if (!Number.isInteger(page) || page < 1) {
    throw new RangeError(`Ungültige Seitenzahl: "${input}"`, {
      cause: { input, parsed: page }
    });
  }
  return page;
};

try {
  parsePage('0');
} catch (err) {
  console.log(err.message);
  console.log(err.cause);
}

Ungültige Seitenzahl: "0" { input: '0', parsed: 0 }

Aufruf ohne new

const err = RangeError('Wert zu groß');
console.log(err instanceof RangeError);
console.log(String(err));

true RangeError: Wert zu groß

// Wichtig · Fallstricke

RangeError oder TypeError? RangeError gilt für einen korrekten Typ mit unzulässigem Wert, TypeError für einen falschen Typ. Wer das sauber trennt, macht die Fehlerbehandlung beim Aufrufer einfacher.
Die Meldungstexte der Engine (V8, SpiderMonkey, JavaScriptCore) sind nicht standardisiert. Prüfe daher nie auf err.message, sondern auf err instanceof RangeError oder err.name.
Ein Stapelüberlauf (Maximum call stack size exceeded) ist in V8 ein RangeError, in Firefox dagegen ein InternalError („too much recursion“). Darauf sollte man sich also nicht plattformübergreifend verlassen.
instanceof kann über Realm-Grenzen hinweg (iframes, vm-Kontexte in Node.js) fehlschlagen. In diesem Fall hilft err.name === 'RangeError'.
Die Option cause gibt es seit ES2022 (Chrome 93, Firefox 91, Safari 15, Node.js 16.9). Ältere Umgebungen ignorieren das zweite Argument einfach.
Für eigene Unterklassen class MyError extends RangeError verwenden und this.name im Konstruktor setzen.

Siehe auch

Error new Error() throw try...catch new TypeError()