Awesome
Symbol Predicates Proposal
Status
Stage 2
Champions: Ashley Claymore, Jordan Harband
Authors: Robin Ricard, Ashley Claymore, Jordan Harband
Motivation
A proposal to introduce ways to differentiate symbols.
This proposal adds the following predicates:
Symbol.isRegistered(symbol)
Symbol.isWellKnown(symbol)
Not all symbols are the same and knowing more about what they are can be useful, notably for libraries.
Knowing if a symbol is truly unique, is forgeable (registered) or is shared across realms (well-known), can be important depending on the use case.
For instance Symbols as WeakMap keys require symbols to not be registered.
Use Cases
You can detect in a library if a symbol can be used as a WeakMap key:
function isWeakMapKey(key) {
switch (typeof key): {
case "object":
return key !== null;
case "function":
return true;
case "symbol":
return !Symbol.isRegistered(sym);
}
return false;
}
isWeakMapKey({}); // true
isWeakMapKey(Symbol()); // true
isWeakMapKey("foo"); // false
isWeakMapKey(Symbol.for("foo")); // false
isWeakMapKey(Symbol.asyncIterator); // true
You can also find out if you are being given a truly unique symbol:
const isUniqueSymbol = sym => typeof sym === "symbol" && !(Symbol.isRegistered(sym) || Symbol.isWellKnown(sym));
isUniqueSymbol(Symbol()); // true
isUniqueSymbol(Symbol.for("foo")); // false
isUniqueSymbol(Symbol.asyncIterator); // false
isUniqueSymbol({}); // false
Description
Symbol.isRegistered(value)
Takes an unknown value as the only argument, returns a boolean: true
if the symbol is registered, false
otherwise.
Symbol.isWellKnown(value)
Takes an unknown value as the only argument, returns a boolean: true
if the symbol is one of the well known symbols as defined by ECMA262 & ECMA402, false
otherwise.
Implementations
Note that the two predicate packages belo are not polyfills; but they precisely match the current spec text, so they represent valid implementations of the proposal.
Symbol.isRegistered(symbol)
: https://github.com/inspect-js/is-registered-symbolSymbol.isWellKnown(symbol)
: https://github.com/inspect-js/is-well-known-symbol
Maintain the proposal repo
- Make your changes to
spec.emu
(ecmarkup uses HTML syntax, but is not HTML, so I strongly suggest not naming it ".html") - Any commit that makes meaningful changes to the spec, should run
npm run build
and commit the resulting output. - Whenever you update
ecmarkup
, runnpm run build
and commit any changes that come from that dependency.