Class Collection<T>

Cast the collection to an array.

Return an object mapping the given key to the record with that key. See keyBy().

Create a new collection by mapping the items in this collection using the given function where the function returns an Either. The collection is all Right instances. If a Left is encountered, that value is returned.

Return a new AsyncPipe of this collection.

Return the item at the given index in the collection, if it exists.

Get the average value of the items or one of their keys.

Await all values in the collection.

Shortcut for .mapCall(...).awaitAll().

Create a copy of this collection. Does NOT deep copy the underlying items.

Collapse a (potentially nested) collection of items down to a single dimension.

Push the given items to the end of this collection. Unlike merge(), this mutates the current collection's items.

Returns true if the given key matches the given condition for any item in the collection.

Example

const userExists = users.contains('username', '=', 'jdoe')

Get the number of items in the collection.

Return a collection of items that ARE in this collection, but NOT in the items collection.

Like diff, but mutates the current collection.

Return a collection of items that ARE in this collection, but NOT In the items collection using a helper function to determine whether two items are equal.

Example

potentialUsers.diffUsing(storedUsers, (u1, u2) => u1.username.toLowerCase() === u2.username.toLowerCase())

Execute the function for every item in the collection.

Returns true if the given function returns true for every item in the collection.

Return a new collection filtered by the given function.

Like filter, but inverted. That is, removes items that DO match the criterion.

Returns the index of the record for which the given function returns true, if such an index exists.

Return the first item in the collection, if it exists.

Return the first item in the collection that matches the given where-condition.

Return the first item in the collection that does NOT match the given where-condition.

Return the items that should exist on the given page, assuming there are perPage many items on a single page.

Get the item at the given index in the collection. If none exists, return the fallback.

Return an object mapping key values to arrays of records with that key.

Example

const users = collect([
 {uid: 1, name: 'John', type: 'admin'},
 {uid: 2, name: 'Jane', type: 'user'},
 {uid: 3, name: 'James', type: 'user'},
])

users.groupBy('type')  // => {admin: [{uid: 1, ...}], user: [{uid: 2, ...}, {uid: 3, ...}]}

Join the items in the collection to a string delimited by the given delimiter.

Returns true if the given item is in this collection.

Return a collection of the items that exist in both this collection and this collection, (optionally) using the given key to compare.

True if the collection has no items.

True if the collection has at least one item.

Join the items in the collection to a string delimited by the given delimiter.

Convert this collection to an object keyed by the given field.

Example

const users = collect([{uid: 1, name: 'John'}, {uid: 2, name: 'Jane'}])
users.keyBy('name')  // => {John: {uid: 1, name: 'John'}, Jane: {uid: 2, name: 'Jane'}}

Convert this collection to an object keyed by the given field, whose values are the output of the value operator.

Example

const users = collect([{uid: 1, name: 'John'}, {uid: 2, name: 'Jane'}])
users.keyMap('name', 'uid')  // => {John: 1, Jane: 2}

Return the last item in the collection.

Return the last item in the collection that matches the given where-condition.

Return the last item in the collection that does NOT match the given where-condition.

Create a new collection by mapping the items in this collection using the given function.

Map a method on the underlying type, passing it any required parameters. This is delightfully type-safe.

Create a new collection by mapping the items in this collection using the given function where the function returns an Either. The collection is all Right instances. If a Left is encountered, that value is returned.

Return the max value of the given key.

Get the median value of the items or one of their keys.

Get a new collection containing both the items in this collection, and the items collection.

Return the min value of the given key.

Get the mode of the items or one of their keys.

Return every nth item in the collection.

Example

const items = collect(['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'])

items.nth(3)  // => Collection['a', 'd', 'g']

Add on to the end of this collection as many value items as necessary until the collection is length long.

Create a new collection by mapping the items in this collection using the given function, excluding any for which the function returns undefined.

Build and apply a pipeline.

Return a new Pipe of this collection.

Map the collection to a collection of the values of the key.

Example

const users = collect([
 {uid: 1, name: 'John', type: 'admin'},
 {uid: 2, name: 'Jane', type: 'user'},
 {uid: 3, name: 'James', type: 'user'},
])

users.pluck('name')  // => Collection['John', 'Jane', 'James']

Remove the last item from this collection.

Add the given item to the beginning of this collection.

Like map(), but the callback can be async.

Example

A trivial example, but demonstrative:

const collection = collect([1, 2, 3])

collection.map(async item => item + 1)  // => Collection[Promise<1>, Promise<2>, Promise<3>]

collection.promiseMap(async item => item + 1)  // => Promise<Collection[2, 3, 4]>

Add the given item to the end of this collection.

Subscribe to listen for items being added to the collection.

Insert the given item into this collection at the specified index.

Return n many randomly-selected items from this collection.

Reduce this collection to a single value using the given reducer function.

Example

const items = collect([1, 3, 5, 7])

items.reduce((sum, item) => sum + item, 0)  // => 16

Return a new collection of items that fail the given truth-test function.

Return a new collection whose items are in the reverse order of the current one.

Try to find the given item in the collection. If it exists, return the index.

Remove and return the first item in the collection, if it exists.

Shuffle the items in this collection to a random order.

Return a sub-set of this collection between the given index ranges.

Returns true if the given function returns truthy for any item in the collection. Stops executing if a single truth case is found.

Sort the collection (optionally) using the given comparison function.

Sort the collection (optionally) using the given key operator.

Identical to sortBy(), but in reverse order.

Identical to sort(), but in reverse order.

Remove deleteCount many items from the collection, starting at the start index.

Map each element in the collection to a string.

Return the sum of the items in the collection, optionally by key.

Example

const items = collect([{k1: 1}, {k1: 3}, {k1: 5}, {k1: 7}])

items.sum('k1')  // => 16

Return a collection of the first limit many items in this collection. If limit is negative, returns the last limit many items.

Apply the given function to this collection then return the collection. This is intended to help with chaining.

Example

collection.tap(coll => {
        coll.push(item)
    })
    .where('someKey', '>', 4)
    // ... &c.

Cast the collection to an array.

Get the collection as an AsyncCollection.

Cast the collection to a JSON string, optionally specifying the replacer and indentation.

Return all distinct items in this collection. If a key is specified, returns all unique values of that key.

Example

const users = collect([
 {uid: 1, name: 'John', type: 'admin'},
 {uid: 2, name: 'Jane', type: 'user'},
 {uid: 3, name: 'James', type: 'user'},
])

users.unique('type')  // => Collection['admin', 'user']

When bool is falsy, execute the callback, passing in the collection. Can be used for functional-style chained calls.

When bool is truthy, execute the callback, passing in the collection. Can be used for functional-style chained calls.

Filter the collection by the given where-condition.

Example

const users = collect([
 {uid: 1, name: 'John'},
 {uid: 2, name: 'Jane'},
 {uid: 3, name: 'James'},
])

users.where('uid', '<', 3)  // => Collection[{uid: 1, name: 'John'}, {uid: 2, name: 'Jane'}]

Filter the collection for all records where the given key is in a set of items.

Return the item with the max value of the given key.

Return the item with the min value of the given key.

Filter the collection by the inverse of the given where-condition.

Filter the collection for all records where the given key is NOT in a set of items.

Create a new collection from an array of items.

Fill a new collection of the given size with the given item.

Create a new collection from an item or array of items. Filters out undefined items.

Create a collection of "undefined" elements of a given size.