Awesome
utils
Fast, generic JavaScript/node.js utility functions.
Install with npm
$ npm i utils --save
TOC
<!-- toc -->(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}: Collectionn
{Number}: Starting index (number of items to exclude)returns
{Array}: Array exludingn
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 athisArg
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 at0
.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 athisArg
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 uniquifyreturns
{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 uniquifyreturns
{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}: theutf8
contents string, ornull
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 directoryreturns
{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 requirereturns
{*}: Returns the module function/object, ornull
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 forvalue
value
{*}: the value to look forreturns
{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 forvalue
value
{*}: the value to look forreturns
{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.
Params
value
{Object}: The value to check.returns
{Boolean}
Example
isObject(['a', 'b', 'c'])
//=> 'false'
isObject({a: 'b'})
//=> 'true'
.isPlainObject
Return true if the given value
is an object with keys.
Params
value
{Object}: The value to check.returns
{Boolean}
Example
isPlainObject(Object.create({}));
//=> true
isPlainObject(Object.create(Object.prototype));
//=> true
isPlainObject({foo: 'bar'});
//=> true
isPlainObject({});
//=> true
.sum
Returns the sum of all numbers in the given array.
Params
array
{Array}: Array of numbers to add up.returns
{Number}
Example
sum([1, 2, 3, 4, 5])
//=> '15'
.defaults
Extend object
with properties of other objects
Params
object
{Object}: The target object. Pass an empty object to shallow clone.objects
{Object}returns
{Object}
.extend
Extend o
with properties of other objects
.
Params
o
{Object}: The target object. Pass an empty object to shallow clone.objects
{Object}returns
{Object}
.functions
Returns a copy of the given obj
filtered to have only enumerable properties that have function values.
Params
obj
{Object}returns
{Object}
Example
functions({a: 'b', c: function() {}});
//=> {c: function() {}}
.hasOwn
Return true if key
is an own, enumerable property of the given obj
.
Params
key
{String}obj
{Object}: Optionally pass an object to check.returns
{Boolean}
Example
hasOwn(obj, key);
.keys
Return an array of keys for the given obj
. Uses Object.keys
when available, otherwise falls back on forOwn
.
Params
obj
{Object}returns
{Array}: Array of keys.
mapValues
Returns new object where each value is the result of
calling the a callback
function.
Params
- {Object}: obj The object to iterate over
cb
{Function}: Callback function- {Object}: thisArg Invocation context of
cb
returns
{Object}
.merge
Recursively combine the properties of o
with the
properties of other objects
.
Params
o
{Object}: The target object. Pass an empty object to shallow clone.objects
{Object}returns
{Object}
.methods
Returns a list of all enumerable properties of obj
that have function
values
Params
obj
{Object}returns
{Array}
.reduce
Reduces an object to a value that is the accumulated result of running each property in the object through a callback.
Params
obj
{Object}: The object to iterate over.iterator
{Function}: Iterator functioninitial
{Object}: Initial value.thisArg
{Object}: Thethis
binding of the iterator function.returns
{Object}
Example
var a = {a: 'foo', b: 'bar', c: 'baz'};
reduce(a, function (acc, value, key, obj) {
// `acc`- the initial value (or value from the previous callback call),
// `value`- the of the current property,
// `key`- the of the current property, and
// `obj` - original object
acc[key] = value.toUpperCase();
return acc;
}, {});
//=> {a: 'FOO', b: 'BAR', c: 'BAZ'};
.camelcase
camelCase the characters in string
.
Params
string
{String}: The string to camelcase.returns
{String}
Example
camelcase("foo bar baz");
//=> 'fooBarBaz'
.centerAlign
Center align the characters in a string using non-breaking spaces.
Params
str
{String}: The string to reverse.returns
{String}: Centered string.
Example
centerAlign("abc");
.chop
Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string.
Params
string
{String}: The string to chop.returns
{String}
Example
chop("_ABC_");
//=> 'ABC'
chop("-ABC-");
//=> 'ABC'
chop(" ABC ");
//=> 'ABC'
.count
Count the number of occurrances of a substring within a string.
Params
string
{String}substring
{String}returns
{Number}: The occurances ofsubstring
instring
Example
count("abcabcabc", "a");
//=> '3'
.dashcase
dash-case the characters in string
. This is similar to [slugify], but [slugify] makes the string compatible to be used as a URL slug.
Params
string
{String}returns
{String}
Example
dashcase("a b.c d_e");
//=> 'a-b-c-d-e'
.dotcase
dot.case the characters in string
.
Params
string
{String}returns
{String}
Example
dotcase("a-b-c d_e");
//=> 'a.b.c.d.e'
.ellipsis
Truncate a string to the specified length
, and append it with an elipsis, …
.
Params
str
{String}length
{Number}: The desired length of the returned string.ch
{String}: Optionally pass custom characters to append. Default is…
.returns
{String}: The truncated string.
Example
ellipsis("<span>foo bar baz</span>", 7);
//=> 'foo bar…'
.hyphenate
Replace spaces in a string with hyphens. This
Params
string
{String}returns
{String}
Example
hyphenate("a b c");
//=> 'a-b-c'
.isString
Returns true if the value is a string.
Params
val
{String}returns
{Boolean}: True if the value is a string.
Example
isString('abc');
//=> 'true'
isString(null);
//=> 'false'
.pascalcase
PascalCase the characters in string
.
Params
string
{String}returns
{String}
Example
pascalcase("foo bar baz");
//=> 'FooBarBaz'
.pathcase
path/case the characters in string
.
Params
string
{String}returns
{String}
Example
pathcase("a-b-c d_e");
//=> 'a/b/c/d/e'
.replace
Replace occurrences of a
with b
.
Params
str
{String}a
{String|RegExp}: Can be a string or regexp.b
{String}returns
{String}
Example
replace("abcabc", /a/, "z");
//=> 'zbczbc'
.reverse
Reverse the characters in a string.
Params
str
{String}: The string to reverse.returns
{String}
Example
reverse("abc");
//=> 'cba'
.rightAlign
Right align the characters in a string using non-breaking spaces.
Params
str
{String}: The string to reverse.returns
{String}: Right-aligned string.
Example
rightAlign(str);
.sentencecase
Sentence-case the characters in string
.
Params
string
{String}returns
{String}
Example
sentencecase("foo bar baz.");
//=> 'Foo bar baz.'
.snakecase
snake_case the characters in string
.
Params
string
{String}returns
{String}
Example
snakecase("a-b-c d_e");
//=> 'a_b_c_d_e'
.truncate
Truncate a string by removing all HTML tags and limiting the result to the specified length
.
Params
str
{String}length
{Number}: The desired length of the returned string.returns
{String}: The truncated string.
Example
truncate("<span>foo bar baz</span>", 7);
//=> 'foo bar'
.wordwrap
Wrap words to a specified width using [word-wrap].
Params
string
{String}: The string with words to wrap.object
{Options}: Options to pass to [word-wrap]returns
{String}: Formatted string.
Example
wordwrap("a b c d e f", {width: 5, newline: '<br> '});
//=> ' a b c <br> d e f'
Code coverage
Please help improve code coverage by adding unit tests.
-----------------------|----------|----------|----------|----------|----------------|
File | % Stmts | % Branch | % Funcs | % Lines |Uncovered Lines |
-----------------------|----------|----------|----------|----------|----------------|
utils/ | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
utils/lib/ | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
utils/lib/array/ | 91.75 | 83.33 | 100 | 92.55 | |
after.js | 100 | 75 | 100 | 100 | |
arrayify.js | 100 | 100 | 100 | 100 | |
before.js | 100 | 75 | 100 | 100 | |
compact.js | 100 | 100 | 100 | 100 | |
difference.js | 100 | 100 | 100 | 100 | |
each.js | 100 | 100 | 100 | 100 | |
first.js | 88.89 | 83.33 | 100 | 88.24 | 27,46 |
flatten.js | 100 | 100 | 100 | 100 | |
forEach.js | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
indexOf.js | 76.92 | 70 | 100 | 83.33 | 23,40 |
isArray.js | 100 | 100 | 100 | 100 | |
last.js | 88.89 | 83.33 | 100 | 88.24 | 27,46 |
map.js | 100 | 100 | 100 | 100 | |
slice.js | 100 | 100 | 100 | 100 | |
sort.js | 90.91 | 87.5 | 100 | 90.91 | 27 |
union.js | 100 | 100 | 100 | 100 | |
unique.js | 100 | 100 | 100 | 100 | |
utils/lib/collection/ | 55.56 | 0 | 0 | 55.56 | |
any.js | 100 | 100 | 100 | 100 | |
contains.js | 42.86 | 0 | 0 | 42.86 | 18,19,21,22 |
index.js | 100 | 100 | 100 | 100 | |
utils/lib/fs/ | 68.75 | 100 | 66.67 | 68.75 | |
index.js | 100 | 100 | 100 | 100 | |
tryRead.js | 40 | 100 | 0 | 40 | 16,17,19 |
tryReaddir.js | 80 | 100 | 100 | 80 | 20 |
tryRequire.js | 80 | 100 | 100 | 80 | 19 |
utils/lib/function/ | 36.36 | 0 | 0 | 36.36 | |
identity.js | 50 | 100 | 0 | 50 | 12 |
index.js | 100 | 100 | 100 | 100 | |
noop.js | 50 | 100 | 0 | 50 | 13 |
partialRight.js | 16.67 | 0 | 0 | 16.67 | 26,27,28,29,30 |
utils/lib/lang/ | 100 | 100 | 100 | 100 | |
hasValues.js | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
isEmpty.js | 100 | 100 | 100 | 100 | |
isObject.js | 100 | 100 | 100 | 100 | |
isPlainObject.js | 100 | 100 | 100 | 100 | |
typeOf.js | 100 | 100 | 100 | 100 | |
utils/lib/math/ | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
sum.js | 100 | 100 | 100 | 100 | |
utils/lib/object/ | 62.77 | 46.15 | 17.65 | 61.96 | |
defaults.js | 100 | 100 | 100 | 100 | |
extend.js | 100 | 83.33 | 100 | 100 | |
filter.js | 100 | 100 | 100 | 100 | |
forIn.js | 100 | 100 | 100 | 100 | |
forOwn.js | 100 | 100 | 100 | 100 | |
functions.js | 28.57 | 0 | 0 | 28.57 | 21,23,24,25,29 |
hasOwn.js | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
keys.js | 33.33 | 50 | 0 | 33.33 | 16,17,18,20 |
mapValues.js | 37.5 | 100 | 0 | 37.5 | 18,19,21,22,25 |
merge.js | 100 | 75 | 100 | 100 | |
methods.js | 28.57 | 0 | 0 | 28.57 | 16,18,19,20,24 |
omit.js | 100 | 100 | 100 | 100 | |
pick.js | 100 | 100 | 100 | 100 | |
pluck.js | 75 | 100 | 0 | 75 | 17 |
prop.js | 33.33 | 100 | 0 | 33.33 | 4,5 |
reduce.js | 100 | 100 | 100 | 100 | |
result.js | 25 | 0 | 0 | 25 | 6,7,8,10,11,13 |
some.js | 30 | 0 | 0 | 30 |... 11,12,13,16 |
utils/lib/string/ | 99.28 | 96.77 | 96 | 99.1 | |
camelcase.js | 100 | 100 | 100 | 100 | |
centerAlign.js | 100 | 100 | 100 | 100 | |
chop.js | 100 | 100 | 100 | 100 | |
count.js | 100 | 100 | 100 | 100 | |
dashcase.js | 100 | 100 | 100 | 100 | |
dotcase.js | 100 | 100 | 100 | 100 | |
ellipsis.js | 100 | 100 | 100 | 100 | |
hyphenate.js | 100 | 100 | 100 | 100 | |
index.js | 100 | 100 | 100 | 100 | |
isString.js | 100 | 100 | 100 | 100 | |
pascalcase.js | 100 | 100 | 100 | 100 | |
pathcase.js | 100 | 100 | 100 | 100 | |
replace.js | 100 | 100 | 100 | 100 | |
reverse.js | 100 | 100 | 100 | 100 | |
rightAlign.js | 100 | 100 | 100 | 100 | |
sentencecase.js | 100 | 100 | 100 | 100 | |
slugify.js | 100 | 100 | 100 | 100 | |
snakecase.js | 100 | 100 | 100 | 100 | |
toString.js | 50 | 0 | 0 | 50 | 10 |
truncate.js | 100 | 100 | 100 | 100 | |
wordwrap.js | 100 | 100 | 100 | 100 | |
-----------------------|----------|----------|----------|----------|----------------|
All files | 84.54 | 80.52 | 67.16 | 83.43 | |
-----------------------|----------|----------|----------|----------|----------------|
Running tests
Install dev dependencies:
$ npm i -d && npm test
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Adding utils
If you want to do a PR to add a util, please read the following first:
- follow the same coding style as the rest of the library, same with code comments
- add sufficient unit tests
- Install dev dependencies and run verb
- Look over the README to make sure that verb rendered out the docs with your method and code comments.
Adding external modules as dependencies
- External modules will only be considered if they meet the same quality and coding standards as the rest of the library. At minimum this includes documentation, code comments, and unit tests. Benchmarks are also strongly preferred.
Updating the docs
Do not edit the readme manually since verbis used to generate documentation.
- API docs: If you see an error in the API documentation, just update the code comments for that method, then run verb.
- Everything else, please look over the .verb.md template to see where the error is, then run verb.
Running verb
Install dev dependencies, then run verb:
$ npm install -d && verb
About
Why another utils lib?
- I'm a node.js developer. I want fast, light, dependable utility functions for node.js projects.
- Do you really need bloated, everything-but-the-kitchen-sink functions that are guaranteed to work with IE 4, for your Yeoman generator or gulp plugin!? Nonsense.
- The benchmarks that accompany many of the functions in the library show that in some cases, the penalty for using such "kitchen-sink" code is a 2,000-5,000% reduction in speed. Sometimes greater.
Project goals
- Fastest implementation of each method, without too much compromise. Covering uncommon cases is fine, but don't go overboard.
- Clean well-documented, commented code.
- When it makes sense, external libraries are used and exposed instead of writing new code.
- Focus on node.js usage and projects that are likely to use a number of these utils in one project. If you only need one or two of these in a small project, don't use this. Use small modules that do only one thing.
Related projects
This project depends on these great libraries. If you don't need a full utility belt for your project, any of these can be used by themselves:
- any: Returns
true
if a value exists in the given string, array or object. | homepage - arr-diff: Returns an array with only the unique values from the first array, by excluding all… more | homepage
- arr-flatten: Recursively flatten an array or arrays. This is the fastest implementation of array flatten. | homepage
- arr-map: Faster, node.js focused alternative to JavaScript's native array map. | homepage
- arr-union: Combines a list of arrays, returning a single array with unique values, using strict equality… more | homepage
- array-each: Loop over each item in an array and call the given function on every element. | homepage
- array-slice: Array-slice method. Slices
array
from thestart
index up to, but not including, theend
… more | homepage - array-unique: Return an array free of duplicate values. Fastest ES5 implementation. | homepage
- center-align: Center-align the text in a string. | homepage
- export-dirs: Export directories and their files as node.js modules. | homepage
- export-files: node.js utility for exporting a directory of files as modules. | homepage
- for-in: Iterate over the own and inherited enumerable properties of an objecte, and return an object… more | homepage
- for-own: Iterate over the own enumerable properties of an object, and return an object with properties… more | homepage
- has-values: Returns true if any values exist, false if empty. Works for booleans, functions, numbers, strings,… more | homepage
- is-number: Returns true if the value is a number. comprehensive tests. | homepage
- is-plain-object: Returns true if an object was created by the
Object
constructor. | homepage - kind-of: Get the native type of a value. | homepage
- make-iterator: Convert an argument into a valid iterator. Based on the
.makeIterator()
implementation in mout https://github.com/mout/mout. | homepage - object.defaults: Like
extend
but only copies missing properties/values to the target object. | homepage - object.filter: Create a new object filtered to have only properties for which the callback returns true. | homepage
- object.omit: Return a copy of an object excluding the given key, or array of keys. Also… more | homepage
- object.pick: Returns a filtered copy of an object with only the specified keys, like
pick
from… more | homepage - object.reduce: Reduces an object to a value that is the accumulated result of running each property… more | homepage
- right-align: Right-align the text in a string. | homepage
- striptags: PHP strip_tags in Node.js | homepage
- word-wrap: Wrap words to a specified length. | homepage
Author
Jon Schlinkert
License
Copyright © 2015 Jon Schlinkert Released under the MIT license.
This file was generated by verb-cli on September 23, 2015.