proto-lib v1.0.0

ProtoLib

The namespace friendly prototype library.

There's nothing wrong with modifying built-in prototypes, as long as you do it right.

Some of the magic from Javascript comes from the ability to modify built-in types—but it's also taboo.
It can lead to dangerous library collisions.

That's where ProtoLib comes to the rescue. It's is a fast, Node.js and browser friendly JavaScript library that "tucks" utility methods inside a single, customizable property added to Object.prototype.

Static utility methods are cumbersome and don't lend themselves to easy reading. Basically, I grew tired of using static libraries and re-writing utility methods over various projects... enter ProtoLib.

Currently tested and working in Node.js, Chrome, Firefox, Safari, IE 10 & 11.

Features

• Over 100 library methods
  • See the list below...
  • Methods are attached to Object.prototype, which means terse, readable code.
  • Iterating functions like each, every, and any work on objects, arrays, strings, numbers, and functions.
• Collision Free
  • You define the property attached to Object.prototype.
  • The default is _ (underscore), but this can be set to any string.
  • No ES6 for browser compatibility.
• Extensible
  • ProtoLib allows you to extend the library for any prototype.
  • Extend both custom objects and primitives.
• Switch the library on and off, on the fly

Contents

1. Install
2. Getting Started
   • Node.js
   • Browser Use
3. Available Methods
   • Objects
   • Strings
   • Arrays
   • Functions
   • Numbers
   • Date Objects
4. Extending ProtoLib
   • Adding Methods
   • Deleting Methods
5. Advanced
   • Instance Methods
   • Static Methods

Install

$ npm install proto-lib --save

Getting Started

Node.js

// Require the protolib library.
var ProtoLib = require('proto-lib');

// Get a new instance, specifying the accessor property (i.e. "handle").
// This will default to '_' if unspecified.
var lib = ProtoLib.get('_');

// That's it!
// All objects now have access to the defined library methods from the '_' property.
var str = 'hello world!';

str._.titleCase() // -> 'Hello World!'
str._.ucFirst()   // -> 'Hello world!'
str._.reverse()   // -> '!dlrow olleh'

// Chaning with ProtoLib:
str._.titleCase()._.reverse()) // ->'!dlroW olleH'

Oh Noes! I'm using a library that uses '_', what can I do?

var ProtoLib = require('proto-lib');

// Just get a new ProtoLib instance with a different handle.
var lib = ProtoLib.get('lib'),
    obj = { foo: 'hello', bar: 'world' };

obj.lib.invert()        // -> { hello: 'foo', world: 'bar' }
   .lib.histogram()     // -> { 'foo': 1, 'bar': 1 }
   .lib.size()          // -> 2

Any handle attached to Object.prototype by ProtoLib is both configurable and writable.

Do not use new with ProtoLib

Use ProtoLib's static function: ProtoLib.get.
It should be used to prevent the instantiation new ProtoLib instances across files. By using ProtoLib.get you can retrieve the same instance of the library across namespaces.

// Bad, don't do it.
var lib = new ProtoLib('_');

// Correct way to instantiate ProtoLib...
var lib = ProtoLib.get('_');

// You can create multiple instances using get...
// Not sure why you'd want to, however.
var lib  = ProtoLib.get('a');
var lib2 = ProtoLib.get('b');

Example: Cross-file use:
foo.js

var ProtoLib = require('proto-lib'),
    lib      = ProtoLib.get('_');

// Library now available to objects...
'string'._.reverse();

bar.js

// If called after foo.js, bar.js will still have the library methods attached.
// This still works...
'string'._.reverse();

// However, just to be safe you should include the library at the top of each file.
// If you don't need a reference to the class itself, just call:
require('proto-lib').get('_');

Browser Use

Use /dist/protolib.min.js... /index.js is for Node.js only.

my-html-file.hmtl

<script type="text/javascript" src="path/to/protolib.min.js"></script>
<script type="text/javascript" src="my-script.js"></script>

my-script.js

var lib = window.ProtoLib.get('_');
var arr = [1, 2, 3, 4];

arr._.rotate('left', 2)                 // -> [3, 4, 1, 2]
arr._.intersect([1, 5, 6], [9, 3, 4])   // -> [3, 4, 1]
arr._.without(4, 1)                     // -> [3]

// Chaining some methods together:
arr = [1, 2, 'hello', 'world', { foo: 'bar' }];

arr._.only('string')                   // -> ['hello', 'world']
   ._.each(function (val, key) {       // -> ['dlrow', 'olleh']
        this[key] = val._.reverse();
   });

Available Methods

Note: npm truncates this file... view the full read me on GitHub

Objects

Methods available to all Objects (objects, arrays, strings, functions, etc.).

Strings

Methods available to all String objects.

Arrays

Methods available to all Array objects and their inheritors.

Functions

Methods available to all Function objects and their inheritors.

Numbers

Methods available to all Number objects and their inheritors.

Dates

Methods available to all Date objects and their inheritors.

The examples below assume you have set 'lib' to a new instance of ProtoLib and that you're using the default handler ('_'), that is...

