For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/year/pending/proposal-array-filtering.md.
TC39 Atlas
  • English

      • Array filtering S1

      Proposal details
      Proposal overview

      This proposal addresses the confusion caused by Array.prototype.filter's semantics, where 'filter' implies removal but actually retains items. It proposes adding Array.prototype.filterReject, which removes items for which the callback returns true, matching the intuitive meaning of 'filtering out'.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      proposal-array-filtering

      A proposal to add Array.prototype.filterReject.

      const array = [1, 2, 3, 4, 5];

// filter keeps the items that return true.
array.filter(i => (i < 3)); // => [1, 2];

// filterReject removes the items that return true.
array.filterReject(i => (i < 3)); // => [3, 4, 5];

      Champions

      Status

      Current Stage: 1

      Motivation

      Array.p.filter is confusing. I constantly have to ask myself "am I keeping, or filtering out the current item?".

      "Keeping"

      Implies that returning true would keep the current item.

      "Filtering out"

      Implies that returning true would remove the current item.

      Array.p.filter acts as "keeping". But when I think of the word "filter", I think of "filtering out". So every time that I attempt to write an array filter, I end up writing the opposite of what I intended.

      Array.p.filterReject attempts to fix this confusion. By providing a clearly named filtering function that matches my intuition, I'm able what will happen when calling filterReject. And because it exists, I'm able to assume that filter does something different, so it must be "keep" version.

      Polyfill

      A polyfill is available in the core-js library. You can find it in the ECMAScript proposals section.

      Ongoing Discussions