Iterable

The Iterable is a set of (key, value) entries which can be iterated, and is the base class for all collections in immutable, allowing them to make use of all the Iterable methods (such as map and filter).

type Iterable<K, V>

Discussion

Note: An iterable is always iterated in the same order, however that order may not always be well defined, as is the case for the Map and Set.

Construction

Iterable()

Iterable<K, V>(iterable: Iterable<K, V>): Iterable<K, V> Iterable<T>(array: Array<T>): Iterable.Indexed<T> Iterable<V>(obj: {[key: string]: V}): Iterable.Keyed<string, V> Iterable<T>(iterator: Iterator<T>): Iterable.Indexed<T> Iterable<T>(iterable: Object): Iterable.Indexed<T> Iterable<V>(value: V): Iterable.Indexed<V>

Static methods

Iterable.isIterable()

Iterable.isIterable(maybeIterable: any): boolean

Iterable.isKeyed()

Iterable.isKeyed(maybeKeyed: any): boolean

Iterable.isIndexed()

Iterable.isIndexed(maybeIndexed: any): boolean

Iterable.isAssociative()

Iterable.isAssociative(maybeAssociative: any): boolean

Iterable.isOrdered()

Iterable.isOrdered(maybeOrdered: any): boolean

Value equality

equals()

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

equals(other: Iterable<K, V>): boolean

Discussion

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

hashCode()

Computes and returns the hashed identity for this Iterable.

hashCode(): number

Discussion

The hashCode of an Iterable 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.

var a = List.of(1, 2, 3); var b = List.of(1, 2, 3); assert(a !== b); // different instances var set = Set.of(a); assert(set.has(b) === true);

If two values have the same hashCode, they are not guaranteed to be equal. If two values have different hashCodes, they must not be equal.

Reading values

get()

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

get(key: K, notSetValue?: V): V

Discussion

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.

has()

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

has(key: K): boolean

includes()

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

includes(value: V): boolean

alias

contains()

first()

The first value in the Iterable.

first(): V

last()

The last value in the Iterable.

last(): V

Reading deep values

getIn()

getIn(searchKeyPath: Array<any>, notSetValue?: any): any getIn(searchKeyPath: Iterable<any, any>, notSetValue?: any): any

hasIn()

hasIn(searchKeyPath: Array<any>): boolean hasIn(searchKeyPath: Iterable<any, any>): boolean

Conversion to JavaScript types

toJS()

Deeply converts this Iterable to equivalent JS.

toJS(): any

alias

toJSON()

Discussion

Iterable.Indexeds, and Iterable.Sets become Arrays, while Iterable.Keyeds become Objects.

toArray()

Shallowly converts this iterable to an Array, discarding keys.

toArray(): Array<V>

toObject()

Shallowly converts this Iterable to an Object.

toObject(): {[key: string]: V}

Discussion

Throws if keys are not strings.

Conversion to Collections

toMap()

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

toMap(): Map<K, V>

Discussion

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

toOrderedMap()

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

toOrderedMap(): OrderedMap<K, V>

Discussion

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

toSet()

Converts this Iterable to a Set, discarding keys. Throws if values are not hashable.

toSet(): Set<V>

Discussion

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

toOrderedSet()

Converts this Iterable to a Set, maintaining the order of iteration and discarding keys.

toOrderedSet(): OrderedSet<V>

Discussion

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

toList()

Converts this Iterable to a List, discarding keys.

toList(): List<V>

Discussion

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

toStack()

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

toStack(): Stack<V>

Discussion

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

Conversion to Seq

toSeq()

Converts this Iterable to a Seq of the same kind (indexed, keyed, or set).

toSeq(): Seq<K, V>

toKeyedSeq()

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

toKeyedSeq(): Seq.Keyed<K, V>

Discussion

This is useful if you want to operate on an Iterable.Indexed and preserve the [index, value] pairs.

The returned Seq will have identical iteration order as this Iterable.

Example:

