===============================
Exposed Object.defineProperty()
===============================

Original algorithm
==================

The algorithm is specified in E5 Section 15.2.3.6:

1. If ``Type(O)`` is not ``Object`` throw a ``TypeError`` exception.

2. Let ``name`` be ``ToString(P)``.
   (Note: this may have side effects.)

3. Let ``desc`` be the result of calling ``ToPropertyDescriptor`` with
   ``Attributes`` as the argument.

4. Call the ``[[DefineOwnProperty]]`` internal method of ``O`` with
   arguments ``name``, ``desc``, and ``true``.
   (Note: the last argument, ``true``, is the ``Throw`` flag.)

5. Return ``O``.

The algorithm returns the object, which allows chaining; for instance::

  var o = {};
  Object.defineProperty(o, 'foo',
    { value: 'bar' }
  ).seal();

``ToPropertyDescriptor()`` is a helper called only from
``Object.defineProperty()`` and ``Object.defineProperties()``.  It
converts a property descriptor expressed as an ECMAScript object into
a "specification descriptor", doing boolean coercions and cross checking
the descriptor.  For instance, ``ToPropertyDescriptor()`` will reject
any property descriptor which contains fields indicating it is both
a data property descriptor and an accessor property descriptor.
Example from Node / V8::

  > var o = {};
  > Object.defineProperty(o, 'foo',
  ...   { value: 'bar', set: function() {} });
  TypeError: Invalid property.  A property cannot both
  have accessors and be writable or have a value, #<Object>

The result of the property descriptor conversion is an "internal descriptor".
Note that unlike when dealing with existing object properties, this descriptor
may not be fully populated, i.e. may be missing fields.  From an implementation
perspective this means that the descriptor needs to be represented differently.
The current implementation doesn't have an explicit representation for the
"internal descriptor" which exists for the duration of
``Object.defineProperty()``; the descriptor is represented by a bunch of local
variables indicating the presence and coerced values of the descriptor fields
(for instance: ``has_writable`` and ``is_writable`` are separate variables).

The ``ToPropertyDescriptor()`` algorithm is reformulated in the restatements
section.

Other notes:

* The key is coerced to a string leniently while the object is just checked
  and never coerced.

* ``[[DefineOwnProperty]]`` is always called with ``Throw`` set to ``true``,
  so the implementation doesn't need to expose a "throw flag".

First draft
===========

Starting from the original algorithm and inlining both
``ToPropertyDescriptor()`` and the ``[[DefineOwnProperty]]`` algorithm
with exotic behaviors, we get:

1. If ``Type(O)`` is not ``Object`` throw a ``TypeError`` exception.

2. Let ``name`` be ``ToString(P)``.
   (Note: this may have side effects.)

3. If ``Type(O)`` is not ``Object`` throw a ``TypeError`` exception.

4. Let ``desc`` be a new, empty Property Descriptor.

5. If ``O.[[HasProperty]]("enumerable")`` === ``true``, then
   set ``desc.[[Enumerable]]`` to ``ToBoolean(O.[[Get]]("enumerable"))``.

6. If ``O.[[HasProperty]]("configurable")`` === ``true``, then
   set ``desc.[[Configurable]]`` to ``ToBoolean(O.[[Get]]("configurable"))``.

7. If ``O.[[HasProperty]]("value")`` === ``true``, then
   set ``desc.[[Value]]`` to ``O.[[Get]]("value")``.

8. If ``O.[[HasProperty]]("writable")`` === ``true``, then
   set ``desc.[[Writable]]`` to ``ToBoolean(O.[[Get]]("writable"))``.

9. If ``O.[[HasProperty]]("get")`` === ``true``, then:

   a. Set ``desc.[[Get]]`` to ``O.[[Get]]("get")``.

   b. If ``desc.[[Get]]`` !== ``undefined`` and
      ``IsCallable(desc.[[Get]])`` === ``false``, then
      throw a ``TypeError`` exception.

10. If ``O.[[HasProperty]]("set")`` === ``true``, then:

    a. Set ``desc.[[Set]]`` to ``O.[[Get]]("set")``.

    b. If ``desc.[[Set]]`` !== ``undefined`` and
       ``IsCallable(desc.[[Set]])`` === ``false``, then
       throw a ``TypeError`` exception.

11. If either ``desc.[[Get]]`` or ``desc.[[Set]]`` are present, then:

    a. If either ``desc.[[Value]]`` or ``desc.[[Writable]]`` are present,
       then throw a ``TypeError`` exception.

12. Let ``Throw`` be ``true``.

