@quinck/collections NPM

collections

Allows extra operations on JavaScript collections: Array, Map and Set.

Overview

The operations are inspired from the Scala collection framework and aims to provide a simple way to perform operations like collect using match cases. Moreover add operations that allows to write fluent code.

Installation

npm i @quinck/collections

Tests

npm run test

Features

In this section will be presented some of the implemented operations.

Collection	Operation	Description
`Array`	`groupBy`	Perform a group by operation, allowing to create a `Map` from an `Array`. The user has only to specify a function to obtain a the key from an element of the `Array`. It also allow to transform each element in a new element letting the user specifying a function to evaluate the new values. The resulting map will contain the different keys generated
`Array`	`groupByToDictionary`	Similar to the `groupBy`, but instead of a Map this will create an object. The created object will have as keys all the different keys generated.
`Array`	`simpleGroupBy`	Simplified version of the `groupBy`, this operation will not allow to specify a mapper function for the values. In this case for each key will be generated and `Array` of values referring to that key.
`Array`	`simpleGroupByToDictionary`	Simplified version of the `groupByToDictionary`, this operation will not allow to specify a mapper function for the values. In this case for each key will be generated and `Array` of values referring to that key.
`Array`	`singleCollect`	It performs `Array.filter` and `Array.map` operations in a single operation (browsing the elements of the array once). It allow to specify a filter and a mapper function. The elements that match the filter will be kept and the others will be discarded. Moreover as in Scala also here is possible to specify the default case that will take care of the elements that didn't matched the filter.
`Array`	`collect`	This operation tries to perform the `collect` operation of the Scala collection framework. As in Scala is possible to use the `match` construct, infact the `collect` allows to specify an ordered `Array` of `MatchCase`. Starting from the first to the last `MatchCase`, if an element of the `Array` satisfy the filter the relative mapper will be applied. As in Scala only the first successful case will be cosidered. Moreover as in the `collect` is possible to specify the default case specifying teh relative mapper.
`Array`	`chunckify`	Considering `n` the the length of the array and `size` the number of items per chunck. Splits array items in `sn=n/size`, rounded up, arrays. The first `sn-1` resulting arrays are of length equals to `size`, while the last array cloud have a length between `1` and `size` inclusive.
`Array`	`toSet`	Transform an `Array` into a `Set` with unique values.
`Array`	`awaitAll`	Awaits all the promises elements of the `Array` to be fulfilled.
`Array`	`tryToAwaitAll`	Awaits all the promises elements of the `Array` to be settled. If a `Promise` fulfills the item will be replaced with its awaited version, if a `Promise` rejects the item will be replaced with the error reported.
`Array`	`awaitAllFulfilled`	Awaits all the promises elements of the `Array` to be settled, discarding elements that does not fulfills.
`Array`	`awaitAllRejected`	Awaits all the promises elements of the `Array` to be settled, taking only the rejected.
`Map`	`toArray`	`Map` objects in JavaScript (or Typescript) are not really 'array-friendly'. In fact in order to obtain an `Array` having a `Map` you have to get all the entries, using `map.entries()`, and then creating an `Array` (i.e. using `Array.from`). This way does not allow to have a fluent code, so in order to achieve this the additional method `Map.toArray` transform a `Map` in an `Array` where each element is a pair of a key and the relative value. Doing this way is possible to have a fluent code.
`Map`	`keysArray`	Allow to get the keys of a `Map` in an `Array` in a fluent way.
`Map`	`valuesArray`	Allow to get the values of a `Map` in an `Array` in a fluent way.

Usage

In this section will be showed some examples.

Array

GroupBy

const students = [
    {
        studentClass = "A",
        studentGrade = 9,
        studentName = "Earvin"
    },
    {
        studentClass = "A",
        studentGrade = 10,
        studentName = "Michael"
    },
    {
        studentClass = "B",
        studentGrade = 9,
        studentName = "James"
    },
    {
        studentClass = "B",
        studentGrade = 10,
        studentName = "Kobe"
    },
    {
        studentClass = "B",
        studentGrade = 9,
        studentName = "Stephen"
    }
]

/* Lets find the best student per each class */

const bestStudents = students.groupBy(
    /* group by student class */
    ({studentClass}) => studentClass,
    student => student,
    /*
     * merge elements of the same group,
     * in this case take the higher studentGrade
     */
    (a,b) => a.studentGrade > b.studentGrade ? a : b
)

/*
bestStudents will contain:
A => {
        studentClass = "A",
        studentGrade = 10,
        studentName = "Michael"
    }
B => {
        studentClass = "B",
        studentGrade = 10,
        studentName = "Kobe"
    }
*/

Collect

const students = [
    {
        studentClass = "A",
        studentGrade = 9,
        studentName = "Earvin"
    },
    {
        studentClass = "A",
        studentGrade = 10,
        studentName = "Michael"
    },
    {
        studentClass = "B",
        studentGrade = 9,
        studentName = "James"
    },
    {
        studentClass = "B",
        studentGrade = 10,
        studentName = "Kobe"
    },
    {
        studentClass = "B",
        studentGrade = 9,
        studentName = "Stephen"
    },
    {
        studentClass = "B",
        studentGrade = 5,
        studentName = "Kevin"
    }
]

/* Lets the students names of the class A */

const classAStudentsNames = students.singleCollect(
    ({studentClass}) => studentClass === "A",
    ({studentName}) => studentName
)

/*
classAStudentsNames will be:
["Earvin","Michael"]
*/

/* Lets perform this operations:
give a scholarship to students with grade equals to 10
pass students with a grade greater than or equals to 6
fail other students
*/

const studentsWithStatus = students.collect([
    [
        ({studentGrade}) => studentGrade === 10,
        student => ({...student, status: "scholarship"})
    ],
    [
        ({studentGrade}) => studentGrade >= 6,
        student => ({...student, status: "pass"})
    ]
], student => ({...student, status: "fail"})
)

/*
studentsWithStatus will be:
[
    {
        studentClass = "A",
        studentGrade = 9,
        studentName = "Earvin",
        status: "pass"
    },
    {
        studentClass = "A",
        studentGrade = 10,
        studentName = "Michael",
        status: "scholarship"
    },
    ...
    {
        studentClass = "B",
        studentGrade = 5,
        studentName = "Kevin",
        status: "fail"
    }
]
*/

Map

toArray

const map = new Map([1,10],[2,20],[3,30])

const result = map.toArray() /* [[1,10],[2,20],[3,30]] */
    .filter(([key]) => key > 2) /* [[3,30]] */

Mixing

const map = new Map([1,10],[2,20],[3,30])

const result = map.toArray() /* [[1,10],[2,20],[3,30]] */
    .singleCollect(
        ([key]) => key > 2,
        ([,value]) => [value],
        (a,b) => a.concat(b)
    )
/*
result = [30]
*/