set

Functional utilities for sets.

Documentation

Features

• Opt-in mutability with remmi
• Reference preservation (mapEach(set, (v) => v) === set)
• Pipe-friendly (pipe(mapEach((v) => v))(set))
• Graceful failure handling (get(), getOr(), getOrElse(), getOrThrow())

Installation

npm install @monstermann/set

pnpm add @monstermann/set

yarn add @monstermann/set

bun add @monstermann/set

Tree-shaking

Installation

npm install -D @monstermann/unplugin-set

pnpm -D add @monstermann/unplugin-set

yarn -D add @monstermann/unplugin-set

bun -D add @monstermann/unplugin-set

Usage

// vite.config.tsimportsetfrom"@monstermann/unplugin-set/vite";exportdefaultdefineConfig({plugins: [set()],});

// rollup.config.jsimportsetfrom"@monstermann/unplugin-set/rollup";exportdefault{plugins: [set()],};

// rolldown.config.jsimportsetfrom"@monstermann/unplugin-set/rolldown";exportdefault{plugins: [set()],};

// webpack.config.jsconstset=require("@monstermann/unplugin-set/webpack");module.exports={plugins: [set()],};

// rspack.config.jsconstset=require("@monstermann/unplugin-set/rspack");module.exports={plugins: [set()],};

// esbuild.config.jsimport{build}from"esbuild";importsetfrom"@monstermann/unplugin-set/esbuild";build({plugins: [set()],});

Set

add

functionSet.add<T>(target: ReadonlySet<T>,value: NoInfer<T>,): ReadonlySet<T>

Returns a set with the value added. If the value already exists in the set, returns the original set unchanged.

Example

import{Set}from"@monstermann/set";Set.add(Set.create([1,2]),3);// Set([1, 2, 3])Set.add(Set.create([1,2]),2);// Set([1, 2])

import{Set}from"@monstermann/set";pipe(Set.create([1,2]),Set.add(3));// Set([1, 2, 3])pipe(Set.create([1,2]),Set.add(2));// Set([1, 2])

addAll

functionSet.addAll<T>(target: ReadonlySet<T>,values: Iterable<NoInfer<T>>,): ReadonlySet<T>

Returns a set with all values from the iterable added. Values that already exist in the set are skipped.

Example

import{Set}from"@monstermann/set";Set.addAll(Set.create([1,2]),[3,4]);// Set([1, 2, 3, 4])Set.addAll(Set.create([1,2]),[2,3]);// Set([1, 2, 3])

import{Set}from"@monstermann/set";pipe(Set.create([1,2]),Set.addAll([3,4]));// Set([1, 2, 3, 4])pipe(Set.create([1,2]),Set.addAll([2,3]));// Set([1, 2, 3])

clone

functionSet.clone<T>(target: ReadonlySet<T>): Set<T>

Returns a shallow copy of the set, unless marked as mutable with markAsMutable inside a mutation context (see @monstermann/remmi).

Example

import{Set}from"@monstermann/set";constoriginal=Set.create([1,2,3]);constcopy=Set.clone(original);// Set { 1, 2, 3 }

import{Set}from"@monstermann/set";constoriginal=Set.create([1,2,3]);constcopy=pipe(original,Set.clone());// Set { 1, 2, 3 }

compact

functionSet.compact<T>(target: ReadonlySet<T>,): ReadonlySet<NonNil<T>>

Returns a set with all null and undefined values removed.

Example

import{Set}from"@monstermann/set";Set.compact(Set.create([1,null,2,undefined]));// Set([1, 2])Set.compact(Set.create([1,2,3]));// Set([1, 2, 3])

import{Set}from"@monstermann/set";pipe(Set.create([1,null,2,undefined]),Set.compact());// Set([1, 2])pipe(Set.create([1,2,3]),Set.compact());// Set([1, 2, 3])

create

functionSet.create<T>(iterable?: Iterable<T>|null|undefined,): Set<T>

Creates a new set from an optional iterable.

Example

import{Set}from"@monstermann/set";Set.create([1,2,3]);// Set([1, 2, 3])

difference

functionSet.difference<T,U>(target: Set<T>,source: Set<U>,): Set<T>

Returns a set containing all values from the target set that are not in the source set.

Example

import{Set}from"@monstermann/set";Set.difference(Set.create([1,2,3]),Set.create([2,3,4]));// Set([1])Set.difference(Set.create([1,2]),Set.create([3,4]));// Set([1, 2])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.difference(Set.create([2,3,4])));// Set([1])pipe(Set.create([1,2]),Set.difference(Set.create([3,4])));// Set([1, 2])

forEach

functionSet.forEach<T>(target: ReadonlySet<T>,fn: (value: NoInfer<T>,target: ReadonlySet<NoInfer<T>>,)=>unknown,): ReadonlySet<T>

Executes a function for each value in the set and returns the set unchanged.

Example

