New collections (Set and Map) methods

See formal spec WIP.

(Semi)relevant previous discussions

Motivations

  • it's consistent with already familiar and widely used Array API (reduced cognitive overhead)
    • easier refactoring
    • certain function become generic
  • reduces boilerplate code when dealing with common collection use cases
  • no new syntax
  • allow developers coming from other languages to use familiar APIs

Adoption

TBA

Quick reference for other languages similar data structures

Set

Map (known also as Dictionary)

TBA

Proposal

This proposal does not change grammar of language.

New methods are added to Set.prototype.

  • Array-like methods. These methods replicates functionality of Array.prototype methods:
    • Set.prototype.filter(predicate, thisArg)
    • Set.prototype.map(fn, thisArg)
    • Set.prototype.find(fn, thisArg)
    • Set.prototype.reduce(fn, initialValue)
    • Set.prototype.join(separator)
    • Set.prototype.some(predicate, thisArg)
    • Set.prototype.every(predicate, thisArg)
  • New methods:
    • Set.prototype.addAll(...elements) - similar to Array.prototype.push. Adds all of arguments to existing Set.
      • Alternative name: .addEach
    • Set.prototype.deleteAll(...elements) - reverse of addAll. Remove every element in elements from existing Set.
      • Alternative names: .deleteEach

New methods are added to Map.prototype.

  • Array-like methods. These methods replicates functionality of Array.prototype methods:

    • Map.prototype.filter(predicate, thisArg)
    • Map.prototype.mapValues(fn, thisArg)
    • Map.prototype.mapKeys(fn, thisArg)
    • Map.prototype.reduce(fn, initialValue)
    • Map.prototype.find(fn, thisArg)
    • Map.prototype.findKey(fn, thisArg)
    • Map.prototype.keyOf(searchElement)
    • Map.prototype.some(predicate, thisArg)
    • Map.prototype.every(predicate, thisArg)
    • Map.prototype.includes(searchElement)
    • Map.prototype.update(key, callbackfn, thunk)

  • New methods:

    • Map.prototype.deleteAll(...elements) - similar to Set.prototype.deleteAll.
    • Map.prototype.merge(...iterables) - performs in-place update joining arbitrary number of iterables.
    • Map.prototype.update(key, cb [,thunk]) - performs in-place update of single value.

New methods are added to %Map%.

  • Map.groupBy(iterable, keyDerivative) -
  • Map.keyBy(iterable, keyDerivative) -

New methods are added to WeakSet.prototype.

  • New methods:
    • WeakSet.prototype.addAll(...elements) - similar to Set.prototype.addAll.
    • WeakSet.prototype.deleteAll(...elements) - similar to Set.prototype.deleteAll.

New methods are added to WeakMap.prototype.

  • New methods:
    • WeakMap.prototype.deleteAll(...elements) - similar to Map.prototype.deleteAll.

Polyfill

A polyfill is available in the core-js library. You can find it in the ECMAScript proposal section / Stage 1 proposals / New Set and Map methods proposal.

For all new collection methods include this at the top of your entry point.

require('core-js/proposals/collection-methods');

const colors = new Map([['red', '#FF0000'], ['gold', '#FFD700']]);
colors
  .mapKeys((value, key) => key.toUpperCase()) // Map { 'RED' => '#FF0000', 'GOLD' => '#FFD700' }
  .mapValues(value => value.toLowerCase()); // Map { 'RED' => '#ff0000', 'GOLD' => '#ffd700' }

For a specific method include the needed polyfill directly.

require('core-js/features/set/join');

const mySet = new Set(['Just', 'like', 'an', 'array']);
mySet.join(' '); // Just like an array

Not included in this proposal but worth considering

Why not %IteratorPrototype% methods

  • Explicit usage of iterators is verbose
    • Compare new Set(set.entries().filter(fn)) to set.filter(fn). 19 characters of boilerplate.
      • Even small codebase can have hundreds occurrences of this pattern - and hundreds places to make a mistake.
  • User code have no easy way to inherit from %IteratorPrototype%

Rationales

See rationales.md for details.