const sym1 = Symbol();
const sym2 = Symbol("foo");
const sym3 = Symbol("foo");

The above code creates three new Symbols. Note that Symbol("foo") does not coerce the string "foo" into a Symbol. It creates a new Symbol each time:

Symbol("foo") === Symbol("foo"); / false

The following syntax with the TypeError:

const sym = new Symbol(); / TypeError

This prevents authors from creating an explicit Symbol wrapper object instead of a new Symbol value and might be surprising as creating explicit wrapper objects around primitive data types is generally possible (for example, new Boolean, new String and new Number).

If you really want to create a Symbol wrapper object, you can use the Object() function:

const sym = Symbol("foo");
typeof sym; / "symbol"
const symObj = Object(sym);
typeof symObj; / "object"

Because symbols are the only primitive data type that has reference identity (that is, you cannot create the same symbol twice), they behave like objects in some way. For example, they are garbage collectable and can therefore be stored in FinalizationRegistry objects.

Note that the "global Symbol registry" is only a fictitious concept and may not correspond to any internal data structure in the JavaScript engine — and even if such a registry exists, its content is not available to the JavaScript code, except through the for() and keyFor() methods.

The method Symbol.for(tokenString) takes a string key and returns a symbol value from the registry, while Symbol.keyFor(symbolValue) takes a symbol value and returns the string key corresponding to it. Each is the other's inverse, so the following is true:

Symbol.keyFor(Symbol.for("tokenString")) === "tokenString"; / true

Because registered symbols can be arbitrarily created anywhere, they behave almost exactly like the strings they wrap. Therefore, they are not guaranteed to be unique and are not garbage collectable. Therefore, registered symbols are disallowed in FinalizationRegistry objects.

Prior to well-known Symbols, JavaScript used normal properties to implement certain built-in operations. For example, the String function will call the object's toString() and valueOf() methods. However, as more operations are added to the language, designating each operation a "magic property" can break backward compatibility and make the language's behavior harder to reason with. Well-known Symbols allow the customizations to be "invisible" from normal code, which typically only read string properties.

Well-known symbols do not have the concept of garbage collectability, because they come in a fixed set and are unique throughout the lifetime of the program, similar to intrinsic objects such as Array.prototype, so they are also allowed in FinalizationRegistry objects.

Symbol.asyncIterator

A method that returns the default AsyncIterator for an object. Used by for await...of.

Symbol.hasInstance

A method determining if a constructor object recognizes an object as its instance. Used by instanceof.

Symbol.isConcatSpreadable

A Boolean value indicating if an object should be flattened to its array elements. Used by Array.prototype.concat().

Symbol.iterator

A method returning the default iterator for an object. Used by for...of.

Symbol.match

A method that matches against a string, also used to determine if an object may be used as a regular expression. Used by String.prototype.match().

Symbol.matchAll

A method that returns an iterator, that yields matches of the regular expression against a string. Used by String.prototype.matchAll().

Symbol.replace

A method that replaces matched substrings of a string. Used by String.prototype.replace().

Symbol.search

A method that returns the index within a string that matches the regular expression. Used by String.prototype.search().

Symbol.species

A constructor function that is used to create derived objects.

Symbol.split

A method that splits a string at the indices that match a regular expression. Used by String.prototype.split().

Symbol.toPrimitive

A method converting an object to a primitive value.

Symbol.toStringTag

A string value used for the default description of an object. Used by Object.prototype.toString().

Symbol.unscopables

An object value of whose own and inherited property names are excluded from the with environment bindings of the associated object.

Symbol.prototype.constructor

The constructor function that created the instance object. For Symbol instances, the initial value is the Symbol constructor.

Symbol.prototype.description

A read-only string containing the description of the Symbol.

Symbol.prototype[Symbol.toStringTag]

The initial value of the Object.prototype.toString.call() with a symbol as thisArg.

• When trying to convert a Symbol to a number, a TypeError will be thrown (e.g., +sym or sym | 0).
• When using loose equality, Object(sym) == sym returns true.
• Symbol("foo") + "bar" throws a TypeError (can't convert Symbol to string). This prevents you from silently creating a new string property name from a Symbol, for example.
• The Symbol.prototype.toString() with Symbols, but note that new String(sym) will throw.

JSON.stringify({ [Symbol("foo")]: "foo" });
/ '{}'

For more details, see JSON.stringify().