var indexedSeq = Immutable.Seq.of('A', 'B', 'C'); indexedSeq.filter(v => v === 'B').toString() // Seq [ 'B' ] var keyedSeq = indexedSeq.toKeyedSeq(); keyedSeq.filter(v => v === 'B').toString() // Seq { 1: 'B' }

toIndexedSeq()

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

toIndexedSeq(): Seq.Indexed<V>

toSetSeq()

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

toSetSeq(): Seq.Set<V>

Iterators

keys()

An iterator of this Iterable's keys.

keys(): Iterator<K>

Discussion

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

values()

An iterator of this Iterable's values.

values(): Iterator<V>

Discussion

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

entries()

An iterator of this Iterable's entries as [key, value] tuples.

entries(): Iterator<Array<any>>

Discussion

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

Iterables (Seq)

keySeq()

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

keySeq(): Seq.Indexed<K>

valueSeq()

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

valueSeq(): Seq.Indexed<V>

entrySeq()

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

entrySeq(): Seq.Indexed<Array<any>>

Sequence algorithms

map()

Returns a new Iterable of the same type with values passed through a mapper function.

map<M>(
mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => M,
context?: any
): Iterable<K, M>

Discussion

Seq({ a: 1, b: 2 }).map(x => 10 * x) // Seq { a: 10, b: 20 }

filter()

Returns a new Iterable of the same type with only the entries for which the predicate function returns true.

