wodge

#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 array

• converts 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'