Symbol.prototype.description — Eigenschaft · JavaScript-Referenz

Signatur

get Symbol.prototype.description

Beschreibung

Die schreibgeschützte Zugriffs-Eigenschaft description liefert den Text, der beim Erzeugen eines Symbols über Symbol(beschreibung) oder Symbol.for(schlüssel) angegeben wurde. Bei bekannten Symbolen wie Symbol.iterator lautet sie z. B. "Symbol.iterator".

Vor ES2019 kam man nur über symbol.toString() an die Beschreibung und musste das Ergebnis "Symbol(...)" umständlich zerlegen. description gibt den Rohtext direkt zurück. Außerdem unterscheidet die Eigenschaft zwischen keiner Beschreibung (undefined) und einer leeren Beschreibung (""). Mit toString() geht das nicht, denn beide Fälle ergeben dort "Symbol()".

Typische Einsatzzwecke sind Logging, Fehlersuche, Fehlermeldungen und das Auswerten symbolbasierter Schlüssel, z. B. zusammen mit Object.getOwnPropertySymbols(). Die Beschreibung dient nur als Bezeichnung: Zwei Symbole mit derselben Beschreibung sind trotzdem verschieden.

Rückgabewert

Typ

string | undefined

Beschreibung

Die Beschreibung des Symbols als Zeichenfolge oder undefined, wenn beim Erzeugen keine Beschreibung angegeben wurde.

Beispiele

Grundlagen: Beschreibung auslesen

const ohne = Symbol();
const leer = Symbol('');
const mit = Symbol('userId');

console.log(ohne.description);
console.log(leer.description === '');
console.log(mit.description);
console.log(Symbol.iterator.description);
console.log(Symbol.for('app.token').description);

// Vergleich mit toString(): hier gehen Informationen verloren
console.log(ohne.toString(), leer.toString());

undefined true userId Symbol.iterator app.token Symbol() Symbol()

Symbol-Schlüssel eines Objekts für das Logging lesbar machen

const ROLE = Symbol('role');
const SESSION = Symbol('session');

const user = {
  name: 'Anna',
  [ROLE]: 'admin',
  [SESSION]: 'abc123'
};

const symbolKeys = Object.getOwnPropertySymbols(user)
  .map((sym) => sym.description ?? '(ohne Beschreibung)');

console.log(`Versteckte Schlüssel: ${symbolKeys.join(', ')}`);

Versteckte Schlüssel: role, session

Gleiche Beschreibung heißt nicht gleiches Symbol

const a = Symbol('id');
const b = Symbol('id');

console.log(a.description === b.description);
console.log(a === b);

// Nur Symbol.for() liefert für denselben Schlüssel dasselbe Symbol zurück
console.log(Symbol.for('id') === Symbol.for('id'));

true false true

// Wichtig · Fallstricke

Schreibgeschützt: Die Eigenschaft hat nur einen Getter. Eine Zuweisung wie sym.description = 'x' wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.
undefined und "" unterscheiden: Mit ?? statt || einen Ersatzwert setzen, sonst geht eine absichtlich leere Beschreibung verloren.
Umwandlung der Beschreibung: Wird Symbol() ein Wert übergeben, der keine Zeichenfolge ist, wird er in eine Zeichenfolge umgewandelt: Symbol(42).description ergibt "42". Bei Symbol(undefined) ist die Beschreibung undefined.
Nicht eindeutig: Die Beschreibung taugt nicht zum Identifizieren oder Vergleichen von Symbolen. Für programmweit geteilte Symbole gibt es Symbol.for() und Symbol.keyFor().
Kompatibilität: Gehört zu ES2019. Wird von allen modernen Browsern (seit etwa Chrome 70, Firefox 63, Safari 12.1) und von Node.js ab Version 11 unterstützt. Der Internet Explorer kennt die Eigenschaft nicht, dort bleibt nur toString().

Siehe auch

Symbol Symbol.prototype.toString() Symbol.for() Symbol.keyFor() Object.getOwnPropertySymbols()