shelving/util/setmodule

Typed helpers for working with JavaScript Set objects. Covers type guards, conversion, membership checks, and mutable add/delete operations.

Things to know:

  • ImmutableSet<T> is an alias for ReadonlySet<T>; MutableSet<T> is Set<T>. Use immutable types in function signatures where you don't need to mutate.
  • addSetItem() mutates the set in place and returns the item — handy for chaining or registering items by reference.
  • limitSet() returns the original set reference unchanged when the limit is greater than or equal to the set size.

Usage

Type guards and conversion

ts
import { isSet, assertSet, getSet } from "shelving/util";

isSet(new Set([1, 2]));  // true
isSet([1, 2]);           // false
assertSet("oops");       // throws RequiredError

getSet([1, 2, 2, 3]);    // Set { 1, 2, 3 }  (deduplicates)
getSet(new Set([1, 2])); // same reference returned

Membership checks

ts
import { isSetItem, assertSetItem } from "shelving/util";

const roles = new Set(["admin", "editor"]);

isSetItem(roles, "admin");   // true
isSetItem(roles, "guest");   // false
assertSetItem(roles, "guest"); // throws RequiredError

Mutating a set

ts
import { addSetItem, addSetItems, deleteSetItems } from "shelving/util";

const s: Set<string> = new Set();

addSetItem(s, "a");           // adds "a", returns "a"
addSetItems(s, "b", "c");     // adds "b" and "c"
deleteSetItems(s, "a", "b");  // removes "a" and "b"

Limiting a set

ts
import { limitSet } from "shelving/util";

const s = new Set([1, 2, 3, 4, 5]);
limitSet(s, 3);  // Set { 1, 2, 3 }
limitSet(s, 10); // same Set reference (no copy needed)

Functions

Go

isSet()function

Is an unknown value a set?

isSet(value: unknown): value is ImmutableSet
Go

assertSet()function

Assert that a value is a Set instance.

assertSet(value: unknown, caller: AnyCaller = assertSet): asserts value is ImmutableSet
Go

getSet()function

Convert a possible set to a Set.

getSet(value: PossibleSet<T>): ImmutableSet
Go

limitSet()function

Apply a limit to a set.

limitSet(set: ImmutableSet<T>, limit: number): ImmutableSet<T>
Go

isSetItem()function

Is an unknown value an item in a set?

isSetItem(set: ImmutableSet<T>, item: unknown): item is T
Go

assertSetItem()function

Assert that an unknown value is an item in a set.

assertSetItem(set: ImmutableSet<T>, item: unknown, caller: AnyCaller = assertSetItem): asserts item is T
Go

addSetItem()function

Add an item to a set (by reference) and return the set item.

addSetItem(set: MutableSet<T>, item: T): T
Go

addSetItems()function

Add multiple items to a set (by reference).

addSetItems(set: MutableSet<T>, ...items: T[]): void
Go

deleteSetItems()function

Remove multiple items from a set (by reference).

deleteSetItems(set: MutableSet<T>, ...items: T[]): void

Types

Go

ImmutableSettype

Set that cannot be changed.

ReadonlySet<T>
Go

MutableSettype

Set that can be changed.

Set<T>
Go

PossibleSettype

Things that can be converted to sets.

ImmutableSet<T> | Iterable<T>
Go

SetItemtype

Get the type of the items in a set.

X extends ReadonlySet<infer Y> ? Y : never