4.21 Assignment Operators

An assignment of the form

v = expr

requires v to be classified as a reference (section 4.1) or as an assignment pattern (section 4.21.1). The expr expression is contextually typed (section 4.23) by the type of v, and the type of expr must be assignable to (section 3.11.4) the type of v, or otherwise a compile-time error occurs. The result is a value with the type of expr.

A compound assignment of the form

v ??= expr

where ??= is one of the compound assignment operators

*=   /=   %=   +=   -=   <<=   >>=   >>>=   &=   ^=   |=

is subject to the same requirements, and produces a value of the same type, as the corresponding non-compound operation. A compound assignment furthermore requires v to be classified as a reference (section 4.1) and the type of the non-compound operation to be assignable to the type of v. Note that v is not permitted to be an assignment pattern in a compound assignment.

4.21.1 Destructuring Assignment

A destructuring assignment is an assignment operation in which the left hand operand is a destructuring assignment pattern as defined by the AssignmentPattern production in the ECMAScript 2015 specification.

In a destructuring assignment expression, the type of the expression on the right must be assignable to the assignment target on the left. An expression of type S is considered assignable to an assignment target V if one of the following is true:

• V is variable and S is assignable to the type of V.
• V is an object assignment pattern and, for each assignment property P in V,
  • S is the type Any, or
  • S has an apparent property with the property name specified in P of a type that is assignable to the target given in P, or
  • P specifies a numeric property name and S has a numeric index signature of a type that is assignable to the target given in P, or
  • S has a string index signature of a type that is assignable to the target given in P.
• V is an array assignment pattern, S is the type Any or an array-like type (section 3.3.2), and, for each assignment element E in V,
  • S is the type Any, or
  • S is a tuple-like type (section 3.3.3) with a property named N of a type that is assignable to the target given in E, where N is the numeric index of E in the array assignment pattern, or
  • S is not a tuple-like type and the numeric index signature type of S is assignable to the target given in E.

TODO: Update to specify behavior when assignment element E is a rest element.

In an assignment property or element that includes a default value, the type of the default value must be assignable to the target given in the assignment property or element.

When the output target is ECMAScript 2015 or higher, destructuring variable assignments remain unchanged in the emitted JavaScript code. When the output target is ECMAScript 3 or 5, destructuring variable assignments are rewritten to series of simple assignments. For example, the destructuring assignment

var x = 1;  
var y = 2;  
[x, y] = [y, x];

is rewritten to the simple variable assignments

var x = 1;  
var y = 2;  
_a = [y, x], x = _a[0], y = _a[1];  
var _a;