Traducción en curso

Symbol es un tipo de datos cuyos valores son únicos e immutables. Dichos valores pueden ser utilizados como identificadores (claves) de las propiedades de los objetos.  Cada valor del tipo Symbol tiene asociado un valor del tipo String o Undefined que sirve únicamente como descripción del símbolo.

La función Symbol primitive data type es el constructor de valores del tipo Symbol. Cuando Symbol es llamado como función nos devuelve una nuevo valor del tipo Symbol. El constructor Symbol no debe ser usado con el operador new. Tampoco debe ser extendido mediante clases.

 

Sintaxis

Symbol([description])

Parametros

Descripcion Optional
Es un valor opcional de tipo String. Unicamente sirve como descripción del símbolo que puede ser útil para depurar. No permite el acceso al símbolo que describe.

Descripción

Para crear un nuevo símbolo, simplemente escribimos  Symbol(), opcionalmente  con un argumento de tipo String que constituiría la descripción del símbolo:

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

El código anterior crea tres símbolos nuevos. Hay que destacar que  Symbol("foo") no convierte la cadena "foo" en un símbolo, sino que crea un símbolo nuevo que tiene la misma descripción.

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

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

var sym = new Symbol(); // TypeError

Esto evita la creación de un objeto envolvente explícito de Symbol en lugar de un nuevo valor de tipo símbolo. Si realmente se desea crear un Symbol wrapper object,  podemos usar la función Object():

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

Símbolos compartidos en el registro global de símbolos

La sintaxis anteriormente descrita que usa la función Symbol() no creara un símbolo global disponible para toda el código base. Para crear símmbolos accesibles a través de los archivos incluso a través de realms (cada uno de los cuales tiene su propio global scope) es necesario utilizar los métodos Symbol.for() y Symbol.keyFor() para crear y acceder a los símbolos desde un registro global de valores del tipo Symbol.

Encontrando las claves de tipo símbolo de un objeto

El método Object.getOwnPropertySymbols() devuelve un array con los símbolos que sirven como claves de las propiedades propias de un ojeto. Hay que destacar que cada objeto es inicializado sin propiedades propias con claves de tipo Symbol, así que este array estará vacio a menos que se hayan creado explicitamente propiedades con clave de tipo símbolo en el objeto.

Propiedades

Symbol.length
La propiedad length property cuyo valor es 0 para todos los símbolos.
Symbol.prototype
Representa el prototipo constructor Symbol  Es un objeto ordinario.

Símbolos bien conocidos

JavaScript tiene algunos símbolos incorporados que representan comportamientos internos del lenguaje que no fueron expuestos a los programadoreshich antes de ECMAScript 6. Se accede a los dichos símbolos a través de las siguientes propiedades del constructor Symbol.

Símbolo de iteración

Symbol.iterator
Los objetos que implementen la interfaz Iterable deben tener una propiedad que tenga como clave este símbolo. Dicha propiedad deb ser una función que devuelva un objeto que implemente la interfaz Iterator.  Usado por for...of.

Símbolos de expresiones regulares

Symbol.match
Un método que iguala a un String, también usado para determinar si un objeto puede ser usado como una expresión regular. Usado por String.prototype.match().
Symbol.replace
Un método que reemplaza las subcadenas que coinciden con 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 separa una cadena en los índices que coincide una expresión regular. Utilizado por String.prototype.split().

Otros símbolos

Symbol.hasInstance
Un método que determina si un objeto constructor reconoce al objeto como su instancia. Utilizado por instanceof.
Symbol.isConcatSpreadable
A Boolean value indicating if an object should be flattened to its array elements. Used by Array.prototype.concat().
Symbol.unscopables
An Array of string values that are property values. These are excluded from the with environment bindings of the associated objects.
Symbol.species
A constructor function that is used to create derived objects.
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().

Métodos

Symbol.for(key)
Searches for existing symbols with the given key and returns it if found. Otherwise a new symbol gets created in the global symbol registry with this key.
Symbol.keyFor(sym)
Retrieves a shared symbol key from the global symbol registry for the given symbol.

Symbol prototype

All Symbols inherit from Symbol.prototype.

Propiedades

Symbol.prototype.constructor
Returns the function that created an instance's prototype. This is the Symbol function by default.
Symbol.prototype.description
A read-only string containing the description of the symbol.

Métodos

Symbol.prototype.toSource()
Returns a string containing the source of the Symbol object. Overrides the Object.prototype.toSource() method.
Symbol.prototype.toString()
Returns a string containing the description of the Symbol. Overrides the Object.prototype.toString() method.
Symbol.prototype.valueOf()
Returns the primitive value of the Symbol object. Overrides the Object.prototype.valueOf() method.
Symbol.prototype[@@toPrimitive]
Returns the primitive value of the Symbol object.

Ejemplos

Usando el operador typeof con  symbols

El operador typeof puede ayudar a identificar los Symbol.

typeof Symbol() === 'symbol'
typeof Symbol('foo') === 'symbol'
typeof Symbol.iterator === 'symbol'

Symbol type conversions

Some things to note when working with type conversion of symbols.

  • 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 "safer" String(sym) conversion works like a call to Symbol.prototype.toString() with symbols, but note that new String(sym) will throw.

Symbols y el iterador for...in

Symbols are not visible in for...in iterations. In addition, Object.getOwnPropertyNames() will not return symbol object properties, however, you can use Object.getOwnPropertySymbols() to get these.

var obj = {};

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

for (var i in obj) {
   console.log(i); // logs "c" and "d"
}

Symbols y JSON.stringify()

Symbol-keyed properties will be completely ignored when using JSON.stringify():

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

For more details, see JSON.stringify().

Symbol wrapper objects as property keys

When a Symbol wrapper object is used as a property key, this object will be coerced to its wrapped symbol:

var sym = Symbol("foo");
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1

Especificaciones

Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
La definición de 'Symbol' en esta especificación.
Standard Initial definition

Compatibilidad del navegador

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 38 36.0 (36.0) Sin soporte 25 9
Symbol.iterator (@@iterator) 38 36.0 (36.0) Sin soporte 25 9
Symbol.unscopables (@@unscopables) 38 Sin soporte Sin soporte 25 9
Symbol.match (@@match) Sin soporte 40.0 (40.0) Sin soporte Sin soporte Sin soporte
Symbol.species (@@species) Sin soporte 41.0 (41.0) Sin soporte Sin soporte Sin soporte
Symbol.toPrimitive (@@toPrimitive) Sin soporte 44.0 (44.0) Sin soporte Sin soporte Sin soporte
Other well-known symbols Sin soporte Sin soporte Sin soporte Sin soporte Sin soporte
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support Sin soporte 38 36.0 (36.0) Sin soporte 25 9
Symbol.iterator (@@iterator) Sin soporte 38 36.0 (36.0) Sin soporte 25 9
Symbol.unscopables (@@unscopables) Sin soporte 38 Sin soporte Sin soporte 25 9
Symbol.match (@@match) Sin soporte Sin soporte 40.0 (40.0) Sin soporte Sin soporte Sin soporte
Symbol.species (@@species) Sin soporte Sin soporte 41.0 (41.0) Sin soporte Sin soporte Sin soporte
Symbol.toPrimitive (@@toPrimitive) Sin soporte Sin soporte 44.0 (44.0) Sin soporte Sin soporte Sin soporte
Other well-known symbols Sin soporte Sin soporte Sin soporte Sin soporte Sin soporte Sin soporte

Mira también

Etiquetas y colaboradores del documento

Última actualización por: onit4ku,