Builtins

Every method that has a matching Array.prototype is documented here. They all delegate to the underlying array and produce a new collection (for transforms) or a scalar value (for reads).

Transforms (return a new collection)

c.map<U>(cb: (item: T, index: number) => U): ImmutableCollection<U>
c.filter(cb: (item: T, index: number) => boolean): ImmutableCollection<T>
c.flat(depth?: number): ImmutableCollection<any>
c.flatMap(cb: (item: T, index: number) => any): ImmutableCollection<any>
c.takeWhile(cb): ImmutableCollection<T>          // alias for filter
c.removeAll(cb): ImmutableCollection<T>          // alias for filter (confusing name)

collect([1, 2, 3]).map(n => n * 2);                       // [2, 4, 6]
collect([1, 2, 3]).filter(n => n > 1);                    // [2, 3]
collect([1, [2, 3], [4]]).flat();                         // [1, 2, 3, 4]
collect([1, 2, 3]).flatMap(n => [n, n + 100]);            // [1, 101, 2, 102, 3, 103]

removeAll is not a remove operation — it’s a filter that KEEPS the matching items. Despite the name, it’s the same as filter. Use reject(...) for the inverse.

Reads (return a scalar)

c.reduce<Acc>(cb, initialValue?): Acc
c.reduceRight(cb, initialValue?): any
c.find(cb): T | undefined
c.findIndex(cb): number
c.indexOf(item, fromIndex?): number
c.lastIndexOf(item, fromIndex?): number
c.includes(item): boolean
c.contains(item): boolean           // alias
c.every(cb): boolean
c.some(cb): boolean
c.join(separator?): string
c.implode(separator?): string       // alias

collect([1, 2, 3, 4]).reduce((acc, n) => acc + n, 0);     // 10
collect([1, 2, 3, 4]).reduce((acc, n) => acc + n);        // 10 — also works
collect([1, 2, 3]).find(n => n > 1);                      // 2
collect([1, 2, 3]).every(n => n > 0);                     // true
collect([1, 2, 3]).join("-");                             // "1-2-3"

reduce(cb) (no initialValue) preserves native Array.prototype.reduce semantics — the wrapper uses arguments.length to decide whether to forward initialValue, so items[0] is used as the accumulator when none is supplied. Calling reduce on an empty collection with no initial value still throws TypeError, matching the native behavior.

Iteration / shape

c.forEach(cb): this           // executes cb for each item, returns the collection
c.each(cb): this              // alias for forEach
c.keys(): ImmutableCollection<number>     // [0, 1, 2, ...]
c.values(): ImmutableCollection<T>
c.entries(): ImmutableCollection<[number, T]>
c.indexes(): ImmutableCollection<number>  // same as keys()
c.length: number                          // getter

collect(["a", "b", "c"]).keys().all();    // [0, 1, 2]
collect(["a", "b", "c"]).entries().all(); // [[0, "a"], [1, "b"], [2, "c"]]

for-of / spread / Array.from

A collection IS an Iterable.

const c = collect([1, 2, 3]);
for (const n of c) /* ... */;
[...c];                  // [1, 2, 3]
Array.from(c);           // [1, 2, 3]

Conversion

c.toArray(): T[]                     // returns the live reference (mutating it mutates the collection)
c.toArray(mapper): U[]               // maps before returning
c.all(): T[]                         // alias for toArray()
c.toString(): string                 // Array.prototype.toString semantics
c.toJson(): string                   // JSON.stringify(items)
c.join(sep?): string