proposal.html

<pre class=metadata>
title: Array.prototype.flatMap &amp; Array.prototype.flat
toc: false
stage: 4
contributors: Michael Ficarra, Brian Terlson, and Mathias Bynens
</pre>

<emu-intro id="intro">
  <h1>Introduction</h1>
  <p>`Array.prototype.flat` returns a new array with all sub-array elements concatenated into it recursively up to the specified depth.</p>
  <p>`Array.prototype.flatMap` first maps each element using a mapping function, then flattens the result into a new array. It is identical to a map followed by a flatten of depth 1, but flatMap is quite often useful and merging both into one method is slightly more efficient.</p>
</emu-intro>

<emu-clause id="sec-array.prototype.flatmap">
  <h1>Array.prototype.flatMap ( _mapperFunction_ [ , _thisArg_ ] )</h1>
  <p>When the `flatMap` method is called with one or two arguments, the following steps are taken:</p>
  <emu-alg>
    1. Let _O_ be ? ToObject(*this* value).
    1. Let _sourceLen_ be ? ToLength(? Get(_O_, `"length"`)).
    1. If IsCallable(_mapperFunction_) is *false*, throw a *TypeError* exception.
    1. If _thisArg_ is present, let _T_ be _thisArg_; else let _T_ be *undefined*.
    1. Let _A_ be ? ArraySpeciesCreate(_O_, 0).
    1. Perform ? FlattenIntoArray(_A_, _O_, _sourceLen_, 0, 1, _mapperFunction_, _T_).
    1. Return _A_.
  </emu-alg>
</emu-clause>

<emu-clause id="sec-array.prototype.flat">
  <h1>Array.prototype.flat( [ _depth_ ] )</h1>
  <p>When the `flat` method is called with zero or one arguments, the following steps are taken:</p>
  <emu-alg>
    1. Let _O_ be ? ToObject(*this* value).
    1. Let _sourceLen_ be ? ToLength(? Get(_O_, `"length"`)).
    1. Let _depthNum_ be 1.
    1. If _depth_ is not *undefined*, then
      1. Set _depthNum_ to ? ToInteger(_depth_).
    1. Let _A_ be ? ArraySpeciesCreate(_O_, 0).
    1. Perform ? FlattenIntoArray(_A_, _O_, _sourceLen_, 0, _depthNum_).
    1. Return _A_.
  </emu-alg>

  <emu-clause id="sec-flattenintoarray" aoid="FlattenIntoArray">
    <h1>FlattenIntoArray(_target_, _source_, _sourceLen_, _start_, _depth_ [ , _mapperFunction_, _thisArg_ ])</h1>
    <emu-alg>
      1. Let _targetIndex_ be _start_.
      1. Let _sourceIndex_ be 0.
      1. Repeat, while _sourceIndex_ &lt; _sourceLen_
        1. Let _P_ be ! ToString(_sourceIndex_).
        1. Let _exists_ be ? HasProperty(_source_, _P_).
        1. If _exists_ is *true*, then
          1. Let _element_ be ? Get(_source_, _P_).
          1. If _mapperFunction_ is present, then
            1. Assert: _thisArg_ is present.
            1. Set _element_ to ? Call(_mapperFunction_, _thisArg_ , &laquo; _element_, _sourceIndex_, _source_ &raquo;).
          1. Let _shouldFlatten_ be *false*.
          1. If _depth_ &gt; 0, then
            1. Set _shouldFlatten_ to ? IsArray(_element_).
          1. If _shouldFlatten_ is *true*, then
            1. Let _elementLen_ be ? ToLength(? Get(_element_, `"length"`)).
            1. Set _targetIndex_ to ? FlattenIntoArray(_target_, _element_, _elementLen_, _targetIndex_, _depth_ - 1).
          1. Else,
            1. If _targetIndex_ &ge; 2<sup>53</sup>-1, throw a *TypeError* exception.
            1. Perform ? CreateDataPropertyOrThrow(_target_, ! ToString(_targetIndex_), _element_).
            1. Increase _targetIndex_ by 1.
        1. Increase _sourceIndex_ by 1.
      1. Return _targetIndex_.
    </emu-alg>
  </emu-clause>
</emu-clause>

<emu-clause id="sec-array.prototype-@@unscopables">
  <h1>Array.prototype [ @@unscopables ]</h1>
  <p>The initial value of the @@unscopables data property is an object created by the following steps:</p>
  <emu-alg>
    1. Let _unscopableList_ be ObjectCreate(*null*).
    1. Perform CreateDataProperty(_unscopableList_, `"copyWithin"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"entries"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"fill"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"find"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"findIndex"`, *true*).
    1. <ins>Perform CreateDataProperty(_unscopableList_, `"flat"`, *true*).</ins>
    1. <ins>Perform CreateDataProperty(_unscopableList_, `"flatMap"`, *true*).</ins>
    1. Perform CreateDataProperty(_unscopableList_, `"includes"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"keys"`, *true*).
    1. Perform CreateDataProperty(_unscopableList_, `"values"`, *true*).
    1. Assert: Each of the above calls <del>will</del> return<ins>s</ins> *true*.
    1. Return _unscopableList_.
  </emu-alg>
  <p>This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.</p>
  <emu-note>
    <p>The own property names of this object are property names that were not included as standard properties of `Array.prototype` <del>prior to</del> <ins>in earlier editions of</ins> the ECMAScript <del>2015</del> specification. These names are ignored for `with` statement binding purposes in order to preserve the behaviour of existing code that might use one of these names as a binding in an outer scope that is shadowed by a `with` statement whose binding object is an Array object.</p>
  </emu-note>
</emu-clause>