Strawman for new Set methods
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
docs Changed naming before TC39 meeting May 21, 2018
spec Rename to intersection May 22, 2018
test Splitting proposal into two. Jan 27, 2018
package.json SpeciesConstructor Oct 20, 2017
polyfill.js Updated polyfill to closer match spec Feb 25, 2018

New Set methods

See formal spec WIP.

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

(Semi)relevant previous discussions


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


  • 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)

Comparision with Immutable.js

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

Comparison with other languages


Java Set interface is rather limited and doesn't include APIs found in this proposal.

Though, Java 8 introduces stream API that allow to deal with arbitrary collections.

Stream API has methods from this proposal like union (as concat).

Stream API nor Set does not include intersection, xor.

Other languages

.union, .intersection etc. desired signature

Signature of these functions isn't obvious. They can accept:

  • single Set
    • best possible performance
    • would slowdown adoption
  • multiple Sets
    • looks like rare use case
  • Single iterable
  • Multiple iterables
    • Used by Immutable.js
    • Certain algorithms can be ineffective without converting arguments to Set instances (intersection without at least log(n) random access seems to be too slow for real world)


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.

Not included in this proposal but worth considering

  • Set.prototype.isSubsetOf(otherSet)
  • Set.prototype.isSupersetOf(iterable)
  • Static Set.union(...iterables), Set.intersection(...iterables)


Symmetric difference

Proposed names: xor, symmetricDifference, disjointUnion


Proposed names: intersect, intersection.


Proposed names: union, concat.


Proposed names: difference, minus, except, without, withoutAll, relativeComplement.