Skip to content

Latest commit

 

History

History
1540 lines (973 loc) · 50 KB

hobject-alg-preliminaries.rst

File metadata and controls

1540 lines (973 loc) · 50 KB

Preliminary algorithm work

In this section we look at the internal algorithms and do some preliminary work of restating them by: inlining algorithms, merging algorithms, looking at algorithm behavior with some fixed parameters, etc. Tricky issues of algorithms are also discussed to some extent.

The purpose of this section is to provide raw material for the sections dealing with actual exposed algorithms.

CanPut

[[CanPut]] indicates whether a [[Put]] would cause an error or not. An error is possible in the following cases for object O, property P:

  • O has P as own property, it is a plain property, and [[Writable]] is false
  • O has P as own property, it is an accessor property, and is missing the [[Set]] function
  • P is found in O's prototype chain (not in O), it is a plain property, and either O.[[Extensible]] or property [[Writable]] is false
  • P is found in O's prototype chain (not in O), it is an accessor property, and is missing the [[Set]] function
  • P is not found in O's prototype chain, and O.[[Extensible]] is false

The algorithm in E5 Section 8.12.4 deals with the "own property" case first and then looks up the property again from the prototype chain. If a property is found, the only difference is between steps 2.b and 8.a: the [[Extensible]] property of the original object O must be checked if the property is found in an ancestor, as a [[Put]] would actually go into O, extending its set of properties.

The following simplified (and restated) variant should be equivalent and requires only one prototype chain lookup:

  1. desc = O.[[GetProperty]](P).
  2. If desc is undefined, return O.[[Extensible]].
  3. If IsAccessorDescriptor(desc):
    1. If desc.[[Set]] is undefined, return false.
    2. Else, return true.
  4. Else, desc must be a data descriptor:
    1. (CHANGED:) If desc was not found in the original object O, and O.[[Extensible]] is false, return false.
    2. Return desc.[[Writable]].

The step denoted with CHANGED reconciles steps 2.b and 8.a of the original algorithm. The "found in the original object O" part can be implemented in many ways:

  • Compare object pointers of original object vs. object where property was found: works if an object occurs at most once in a prototype chain (which should always be the case)
  • The prototype chain lookup [[GetProperty]] also returns an "inherited" flag

GetProperty

[[GetProperty]] is a very straightforward wrapper over [[GetOwnProperty]] which follows the prototype chain. Like [[GetOwnProperty]], it returns a descriptor.

There is no exotic behavior for [[GetProperty]], the exotic behaviors only affect [[GetOwnProperty]] which is called during [[GetProperty]].

Original algorithm

  1. Let prop be the result of calling the [[GetOwnProperty]] internal method of O with property name P.
  2. If prop is not undefined, return prop.
  3. Let proto be the value of the [[Prototype]] internal property of O.
  4. If proto is null, return undefined.
  5. Return the result of calling the [[GetProperty]] internal method of proto with argument P.

Eliminating recursion

This is better unwound into a loop (using desc instead of prop, as it is more descriptive):

  1. Let curr be O.
  2. While curr is not null:
    1. Let desc be the result of calling the [[GetOwnProperty]] internal method of curr with property name P.
    2. If desc is not undefined, return desc.
    3. Let curr be the value of the [[Prototype]] internal property of curr.
  3. Return undefined.

Less nested form

The following is a less "nested" form (note that curr is guaranteed to be non-null in the first loop):

  1. Let curr be O.
  2. NEXT: Let desc be the result of calling the [[GetOwnProperty]] internal method of curr with property name P.
  3. If desc is not undefined, return desc.
  4. Let curr be the value of the [[Prototype]] internal property of curr.
  5. If curr is not null, goto NEXT.
  6. Return undefined

Note

A maximum prototype chain depth should be imposed as a safeguard against loops. Note that while it should be impossible to create prototype loops with ECMAScript code alone, creating them from C code is possible.

GetProperty with default GetOwnProperty inlined

[[GetOwnProperty]] is just creating the descriptor from whatever form properties are stored. It has exotic behaviors, so the resulting function is a bit complicated.

The inlined form for default [[GetOwnProperty]] is essentially:

  1. curr = O
  2. NEXT: If curr has own property P:
    1. Let D be a newly created Property Descriptor with no fields.
    2. Let X be curr's own property named P.
    3. If X is a data property, then
      1. Set D.[[Value]] to the value of X's [[Value]] attribute.
      2. Set D.[[Writable]] to the value of X's [[Writable]] attribute.
    4. Else X is an accessor property, so
      1. Set D.[[Get]] to the value of X's [[Get]] attribute.
      2. Set D.[[Set]] to the value of X's [[Set]] attribute.
    5. Set D.[[Enumerable]] to the value of X's [[Enumerable]] attribute.
    6. Set D.[[Configurable]] to the value of X's [[Configurable]] attribute.
    7. Return D.
  3. Let curr be the value of the [[Prototype]] internal property of curr.
  4. If curr is not null, goto NEXT.
  5. Return undefined

This is a relatively useless form, because exotic behaviors are missing.

GetProperty with complete GetOwnProperty inlined