13. Set ``pendingWriteProtect`` to ``false``.

14. If ``O`` is not an ``Array`` object, goto SKIPARRAY.

15. 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.

16. Let ``oldLen`` be ``oldLenDesc.[[Value]]``.
    (Note that ``oldLen`` is guaranteed to be a unsigned 32-bit integer.)

17. If ``P`` is ``"length"``, then

    a. If the ``[[Value]]`` field of ``Desc`` is absent, then goto SKIPARRAY.

    b. Let ``newLen`` be ``ToUint32(Desc.[[Value]])``.

    c. If ``newLen`` is not equal to ``ToNumber(Desc.[[Value]])``, goto
       REJECTRANGE.

    d. Set ``Desc.[[Value]]`` to ``newLen``.

    e. If ``newLen`` >= ``oldLen``, then goto SKIPARRAY.

    f. Goto REJECT if ``oldLenDesc.[[Writable]]`` is ``false``.

    g. If ``Desc.[[Writable]]`` has the value ``false``:

       1. Need to defer setting the ``[[Writable]]`` attribute to ``false``
          in case any elements cannot be deleted.

       2. Set ``pendingWriteProtect`` to ``true``.

       3. Set ``Desc.[[Writable]]`` to ``true``.

    h. Goto SKIPARRAY.  (Rest of the processing happens in the post-step.)

18. Else if ``P`` is an array index (E5 Section 15.4), then:

    a. Let ``index`` be ``ToUint32(P)``.

    b. Goto REJECT if ``index`` >= ``oldLen`` and ``oldLenDesc.[[Writable]]``
       is ``false``.

    c. Goto SKIPARRAY.  (Rest of the processing happens in the post-step.)

19. **SKIPARRAY**:
    Let ``current`` be the result of calling the ``[[GetOwnProperty]]``
    internal method of ``O`` with property name ``P``.

20. Let ``extensible`` be the value of the ``[[Extensible]]`` internal
    property of ``O``.

21. If ``current`` is ``undefined``:

    a. If ``extensible`` is ``false``, then goto REJECT.

    b. If ``IsGenericDescriptor(Desc)`` or ``IsDataDescriptor(Desc)`` is
       ``true``, then

       1. Create an own data property named ``P`` of object ``O`` whose
          ``[[Value]]``, ``[[Writable]]``, ``[[Enumerable]]`` and
          ``[[Configurable]]`` attribute values are described by ``Desc``.
          If the value of an attribute field of ``Desc`` is absent, the
          attribute of the newly created property is set to its default
          value.

    c. Else, ``Desc`` must be an accessor Property Descriptor so,

       1. Create an own accessor property named ``P`` of object ``O`` whose
          ``[[Get]]``, ``[[Set]]``, ``[[Enumerable]]`` and ``[[Configurable]]``
          attribute values are described by ``Desc``.  If the value of an
          attribute field of ``Desc`` is absent, the attribute of the newly
          created property is set to its default value.

    d. Goto SUCCESS.

22. Goto SUCCESS, if every field in ``Desc`` also occurs in ``current``
    and the value of every field in ``Desc`` is the same value as the
    corresponding field in ``current`` when compared using the ``SameValue``
    algorithm (E5 Section 9.12).  (This also covers the case where
    every field in ``Desc`` is absent.)

23. If the ``[[Configurable]]`` field of ``current`` is ``false`` then

    a. Goto REJECT, if the ``[[Configurable]]`` field of ``Desc`` is true.

    b. Goto REJECT, if the ``[[Enumerable]]`` field of ``Desc`` is present
       and the ``[[Enumerable]]`` fields of ``current`` and ``Desc`` are the
       Boolean negation of each other.

24. If ``IsGenericDescriptor(Desc)`` is ``true``, then goto VALIDATED.

25. Else, if ``IsDataDescriptor(current)`` and ``IsDataDescriptor(Desc)``
    have different results, then

    a. Goto REJECT, if the ``[[Configurable]]`` field of ``current`` is
       ``false``.

    b. If ``IsDataDescriptor(current)`` is true, then

       1. Convert the property named ``P`` of object ``O`` from a data property
          to an accessor property.  Preserve the existing values of the
          converted property's ``[[Configurable]]`` and ``[[Enumerable]]``
          attributes and set the rest of the property's attributes to their
          default values.

    c. Else,

       1. Convert the property named ``P`` of object ``O`` from an accessor
          property to a data property.  Preserve the existing values of the
          converted property's ``[[Configurable]]`` and ``[[Enumerable]]``
          attributes and set the rest of the property's attributes to their
          default values.

    d. Goto VALIDATED.