import{Set}from"@monstermann/set";Set.forEach(Set.create([1,2,3]),(value)=>console.log(value));// Set([1, 2, 3])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.forEach((value)=>console.log(value)),);// Set([1, 2, 3])

has

functionSet.has<T>(target: ReadonlySet<T>,value: NoInfer<T>,): boolean

Returns true if the set contains the value, false otherwise.

Example

import{Set}from"@monstermann/set";Set.has(Set.create([1,2,3]),2);// trueSet.has(Set.create([1,2,3]),4);// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.has(2));// truepipe(Set.create([1,2,3]),Set.has(4));// false

hasAll

functionSet.hasAll<T>(target: ReadonlySet<T>,values: Iterable<NoInfer<T>>,): boolean

Returns true if the set contains all values from the iterable, false otherwise.

Example

import{Set}from"@monstermann/set";Set.hasAll(Set.create([1,2,3]),[1,2]);// trueSet.hasAll(Set.create([1,2,3]),[1,4]);// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.hasAll([1,2]));// truepipe(Set.create([1,2,3]),Set.hasAll([1,4]));// false

hasAny

functionSet.hasAny<T>(target: ReadonlySet<T>,values: Iterable<NoInfer<T>>,): boolean

Returns true if the set contains at least one value from the iterable, false otherwise.

Example

import{Set}from"@monstermann/set";Set.hasAny(Set.create([1,2,3]),[3,4]);// trueSet.hasAny(Set.create([1,2,3]),[4,5]);// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.hasAny([3,4]));// truepipe(Set.create([1,2,3]),Set.hasAny([4,5]));// false

hasNone

functionSet.hasNone<T>(target: ReadonlySet<T>,values: Iterable<NoInfer<T>>,): boolean

Returns true if the set contains none of the values from the iterable, false otherwise.

Example

import{Set}from"@monstermann/set";Set.hasNone(Set.create([1,2,3]),[4,5]);// trueSet.hasNone(Set.create([1,2,3]),[3,4]);// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.hasNone([4,5]));// truepipe(Set.create([1,2,3]),Set.hasNone([3,4]));// false

intersection

functionSet.intersection<T,U>(target: Set<T>,source: Set<U>,): Set<T|U>

Returns a set containing only the values that exist in both sets.

Example

import{Set}from"@monstermann/set";Set.intersection(Set.create([1,2,3]),Set.create([2,3,4]));// Set([2, 3])Set.intersection(Set.create([1,2]),Set.create([3,4]));// Set([])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.intersection(Set.create([2,3,4])));// Set([2, 3])pipe(Set.create([1,2]),Set.intersection(Set.create([3,4])));// Set([])

is

functionSet.is(target: unknown): target is Set<unknown>

Returns true if the value is a Set, false otherwise.

Example

import{Set}from"@monstermann/set";Set.is(Set.create([1,2,3]));// trueSet.is([1,2,3]);// falseSet.is({});// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.is());// truepipe([1,2,3],Set.is());// falsepipe({},Set.is());// false

isDisjointFrom

functionSet.isDisjointFrom<T>(target: ReadonlySet<T>,source: ReadonlySet<NoInfer<T>>,): boolean

Returns true if the sets have no values in common, false otherwise.

Example

import{Set}from"@monstermann/set";Set.isDisjointFrom(Set.create([1,2]),Set.create([3,4]));// trueSet.isDisjointFrom(Set.create([1,2]),Set.create([2,3]));// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2]),Set.isDisjointFrom(Set.create([3,4])));// truepipe(Set.create([1,2]),Set.isDisjointFrom(Set.create([2,3])));// false

isEmpty

functionSet.isEmpty<TextendsReadonlySet<unknown>>(target: T,): boolean

Returns true if the set contains no values, false otherwise.

Example

import{Set}from"@monstermann/set";Set.isEmpty(Set.create());// trueSet.isEmpty(Set.create([1,2,3]));// false

import{Set}from"@monstermann/set";pipe(Set.create(),Set.isEmpty());// truepipe(Set.create([1,2,3]),Set.isEmpty());// false

isShallowEqual

functionSet.isShallowEqual<T>(target: ReadonlySet<T>,source: ReadonlySet<NoInfer<T>>,): boolean

Returns true if both sets contain the same values, false otherwise.

Example

import{Set}from"@monstermann/set";Set.isShallowEqual(Set.create([1,2,3]),Set.create([3,2,1]));// trueSet.isShallowEqual(Set.create([1,2]),Set.create([1,2,3]));// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.isShallowEqual(Set.create([3,2,1])));// truepipe(Set.create([1,2]),Set.isShallowEqual(Set.create([1,2,3])));// false

isSubsetOf

functionSet.isSubsetOf<T>(target: ReadonlySet<T>,source: ReadonlySet<NoInfer<T>>,): boolean

Returns true if all values in the target set are also in the source set, false otherwise.

Example