The following inlines [[GetOwnProperty]] with all exotic behaviors:

  1. curr = O
  2. NEXT: Let X be curr's own property named P. If curr doesn't have an own property with name P:
    1. If curr is not a String instance, goto NOTFOUND.
    2. (String object exotic behavior.) Let str be the String value of the [[PrimitiveValue]] internal property of O and len be the number of characters in str.
    3. If P is "length":
      1. Return a Property Descriptor with the values:
        • [[Value]]: len (a primitive number)
        • [[Enumerable]]: false
        • [[Writable]]: false
        • [[Configurable]]: false
    4. If P is an array index (E5 Section 15.4):
      1. Let index be ToUint32(P).
      2. If index < len, return a Property Descriptor with the values:
        • [[Value]]: a primitive string of length 1, containing one character from str at position index (zero based index)
        • [[Enumerable]]: true
        • [[Writable]]: false
        • [[Configurable]]: false
    5. Goto NOTFOUND.
  3. Let D be a newly created Property Descriptor filled as follows:
    1. If X is a data property:
      1. Set D.[[Value]] to the value of X's [[Value]] attribute.
      2. Set D.[[Writable]] to the value of X's [[Writable]] attribute.
    2. Else X is an accessor property:
      1. Set D.[[Get]] to the value of X's [[Get]] attribute.
      2. Set D.[[Set]] to the value of X's [[Set]] attribute.
    3. For either type of property:
      1. Set D.[[Enumerable]] to the value of X's [[Enumerable]] attribute.
      2. Set D.[[Configurable]] to the value of X's [[Configurable]] attribute.
  4. If curr is an arguments object which contains a [[ParameterMap]] internal property:
    1. (Arguments object exotic behavior.) Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined, then:
      1. Set D.[[Value]] to the result of calling the [[Get]] internal method of map passing P as the argument.
  5. Return D.
  6. NOTFOUND: Let curr be the value of the [[Prototype]] internal property of curr.
  7. If curr is not null, goto NEXT.
  8. Return undefined

Note

This implementation is currently not used. The implementation for [[GetOwnProperty]] is a separate helper. See duk_hobject_props.c, helper functions: get_own_property_desc() and get_property_desc().

Get

[[Get]] is straightforward; it gets a property descriptor with [[GetProperty]] and then coerces it to a value.

Get with GetProperty inlined

[[Get]] was covered above when discussion exotic behaviors, so we'll skip discussing it again here.

[[Get]] is essentially a [[GetProperty]] followed by coercion of the descriptor into a value. For a data descriptor, simply return its [[Value]]. For a property accessor, simply call its [[Get]] function. The descriptor does not need to be created at all, as we're just interested in the final value.

The following combines both [[GetOwnProperty]] and [[Get]] with exotic behaviors:

  1. If O is an arguments object which contains a [[ParameterMap]] internal property:
    1. (Arguments object exotic behavior.) Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined:
      1. Return the result of calling the [[Get]] internal method of map passing P as the argument.
  2. curr = O
  3. NEXT: Let X be curr's own property named P. If curr doesn't have an own property with name P:
    1. If curr is not a String instance, goto NOTFOUND.
    2. (String object exotic behavior.) Let str be the String value of the [[PrimitiveValue]] internal property of O and len be the number of characters in str.
    3. If P is "length":
      1. Return len (a primitive number). (No need to check for arguments object exotic behavior or "caller" property exotic behavior.)
    4. If P is an array index (E5 Section 15.4):
      1. Let index be ToUint32(P).
      2. If index < len:
        1. Return a primitive string of length 1, containing one character from str at position index (zero based index). (No need to check for arguments object exotic behavior or "caller" property exotic behavior.)
    5. Goto NOTFOUND.
  4. If X is a data property:
    1. Set res to the value of X's [[Value]] attribute.
    2. Goto FOUND1
  5. Else X is an accessor property:
    1. Let getter be X's [[Get]] attribute.
    2. If getter is undefined:
      1. Return undefined. (Note: arguments object exotic behavior for mapped variables cannot apply: if the property is an accessor, it can never be in the arguments object [[ParameterMap]]. Also, the "caller" exotic behavior does not apply, since the result undefined is not a strict mode function. Thus, no "goto FOUND1" here.)
    3. Else let res be the result of calling the [[Call]] internal method of getter providing O as the this value and providing no arguments.
    4. Goto FOUND2. (Note: arguments object exotic behavior for mapped variables cannot apply: if the property is an accessor, it can never be in the arguments object [[ParameterMap]]. However, the "caller" exotic behavior might apply, at FOUND2.)
  6. FOUND1: If curr is an arguments object which contains a [[ParameterMap]] internal property:
    1. (Arguments object exotic behavior.) Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined, then:
      1. Set res to the result of calling the [[Get]] internal method of map passing P as the argument.
  7. FOUND2: If O is a Function object or an arguments object which contains a [[ParameterMap]] internal property:
    1. (Arguments or Function object exotic behavior.) If P is "caller" and res is a strict mode Function object, throw a TypeError exception.
  8. Return res.
  9. NOTFOUND: Let curr be the value of the [[Prototype]] internal property of curr.
  10. If curr is not null, goto NEXT.
  11. Return undefined. (Note: no need for exotic behavior checks here; e.g. result is not a strict mode function.)