filter(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq({a:1,b:2,c:3,d:4}).filter(x => x % 2 === 0) // Seq { b: 2, d: 4 }

filterNot()

Returns a new Iterable of the same type with only the entries for which the predicate function returns false.

filterNot(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq({a:1,b:2,c:3,d:4}).filterNot(x => x % 2 === 0) // Seq { a: 1, c: 3 }

reverse()

Returns a new Iterable of the same type in reverse order.

reverse(): Iterable<K, V>

sort()

Returns a new Iterable of the same type which includes the same entries, stably sorted by using a comparator.

sort(comparator?: (valueA: V, valueB: V) => number): Iterable<K, V>

Discussion

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
  • Is pure, i.e. it must always return the same value for the same pair of values.

When sorting collections which have no defined order, their ordered equivalents will be returned. e.g. map.sort() returns OrderedMap.

sortBy()

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

sortBy<C>(
comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,
comparator?: (valueA: C, valueB: C) => number
): Iterable<K, V>

Discussion

hitters.sortBy(hitter => hitter.avgHits);

groupBy()

Returns a Iterable.Keyed of Iterable.Keyeds, grouped by the return value of the grouper function.

groupBy<G>(
grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,
context?: any
): Seq.Keyed<G, Iterable<K, V>>

Discussion

Note: This is always an eager operation.

Side effects

forEach()

The sideEffect is executed for every entry in the Iterable.

forEach(
sideEffect: (value?: V, key?: K, iter?: Iterable<K, V>) => any,
context?: any
): number

Discussion

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

slice()

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

slice(begin?: number, end?: number): Iterable<K, V>

Discussion

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

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

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

rest()

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

rest(): Iterable<K, V>

butLast()

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

butLast(): Iterable<K, V>

skip()

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

skip(amount: number): Iterable<K, V>

skipLast()

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

skipLast(amount: number): Iterable<K, V>

skipWhile()

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

skipWhile(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq.of('dog','frog','cat','hat','god') .skipWhile(x => x.match(/g/)) // Seq [ 'cat', 'hat', 'god' ]

skipUntil()

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

skipUntil(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq.of('dog','frog','cat','hat','god') .skipUntil(x => x.match(/hat/)) // Seq [ 'hat', 'god' ]

take()

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

take(amount: number): Iterable<K, V>

takeLast()

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

takeLast(amount: number): Iterable<K, V>

takeWhile()

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

takeWhile(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq.of('dog','frog','cat','hat','god') .takeWhile(x => x.match(/o/)) // Seq [ 'dog', 'frog' ]

takeUntil()

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

takeUntil(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): Iterable<K, V>

Discussion

Seq.of('dog','frog','cat','hat','god').takeUntil(x => x.match(/at/)) // ['dog', 'frog']

Combination

concat()

Returns a new Iterable of the same type with other values and iterable-like concatenated to this one.

concat(...valuesOrIterables: any[]): Iterable<K, V>

Discussion

For Seqs, all entries will be present in the resulting iterable, even if they have the same key.

flatten()

flatten(depth?: number): Iterable<any, any> flatten(shallow?: boolean): Iterable<any, any>

flatMap()

flatMap<MK, MV>(
mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => Iterable<MK, MV>,
context?: any
): Iterable<MK, MV>
flatMap<MK, MV>(
mapper: (value?: V, key?: K, iter?: Iterable<K, V>) => any,
context?: any
): Iterable<MK, MV>

Reducing a value

reduce()

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

reduce<R>(
reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,
initialReduction?: R,
context?: any
): R

see

Discussion

If initialReduction is not provided, or is null, the first item in the Iterable will be used.

reduceRight()

Reduces the Iterable in reverse (from the right side).

reduceRight<R>(
reducer: (reduction?: R, value?: V, key?: K, iter?: Iterable<K, V>) => R,
initialReduction?: R,
context?: any
): R

Discussion

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

every()

True if predicate returns true for all entries in the Iterable.

every(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): boolean

some()

True if predicate returns true for any entry in the Iterable.

some(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): boolean

join()

Joins values together as a string, inserting a separator between each. The default separator is ",".

join(separator?: string): string

isEmpty()

Returns true if this Iterable includes no values.

isEmpty(): boolean

Discussion

For some lazy Seq, isEmpty might need to iterate to determine emptiness. At most one iteration will occur.

count()

count(): number count(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any
): number

countBy()

Returns a Seq.Keyed of counts, grouped by the return value of the grouper function.

countBy<G>(
grouper: (value?: V, key?: K, iter?: Iterable<K, V>) => G,
context?: any
): Map<G, number>

Discussion

Note: This is not a lazy operation.

Search for value

find()

Returns the first value for which the predicate returns true.

find(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any,
notSetValue?: V
): V

findLast()

Returns the last value for which the predicate returns true.

findLast(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any,
notSetValue?: V
): V

Discussion

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

findEntry()

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

findEntry(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any,
notSetValue?: V
): Array<any>

findLastEntry()

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

findLastEntry(
predicate: (value?: V, key?: K, iter?: Iterable<K, V>) => boolean,
context?: any,
notSetValue?: V
): Array<any>

Discussion

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

findKey()

Returns the key for which the predicate returns true.

findKey(
predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,
context?: any
): K

findLastKey()

Returns the last key for which the predicate returns true.

findLastKey(
predicate: (value?: V, key?: K, iter?: Iterable.Keyed<K, V>) => boolean,
context?: any
): K

Discussion

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

keyOf()

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

keyOf(searchValue: V): K

lastKeyOf()

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

lastKeyOf(searchValue: V): K

max()

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

max(comparator?: (valueA: V, valueB: V) => number): V

Discussion

The comparator is used in the same way as Iterable#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.

maxBy()

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

maxBy<C>(
comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,
comparator?: (valueA: C, valueB: C) => number
): V

Discussion

hitters.maxBy(hitter => hitter.avgHits);

min()

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

min(comparator?: (valueA: V, valueB: V) => number): V

Discussion

The comparator is used in the same way as Iterable#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.

minBy()

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

minBy<C>(
comparatorValueMapper: (value?: V, key?: K, iter?: Iterable<K, V>) => C,
comparator?: (valueA: C, valueB: C) => number
): V

Discussion

hitters.minBy(hitter => hitter.avgHits);

Comparison

isSubset()

isSubset(iter: Iterable<any, V>): boolean isSubset(iter: Array<V>): boolean

isSuperset()

isSuperset(iter: Iterable<any, V>): boolean isSuperset(iter: Array<V>): boolean
This documentation is generated from immutable.d.ts. Pull requests and Issues welcome.