【JavaScript】 オブジェクトで直接計算させるSymbol.toPrimitiveでプリミティブ変換

JavaScriptの全てのオブジェクトは[Symbol.toPrimitive]という特殊なプロパティを指定することができます。

このプロパティを使用すると、オブジェクトそのものを値として算術演算などおこなうことができます。

JavaScriptでは計算をするときなど、状況によってはオブジェクトをプリミティブ値に変換します。
その際、[Symbol.toPrimitive]を参照します。

[Symbol.toPrimitive]でプリミティブに変換

オブジェクトに、Symbol.toPrimitiveプロパティを定義すると、オブジェクトをプリミティブに変換できます。

例えば次のように、Symbol.toPrimitiveプロパティを定義したオブジェクトがあるとします。

const obj = {
    num : 1000,
    [Symbol.toPrimitive]:function(){
        return this.num;
    }
};

このオブジェクトは、次のようにオブジェクト名で演算することができます。

console.log( 123 + obj ); // 1123

つまり、Symbol.toPrimitiveプロパティで、obj を 1000という数値プリミティブに変換したのです。

[Symbol.toPrimitive]が定義されていないケース

通常のオブジェクトには[Symbol.toPrimitive]が定義されていません。

このようなケースでは、toStringメソッドとvalueOfメソッドが順番に呼び出されます。
呼び出される順番は状況により変化しますが、概ね、文字列が必要なときはtoStringが、数値が必要な時はvalueOfが先に呼び出されます。

なお、メソッド呼び出しの結果がオブジェクトでないとき、値が有効になります。
通常オブジェクトのvalueOf実行結果は、自分自身なのでオブジェクトです。
そのため、toStringの結果がプリミティブ値として採用されます。

console.log( { }.toString() );  // "[object Object]" ← 文字列
console.log( { }.valueOf() );  //  { } ← オブジェクト

次のようにオブジェクトを演算対象にすると、奇妙な文字列が表示されるのは、このような処理をおこなっているからです。

console.log( "" + { } ); // "[object Object]"

Symbol.toPrimitiveプロパティは、この規定値を上書きしているわけです。

Symbol.toPrimitiveプロパティは、引数を一つ受け付ける関数をセットします。

{
    [Symbol.toPrimitive]:function( hint ){ }
}

引数hintは、次の文字列のうちどれかです。

これらの値を使用した場合、次のようなコードになります。

const obj = {
    num : 1000,
    text : "abcde",
    default : Symbol("default"),
    [Symbol.toPrimitive]:function(hint){
        switch ( hint ){
            case "number": return this.num;
            case "string": return this.text;
            default: return this.default;
        }
    }
};

このオブジェクトは、hintが"number"のときは1000を、"string"のときは"abcde"を、"default"のときはシンボル値を返しています。

このオブジェクトを使って計算してみます。

console.log( 500 - obj ); // -500
console.log(  obj / 2 ); // 500
console.log(  obj % 3 ); // 1

数値演算のためhintの値が"number"でした。
そのため500がリターンされ、その値で計算が続行されました。
この動作は容易に想像できます。

しかし + 演算子は注意が必要です。

console.log( 123 + obj );
  // TypeError: can't convert symbol to number

「シンボルが数値に変換できない」というエラーが表示されてしまいました。
つまり、hintの値が"number"でなく、"default"だったため、シンボル値をリターンしたのです。

+ 演算子は加算だけでなく、文字列の連結にも使用されます。
優先度が特に決まっていないため、hintは"default"が使用されるのです。

そして、+ 演算子は、その左右のどちらかが文字列なら、連結されます。
両方文字列でないときは、値を数値に変換してから計算されます。

しかしJavaScriptの仕様上、シンボルは数値に変換できません。
そのため上述のエラーが表示されるのです。

hintとして"number"と"string"を受け取れることから、次のような結果を期待すると思います。

残念ながら、このようなことはできません。
個人的には、とても残念です。

JavaScriptの関数の中には、引数として受け取ったオブジェクトを内部でプリミティブに変換するものがあります。

概要