Note

The step 5.c gives the object as the this binding for the getter call. When properties are actually accessed from ECMAScript code, the wrappers (property accessor evaluation, GetValue()) have a different behavior: the primitive (uncoerced) object is given as the this binding.

DefineOwnProperty callers

[[DefineOwnProperty]] is defined in E5 Section 8.12.9. It is a complex algorithm which allows the value and attributes of property P of object O to be changed. It is used for [[Put]] which is performance relevant and should thus be "inlined" to the extent possible (see special case analysis below). It is also used generically when initializing newly created objects etc, which can also use a simplified version.

Note: [[DefineOwnProperty]] allows some counterintuitive property attributes changes to be made. The callers in the specification are supposed to "guard" against these. For instance:

  • A property which is non-configurable but writable can be changed to non-writable (but not vice versa). Non-configurability does not guarantee that changes cannot be made.
  • A property which is configurable but not writable can have its value changed by a [[DefineOwnProperty]] call. This is allowed because a caller could simply change the property to writable, change its value, and then change it back to non-writable (this is possible because the property is configurable). The [[Put]] algorithms prevents writing to a non-writable but configurable property with an explicit check, [[CanPut]].

[[DefineOwnProperty]] is referenced by the following property-related internal algorithms:

  • FromPropertyDescriptor, E5 Section 8.10.4
  • [[Put]], E5 Section 8.12.5
  • Array's exotic [[DefineOwnProperty]] relies on the default one, E5 Section 15.4.5.1
  • Argument object's exotic [[DefineOwnProperty]] relies on the default one, E5 Section 10.6

It is used less fundamentally in many places, e.g. to initialize values (list probably not complete):

  • CreateMutableBinding, E5 Section 10.2.1.2.2
  • Arguments object setup, E5 Section 10.6
  • Array initializer, E5 Section 11.1.4
  • Object initializer, E5 Section 11.1.5
  • Function object creation, E5 Section 13.2
  • [[ThrowTypeError]] function object, E5 Section 13.2.3
  • Object.getOwnPropertyNames, E5 Section 15.2.3.4
  • Object.defineProperty, E5 Section 15.2.3.6
  • Object.seal, E5 Section 15.2.3.8
  • Object.freeze, E5 Section 15.2.3.9
  • Object.keys, E5 Section 15.2.3.14
  • Function.prototype.bind, E5 Section 15.3.4.5
  • Array.prototype.concat, E5 Section 15.4.4.4
  • Array.prototype.slice, E5 Section 15.4.4.10
  • Array.prototype.splice, E5 Section 15.4.4.12
  • Array.prototype.map, E5 Section 15.4.4.19
  • Array.prototype.filter, E5 Section 15.4.4.20
  • String.prototype.match, E5 Section 15.5.4.10
  • String.prototype.split, E5 Section 15.5.4.14
  • RegExp.prototype.exec, E5 Section 15.10.6.2
  • JSON.parse, E5 Section 15.12.2
  • JSON.stringify, E5 Section 15.12.3

DefineOwnProperty for an existing property in Put

This case arises when a [[Put]] is performed and the property already exists. The property value is updated with a call to [[DefineOwnProperty]] with a property descriptor only containing [[Value]]. See E5 Section 8.12.5, step 3.

We can assume that:

  • The property exists (checked by [[Put]])
  • The property is a data property (checked by [[Put]])
  • The property cannot be non-writable (checked by [[Put]], using [[CanPut]])
  • The property descriptor is a data descriptor
  • The property descriptor is of the form: { [[Value]]: val }
  • Because the property exists, the length of an Array object cannot change by a write to an array index; however, a write to "length" may delete array elements

More specifically, we know that in the [[DefineOwnProperty]] algorithm:

  • current is not undefined
  • IsGenericDescriptor(current) is false
  • IsDataDescriptor(current) is true
  • IsAccessorDescriptor(current) is false
  • IsGenericDescriptor(Desc) is false
  • IsDataDescriptor(Desc) is true
  • IsAccessorDescriptor(Desc) is false

Taking the [[DefineOwnProperty]] with all exotic behaviors included, using the above assumptions, eliminating any unnecessary steps, cleaning up and clarifying, we get:

  1. If O is an Array object, and P is "length", then:
    1. Let newLen be ToUint32(Desc.[[Value]]).
    2. If newLen is not equal to ToNumber(Desc.[[Value]]), throw a RangeError exception. Note that this is unconditional (thrown even if Throw is false).
    3. Let oldLenDesc be the result of calling the [[GetOwnProperty]] internal method of O passing "length" as the argument. The result will never be undefined or an accessor descriptor because Array objects are created with a length data property that cannot be deleted or reconfigured.
    4. Let oldLen be oldLenDesc.[[Value]]. (Note that oldLen is guaranteed to be a unsigned 32-bit integer.)
    5. If newLen < oldLen, then:
      1. Let shortenSucceeded, finalLen be the result of calling the internal helper ShortenArray() with oldLen and newLen.
      2. Update the property ("length") value to finalLen.
      3. Goto REJECT, if shortenSucceeded is false.
      4. Return.
    6. Update the property ("length") value to newLen.
    7. Return.
  2. Set the [[Value]] attribute of the property named P of object O to the value of Desc.[[Value]]. (Since it is side effect free to update the value with the same value, no check for that case is needed.)
  3. If O is an arguments object which has a [[ParameterMap]] internal property:
    1. Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined, then:
      1. Call the [[Put]] internal method of map passing P, Desc.[[Value]], and Throw as the arguments. (This updates the bound variable value.)
  4. Return true.

