Symbol.toPrimitive vs Object.prototype.valueOf

Question

In ECMAScript 6, a new Symbol.toPrimitive symbol is introduced, which, when used as an object key, should define a function to return the primitive value of an object:

let object = {     aNumber: 0,     [Symbol.toPrimitive]() {         return this.aNumber;     } };  object.aNumber = 5; console.log(object + 2) // 7 

However, there is also the Object.prototype.valueOf function, which, according to the documentation, could be redefined to convert an object to the primitive value:

let object = {     aNumber: 0,     valueOf() {         return this.aNumber;     } };  object.aNumber = 5; console.log(object + 2) // 7 

So, which of these ways to convert an object to its primitive value should be used in ES6 when defining a new object?

Answer 1

The main purpose of Symbol.toPrimitive is to change the order in which toString and valueOf are called in different coercion scenarios.

An example of this is the Date native object, where it will convert the value to a string instead of a number by default:

console.log(1 + new Date()); // "1Mon Aug 15 2016 13:25:31 GMT-0500 (EST)"  var a = new Date(1000); console.log(a == 1000); // false console.log(a == a.toString()); // true 

If you do not intend to do this, you should just override both obj.valueOf and obj.toString to match the behaviour that you want -- this is what most of the native objects do in JavaScript.

Note that both valueOf and toString should be overridden, as the ToPrimitive abstract operation may call either of them for coercion depending on the reason ToPrimitive is being called.