import Repl from '@/repl/Repl.tsx';

import CodeLink from '@/mdx-components/CodeLink.tsx';

`Seq` describes a lazy operation, allowing them to efficiently chain

use of all the higher-order collection methods (such as <CodeLink to="map" /> and <CodeLink to="filter" />)

by not creating intermediate collections.

<Signature code={`type Seq<K, V> extends Collection<K, V>`} />

**Seq is immutable** — Once a Seq is created, it cannot be

changed, appended to, rearranged or otherwise modified. Instead, any

mutative method called on a `Seq` will return a new `Seq`.

**Seq is lazy** — `Seq` does as little work as necessary to respond to any

method call. Values are often created during iteration, including implicit

iteration when reducing or converting to a concrete data structure such as

a <CodeLink to="../List" /> or JavaScript [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).

For example, the following performs no work, because the resulting

`Seq`'s values are never iterated:

import { Seq } from 'immutable';

const oddSquares = Seq([1, 2, 3, 4, 5, 6, 7, 8])

.filter((x) => x % 2 !== 0)

.map((x) => x * x);

Once the `Seq` is used, it performs only the work necessary. In this

example, no intermediate arrays are ever created, filter is called three

times, and map is only called once:

oddSquares.get(1); // 9

Any collection can be converted to a lazy Seq with `Seq()`.

import { Map } from 'immutable';

const map = Map({ a: 1, b: 2, c: 3 });

const lazySeq = Seq(map);

`Seq` allows for the efficient chaining of operations, allowing for the

expression of logic that can otherwise be very tedious:

lazySeq

.flip()

.map((key) => key.toUpperCase())

.flip();

As well as expressing logic that would otherwise seem memory or time

limited, for example `Range` is a special kind of Lazy sequence.

<Repl