Note that step 1 combines the pre-step and post-step for an Array object length exotic behavior. This is only possible if we know beforehand that the "length" property is writable (so that the write never fails and we always reach the post-step).

We'll refine one more time, by eliminating references to Desc and using val to refer to Desc.[[Value]]:

  1. If O is an Array object, and P is "length", then:
    1. Let newLen be ToUint32(val).
    2. If newLen is not equal to ToNumber(val), throw a RangeError exception. Note that this is unconditional (thrown even if Throw is false).
    3. Let oldLenDesc be the result of calling the [[GetOwnProperty]] internal method of O passing "length" as the argument. The result will never be undefined or an accessor descriptor because Array objects are created with a length data property that cannot be deleted or reconfigured.
    4. Let oldLen be oldLenDesc.[[Value]]. (Note that oldLen is guaranteed to be a unsigned 32-bit integer.)
    5. If newLen < oldLen, then:
      1. Let shortenSucceeded, finalLen be the result of calling the internal helper ShortenArray() with oldLen and newLen.
      2. Update the property ("length") value to finalLen.
      3. Goto REJECT, if shortenSucceeded is false.
      4. Return.
    6. Update the property ("length") value to newLen.
    7. Return.
  2. Set the [[Value]] attribute of the property named P of object O to val. (Since it is side effect free to update the value with the same value, no check for that case is needed.)
  3. If O is an arguments object which has a [[ParameterMap]] internal property:
    1. Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined, then:
      1. Call the [[Put]] internal method of map passing P, val, and Throw as the arguments. (This updates the bound variable value.)
  4. Return true.

We'll need this variant later when creating an inlined version for the full property write processing.

DefineOwnProperty for a non-existent property in Put

This case arises when a [[Put]] is performed and the property does not already exist as an "own property", and no setter in an ancestor captured the write. The property is created with a call to [[DefineOwnProperty]] with a property descriptor containing a [[Value]], and the following set to true: [[Writable]], [[Enumerable]], [[Configurable]]. See E5 Section 8.12.5, step 6.

We can assume that:

  • The property does not exist (checked by [[Put]])
  • The object is extensible (checked by [[Put]])
  • The property descriptor is a data descriptor
  • The property descriptor has the fields:
    • [[Value]]: val
    • [[Writable]]: true
    • [[Enumerable]]: true
    • [[Configurable]]: true
  • If the object is an Array, the property name P cannot be "length" (as that would exist)

More specifically, we know that in the [[DefineOwnProperty]] algorithm:

  • current is undefined

Taking the [[DefineOwnProperty]] with all exotic behaviors included, using the above assumptions, and then eliminating any unnecessary steps, cleaning up and clarifying, we get:

  1. If O is an Array object and P is an array index (E5 Section 15.4), then:
    1. Let oldLenDesc be the result of calling the [[GetOwnProperty]] internal method of O passing "length" as the argument. The result will never be undefined or an accessor descriptor because Array objects are created with a length data property that cannot be deleted or reconfigured.
    2. Let oldLen be oldLenDesc.[[Value]]. (Note that oldLen is guaranteed to be a unsigned 32-bit integer.)
    3. Let index be ToUint32(P).
    4. Goto REJECT if index >= oldLen and oldLenDesc.[[Writable]] is false.
  2. Create an own data property named P of object O whose [[Value]], [[Writable]], [[Enumerable]] and [[Configurable]] attribute values are described by Desc.
  3. If O is an Array object, P is an array index and index >= oldLen:
    1. Update the "length" property of O to the value index + 1. This always succeeds, because we've checked in the pre-step that the "length" is writable, and since P is an array index property, the length must still be writable here.
  4. If O is an arguments object which has a [[ParameterMap]] internal property:
    1. Let map be the value of the [[ParameterMap]] internal property of the arguments object.
    2. If the result of calling the [[GetOwnProperty]] internal method of map passing P as the argument is not undefined, then:
      1. Call the [[Put]] internal method of map passing P, Desc.[[Value]], and Throw as the arguments. (This updates the bound variable value.)
  5. Return true.
  6. REJECT:
    If Throw is true, then throw a TypeError exception, otherwise return false.

This can be refined further by noticing that the arguments object exotic behavior cannot be triggered if the property does not exist: all magically bound properties exist initially, and if they are deleted, the magic variable binding is also deleted.

We can also change the order of property creation and the postponed array length write because they are both guaranteed to succeed.