var ProtoLib = require('proto-lib'),
    lib = ProtoLib.get('_');

// Or in the browser...
var lib = window.ProtoLib.get('_');

Objects

histogram

Returns an object containing a frequencies of values.
For objects (arrays and pure objects), it will count the frequency of values. For strings, it will count character frequencies. Numbers and functions will be converted using toString.

[1, 2, 3, 4, 1, 1, 1, 5, 5]._.histogram()
// Returns { 1: 4, 2: 1, 3: 1, 4: 1, 5: 2 }

'racecar'._.histogram()
// Returns { r: 2, a: 2, c: 2, e: 1 }

'AAAAaaaa'._.histogram()
// Returns { A: 4, a: 4 }

(1234).histogram()
// Returns { 1: 1, 2: 1, 3: 1, 4: 1 }

(-1234).histogram()
// Returns { '-': 1, 1: 1, 2: 1, 3: 1, 4: 1 }

{ foo: 'bar', hello: 'world', number: 5, five: 5 }._.histogram()
// Returns { bar: 1, world: 1, 5: 2 }

/* Static Use */

lib.object.histogram([1, 2, 3], 'a string', function () {});
// Returns { 1: 1, 2: 1, 3: 1, a: 1, ' ': 1, s: 1, t: 1, r: 1, i: 1, n: 1, g: 1, 'function': 1 }

lib.object.histogram([1, 2, 3, [3, 4, 5], ['a', 'b', 'c']]);
// Returns { 1: 1, 2: 1, 3: 1, array: 2 }

copy

Returns a shallow copy of an object.
For non-objects, the provided value is simply returned. For objects, a shallow copy is made.

[1, 2, 3, 'a', 'b', 'c']._.copy();
// Returns a copy of the above array.

{ foo: 'bar' }._.copy();
// Returns a copy of the above object.

'hello world'._.copy();
// Returns 'hello world'

/* Static Use */
lib.object.copy(something);

occurrencesOf

Counts the number of occurrences of what.

[1, 1, 1, 1, 3]._.occurrencesOf(1);
// Returns 4

[1, 1, 1, 1, 3]._.occurrencesOf('1');
// Returns 0

{ foo: 'bar', hello: 'world' }._.occurrencesOf('bar');
// Returns 1

'racecar'._.occurrencesOf('r');
// Returns 2

'the rain falls mainly in the plain in spain'._.occurrencesOf('ain');
// Returns 4


/* Static Use */
lib.object.occurrencesOf(haystack, needle);

keys

Returns the object's key set.
Note: For numbers and functions, this will always return an empty array.

[1, 1, 1, 1, 3]._.keys();
// Returns ['0', '1', '2', '3', '4']

{ foo: 'bar', baz: 'biz' }._.keys();
// Returns ['foo', 'bar']

'a string'._.keys();
// Returns ['0', '1', '2', '3', '4', '5', '6', '7']

(1234)._.keys();
// Returns []

(function () {})._.keys();
// Returns []

/* Static Use */
lib.object.keys(item);

size

Returns the "size" of an object (length).
For strings, it will return the string's length, for numbers: the number of digits, for objects: Object.keys(...).length, for arrays: Array.length, and for functions: 1.

[1, 1, 1, 1, 3]._.size();
// Returns 5

{ foo: 'bar', baz: 'biz' }._.size();
// Returns 2

'a string'._.size();
// Returns 8

(1234)._.size();
// Returns 4

(-1234)._.size();
// Returns 5

(function () {})._.size();
// Returns 1

/* Static Use */
lib.object.size(item);

isNumeric

Determines if the object "is numeric".
Returns true if the object can be parsed as a number and is finite, false otherwise.
If used in the static context, it will return true if and only if all arguments are numeric.

[]._.isNumeric();               // false
{}._.isNumeric();               // false

'string'._.isNumeric();         // false
'1234'._.isNumeric();           // true
'-1234'._.isNumeric();          // true
'1e7'._.isNumeric();            // true
'0xFF'._.isNumeric();           // true

(1234)._.isNumeric();           // true
(-1234)._.isNumeric();          // true
(1e7)._.isNumeric();            // true
(0x64)._.isNumeric();           // true

(function () {})._.isNumeric(); // false

/* Static Use */
lib.object.isNumeric(a, b, c...);

getNumeric

Get's an object's number equivalent.
Returns the number represented by the given value, or NaN.
If used in the static context, it will return an array with the results for each argument if more than one argument is supplied.

[]._.getNumeric();               // NaN
{}._.getNumeric();               // NaN

'string'._.getNumeric();         // NaN
'1234'._.getNumeric();           // 1234
'-1234'._.getNumeric();          // -1234
'-1234.56'._.getNumeric();       // -1234.56
'1e7'._.getNumeric();            // 10000000
'0xFF'._.getNumeric();           // 255

(1234)._.getNumeric();           // 1234
(1234.56)._.getNumeric();        // 1234.56
(-1234)._.getNumeric();          // -1234
(1e7)._.getNumeric();            // 10000000
(0x64)._.getNumeric();           // 100