defaultValue={`Range(1, Infinity)

/>

Seq is often used to provide a rich collection API to JavaScript Object.

<Repl

defaultValue={`Seq({ x: 0, y: 1, z: 2 })

/>

<MemberLabel label="Seq()" />

Creates a Seq.

<Signature

code={`function Seq<S extends Seq>(seq: S): S;

/>

Returns a particular kind of `Seq` based on the input.

* If a `Seq`, that same `Seq`.

* If an `Collection`, a `Seq` of the same kind (Keyed, Indexed, or Set).

* If an Array-like, an `Seq.Indexed`.

* If an Iterable Object, an `Seq.Indexed`.

* If an Object, a `Seq.Keyed`.

Note: An Iterator itself will be treated as an object, becoming a `Seq.Keyed`,

which is usually not what you want. You should turn your Iterator Object into

an iterable object by defining a Symbol.iterator (or @@iterator) method which

returns `this`.

Note: `Seq` is a conversion function and not a class, and does not use the

`new` keyword during construction.

<MemberLabel label="isSeq()" />

<Signature

code={`function isSeq(maybeSeq: unknown): maybeSeq is Seq.Indexed | Seq.Keyed | Seq.Set;`}

/>

<MemberLabel label="size" />

Some Seqs can describe their size lazily. When this is the case,

size will be an integer. Otherwise it will be undefined.

<Signature code={`readonly size: number | undefined;`} />

For example, Seqs returned from <CodeLink to="map" /> or <CodeLink to="reverse" />

preserve the size of the original `Seq` while <CodeLink to="filter" /> does not.

Note: <CodeLink to="../Range()" />,

<CodeLink to="../Repeat()" /> and `Seq`s made from

<CodeLink to="../List" />s and <CodeLink to="../Map" />s will always have a

size.

<MemberLabel label="cacheResult()" />

Because Sequences are lazy and designed to be chained together, they do

not cache their results. For example, this <CodeLink to="map" /> function is called a total

of 6 times, as each `join` iterates the `Seq` of three values.

<Signature code={`cacheResult(): this;`} />

var squares = Seq([1, 2, 3]).map((x) => x * x);

squares.join() + squares.join();

If you know a `Seq` will be used multiple times, it may be more

efficient to first cache it in memory. Here, the <CodeLink to="map" /> function is called

only 3 times.

var squares = Seq([1, 2, 3])

.map((x) => x * x)

.cacheResult();

squares.join() + squares.join();

Use this method judiciously, as it must fully evaluate a `Seq` which can be

a burden on memory and possibly performance.

Note: after calling <CodeLink to="cacheResult" />, a `Seq` will always have a `size`.

<MemberLabel label="map()" />

Returns a new `Seq` with values passed through a

`mapper` function.

<Signature

code={`map<M>(mapper: (value: V, key: K, iter: this) => M, context?: unknown): Seq<K, M>;`}

/>

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

Note: <CodeLink to="map" /> always returns a new instance, even if it produced the same

value at every step.

Note: used only for sets.

<MemberLabel label="flatMap()" />

Flat-maps the `Seq`, returning a `Seq` of the same type.

<Signature

code={`flatMap<M>(mapper: (value: V, key: K, iter: this) => Iterable<M>, context?: unknown): Seq<K, M>;`}

/>

Similar to <CodeLink to="map" />(...).<CodeLink to="flatten" />(true).

Note: Used only for sets.

<MemberLabel label="filter()" />

Returns a new `Seq` with only the values for which the `predicate`

function returns true.

<Signature

code={`filter(predicate: (value: V, key: K, iter: this) => unknown, context?: unknown): this;`}

/>

Note: <CodeLink to="filter" /> always returns a new instance, even if it results in

not filtering out any values.

<MemberLabel label="partition()" />

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

<Signature

code={`partition<F extends V>(

/>

<MemberLabel label="concat()" />

Returns a new `Seq` of the same type with other values and collection-like concatenated to this one.

<Signature code={`concat(...valuesOrCollections): Seq;`} />

All entries will be present in the resulting `Seq`, even if they have the same key.

<MemberLabel label="filterNot()" />

<MemberLabel label="reverse()" />

<MemberLabel label="sort()" />

<MemberLabel label="sortBy()" />

<MemberLabel label="groupBy()" />

<MemberLabel label="equals()" />

<MemberLabel label="hashCode()" />

<MemberLabel label="get()" />

<MemberLabel label="has()" />

<MemberLabel label="includes()" />

<MemberLabel label="first()" />

<MemberLabel label="last()" />

<MemberLabel label="getIn()" />

<MemberLabel label="hasIn()" />

<MemberLabel label="update()" />

<MemberLabel label="toJS()" />

<MemberLabel label="toJSON()" />

<MemberLabel label="toArray()" />

<MemberLabel label="toObject()" />

<MemberLabel label="toMap()" />

<MemberLabel label="toOrderedMap()" />

<MemberLabel label="toSet()" />

<MemberLabel label="toOrderedSet()" />

<MemberLabel label="toList()" />

<MemberLabel label="toStack()" />

<MemberLabel label="toSeq()" />

<MemberLabel label="toKeyedSeq()" />

<MemberLabel label="toIndexedSeq()" />

<MemberLabel label="toSetSeq()" />

<MemberLabel label="keys()" />

<MemberLabel label="values()" />

<MemberLabel label="entries()" />

<MemberLabel label="keySeq()" />

<MemberLabel label="valueSeq()" />

<MemberLabel label="entrySeq()" />

<MemberLabel label="forEach()" />

<MemberLabel label="slice()" />

<MemberLabel label="rest()" />

<MemberLabel label="butLast()" />

<MemberLabel label="skip()" />

<MemberLabel label="skipLast()" />

<MemberLabel label="skipWhile()" />

<MemberLabel label="skipUntil()" />

<MemberLabel label="take()" />

<MemberLabel label="takeLast()" />

<MemberLabel label="takeWhile" />

<MemberLabel label="takeUntil()" />

<MemberLabel label="flatten()" />

<MemberLabel label="reduce()" />

<MemberLabel label="reduceRight()" />

<MemberLabel label="every()" />

<MemberLabel label="some()" />

<MemberLabel label="join()" />

<MemberLabel label="isEmpty()" />

<MemberLabel label="count()" />

<MemberLabel label="countBy()" />

<MemberLabel label="find()" />

<MemberLabel label="findLast()" />

<MemberLabel label="findEntry()" />

<MemberLabel label="findLastEntry()" />

<MemberLabel label="findKey()" />

<MemberLabel label="findLastKey()" />

<MemberLabel label="keyOf()" />

<MemberLabel label="lastKeyOf()" />

<MemberLabel label="max()" />

<MemberLabel label="maxBy()" />

<MemberLabel label="min()" />

<MemberLabel label="minBy()" />

<MemberLabel label="isSubset()" />

<MemberLabel label="isSuperset()" />