例えば、文字列引数を数値に変換するparseIntという関数は、その一つです。
parseIntは、数値として判定できない文字列のとき、NaNを返します。

console.log( parseInt( "12345")  );  // 12345
console.log( parseInt( "abced")  );  // NaN
console.log( parseInt( true )  );  // NaN
console.log( parseInt( { } )  );  // NaN

実際には数値変換の前に、引数を文字列に変換しています。
そのため、引数に数値を渡すことができます。

console.log( parseInt( 12345 )  );  // 12345 ← 12345 ⇒ "12345" ⇒ 12345

同様に、オブジェクトも文字列に変換されます。
しかし通常のオブジェトを変換すると"[object Object]"という文字列になり、数値と判定できないため、parseIntの結果がNaNになるのです。

Symbol.toPrimitiveプロパティで数値や数値文字列を返すと、parseIntで変換することが可能になります。

const obj = {
    [Symbol.toPrimitive]:function(){
        return 12345;
    }
}
console.log( parseInt(obj) ); // 12345

JavaScriptはparseIntの他にも、内部でプリミティブ変換しているものが多数あります。

その際、hintに"default"以外のものが指定されるものを、いくつか挙げてみます。

なお実際に使用するときは、console出力やデバッガでどんなhintが与えられるのかを確認してください。

"number"が指定される関数

一部の関数は、次の例のように[Symbol.toPrimitive]関数が呼び出され、その関数の引数として"number"が渡されます。

const obj2 = {
    [Symbol.toPrimitive]:function(hint){
        switch ( hint ){
            case "number": return 1;
            case "string": return "abcde";
            default: return "abcde";
        }
    }
}
console.log( isFinite(1) ); // true
console.log( isFinite("abcde") ); // false
console.log( isFinite(obj2) );  // false

同様な関数の一部をリストアップします。

"string"が指定される関数

一部の関数は[Symbol.toPrimitive]関数が呼び出され、その関数の引数として"string"が渡されます。
その一部をリストアップします。

比較演算で[Symbol.toPrimitive]プリミティブを使用する場合、注意が必要です。

厳密な比較の場合

[Symbol.toPrimitive]プロパティは、厳密な比較（ === , !== ) では呼び出されません。

厳密な比較は型のチェックをおこなうので、プリミティブとの比較は問答無用でfalseです。

const obj = {
    [Symbol.toPrimitive]:()=>5
};
console.log( obj == 5 ); // false ← Object と Number型との比較

オブジェクトの比較は、同じオブジェクトかどうかがチェックされます。
そのため、プリミティブに変換されません。

const obj1 = {  [Symbol.toPrimitive]:()=>5 };
const obj2 = {  [Symbol.toPrimitive]:()=>5 };
console.log( obj1 === obj2 ); // false ← 内容ではなく同じオブジェクトかどうか

厳密でない比較の場合

厳密でない比較（ == , != ) は、[Symbol.toPrimitive]プロパティが呼び出されるケースと、呼び出されないケースがあります。

呼び出されないケース

オブジェクト同士を比較した場合、同じオブジェクトかどうかがチェックされます。
そのため、プリミティブに変換されません。

const obj1 = {  [Symbol.toPrimitive]:()=>5 };
const obj2 = {  [Symbol.toPrimitive]:()=>5 };
console.log( obj1 == obj2 ); // false ← 内容ではなく同じオブジェクトかどうか

呼び出されるケース

比較対象の一方がオブジェクトで、もう一方が文字列、数値、長整数、シンボルのいずれかの場合、オブジェクトがプリミティブに変換されます。

const obj1 = {  [Symbol.toPrimitive]:()=>5 };
console.log( obj1 == 5 ); // true

このとき、hintは"default"が渡されます。

関係演算子の場合

関係演算子( < 、>、 <=、 >=）は、一方、または両方ともオブジェクトのとき、オブジェクトがプリミティブに変換されます。

const obj1 = {  [Symbol.toPrimitive]:()=>5 };
const obj2 = {  [Symbol.toPrimitive]:()=>6 };
console.log( obj1 > obj2 ); // false

このとき、hintは"number"が渡されます。