(function () {})._.isNumeric();  // NaN

/* Static Use */
lib.object.getNumeric('1', '0xFF', 'hello world', 7); // Returns [1, 255, NaN, 7]
lib.object.getNumeric('90'); // Returns 90

isEmpty

Determines if the given objects are "empty".
That is, if obj !== null && obj !== undefined && obj !== ''. So zero (0) isn't empty.
For collections, it will assert that the object has a length of more than zero.

If used in the static context, it will return true if and only if all arguments are empty.

[]._.isEmpty()                // true
{}._.isEmpty()                // true
[1]._.isEmpty()               // false
{ foo: 1, bar: 2}._.isEmpty() // false
(0)._.isEmpty()               // false
''._.isEmpty()                // true
'hello world'._.isEmpty()     // false
function () {}._.isEmpty()    // false

/* Static Use */
lib.object.isEmpty(0, '', 1, []);    // false
lib.object.isEmpty([], {}, []);      // true
lib.object.isEmpty(null, undefined); // true

isArray

Determines if the given objects are all arrays.
If used in the static context, it will return true if and only if all arguments are arrays.

[]._.isArray()                // true
{}._.isArray()                // false
[1]._.isArray()               // true
{ foo: 1, bar: 2}._.isArray() // false
'hello world'._.isArray()     // false
function () {}._.isArray()    // false

/* Static Use */
lib.object.isArray(0, [], [1, 2, 3]);               // false
lib.object.isArray([], [1, 2, 3], ['a', 'b', 'c']); // true
lib.object.isArray(null, []);                       // false

isPureObject

Determines if the given objects are all objects, but not arrays.
If used in the static context, it will return true if and only if all arguments are "pure objects".

[]._.isPureObject()                // false
{}._.isPureObject()                // true
[1]._.isPureObject()               // false
{ foo: 1, bar: 2}._.isPureObject() // true
'hello world'._.isPureObject()     // false
function () {}._.isPureObject()    // false

/* Static Use */
lib.object.isPureObject({}, {}, {}); // true
lib.object.isPureObject([], {});     // false
lib.object.isPureObject(null, {});   // false

isString

Determines if the given objects are all strings.
If used in the static context, it will return true if and only if all arguments are strings.

isBoolean

Determines if the given objects are all booleans. If used in the static context, it will return true if and only if all arguments are booleans.

isFunction

Determines if the given objects are all functions.
If used in the static context, it will return true if and only if all arguments are functions.

isNull

Determines if the given objects are all null.
If used in the static context, it will return true if and only if all arguments are null.

isUndefined

Determines if the given objects are all undefined.
If used in the static context, it will return true if and only if all arguments are undefined.

isArguments

Determines if the given objects are all arguments objects.
If used in the static context, it will return true if and only if all arguments are Arguments instances.

[]._.isArguments()                // false
{}._.isArguments()                // false
[1]._.isArguments()               // false
{ foo: 1, bar: 2}._.isArguments() // false
'hello world'._.isArguments()     // false
function () {}._.isArguments()    // false

(function () {
    arguments._.isArguments()     // true
}());

/* Static Use */

(function () {
    lib.object.isArguments(arguments); // true
}());

lib.object.isArguments([]);            // false

toNumber

Alias for getNumeric

toInt

Get's the object's integer equivalent.
Returns the integer value represented by the given value(s), or NaN. If used in the static context, it will return an array with the results for each argument if more than one argument is supplied.

[]._.toInt();               // NaN
{}._.toInt();               // NaN

'string'._.toInt();         // NaN
'1234.12'._.toInt();        // 1234
'-1234.000112'._.toInt();   // -1234
'1e7'._.toInt();            // 10000000
'0xFF'._.toInt();           // 255

(1234.789)._.toInt();       // 1234
(-1234.00012)._.toInt();    // -1234
(1e7)._.toInt();            // 10000000
(0x64)._.toInt();           // 100

(function () {})._.toInt();  // NaN

/* Static Use */
lib.object.toInt('1', '0xFF', 'hello world', 7); // Returns [1, 255, NaN, 7]

random

Returns a random item from an array or object, a random digit from a number, or a random character from a string.
Functions are cast to strings with Function.toString

[1, 2, 3, 4].random()._.random();         // Could be any of: 1, 2, 3, or 4
{ foo: 'a', bar: 'b', baz: 0 }._.random() // Could be any of: 'a', 'b', 0,
'string'._.random()                       // Could be any of: 's', 't', 'r', 'i', 'n', 'g'

/* Static Use */
lib.object.random([[1, 2, 3], ['a', 'b', 'c'], 9]);
// Returns either one of the arrays or 9

each

Invokes the provided callback for "each" item in the collection.
For each item in the collection, a callback (onIteration) is invoked with the following arguments: this refers to the object being iterated over within the body of onIteration.

Functions and Numbers are cast to strings with Function/Number.toString.

Arguments passed to onInteration:

