New Set methods

See formal spec WIP.

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

(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

• 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

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

• C# HashSet
• F# - Collections.Set
• Haskell - Data.Set
• Python - set/frozenset
• Hack - HH\Set
• Ruby - Set

.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
  • Consistent with other languages (eg. LINQ .intersect method)
• 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)

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.

Not included in this proposal but worth considering

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

Naming

Symmetric difference

Proposed names: xor, symmetricDifference, disjointUnion

Intersection

Proposed names: intersect, intersection.

Union

Proposed names: union, concat.

Difference

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