language lawyer - Are JavaScript template literals guaranteed to call toString()?

Question

const num = 42
const str = `My number is ${num}`

In this code what guarantee do I have about the conversion of num to a string ?

Is it guaranteed to just call its toString() method or could the conversion be done in another way ?

Answer 1

Untagged templates use the ECMAScript ToString() abstract operation. The logic of template literal evaluation is spread over several sections which makes it difficult to follow, so I'll just post a link to it: https://tc39.es/ecma262/#sec-template-literals-runtime-semantics-evaluation

ToString(argument) uses a table instead of algorithmic steps, so I'll write out some pseudocode here:

switch (Type(argument)) {
  case 'Undefined':
    return 'undefined';
  case 'Null':
    return 'null';
  case 'Boolean':
    return argument ? 'true' : 'false';
  case 'Number':
    return Number::toString(argument);
  case 'String':
    return argument;
  case 'Symbol':
    throw new TypeError();
  case 'BigInt':
    return BigInt::toString(arugment);
  case 'Object':
    return ToString(ToPrimitive(argument, 'string'));
}

As you can see, no js execution happens at all for primitive values, the engine internally creates a string representation. For objects, we go into the ToPrimitive() algorithm.

ToPrimitive(input, PreferredType) will try to get the Symbol.toPrimitive method from input, and if it's present, call it with the given PreferredType hint. If input does not have a Symbol.toPrimitive property, it falls back to OrdinaryToPrimitive.

OrdinrayToPrimitive(O, hint) will try to call the toString and valueOf methods. If hint is 'string', it try to call toString method first, otherwise it will try to call the valueOf method first. If either of those methods are present and they don't return an object, their return value will be used. If neither are present or they both return objects, a TypeError will be thrown.

So to answer your original question, converting 42 will not call any other methods. The engine will internally create a string representation ('42'), and use that.