Note: All ranges are inclusive. If startRange is greater than endRange it will perform a decrementing loop.

var total = 0, keyTotal = 0;
[1, 2, 3, 4, 5]._.each((val, key) => {
    total    += val;
    keyTotal += key.toString();
});
// total    = 15
// keyTotal = '01234'

{ hello: 1, world: 'foo', array: [1, 2, 3] }._.each((val, key, i, exit) => {
    console.log(val + ',' + key + ',' + i);
});
// Logged on 0th iteration: 1, 'hello', 0
// Logged on 1st iteration: 'foo', 'world', 1
// Logged on 2nd iteration: 1,2,3, 'array', 2

var truncated = '';
var result = 'hello world!'._.each((val, key, i, exit) => {
    if(val === ' ') return exit(val);
    truncated += val;
});
// truncated = 'hello'
// result    = ' '

/* Using Ranges */
/* All ranges are inclusive */

var arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
arr._.each(0, 3, function (val, key, i, exit) {
    this[key] *= 7;
});
// arr = [7, 14, 21, 28, 5, 6, 7, 8, 9, 10]

arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
arr._.each(4, 3, function (val, key, i, exit, parent) {
    parent[key] *= 7;
});
// arr = [1, 2, 3, 28, 35, 6, 7, 8, 9, 10]

// If rangeA > rangeB, a decrementing loop will be performed!
arr = ['d', 'l', 'r', 'o', 'w', ' ', 'o', 'l', 'l', 'e', 'h'],
str = '';
arr._.each(10000, 0, function (val, key, i, exit) {
    str += val;
});
// str = 'hello world'

/* Static Use */
var myArray = ['a', 'b', 'c'],
    onInteration = () => { /* Do something... */ }

lib.object.each(myArray, 0, 1 onInteration);
// Iterates through 'a' and 'b', but not 'c'.

every

Invokes the provided callback for "every" item in the collection.
Loops through each item in the object and calls onIteration. If false is returned, the loop will break and return false, otherwise it will return true. This is similar to Array.every except that it works for all objects, and will break only on false and not a falsy return (null, undefined, 0, etc.). this refers to the object being iterated over within the body of onIteration.

Functions and Numbers are cast to strings with Function/Number.toString.

Arguments passed to onInteration:

var obj = { a: 1, b: 2, c: 3 },
    keys = [],
    vals = [];

obj._.every((val, key) => {
    vals.push(val);
    keys.push(key);
});
// vals = [1, 2, 3], keys = ['a', 'b', 'c']

var didLoopThroughAllItems = obj._.every(val => {
    if(val === 3) return false;
});
// didLoopThroughAllItems = false

didLoopThroughAllItems = obj._.every(val => {
    if(val === 999) return false;
});
// didLoopThroughAllItems = true

/* Static Use */
var myArray = ['a', 'b', 'c'],
    onInteration = () => { /* Do something... */ }

lib.object.every(myArray, onInteration);

any

Invokes the provided callback for every item in the collection and breaks when any value (other than undefined) is returned.
Loops through each item in the object and calls onIteration. If a "non-undefined" value is returned, the loop will break and return that value.

Functions and Numbers are cast to strings with Function/Number.toString.

Arguments passed to onInteration:

var obj = { a: 1, b: 2, c: 3 },
    keys = [],
    vals = [];

obj._.any((val, key) => {
    vals.push(val);
    keys.push(key);
});
// vals = [1, 2, 3], keys = ['a', 'b', 'c']

var result = obj._.any(val => {
    if(val === 3) return val;
});
// result = 3

result = obj._.any(val => {
    if(val === 999) return val;
});
// result = undefined

result = 'hello world'._.any(function (val, key) {
    if(key == 4) return 'got the letter o';
});
// result = 'got the letter o'

/* Static Use */
var myArray = ['a', 'b', 'c'],
    onInteration = () => { /* Do something... */ }

lib.object.any(myArray, onInteration);

toArray

Converts an object to an array.
Useful for converting arguments objects to arrays. If an array is passed, a shallow copy of the array will be returned.

var string = 'a string',
    chars  = string._.toArray(); // chars = ['a', ' ', 's', 't', 'r', 'i', 'n', 'g']

var obj = { foo: 1, bar: 2 },
    arr = obj._.toArray(); // arr = [1, 2]

(function () {
    var args = arguments._.toArray();
    // args = [1, 2, 3, 4]
}(1, 2, 3, 4));

/* Static Use */
var converted = lib.object.toArray({ a: [1, 2], b: { foo: 'bar' }});
// converted = [[1, 2], { foo: 'bar' }]

first

Returns the first n items of an object.
If n is 1, the first item will be returned. If n is more than 1, an array/object of the first n items will be returned. IF a string is passed, a single string will always be returned... in this way it works like String.slice. Strings, numbers and functions will be cast to string using toString.

var string = 'a string',

    first = string._.first(),
    // first = 'a'
    firstFour = string._.first(4);
    // firstTwo = 'a st'

