@mysticwave/collect-me v1.0.12

Collect Me

A TypeScript implementation of a Laravel-inspired Collection class, providing powerful utility methods for handling arrays of items in a more expressive way.

Note: This package is mainly for fun and educating purposes. If you are looking more advanced package, try: Collect.JS

Installation

You can install the package via npm:

npm install @mysticwave/collect-me

Usage

Importing the Collection class

import { collect, Collection } from "@mysticwave/collect-me";

Creating a Collection

You can create a new collection by passing an array to the collect function:

const items = collect([1, 2, 3]);
// or
const items = new Collection([1, 2, 3]);

Available Methods

Here is a list of the methods available in the Collection class:

all()

Returns all items in the collection.

items.all(); // [1, 2, 3]

get()

Alias for the all method. Returns all items in the collection.

items.get(); // [1, 2, 3]

entries()

Returns an array of key-value pairs for items in the collection.

items.entries(); // [[0, 1], [1, 2], [2, 3]]

first()

Returns the first item in the collection.

items.first(); // 1

last()

Returns the last item in the collection.

items.last(); // 3

take(count)

Returns a new collection with a specified number of items.

items.take(2); // [1, 2]

push(item)

Adds an item to the collection.

items.push(4); // [1, 2, 3, 4]

map(callback)

Applies a callback function to each item in the collection and updates the items with the results.

items.map((item) => item * 2); // [2, 4, 6]

filter(callback)

Filters the items in the collection based on a callback function.

items.filter((item) => item > 1); // [2, 3]

reduce(callback, initialValue)

Reduces the collection to a single value using a callback function.

items.reduce((total, item) => total + item, 0); // 6

reverse()

Reverses the order of the items in the collection.

items.reverse(); // [3, 2, 1]

flatten(depth)

Flattens a multi-dimensional collection into a single dimension.

items = collect([1, 2, 3, [11, 12, 13]]);
items.flatten(); // [1, 2, 3, 11, 12, 13]

chunk()

Splits the collection into smaller chunks of a given size.

const items = collect([1, 2, 3, 4, 5]);
const chunks = items.chunk(2); // [[1, 2], [3, 4], [5]]

unique(key?)

Removes duplicate values from the collection.

const items = collect([1, 2, 2, 3]);
const uniqueItems = items.unique(); // [1, 2, 3]

const objects = collect([{ id: 1 }, { id: 2 }, { id: 1 }]);
const uniqueObjects = objects.unique("id"); // [{ id: 1 }, { id: 2 }]

contains(value)

Checks if a given value exists in the collection.

const items = collect([1, 2, 3]);
const hasTwo = items.contains(2); // true
const hasFour = items.contains(4); // false

diff(values)

Finds the difference between the collection and another array or collection.

const items = collect([1, 2, 3]);
const difference = items.diff([2, 3, 4]); // [1]

merge(values)

Merges the collection with another array or collection.

const items = collect([1, 2]);
const merged = items.merge([3, 4]); // [1, 2, 3, 4]

isEmpty()

Checks if the collection is empty.

collect([]).isEmpty(); // true
collect([1, 2, 3]).isEmpty(); // false

isNotEmpty()

Checks if the collection is not empty.

collect([]).isNotEmpty(); // false
collect([1, 2, 3]).isNotEmpty(); // true

where(condition, operatorOrValue, value?)

Filters the collection where a specific condition is met.

items.where("id", 1); // [{ id: 1 }]
items.where("id", ">", 1); // [{ id: 2 }, {id: 3}]

items.where("name", "LIKE", "%anderson"); // [{name: 'Thomas Anderson'}]
items.where("name", "LIKE", "Thomas%"); // [{name: 'Thomas Anderson'}]
items.where("name", "LIKE", "%mas An%"); // [{name: 'Thomas Anderson'}]

whereNot(condition, value)

Filters the collection where the specified key's value is not equal to a given value.

items.whereNot("id", 1); // [{ id: 2 }, {id: 3}]