So, we get:

  1. If O is an Array object and P is an array index (E5 Section 15.4), then:
    1. Let oldLenDesc be the result of calling the [[GetOwnProperty]] internal method of O passing "length" as the argument. The result will never be undefined or an accessor descriptor because Array objects are created with a length data property that cannot be deleted or reconfigured.
    2. Let oldLen be oldLenDesc.[[Value]]. (Note that oldLen is guaranteed to be a unsigned 32-bit integer.)
    3. Let index be ToUint32(P).
    4. If index >= oldLen:
      1. Goto REJECT oldLenDesc.[[Writable]] is false.
      2. Update the "length" property of O to the value index + 1. This always succeeds.
  2. Create an own data property named P of object O whose [[Value]], [[Writable]], [[Enumerable]] and [[Configurable]] attribute values are described by Desc.
  3. Return true.
  4. REJECT:
    If Throw is true, then throw a TypeError exception, otherwise return false.

We'll refine one more time, by eliminating references to Desc and using val to refer to Desc.[[Value]]:

  1. If O is an Array object and P is an array index (E5 Section 15.4), then:
    1. Let oldLenDesc be the result of calling the [[GetOwnProperty]] internal method of O passing "length" as the argument. The result will never be undefined or an accessor descriptor because Array objects are created with a length data property that cannot be deleted or reconfigured.
    2. Let oldLen be oldLenDesc.[[Value]]. (Note that oldLen is guaranteed to be a unsigned 32-bit integer.)
    3. Let index be ToUint32(P).
    4. If index >= oldLen:
      1. Goto REJECT oldLenDesc.[[Writable]] is false.
      2. Update the "length" property of O to the value index + 1. This always succeeds.
  2. Create an own data property named P of object O whose attributes are:
    • [[Value]]: val
    • [[Writable]]: true
    • [[Enumerable]]: true
    • [[Configurable]]: true
  3. Return true.
  4. REJECT: If Throw is true, then throw a TypeError exception, otherwise return false.

Notes:

  • If step 2 fails due to an out-of-memory or other internal error, we may have updated length already. So, switching steps 2 and 1.d.2 might be prudent (the check in step 1.d.1 must be executed before writing anything though).

We'll need this variant later when creating an inlined version for the full property write processing.

DefineOwnProperty for (some) internal object initialization

This case occurs when internal objects or results objects are created by the implementation. We can't simply use a normal property write internally, because we need to set the property attributes to whatever combination is required by the context (many different property attribute variants are used throughout the specification).

Because user code has not had any access to the object, we can narrow down the possibilities a great deal. Here we assume that:

  • Object is extensible
  • Property does not exist
  • Property does not have exotic behavior and is not virtual
  • Property descriptor is a data descriptor, which is fully populated

With these assumptions, eliminating any unnecessary steps, the algorithm is simply:

  1. Create an own data property named P of object O whose [[Value]], [[Writable]], [[Enumerable]] and [[Configurable]] attribute values are described by Desc.
  2. Return true.

This doesn't cover all the initialization cases, but simply illustraes that very constrained cases are very simple.

Put

"Reject" below is shorthand for:

  • If Throw is true, then throw a TypeError exception; else return.

Original algorithm

For object O, property P, and value V:

  1. If the result of calling the [[CanPut]] internal method of O with argument P is false, then
    1. If Throw is true, then throw a TypeError exception.
    2. Else return.
  2. Let ownDesc be the result of calling the [[GetOwnProperty]] internal method of O with argument P.
  3. If IsDataDescriptor(ownDesc) is true, then
    1. Let valueDesc be the Property Descriptor {[[Value]]: V}.
    2. Call the [[DefineOwnProperty]] internal method of O passing P, valueDesc, and Throw as arguments.
    3. Return.
  4. Let desc be the result of calling the [[GetProperty]] internal method of O with argument P. This may be either an own or inherited accessor property descriptor or an inherited data property descriptor.
  5. If IsAccessorDescriptor(desc) is true, then
    1. Let setter be desc.[[Set]] which cannot be undefined.
    2. Call the [[Call]] internal method of setter providing O as the this value and providing V as the sole argument.
  6. Else, create a named data property named P on object O as follows
    1. Let newDesc be the Property Descriptor:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    2. Call the [[DefineOwnProperty]] internal method of O passing P, newDesc, and Throw as arguments.
  7. Return.

Notes:

  • Step 5.a: setter cannot be undefined at this point because [[CanPut]] has checked it (and throws an exception if it is undefined).

Minimizing prototype traversal

The ownDesc check is necessary because a [[Put]] on an existing own property is a change of value; a [[Put]] on an inherited plain property is an addition of a new property on the original target object (not the ancestor where the inherited property was found).

