【Node.js24.x】Symbol::toPrimitive定数の使い方

toPrimitive定数は、Node.js環境におけるJavaScriptの組み込みオブジェクトであるSymbolに属する定数であり、オブジェクトがプリミティブ値（例えば、文字列、数値、真偽値など）に変換される際の振る舞いをカスタマイズするために用いられます。この定数は、任意のオブジェクトに[Symbol.toPrimitive]という名前のメソッドを定義することで利用され、オブジェクトがプリミティブ値へ変換される際の優先的なロジックを提供します。

JavaScriptのオブジェクトは、算術演算や文字列連結といった文脈において、自動的にプリミティブ値への変換が必要となることがあります。通常、このような変換が行われる際には、オブジェクトが持つvalueOf()メソッドやtoString()メソッドが呼び出されます。しかし、[Symbol.toPrimitive]メソッドがオブジェクトに実装されている場合、これらの既存のメソッドよりも先に呼び出され、変換処理の制御を優先的に担います。

[Symbol.toPrimitive]メソッドは、変換先のプリミティブ値の型を示す「ヒント」を引数として受け取ります。このヒントは、"number"（数値への変換を期待）、"string"（文字列への変換を期待）、または"default"（特定の型に限定されない、またはデフォルトの変換を期待）のいずれかです。開発者は、このヒントに基づいて、オブジェクトを最も適切と思われるプリミティブ値に変換して返すロジックを実装できます。これにより、オブジェクトを様々な文脈で利用する際に、より意図した通りの、予測可能な変換動作を実現することが可能になります。

Copy
1const myObject = {
2  value: 42,
3  [Symbol.toPrimitive](hint) {
4    if (hint === 'number') {
5      return this.value;
6    }
7    if (hint === 'string') {
8      return `Object with value ${this.value}`;
9    }
10    // 'default' hint
11    return String(this.value);
12  }
13};

引数なし

引数はありません

symbol

Symbol.toPrimitive は、オブジェクトがプリミティブ値に変換される際に、どのように変換されるかを定義するための特殊なシンボルです。このシンボルに紐づけられたメソッドは、オブジェクトのプリミティブ表現を返すシンボルを戻り値として生成します。