Symbol es un objeto incorporado cuyo constructor devuelve unsymbolprimitivo — también llamadoSymbol value o simplementeSymbol — que está garantizado que sea único. Los Symbols se utilizan a menudo para añadir claves de propiedades únicas a un objeto que no sean iguales a las claves que cualquier otro código pueda añadir al objeto, y que están ocultas de cualquier mecanismo que otro código utilice normalmente para acceder al objeto. Esto permite una forma deencapsulation débil, o una forma débil deocultación de información.

Se garantiza que cada llamada aSymbol() devuelve un único Symbol. Cada llamada aSymbol.for("key") devolverá siempre el mismo Symbol para un valor dado de"key". Cuando se llama aSymbol.for("key"), si se puede encontrar un símbolo con la clave dada en el registro global de símbolos, se devuelve ese Symbol. En caso contrario, se crea un nuevo Symbol, se añade al registro global de Symbols con la clave dada y se devuelve.

Descripción

Para crear un nuevo Símbolo primitivo, se escribeSymbol() 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 queSymbol("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 operadornew lanzará unTypeError:

let sym = new Symbol(); // TypeError

Esto evita que los autores creen un objeto envolvente explícitoSymbol 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 ynew Number).

Si realmente quieres crear un objeto envolventeSymbol, puedes utilizar la funciónObject():

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

Symbols compartidos en el registro global de Symbols

La sintaxis anterior utilizando la funciónSymbol() 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étodosSymbol.for() ySymbol.keyFor() para establecer y recuperar Symbols del registro global de Symbols.

Encontrar las propiedades de los Symbols en los objetos

El métodoObject.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.

Constructor

Symbol()

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

Propiedades estáticas

Symbol.asyncIterator

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

Symbol.hasInstance

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

Symbol.isConcatSpreadable

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

Symbol.iterator

Un método que devuelve el iterador por defecto de un objeto. Utilizado porfor...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 porString.prototype.match().

Symbol.matchAll

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

Symbol.replace

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

Symbol.search

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

Symbol.split

Un método que divide una cadena en los índices que coinciden con una expresión regular. Utilizado porString.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 porObject.prototype.toString().

Symbol.unscopables

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

Métodos estáticos

Symbol.for(key)

Busca los Symbols existentes con lakey 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.

Propiedades de instancias

Symbol.prototype.description

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

Métodos de instancia

Symbol.prototype.toString()

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

Symbol.prototype.valueOf()

Devuelve el Symbol. Anula el métodoObject.prototype.valueOf().

Symbol.prototype[@@toPrimitive]

Devuelve el Symbol.

Ejemplos

Uso del operador typeof con Symbols

El operadortypeof puede ayudarle a identificar los Symbols.

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

Conversiones de tipos de Symbols

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á unTypeError.(e.g.+sym orsym | 0).
• Cuando se utiliza la igualdad suelta,Object(sym) == sym devuelvetrue.
• Symbol("foo") + "bar" lanza unTypeError (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 aSymbol.prototype.toString() con Symbols, pero ten en cuenta quenew String(sym) será lanzado.

Iteración de Symbols y for...in

Los Symbols no son enumerables en las iteracionesfor...in. Además,Object.getOwnPropertyNames() no devolverá las propiedades del objeto Symbol, sin embargo, puede utilizarObject.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"}

Symbols y JSON.stringify()

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

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

Para más detalles, consulteJSON.stringify().

Objetos envolventes de Symbols como claves de propiedades

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]; // 1obj[Object(sym)]; // sigue siendo 1

Especificaciones

Compatibilidad con navegadores

Véase también

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