To minimize prototype traversal, these can be combined as follows (with some cleanup):

  1. If the result of calling the [[CanPut]] internal method of O with argument P is false, then Reject.
  2. Let desc be the result of calling the [[GetProperty]] internal method of O with argument P. (Note: here we assume that we also get to know whether the property was found in O or in its ancestor.)
  3. If IsAccessorDescriptor(desc) is true, then:
    1. Call the [[Call]] internal method of desc.[[Set]] providing O as the this value and providing V as the sole argument. (Note: desc.[[Set]] cannot be undefined, as this is checked by [[CanPut]].)
  4. Else if desc was found in O directly (as an "own data property"), then:
    1. Let valueDesc be the Property Descriptor {[[Value]]: V}.
    2. Call the [[DefineOwnProperty]] internal method of O passing P, valueDesc, and Throw as arguments.
  5. Else desc is an inherited data property or undefined, then:
    1. Let newDesc be the Property Descriptor:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    2. Call the [[DefineOwnProperty]] internal method of O passing P, newDesc, and Throw as arguments.
  6. Return.

This still travels the prototype chain twice: once for [[CanPut]], and a second time for the actual [[Put]]. [[CanPut]] can be inlined quite easily, as it does very similar checks as [[Put]].

The result is:

  1. Let desc be the result of calling the [[GetProperty]] internal method of O with argument P. (Note: here we assume that we also get to know whether the property was found in O or in its ancestor.)

  2. If IsAccessorDescriptor(desc) is true, then:

    1. If desc.[[Set]] is undefined, Reject.
    2. Call the [[Call]] internal method of desc.[[Set]] providing O as the this value and providing V as the sole argument.

  3. Else if desc is an inherited (data) property, then:

    1. If O.[[Extensible]] is false, Reject.
    2. If desc.[[Writable]] is false, Reject.
    3. Let newDesc be the Property Descriptor:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    4. Call the [[DefineOwnProperty]] internal method of O passing P, newDesc, and Throw as arguments.

  4. Else if desc was not found (is undefined):

    1. If O.[[Extensible]] is false, Reject.
    2. Let newDesc be the Property Descriptor:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    3. Call the [[DefineOwnProperty]] internal method of O passing P, newDesc, and Throw as arguments.

  5. Else desc was found in O directly (as an "own data property"), then:

    1. If desc.[[Writable]] is false, Reject.
    2. Let valueDesc be the Property Descriptor {[[Value]]: V}.
    1. Call the [[DefineOwnProperty]] internal method of O passing P, valueDesc, and Throw as arguments.

  6. Return.

The above can be further refined to (making also the modification required to [[GetProperty]] explicit):

  1. Let desc and inherited be the result of calling the [[GetProperty]] internal method of O with argument P.

  2. If IsAccessorDescriptor(desc) is true, then:

    1. If desc.[[Set]] is undefined, Reject.
    2. Call the [[Call]] internal method of desc.[[Set]] providing O as the this value and providing V as the sole argument.

  3. Else if desc is not undefined and inherited is false (own data property), then:

    1. If desc.[[Writable]] is false, Reject.
    2. Let valueDesc be the Property Descriptor {[[Value]]: V}.
    1. Call the [[DefineOwnProperty]] internal method of O passing P, valueDesc, and Throw as arguments.
  1. Else desc is an inherited (data) property or undefined:
    1. If O.[[Extensible]] is false, Reject.
    2. If desc is not undefined and desc.[[Writable]] is false, Reject. (In other words: desc was inherited and is non-writable.)
    3. Let newDesc be the Property Descriptor:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    4. Call the [[DefineOwnProperty]] internal method of O passing P, newDesc, and Throw as arguments.
  2. Return.

This can be further improved in actual C code.

Inlining GetProperty

When actually implementing, it's useful to "inline" the [[GetProperty]] loop, which changes the code structure quite a bit:

  1. Set curr to O.

  2. While curr !== null:

    1. If O does not have own property P:

      1. Set curr to curr.[[Prototype]]
      1. Continue (while loop)

    2. Let desc be the descriptor for own property P

    3. If IsDataDescriptor(desc):

      1. If curr != O (property is an inherited data property): (Note: assumes there are no prototype loops.)
        1. If O.[[Extensible] is false, Reject.
        2. If desc.[[Writable]] is false, Reject.
        3. Let newDesc be a property descriptor with values:
          • [[Value]]: V
          • [[Writable]]: true
          • [[Enumerable]]: true
          • [[Configurable]]: true}
        4. Call O.[[DefineOwnProperty]](P, newDesc, Throw).
      2. Else (property is an own data property):
        1. If desc.[[Writable]] is false, Reject.
        2. Let valueDesc be { [[Value]]: V }.
        3. Call O.[[DefineOwnProperty]](P, valueDesc, Throw).
    1. Else (property is an accessor):
      1. If desc.[[Set]] is undefined, Reject.
      2. Call the [[Call]] internal method of desc.[[Set]] providing O as the this value and providing V as the sole argument.
    2. Return.

  3. Property was not found in the prototype chain:

    1. If O.[[Extensible]] is false, Reject.
    2. Let newDesc be a property descriptor with values:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    3. Call O.[[DefineOwnProperty]](P, newDesc, Throw).

Less nested form

