Welcome to Arcaelas Insiders!

Hello, if this is your first time reading the Arcaelas Insiders documentation, let me tell you that you have found a good place to learn.

Our team and community are happy to write and make methods simple to implement and understand, but I think you already know that.

The documentation for this tool is open to edits and suggestions.

Let's start with the basic implementation steps.

> npm i --save @arcaelas/collection
> yarn add --save @arcaelas/collection

Implementation

// Class Import Statement
import Collection from  '@arcaelas/Collection'

// Function import statement
import { Collection } from  '@arcaelas/collection'

// EsModule
const Collection =  require('@arcaelas/collection')

Motivation

In object-oriented programming we find common situations, such as those where we want to order, filter and modify elements of a list, however the "Array Prototypes" are not very complete in some cases, for these situations the Arcaelas Insiders team has designed useful tools that allow these actions within "Collections".

Curiosities

As an interesting part of this tool, we have the B-JSON notation that Atlas implements in its MongoDB database engine, only some of them are implemented here, but we will explain how to extend them and create your own validators.

Get Started

import Collection from "@arcaelas/collection"

const collection = new Collection([ ... ])

all

Return all elements as Plain JSON

collection.all() // Expected: [ {...}, ... ]

collect

Create a collection with parent collection prototypes.

collection.collect([...]) // Expected: Collection

count

Count items length into collection.

collection.count() // 0 - Infinity

find

Filter the elements of the collection using Functions and Queries, some of the examples could be:

NOTE: It is important to use "$" to refer to a property based query.

collection.find(item=>{
	return item.age >= 18;
});
// or
collection.find({
	age:{ $gte: 18 }
});
collection.find({
	name: /Alejandro/,
	skills:{
		$contains: "Liberty"
	},
	gender:{
		$not:{
			$in: ['animal','fruit'],
		}
	},
	work:{
		$not:{
			$in: ["work", "without", "coffe"]
		}
	}
});

first

Use find() and get first element

users.first({
	_id: "...",
	age:{ $gte: 18 },
	role:{
		$not:{
			$in:["admin"]
		}
	}
})

not

Is opposite of find()

users.find({
	online: { $not: false }
})
user.not({
	online: false
})

where

Use this shorthand to filter items

const offline = users.where("online", false)
const online = users.where("online", "==", false)

whereNot

Is opposite of where()

const offline = users.whereNot("online", true)
const online = users.whereNot("online", "==", true)

dd

The dd method will console.log the collection and exit the current process

collection.dd()
// Collection { items: [ 1, 2, 3 ] }
// (Exits node.js process)

dump

Print collection and continue.

collection.dump()

max

The max method returns the maximum value of a given key.

pictures.max("upvotes")

min

The min method returns the minimum value of a given key.

pictures.min("upvotes")

random

Get random elements, with the argument "length" the number of elements is indicated.

collection.random() // All elements random sorted
collection.random(2) // Two random elements

shuffle

This method set items order as random and mutate collection.

collection.shuffle()

sum

Sum the elements values according to a specific key.

const to_pay = shop_cart.sum("articles.price")

chunk

Break the collection into multiple, smaller collections of a given size.

paginate = posts.chunks(100)

countBy

Group items by key and count

products.countBy("buyed")

each

Iterate over each collection elements, if return false break iteration

sockets.each(socket=>{
	if( !socket.online ) return // This stop iteration
	socket.send("ping")
})

every

Read Array.prototype.every

forget

Remove a specific fields from each items

	sessions.forget("access_token")

groupBy

Group items by key

const online = followers.grupBy("online") // { ... }
const offline = online.false

paginate

Wrap element in X number of items and return specific page.

const page_one = post.paginate(1) // 1 - 20
const page_two = post.paginate(2, 500) // 501 - 1000

unique

Filter elements and return only elements that key/value is unique.

const unlinked = links.unique("_id")
const removed = trash.unique((item)=>{
	return item.id
})

macro

Adding custom methods for current collection.

collection.macro("getName", (item)=>{
	return item.name
}) // Expected: Collection

collection.getName() // Expected: [ Joe, Julia, ... ]

macro (static)

Adding custom method for all Collections

Collection.macro("get", (item, key)=>{...})

const pictures = new Collection([...])

pictures.get("url") // Expected: [...]

join

Returns a string with the values of the specified key in each object.

collection.join("email")
// dany@email.com,julia@email.com,rose@email.com

collection.join("folders", "-")
// dany@email.com-julia@email.com-rose@email.com

collection.join("email", ", ", " and ")
// dany@email.com, julia@email.com and rose@email.com

sort

The sort method sorts the collection.

collection.sort((a, b)=> a.age > b.age ? 1 : -1)
// or
collection.sort("age", "desc")

concat

Read Array.prototype.concat

map

Read Array.prototype.map

pop

Read Array.prototype.pop

slice

Read Array.prototype.slice

splice

Read Array.prototype.splice

shift

Read Array.prototype.shift

unshift

Read Array.prototype.unshift

¿Want to discuss any of my open source projects, or something else?Send me a direct message on Twitter.
If you already use these libraries and want to support us to continue development, you can sponsor us at Github Sponsors.

Arcaelas Collection LTS