Sort Group

Sort

c.sort(cb?): ImmutableCollection<T>                      // Array.prototype.sort
c.sortBy(key: string): ImmutableCollection<T>            // ascending by key (dot-notation OK)
c.sortBy({ [key]: "asc" | "desc" }): ImmutableCollection<T>  // multi-key
c.sortByDesc(key: string): ImmutableCollection<T>        // descending by key

All four sort variants clone this.items internally before sorting, so the original collection is untouched. See mutation for the full matrix.

collect([3, 1, 2]).sort();
//  [1, 2, 3]

collect(users).sortBy("age");
//  ascending by user.age

collect(users).sortByDesc("createdAt");
//  newest first

collect(users).sortBy({ group: "asc", age: "desc" });
//  group A first; within each group oldest first

Stability

Array.prototype.sort is stable in ES2019+ (Node 12+). The comparators in sortBy return 0 for equal keys, so input order is preserved within a tie.

Group

c.groupBy(key: string | string[]): ImmutableCollection<{ [key]: any; items: T[] }>

Returns a collection where each item is an object with the grouping key value(s) plus an items array. For multi-key grouping, every key from the array appears on each bucket:

collect(students).groupBy("class");
//  [
//    { class: "A", items: [...studentsInA] },
//    { class: "B", items: [...studentsInB] },
//  ]

collect(students).groupBy(["class", "grade"]);
//  [
//    { class: "A", grade: 1, items: [{...}] },
//    { class: "B", grade: 2, items: [{...}, {...}] },
//    ...
//  ]

Internally delegates to reinforcements’ groupBy(items, keys, "items") — the third arg names the bucket field.

Partition

c.partition(cb): [ImmutableCollection<T>, ImmutableCollection<T>]

Splits into two collections in one pass — items where cb returns truthy, then the rest.

const [active, inactive] = collect(users).partition(u => u.active);

active.length + inactive.length === users.length;   // always true

Unique

c.unique(key?: string): ImmutableCollection
c.uniqueList(key: string): ImmutableCollection<T>     // first object per unique key value

Important behavior difference: unique("key") returns the VALUES at the key (a flat list of the unique values), not deduped objects. uniqueList("key") returns the OBJECTS (one per unique key value).

collect([
  { name: "Ada", age: 20 },
  { name: "Bob", age: 20 },
  { name: "Cid", age: 25 },
]).unique("age");
//  [20, 25]   — values, not objects

collect([
  { id: 1, name: "Ada" },
  { id: 2, name: "Ada" },
  { id: 3, name: "Bob" },
]).uniqueList("name");
//  [
//    { id: 1, name: "Ada" },
//    { id: 3, name: "Bob" },
//  ]

For primitive arrays, unique() is unambiguous:

collect([1, 2, 1, 3, 2]).unique();    // [1, 2, 3]

Reorder helpers

c.swap(i, j): ImmutableCollection<T>             // exchange two indices
c.move(from, to): ImmutableCollection<T>         // splice-style reposition
c.reorder({ [oldIndex]: newIndex }): ImmutableCollection<T>   // map of old→new positions
c.reverse(): ImmutableCollection<T>              // returns a new reversed collection
c.flip(): ImmutableCollection<T>                 // alias for reverse

collect([1, 2, 3, 4, 5]).swap(0, 4);
//  [5, 2, 3, 4, 1]

collect([1, 2, 3, 4, 5]).move(0, 4);
//  [2, 3, 4, 5, 1]

collect([1, 2, 3]).reorder({ 0: 2, 1: 1, 2: 0 });
//  [3, 2, 1]