The following is a less "nested" form (note that curr is guaranteed to be non-null in the first loop):

  1. Let curr be O.
  2. NEXT: Let desc be the result of calling the [[GetOwnProperty]] internal method of curr with property name P.
  3. If desc is undefined:
    1. Let curr be the value of the [[Prototype]] internal property of curr.
    2. If curr is not null, goto NEXT.
    3. If O.[[Extensible]] is false, Reject.
    4. Let newDesc be a property descriptor with values:
      • [[Value]]: V
      • [[Writable]]: true
      • [[Enumerable]]: true
      • [[Configurable]]: true}
    5. Call O.[[DefineOwnProperty]](P, newDesc, Throw).
    6. Return.
  4. If IsDataDescriptor(desc):
    1. If curr != O (property is an inherited data property): (Note: assumes there are no prototype loops.)
      1. If O.[[Extensible] is false, Reject.
      2. If desc.[[Writable]] is false, Reject.
      3. Let newDesc be a property descriptor with values:
        • [[Value]]: V
        • [[Writable]]: true
        • [[Enumerable]]: true
        • [[Configurable]]: true}
      4. Call O.[[DefineOwnProperty]](P, newDesc, Throw).
    2. Else (property is an own data property):
      1. If desc.[[Writable]] is false, Reject.
      2. Let valueDesc be { [[Value]]: V }.
      3. Call O.[[DefineOwnProperty]](P, valueDesc, Throw).
  5. Else (property is an accessor):
    1. If desc.[[Set]] is undefined, Reject.
    2. Call the [[Call]] internal method of desc.[[Set]] providing O as the this value and providing V as the sole argument.
  6. Return.

Note about PutValue

Note that PutValue() has a [[Put]] variant with two exotic behaviors related to object coercion. The above algorithm does not take those into account.

Property descriptor algorithms

E5 Section 8.10 describes descriptor related algorithms:

  • IsAccessorDescriptor(desc): true, if desc contains either [[Set]] or [[Get]]
  • IsDataDescriptor(desc): true, if desc contains either [[Value]] or [[Writable]]
  • IsGenericDescriptor(desc): true if both IsAccessorDescriptor(desc) and IsGenericDescriptor are false; concretely:
    • desc contains none of the following: [[Set]], [[Get]], [[Value]], [[Writable]]
    • desc may contain: [[Enumerable]], [[Configurable]]

A property descriptor may be fully populated or not. If fully populated, it is either a data descriptor or an access descriptor, not a generic descriptor.

A property descriptor may not be both a data descriptor and access descriptor (this is stated in E5 Section 8.10). However, an argument to e.g. Object.defineProperty() may naturally contain e.g. "set" and "value" keys. In this case:

  • defineProperty() uses ToPropertyDescriptor() to convert the ECMAScript object into an internal property descriptor
  • ToPropertyDescriptor() creates a property descriptor and throws a TypeError if the descriptor contains conflicting fields

ToPropertyDescriptor() also coerces the values in its argument ECMAScript object (e.g. it uses ToBoolean() for the flags). The behavior of ToPropertyDescriptor() is probably easiest to "inline" into wherever it is needed. The E5 specification refers to ToPropertyDescriptor only in Object.defineProperty() and Object.defineProperties().

The current implementation does not have partial internal property descriptors (internal property value and attributes are always fully populated).

ToPropertyDescriptor

The ToPropertyDescriptor() algorithm is specified in E5 Section 8.10.5 and is as follows:

  1. If Type(Obj) is not Object throw a TypeError exception.
  2. Let desc be the result of creating a new Property Descriptor that initially has no fields.
  3. If the result of calling the [[HasProperty]] internal method of Obj with argument "enumerable" is true, then:
    1. Let enum be the result of calling the [[Get]] internal method of Obj with "enumerable".
    2. Set the [[Enumerable]] field of desc to ToBoolean(enum).
  4. If the result of calling the [[HasProperty]] internal method of Obj with argument "configurable" is true, then:
    1. Let conf be the result of calling the [[Get]] internal method of Obj with argument "configurable".
    2. Set the [[Configurable]] field of desc to ToBoolean(conf).
  5. If the result of calling the [[HasProperty]] internal method of Obj with argument "value" is true, then:
    1. Let value be the result of calling the [[Get]] internal method of Obj with argument "value".
    2. Set the [[Value]] field of desc to value.
  6. If the result of calling the [[HasProperty]] internal method of Obj with argument "writable" is true, then:
    1. Let writable be the result of calling the [[Get]] internal method of Obj with argument "writable".
    2. Set the [[Writable]] field of desc to ToBoolean(writable).
  7. If the result of calling the [[HasProperty]] internal method of Obj with argument "get" is true, then:
    1. Let getter be the result of calling the [[Get]] internal method of Obj with argument "get".
    2. If IsCallable(getter) is false and getter is not undefined, then throw a TypeError exception.
    3. Set the [[Get]] field of desc to getter.
  8. If the result of calling the [[HasProperty]] internal method of Obj with argument "set" is true, then:
    1. Let setter be the result of calling the [[Get]] internal method of Obj with argument "set".
    2. If IsCallable(setter) is false and setter is not undefined, then throw a TypeError exception.
    3. Set the [[Set]] field of desc to setter.
  9. If either desc.[[Get]] or desc.[[Set]] are present, then:
    1. If either desc.[[Value]] or desc.[[Writable]] are present, then throw a TypeError exception.
  10. Return desc.

