Extended Set

ExtendedSet extends the native JavaScript Set with functional programming methods (map, filter, reduce) and set-theory operations (union, intersection, difference, isSuperSetOf, isSubSetOf).

Set-theory methods delegate to the native ES2024 Set methods when available, falling back to a custom implementation for older environments.

Installation

npm install @cahmoraes93/extended-set

API

of (static)

Creates a new ExtendedSet from an array.

const set = ExtendedSet.of([1, 2, 3])
console.log(set.toString()) // 1,2,3

map

Maps each element through a callback and returns a new ExtendedSet.

const set = new ExtendedSet<number>([2, 3, 10])
const result = set.map((item) => item * 2)
console.log(result) // ExtendedSet {4, 6, 20}

filter

Filters elements through a predicate and returns a new ExtendedSet.

const set = new ExtendedSet<number>([1, 2, 3, 4, 5])
const evenSet = set.filter((item) => item % 2 === 0)
console.log(evenSet) // ExtendedSet {2, 4}

reduce

Reduces the set to a single value. Optionally accepts an initialValue; if omitted, the first element is used as the accumulator.

const set = new ExtendedSet<number>([2, 3, 0, 5, 20])
const smallest = set.reduce((acc, item) => (acc > item ? item : acc))
console.log(smallest) // 0

const sum = set.reduce((acc, item) => acc + item, 0)
console.log(sum) // 30

find

Returns the first element that satisfies the predicate, or null if none is found.

const users = [{ name: 'John' }, { name: 'George' }, { name: 'Jackie' }]
const set = ExtendedSet.of(users)

const george = set.find((item) => item.name === 'George')
console.log(george) // { name: 'George' }

const annie = set.find((item) => item.name === 'Annie')
console.log(annie) // null

every

Returns true if every element satisfies the predicate.

const set = ExtendedSet.of([1, 2, 3])
console.log(set.every((n) => n > 0)) // true
console.log(set.every((n) => n < 0)) // false

some

Returns true if at least one element satisfies the predicate.

const set = ExtendedSet.of([1, -2, 3, 4])
console.log(set.some((n) => n < 0)) // true
console.log(set.some((n) => n === 0)) // false

toArray

Returns a plain array from the set.

const set = new ExtendedSet<number>([1, 2, 3, 4, 5])
console.log(set.toArray()) // [1, 2, 3, 4, 5]

isSuperSetOf

Returns true if the set contains every element of other.

const set_1 = new ExtendedSet<number>([1, 2, 3, 4])
const set_2 = new ExtendedSet<number>([1, 2])
console.log(set_1.isSuperSetOf(set_2)) // true

isSubSetOf

Returns true if every element of the set is contained in other.

const set_1 = new ExtendedSet<number>([1, 2])
const set_2 = new ExtendedSet<number>([1, 2, 3, 4])
console.log(set_1.isSubSetOf(set_2)) // true

union

Returns a new ExtendedSet containing all elements from both sets (A ∪ B). Accepts one set at a time; chain calls for multiple unions.

const set_1 = new ExtendedSet<number>([1, 2, 3, 4])
const set_2 = new ExtendedSet<number>([1, 5])
const set_3 = new ExtendedSet<number>([6, 2])

const result = set_1.union(set_2).union(set_3)
console.log(result) // ExtendedSet {1, 2, 3, 4, 5, 6}

intersection

Returns a new ExtendedSet with elements present in both sets (A ∩ B).

const set_1 = new ExtendedSet<number>([1, 2, 3, 4])
const set_2 = new ExtendedSet<number>([1, 4])
const result = set_1.intersection(set_2)
console.log(result) // ExtendedSet {1, 4}

difference

Returns a new ExtendedSet with elements in the set that are not in other (A − B).

const set_1 = new ExtendedSet<number>([1, 2, 3, 4])
const set_2 = new ExtendedSet<number>([1, 4])
const result = set_1.difference(set_2)
console.log(result) // ExtendedSet {2, 3}

Native ES2024 fallback

union, intersection and difference use the native Set methods introduced in ES2024 when available, and fall back to a custom implementation automatically — no configuration required.