var array = [1, 2, 3, 4],

    arrayFirst = array._.first(),
    // arrayFirst = 1

    arrayFirstThree = array._.first(3);
    // arrayFirstThree = [1, 2, 3]

var object = { foo: 'bar', hello: 'world' },

    objectFirst = object._.first(),
    // objectFirst = 'bar'

    objectFirstThree = object._.first(3);
    // objectFirstThree = { foo: 'bar', hello: 'world' }

/* Static Use */
var staticFirst = lib.object.first([1, 2, 3]);
// staticFirst = 1

last

Returns the last n items of an object.
Works similar to first, except it returns the last n items, rather than the first n,

getCallback

Always returns a callback.
If the last item in the object is a function, it will be returned, otherwise an "empty" function is returned. This is useful for ensuring that you always have a valid callback when used against an arguments object.

This method is useless against strings, numbers, and functions. It will however, return an "empty" function if called on one.

// For this example EMPTY_CALLBACK_REPLACEMENT is a "blank" function.
// EMPTY_CALLBACK_REPLACEMENT === function () {}

var cb = [1, 2, 3, 4].getCallback();         // cb === EMPTY_CALLBACK_REPLACEMENT

cb = [1, 2, 3, function someFunction () {}]; // cb === someFunction
cb = { foo: 'bar', hello: 'world' };         // cb === EMPTY_CALLBACK_REPLACEMENT
cb = { foo: 'bar', hello: () => {} };        // cb === anonymous arrow function

(function (argA, argB, argC) {
    cb = arguments.getCallback();
    // cb === argC === exampleCallbackFunction
}('argA', 'argB', function exampleCallbackFunction () {}));

(function (argA, argB, argC, argD, argE) {
    cb = arguments.getCallback();
    // cb === EMPTY_CALLBACK_REPLACEMENT
    // Since exampleCallbackFunction wasn't the *last* argument,
    // the empty function was assigned to cb.
}('argA', 'argB', function exampleCallbackFunction () {}, 'argD', 'argE'));

/* Static Use */
var staticFirst = lib.object.getCallback(someObject);

findChildAtPath

Finds the child of an object specified by the given string path.
Finds the child specified by the given string "path" and delimiter (default '.') by walking the objects keys.

var someObject = {
    a: {
        aa: {
            aaa: 1,
            aab: 'hello'
        },
        ab: {
            aba: 2,
            abb: 'world'
        }
    },
    b: {
        ba: {
            baa: 3,
            bab: 'foo'
        },
        bb: {
            bba: 4,
            bbb: 'bar'
        }
    },
    c: [
        100,
        200,
        {
            example: 'value'
        }
    ]
}

var aa = someObject._.findChildAtPath('a.aa'),
    // Returns the object labeled by 'aa'

    aaa = someObject._.findChildAtPath('a.aa.aaa'),
    // Returns the value labeled by 'aaa' (1)

    bba = someObject._.findChildAtPath('a.bb.bba'),
    // Returns the value labeled by 'bba' (3)

    xxy = someObject._.findChildAtPath('a.bb.xxy'),
    // Returns null

    // Works on arrays too...
    c1 = someObject._.findChildAtPath('c.1'),
    // Returns 200

    c1 = someObject._.findChildAtPath('c.2.example'),
    // Returns 'value'

    d = someObject._.findChildAtPath('d'),
    // Returns null

    xxx = someObject._.findChildAtPath('');
    // Returns someObject

// If a function is passed for parameter *done*, it will be invoked
// with the item at the path, the parent of the item, and the item's key
aa = someObject._.findChildAtPath('a.aa', function (value, parent, key) {
    // this   = someObject
    // value  = { aaa: 1, aab: 'hello' }
    // parent = the object labeled by 'a' above.
    // key    = 'aa'
});

aaa = someObject._.findChildAtPath('a.aa.aaa', function (value, parent, key) {
    // this   = someObject
    // value  = 1
    // parent = the object labeled by 'a.aa' above.
    // key    = 'aaa'
});

/* Static Use */
var child = lib.object.findChildAtPath(someObject, 'somePath');

clone