26. Else, if ``IsDataDescriptor(current)`` and ``IsDataDescriptor(Desc)``
    are both true, then

    a. If the ``[[Configurable]]`` field of ``current`` is ``false``, then

       1. Goto REJECT, if the ``[[Writable]]`` field of ``current`` is
          ``false`` and the ``[[Writable]]`` field of ``Desc`` is ``true``.

       2. Goto REJECT, If the ``[[Writable]]`` field of ``current`` is
          ``false``, and the ``[[Value]]`` field of ``Desc`` is present, and
          ``SameValue(Desc.[[Value]], current.[[Value]])`` is ``false``.

    b. Goto VALIDATED.

27. Else, ``IsAccessorDescriptor(current)`` and ``IsAccessorDescriptor(Desc)``
    are both ``true`` so,

    a. If the ``[[Configurable]]`` field of ``current`` is ``false``, then

       1. Goto REJECT, if the ``[[Set]]`` field of ``Desc`` is present and
          ``SameValue(Desc.[[Set]], current.[[Set]])`` is ``false``.

       2. Goto REJECT, if the ``[[Get]]`` field of ``Desc`` is present and
          ``SameValue(Desc.[[Get]], current.[[Get]])`` is ``false``.

    b. Goto VALIDATED.

28. **VALIDATED:**
    For each attribute field of ``Desc`` that is present, set the
    correspondingly named attribute of the property named ``P`` of object
    ``O`` to the value of the field.

29. **SUCCESS:**
    If ``O`` is an ``Array`` object:

    a. If ``P`` is ``"length"``, and ``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. If ``pendingWriteProtect`` is ``true``, update the property
          (``"length"``) to have ``[[Writable]] = false``.

       4. Goto REJECT, if ``shortenSucceeded`` is ``false``.

    b. If ``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.

30. If ``O`` is an arguments object which has a ``[[ParameterMap]]``
    internal property:

    a. Let ``map`` be the value of the ``[[ParameterMap]]`` internal property
       of the arguments object.

    b. If the result of calling the ``[[GetOwnProperty]]`` internal method
       of ``map`` passing ``P`` as the argument is not ``undefined``, then:

       1. If ``IsAccessorDescriptor(Desc)`` is ``true``, then:

          a. Call the ``[[Delete]]`` internal method of ``map`` passing ``P``,
             and ``false`` as the arguments.  (This removes the magic binding
             for ``P``.)

       2. Else (``Desc`` may be generic or data descriptor):

          a. If ``Desc.[[Value]]`` is present, then:

             1. Call the ``[[Put]]`` internal method of ``map`` passing ``P``,
                ``Desc.[[Value]]``, and ``Throw`` as the arguments.  (This
                updates the bound variable value.)

          b. If ``Desc.[[Writable]]`` is present and its value is ``false``,
             then:

             1. Call the ``[[Delete]]`` internal method of ``map`` passing ``P``
                and ``false`` as arguments.  (This removes the magic binding
                for ``P``, and must happen after a possible update of the
                variable value.)

31. Return ``O``.

32. **REJECT**:
    If ``Throw`` is ``true``, then throw a ``TypeError`` exception,
    otherwise return ``false``.

33. **REJECTRANGE**:
    Throw a ``RangeError`` exception.  Note that this is unconditional
    (thrown even if ``Throw`` is ``false``).

Notes:

