.JS File Format – Types

Well-known symbols

ToPrimitive

ToPrimitive(input, preferredType) returns non-objects as they are. For an object, it asks the object for a primitive, using a hint of "string", "number" or "default":

1. If the object has a Symbol.toPrimitive method, it is called with the hint. The result is returned if it is not an object; otherwise a TypeError is thrown.
2. Otherwise OrdinaryToPrimitive runs, with "default" treated as "number". For hint "string" it tries toString then valueOf; for hint "number" it tries valueOf then toString. The first that returns a non-object wins, and if neither does, a TypeError is thrown.

const money = {
  [Symbol.toPrimitive](hint) {
    return hint === 'string' ? '£5.00' : 5;
  },
};
`${money}`;   // "£5.00"  (hint "string")
money * 2;    // 10       (hint "number")
money + 1;    // 6        (hint "default")

ToBoolean

These values are falsy, and everything else is truthy, including "0", [] and {}:

ToNumber and ToNumeric

A string is trimmed of white space and line terminators. An empty result gives 0. Otherwise the text must be a decimal literal, optionally signed, or 0x, 0o or 0b digits, or Infinity with an optional sign; anything else gives NaN. Numeric separators and the n suffix are not accepted, nor is a sign before the prefixed forms, so Number('-0x10') is NaN. parseInt and parseFloat follow looser rules and ignore trailing text.

ToNumeric is ToNumber except that a BigInt stays a BigInt. It is what arithmetic operators use.

ToString

Other conversions

Integer conversions

ToInt32, ToUint32, ToInt16, ToUint16, ToInt8, ToUint8 and ToUint8Clamp reduce a number to a fixed-size integer. NaN and ±Infinity become 0, and the value is truncated. Only ToUint8Clamp clamps and rounds, rounding halves to even; the others wrap modulo the size.

2 ** 32 | 0;        // 0   (ToInt32 wraps)
-1 >>> 0;           // 4294967295   (ToUint32)
~~3.7;              // 3   (truncation through ToInt32)

Strict equality

Values of different types are never equal. For two Numbers, the comparison is numeric, with the NaN and zero rules above. For two BigInts it is mathematical, two Strings compare code unit by code unit, and two Objects are equal only if they are the same object.

Loose equality

x == y works through these steps (IsLooselyEqual):

1. If the types are the same, return the strict result.
2. If one is null and the other undefined, return true.
3. (Annex B) If one is an object with [[IsHTMLDDA]] and the other is null or undefined, return true.
4. If one is a Number and the other a String, convert the string with ToNumber and compare.
5. If one is a BigInt and the other a String, convert the string to a BigInt; if that fails return false, otherwise compare.
6. If one is a Boolean, convert it with ToNumber and compare again.
7. If one is an Object and the other a String, Number, BigInt or Symbol, convert the object with ToPrimitive and compare again.
8. If one is a BigInt and the other a Number, compare them mathematically; NaN and the infinities are never equal to a BigInt.
9. Otherwise return false.

0 == '';                // true    (ToNumber("") is 0)
'' == '0';              // false   (both strings)
null == 0;              // false   (null equals only undefined)
[1] == 1;               // true    (ToPrimitive gives "1")
[] == false;            // true    (both reach 0)
NaN == NaN;             // false

Relational comparison

<, >, <= and >= use IsLessThan. Each operand goes through ToPrimitive with hint "number". If both are strings, they compare by code unit. Otherwise they compare numerically, with a BigInt and a string compared by converting the string; NaN, or a string that cannot convert, makes the comparison false. >= is therefore not simply the opposite of <.