muster-js
v0.1.0
Published
A small library to work with arrays in Javascript.
Downloads
8
Readme
MusterJS
Muster is the definitive way to work with collections in Javascript.
How to install:
npm install muster-js
Example of use:
var collect = require('muster-js').collect;
var collection = collect([
{ id: 1, name: 'Bulbasaur', type: 'grass' },
{ id: 4, name: 'Charmander', type: 'fire' },
{ id: 7, name: 'Squirtle', type: 'blue' }
]);
collection.count(); //outputs 3
collection.get(2).name; //outputs 'Squirtle'Most of methods return a new collection, so you can chain the calls if you want:
var collect = require('muster-js').collect;
var collection = collect([
{ id: 1, name: 'Bulbasaur', type: 'grass' },
{ id: 4, name: 'Charmander', type: 'fire' },
{ id: 7, name: 'Squirtle', type: 'water' }
]);
collection
.union([
{ id: 152, name: 'Chikorita', type: 'grass' },
{ id: 155, name: 'Cindaquil', type: 'fire' },
{ id: 158, name: 'Totodile', type: 'water' }
])
.where('type', 'water')
.all(); //outputs '[{ id: 7, name: 'Squirtle', type: 'water' }, { id: 158, name: 'Totodile', type: 'water' }]'API documentation
all()
Get all of the items in the collection.
Returns: Array
avg(callback)
Get the average value of a given key.
Parameters
callback: string | function
Returns: *
chunk(size)
Chunk the underlying collection array.
Parameters
size: int
Returns: Collection
collapse()
Collapse the collection of items into a single array.
Returns: Collection
combine(values)
Create a collection by using this collection for keys and another for its values.
Parameters
values: *
Returns: Collection
contains(key, value)
Determine if an item exists in the collection.
Parameters
key: *
value: *
Returns: bool
containsStrict(key, value)
Determine if an item exists in the collection using the strict mode.
Parameters
key: *
value: *
Returns: bool
count()
Count the number of items in the collection.
Returns: int
diff(items)
Get the items in the collection that are not present in the given items.
Parameters
items: *
Returns: Collection
each(callback)
Execute a callback over each item.
Parameters
callback: function
Returns: this
every(step, offset)
Create a new collection consisting of every n-th element.
Parameters
step: int
offset: int
Returns: Collection
except(keys)
Get all items except for those with the specified keys.
Parameters
keys: *
Returns: Collection
filter(callback)
Run a filter over each of the items.
Parameters
callback: function | null
Returns: Collection
first(callback, default)
Get the first item from the collection.
Parameters
callback: function | null
default: *
Returns: *
flatten(depth)
Get a flattened array of the items in the collection.
Parameters
depth: int
Returns: Collection
flip()
Flip the items in the collection.
Returns: Collection
forget(keys)
Remove an item from the collection by key.
Parameters
keys: string | array
Returns: this
forPage(page, perPage)
"Paginate" the collection by slicing it into a smaller collection.
Parameters
page: int
perPage: int
Returns: Collection
get(key, callback)
Get an item from the collection by key.
Parameters
key: int
callback: *
Returns: *
groupBy(groupBy, preserveKeys)
Group an associative array by a field or using a callback.
Parameters
groupBy: function | string
preserveKeys: bool
Returns: Collection
has(key)
Determine if an item exists in the collection by key.
Parameters
key: *
Returns: bool
implode(value, glue)
Concatenate values of a given key as a string.
Parameters
value: string
glue: string
Returns: string
intersect(items)
Intersect the collection with the given items.
Parameters
items: *
Returns: Collection
isEmpty()
Determine if the collection is empty or not.
Returns: bool
keyBy(keyBy)
Key an associative array by a field or using a callback.
Parameters
keyBy: function | string
Returns: Collection
keys()
Get the keys of the collection items.
Returns: Collection
last(callback, default)
Get the last item from the collection.
Parameters
callback: function | null
default: *
Returns: *
map(callback)
Run a map over each of the items.
Parameters
callback: function
Returns: Collection
max(key)
Get the max value of a given key.
Parameters
key: string | null
Returns: *
median(null)
Get the median of a given key.
Parameters
null: key
Returns: *
merge(items)
Merge the collection with the given items.
Parameters
items: *
Returns: Collection
min(key)
Get the min value of a given key.
Parameters
key: string | null
Returns: *
mode(key)
Get the mode of a given key.
Parameters
key: string | null
Returns: Array
pipe(callback)
Pass the collection to the given callback and return the result.
Parameters
callback: function
Returns: *
pluck(value)
Get the values of a given key.
Parameters
value: string
Returns: Collection
pop()
Get and remove the last item from the collection.
Returns: *
prepend(value, key)
Push an item onto the beginning of the collection.
Parameters
value: *
key: *
Returns: this
pull(key)
Get and remove an item from the collection.
Parameters
key: *
Returns: this
push(value)
Push an item onto the end of the collection.
Parameters
value: *
Returns: this
random(amount)
Get one or more items randomly from the collection.
Parameters
amount: int
Returns: *
reduce(callback, initial)
Reduce the collection to a single value.
Parameters
callback: function
initial: *
Returns: *
reject(callback)
Create a collection of all elements that do not pass a given truth test.
Parameters
callback: function
Returns: Collection
reverse()
Reverse items order.
Returns: Collection
search(value, strict)
Search the collection for a given value and return the corresponding key if successful.
Parameters
value: *
strict: bool
Returns: *
shift()
Get and remove the first item from the collection.
Returns: *
shuffle()
Shuffle the items in the collection.
Returns: Collection
slice(offset, length)
Slice the underlying collection array.
Parameters
offset: int
length: int
Returns: Collection
sort(callback)
Sort through each item with a callback.
Parameters
callback: function | null
Returns: Collection
sortBy(callback, options, descending)
Sort the collection using the given callback.
Parameters
callback: function | string
options: int
descending: bool
Returns: Collection
sortByDesc(callback, options)
Sort the collection in descending order using the given callback.
Parameters
callback: function | string
options: int
Returns: Collection
splice(offset, length, replacement)
Splice a portion of the underlying collection array.
Parameters
offset: int
length: int | null
replacement: *
Returns: Collection
sum(callback)
Get the sum of the given values.
Parameters
callback: function | string | null
Returns: *
take(limit)
Take the first {limit} items.
Parameters
limit: int
Returns: Collection
toString(limit)
Converts the items in a string.
Parameters
limit: int
Returns: Collection
transform(callback)
Transform each item in the collection using a callback.
Parameters
callback: function
Returns: , this
union(items)
Union the collection with the given items.
Parameters
items: *
Returns: Collection
unique(key, strict)
Return only unique items from the collection array.
Parameters
key: string | function | null
strict: bool
Returns: Collection
values()
Reset the keys on the underlying array.
Returns: Collection
where(key, operator, value)
Filter items by the given key value pair.
Parameters
key: string
operator: *
value: *
Returns: Collection
whereIn(key, values, strict)
Filter items by the given key value pair.
Parameters
key: string
values: *
strict: bool
Returns: Collection
whereInStrict(key, values)
Filter items by the given key value pair using strict comparison.
Parameters
key: string
values: *
Returns: Collection
whereStrict(key, value)
Filter items by the given key value pair using strict comparison.
Parameters
key: string
value: *
Returns: Collection
zip(items)
Zip the collection together with one or more arrays.
e.g. collect([1, 2, 3]).zip([4, 5, 6]); => [[1, 4], [2, 5], [3, 6]]
Parameters
items: array, Zip the collection together with one or more arrays.
Returns: Collection