Símbolo

A função Symbol() retorna um valor do tipo símbolo (symbol), tem propriedades estáticas que expõem vários membros dos objetos nativos, possuem métodos estáticos que expõem o registro de símbolos globais e se parecem com uma classe de objeto nativo, mas estão incompletos como construtor porque não suportam a sintaxe "new Symbol()" .

Cada valor símbolo retornado de Symbol() é único. Um símbolo pode ser usado como o identificador para propriedades de objetos; esse é o único propósito do tipo de dado. Algumas explicações sobre propósito e uso podem ser encontradas no verbete do glossário para Symbol.

O tipo de dado símbolo é um tipo de dado primitivo.

Symbol([descrição])

descrição Optional

String opcional. Uma descrição de símbolo no qual pode ser usado para debugar mas não para acessar o próprio símbolo.

Para criar um novo simbolo primitivo, simplesmente escreva Symbol() com uma string opçional para sua descrição:

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

O codigo acima cria três simbolos novos. Note que a função Symbol("foo") não faz a string "foo" ser um símbolo. Ela cria um novo simbolo a cada vez que é chamada:

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

A sintaxe a seguir com o operador new vai resultar em um  TypeError:

var sym = new Symbol(); // TypeError

Isso evita que os autores criem um objeto empacotador explícito de Symbol em vez de um novo valor de símbolo. O que pode surpreender, pois geralmente é possível criar objetos empacotadores explícitos em torno de tipos de dados primitivos (por exemplo, new Boolean, new String e new Number).

Se você realmente quiser criar um objeto empacotador de Symbol , você pode usar a função Object():

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

A sintaxe acima usando a função Symbol() não criará um símbolo global que estará disponível em todo o seu código. Para criar símbolos disponíveis em vários arquivos em um escopo como se fosse global, use os métodos Symbol.for() (en-US) e Symbol.keyFor() (en-US) para definir e configurar símbolos no registro global de símbolo.

O método Object.getOwnPropertySymbols() retorna um array de símbolos e permite que você encontre propriedades de símbolos em um determinado objeto. Observe que cada objeto é inicializado sem suas próprias propriedades de símbolo, de modo que este array estará vazio, a menos que você estabeleça propriedades de símbolo no objeto.

Symbol.length

Propriedade de tamanho cujo valor é 1.

Symbol.prototype (en-US)

Representa o protótipo do Symbol construtor.

Em adição para seus próprios símbolos, JavaScript possui alguns símbolos built-in que representa os comportamentos internos da linguagem que não foram revelados para os desenvolvedores no ECMAScript 5 e anterior. Esses símbolos podem ser acessados usando as seguintes propriedades:

Symbol.hasInstance

Especificado como @@hasInstance. Um método que determina se um construtor de um objeto é reconhecido como a instancia de um objeto. Usado por instanceof.

Symbol.isConcatSpreadable

Especificado como @@isConcatSpreadable. Um valor Booleano indicando se um objeto deve ser adicionado como elemento de uma array. Usado por Array.prototype.concat().

Symbol.isRegExp

Especificado como @@isRegExp. Um valor Booleano indicando se um objeto pode ser usado como uma expressão regular.

Symbol.iterator

Especificado como @@iterator. Um método retornando o iterador padrão para um objeto. Usado por for...of.

Symbol.toPrimitive

Especificado como @@toPrimitive. Um método convertendo um objeto para um valor primitivo .

Symbol.toStringTag

Especificado como @@toStringTag. Um valor string usado para descrição padrão de um objeto. Usado por Object.prototype.toString()

Symbol.unscopables

Especificado como @@unscopables. Uma Array com valores string que são  valores propriedade. Esses são excluídos das ligações com o objeto associado.

Symbol.for(key) (en-US)

Procura por símbolos existentes com as chaves dada e retorna as chaves se for encontradas. Caso contrário um novo símbolo vai ser criado no registro de símbolo global com essa chave.

Symbol.keyFor(sym) (en-US)

Retorna um símbolo compartilhado do registro global de símbolo para o símbolo dado.

Todos os símbolos herdados de Symbol.prototype (en-US).

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')}}

{{page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')}}

O typeof operador pode ajudar a identificar os símbolos.

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

Algumas anotações quando trabalhando com conversão de tipo de símbolos.

• Quando estiver tentando converter um símbolo para um número, um TypeError vai ser retornado.
  (e.g. +sym or sym | 0).
• Quando usando operador de igualdade , Object(sym) == sym retorna true.
• Symbol("foo") + "bar" lança um TypeError (não pode converter um símbolo para string). Isso previne você de silenciamente criar um novo nome de propriedade string a partir de um símbolo, por exemplo.
• A "safer" String(sym) conversion funciona como uma chamada para Symbol.prototype.toString() (en-US) com símbolos, mas note que uma new String(sym) vai ser lançada.

Símbolos não são visíveis em for...in iterações. Além de , Object.getOwnPropertyNames() não retornará o objeto símbolo propriedade, entretante, você pode fazer uso do Object.getOwnPropertySymbols() para conseguir esses resultados.

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"
}

Propriedade com chave de símbolo vão ser completamente ignoradas quando usando JSON.stringify():

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

Para mais detalhes, veja JSON.stringify().

Quando um objeto wrapper de um símbolo é usado como uma chave de propriedade , esse objeto vai ser coerced para o seu símbolo wrapper:

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

• Glossary: Symbol data type
• typeof
• Data types and data structures