cellophane.js
A lightweight wrapper around the array.
API
var cellophane = ;
Constructor
Methods
.any(fn)
.any(op, val)
.any(key, op, val)
.append(obj)
.compact()
.contains(obj [, opts])
.each(fn)
.every(fn)
.every(op, val)
.every(key, op, val)
.filter(fn)
.filter(op, val)
.filter(key, op, val)
.first([n])
.fold(fn, acc)
.foldRight(fn, acc)
.get(i)
.indexOf(obj [, opts])
.insert(obj, i)
.last([n])
.limit(n)
.map(fn)
.max([key])
.min([key])
.prepend(obj)
.remove(obj [, opts])
.removeAt(i)
.reverse()
.size()
.slice(i [, j])
.sort(comp)
.sort([opts])
.sortBy(key [, opts])
.unique([opts])
.unwrap()
--
cellophane([array])
Constructs a new Cellophane object. If array
was specified, sets the Cellophane object’s “internal” array to array
. Throws if array
is not an array.
var a = ;var b = ;var c = ;
.any(fn)
Returns true
if the fn
iterator is truthy for any object in the array.
var c = ; c; //=> true c; //=> false
.any(op, val)
Returns true
if the comparison with val
using the op
operator returns true
for any object in the array.
var c = ; c; //=> truec; //=> false
.any(key, op, val)
Returns true
if the comparison with val
using the op
operator returns true
for the value at key
of any object in the array. key
can be a dot-delimited path.
var c = ; c; //=> truec; //=> false
.append(obj)
Adds obj
to the end of the array, returning the result as a new Cellophane object.
Aliases: add
, push
; //=> cellophane([1, 2, 3])
.compact()
Returns a new Cellophane object with falsy values removed.
compact; //=> cellophane([1, 2, 3])
.contains(obj [, opts])
Returns true
if the array contains obj
, with objects compared by value. For strict comparison, set opts.strict
to true
.
var c = ; c; //=> truec; //=> false
.each(fn)
Calls the fn
iterator on each object in the array, and returns the original Cellophane object. Return false
in the fn
iterator to break from the loop.
Alias: forEach
;
.every(fn)
Returns true
if the fn
iterator is truthy for every object in the array.
var c = ; c; //=> true c; //=> false
.every(op, val)
Returns true
if the comparison with val
using the op
operator returns true
for every object in the array.
var c = ; c; //=> truec; //=> false
.every(key, op, val)
Returns true
if the comparison with val
using the op
operator returns true
for the value at key
of every object in the array. key
can be a dot-delimited path.
var c = ; c; //=> truec; //=> false
.filter(fn)
Filters the array using the fn
iterator, returning the filtered result as a new Cellophane object.
; //=> cellophane([2, 3])
.filter(op, val)
Filters the array. Objects that return true
when compared with val
using the op
operator will be included in the filtered result. Returns the filtered result as a new Cellophane object.
; //=> cellophane([2, 3])
.filter(key, op, val)
Filters the array. Objects whose value at key
returns true
when compared with val
using the op
operator will be included in the filtered result. Returns the filtered result as a new Cellophane object. key
can be a dot-delimited path.
;//=> cellophane([// { foo: 2 },// { foo: 3 }// ])
.first([n])
Returns the first object in the array. If n
is specified, returns the first n
objects of the array as a new Cellophane object.
var c = ; c; //=> 1c; //=> cellophane([1, 2])
.fold(fn, acc)
Accumulates the objects in the array to a single value, with the accumulator value initialised to acc
. Returns the final value of acc
. If acc
is an array, returns it wrapped in a new Cellophane object. The fn
iterator takes 4 arguments:
acc
— The current value of the accumulator.val
— The current value of the array being iterated over.i
— The current index.array
— The Cellophane object’s internal array.
Aliases: foldLeft
, foldl
, reduce
, reduceLeft
var c = ; c; //=> 6 c; //=> cellophane([10, 20, 30])
.foldRight(fn, acc)
Just like fold
, but the array is iterated over from right to left.
Aliases: foldr
, reduceRight
.get(i)
Returns the object at index i
of the array, or undefined
if i
is an invalid index. If i
is negative, indexing is from the end of the array (ie. index -1
refers to the last object in the array, and so on).
var c = ; c; //=> 1c; //=> 2c; //=> 3c; //=> undefined c; //=> 3c; //=> 2c; //=> 1
.indexOf(obj [, opts])
Returns the index of the first instance of obj
in the array, with objects compared by value. For strict comparison, set opts.strict
to true
. Returns -1
if obj
is not found in the array.
var c = ; c; //=> 1 c; //=> 2c; //=> -1
.insert(obj, i)
Inserts obj
at index i
of the array, returning the result as a new Cellophane object. If i
is negative, indexing is from the end of the array (ie. index -1
refers to the last object in the array, and so on). If i
is beyond the bounds of the original array, the resulting array is “expanded” accordingly.
var c = ; c; //=> cellophane(['foo', 1, 2, 3])c; //=> cellophane([1, 2, 3, 'foo'])c; //=> cellophane([1, 2, 3, undefined, 'foo']) c; //=> cellophane([1, 2, 3, 'foo'])c; //=> cellophane(['foo', 1, 2, 3])c; //=> cellophane(['foo', undefined, 1, 2, 3])
.last([n])
Returns the last object in the array. If n
is specified, returns the last n
objects of the array as a new Cellophane object.
var c = ; c; //=> 3c; //=> cellophane([2, 3])
.limit(n)
If n
is positive, returns the first n
objects of the array as a new Cellophane object. Else returns the last |n|
objects of the array as a new Cellophane object.
var c = ; c; //=> cellophane([1, 2])c; //=> cellophane([2, 3])
.map(fn)
Maps the array over the fn
iterator, returning the result as a new Cellophane object.
; //=> cellophane([10, 20, 30])
.max([key])
Returns the largest object in the array. If key
was specified, compares the objects based on the value corresponding to key
. key
can be a dot-delimited path.
Aliases: maximum
, largest
; //=> 3 ; //=> { foo: 3 }
.min([key])
Returns the smallest object in the array. If key
was specified, compares the objects based on the value corresponding to key
. key
can be a dot-delimited path.
Aliases: minimum
, smallest
; //=> 1 ; //=> { foo: 1 }
.prepend(obj)
Adds obj
to the start of the array, returning the result as a new Cellophane object.
; //=> cellophane([1, 2, 3])
.remove(obj [, opts])
Removes all objects that are equal to obj
from the array, with objects compared by value. For strict comparison, set opts.strict
to true
. Returns the result as a new Cellophane object.
;//=> cellophane([// { foo: 2 },// { foo: 3 }// ]) ;//=> cellophane([// { foo: 1 },// { foo: 2 },// { foo: 3 },// { foo: 1 }// ])
.removeAt(i)
Removes the object at index i
of the array, returning the result as a new Cellophane object.
; //=> cellophane([1, 3])
.reverse()
Returns a new Cellophane object with the ordering of its objects reversed.
; //=> cellophane([3, 2, 1])
.size()
Returns the array size.
Alias: length
size; //=> 0size; //=> 3
.slice(i [, j])
Takes a slice of the array and returns it as a new Cellophane object.
Alias: subarray
; //=> cellophane([2, 3])
.sort(comp)
Sorts the array using the comp
comparator function, returning the sorted result as a new Cellophane object. comp
takes two arguments a
and b
, and must return:
- a negative value if
a
is to be ordered beforeb
, or - a positive value if
a
is to be ordered afterb
, or 0
if the ordering ofa
andb
(with respect to each other) should be left unchanged.
; //=> cellophane([1, 2, 3])
.sort([opts])
Sorts the array in ascending order, returning the sorted result as a new Cellophane object. Set opts.order
to 'desc'
to sort in descending order.
; //=> cellophane([1, 2, 3]); //=> cellophane([3, 2, 1])
.sortBy(key [, opts])
Sorts the array of objects in ascending order based on the value corresponding to key
of each object, returning the sorted result as a new Cellophane object. key
can be a dot-delimited path. To sort in descending order, set opts.order
to 'desc'
.
var c = ; c;//=> cellophane([// { foo: 1 },// { foo: 2 },// { foo: 3 }// ]) c;//=> cellophane([// { foo: 3 },// { foo: 2 },// { foo: 1 }// ])
.unique([opts])
Removes duplicates removed from the array, with objects compared by value. For strict comparison, set opts.strict
to true
. Returns the result as a new Cellophane object.
var c = ; c;//=> cellophane([// { foo: 1 },// { foo: 2 },// { foo: 3 }// ]) c;//=> cellophane([// { foo: 1 },// { foo: 2 },// { foo: 3 },// { foo: 1 }// ])
.unwrap()
Returns a copy of the Cellophane object’s “internal” array.
; //=> [1, 2, 3]
Usage notes
Accessing the “internal” array
We can get the Cellophane object’s “internal” array on its .array
attribute:
var original = ; console; //=> [{ foo: 1 }, { foo: 2 }, { foo: 3 }]
Methods always return a copy
A Cellophane object is designed to be immutable. So, for all methods (apart from each
) that returns a Cellophane object, it is actually a copy of the original Cellophane object that is returned:
var filtered = original; console; //=> false
By copy, we mean that while filtered.array
and original.array
are different arrays, and refer to different objects in memory…
console; //=> false
…they actually contain references to the same objects:
console; //=> trueconsole; //=> true
Iterator function signature
For all methods that take an iterator fn
(called over each object in the array), note that the iterator is passed 3 arguments:
val
— The current object of the array being iterated over.i
— The index of the current object.array
— The Cellophane object’s internal array.
The exceptions are the fold
and foldr
methods; their fn
iterator takes an additional acc
accumulator argument.
Compare by value
In the contains
, indexOf
, and remove
methods, the default behavior is to compare objects by value. For example:
; //=> true
See deep-equal.
To use strict comparison (where objects a
and b
are considered as equal if and only if a === b
), set opts.strict
to true
.
var opts = strict: true ; ; //=> false
Operators for comparing values
In the any
, every
, and filter
methods, the op
argument must be one of the following strings:
'=='
'==='
'!='
'!=='
'<'
'>'
'<='
'>='
See Versus.js.
Accessing nested properties
In the any
, every
, filter
, and sortBy
methods, access a nested object property by specifying a dot-delimited path as the key
. For example:
; //=> true
See Jaunt.js.
Installation
Install via npm:
$ npm i --save cellophane
Changelog
- 0.1.0
- Initial release