+ The following [=IDL fragment=] defines an [=interface=] with an observable array attribute:
+
+
+
+ [Exposed=Window]
+ interface Building {
+ attribute ObservableArray<Employee> employees;
+ };
+
+
+ The behavior of the attribute could be defined like so:
+
+
+ The [=observable array attribute/set an indexed value=] algorithm for
+ Building's employees attribute, given
+ |employee| and |index|, is:
+
+ 1. If |employee| is not allowed to enter the building today, then throw a
+ "{{NotAllowedError}}" {{DOMException}}.
+ 1. If |index| is greater than 200, then throw a "{{QuotaExceededError}}" {{DOMException}}.
+ 1. Put |employee| to work!
+
+ The [=observable array attribute/delete an indexed value=] algorithm for
+ Building's employees attribute, given
+ |employee| and index, is:
+
+ 1. Alert security that |employee| has left the building.
+
+
+ Then, ECMAScript code could manipulate the
employees property in
+ various ways:
+
+
+ // Get an instance of Building.
+ const building = getBuilding();
+
+ building.employees.push(new Employee("A"));
+ building.employees.push(new Employee("B"));
+ building.employees.push(new Employee("C"));
+
+ building.employees.splice(1, 1);
+ const employeeB = building.employees.pop();
+
+ building.employees = [new Employee("D"), employeeB, new Employee("C")];
+
+ building.employees.length = 0;
+
+ // Will throw:
+ building.employees.push("not an Employee; a string instead");
+
+
+ All of these manipulations would pass through the above-defined
+ [=observable array attribute/set an indexed value=] algorithm, potentially throwing if the
+ conditions described there were met. They would also perform the appropriate side effects listed
+ there and in the [=observable array attribute/delete an indexed value=] algorithm.
+
+ Another thing to note about the above code example is how all of the ECMAScript array methods
+ from {{%ArrayPrototype%}} work on the observable array. Indeed, it fully behaves like an
+
Array instance:
+
+
+ const normalArray = [];
+
+ // If building.employees were defined as an indexed property getter interface: normalArray
+ // would contains a single item, building.employees.
+ //
+ // For observable arrays (and frozen arrays): normalArray contains all of the items inside
+ // of building.employees.
+ normalArray.concat(building.employees);
+
+ // names is an ECMAScript Array.
+ const names = building.employees.map(employee => employee.name);
+
+ // Passes various brand checks:
+ console.assert(building.employees instanceof Array);
+ console.assert(Array.isArray(building.employees));
+ console.assert(building.employees.constructor === Array);
+
+ // Even is treated as an array by JSON.stringify!
+ console.assert(JSON.stringify(building.employees) === `["object Employee"]`);
+
+
@@ -13629,6 +13803,250 @@ internal method as follows.
1. Return OrdinaryGetOwnProperty(|O|, |P|).
+Observable array exotic objects
+
+An observable array exotic object is a specific type of ECMAScript
+[=Proxy exotic object=] which is created using the proxy traps defined in this section. They are
+defined in this manner because the ECMAScript specification includes special treatment for
+[=Proxy exotic objects=] that have Array instances as their proxy target, and we want
+to ensure that [=observable array types=] are exposed to ECMAScript code with this special treatment
+intact.
+
+The proxy traps used by observable array exotic objects work to ensure a number of invariants beyond
+those of normal Array instances:
+
+* The arrays have no holes, i.e. every property in the inclusive range 0 through
+ observableArray.length − 1 will be filled with a value compatible with the
+ specified Web IDL type, and no [=array index=] properties will exist outside that range.
+* The property descriptors for important properties cannot be changed from their default
+ configuration; indexed properties always remain as configurable, enumerable, and writable data
+ properties, while the length property remains as a non-configurable,
+ non-enumerable, and writable data property.
+* Adding additional properties to the array cannot be prevented using, for example,
+ Object.preventExtensions().
+
+
+ To create an observable array exotic object
+ in a [=Realm=] |realm|, given Web IDL type |T| and algorithms |setAlgorithm| and |deleteAlgorithm|:
+
+ 1. Let |innerArray| be [=!=] [$ArrayCreate$](0).
+ 1. Let |handler| be [$ObjectCreate$](null, « \[[Type]], \[[SetAlgorithm]], \[[DeleteAlgorithm]], \[[BackingList]] »).
+ 1. Set |handler|.\[[Type]] to |T|.
+ 1. Set |handler|.\[[SetAlgorithm]] to |setAlgorithm|.
+ 1. Set |handler|.\[[DeleteAlgorithm]] to |deleteAlgorithm|.
+ 1. Let |defineProperty| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-defineProperty]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "defineProperty", |defineProperty|).
+ 1. Let |deleteProperty| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-deleteProperty]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "deleteProperty", |deleteProperty|).
+ 1. Let |get| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-get]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "get", |get|).
+ 1. Let |getOwnPropertyDescriptor| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-getOwnPropertyDescriptor]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "getOwnPropertyDescriptor", |getOwnPropertyDescriptor|).
+ 1. Let |has| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-has]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "has", |has|).
+ 1. Let |ownKeys| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-ownKeys]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "ownKeys", |ownKeys|).
+ 1. Let |preventExtensions| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-preventExtensions]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "preventExtensions", |preventExtensions|).
+ 1. Let |set| be [=!=] [$CreateBuiltinFunction$](the steps from [[#es-observable-array-set]], « », |realm|).
+ 1. Perform [=!=] [$CreateDataProperty$](|handler|, "set", |set|).
+ 1. Return [=!=] [$ProxyCreate$](|innerArray|, |handler|).
+
+
+defineProperty
+
+
+ The steps for the defineProperty proxy trap for
+ [=observable array exotic objects=], given |O|, |P|, and |descriptorObj| are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. Let |descriptor| be [=!=] [$ToPropertyDescriptor$](|descriptorObj|).
+ 1. If |P| is "length", then:
+ 1. If [=!=] [$IsAccessorDescriptor$](|descriptor|) is true, then return
+ false.
+ 1. If |descriptor|.\[[Configurable]] is present and has the value true,
+ then return false.
+ 1. If |descriptor|.\[[Enumerable]] is present and has the value true,
+ then return false.
+ 1. If |descriptor|.\[[Writable]] is present and has the value false,
+ then return false.
+ 1. If |descriptor|.\[[Value]] is present, then return the result of
+ [=observable array exotic object/setting the length=] given |handler| and
+ |descriptor|.\[[Value]].
+ 1. Return true.
+ 1. If |P| [=is an array index=], then:
+ 1. If [=!=] [$IsAccessorDescriptor$](|descriptor|) is true, then return
+ false.
+ 1. If |descriptor|.\[[Configurable]] is present and has the value false,
+ then return false.
+ 1. If |descriptor|.\[[Enumerable]] is present and has the value false,
+ then return false.
+ 1. If |descriptor|.\[[Writable]] is present and has the value false,
+ then return false.
+ 1. If |descriptor|.\[[Value]] is present, then return the result of
+ [=observable array exotic object/setting the indexed value=] given |handler|, |P|, and
+ |descriptor|.\[[Value]].
+ 1. Return true.
+ 1. Return [=?=] |O|.\[[DefineOwnProperty]](|P|, |descriptor|).
+
+
+deleteProperty
+
+
+ The steps for the deleteProperty proxy trap for
+ [=observable array exotic objects=], given |O| and |P|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. If |P| is "length", then return false.
+ 1. If |P| [=is an array index=], then:
+ 1. Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. Let |index| be [=!=] [$ToUint32$](|P|).
+ 1. If |index| ≠ |oldLen| − 1, then return
+ false.
+ 1. Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
+ |handler|.\[[BackingList]][|index|] and |index|.
+ 1. [=list/Remove=] the last item from |handler|.\[[BackingList]].
+ 1. Return true.
+ 1. Return [=?=] |O|.\[[Delete]](|P|).
+
+
+get
+
+
+ The steps for the get proxy trap for
+ [=observable array exotic objects=], given |O|, |P|, and |Receiver|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. If |P| is "length", then return |length|.
+ 1. If |P| [=is an array index=], then:
+ 1. Let |index| be [=!=] [$ToUint32$](|P|).
+ 1. If |index| ≥ |length|, then return undefined.
+ 1. Let |esValue| be the result of [=converted to an ECMAScript value|converting=]
+ |handler|.\[[BackingList]][|index|] to an ECMAScript value.
+ 1. Assert: the above step never throws an exception.
+ 1. Return |esValue|.
+ 1. Return [=?=] |O|.\[[Get]](|P|, |Receiver|).
+
+
+getOwnPropertyDescriptor
+
+
+ The steps for the getOwnPropertyDescriptor proxy trap for
+ [=observable array exotic objects=], given |O| and |P|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. If |P| is "length", then return [=!=]
+ [$FromPropertyDescriptor$](PropertyDescriptor{\[[Configurable]]: false,
+ \[[Enumerable]]: false, \[[Writable]]: true,
+ \[[Value]]: |length| }).
+ 1. If |P| [=is an array index=], then
+ 1. Let |index| be [=!=] [$ToUint32$](|P|).
+ 1. If |index| ≥ |length|, then return undefined.
+ 1. Let |esValue| be the result of [=converted to an ECMAScript value|converting=]
+ |handler|.\[[BackingList]][|index|] to an ECMAScript value.
+ 1. Assert: the above step never throws an exception.
+ 1. Return [=!=] [$FromPropertyDescriptor$](PropertyDescriptor{\[[Configurable]]:
+ true, \[[Enumerable]]: true, \[[Writable]]:
+ true, \[[Value]]: |esValue| }).
+ 1. Return [=!=] [$FromPropertyDescriptor$]([=?=] |O|.\[[GetOwnProperty]](|P|)).
+
+
+has
+
+
+ The steps for the has proxy trap for
+ [=observable array exotic objects=], given |O| and |P|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. If |P| is "length", then return true.
+ 1. If |P| [=is an array index=], then:
+ 1. Let |index| be [=!=] [$ToUint32$](|P|).
+ 1. If |index| < |handler|.\[[BackingList]]'s [=list/size=], then return
+ true.
+ 1. Return false.
+ 1. Return [=?=] |O|.\[[HasProperty]](|P|).
+
+
+ownKeys
+
+
+ The steps for the ownKeys proxy trap for
+ [=observable array exotic objects=], given |O|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. Let |keys| be an empty [=list=].
+ 1. Let |i| be 0.
+ 1. [=While=] |i| < |length|:
+ 1. [=list/Append=] [=!=] [$ToString$](|i|) to |keys|.
+ 1. Set |i| to |i| + 1.
+ 1. [=list/Extend=] |keys| with [=!=] |O|.\[[OwnPropertyKeys]]().
+ 1. Return [=!=] [$CreateArrayFromList$](|keys|).
+
+
+preventExtensions
+
+
+ The steps for the preventExtensions proxy trap for
+ [=observable array exotic objects=] are as follows:
+
+ 1. Return false.
+
+
+set
+
+
+ The steps for the set proxy trap for
+ [=observable array exotic objects=], given |O|, |P|, |V|, and |Receiver|, are as follows:
+
+ 1. Let |handler| be the this value.
+ 1. If |P| is "length", then return the result of
+ [=observable array exotic object/setting the length=] given |handler| and |V|.
+ 1. If |P| [=is an array index=], then return the result of
+ [=observable array exotic object/setting the indexed value=] given |handler|, |P|, and |V|.
+ 1. Return [=?=] |O|.\[[Set]](|P|, |V|, |Receiver|).
+
+
+Abstract operations
+
+
+ To set the length
+ of an observable array exotic object given |handler| and |newLen|:
+
+ 1. Let |uint32Len| be [=?=] [$ToUint32$](|newLen|).
+ 1. Let |numberLen| be [=?=] [$ToNumber$](|newLen|).
+ 1. If |uint32Len| ≠ |numberLen|, then throw a {{RangeError}} exception.
+ 1. Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. If |uint32Len| > |oldLen|, then return false.
+ 1. Let |indexToDelete| be |oldLen| − 1.
+ 1. [=While=] |indexToDelete| ≥ |uint32Len|:
+ 1. Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
+ |handler|.\[[BackingList]][|indexToDelete|] and |indexToDelete|.
+ 1. [=list/Remove=] the last item from |handler|.\[[BackingList]].
+ 1. Set |indexToDelete| to |indexToDelete| − 1.
+
+
+
+ To set the indexed value
+ of an observable array exotic object given |handler|, |P|, and |V|:
+
+ 1. Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
+ 1. Let |index| be [=!=] [$ToUint32$](|P|).
+ 1. If |index| > |oldLen|, return false.
+ 1. Let |idlValue| be the result of [=converted to an IDL value|converting=]
+ |V| to the type given by |handler|.\[[Type]].
+ 1. If |index| < |oldLen|, then:
+ 1. Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
+ |handler|.\[[BackingList]][|index|] and |index|.
+ 1. Perform the algorithm steps given by |handler|.\[[SetAlgorithm]], given |idlValue| and
+ |index|.
+ 1. If |index| = |oldLen|, then [=list/append=] |idlValue| to |handler|.\[[BackingList]].
+ 1. Otherwise, set |handler|.\[[BackingList]][|index|] to |idlValue|.
+ 1. Return true.
+
+
Callback interfaces
As described in [[#idl-objects]],