/proposal-set-methods

Strawman for new Set methods

Primary LanguageHTMLOtherNOASSERTION

New Set methods

See formal spec WIP.

See proposal extending Set and Map with Array-like methods.

Proposal

This proposal does not change syntax of language.

New methods based on set theory are added to Set.prototype.

  • Set.prototype.intersection(iterable) - method creates new Set instance by set intersection operation.
  • Set.prototype.union(iterable) - method creates new Set instance by set union operation.
  • Set.prototype.difference(iterable) - method creates new Set without elements present in iterable.
  • Set.prototype.symmetricDifference(iterable) - returns Set of elements found only in either this or in iterable.
  • Set.prototype.isSubsetOf(iterable)
  • Set.prototype.isDisjointFrom(iterable)
  • Set.prototype.isSupersetOf(iterable)

(Semi)relevant previous discussions

Motivations

  • reduces need to depend on Immutable.js Set<T>
  • reduces boilerplate code when dealing with common use cases of Set
  • no new syntax

Adoption

  • No npm package duplicating this proposal was found
  • Very similar API was found in popular Collections.js (205k downloads per month)
  • This proposal is inspired by Set API from Immutable.js (3M downloads per month)

Comparison with Immutable.js

  • No static intersection, union methods in this proposal
  • union, intersection, difference takes single argument

Comparison with other languages

See other languages document to get overview of Set methods in other languages.

Not included in this proposal but worth considering

  • Static Set.union(...iterables), Set.intersection(...iterables)

Polyfill

Naming

See naming bikeshedding document for details.

We decided to choose:

  • Symmetric difference - symmetricDifference
  • Intersection - intersection
  • Union - union
  • Difference - difference