README
wodge
A collection of useful functions.
Example
var w = require("wodge");
API
- wodge
- symbol
- extend(object)
- clone(input)
- omit(object, toOmit)
- escapeRegExp()
- pluck(arrayOfObjects, the)
- isNumber()
- isPlainObject(input)
- arrayify(input)
- every(object, iterator)
- each(object, callback)
- bytesToSize(bytes, [precision])
- getHomeDir()
- fill(fillWith, len)
- padRight(input, width, [padWith])
- exists(array, value)
- queryFoundInObject()
- where()
- findWhere()
- without(input, toRemove)
- first(objectArray, prop, val)
- commonDir(files)
- union()
- commonSequence(a, b)
- escapeForJSON(input)
w.symbol
some cross platform symbols (tick
and cross
)
w.extend(object)
Merge a list of objects, left to right, into one.
- object
Object
a sequence of Object instances to be extended
Example
> w.extend({}, { one: 1, three: 3 }, { one: "one", two: 2 }, { four: 4 });
{ one: 'one',
three: 3,
two: 2,
four: 4 }
w.clone(input)
Clones an object or array
- input
Object | Array
the input to clone
Returns: Object | Array
Example
> date = new Date()
Fri May 09 2014 13:54:34 GMT+0200 (CEST)
> w.clone(date)
{} // a Date instance doensn't own any properties
> date.clive = "hater"
'hater'
> w.clone(date)
{ clive: 'hater' }
> array = [1,2,3]
[ 1, 2, 3 ]
> newArray = w.clone(array)
[ 1, 2, 3 ]
> array === newArray
false
w.omit(object, toOmit)
Returns a clone of the input object, minus the specified properties
- object
Object
the object to clone - toOmit
string[]
an array of property names to omit from the clone
Returns: Object
Example
> w.omit({ one: 1, two: 2, three: 3, four: 4 }, [ "two", "four" ]);
{ one: 1, three: 3 }
w.escapeRegExp()
escape special regular expression characters
Example
> w.escapeRegExp("(.*)");
'\\(\\.\\*\\)'
w.pluck(arrayOfObjects, the)
Plucks the value of the specified property from each object in the input array
- arrayOfObjects
Object[]
the input array of objects - the
string
property to pluck
Returns: Array
Example
> var data = [
... {one: 1, two: 2},
... {two: "two"},
... {one: "one", two: "zwei"},
... ];
undefined
> w.pluck(data, "one");
[ 1, 'one' ]
> w.pluck(data, "two");
[ 2, 'two', 'zwei' ]
> w.pluck(data, "one", "two");
[ 1, 'two', 'one' ]
w.isNumber()
Returns true if input is a number
Example
> w.isNumber(0)
true
> w.isNumber(1)
true
> w.isNumber(1.1)
true
> w.isNumber(0xff)
true
> w.isNumber(0644)
true
> w.isNumber(6.2e5)
true
> w.isNumber(a)
false
> w.isNumber(NaN)
false
> w.isNumber(Infinity)
false
w.isPlainObject(input)
Returns true if input type is object
and not an Array
- input
*
the input to test
Returns: boolean
Example
> w.isPlainObject(new Date())
true
> w.isPlainObject({ clive: "hater" })
true
> w.isPlainObject([ 0, 1 ])
false
w.arrayify(input)
Takes input and guarantees an array back. Result can be one of three things:
puts a single scalar in an array
converts array-like object (e.g.
arguments
) to a real arrayconverts null or undefined to an empty array
input
*
the input value to convert to an array
Returns: Array
Example
> w.arrayify(null)
[]
> w.arrayify(0)
[ 0 ]
> w.arrayify([ 1, 2 ])
[ 1, 2 ]
> function f(){ return w.arrayify(arguments); }
undefined
> f(1,2,3)
[ 1, 2, 3 ]
w.every(object, iterator)
Returns true if the supplied iterator function returns true for every property in the object
- object
Object
the object to inspect - iterator
function
the iterator function to run against each key/value pair, the args are(value, key)
.
Returns: Boolean
Example
> function aboveTen(input){ return input > 10; }
undefined
> w.every({ eggs: 12, carrots: 30, peas: 100 }, aboveTen)
true
> w.every({ eggs: 6, carrots: 30, peas: 100 }, aboveTen)
false
w.each(object, callback)
Runs the iterator function against every key/value pair in the input object
- object
Object
the object to iterate - callback
function
the iterator function to run against each key/value pair, the args are(value, key)
.
Example
> var total = 0;
undefined
> function addToTotal(n){ total += n; }
undefined
> w.each({ eggs: 3, celery: 2, carrots: 1 }, addToTotal)
undefined
> total
6
w.bytesToSize(bytes, [precision])
Convert bytes to human-readable size
- bytes
number
the bytes value to convert - [precision]
number
number of decimal places
Returns: string
Example
> w.bytesToSize(10000)
'10 KB'
> w.bytesToSize(10000, 1)
'9.8 KB'
> w.bytesToSize(10000, 2)
'9.77 KB'
> w.bytesToSize(10000, 3)
'9.766 KB'
w.getHomeDir()
Cross-platform home directory retriever
Example
> w.getHomeDir()
'/Users/Lloyd'
w.fill(fillWith, len)
Create a new string filled with the supplied character
- fillWith
string
the fill character - len
number
the length of the output string
Returns: string
Example
> w.fill("a", 10)
'aaaaaaaaaa'
> w.fill("ab", 10)
'aaaaaaaaaa'
w.padRight(input, width, [padWith])
Add padding to the right of a string
- input
string
the string to pad - width
number
the desired final width - [padWith]
string
the padding character
Returns: string
Example
> w.padRight("clive", 1)
'clive'
> w.padRight("clive", 1, "-")
'clive'
> w.padRight("clive", 10, "-")
'clive-----'
w.exists(array, value)
returns true if a value, or nested object value exists in an array
- array
Array
the array to search - value
*
the value to search for
Returns: boolean
Example
> w.exists([ 1, 2, 3 ], 2)
true
> w.exists([ { result: false }, { result: false } ], { result: true })
false
> w.exists([ { result: true }, { result: false } ], { result: true })
true
> w.exists([ { result: true }, { result: true } ], { result: true })
true
w.queryFoundInObject()
docs todo
w.where()
docs todo
w.findWhere()
docs todo
w.without(input, toRemove)
If the input is an array, returns the input minus the specified values. If the input is an object, it returns a clone of the object minus the specified properties.
- input
Array | Object
the input array or object - toRemove
*
a single, or array of values to omit
Returns: Array | Object
Example
> w.without([ 1, 2, 3 ], 2)
[ 1, 3 ]
> w.without([ 1, 2, 3 ], [ 2, 3 ])
[ 1 ]
w.first(objectArray, prop, val)
Returns the first object in the input array with property
set to value
.
- objectArray
Object[]
input array of objects - prop
string
property to inspect - val
*
desired value
Returns: Object | undefined
Example
> w.first([{ product: "egg", stock: true }, { product: "chicken", stock: true }], "stock", true)
{ product: 'egg', stock: true }
> w.first([{ product: "egg", stock: true }, { product: "chicken", stock: true }], "stock", false)
undefined
w.commonDir(files)
commonDir returns the directory common to each path in the list
- files
Array
An array of file paths to inspect
Returns: string
- - A single path ending with the path separator, e.g. "/user/some/folder/"
Example
> files = fs.readdirSync(".").map(function(file){ return path.resolve(file); })
[ '/Users/Lloyd/Documents/75lb/wodge/.DS_Store',
'/Users/Lloyd/Documents/75lb/wodge/.git',
'/Users/Lloyd/Documents/75lb/wodge/.gitignore',
'/Users/Lloyd/Documents/75lb/wodge/.jshintrc',
'/Users/Lloyd/Documents/75lb/wodge/README.md',
'/Users/Lloyd/Documents/75lb/wodge/lib',
'/Users/Lloyd/Documents/75lb/wodge/node_modules',
'/Users/Lloyd/Documents/75lb/wodge/package.json',
'/Users/Lloyd/Documents/75lb/wodge/test' ]
> w.commonDir(files)
'/Users/Lloyd/Documents/75lb/wodge/'
w.union()
merge two arrays into a single array of unique values
Example
> var array1 = [ 1, 2 ], array2 = [ 2, 3 ];
undefined
> w.union(array1, array2)
[ 1, 2, 3 ]
> var array1 = [ { id: 1 }, { id: 2 } ], array2 = [ { id: 2 }, { id: 3 } ];
undefined
> w.union(array1, array2)
[ { id: 1 }, { id: 2 }, { id: 3 } ]
> var array2 = [ { id: 2, blah: true }, { id: 3 } ]
undefined
> w.union(array1, array2)
[ { id: 1 },
{ id: 2 },
{ id: 2, blah: true },
{ id: 3 } ]
> w.union(array1, array2, "id")
[ { id: 1 }, { id: 2 }, { id: 3 } ]
w.commonSequence(a, b)
Returns the initial elements which both input arrays have in common
- a
Array
first array to compare - b
Array
second array to compare
Returns: Array
Example
> w.commonSequence([1,2,3], [1,2,4])
[ 1, 2 ]
w.escapeForJSON(input)
strips special characters, making suitable for storage in a JS/JSON string
- input
string
the input
Returns: string
Example
> w.escapeForJSON("hello\nthere")
'hello\\nthere'