website/docs/Set.mdx - main - githubmirror/immutable-js

website/docs/Set.mdx
860 строк26 KB
Julien Deniau
Doc as mdx instead of export from .d.ts file (#2104)
24 май 2025, 00:47
24 май 2025, 00:4721de701
import Repl from '@/repl/Repl.tsx';
import CodeLink from '@/mdx-components/CodeLink.tsx';

# Set

A Collection of unique values with `O(log32 N)` adds and has.

<Signature code={`type Set<T> extends Collection.Set<T>`} />

When iterating a Set, the entries will be (value, value) pairs. Iteration order of a Set is undefined, however is stable. Multiple iterations of the same Set will iterate in the same order.

Set values, like Map keys, may be of any type. Equality is determined by `Immutable.is` enabling Sets to uniquely include other Immutable collections, custom value types, and NaN.

## Construction

<MemberLabel label="Set()" />

Create a new Immutable Set.

<Signature code={`Set<T>(collection?: Iterable<T> | ArrayLike<T>): Set<T>`} />

Note: `Set` is a factory function and not a class, and does not use the `new` keyword during construction.

<Repl defaultValue={`Set()`} />

## Static Methods

<MemberLabel label="Set.isSet()" />

True if the provided value is a Set.

<Signature code={`Set.isSet(maybeSet: unknown): boolean`} />

<MemberLabel label="Set.of()" />

Creates a new Set containing `values`.

<Signature code={`Set.of<T>(...values: Array<T>): Set<T>`} />

<MemberLabel label="Set.fromKeys()" />

`Set.fromKeys()` creates a new immutable Set containing the keys from this Collection or JavaScript Object.

<Signature
  code={`Set.fromKeys<T>(iter: Collection.Keyed<T, unknown>): Set<T>
Set.fromKeys<T>(iter: Collection<T, unknown>): Set<T>
Set.fromKeys(obj: { [key: string]: unknown }): Set<string>`}
/>

<MemberLabel label="Set.intersect()" />

Creates a Set that contains every value shared between all of the provided Sets.

<Signature code={`Set.intersect<T>(sets: Iterable<Iterable<T>>): Set<T>`} />

<Repl defaultValue={`Set.intersect([ Set([ 1, 2, 3 ]), Set([ 2, 3, 4 ]) ])`} />

<MemberLabel label="Set.union()" />

Creates a Set that contains all values contained in any of the provided Sets.

<Signature code={`Set.union<T>(sets: Iterable<Iterable<T>>): Set<T>`} />

<Repl defaultValue={`Set.union([ Set([ 1, 2, 3 ]), Set([ 2, 3, 4 ]) ])`} />

## Members

<MemberLabel label="size" />

The number of items in this Set.

<Signature code={`size: number`} />

## Persistent changes

<MemberLabel label="add()" />

Returns a new Set which includes this value.

<Signature code={`add(value: T): Set<T>`} />

Note: `add` can be used in `withMutations`.

<MemberLabel label="delete()" alias="remove()" />

Returns a new Set which excludes this value.

<Signature code={`delete(value: T): Set<T>`} />

Note: `delete` cannot be safely used in IE8, use `remove` if supporting old browsers.

Note: `delete` can be used in `withMutations`.

<MemberLabel label="clear()" />

Returns a new Set containing no values.

<Signature code={`clear(): Set<T>`} />

Note: `clear` can be used in `withMutations`.

<MemberLabel label="union()" alias="merge, concat" />

Returns a Set including any value from `collections` that does not already exist in this Set.

<Signature code={`union<C>(...collections: Array<Iterable<C>>): Set<T | C>`} />

Note: `union` can be used in `withMutations`.

<MemberLabel label="intersect()" />

Returns a Set which has removed any values not also contained within `collections`.

<Signature code={`intersect(...collections: Array<Iterable<T>>): Set<T>`} />

Note: `intersect` can be used in `withMutations`.

<MemberLabel label="subtract()" />

Returns a Set excluding any values contained within `collections`.

<Signature code={`subtract(...collections: Array<Iterable<T>>): Set<T>`} />

<Repl defaultValue={`Set([ 1, 2, 3 ]).subtract([1, 3])`} />

Note: `subtract` can be used in `withMutations`.

## Transient changes

<MemberLabel label="withMutations()" />

Note: Not all methods can be used on a mutable collection or within `withMutations`! Check the documentation for each method to see if it allows being used in `withMutations`.

<Signature
  code={`withMutations(mutator: (mutable: this) => unknown): Set<T>`}
/>

<MemberLabel label="asMutable()" />

<Signature code={`asMutable(): Set<T>`} />

Note: Not all methods can be used on a mutable collection or within `withMutations`! Check the documentation for each method to see if it allows being used in `withMutations`.

<MemberLabel label="wasAltered()" />

Returns true if this is a mutable copy (see `asMutable()`) and mutative alterations have been applied.

<Signature code={`wasAltered(): boolean`} />

<MemberLabel label="asImmutable()" />

The yin to `asMutable`'s yang. Because it applies to mutable collections, this operation is _mutable_ and may return itself (though may not return itself, i.e. if the result is an empty collection). Once performed, the original mutable copy must no longer be mutated since it may be the immutable result.

<Signature code={`asImmutable(): Set<T>`} />

If possible, use `withMutations` to work with temporary mutable copies as it provides an easier to use API and considers many common optimizations.

## Sequence algorithms

<MemberLabel label="map()" />

Returns a new Set with values passed through a `mapper` function.

<Signature
  code={`map<M>(mapper: (value: T, key: T, iter: this) => M, context?: unknown): Set<M>`}
/>

<Repl defaultValue={`Set([ 1, 2 ]).map(x => 10 * x)`} />

<MemberLabel label="flatMap()" />

Flat-maps the Set, returning a new Set.

Similar to `set.map(...).flatten(true)`.

<Signature
  code={`flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>, context?: unknown): Set<M>`}
/>

<MemberLabel label="filter()" />

Returns a new Set with only the values for which the `predicate` function returns true.

Note: `filter()` always returns a new instance, even if it results in not filtering out any values.

<Signature
  code={`filter(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

<MemberLabel label="filterNot()" />

Returns a new Set with only the values for which the `predicate` function returns false.

<Signature
  code={`filterNot(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

Note: `filterNot()` always returns a new instance, even if it results in not filtering out any values.

<MemberLabel label="partition()" />

Returns a new Set with the values for which the `predicate` function returns false and another for which is returns true.

<Signature
  code={`partition(predicate: (this: C, value: T, key: T, iter: this) => boolean, context?: C): [Set<T>, Set<T>]`}
/>

<MemberLabel label="sort()" />

Returns an OrderedSet of the same type which includes the same entries, stably sorted by using a `comparator`.

<Signature code={`sort(comparator?: Comparator<T>): OrderedSet<T>`} />

If a `comparator` is not provided, a default comparator uses `<` and `>`.

`comparator(valueA, valueB)`:

- Returns `0` if the elements should not be swapped.
- Returns `-1` (or any negative number) if `valueA` comes before `valueB`
- Returns `1` (or any positive number) if `valueA` comes after `valueB`
- Alternatively, can return a value of the `PairSorting` enum type
- Is pure, i.e. it must always return the same value for the same pair of values.

Note: `sort()` Always returns a new instance, even if the original was already sorted.

Note: This is always an eager operation.

<MemberLabel label="sortBy()" />

Like `sort`, but also accepts a `comparatorValueMapper` which allows for sorting by more sophisticated means:

<Signature
  code={`sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C, comparator?: (valueA: C, valueB: C) => number): this & OrderedSet<T>`}
/>

<Repl
  defaultValue={`Set([
    { name: 'Bob', age: 30 },
    { name: 'Max', age: 25 },
    { name: 'Lili', age: 35 }
  ]).sortBy(person => person.age)`}
/>

Note: `sortBy()` Always returns a new instance, even if the original was already sorted.

Note: This is always an eager operation.

<MemberLabel label="reverse()" />

Returns a new Set with the order of the values reversed.

<Signature code={`reverse(): Set<T>`} />

<MemberLabel label="groupBy()" />

Returns a `Map` of `Set`, grouped by the return value of the `grouper` function.

<Signature
  code={`groupBy<G>(grouper: (value: T, key: T, iter: this) => G, context?: unknown): Map<G, Set<T>>`}
/>

Note: This is not a lazy operation.

## Conversion to JavaScript types

<MemberLabel label="toJS()" />

Deeply converts this Set to equivalent native JavaScript Array.

<Signature code={`toJS(): Array<DeepCopy<T>>`} />

<MemberLabel label="toJSON()" />

Shallowly converts this Set to equivalent native JavaScript Array.

<Signature code={`toJSON(): Array<T>`} />

<MemberLabel label="toArray()" />

Shallowly converts this collection to an Array.

<Signature code={`toArray(): Array<T>`} />

<MemberLabel label="toObject()" />

Shallowly converts this Collection to an Object.

<Signature code={`toObject(): { [key: string]: T }`} />

Converts keys to Strings.

## Conversion to Seq

<MemberLabel label="toSeq()" />

Returns itself.

<Signature code={`toSeq(): Seq.Set<T>`} />

<MemberLabel label="toKeyedSeq()" />

Returns a Seq.Keyed from this Collection where indices are treated as keys.

This is useful if you want to operate on a Collection and preserve the [value, value] pairs.

<Signature code={`toKeyedSeq(): Seq.Keyed<T, T>`} />

<MemberLabel label="toIndexedSeq()" />

Returns an Seq.Indexed of the values of this Collection, discarding keys.

<Signature code={`toIndexedSeq(): Seq.Indexed<T>`} />

<MemberLabel label="toSetSeq()" />

Returns a Seq.Set of the values of this Collection, discarding keys.

<Signature code={`toSetSeq(): Seq.Set<T>`} />

## Value equality

<MemberLabel label="equals()" />

True if this and the other Collection have value equality, as defined by `Immutable.is()`.

<Signature code={`equals(other): boolean`} />

Note: This is equivalent to `Immutable.is(this, other)`, but provided to allow for chained expressions.

<MemberLabel label="hashCode()" />

Computes and returns the hashed identity for this Collection.

The `hashCode` of a Collection is used to determine potential equality, and is used when adding this to a `Set` or as a key in a `Map`, enabling lookup via a different instance.

<Signature code={`hashCode(): number`} />

<Repl
  defaultValue={`const a = Set([ 1, 2, 3 ]);
const b = Set([ 1, 2, 3 ]);
assert.notStrictEqual(a, b); // different instances
const set = Set([ a ]);
assert.equal(set.has(b), true);`}
/>

If two values have the same `hashCode`, they are [not guaranteed to be equal][Hash Collision]. If two values have different `hashCode`s, they must not be equal.

[Hash Collision]: https://en.wikipedia.org/wiki/Collision_(computer_science)

## Reading values

<MemberLabel label="get()" />

Returns the value associated with the provided key, or notSetValue if the Collection does not contain this key.

Note: it is possible a key may be associated with an `undefined` value, so if `notSetValue` is not provided and this method returns `undefined`, that does not guarantee the key was not found.

<Signature
  code={`get<NSV>(key: T, notSetValue: NSV): T | NSV
get(key: T): T | undefined`}
/>

<MemberLabel label="has()" />

True if a key exists within this Collection, using `Immutable.is` to determine equality.

<Signature code={`has(key: T): boolean`} />

<MemberLabel label="includes()" alias="contains()" />

True if a value exists within this `Collection`, using `Immutable.is` to determine equality.

<Signature code={`includes(value: T): boolean`} />

<MemberLabel label="first()" />

Returns the first value in this Collection.

<Signature
  code={`first<NSV>(notSetValue: NSV): T | NSV
first(): T | undefined`}
/>

<MemberLabel label="last()" />

Returns the last value in this Collection.

<Signature
  code={`last<NSV>(notSetValue: NSV): T | NSV
last(): T | undefined`}
/>

## Reading deep values

<MemberLabel label="getIn()" />

Returns the value found by following a path of keys or indices through nested Collections.

<Signature
  code={`getIn(searchKeyPath: Iterable<unknown>, notSetValue?: unknown): unknown`}
/>

<Repl
  defaultValue={`const deepSet = Set([Set([1, 2, 3])]);
deepSet.getIn([0, 1])`}
/>

Plain JavaScript Object or Arrays may be nested within an Immutable.js Collection, and getIn() can access those values as well:

<Repl
  defaultValue={`const deepSet = Set([{ a: 1, b: 2 }]);
deepSet.getIn([0, 'b'])`}
/>

<MemberLabel label="hasIn()" />

True if the result of following a path of keys or indices through nested Collections results in a set value.

<Signature code={`hasIn(searchKeyPath: Iterable<unknown>): boolean`} />

## Conversion to Collections

<MemberLabel label="toMap()" />

Converts this Collection to a Map, Throws if keys are not hashable.

<Signature code={`toMap(): Map<T, T>`} />

Note: This is equivalent to `Map(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

<MemberLabel label="toOrderedMap()" />

Converts this Collection to a Map, maintaining the order of iteration.

<Signature code={`toOrderedMap(): OrderedMap<T, T>`} />

Note: This is equivalent to `OrderedMap(this.toKeyedSeq())`, but provided for convenience and to allow for chained expressions.

<MemberLabel label="toSet()" />

Returns itself.

<Signature code={`toSet(): Set<T>`} />

<MemberLabel label="toOrderedSet()" />

Converts this Collection to a Set, maintaining the order of iteration.

<Signature code={`toOrderedSet(): OrderedSet<T>`} />

Note: This is equivalent to `OrderedSet(this)`, but provided for convenience and to allow for chained expressions.

<MemberLabel label="toList()" />

Converts this Collection to a List.

<Signature code={`toList(): List<T>`} />

<MemberLabel label="toStack()" />

Converts this Collection to a Stack, discarding keys. Throws if values are not hashable.

<Signature code={`toStack(): Stack<T>`} />

Note: This is equivalent to `Stack(this)`, but provided to allow for chained expressions.

## Iterators

<MemberLabel label="keys()" />

An iterator of this `Set`'s keys.

<Signature code={`keys(): IterableIterator<T>`} />

Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `keySeq` instead, if this is what you want.

<MemberLabel label="values()" />

An iterator of this `Set`'s values.

<Signature code={`values(): IterableIterator<T>`} />

Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `valueSeq` instead, if this is what you want.

<MemberLabel label="entries()" />

An iterator of this `Set`'s entries as `[value, value]` tuples.

<Signature code={`entries(): IterableIterator<[T, T]>`} />

Note: this will return an ES6 iterator which does not support Immutable.js sequence algorithms. Use `entrySeq` instead, if this is what you want.

## Collections (Seq)

<MemberLabel label="keySeq()" />

Returns a new Seq.Indexed of the keys of this Collection, discarding values.

<Signature code={`keySeq(): Seq.Indexed<T>`} />

<MemberLabel label="valueSeq()" />

Returns an Seq.Indexed of the values of this Collection, discarding keys.

<Signature code={`valueSeq(): Seq.Indexed<T>`} />

<MemberLabel label="entrySeq()" />

Returns a new Seq.Indexed of [value, value] tuples.

<Signature code={`entrySeq(): Seq.Indexed<[T, T]>`} />

## Side effects

<MemberLabel label="forEach()" />

The `sideEffect` is executed for every entry in the Collection.

<Signature
  code={`forEach(sideEffect: (value: T, key: T, iter: this) => unknown, context?: unknown): number`}
/>

Unlike `Array#forEach`, if any call of `sideEffect` returns `false`, the iteration will stop. Returns the number of entries iterated (including the last iteration which returned false).

## Creating subsets

<MemberLabel label="slice()" />

Returns a new Set of the same type representing a portion of this Set from start up to but not including end.

<Signature code={`slice(begin?: number, end?: number): Set<T>`} />

If begin is negative, it is offset from the end of the Collection. e.g. `slice(-2)` returns a Collection of the last two entries. If it is not provided the new Collection will begin at the beginning of this Collection.

If end is negative, it is offset from the end of the Collection. e.g. `slice(0, -1)` returns a Collection of everything but the last entry. If it is not provided, the new Collection will continue through the end of this Collection.

If the requested slice is equivalent to the current Collection, then it will return itself.

<MemberLabel label="rest()" />

Returns a new Collection of the same type containing all entries except the first.

<Signature code={`rest(): Set<T>`} />

<MemberLabel label="butLast()" />

Returns a new Collection of the same type containing all entries except the last.

<Signature code={`butLast(): Set<T>`} />

<MemberLabel label="skip()" />

Returns a new Collection of the same type which excludes the first `amount` entries from this Collection.

<Signature code={`skip(amount: number): Set<T>`} />

<MemberLabel label="skipLast()" />

Returns a new Collection of the same type which excludes the last `amount` entries from this Collection.

<Signature code={`skipLast(amount: number): Set<T>`} />

<MemberLabel label="skipWhile()" />

Returns a new Collection of the same type which includes entries starting from when `predicate` first returns false.

<Signature
  code={`skipWhile(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

<Repl
  defaultValue={`Set([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipWhile(x => x.match(/g/))`}
/>

<MemberLabel label="skipUntil()" />

Returns a new Collection of the same type which includes entries starting from when `predicate` first returns true.

<Signature
  code={`skipUntil(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

<Repl
  defaultValue={`Set([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .skipUntil(x => x.match(/hat/))`}
/>

<MemberLabel label="take()" />

Returns a new Collection of the same type which includes the first `amount` entries from this Collection.

<Signature code={`take(amount: number): Set<T>`} />

<MemberLabel label="takeLast()" />

Returns a new Collection of the same type which includes the last `amount` entries from this Collection.

<Signature code={`takeLast(amount: number): Set<T>`} />

<MemberLabel label="takeWhile()" />

Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns true.

<Signature
  code={`takeWhile(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

<Repl
  defaultValue={`Set([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeWhile(x => x.match(/o/))`}
/>

<MemberLabel label="takeUntil()" />

Returns a new Collection of the same type which includes entries from this Collection as long as the `predicate` returns false.

<Signature
  code={`takeUntil(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): Set<T>`}
/>

<Repl
  defaultValue={`Set([ 'dog', 'frog', 'cat', 'hat', 'god' ])
  .takeUntil(x => x.match(/at/))`}
/>

## Combination

<MemberLabel label="concat()" />

Returns a new Set with other collections concatenated to this one.

<Signature
  code={`concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Set<T | C>`}
/>

<MemberLabel label="flatten()" />

Flattens nested Collections.

Will deeply flatten the Collection by default, returning a Collection of the same type, but a `depth` can be provided in the form of a number or boolean (where true means to shallowly flatten one level). A depth of 0 (or shallow: false) will deeply flatten.

Flattens only others Collection, not Arrays or Objects.

<Signature
  code={`flatten(depth?: number): this
flatten(shallow?: boolean): this`}
/>

<MemberLabel label="flatMap()" />

Flat-maps the Set, returning a new Set.

Similar to `set.map(...).flatten(true)`.

<Signature
  code={`flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>, context?: unknown): Set<M>`}
/>

## Reducing a value

<MemberLabel label="reduce()" />

Reduces the Iterable to a value by calling the `reducer` for every entry in the Iterable and passing along the reduced value.

<Signature
  code={`reduce<R>(reducer: (reduced: R, value: T, key: T, iter: this) => R, initialValue: R): R`}
/>

If initialValue is not provided, the first entry in the Iterable will be used as the initial value.

<MemberLabel label="reduceRight()" />

Reduces the Iterable to a value by calling the `reducer` for every entry in the Iterable and passing along the reduced value.

<Signature
  code={`reduceRight<R>(reducer: (reduced: R, value: T, key: T, iter: this) => R, initialValue: R): R`}
/>

Note: Similar to this.reverse().reduce(), and provided for parity with `Array#reduceRight`.

<MemberLabel label="every()" />

Returns true if the `predicate` returns true for every entry in the Iterable.

<Signature
  code={`every(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): boolean`}
/>

<MemberLabel label="some()" />

Returns true if the `predicate` returns true for any entry in the Iterable.

<Signature
  code={`some(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): boolean`}
/>

<MemberLabel label="join()" />

Returns a string of all the entries in the Iterable, separated by `separator`.

<Signature code={`join(separator?: string): string`} />

<MemberLabel label="isEmpty()" />

Returns true if the Iterable is empty.

<Signature code={`isEmpty(): boolean`} />

<MemberLabel label="count()" />

Returns the number of entries in the Iterable.

<Signature code={`count(): number`} />

<MemberLabel label="countBy()" />

Returns a Map of the number of occurrences of each value in the Iterable.

<Signature
  code={`countBy<G>(grouper: (value: T, key: T, iter: this) => G, context?: unknown): Map<G, number>`}
/>

## Search for value

<MemberLabel label="find()" />

Returns the first value for which the `predicate` returns true.

<Signature
  code={`find(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown, notSetValue?: T): T | undefined`}
/>

<MemberLabel label="findLast()" />

Returns the last value for which the `predicate` returns true.

<Signature
  code={`findLast(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown, notSetValue?: T): T | undefined`}
/>

Note: `predicate` will be called for each entry in reverse.

<MemberLabel label="findEntry()" />

Returns the first [value, value] entry for which the `predicate` returns true.

<Signature
  code={`findEntry(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown, notSetValue?: T): [T, T] | undefined`}
/>

<MemberLabel label="findLastEntry()" />

Returns the last [value, value] entry for which the `predicate` returns true.

<Signature
  code={`findLastEntry(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown, notSetValue?: T): [T, T] | undefined`}
/>

Note: `predicate` will be called for each entry in reverse.

<MemberLabel label="findKey()" />

Returns the first key for which the `predicate` returns true.

<Signature
  code={`findKey(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): T | undefined`}
/>

<MemberLabel label="findLastKey()" />

Returns the last key for which the `predicate` returns true.

<Signature
  code={`findLastKey(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): T | undefined`}
/>

Note: `predicate` will be called for each entry in reverse.

<MemberLabel label="keyOf()" />

Returns the key associated with the search value, or undefined.

<Signature code={`keyOf(searchValue: T): T | undefined`} />

<MemberLabel label="lastKeyOf()" />

Returns the last key associated with the search value, or undefined.

<Signature code={`lastKeyOf(searchValue: T): T | undefined`} />

<MemberLabel label="max()" />

Returns the maximum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

<Signature code={`max(comparator?: Comparator<T>): T | undefined`} />

The comparator is used in the same way as `Collection#sort`. If it is not provided, the default comparator is `>`.

When two values are considered equivalent, the first encountered will be returned. Otherwise, `max` will operate independent of the order of input as long as the comparator is commutative. The default comparator `>` is commutative only when types do not differ.

If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

<MemberLabel label="maxBy()" />

Like `max`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

<Signature
  code={`maxBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C, comparator?: Comparator<C>): T | undefined`}
/>

<Repl
  defaultValue={`Set([
    { name: 'Bob', age: 30 },
    { name: 'Max', age: 25 },
    { name: 'Lili', age: 35 }
  ]).maxBy(person => person.age)`}
/>

<MemberLabel label="min()" />

Returns the minimum value in this collection. If any values are comparatively equivalent, the first one found will be returned.

<Signature code={`min(comparator?: Comparator<T>): T | undefined`} />

The comparator is used in the same way as `Collection#sort`. If it is not provided, the default comparator is `<`.

When two values are considered equivalent, the first encountered will be returned. Otherwise, `min` will operate independent of the order of input as long as the comparator is commutative. The default comparator `<` is commutative only when types do not differ.

If `comparator` returns 0 and either value is NaN, undefined, or null, that value will be returned.

<MemberLabel label="minBy()" />

Like `min`, but also accepts a `comparatorValueMapper` which allows for comparing by more sophisticated means:

<Signature
  code={`minBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C, comparator?: Comparator<C>): T | undefined`}
/>

<Repl
  defaultValue={`Set([
    { name: 'Bob', age: 30 },
    { name: 'Max', age: 25 },
    { name: 'Lili', age: 35 }
  ]).minBy(person => person.age)`}
/>

## Comparison

<MemberLabel label="isSubset()" />

True if `iter` includes every value in this Collection.

<Signature code={`isSubset(iter: Iterable<T>): boolean`} />

<MemberLabel label="isSuperset()" />

True if this Collection includes every value in `iter`.

<Signature code={`isSuperset(iter: Iterable<T>): boolean`} />