whereIn(condition, values)

Filters the collection where the specified key's value is in a list of values.

items.whereIn("id", [1, 3]); // [{ id: 1 }, {id: 3}]

whereNotIn(condition, values)

Filters the collection where the specified key's value is not in a list of values.

items.whereNotIn("id", [1, 3]); // [{ id: 2 }]

whereBetween(condition, min, max?)

Filters the collection where the specified key's value is between two values. The second parameter can be an array.

items.whereBetween("id", [2, 3]); // [{ id: 2 }, { id: 3 }]
items.whereBetween("id", 2, 3); // [{ id: 2 }, { id: 3 }]

whereNotBetween(condition, min, max?)

Filters the collection where the specified key's value is not between two values. The second parameter can be an array.

items.whereNotBetween("id", [2, 3]); // [{ id: 1 }]
items.whereNotBetween("id", 2, 3); // [{ id: 1 }]

whereNull(condition)

Filters the collection where the specified key's value is null.

items.whereNull("deleted_at"); // [{ id: 1, deleted_at: null }]

whereNotNull(condition)

Filters the collection where the specified key's value is not null.

items.whereNotNull("deleted_at"); // [{ id: 2, deleted_at: "2024-04-04" }]

firstWhere(condition, operatorOrValue, value?)

Returns the first item that matches the given condition.

items.firstWhere("id", 1); // [{ id: 1 }]
items.firstWhere("id", "!=", 1); // [{ id: 2 }, { id: 3 }]

pluck(key)

Extracts values of a specified key from each item in the collection.

items.pluck("id"); // [1, 2, 3]

count()

Returns the number of items in the collection.

items.count(); // 3

sum(key)

Returns the sum of a specified key's values in the collection.

items.sum("id"); // 1 + 2 + 3 = 6

avg(key)

Returns the average of a specified key's values in the collection.

items.avg("id"); // (1 + 2 + 3) / 3 = 2

min(key)

Returns the smallest value of a specified key in the collection.

items.min("id"); // 1

max(key)

Returns the largest value of a specified key in the collection.

items.max("id"); // 3

groupBy(key)

Groups the items in the collection by a specified key.

items.groupBy("occupation");
/* 
{
    ocean: [
        {name: "squid", occupation: "ocean"},
        {name: "fish", occupation: "ocean"},
    ],
    desert: [
        {name: "scorpio", occupation: "desert"},
        {name: "desert fox", occupation: "desert"},
    ]
}
*/

sortBy(key, order = 'ASC')

Sorts the items in the collection by a specified key.

items.sortBy("name", "ASC");
/* 
[
    {name: "desert fox", occupation: "desert"},
    {name: "fish", occupation: "ocean"},
    {name: "scorpio", occupation: "desert"},
    {name: "squid", occupation: "ocean"},
]
*/

sortByAsc(key)

Sorts the items in the collection by a specified key in ascending order.

items.sortByAsc("name");
/* 
[
    {name: "desert fox", occupation: "desert"},
    {name: "fish", occupation: "ocean"},
    {name: "scorpio", occupation: "desert"},
    {name: "squid", occupation: "ocean"},
]
*/

sortByDesc(key)

Sorts the items in the collection by a specified key in descending order.

items.sortByDesc("name");
/* 
[
    {name: "squid", occupation: "ocean"},
    {name: "scorpio", occupation: "desert"},
    {name: "fish", occupation: "ocean"},
    {name: "desert fox", occupation: "desert"},
]
*/

orderBy(key, order = 'ASC')

Alias for the sortBy method.

orderByAsc(key)

Alias for the sortByAsc method.

orderByDesc(key)

Alias for the sortByDesc method.

toArray()

Converts the collection into a plain array.

items.toArray(); // [1, 2, 3]

toJSON()

Converts the collection into a JSON string.

items.toJSON(); // "[1, 2, 3]"

join()

Joins the items in the collection using a given separator.

items.join(","); // "1,2,3"