A better API for arrays that you can activate whenever you like. It is a little like an underscore.js, but only for arrays. Inspired by Ruby's core library, but closer to JavaScript's.
var BetterArray = require('better-array'); // if node/commonjs
You feed your arrays into the BetterArray()
function:
var a = BetterArray([3, "b", 4, null, 5, "b", 0]);
Now, a
is a BetterArray object and has access to all the wonderful methods below. For example, compact
, which removes all null
and undefined
elements:
a.compact(); // => [3, 'b', 4, 5, "b", 0]
Please note that the resulting objects are always vanilla JS objects, not BetterArray wrapper objects. This is intentional; the main goal of this library is not the ability to chain, but to be very unobtrusive.
- Good API over performance
- Delegate to native functions whenever possible
- Don't extend
Array.prototype
Use the script file directly (via the BetterArray
browser global), or get it from npm:
$ npm install better-array
$ node
> ba = require('better-array')
> array = ba([2, 3, 4, 4, 5])
> array.first()
2
> array.last()
5
> array.last(3)
[ 4, 4, 5 ]
> array.minus([3, 4])
[ 2, 5 ]
> array.or([4, 5, 6])
[ 2, 3, 4, 5, 6 ]
> array.unique()
[ 2, 3, 4, 5 ]
> array.count(4)
2
> array.contains(9)
false
> array.isEmpty()
false
> array.doesSome(function(e){ return e % 2 == 0 })
true
> array.doesEvery(function(e){ return e % 2 == 0 })
false
> array.doesNone(function(e){ return e % 2 == 0 })
false
> array.$insert(2, "new element");
// array is now [2, 3, 'new element', 4, 4, 5 ]
See better_array_spec for more examples!
All methods that begin with $
mutate the original array, the others don't.
Method | Description |
---|---|
.and(array) |
Returns the intersection: Keep only values which can be found in both arrays |
.at(index) |
Returns value at this index. Returns an array with the values when given multiple arguments |
.$clear() |
Deletes all content from the array and returns the emptied array |
.clone() |
Returns a new array object referencing the same values |
.compact() |
Returns array with all null and undefined values removed. Note that this is different from underscore's version, which removes all falsy values. |
.contains() |
Returns boolean that indicates if the element is part of the array |
.count() |
Returns number of elements. If argument given, returns how often this object appears(using === ) |
.$delete(index) |
Remove the element at the given index. Can take multiple arguments. |
.doesEvery() |
Array.prototype.every |
.doesSome() |
Array.prototype.some |
.doesNone() |
Returns true if none of the elements returns a true value for the test function |
.each() |
Array.prototype.forEach |
.filter() |
Array.prototype.filter |
.first() |
Returns the first element |
.grep() |
Returns an array of elements matching the (regex) test |
.first(integer) |
Returns an array of the first N elements |
.grep(matcher) |
Returns a filtered array by calling matcher.test() on every element, so you can use it to filter an array of strings using a regex |
.indexOf() |
Array.prototype.indexOf |
.$insert(index, value) |
Inserts an new element at this position |
.isEmpty() |
Returns true if the array is empty |
.last() |
Returns the last element. Returns an array of the last N elements if an integer argument given |
.lastIndexOf() |
Array.prototype.lastIndexOf |
.map() |
Array.prototype.map |
.minus(array) |
Returns an array with unique values and all elements of the other array removed |
.or(array) |
Returns a unique array out of all elements of both arrays |
.plus(array) |
Returns a concatenated array |
.$pop() |
Array.prototype.pop |
.$push() |
Array.prototype.push |
.reduce() |
Array.prototype.reduce |
.reduceRight() |
Array.prototype.reduceRight |
.reverse() |
Returns the reversed array |
.$reverse() |
Array.prototype.reverse |
.rotate() |
Returns an array with the first element(s) put at the end |
.$set(index, value) |
Sets the value at the given index |
.size() |
Returns the array length |
.$shift() |
Array.prototype.shift |
.slice() |
Array.prototype.slice |
.sliceLength(index, length) |
Returns an array slice, but second parameter determines length instead of end position |
.sort() |
Returns the array with all elements sorted |
.$sort() |
Array.prototype.sort |
.$splice() |
Array.prototype.splice |
.times(integer) |
Repeats the array N times |
.toArray() |
Returns the underlying array |
.unique() |
Returns array with no double entries |
.$unshift() |
Array.prototype.unshift |
.withoutFirst(number) |
Returns an array without the first N elements |
.withoutLast(number) |
Returns an array without the last N elements |
.zip(*arrays) |
Returns the transposed array |
You have two options to chain together multiple better array functions:
BetterArray.chain([2, null, 3, 4]).reverse().compact().toArray() // => [4, 3, 2]
Array.prototype.betterArray = function betterArray(){
return BetterArray(this);
}
Use it like this:
BetterArray([2, null, 3, 4]).reverse().betterArray().compact() // => [4, 3, 2]
Not implemented, yet:
- xor
- eachRight
- mapRight
- $deleteValue
- isEqual
- find
- findIndex
- $fill
- fetch
- flatten
- reject
- sample
- shuffle
- $shuffle
- groupBy
- eachWindow (each_slice)
- eachGroupOf (each_cons)
- eachWithObject
- cycle
- min
- max
- minmax
Don't like better-array's different approach? Try one of these:
- http://underscorejs.org
- https://lodash.com
- http://sugarjs.com
- http://rubyjs.org
- http://stringjs.com
- http://matthewmueller.github.io/array/
Copyright (C) 2015 Jan Lelis http://janlelis.com. Released under the MIT license.