CollectionsJS

A lightweight object for array pipelining operations.

Arrays are awesome in JavaScript and now are easier to use and manipulate using the ES5 functions like map and filter, which enables you to chain some operations like:

var array = [1, 2, 3];
array.map(i => i + 1).filter(i => i > 2);

which can be thought of as a pipeline of operations. however there are some functions that do not exist or considered as an edge case which can be fairly simple to implement, but annoying to reuse.

CollectionJS is an extensible object that acts as a wrapper around the Array object, exposing API methods and utilities, and simplifying their use. and it always returns a Collection (except for some examples) meaning you will be able to keep chaining until you get the collection you want to work with.

Why (Inspiration)?

I'm not an expert JavaScript developer, but I run into enough situations where I needed some complex operations, great libraries like lodash or underscore are amazing and offer a whole lot to do with arrays, but most methods return an array. so doing multiple operations wasn't as great. although they provide a way for chaining.

Working with The PHP framework Laravel, I came across the collection object. I didn't realize how powerful the combination of immutable objects are until I read the Refactoring to collections which is a great read for any developer.

And I had a free week at the time.

Install

npm

npm install collectionsjs --save

bower

bower install collectionjs --save

Usage

Download it manually and add the script tag at the bottom of your body, it doesn't matter in which order because there are no dependencies.

<script src="dist/collection.min.js"></script>

However if you have a more complex setup, Then in your code you can do:

// ES6
import Collection from 'collectionsjs';

or

var Collection = require('collectionsjs');

Behaviors

I have chosen to allow different types to be used for the same parameter, some may see this as some violation of some pattern out there or something, while I like to respect all best practices I think the trade of having less methods to memorize and the versatility of one method is better than writing over 2x the same amount of functions for slightly different behaviors.

• Most of the methods just defer to the existing array functions like filter and map.
• Many methods accept a different argument types for the same parameter, which will dictate its behavior like where() and first().
• Few methods are just an alias.
• sort() and sortBy() sorting doesn't change the original collection order.

API

There are just over 25+ unique methods for most of your needs I will be adding more useful ones in time.

Here is a brief summary, read the docs for different behaviors and usage:

Static Methods

• collect(collectable)
• macro(name, callback)

Instance Methods

• add(item)
• all()
• average(callback)
• chunk(size)
• concat(Array)
• contains(callback)
• count()
• each(callback)
• filter(callback)
• find(item)
• first(callback)
• flatten(deep)
• has(item)
• get(index)
• join(seperator)
• keys()
• last(callback)
• map(callback)
• pluck(callback)
• push(item)
• reduce(callback, initial)
• reject(callback)
• remove(item)
• reverse()
• skip(count)
• slice(start, end)
• sort()
• sortBy(property, order)
• stringify()
• sum(callback)
• take(count)
• unique(callback)
• values(count)
• where(callback)
• zip(Array)

Testing

I use ava for testing which is an amazing test runner. With nyc for coverage.

npm run test

and you can lint with

npm run lint

Contribution

Go a head and you will be fully credited. Don't forget to follow the code style and always add a test file for any additions.

Build

• Clone the repo: git clone [email protected]:logaretm/collectionsjs.git

• Install the dev dependencies: npm install

• Write code better than mine.

• Build the library: npm run build

which will build both minified and unminified versions.

So...Performance?

I can always use some help with optimizing things. however most of the methods are based on the underlying Array API.

MIT