Skip to content package
utils v0.2.0 Fast, generic JavaScript/node.js utility functions.
node >=0.10.0 25 deps cjs open source
overview readme
license MIT
deps 25
unpacked Unknown
files Unknown
node >=0.10.0 $ npm install utils@0.2.0n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
array collection function lang language math object object string util utils
versions Latest published Sep 24, 2015
maintainers Registry package owners.
contents utils
Fast, generic JavaScript/node.js utility functions.
Install with npm
TOC
(Table of contents generated by verb )
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: {...}} copy 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' )._; copy Only get a specific collection
If you just want the string or object utils:
var string = require ( 'utils' ).string;
var object = require ( 'utils' ).object; copy
API Returns all of the items in an array after the specified index.
array {Array} : Collection
n {Number} : Starting index (number of items to exclude)
returns {Array} : Array exluding n items.
after ([ 'a' , 'b' , 'c' ], 1 )
//=> ['c'] copy Cast the give value to an array.
arrayify ( 'abc' )
//=> ['abc']
arrayify ([ 'abc' ])
//=> ['abc'] copy Returns all of the items in an array up to the specified number Opposite of <%= after() %.
array {Array}
n {Number}
returns {Array} : Array excluding items after the given number.
before ([ 'a' , 'b' , 'c' ], 2 )
//=> ['a', 'b'] copy Remove all falsey values from an array.
arr {Array}
returns {Array}
compact ([null, a, undefined, 0 , false , b, c, '' ]);
//=> [a, b, c] copy Return the difference between the first array and additional arrays.
a {Array}
b {Array}
returns {Array}
var a = [ 'a' , 'b' , 'c' , 'd' ];
var b = [ 'b' , 'c' ];
diff (a, b);
//=> ['a', 'd'] copy Loop over each item in an array and call the given function on every element.
array {Array}
fn {Function}
thisArg {Object} : Optionally pass a thisArg to be used as the context in which to call the function.
returns {Array}
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'] copy Returns the first item, or first n items of an array.
array {Array}
n {Number} : Number of items to return, starting at 0.
returns {Array}
first ([ 'a' , 'b' , 'c' , 'd' , 'e' ], 2 )
//=> ['a', 'b'] copy Recursively flatten an array or arrays. Uses the fastest implementation of array flatten for node.js
array {Array}
returns {Array} : Flattened array
flatten ([ 'a' , [ 'b' , [ 'c' ]], 'd' , [ 'e' ]]);
//=> ['a', 'b', 'c', 'd', 'e'] copy Loop over each item in an array and call the given function on every element.
array {Array}
fn {Function}
thisArg {Object} : Optionally pass a thisArg to be used as the context in which to call the function.
returns {Array}
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'] copy Returns true if the given value is an array.
value {Array} : Value to test.
isArray ( 1 );
//=> 'false'
isArray ([ 1 ]);
//=> 'true' copy Returns the last item, or last n items of an array.
array {Array}
n {Number} : Number of items to return, starting with the last item.
returns {Array}
last ([ 'a' , 'b' , 'c' , 'd' , 'e' ], 2 )
//=> ['d', 'e'] copy 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.
array {Array}
fn {Function}
returns {Array}
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'] copy Alternative to JavaScript's native array-slice method. Slices array from the start index up to but not including the end index.
array {Array} : the array to slice.
start {Number} : Optionally define the starting index.
end {Number} : Optionally define the ending index.
var arr = [ 'a' , 'b' , 'd' , 'e' , 'f' , 'g' , 'h' , 'i' , 'j' ];
slice (arr, 3 , 6 );
//=> ['e', 'f', 'g'] copy Return an array free of duplicate values. Fastest ES5 implementation.
array {Array} : The array to uniquify
returns {Array} : With all union values.
union ([ 'a' , 'b' , 'c' , 'c' ]);
//=> ['a', 'b', 'c'] copy Return an array free of duplicate values. Fastest ES5 implementation.
array {Array} : The array to uniquify
returns {Array} : With all unique values.
unique ([ 'a' , 'b' , 'c' , 'c' ]);
//=> ['a', 'b', 'c'] copy Returns true if value exists in the given string, array
or object. See [any] for documentation.
value {*}
target {*}
options {Object}
Return true if collection contains value
collection {Array|Object}
string {*}
returns {Boolean}
Try to read the given filepath, fail silently and return null
when a file doesn't exist. Slightly faster than using fs.existsSync.
fp {String} : Path of the file to read.
returns {String|Null} : the utf8 contents string, or null if an error is thrown.
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.
dir {String} : Starting directory
returns {Array} : Array of files.
Try to require the given file, returning null if not successful
instead of throwing an error.
fp {String} : File path of the file to require
returns {*} : Returns the module function/object, or null if not found.
Returns the first argument passed to the function.
A "no-operation" function. Returns undefined regardless
of the arguments it receives.
Partially applies arguments that will be appended to those provided to the returned function.
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.
function fullname (first, last) {
return first + ' ' + last;
}
var name = partialRight (fn, 'Woodward' );
name ( 'Brian' );
//=> 'Brian Woodward' copy Returns true if any value exists, false if empty. Works for booleans, functions, numbers, strings, nulls, objects and arrays.
object {Object} : The object to check for value
value {*} : the value to look for
returns {Boolean} : True if any values exists.
hasValues ( 'a' );
//=> true
hasValues ( '' );
//=> false
hasValues ( 1 );
//=> true
hasValues ({a: 'a' }});
//=> true
hasValues ({}});
//=> false
hasValues ([ 'a' ]);
//=> true copy Returns true if the given value is empty, false if any value exists. Works for booleans, functions, numbers, strings, nulls, objects and arrays.
object {Object} : The object to check for value
value {*} : the value to look for
returns {Boolean} : False if any values exists.
isEmpty ( 'a' );
//=> false
isEmpty ( '' );
//=> true
isEmpty ( 1 );
//=> false
isEmpty ({a: 'a' });
//=> false
isEmpty ({});
//=> true
isEmpty ([ 'a' ]);
//=> false copy Return true if the given value is an object with keys.
value {Object} : The value to check.
returns {Boolean}
isObject ([ 'a' , 'b' , 'c' ])
//=> 'false'
isObject ({a: 'b' })
//=> 'true' copy Return true if the given value is an object with keys.
value {Object} : The value to check.
returns {Boolean}
isPlainObject (Object. create ({}));
//=> true
isPlainObject (Object. create ( Object .prototype));
//=> true
isPlainObject ({foo: 'bar' });
//=> true
isPlainObject ({});
//=> true copy Returns the sum of all numbers in the given array.
array {Array} : Array of numbers to add up.
returns {Number}
sum ([ 1 , 2 , 3 , 4 , 5 ])
//=> '15' copy Extend object with properties of other objects
object {Object} : The target object. Pass an empty object to shallow clone.
objects {Object}
returns {Object}
Extend o with properties of other objects.
o {Object} : The target object. Pass an empty object to shallow clone.
objects {Object}
returns {Object}
Returns a copy of the given obj filtered to have only enumerable properties that have function values.
obj {Object}
returns {Object}
functions ({a: 'b' , c : function () {}});
//=> {c: function() {}} copy Return true if key is an own, enumerable property of the given obj.
key {String}
obj {Object} : Optionally pass an object to check.
returns {Boolean}
Return an array of keys for the given obj. Uses Object.keys
when available, otherwise falls back on forOwn.
obj {Object}
returns {Array} : Array of keys.
Returns new object where each value is the result of
calling the a callback function.
{Object} : obj The object to iterate over
cb {Function} : Callback function
{Object} : thisArg Invocation context of cb
returns {Object}
Recursively combine the properties of o with the
properties of other objects.
o {Object} : The target object. Pass an empty object to shallow clone.
objects {Object}
returns {Object}
Returns a list of all enumerable properties of obj that have function
values
obj {Object}
returns {Array}
Reduces an object to a value that is the accumulated result of running each property in the object through a callback.
obj {Object} : The object to iterate over.
iterator {Function} : Iterator function
initial {Object} : Initial value.
thisArg {Object} : The this binding of the iterator function.
returns {Object}
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'}; copy camelCase the characters in string.
string {String} : The string to camelcase.
returns {String}
camelcase ( "foo bar baz" );
//=> 'fooBarBaz' copy Center align the characters in a string using non-breaking spaces.
str {String} : The string to reverse.
returns {String} : Centered string.
Like trim, but removes both extraneous whitespace and non-word characters from the beginning and end of a string.
string {String} : The string to chop.
returns {String}
chop ( "_ABC_" );
//=> 'ABC'
chop ( "-ABC-" );
//=> 'ABC'
chop ( " ABC " );
//=> 'ABC' copy Count the number of occurrances of a substring within a string.
string {String}
substring {String}
returns {Number} : The occurances of substring in string
count ( "abcabcabc" , "a" );
//=> '3' copy dash-case the characters in string. This is similar to [slugify], but [slugify] makes the string compatible to be used as a URL slug.
string {String}
returns {String}
dashcase ( "a b.c d_e" );
//=> 'a-b-c-d-e' copy dot.case the characters in string.
string {String}
returns {String}
dotcase ( "a-b-c d_e" );
//=> 'a.b.c.d.e' copy Truncate a string to the specified length, and append it with an elipsis, ….
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.
ellipsis ( "<span>foo bar baz</span>" , 7 );
//=> 'foo bar…' copy Replace spaces in a string with hyphens. This
string {String}
returns {String}
hyphenate ( "a b c" );
//=> 'a-b-c' copy Returns true if the value is a string.
val {String}
returns {Boolean} : True if the value is a string.
isString ( 'abc' );
//=> 'true'
isString (null);
//=> 'false' copy PascalCase the characters in string.
string {String}
returns {String}
pascalcase ( "foo bar baz" );
//=> 'FooBarBaz' copy path/case the characters in string.
string {String}
returns {String}
pathcase ( "a-b-c d_e" );
//=> 'a/b/c/d/e' copy Replace occurrences of a with b.
str {String}
a {String|RegExp} : Can be a string or regexp.
b {String}
returns {String}
replace ( "abcabc" , /a/ , "z" );
//=> 'zbczbc' copy Reverse the characters in a string.
str {String} : The string to reverse.
returns {String}
reverse ( "abc" );
//=> 'cba' copy Right align the characters in a string using non-breaking spaces.
str {String} : The string to reverse.
returns {String} : Right-aligned string.
Sentence-case the characters in string.
string {String}
returns {String}
sentencecase ( "foo bar baz." );
//=> 'Foo bar baz.' copy snake_case the characters in string.
string {String}
returns {String}
snakecase ( "a-b-c d_e" );
//=> 'a_b_c_d_e' copy Truncate a string by removing all HTML tags and limiting the result to the specified length.
str {String}
length {Number} : The desired length of the returned string.
returns {String} : The truncated string.
truncate ( "<span>foo bar baz</span>" , 7 );
//=> 'foo bar' copy Wrap words to a specified width using [word-wrap].
string {String} : The string with words to wrap.
object {Options} : Options to pass to [word-wrap]
returns {String} : Formatted string.
wordwrap ( "a b c d e f" , {width: 5 , newline: '<br> ' });
//=> ' a b c <br> d e f' copy
Code coverage -----------------------|----------|----------|----------|----------|----------------|
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 | |
-----------------------|----------|----------|----------|----------|----------------| copy
Running tests Install dev dependencies:
$ npm i -d && npm test copy
Contributing
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 verb is 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 copy
About
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.
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.
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 the start index up to, but not including, the end… 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
License Copyright © 2015 Jon Schlinkert
Released under the MIT license.
This file was generated by verb-cli on September 23, 2015.
dependencies 25 direct dependencies.