CKTIS / JavaScript
Symbol.toPrimitive — conversão personalizada de objeto para primitivo
Symbol.toPrimitive é um símbolo conhecido que identifica o método de conversão de um objeto num valor primitivo. O método recebe a indicação "string", "number" ou "default" e tem precedência sobre a utilização habitual de valueOf() e toString().
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
const value = { [Symbol.toPrimitive](hint) { return hint === "string" ? "label" : 10; } };Symbol.toPrimitive é um símbolo utilizado como chave de método, não uma função de conversão. Define [Symbol.toPrimitive](hint) { ... } para controlar a conversão de um objeto num valor primitivo. O método é chamado com o objeto a converter como this.
O argumento hint é "string" para String(obj), "number" para Number(obj) e "default" na adição em obj + 3. A indicação não impõe o tipo do resultado: o método tem de devolver um valor primitivo, que a operação envolvente pode converter novamente. Devolver um objeto lança TypeError, sem tentar valueOf() nem toString().
Se a propriedade tiver o valor undefined ou null, aplica-se a conversão habitual: com uma indicação de cadeia de caracteres, tenta-se primeiro toString() e depois valueOf(); com uma indicação numérica, a ordem é inversa. Sem indicação, a conversão habitual dá preferência ao número. Qualquer outro valor não invocável da propriedade lança TypeError.
No exemplo, String(amount) produz Amount(7), Number(amount) produz 7 e amount + 3 produz 10. Trata deliberadamente as três indicações para evitar resultados inesperados com o operador +.
Exemplos
const amount = {
value: 7,
[Symbol.toPrimitive](hint) {
if (hint === "string") return `Amount(${this.value})`;
return this.value;
}
};
console.log(String(amount));
console.log(Number(amount));
console.log(amount + 3);Resultado
Amount(7) 7 10
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.