【JavaScript ECMAScript】Proxy::handler.definePropertyインスタンスメソッドの使い方

handler.defineProperty()メソッドは、Proxyオブジェクトに対して、プロパティの定義や変更を制御するトラップを実行するメソッドです。これは、JavaScriptのObject.defineProperty()メソッドがプロキシのターゲットオブジェクトに対して呼び出された際に介入し、その挙動をカスタマイズするために使用されます。

具体的には、オブジェクトに新しいプロパティを追加する操作や、既存のプロパティの属性（例えば、そのプロパティが書き込み可能か、列挙可能か、設定可能か、そしてその値など）を変更する操作を、独自のロジックで制御することができます。これにより、プロパティ定義のセキュリティ制御、バリデーション、または特定の条件下でのみ定義を許可するなどの目的で活用できます。

このメソッドは、target（操作対象となる元のオブジェクト）、property（定義または変更するプロパティの名前）、そしてdescriptor（プロパティの詳細な設定情報を含むオブジェクト）の3つの引数を受け取ります。カスタムロジックの実行後、プロパティの定義操作が成功した場合はtrueを、失敗した場合はfalseを返さなければなりません。

プロパティの定義に関するJavaScriptの標準的なルール（不変条件）は、このトラップが介入しても変わりません。例えば、ターゲットオブジェクトが新しいプロパティの追加を禁止している場合（Object.preventExtensions()など）、このトラップで新しいプロパティを定義することはできません。また、既に存在する非設定可能（configurable: false）なプロパティの属性を変更することもできません。これらの条件に違反した場合、たとえトラップがtrueを返したとしても、JavaScriptエンジンは適切なエラーを発生させます。特に、このトラップがfalseを返した場合、厳格モードではTypeErrorがスローされる点に注意が必要です。これにより、オブジェクトの整合性を保ちながら、柔軟なプロパティ操作の監視や制御が可能になります。

Copy
1new Proxy(target, {
2  defineProperty(target, property, descriptor) {
3    return Reflect.defineProperty(target, property, descriptor);
4  }
5});

target, property, descriptor

• target: object: プロキシ対象のオブジェクト
• property: string | symbol: 追加するプロパティの名前
• descriptor: PropertyDescriptor: プロパティのディスクリプタ

Boolean

Proxy オブジェクトの handler.defineProperty() メソッドは、プロパティが正常に定義されたかどうかを示す真偽値（true または false）を返します。true は成功、false は失敗を示します。