import{Set}from"@monstermann/set";Set.isSubsetOf(Set.create([1,2]),Set.create([1,2,3]));// trueSet.isSubsetOf(Set.create([1,4]),Set.create([1,2,3]));// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2]),Set.isSubsetOf(Set.create([1,2,3])));// truepipe(Set.create([1,4]),Set.isSubsetOf(Set.create([1,2,3])));// false

isSupersetOf

functionSet.isSupersetOf<T>(target: ReadonlySet<T>,source: ReadonlySet<NoInfer<T>>,): boolean

Returns true if the target set contains all values from the source set, false otherwise.

Example

import{Set}from"@monstermann/set";Set.isSupersetOf(Set.create([1,2,3]),Set.create([1,2]));// trueSet.isSupersetOf(Set.create([1,2,3]),Set.create([1,4]));// false

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.isSupersetOf(Set.create([1,2])));// truepipe(Set.create([1,2,3]),Set.isSupersetOf(Set.create([1,4])));// false

mapEach

functionSet.mapEach<T,U>(target: ReadonlySet<T>,fn: (value: NoInfer<T>,target: ReadonlySet<NoInfer<T>>,)=>U,): ReadonlySet<U>

Returns a new set with each value transformed by the mapping function.

Example

import{Set}from"@monstermann/set";Set.mapEach(Set.create([1,2,3]),(x)=>x*2);// Set([2, 4, 6])Set.mapEach(Set.create(["a","b"]),(x)=>x.toUpperCase());// Set(['A', 'B'])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.mapEach((x)=>x*2),);// Set([2, 4, 6])pipe(Set.create(["a","b"]),Set.mapEach((x)=>x.toUpperCase()),);// Set(['A', 'B'])

remove

functionSet.remove<T>(target: ReadonlySet<T>,value: NoInfer<T>,): ReadonlySet<T>

Returns a set with the value removed. If the value doesn't exist in the set, returns the original set unchanged.

Example

import{Set}from"@monstermann/set";Set.remove(Set.create([1,2,3]),2);// Set([1, 3])Set.remove(Set.create([1,2,3]),4);// Set([1, 2, 3])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.remove(2));// Set([1, 3])pipe(Set.create([1,2,3]),Set.remove(4));// Set([1, 2, 3])

removeAll

functionSet.removeAll<T>(target: ReadonlySet<T>,values: Iterable<NoInfer<T>>,): ReadonlySet<T>

Returns a set with all values from the iterable removed. Values that don't exist in the set are skipped.

Example

import{Set}from"@monstermann/set";Set.removeAll(Set.create([1,2,3,4]),[2,3]);// Set([1, 4])Set.removeAll(Set.create([1,2,3]),[4,5]);// Set([1, 2, 3])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3,4]),Set.removeAll([2,3]));// Set([1, 4])pipe(Set.create([1,2,3]),Set.removeAll([4,5]));// Set([1, 2, 3])

size

functionSet.size<TextendsReadonlySet<unknown>>(target: T,): number

Returns the number of values in the set.

Example

import{Set}from"@monstermann/set";Set.size(Set.create([1,2,3]));// 3Set.size(Set.create());// 0

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.size());// 3pipe(Set.create(),Set.size());// 0

symmetricDifference

functionSet.symmetricDifference<T,U>(target: Set<T>,source: Set<U>,): Set<T|U>

Returns a set containing values that exist in either set but not in both.

Example

import{Set}from"@monstermann/set";Set.symmetricDifference(Set.create([1,2,3]),Set.create([3,4,5]));// Set([1, 2, 4, 5])Set.symmetricDifference(Set.create([1,2]),Set.create([3,4]));// Set([1, 2, 3, 4])

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.symmetricDifference(Set.create([3,4,5])));// Set([1, 2, 4, 5])pipe(Set.create([1,2]),Set.symmetricDifference(Set.create([3,4])));// Set([1, 2, 3, 4])

toArray

functionSet.toArray<T>(target: ReadonlySet<T>): T[]

Converts the set to an array.

Example

import{Set}from"@monstermann/set";Set.toArray(Set.create([1,2,3]));// [1, 2, 3]Set.toArray(Set.create(["a","b"]));// ['a', 'b']

import{Set}from"@monstermann/set";pipe(Set.create([1,2,3]),Set.toArray());// [1, 2, 3]pipe(Set.create(["a","b"]),Set.toArray());// ['a', 'b']

union

functionSet.union<T,U>(target: Set<T>,source: Set<U>,): Set<T|U>

Returns a set containing all values from both sets.

Example

import{Set}from"@monstermann/set";Set.union(Set.create([1,2]),Set.create([2,3,4]));// Set([1, 2, 3, 4])Set.union(Set.create([1,2]),Set.create([3,4]));// Set([1, 2, 3, 4])

import{Set}from"@monstermann/set";pipe(Set.create([1,2]),Set.union(Set.create([2,3,4])));// Set([1, 2, 3, 4])pipe(Set.create([1,2]),Set.union(Set.create([3,4])));// Set([1, 2, 3, 4])