cellophane

    0.1.2 • Public • Published

    cellophane.js npm Version Build Status Coverage Status

    A lightweight wrapper around the array.

    API

    var cellophane = require('cellophane');

    Constructor

    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

    Install

    npm i cellophane

    DownloadsWeekly Downloads

    1

    Version

    0.1.2

    License

    MIT

    Last publish

    Collaborators

    • yuanqing