Notes:

  • Since [[Get]] is used to read the descriptor value fields, they can be inherited from a parent object, and they can also be accessors.
  • Setter/getter values must be either callable or undefined if they are present. In particular, null is not an allowed value.
  • Any call to [[Get]] may cause an exception (e.g. if the property is an accessor with a throwing getter). In addition, there are explicit exceptions for object type check and setter/getter check. The order of checking and coercion thus matters, at least if the errors thrown have a message indicating the failing check. All the exceptions are of the same type (TypeError), so a chance in ordering is not strictly a compliance issue (there are no guaranteed error messages).
  • ToBoolean() has no side effects and is guaranteed to succeed.

The algorithm in the specification is expressed quite verbosely; the following is a reformulation with less text, the target object has also been renamed to O:

  1. If Type(O) is not Object throw a TypeError exception.
  2. Let desc be a new, empty Property Descriptor.
  3. If O.[[HasProperty]]("enumerable") === true, then set desc.[[Enumerable]] to ToBoolean(O.[[Get]]("enumerable")).
  4. If O.[[HasProperty]]("configurable") === true, then set desc.[[Configurable]] to ToBoolean(O.[[Get]]("configurable")).
  5. If O.[[HasProperty]]("value") === true, then set desc.[[Value]] to O.[[Get]]("value").
  6. If O.[[HasProperty]]("writable") === true, then set desc.[[Writable]] to ToBoolean(O.[[Get]]("writable")).
  7. If O.[[HasProperty]]("get") === true, then:
    1. Set desc.[[Get]] to O.[[Get]]("get").
    2. If desc.[[Get]] !== undefined and IsCallable(desc.[[Get]]) === false, then throw a TypeError exception.
  8. If O.[[HasProperty]]("set") === true, then:
    1. Set desc.[[Set]] to O.[[Get]]("set").
    2. If desc.[[Set]] !== undefined and IsCallable(desc.[[Set]]) === false, then throw a TypeError exception.
  9. If either desc.[[Get]] or desc.[[Set]] are present, then:
    1. If either desc.[[Value]] or desc.[[Writable]] are present, then throw a TypeError exception.
  10. Return desc.

NormalizePropertyDescriptor

This algorithm is not defined in the E5 specification, but is used as an internal helper for implementing Object.defineProperties() and Object.defineProperty().

The algorithm is a variant of ToPropertyDescriptor() which, instead of an internal descriptor, outputs an equivalent ECMAScript property descriptor which has been fully validated, and contains only "own" data properties. If the resulting ECMAScript object, desc, is later given to ToPropertyDescriptor():

  • The call cannot fail.
  • The call will yield the same internal descriptor as if given the original object.
  • There can be no user visible side effects, because desc only contains plain (own) values.

For instance, if the input property descriptor were:

{
  get value() { return "test"; },
  writable: 0.0,
  configurable: "nonempty",
  enumerable: new Date(),
  additional: "ignored"   // ignored, not relevant to a descriptor
}

the normalized descriptor would be:

{
  value: "test",
  writable: false,
  configurable: true,
  enumerable: true
}

(The example doesn't illustrate the fact that inherited properties are converted to "own" properties.)

The algorithm is as follows:

  1. If Type(O) is not Object throw a TypeError exception.
  2. Let desc be a new, empty Object.
  3. If O.[[HasProperty]]("enumerable") === true, then call desc.[[Put]] with the arguments "enumerable", ToBoolean(O.[[Get]]("enumerable")) and true.
  4. If O.[[HasProperty]]("configurable") === true, then call desc.[[Put]] with the arguments "configurable", ToBoolean(O.[[Get]]("configurable")) and true.
  5. If O.[[HasProperty]]("value") === true, then call desc.[[Put]] with the arguments "value", O.[[Get]]("value") and true.
  6. If O.[[HasProperty]]("writable") === true, then call desc.[[Put]] with the arguments "writable", ToBoolean(O.[[Get]]("writable")) and true.
  7. If O.[[HasProperty]]("get") === true, then:
    1. Let getter be O.[[Get]]("get").
    2. If getter !== undefined and IsCallable(getter) === false, then throw a TypeError exception.
    3. Call desc.[[Put]] with the arguments "get", getter and true.
  8. If O.[[HasProperty]]("set") === true, then:
    1. Let setter be O.[[Get]]("set").
    2. If setter !== undefined and IsCallable(setter) === false, then throw a TypeError exception.
    3. Call desc.[[Put]] with the arguments "set", setter and true.
  9. Validation:
    1. Let g be desc.[[HasProperty]]("get").
    2. Let s be desc.[[HasProperty]]("set").
    3. Let v be desc.[[HasProperty]]("value").
    4. Let w be desc.[[HasProperty]]("writable").
    5. If (g || s) && (v || w) then throw a TypeError exception.
  10. Return desc.

Notes:

  • The third argument to desc.[[Put]] is the Throw flag. The value is irrelevant as the [[Put]] calls cannot fail.