utils

Fast, generic JavaScript/node.js utility functions.

Install with npm

$ npm i utils --save

TOC

<!-- toc -->

• Usage
• API
• Code coverage
• Running tests
• Contributing
  • Adding utils
  • Updating the docs
  • Running verb
• About
• Related projects
• Author
• License

(Table of contents generated by verb)

<!-- tocstop -->

Usage

Utils grouped by collection

The top level export gives you an object with utils grouped into collections, like array, object, math, etc:

var utils = require('utils');
//=> {array: {flatten: [function], ...}, collection: {...}}

See example.md for an example of the utils object.

Get all utils on one object

If you want all utils on a single object (e.g. not grouped by collection):

// all utils are on the `_` property
var utils = require('utils')._;

Only get a specific collection

If you just want the string or object utils:

var string = require('utils').string;
var object = require('utils').object;

API

.after

Returns all of the items in an array after the specified index.

Params

• array {Array}: Collection
• n {Number}: Starting index (number of items to exclude)
• returns {Array}: Array exluding n items.

Example

after(['a', 'b', 'c'], 1)
//=> ['c']

.arrayify

Cast the give value to an array.

Params

• val {*}
• returns {Array}

Example

arrayify('abc')
//=> ['abc']

arrayify(['abc'])
//=> ['abc']

.before

Returns all of the items in an array up to the specified number Opposite of <%= after() %.

Params

• array {Array}
• n {Number}
• returns {Array}: Array excluding items after the given number.

Example

before(['a', 'b', 'c'], 2)
//=> ['a', 'b']

.compact

Remove all falsey values from an array.

Params

• arr {Array}
• returns {Array}

Example

compact([null, a, undefined, 0, false, b, c, '']);
//=> [a, b, c]

.difference

Return the difference between the first array and additional arrays.

Params

• a {Array}
• b {Array}
• returns {Array}

Example

var a = ['a', 'b', 'c', 'd'];
var b = ['b', 'c'];

diff(a, b);
//=> ['a', 'd']

.each

Loop over each item in an array and call the given function on every element.

Params

• array {Array}
• fn {Function}
• thisArg {Object}: Optionally pass a thisArg to be used as the context in which to call the function.
• returns {Array}

Example

each(['a', 'b', 'c'], function (ele) {
  return ele + ele;
});
//=> ['aa', 'bb', 'cc']

each(['a', 'b', 'c'], function (ele, i) {
  return i + ele;
});
//=> ['0a', '1b', '2c']

.first

Returns the first item, or first n items of an array.

Params

• array {Array}
• n {Number}: Number of items to return, starting at 0.
• returns {Array}

Example

first(['a', 'b', 'c', 'd', 'e'], 2)
//=> ['a', 'b']

.flatten

Recursively flatten an array or arrays. Uses the fastest implementation of array flatten for node.js

Params

• array {Array}
• returns {Array}: Flattened array

Example

flatten(['a', ['b', ['c']], 'd', ['e']]);
//=> ['a', 'b', 'c', 'd', 'e']

.forEach

Loop over each item in an array and call the given function on every element.

Params

• array {Array}
• fn {Function}
• thisArg {Object}: Optionally pass a thisArg to be used as the context in which to call the function.
• returns {Array}

Example

forEach(['a', 'b', 'c'], function (ele) {
  return ele + ele;
});
//=> ['aa', 'bb', 'cc']

forEach(['a', 'b', 'c'], function (ele, i) {
  return i + ele;
});
//=> ['0a', '1b', '2c']

.isArray

Returns true if the given value is an array.

Params

• value {Array}: Value to test.

Example

isArray(1);
//=> 'false'

isArray([1]);
//=> 'true'

.last

Returns the last item, or last n items of an array.

Params

• array {Array}
• n {Number}: Number of items to return, starting with the last item.
• returns {Array}

Example

last(['a', 'b', 'c', 'd', 'e'], 2)
//=> ['d', 'e']

.map

