emgyrz / collossus

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

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

License

This module is MIT licensed.

Enjoy using!