Symbol.keyFor() — Methode · JavaScript-Referenz

Signatur

Symbol.keyFor(sym)

Beschreibung

Symbol.keyFor() ist das Gegenstück zu Symbol.for(): Während Symbol.for(key) ein Symbol im globalen Symbolregister anlegt oder ein vorhandenes abruft, liefert Symbol.keyFor(sym) den Schlüssel-String zu einem solchen registrierten Symbol.

Nützlich ist die Methode vor allem, um festzustellen, ob ein Symbol global geteilt ist (etwa über iframes, Worker-übergreifenden Code oder verschiedene Bibliotheken hinweg), oder um aus einem registrierten Symbol wieder einen serialisierbaren Bezeichner zu gewinnen, z. B. für Logging oder Debugging.

Symbole, die mit Symbol() erzeugt wurden, sowie die sogenannten Well-known Symbols wie Symbol.iterator sind nicht im globalen Register eingetragen – für sie gibt Symbol.keyFor() undefined zurück.

Parameter

Name	Typ	Default	Beschreibung
$sym Pflicht	symbol		Das Symbol, dessen Schlüssel im globalen Symbolregister gesucht werden soll. Muss ein Wert vom Typ `symbol` sein, sonst wird ein `TypeError` geworfen.

Rückgabewert

Typ

string | undefined

Beschreibung

Der Schlüssel-String des Symbols, wenn es über Symbol.for() im globalen Register angelegt wurde; andernfalls undefined.

Beispiele

Schlüssel eines registrierten Symbols abrufen

const appId = Symbol.for('app.id');

console.log(Symbol.keyFor(appId));
console.log(Symbol.for('app.id') === appId);

app.id true

Lokale und Well-known Symbols sind nicht registriert

const lokal = Symbol('app.id');

console.log(Symbol.keyFor(lokal));
console.log(Symbol.keyFor(Symbol.iterator));
// Die Beschreibung ist trotzdem verfügbar:
console.log(lokal.description);

undefined undefined app.id

Prüfen, ob ein Symbol global geteilt ist

const istGlobal = (sym) =>
  typeof sym === 'symbol' && Symbol.keyFor(sym) !== undefined;

const meta = {
  [Symbol.for('lib.version')]: '2.1.0',
  [Symbol('intern')]: true
};

for (const sym of Object.getOwnPropertySymbols(meta)) {
  console.log(sym.toString(), istGlobal(sym) ? 'global' : 'lokal');
}

Symbol(lib.version) global Symbol(intern) lokal

TypeError bei Nicht-Symbol abfangen

try {
  Symbol.keyFor('app.id');
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

TypeError: Wird kein Symbol übergeben (z. B. ein String), wirft die Methode einen TypeError – es erfolgt keine Typumwandlung.
Nicht mit description verwechseln: sym.description liefert die Beschreibung jedes Symbols; Symbol.keyFor() nur den Registerschlüssel. Bei registrierten Symbolen sind beide gleich, bei lokalen liefert keyFor undefined.
Das globale Register ist realm-übergreifend: Ein mit Symbol.for('x') in einem iframe erzeugtes Symbol ist identisch mit dem im Hauptfenster.
Registrierte Symbole werden nie vom Garbage Collector freigegeben und können daher nicht als Schlüssel in WeakMap/WeakRef verwendet werden (ES2023).
Kompatibilität: in allen modernen Browsern und Node.js unterstützt; nicht im Internet Explorer.

Siehe auch

Symbol.for() Symbol Symbol.prototype.description Object.getOwnPropertySymbols() Symbol.iterator arguments[Symbol.iterator]()