Cellophane NPM

cellophane.js

A lightweight wrapper around the array.

API

var cellophane = require('cellophane');

Constructor

cellophane([array])

Methods

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 = cellophane();
var b = cellophane([]);
var c = cellophane([1, 2, 3]);

↩

.any(fn)

Returns true if the fn iterator is truthy for any object in the array.

var c = cellophane([1, 2, 3]);

c.any(function(val, i, array) {
  return val > 1;
}); //=> true

c.any(function(val, i, array) {
  return val > 3;
}); //=> 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 = cellophane([1, 2, 3]);

c.any('>', 1); //=> true
c.any('>', 3); //=> 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 = cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]);

c.any('foo', '>', 1); //=> true
c.any('foo', '>', 3); //=> 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]).append(3); //=> cellophane([1, 2, 3])

↩

.compact()

Returns a new Cellophane object with falsy values removed.

cellophane([0, 1, 2, 3]).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 = cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]);

c.contains({ foo: 3 }); //=> true
c.contains({ foo: 3 }, { strict: true }); //=> 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

cellophane([1, 2, 3]).each(function(val, i, array) {
  console.log(val, i, array);
  //=> 1, 0, [1, 2, 3]
  //=> 2, 1, [1, 2, 3]
  if (val === 2) {
    return false;
  }
});

↩

.every(fn)

Returns true if the fn iterator is truthy for every object in the array.

var c = cellophane([1, 2, 3]);

c.every(function(val, i, array) {
  return val < 4;
}); //=> true

c.every(function(val, i, array) {
  return val < 3;
}); //=> 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 = cellophane([1, 2, 3]);

c.every('<', 4); //=> true
c.every('<', 3); //=> 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 = cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]);

c.every('foo', '<', 4); //=> true
c.every('foo', '<', 3); //=> false

↩

.filter(fn)

Filters the array using the fn iterator, returning the filtered result as a new Cellophane object.

cellophane([1, 2, 3]).filter(function(val, i, array) {
  return val > 1;
}); //=> 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([1, 2, 3]).filter('>', 1); //=> 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: 1 },
  { foo: 2 },
  { foo: 3 }
]).filter('foo', '>', 1);
//=> 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 = cellophane([1, 2, 3]);

c.first(); //=> 1
c.first(2); //=> 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 = cellophane([1, 2, 3]);

c.fold(function(acc, val, i, array) {
  return acc + val;
}, 0); //=> 6

c.fold(function(acc, val, i, array) {
  acc.push(val * 10);
  return acc;
}, []); //=> 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 = cellophane([1, 2, 3]);

c.get(0); //=> 1
c.get(1); //=> 2
c.get(2); //=> 3
c.get(3); //=> undefined

c.get(-1); //=> 3
c.get(-2); //=> 2
c.get(-3); //=> 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 = cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 2 },
  { foo: 3 }
]);

c.indexOf({ foo: 2 }); //=> 1

c.indexOf({ foo: 3 }); //=> 2
c.indexOf({ foo: 3 }, { strict: true }); //=> -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 = cellophane([1, 2, 3]);

c.insert('foo', 0); //=> cellophane(['foo', 1, 2, 3])
c.insert('foo', 3); //=> cellophane([1, 2, 3, 'foo'])
c.insert('foo', 4); //=> cellophane([1, 2, 3, undefined, 'foo'])

c.insert('foo', -1); //=> cellophane([1, 2, 3, 'foo'])
c.insert('foo', -4); //=> cellophane(['foo', 1, 2, 3])
c.insert('foo', -5); //=> 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 = cellophane([1, 2, 3]);

c.last(); //=> 3
c.last(2); //=> 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 = cellophane([1, 2, 3]);

c.limit(2); //=> cellophane([1, 2])
c.limit(-2); //=> cellophane([2, 3])

↩

.map(fn)

Maps the array over the fn iterator, returning the result as a new Cellophane object.

