Symbol

Para crear un nuevo Símbolo primitivo, se escribe Symbol() con una cadena opcional como descripción:

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

El código anterior crea tres nuevos símbolos. Tenga en cuenta que Symbol("foo") no coacciona la cadena "foo" en un Symbol. Crea un nuevo Symbol cada vez:

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

La siguiente sintaxis con el operador new lanzará un TypeError:

let sym = new Symbol(); // TypeError

Esto evita que los autores creen un objeto envolvente explícito Symbol en lugar de un nuevo valor Symbol y podría ser sorprendente ya que la creación de objetos envolventes explícitos alrededor de tipos de datos primitivos es generalmente posible (por ejemplo, new Boolean, new String y new Number).

Si realmente quieres crear un objeto envolvente Symbol, puedes utilizar la función Object():

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

La sintaxis anterior utilizando la función Symbol() no creará un Symbol global que esté disponible en toda su base de código. Para crear Symbols disponibles en todos los archivos e incluso en todos los ámbitos (cada uno de los cuales tiene su propio ámbito global), utilice los métodos Symbol.for() y Symbol.keyFor() para establecer y recuperar Symbols del registro global de Symbols.

El método Object.getOwnPropertySymbols() devuelve una matriz de Symbols y permite encontrar las propiedades de los Symbols en un objeto determinado. Tenga en cuenta que cada objeto se inicializa sin propiedades Symbol propias, por lo que este array estará vacío a menos que haya establecido propiedades Symbol en el objeto.

Symbol()

Crea un nuevo objeto Symbol. Está incompleto como constructor porque no soporta la sintaxis "new Symbol()".

Symbol.asyncIterator

Un método que devuelve el AsyncIterator por defecto para un objeto. Utilizado por for await...of.

Symbol.hasInstance

Un método que determina si un objeto constructor reconoce un objeto como su instancia. Utilizado por instanceof.

Symbol.isConcatSpreadable

Un valor booleano que indica si un objeto debe ser convertido a sus elementos de matriz. Utilizado por Array.prototype.concat().

Symbol.iterator

Un método que devuelve el iterador por defecto de un objeto. Utilizado por for...of.

Symbol.match

Un método que coincide con una cadena, también se utiliza para determinar si un objeto puede ser utilizado como una expresión regular. Utilizado por String.prototype.match().

Symbol.matchAll

Un método que devuelve un iterador, que devuelve las coincidencias de la expresión regular con una cadena. Utilizado por String.prototype.matchAll().

Symbol.replace

Un método que reemplaza las subcadenas coincidentes de una cadena. Utilizado por String.prototype.replace().

Symbol.search

Un método que devuelve el índice dentro de una cadena que coincide con la expresión regular. Utilizado por String.prototype.search().

Symbol.split

Un método que divide una cadena en los índices que coinciden con una expresión regular. Utilizado por String.prototype.split().

Symbol.species

Una función constructora que se utiliza para crear objetos derivados.

Symbol.toPrimitive

Un método que convierte un objeto en un valor primitivo.

Symbol.toStringTag

Valor de cadena utilizado para la descripción por defecto de un objeto. Utilizado por Object.prototype.toString().

Symbol.unscopables

Un valor de objeto cuyos nombres de propiedades propias y heredadas se excluyen de los enlaces de entorno with del objeto asociado.

Symbol.for(key)

Busca los Symbols existentes con la key dada y los devuelve si los encuentra. En caso contrario, se crea un nuevo Symbol en el registro global de Symbols con la "key".

Symbol.keyFor(sym)

Recupera una clave de Symbol compartida del registro global de Symbols para el Symbol dado.

Symbol.prototype.description

Una cadena de sólo lectura que contiene la descripción del Symbol.

Symbol.prototype.toString()

Devuelve una cadena que contiene la descripción del Symbol. Anula el método Object.prototype.toString().

Symbol.prototype.valueOf()

Devuelve el Symbol. Anula el método Object.prototype.valueOf().

Symbol.prototype[@@toPrimitive]

Devuelve el Symbol.

El operador typeof puede ayudarle a identificar los Symbols.

typeof Symbol() === "symbol";
typeof Symbol("foo") === "symbol";
typeof Symbol.iterator === "symbol";

Algunas cosas a tener en cuenta cuando se trabaja con la conversión de tipo de Symbols.

• Al intentar convertir un Symbol en un número, se producirá un TypeError. (e.g. +sym or sym | 0).
• Cuando se utiliza la igualdad suelta, Object(sym) == sym devuelve true.
• Symbol("foo") + "bar" lanza un TypeError (no se puede convertir Symbol en cadena). Esto impide crear silenciosamente un nuevo nombre de propiedad de cadena a partir de un Symbol, por ejemplo.
• La conversión "más segura" String(sym) funciona como una llamada a Symbol.prototype.toString() con Symbols, pero ten en cuenta que new String(sym) será lanzado.

Los Symbols no son enumerables en las iteraciones for...in. Además, Object.getOwnPropertyNames() no devolverá las propiedades del objeto Symbol, sin embargo, puede utilizar Object.getOwnPropertySymbols() para obtenerlas.

let obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (let i in obj) {
  console.log(i); // imprime en registro "c" y "d"
}

Las propiedades con clave de Symbol serán completamente ignoradas cuando se utilice JSON.stringify():

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

Para más detalles, consulte JSON.stringify().

Cuando se utiliza un objeto envolvente de un Symbol como clave de propiedad, este objeto será coaccionado a su Symbol envolvente:

let sym = Symbol("foo");
let obj = { [sym]: 1 };
obj[sym]; // 1
obj[Object(sym)]; // sigue siendo 1

• Polyfill de Symbol en core-js
• typeof
• Tipos y estructuras de datos
• "ES6 en profundidad: Symbols" en hacks.mozilla.org