CKTIS / JavaScript
Symbol.toPrimitive — conversión personalizada de objeto a primitivo
Symbol.toPrimitive es un símbolo conocido que identifica el método de conversión de un objeto a un valor primitivo. El método recibe la indicación "string", "number" o "default" y tiene prioridad sobre el uso ordinario de valueOf() y toString().
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
const value = { [Symbol.toPrimitive](hint) { return hint === "string" ? "label" : 10; } };Symbol.toPrimitive es un símbolo que se utiliza como clave de método, no una función de conversión. Define [Symbol.toPrimitive](hint) { ... } para controlar la conversión de un objeto a un valor primitivo. El método se invoca con el objeto que se convierte como this.
El argumento hint es "string" para String(obj), "number" para Number(obj) y "default" para la suma en obj + 3. La indicación no impone el tipo del resultado: el método debe devolver un valor primitivo, que la operación que lo rodea puede convertir después. Devolver un objeto provoca TypeError, sin intentar usar valueOf() ni toString().
Si la propiedad tiene el valor undefined o null, se aplica la conversión ordinaria: con una indicación de cadena, primero se prueba toString() y luego valueOf(); con una indicación numérica, se invierte el orden. Si no hay indicación, la conversión ordinaria da preferencia al número. Cualquier otro valor no invocable de la propiedad provoca TypeError.
En el ejemplo, String(amount) produce Amount(7), Number(amount) produce 7 y amount + 3 produce 10. Trata deliberadamente las tres indicaciones para evitar resultados inesperados con el operador +.
Ejemplos
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
El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.