* Step 3 is redundant (it comes from ``ToPropertyDescriptor()`` because
  of step 1.

* Since ``Throw`` is always ``true``, step 12 can be removed and
  step 32 changed to throw ``TypeError`` unconditionally.  Note that
  ``Throw`` is also given as a parameter in step 30.b.2.1 as an
  argument for an internal ``[[Put]]`` to the parameter map.  This
  actually has no effect on behavior (the internal setter will be
  called, and the ``Throw`` flag is not visible to the setter).

Some cleanup
============

1. If ``Type(O)`` is not ``Object`` throw a ``TypeError`` exception.

2. Let ``name`` be ``ToString(P)``.
   (Note: this may have side effects.)

3. Let ``desc`` be a new, empty Property Descriptor.

4. If ``O.[[HasProperty]]("enumerable")`` === ``true``, then
   set ``desc.[[Enumerable]]`` to ``ToBoolean(O.[[Get]]("enumerable"))``.

5. If ``O.[[HasProperty]]("configurable")`` === ``true``, then
   set ``desc.[[Configurable]]`` to ``ToBoolean(O.[[Get]]("configurable"))``.

6. If ``O.[[HasProperty]]("value")`` === ``true``, then
   set ``desc.[[Value]]`` to ``O.[[Get]]("value")``.

7. If ``O.[[HasProperty]]("writable")`` === ``true``, then
   set ``desc.[[Writable]]`` to ``ToBoolean(O.[[Get]]("writable"))``.

8. If ``O.[[HasProperty]]("get")`` === ``true``, then:

   a. Set ``desc.[[Get]]`` to ``O.[[Get]]("get")``.

   b. If ``desc.[[Get]]`` !== ``undefined`` and
      ``IsCallable(desc.[[Get]])`` === ``false``, then
      throw a ``TypeError`` exception.

9. If ``O.[[HasProperty]]("set")`` === ``true``, then:

   a. Set ``desc.[[Set]]`` to ``O.[[Get]]("set")``.

   b. If ``desc.[[Set]]`` !== ``undefined`` and
      ``IsCallable(desc.[[Set]])`` === ``false``, then
      throw a ``TypeError`` exception.

10. If either ``desc.[[Get]]`` or ``desc.[[Set]]`` are present, then:

    a. If either ``desc.[[Value]]`` or ``desc.[[Writable]]`` are present,
       then throw a ``TypeError`` exception.

11. Set ``pendingWriteProtect`` to ``false``.

12. If ``O`` is not an ``Array`` object, goto SKIPARRAY.

13. 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.

14. Let ``oldLen`` be ``oldLenDesc.[[Value]]``.
    (Note that ``oldLen`` is guaranteed to be a unsigned 32-bit integer.)

15. If ``P`` is ``"length"``, then

    a. If the ``[[Value]]`` field of ``Desc`` is absent, then goto SKIPARRAY.

    b. Let ``newLen`` be ``ToUint32(Desc.[[Value]])``.

    c. If ``newLen`` is not equal to ``ToNumber(Desc.[[Value]])``, goto
       REJECTRANGE.

    d. Set ``Desc.[[Value]]`` to ``newLen``.

    e. If ``newLen`` >= ``oldLen``, then goto SKIPARRAY.

    f. Goto REJECT if ``oldLenDesc.[[Writable]]`` is ``false``.

    g. If ``Desc.[[Writable]]`` has the value ``false``:

       1. Need to defer setting the ``[[Writable]]`` attribute to ``false``
          in case any elements cannot be deleted.

       2. Set ``pendingWriteProtect`` to ``true``.

       3. Set ``Desc.[[Writable]]`` to ``true``.

    h. Goto SKIPARRAY.  (Rest of the processing happens in the post-step.)

16. Else if ``P`` is an array index (E5 Section 15.4), then:

    a. Let ``index`` be ``ToUint32(P)``.

    b. Goto REJECT if ``index`` >= ``oldLen`` and ``oldLenDesc.[[Writable]]``
       is ``false``.

    c. Goto SKIPARRAY.  (Rest of the processing happens in the post-step.)

17. **SKIPARRAY**:
    Let ``current`` be the result of calling the ``[[GetOwnProperty]]``
    internal method of ``O`` with property name ``P``.

18. Let ``extensible`` be the value of the ``[[Extensible]]`` internal
    property of ``O``.

19. If ``current`` is ``undefined``:

    a. If ``extensible`` is ``false``, then goto REJECT.

    b. If ``IsGenericDescriptor(Desc)`` or ``IsDataDescriptor(Desc)`` is
       ``true``, then

       1. Create an own data property named ``P`` of object ``O`` whose
          ``[[Value]]``, ``[[Writable]]``, ``[[Enumerable]]`` and
          ``[[Configurable]]`` attribute values are described by ``Desc``.
          If the value of an attribute field of ``Desc`` is absent, the
          attribute of the newly created property is set to its default
          value.

    c. Else, ``Desc`` must be an accessor Property Descriptor so,

       1. Create an own accessor property named ``P`` of object ``O`` whose
          ``[[Get]]``, ``[[Set]]``, ``[[Enumerable]]`` and ``[[Configurable]]``
          attribute values are described by ``Desc``.  If the value of an
          attribute field of ``Desc`` is absent, the attribute of the newly
           created property is set to its default value.

    d. Goto SUCCESS.

20. Goto SUCCESS, if every field in ``Desc`` also occurs in ``current``
    and the value of every field in ``Desc`` is the same value as the
    corresponding field in ``current`` when compared using the ``SameValue``
    algorithm (E5 Section 9.12).  (This also covers the case where
    every field in ``Desc`` is absent.)

21. If the ``[[Configurable]]`` field of ``current`` is ``false`` then

    a. Goto REJECT, if the ``[[Configurable]]`` field of ``Desc`` is true.

    b. Goto REJECT, if the ``[[Enumerable]]`` field of ``Desc`` is present
       and the ``[[Enumerable]]`` fields of ``current`` and ``Desc`` are the
       Boolean negation of each other.

22. If ``IsGenericDescriptor(Desc)`` is ``true``, then goto VALIDATED.

23. Else, if ``IsDataDescriptor(current)`` and ``IsDataDescriptor(Desc)``
    have different results, then

    a. Goto REJECT, if the ``[[Configurable]]`` field of ``current`` is
       ``false``.

    b. If ``IsDataDescriptor(current)`` is true, then

       1. Convert the property named ``P`` of object ``O`` from a data property
          to an accessor property.  Preserve the existing values of the
          converted property's ``[[Configurable]]`` and ``[[Enumerable]]``
          attributes and set the rest of the property's attributes to their
          default values.

    c. Else,

       1. Convert the property named ``P`` of object ``O`` from an accessor
          property to a data property.  Preserve the existing values of the
          converted property's ``[[Configurable]]`` and ``[[Enumerable]]``
          attributes and set the rest of the property's attributes to their
          default values.

    d. Goto VALIDATED.

24. Else, if ``IsDataDescriptor(current)`` and ``IsDataDescriptor(Desc)``
    are both true, then

    a. If the ``[[Configurable]]`` field of ``current`` is ``false``, then

       1. Goto REJECT, if the ``[[Writable]]`` field of ``current`` is
          ``false`` and the ``[[Writable]]`` field of ``Desc`` is ``true``.

       2. Goto REJECT, If the ``[[Writable]]`` field of ``current`` is
          ``false``, and the ``[[Value]]`` field of ``Desc`` is present, and
          ``SameValue(Desc.[[Value]], current.[[Value]])`` is ``false``.

    b. Goto VALIDATED.

25. Else, ``IsAccessorDescriptor(current)`` and ``IsAccessorDescriptor(Desc)``
    are both ``true`` so,

    a. If the ``[[Configurable]]`` field of ``current`` is ``false``, then

       1. Goto REJECT, if the ``[[Set]]`` field of ``Desc`` is present and
          ``SameValue(Desc.[[Set]], current.[[Set]])`` is ``false``.

       2. Goto REJECT, if the ``[[Get]]`` field of ``Desc`` is present and
          ``SameValue(Desc.[[Get]], current.[[Get]])`` is ``false``.

    b. Goto VALIDATED.

26. **VALIDATED:**
    For each attribute field of ``Desc`` that is present, set the
    correspondingly named attribute of the property named ``P`` of object
    ``O`` to the value of the field.

27. **SUCCESS:**
    If ``O`` is an ``Array`` object:

    a. If ``P`` is ``"length"``, and ``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. If ``pendingWriteProtect`` is ``true``, update the property
          (``"length"``) to have ``[[Writable]] = false``.

       4. Goto REJECT, if ``shortenSucceeded`` is ``false``.

    b. If ``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.

28. If ``O`` is an arguments object which has a ``[[ParameterMap]]``
    internal property:

    a. Let ``map`` be the value of the ``[[ParameterMap]]`` internal property
       of the arguments object.

    b. If the result of calling the ``[[GetOwnProperty]]`` internal method
       of ``map`` passing ``P`` as the argument is not ``undefined``, then:

       1. If ``IsAccessorDescriptor(Desc)`` is ``true``, then:

          a. Call the ``[[Delete]]`` internal method of ``map`` passing ``P``,
             and ``false`` as the arguments.  (This removes the magic binding
             for ``P``.)

       2. Else (``Desc`` may be generic or data descriptor):

          a. If ``Desc.[[Value]]`` is present, then:

             1. Call the ``[[Put]]`` internal method of ``map`` passing ``P``,
                ``Desc.[[Value]]``, and ``true`` as the arguments.
                (This updates the bound variable value.  Note that the ``Throw``
                flag is irrelevant, ``true`` used now.)

          b. If ``Desc.[[Writable]]`` is present and its value is ``false``,
             then:

             1. Call the ``[[Delete]]`` internal method of ``map`` passing ``P``
                and ``false`` as arguments.  (This removes the magic binding
                for ``P``, and must happen after a possible update of the
                variable value.)

29. Return ``O``.

30. **REJECT**:
    Throw a ``TypeError`` exception.

31. **REJECTRANGE**:
    Throw a ``RangeError`` exception.