Returns a new array with the results of calling the given function on every element in the array. This is a faster, node.js focused alternative to JavaScript's native array map.

Params

• array {Array}
• fn {Function}
• returns {Array}

Example

map(['a', 'b', 'c'], function (ele) {
  return ele + ele;
});
//=> ['aa', 'bb', 'cc']

map(['a', 'b', 'c'], function (ele, i) {
  return i + ele;
});
//=> ['0a', '1b', '2c']

.slice

Alternative to JavaScript's native array-slice method. Slices array from the start index up to but not including the end index.

Params

• array {Array}: the array to slice.
• start {Number}: Optionally define the starting index.
• end {Number}: Optionally define the ending index.

Example

var arr = ['a', 'b', 'd', 'e', 'f', 'g', 'h', 'i', 'j'];

slice(arr, 3, 6);
//=> ['e', 'f', 'g']

.union

Return an array free of duplicate values. Fastest ES5 implementation.

Params

• array {Array}: The array to uniquify
• returns {Array}: With all union values.

Example

union(['a', 'b', 'c', 'c']);
//=> ['a', 'b', 'c']

.unique

Return an array free of duplicate values. Fastest ES5 implementation.

Params

• array {Array}: The array to uniquify
• returns {Array}: With all unique values.

Example

unique(['a', 'b', 'c', 'c']);
//=> ['a', 'b', 'c']

.any

Returns true if value exists in the given string, array or object. See [any] for documentation.

Params

• value {*}
• target {*}
• options {Object}

.contains

Return true if collection contains value

Params

• collection {Array|Object}
• string {*}
• returns {Boolean}

.tryRead

Try to read the given filepath, fail silently and return null when a file doesn't exist. Slightly faster than using fs.existsSync.

Params

• fp {String}: Path of the file to read.
• returns {String|Null}: the utf8 contents string, or null if an error is thrown.

.tryReaddir

Try to read the given directory. Wraps fs.readdirSync() with a try/catch, so it fails silently instead of throwing when the directory doesn't exist.

Params

• dir {String}: Starting directory
• returns {Array}: Array of files.

.tryRequire

Try to require the given file, returning null if not successful instead of throwing an error.

Params

• fp {String}: File path of the file to require
• returns {*}: Returns the module function/object, or null if not found.

.identity

Returns the first argument passed to the function.

• returns {*}

.noop

A "no-operation" function. Returns undefined regardless of the arguments it receives.

• returns {undefined}

.partialRight

Partially applies arguments that will be appended to those provided to the returned function.

Params

• ctx {Object}: Optionally supply an invocation context for the returned function.
• fn {Function}: The function to which arguments should be partially applied.
• arguments __{...}*: List of arguments to be partially applied.
• returns {Function}: Returns a function with partially applied arguments.

Example

function fullname(first, last) {
  return first + ' ' + last;
}

var name = partialRight(fn, 'Woodward');
name('Brian');
//=> 'Brian Woodward'

.hasValues

Returns true if any value exists, false if empty. Works for booleans, functions, numbers, strings, nulls, objects and arrays.

Params

• object {Object}: The object to check for value
• value {*}: the value to look for
• returns {Boolean}: True if any values exists.

Example

hasValues('a');
//=> true

hasValues('');
//=> false

hasValues(1);
//=> true

hasValues({a: 'a'}});
//=> true

hasValues({}});
//=> false

hasValues(['a']);
//=> true

.isEmpty

Returns true if the given value is empty, false if any value exists. Works for booleans, functions, numbers, strings, nulls, objects and arrays.

Params

• object {Object}: The object to check for value
• value {*}: the value to look for
• returns {Boolean}: False if any values exists.

Example

isEmpty('a');
//=> false

isEmpty('');
//=> true

isEmpty(1);
//=> false

isEmpty({a: 'a'});
//=> false

isEmpty({});
//=> true

isEmpty(['a']);
//=> false

.isObject

Return true if the given value is an object with keys.

**Par