Symbol
======

**`Symbol`** es un objeto incorporado cuyo constructor devuelve un `symbol` primitivo — también llamado **Symbol value** o simplemente **Symbol** — 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 de encapsulation débil, o una forma débil de ocultación de información.

Se garantiza que cada llamada a `Symbol()` devuelve un único Symbol. Cada llamada a `Symbol.for("key")` devolverá siempre el mismo Symbol para un valor dado de `"key"`. Cuando se llama a `Symbol.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 escribe `Symbol()` con una cadena opcional como descripción:


```js
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:


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


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


```js
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()`:


```js
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ó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.

### Encontrar las propiedades de los Symbols en los objetos

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.

Constructor
-----------

`Symbol()`

Crea un nuevo objeto `Symbol`. 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 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` (en-US) del objeto asociado.

Métodos estáticos
-----------------

`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.

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étodo `Object.prototype.toString()`.

`Symbol.prototype.valueOf()`

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

`Symbol.prototype[@@toPrimitive]`

Devuelve el Symbol.

Ejemplos
--------

### Uso del operador typeof con Symbols

El operador `typeof` puede ayudarle a identificar los Symbols.


```js
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á 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.
### Iteración de Symbols y for...in

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.


```js
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 utilice `JSON.stringify()`:


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


Para más detalles, consulte `JSON.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:


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

Especificaciones
----------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-symbol-objects |

Compatibilidad con navegadores
------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Véase también
-------------

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