Strawman for new Set methods
Switch branches/tags
Nothing to show
Clone or download
Ginden Merge pull request #29 from michaelficarra/patch-1
fix intersection naming in README
Latest commit a70a573 May 29, 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.