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

• Map#map and Map#filter
• Map.prototype.map and Map.prototype.filter (spec) + Set
• Map: filter/map and more
• Original topic regarding this proposal
• Newer topic regarding this proposal

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

• Zet implements the features of this proposal. It includes static versions of all methods, and also implements map, filter and reduce for Sets.
• 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

• core-js/packages/core-js/features/set/
• set-extensions

Naming

See naming bikeshedding document for details.

We decided to choose:

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