Collossus NPM | npm.io

collossus

Collection of elements of the same type, has everything that we are so lacking in JS Arrays and a little more.

Benefits and specialities:

It is strongly typed: written in TypeScript and has Flow declarations
No more boilerplate code when working with arrays
Unbelievable helps when your data has identifiers
Ready to use with MobX. See this block
No built-in objects prototype modifications
Unlike some utility libraries (lodash etc.) which are generally very helpful, you may code in OOP style not by calling multiple unrelated functions
There is no unnecessary methods, focus only on working with arrays

What it has

Exports two main classes:

Collection - Just a wrapper around the Array, adds methods that make life easier (docs).
IdCollection - Identified collection. This collection is inherited from the previous one. Designed to work with data that has an id: number | string (docs).

Example:

Some of `Collection` class

import { Collection } from 'collossus'

const names = new Collection( [ 'Max' ] ) // [ ' Max' ]
names.push( [ 'Yan', 'Li' ] ) // [ ' Max', 'Yan', 'Li' ]
names.last() // -> 'Li'
names.swap( 1, 2 ) // [ ' Max', 'Li', 'Yan' ]
names.pushUniq( 'Max' ) // [ ' Max', 'Li', 'Yan' ]
names.rfindIndexBy( n => n === 'Yan' ) // -> 2
names.clear() // []

Some of `IdCollection` class

import { IdCollection } from 'collossus'

type User = { id: number, name: string }

const users = new IdCollection<User>( [ { id: 33, name: 'Max' } ] ) // [{ id: 33, name: 'Max' }]
users.push( [ { id: 55, name: 'Yan' } ] ) // [{ id: 33, name: 'Max' },{ id: 55, name: 'Yan' }]
users.findById( 33 ) // -> { id: 33, name: 'Max' }
users.pushUniqById( { id: 55, name: 'Li' } ) // [{ id: 33, name: 'Max' },{ id: 55, name: 'Yan' }]
users.removeById( 55 ) // [ { id: 33, name: 'Max' } ]
users.first() // { id: 33, name: 'Max' }
users.clear() // []

Methods

`Collection` methods

chunks - ( chunkSize: number ) => Array<Array<T>>
clear - () => void
drainFilterBy - ( predicate: CallbackFuncType<T, boolean> ) => Array<T>
filterBy - ( predicate: CallbackFuncType<T, boolean> ) => Collection<T>
findBy - ( predicate: CallbackFuncType<T, boolean>, startIndex?: number ) => null | T
findIndexBy - ( predicate: CallbackFuncType<T, boolean>, startIndex?: number ) => number
first - () => null | T
forEach - ( closure: CallbackFuncType<T, void> ) => void
get - ( index: number ) => null | T
getInnerRef - () => Array<T>
has - ( it: T ) => boolean
isEmpty - () => boolean
last - () => null | T
lastIndex - () => number
map - <R>( closure: CallbackFuncType<T, R> ) => Collection<R>
mapArr - <R>( closure: CallbackFuncType<T, R> ) => Array<R>
pop - () => null | T
push - ( it: T | Array<T> ) => void
pushUniq - ( it: T | Array<T> ) => void
pushUniqBy - ( it: T | Array<T>, compare: CompareFuncType<T> ) => void
reduce - <A>( callback: ( acc: A, it: T ) => A, initValue: A ) => A
remove - ( index: number ) => null | T
removeBy - ( predicate: CallbackFuncType<T, boolean> ) => null | T
repeat - ( num: number ) => Collection<T>
reset - ( data: null | Array<T> ) => void
retainBy - ( predicate: CallbackFuncType<T, boolean> ) => Array<T>
rfindBy - ( predicate: CallbackFuncType<T, boolean>, startIndex?: number ) => null | T
rfindIndexBy - ( predicate: CallbackFuncType<T, boolean>, startIndex?: number ) => number
set - ( index: number, it: T ) => boolean
shift - () => null | T
shuffle - () => void
swap - ( indexA: number, indexB: number ) => boolean
toArray - () => Array<T>
toJSON - () => null | string
truncate - ( len: number ) => boolean

`IdCollection` methods

findById - ( id: IdOf<T> ) => null | T
findIndexById - ( id: IdOf<T> ) => number
hasById - ( id: IdOf<T> ) => boolean
pushUniqById - ( it: Array<T> | T ) => void
removeById - ( id: IdOf<T> ) => null | T

Using with `Mobx`

Library exports two classes that prepared to be observable - ObservableCollection and ObservableIdCollection. But since it does not have Mobx in its dependencies you should patch it with your version of Mobx. You need to do it just once in your project before creating instances of observable collection.

import * as mobx from 'mobx'
import { patchObservableCollections, ObservableCollection } from 'collossus'

// call this somewhere on init
patchObservableCollections( mobx )

// now ObservableCollection is **really** observable
const oc = new ObservableCollection( [ 1, 2, 3 ] )

// this is `computed`
oc.length
// this is `action`
oc.push( 4 )
// and this too
oc.remove( 0 )

Everything else is identical to Collection and IdCollection