cellophane([1, 2, 3]).map(function(val, i, array) {
  return val * 10;
}); //=> 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

cellophane([1, 2, 3]).max(); //=> 3

cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]).max('foo'); //=> { 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

cellophane([1, 2, 3]).min(); //=> 1

cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]).min('foo'); //=> { foo: 1 }

↩

.prepend(obj)

Adds obj to the start of the array, returning the result as a new Cellophane object.

cellophane([2, 3]).prepend(1); //=> 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: 1 },
  { foo: 2 },
  { foo: 3 },
  { foo: 1 }
]).remove({ foo: 1 });
//=> cellophane([
//     { foo: 2 },
//     { foo: 3 }
//   ])

cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 },
  { foo: 1 }
]).remove({ foo: 1 }, { strict: true });
//=> 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, 2, 3]).removeAt(1); //=> cellophane([1, 3])

↩

.reverse()

Returns a new Cellophane object with the ordering of its objects reversed.

cellophane([1, 2, 3]).reverse(); //=> cellophane([3, 2, 1])

↩

.size()

Returns the array size.

Alias: length

cellophane([]).size(); //=> 0
cellophane([1, 2, 3]).size(); //=> 3

↩

.slice(i , j)

Takes a slice of the array and returns it as a new Cellophane object.

Alias: subarray

cellophane([1, 2, 3]).slice(1, 3); //=> 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 before b, or
a positive value if a is to be ordered after b, or
0 if the ordering of a and b (with respect to each other) should be left unchanged.

cellophane([3, 1, 2]).sort(function(a, b) {
  return a < b ? -1 : 1;
}); //=> 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([3, 1, 2]).sort(); //=> cellophane([1, 2, 3])
cellophane([3, 1, 2]).sort({ order: 'desc' }); //=> 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 = cellophane([
  { foo: 3 },
  { foo: 1 },
  { foo: 2 },
]);

c.sortBy('foo');
//=> cellophane([
//     { foo: 1 },
//     { foo: 2 },
//     { foo: 3 }
//   ])

c.sortBy('foo', { order: 'desc' });
//=> 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 = cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 },
  { foo: 1 }
]);

c.unique();
//=> cellophane([
//     { foo: 1 },
//     { foo: 2 },
//     { foo: 3 }
//   ])

c.unique({ strict: true });
//=> cellophane([
//     { foo: 1 },
//     { foo: 2 },
//     { foo: 3 },
//     { foo: 1 }
//   ])

↩

.unwrap()

Returns a copy of the Cellophane object’s “internal” array.

cellophane([1, 2, 3]).unwrap(); //=> [1, 2, 3]

↩

Usage notes

Accessing the “internal” array

We can get the Cellophane object’s “internal” array on its .array attribute:

var original = cellophane([{ foo: 1 }, { foo: 2 }, { foo: 3 }]);

console.log(original.array); //=> [{ 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.filter('foo', '>', 1);

console.log(filtered === original); //=> false

By copy, we mean that while filtered.array and original.array are different arrays, and refer to different objects in memory…

console.log(filtered.array === original.array); //=> false

…they actually contain references to the same objects:

console.log(filtered.array[0] === original.array[1]); //=> true
console.log(filtered.array[1] === original.array[2]); //=> 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:

cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]).contains({ foo: 3 }); //=> 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 };

cellophane([
  { foo: 1 },
  { foo: 2 },
  { foo: 3 }
]).contains({ foo: 3 }, opts); //=> 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:

cellophane([
  { foo: { bar: 1 } },
  { foo: { bar: 2 } },
  { foo: { bar: 3 } }
]).any('foo.bar', '>', 0); //=> true

See Jaunt.js.

Installation

Install via npm:

$ npm i --save cellophane

Changelog

0.1.0
- Initial release

License

MIT

array collection list vector

cheque deep-equal jaunt versus

@infinitebrahmanuniverse/nolb-cel @everything-registry/sub-chunk-1305

11 years ago

11 years ago

11 years ago

11 years ago