ursus-utilus-collections v5.1.0

Ursus-Utilus-Collections

Simple library with useful utils for data manipulation

Menu

• Examples
• Setup
• Technologies

Examples

Pay attention

⚠️ Do not change returned array if u want to reuse owned collection

Importing

import u from 'ursus-utilus-collections'

Filtering

const expected = [2, 4];
const result = u([1, 2, 3, 4]).where(item => !(item % 2)).toArray();

assert.deepEqual(expected, result);

Mapping

const expected = ['2', '4', '6', '8'];
const result = u([1, 2, 3, 4]).select(item => (item * 2).toString()).toArray();

assert.deepEqual(expected, result);

Skipping

const expected = [4, 5, 6];
const result = u([1, 2, 3, 4, 5, 6]).skip(3).toArray();

assert.deepEqual(expected, result);

Taking

const expected = [1, 2, 3];
const result = u([1, 2, 3, 4, 5, 6]).take(3).toArray();

assert.deepEqual(expected, result);

Find first

const collection = u([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);
  
const first = collection.first(); // returns 1
assert.equal(first, 1, 'Return wrong first value');
  
const firstByCondition = collection.first(item => item > 10); // returns 11
assert.equal(firstByCondition, 11, 'Return wrong first filtered value');
  
assert.throws(() => {
    collection.first(item => item > 12); // throws error
}, 'No matches found');

Find first or return default

const collection = u([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);

const first = collection.firstOrDefault(); // returns 1
assert.equal(first, 1, 'Return wrong first value');

const firstByCondition = collection.firstOrDefault(item => item > 10); // returns 11
assert.equal(firstByCondition, 11, 'Return wrong first filtered value');

const emptyFirst = collection.firstOrDefault(item => item > 12); // returns null
assert.equal(emptyFirst, null, 'Return wrong default value');

const defaultFirst = collection.firstOrDefault(item => item > 12, 0); // returns null
assert.equal(defaultFirst, 0, 'Return wrong overrided default value');

Find last

const collection = u([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);

const last = collection.last(); // returns 12
assert.equal(last, 12, 'Return wrong last value');

const lastByCondition = collection.last(item => item < 3); // returns 2
assert.equal(lastByCondition, 2, 'Return wrong last filtered value');
  
assert.throws(() => {
    collection.last(item => item < 1); // throws error
}, 'No matches found');

Find first or return default

const collection = u([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);

const last = collection.lastOrDefault(); // returns 12
assert.equal(last, 12, 'Return wrong last value');

const lastByCondition = collection.lastOrDefault(item => item < 3); // returns 2
assert.equal(lastByCondition, 2, 'Return wrong last filtered value');

const emptylast = collection.lastOrDefault(item => item < 1); // returns null
assert.equal(emptylast, null, 'Return wrong default');

const defaultlast = collection.lastOrDefault(item => item < 1, 0); // returns null
assert.equal(defaultlast, 0, 'Return wrong overrided default');

Sorting

Default sorting

const collection = u([3, 2, 1]);

const sorted = collection.sort().toArray();

assert.deepEqual(sorted, [1, 2, 3])

Sorting desc

const collection = u([1, 2, 3]);

const sorted = collection.sort((first, second) => second - first).toArray();

assert.deepEqual(sorted, [3, 2, 1])

Sorting by field

const collection = u([[3, 4], [2, 11], [2, 3], [1, 2]]);

const sorted = collection.sortBy(item => item[0]).toArray();

assert.deepEqual(sorted, [[1, 2], [2, 11], [2, 3], [3, 4]])

Sorting by many fields

const collection = u([[3, 4], [2, 11], [2, 3], [1, 2]]);

const sorted = collection.sortBy(item => item[0]).thenBy(item => item[1]).toArray();

assert.deepEqual(sorted, [[1, 2], [2, 3], [2, 11], [3, 4]])

Grouping

Simple grouping

const collection = u([[1, 2], [2, 3], [2, 4], [3, 4]]);

const expected = u([{
    key: 1,
    group: u([[1, 2]])
},
{
    key: 2,
    group: u([[2, 3], [2, 4]])
},
{
    key: 3,
    group: u([[3, 4]])
}]);

const grouped = collection.groupBy(item => item[0]);

assert.deepEqual(grouped, expected)

Grouping with group manipulations

const collection = u([[1, 2], [2, 3], [2, 4], [3, 4]]);

const expected: ICollection<IGroupedData<number, number[]>> = u([{
    key: 1,
    group: [1, 2]
},
{
    key: 2,
    group: [2, 3]
},
{
    key: 3,
    group: [3, 4]
}]);

const grouped = collection.groupBy(item => item[0], group => group.first());

assert.deepEqual(grouped, expected);

Min & Max

Min

const collection = u([4, 3, 6, 9, 7, 1, 8]);

const expected = 1;

const result = collection.min();

assert.deepEqual(result, expected)

Max

const collection = u([4, 3, 6, 9, 7, 1, 8]);

const expected = 9;

const result = collection.max();

assert.deepEqual(result, expected)

Exists

const collection = u.range(1, 9);

const expected = true;

const result = collection.exists(item => (item % 7) == 0);

assert.equal(result, expected)

Sum

const collection = u.range(1, 9);

const expected = 45;

const result = collection.sum();

assert.equal(result, expected)

Sum other types

const collection = u(['1', '2', '3',]);

const expected = '6';

const result = collection.sum((a, b) => Number(a) + Number(b));

assert.equal(result, expected)

Reverse

const collection = u([1, 2, 3]);

const expected = [3, 2, 1];

const result = collection.reverse().toArray();

assert.deepEqual(result, expected)

Distinct

const collection = u([1, 1, 2, 1, 3, 2, 3]);

const expected = [1, 2, 3];

const result = collection.distinct().toArray();

assert.deepEqual(result, expected)

Distinct by

const collection = u([[1, 1], [2, 1], [3, 2]]);

const expected = [[1, 1], [3, 2]];

const result = collection.distinct(item => item[1]).toArray();

assert.deepEqual(result, expected)

Concat

const collection = u([1, 2]);

const expected = [1, 2, 3, 4, 5, 6, 7, 8, 9];

const result = collection.concat([3, 4]).concat(u([5, 6, 7])).concat([8, 9]).toArray();

assert.deepEqual(result, expected)

Count

const result = u([8, 5, 4, 2, 9, 1, 4]).count();
const expected = 7;

assert.deepEqual(result, expected);

By condition

const result = u([8, 5, 4, 2, 9, 1, 4]).count(item => (item % 2) == 0);
const expected = 4;

assert.deepEqual(result, expected);

Aggregate

Sum by aggregate

const collection = u.range(1, 9);
const expected = 45;
const result = collection.sum();
assert.equal(result, expected)

Aggregation collection to object

const collection = u([
    { name: 'first', value: 1 },
    { name: 'second', value: 2 },
    { name: 'third', value: 3 },
]);
const expected = {
    'first': 1,
    'second': 2,
    'third': 3
};
const result = collection.aggregate((acc, item) => {
    acc[item.name] = item.value
    return acc;
}, {});
assert.deepEqual(result, expected)

Range

const collection = u.range(0, 5);

const expected = u([0, 1, 2, 3, 4, 5]);

assert.deepEqual(collection, expected)

Generating with step

const collection = u.range(0, 6, 2);

const expected = u([0, 2, 4, 6]);

assert.deepEqual(collection, expected)

Setup

$npm install ursus-utilus-collections

Technologies

Project is created with:

• benchmark 2.1.4
• chai 4.2.0
• mocha 8.1.0
• ts-mocha 7.0.0
• ts-node 8.10.2
• typescript 3.9.7