Clones an object using JSON.stringify and JSON.parse.
Throws an error if the object is circular. The optional replacer argument will be passed to JSON.stringify (see MDN's JSON.stringify).

var foo, bar;

foo = { a: 1, b: 2, c: 3 };
bar = foo._.clone(); // bar = { a: 1, b: 2, c: 3 }

foo = [1, 2, 3, 4, { a: 1, b: 2}];
bar = foo._.clone(); // bar = [1, 2, 3, 4, { a: 1, b: 2}]

/* Static Use */
lib.object.clone(myObject);

only

Returns a new object with only the given types.
Filters an object by the specified list of types ('string', 'number', 'object', 'array', 'function', 'object object'). Any typeof type can be used, and multiple arguments can be specified. object will return both arrays and objects, object object will return only objects, and array will filter only arrays.

Plural forms of the types can be used as well.

var foo, bar;
foo = [1, 2, 3, 'a', 'b', 'c', 4, 5, 6];

bar = foo._.only('numbers');            // bar = [1, 2, 3, 4, 5, 6]
bar = foo._.only('strings');            // bar = ['a', 'b', 'c']
bar = foo._.only('numbers', 'strings'); // bar = [1, 2, 3, 'a', 'b', 'c', 4, 5, 6]

foo = {
    a: [1, 2, 3],
    b: 'a string',
    c: function () {},
    d: null,
    e: { z: 9, y: 8 }
};

bar = foo._.only('object');         // bar = { a: [1, 2, 3], d: null, e: { z: 9, y: 8 } }
bar = foo._.only('array');          // bar = { a: [1, 2, 3] }
bar = foo._.only('object object');  // bar = { d: null, e: { z: 9, y: 8 } }
bar = foo._.only('function');       // bar = { c: function () {} }

// Useless on strings, numbers, and functions...
bar = (5)._.only('string')              // bar = 5
bar = ('hello world')._.only('string')  // bar = 'hello world'
bar = (function () {})._.only('string') // bar = function () {}

/* Static Use */
lib.object.only(myObject, 'typeA', 'typeB', 'typeC'...);

where

Returns a new object, filtering by a predicate function.
Filters an object by using a predicate function. If the predicate returns true the item is included in the results. The predicate function will be invoked for each item within the object with the following signature: onItem ({*} item, {String} key).

var foo, bar;
foo = [1, 2, 3, 4];

bar = foo._.where(item => item > 2); // bar = [3, 4]
bar = foo._.where(item => true);     // bar = [1, 2, 3, 4]

foo = {
    a: [1, 2, 3],
    b: 'a string',
    c: function () {},
    d: null,
    e: { z: 9, y: 8 }
};

bar = foo._.where((item, key) => key === 'a');      // bar = { a: [1, 2, 3] }
bar = foo._.where(function (item, key) {            // bar = { b: 'a string' }
    return typeof item !== 'object' && key !== 'c';
});

/* Static Use */
lib.object.where(myObject, predicateFunction);

whereKeys

Returns a new object, filtering an object's keys by a predicate function.
The same as where, except that the predicate function is invoked with the signature: onItem ({String} key, {*} item).

invert

Inverts an object's keys and values.
For numbers it computes the mathematical inverse (x-1).
For strings, it reverses the string.
For functions, invert returns a new function that wraps the given function and inverts it's result.

(1)._.invert()     // -> 1
(0)._.invert()     // -> Infinity
(789)._.invert()   // -> ~0.00126742712

[6, 7, 8]._.invert() // -> { 6: 0, 7: 1, 8: 2 }
{ a: 'foo', b: 5 }   // -> { foo: 'a', 5: b }
'string'._.invert()  // -> 'gnirts'
true._.invert()      // -> false

// For functions, invert returns a new function that wraps the
// given function and inverts it's result.
function alwaysTrue = () {
    return true;
}

var alwaysFalse = alwaysTrue._.invert();
alwaysFalse() // -> false

// Under the hood alwaysFalse was turned into something like this...
function () {
    return alwaysTrue.apply(alwaysTrue, arguments)._.invert();
}

/* Static Use */
lib.object.invert(myObject);

max

Get's the highest value from an object.
For numbers, strings, functions, and booleans, the object is simply returned. An optional predicate function is available to determine the max for objects. The predicate is called with the current value in the collection, whatever is returned from the predicate is used in the evaluation to determine the if the value is the max.

[1, 4, 7, 5, 99, 1, 2]._.max()          // -> 99
['a', 'e', 'i', 'q', 'b', 'z']._.max()  // -> 'z'
[1, 'a', 4, 'r', 999]._.max()           // -> 999, since 999 > 'r' char code
{ a: 43, b: 123, c: 0 }._.max()         // -> 123

// Predicate example
var data = [
    {
        name: 'foo',
        value: 1
    },
    {
        name: 'bar',
        value: 2
    },
    {
        name: 'baz',
        value: 3
    }
];

var max = data._.max(function (item) {
    return item.value;
});

// max = { name: 'baz', value: 3 }

/* Static Use */
lib.object.max(myObject);

min

Get's the lowest value from an object.
Same as max, except it returns the minimum value.

keyOfMax

Returns the key of the highest value in an object.
For numbers, strings, functions, and booleans, the object is simply returned. An optional predicate function is available to determine the max for objects. The predicate is called with the current value in the collection, whatever is returned from the predicate is used in the evaluation to determine the if the value is the max. When a max value is found, its key is returned.

keyOfMin

Same as keyOfMax, except it returns the minimum value's key.

implements

Determines if an object has the given properties, and those properties are methods.

var MyClass = function () {
    this.foo = function () {};
    this.bar = 5;
    this.baz = function () {};
};

var x = new MyClass();
x._.implements('foo', 'baz'); // -> true
x._.implements('bar', 'baz'); // -> false, baz is not a method

var y = {
    orange: function () {},
    apple: false
};

y._.implements('orange'); // -> true
y._.implements('apple'); // -> false, apple is not a method

/* Static Use */
lib.object.implements(myObject);

implementsOwn

Determines if an object has the given properties, and those properties are methods which belongs to the object.
Same as implements, except with added hasOwnProperty check.

uniqueId

Returns a unique id for non-literals.
Returns a unique hex string for objects and functions. Throws on numbers and strings. The id is generated on a as requested basis, so the first time it's called 0x0 is returned, then 0x1, etc. etc. However, once assigned to the object, the same id will always be returned for that object.

var obj = { foo: 1, bar: 2 },
    id  = obj._.uniqueId();  // -> '0xN', where N is some base 16 number

var arr = [1, 2, 3],
    id  = arr._.uniqueId();  // -> '0xN', where N is some base 16 number

var func = function () {},
    id  = func._.uniqueId(); // -> '0xN', where N is some base 16 number

(5).uniqueId();              // Throws an Error
('a string').uniqueId();     // Throws an Error

/* Static Use */
lib.object.uniqueId(myObject);

Strings

toJSValue

Converts 'true', 'false', 'null', and 'undefined' to it's JS equivalent and parses numeric values as a number.
The string will be trimmed. If the string value is numeric, a number will be returned. If the trimmed string is non-numeric or doesn't evaluate to true, false, null, or undefined the original (untrimmed) string will be returned.

'true'._.toJSValue()        // -> returns boolean true
'false'._.toJSValue()       // -> returns boolean false

'  true  '._.toJSValue()    // -> returns boolean true
'  false  '._.toJSValue()   // -> returns boolean false

'True'._.toJSValue()        // -> returns the original string
'falsE'._.toJSValue()       // -> returns the original string

'null'._.toJSValue()        // -> returns null
'undefined'._.toJSValue()   // -> returns undefined

'5.46'._.toJSValue()        // -> returns the number 5.46

lib.string.toJSValue(myString);

camelize

Converts a string to camel case.
Replaces /[^a-z0-9$]/g with '' and makes the first letter of each word uppercase (except the first, of course).

var myString = 'hello world!';
myString._.camelize(); // -> 'helloWorld'

"we_don't_like_underscores_in_javascript"._.camelize();
// -> 'weDontLikeUnderscoresInJavascript'

decamelize

Converts a camel case string to "somewhat" sentance form.

var myString = 'thisIsCamelCased';
myString._.decamelize(); // -> 'this is camel cased'

'interestingBehavior'._.decamelize();
// -> 'interesting behavior'

'interestingBEHAVIOR'._.decamelize();
// -> 'interesting b e h a v i o r'

repeat

Repeats a string n times.

var myString = 'repeat me ';
myString._.repeat(3); // -> 'repeat me repeat me repeat me '

'*'._.repeat(10);     // -> '**********'
'Racecar'._.repeat(3) // -> 'RacecarRacecarRacecar'

/* Static Use */
lib.string.repeat(myString);

ltrim

Left trims whitespace from a string.
Functions just like String.trim, except only on the left side of the string.

rtrim

Right trims whitespace from a string.
Functions just like String.trim, except only on the right side of the string.

htmlEncode

Escapes HTML special characters.

var myString = '5 is > 7, but 7 < 9';
myString._.htmlEncode(); // -> '5 is &gt; 7, but 7 is &lt; 9'

/* Static Use */
lib.string.htmlEncode(myString);

htmlDecode

Unescapes HTML special characters.

var myString = '5 is > 7, but 7 is < 9';
myString._.htmlDecode(); // -> '5 is > 7, but 7 < 9'

/* Static Use */
lib.string.htmlDecode(myString);

addSlashes

Creates an 'eval' safe string, by adding slashes to ", ', \t, \n, \f, \r, and the NULL byte.

var myString = 'function () { return "hello world!" };';
myString._.addSlashes(); // -> 'function () { return \"hello world!\" };'

/* Static Use */
lib.string.addSlashes(myString);

ucFirst

Returns the string with the first letter capitalized.

var myString = 'hello world!';
myString._.ucFirst(); // -> 'Hello world!'

/* Static Use */
lib.string.ucFirst(myString);

lcFirst

Returns the string with the first letter lowercased.

var myString = 'Hello world!';
myString._.lcFirst(); // -> 'hello world!'

/* Static Use */
lib.string.lcFirst(myString);

titleCase

Returns the string in title case.

var myString   = 'the quick red fox jumped over the lazy brown dog!',
    titleCased = myString._.titleCase();

// titleCased = 'The Quick Red Fox Jumped Over The Lazy Brown Dog!'

/* Static Use */
lib.string.titleCase(myString);

splice

Splices a string, like Array.splice.

var myString = 'the quick red fox jumped over the lazy brown dog!';
myString = myString._.splice(4, 5, 'slow');

// myString = 'the slow red fox jumped over the lazy brown dog!'

var helloWorld = 'hello world';
helloWorld._.splice(0, 6); // -> 'world'
helloWorld._.splice(5, 6); // -> 'hello'

/* Static Use */
lib.string.splice(myString, index, deleteCount, stringToAppendAtIndex);

ellipses

Truncates a string, adding ellipses if the string is longer than length.
Truncates the given string to length. If the string is longer than length, ellipses will be added to the end of the string.

• If the optional place argument is set to 'front', the ellipses is prepended to the string, rather than appended.
• The optional ellipses argument allows '...' to be replaces with any string value.

var myString = 'the quick red fox jumped over the lazy brown dog!';

myString._.ellipses(10); // -> 'the qui...'
myString._.ellipses(20); // -> 'the quick red fox...'

myString._.ellipses(20, 'front');          // -> '...the quick red fox'
myString._.ellipses(20, 'front', '•••');   // -> '•••the quick red fox'
myString._.ellipses(20, 'back', '??????'); // -> 'the quick red ??????'

/* Static Use */
lib.string.splice(myString, index, deleteCount, stringToAppendAtIndex);

shuffle

Shuffles a string.
If the optional splitter argument is passed, it will be tokenized by the value of splitter before being shuffled. Otherwise the strings characters will be moved around.

var aString = 'hello world';
aString._.shuffle() // -> 'lweol rhold' (this is one possibility)

'hello world'._.shuffle('hello ');
// Possibilities are...
// 'hello world', and 'worldhello '

'hello world'._.shuffle(' ');
// Possibilities are...
// 'hello world', 'world hello', 'worldhello ', ' helloworld'
// ' worldhello', and 'helloworld '

/* Static Use */
lib.string.shuffle(myString, splitter);

reverse

Reverses a string.

var myString = 'hello world';
myString._.reverse()  // -> 'dlrow olleh';
'racecar'._.reverse() // -> 'racecar'

/* Static Use */
lib.string.reverse(myString);

withoutTrailingSlash

Removes a trailing slash from a string (or path).
On Node.js withoutTrailingSlash uses path.sep for a platform agnostic replacement.

var path = 'path/to/some/directory/';
path._.withoutTrailingSlash() // -> 'path/to/some/directory'

path = 'path/to/some/directory/////';
path._.withoutTrailingSlash() // -> 'path/to/some/directory'

path = '/';
path._.withoutTrailingSlash() // -> ''

// If Node.js and Windows...
path = 'path\\to\\some\\directory\\';
path._.withoutTrailingSlash() // -> 'path\\to\\some\\directory'

/* Static Use */
lib.string.withoutTrailingSlash(myString);

withTrailingSlash

Removes a trailing slash from a string (or path).
On Node.js withoutTrailingSlash uses path.sep for a platform agnostic replacement.

var path = 'path/to/some/directory';
path._.withTrailingSlash() // -> 'path/to/some/directory/'

// If Node.js and Windows...
path = 'path\\to\\some\\directory';
path._.withoutTrailingSlash() // -> 'path\\to\\some\\directory\\'

/* Static Use */
lib.string.withTrailingSlash(myString);

regexpSafe

Returns a regular expression safe string.
Prepends slashes to /[-\/\\^$*+?.()|[\]{}]/g

var money  = '$1,000.00',
    badRegExp, safeRegexp, result;

badRegexp = new RegExp(money, 'gi');
result = '$1,000.00 dollars would be nice.'._.replace(badRegexp, 'One thousand dollars');
// -> Throws 'invalid regular expression'

safeRegexp = new RegExp(money._.regexpSafe(), 'gi');
result = '$1,000.00 dollars would be nice.'._.replace(badRegexp, 'One thousand dollars');
// -> 'One thousand dollars would be nice.'

/* Static Use */
lib.string.regexpSafe(myString);

pad

Pads a string (or truncates it) to the given length.
Prepends slashes to /[-\/\\^$*+?.()|[\]{}]/g

'hello world!'._.pad(3);  // -> 'hel'
'hello world!'._.pad(20); // -> 'hello world!        '

// Custom pad string
'hello world!'._.pad(3, '-');  // -> 'hel'
'hello world!'._.pad(20, '-'); // -> 'hello world!--------'

// If *pre* parameter is passed true...
'hello world!'._.pad(3, '-', true);  // -> 'ld!'
'hello world!'._.pad(20, '-', true); // -> '--------hello world!'

/* Static Use */
lib.string.pad(myString, length, delimiter, pre);

newlineToBreak

Replaces newlines with \<br> tags.

'line 1\nline 2\nline 3'._.newlineToBreak();
// -> 'line 1<br>line 2<br>line 3'

/* Static Use */
lib.string.newlineToBreak(myString);

tabsToSpan

Replaces tab characters with tags.

'line 1\tline 2\tline 3'._.tabsToSpan();
// -> 'line 1<span class="tab"></span>line 2<span class="tab"></span>line 3'

/* Static Use */
lib.string.tabsToSpan(myString);

randomString

Generate a random string with the given length.
If the charPool argument isn't a string, the string below will be used:
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSUVWXYZ_ `~!@#$%^&*()_+\\|][\';/.,|}{":?><

libs.string.randomString(10);      // ew@64cvll- is