amiwo

Namespace: amiwo/util

amiwo/util

Library of misc utility functions

Author:
  • Boris GBAHOUE
Source:

Methods

<static> util.add(obj, property, value [, valueProperty] [, options])

Add 'value' to property 'property' of 'obj'.
Tests if 'obj' is null and property is 'null' and if not add value to the existing value
. if 'obj[property]' is an Array => adds it to the end
. if 'obj[property]' is an Object => adds it to the 'valueProperty' using util.add(obj[property], valueProperty, value, null)
. if 'obj[property]' is a String => concatenate String
. else => replace old value

Parameters:
Name Type Argument Description
obj Object
property any
value any
valueProperty any <optional>

used when obj[property is an object].
. If not null : it represents the property name to use to add 'value' as a new property/value of the existing obj[property] (basically obj[property][valueProperty] = value)
. If null : it creates an array of object (regardless of the value of options.create_array) (basically obj[proprerty] = [obj[property], value])
options any <optional>
Properties
Name Type Argument Description
create_array boolean <optional>

=> create an Array when adding {any} to a String or in the 'else' case (default false; alias 'createArray')
concat_arrays boolean <optional>

=> if true, when 'obj[property]' and value are both Arrays, concat the Arrays instead of pushing 'value' in 'obj[property]' (default false; aliases 'concat', 'concatArray')
merge boolean <optional>

=> if true, when 'obj[property]' and value are both Objects, merge the Objects instead of pushing 'value' in 'obj[property]' (default false)
Source:
Returns:

'true' if all went well, 'false' if 'obj' or 'property' is null

Type
boolean

<static> util.addDays(date, n)

Adds 'n' days to 'date'

Parameters:
Name Type Description
date Date

the date
n Number

the number of days to add/remove
Source:
Returns:
Type
Date

<static> util.addMonths(date, n)

Adds 'n' months to 'date'

Parameters:
Name Type Description
date Date

the date
n Number

the number of months to add/remove
Source:
Returns:
Type
Date

<static> util.addYears()

Adds 'n' years to 'date'

Source:
Returns:
Type
Date

<static> util.argv()

Lookup command line argument 'name'
Sample command line node xxx.js argWithNoValue arg=value

Source:
Returns:

true if command line argument was found but with no value (i.e. argWithNoValue), value if a value was found (i.e. value for 'arg'), undefined if argv doesn't exist

Type
Boolean | String

<static> util.average(array [, key] [, options])

Calculate the average of datas contained in 'data' (or 'data[i].key' if 'key' is not nully)

Parameters:
Name Type Argument Description
array Array

: data to process (Array of numbers or Array of {: number})
key String <optional>

: the property to use if data's content are Objects
options Object <optional>
Properties
Name Type Description
ignore_nan_values: boolean

if set to true ignore NaN values to compute the average (else add 0)
Source:
Returns:

the average or NaN if no average could be computed

Type
Number

<static> util.clone(from)

Create a clone of anything

Parameters:
Name Type Description
from any
Source:
Returns:

a clone of 'from'

<static> util.deepEqual(obj, property, value)

Test if 'obj[property]' is === to 'value' if obj is not null

Parameters:
Name Type Description
obj Object
property any
value any
Source:
Returns:

false if obj is null or values don't match

<static> util.equal(obj, property, value)

Test if 'obj[property]' is == to 'value' if obj is not null

Parameters:
Name Type Description
obj Object
property any
value any
Source:
Returns:

false if obj is null, property is null or values don't match

<static> util.expressParam(req:, name [, defaultValue])

Replacement for Express' req.param() function which got deprecated for some reason
Return the value of param name when present or defaultValue.

  • Checks route placeholders, ex: /user/:id
  • Checks body params, ex: id=12, {"id":12}
  • Checks query string params, ex: ?id=12

To utilize request bodies, req.body
should be an object. This can be done by using
the bodyParser() middleware.

Parameters:
Name Type Argument Description
req: Request

Express Request object
name String
defaultValue Mixed <optional>

: the value to return if no parameter with name 'name' has been found
Source:
Returns:
Type
String

<static> util.filter(obj, callback)

Recursive filter function that go through 'obj' and returns the elements that meet the conditions specified in the callback function 'callback' to each entry (for Arrays) or to each value (for Objects)

Parameters:
Name Type Description
obj Object | Array
callback function

: which signature is callback(element:any, index|key: number|string, array|obj:any[]|{}) => boolean
Source:
Throws:

if 'obj' is neither an Array or an Object

Type
TypeError
Returns:

same type as 'obj'

Type
Object | Array

<static> util.flatten(object [, root] [, options])

Flatten an object transforming {obj: {subobj1: {subsubobj1: "data 1", subsubobj2: "data 2", ...}, ... } } into {obj.subobj1.subsubobj1: "data 1", obj.subobj1.subsubobj2: "data 2", ...}

Parameters:
Name Type Argument Description
object Object
root String <optional>

of the properties to use
options Object <optional>
Properties
Name Type Argument Default Description
ignoreArray boolean <optional>
 false

set to true to navigate through Arrays to flatten its components (else flatten Arrays components but keep the Array structure)
Source:
Returns:
Type
Object

<static> util.flattenArray(array)

Flatten an array of arrays into an array containing (as per concat) all the elements

Parameters:
Name Type Description
array Array
Source:
Returns:
Type
Array

<static> util.fuse(obj1, obj2, options)

Fuse 'obj1' and 'obj2' and return the result.
The result will be of the same type as 'obj1' for Array & Object

- Array + Array => Array (behaves as concat modulo options.array.no_copy)
- Array + Object|value => Array
- Object + Array => Object with a new property 'array' set to Array
- Object + Object => Object (if o1 and o2 have an identical key, o2's is kept)
- Object + value => Object with a new property 'value' set to 'obj2'
- value + Array => Array with value as first entry

Fuse is different from merge in the sense that when if attempting to fuse an Object with a non Object,

  1. 'merge()' will replace o1 property by o2's no matter what o2 is;
  2. 'fuse()' will try to combine them (i.e. "adding" o2's to o1 but keeping o1)
  3. if 'obj2' is null (or in case of a conflict deeper in obj1/obj2) fuse will use obj2 while merge will keep null
Parameters:
Name Type Description
obj1 any
obj2 any
options Object
Properties
Name Type Description
array.no_copy Object

: don't copy existing values when concatenating 2 arrays (to avoid duplicates) [set to true by default (i.e. NOT behaving like concat)]
Source:
Returns:

a fused object (sse above)

<static> util.get()

Parses 'obj' keys and return an Array containing all the properties which keys match 'expr'

Source:
Returns:

[any]

<static> util.getProperty(obj, property, options)

Get the property 'property' from 'obj'. Works with nested structures using a dot syntax

Parameters:
Name Type Description
obj Object

to search
property String

the name of the property to look for
options Object

supported options : upsert (create intermediate objects if they doesn't exist and return null)
Source:
Returns:

or null if the property doesn't exist

Type
any

<static> util.getTime()

Improved Date::getTime() taking ms into account and accepting non Date objects

Source:
Returns:

NaN if date is null

Type
Number

<static> util.getWeek(d, options)

Get the week number
Source = http://weeknumber.net/how-to/javascript

Parameters:
Name Type Description
d Date
options Object
Properties
Name Type Description
iso Object

if set to false return -1 for wk53 of in January, -2 for wk54
Source:
Returns:
Type
Number

<static> util.hasOwnProperties(object, properties)

Test if 'object' has all the properties listed in 'properties'

Parameters:
Name Type Description
object Object
properties Array.<String>
Source:
Returns:
Type
Boolean

<static> util.indexOf(array, object:)

Equivalent of smartEqual() function for Array's indexOf (which native implementation does === test)

Parameters:
Name Type Description
array Array

(can safely be null)
object: any

object which index we are looking for
Source:
Returns:

the index of 'object' if it's contained by 'array'; -1 if not (or if 'array' is null)

Type
Number

<static> util.isEmpty(obj:)

Depending on the type of obj

 - String : return true if null or equal to ""
 - Array : return true if null or length == 0
 - Object : return true if null or keys.length == 0
 - else : return true if null
Parameters:
Name Type Description
obj: any

the Object to test
Source:

<static> util.isNativeObject(any)

Tests if 'any' is a native JS object

Parameters:
Name Type Description
any any
Source:
Returns:

, false if 'any' is null/undefined

Type
Boolean

<static> util.isNotEmpty(obj:)

Depending on the type of obj

 - String : return true if not null and not equal to ""
 - Array : return true if not null and length > 0
 - Object : return true if not null and keys.length > 0
 - else : return true if not null
Parameters:
Name Type Description
obj: any

the Object to test
Source:

<static> util.isObject(obj [, native])

Tests if 'obj' is an Object (excluding Date, Number, Array, ...)
See util::typeOf

Parameters:
Name Type Argument Default Description
obj any
native Boolean <optional>
 false

if true, tests if 'obj' is a native Object and not a non native object (i.e. Class)
Source:
Returns:

, false if 'obj' is null/undefined

Type
Boolean

<static> util.isObject_v1()

Checks if 'a' is an Object
From http://stackoverflow.com/questions/8834126/how-to-efficiently-check-if-variable-is-array-or-object-in-nodejs-v8

Deprecated:
  • Yes
Source:

<static> util.isValidEmail()

Tests if 'str' is a valid email address

Source:
Returns:
Type
boolean

<static> util.keys(obj, def)

Safe Object.keys that works with nully objects

Parameters:
Name Type Description
obj Object
def any

: value to return if 'obj' is nully (null by default)
Source:
Returns:

, undefined if 'obj' is not an Object, null if 'obj' is nully

Type
Array

<static> util.map(obj, callback)

Recursive map function that go through 'obj' and apply 'callback' to each entry (for Arrays) or to each value (for Objects)

Parameters:
Name Type Description
obj Object | Array
callback function

: which signature is callback(element, index|key, array|obj)
Source:
Throws:

if 'obj' is neither an Array or an Object

Type
TypeError
Returns:

same type as 'obj'

Type
Object | Array

<static> util.max( [any] [, key] [, options])

Returns the max value contained in 'data' (or 'data.key' if 'key' is not nully)

Parameters:
Name Type Argument Description
any <optional>

data : array to process
key String <optional>

: the property to use if data's content are Objects
options Object <optional>
Source:
Returns:

the max or NaN/null if no max could be computed

Type
Number/Date

<static> util.merge(o1, o2, options)

Merge that works on complex structures. In case of conflicts, value from o2 takes precedence over o1's.
Merge is different from fuse in the sense when if attempting to merge an Object with a non Object, merge will replace o1 property by o2's not matter what o2 is. Fuse will try to combine them (i.e. "adding" o2's to o1 but keeping o1)

Parameters:
Name Type Description
o1 any
o2 any
options Object

(passed to util::fuse() mostly; array.no_copy set to false by default (behaves LIKE concat for array))
Source:
Returns:

returns a new Object (o1 & o2 are not modified)

Type
Object

<static> util.min( [any] [, key] [, options])

Returns the min value contained in 'data' (or 'data.key' if 'key' is not nully)

Parameters:
Name Type Argument Description
any <optional>

data : data to process
key String <optional>

: the property to use if data's content are Objects
options Object <optional>
Source:
Returns:

the max or NaN/null if no max could be computed

Type
Number/Date

<static> util.notDeepEqual(obj, property, value)

Test if 'obj[property]' is !== to 'value' if obj is not null

Parameters:
Name Type Description
obj Object
property any
value any
Source:
Returns:

false if obj is null or values don't match

<static> util.notEqual(obj, property, value)

Test if 'obj[property]' is != to 'value' if obj is not null

Parameters:
Name Type Description
obj Object
property any
value any
Source:
Returns:

false if obj is null or values don't match

<static> util.notInSet(set, elements)

Returns the items from 'elements' which are not in 'set'

Parameters:
Name Type Description
set Array
elements any
Source:
Returns:
Type
Array

<static> util.overwrite(o1, o2)

Replace 'o1' content by 'o2's' without breaking o1 reference

Parameters:
Name Type Description
o1 Object
o2 Object
Source:
Returns:

o1

Type
Object

<static> util.parseDateFromString(str)

Parse a Date in the format ISO 8601 standard ie 'yyyy-mm-ddThh: mm: ssZ', where hh is in 24h format

Parameters:
Name Type Description
str String
Source:
Returns:

a Date object or NaN

<static> util.removeFirstSlash()

Parse local path : check if the first char is a '/' and if so, remove it.
Doesn't modify 'str'

Source:

<static> util.request(options: [, debug])

Wraps request to add an 'amiwo' parameter with a UUID and in case of error, unwrap the StatusCodeError to send directly the associated Error (i.e. StatusCodeError.error)

Parameters:
Name Type Argument Default Description
options: Object

options to be passed to request but the following
options.uuid boolean <optional>
 true

set to true to tag the request ('amiwo' parameter)
options.rawError boolean <optional>
 false

set to true to send the unprocessed Error
debug function <optional>

debug method (should behave as 'debug()' or 'console.log')
Source:
Returns:
Type
Promise

<static> util.setCharAt(str, index, chr)

Set char 'chr' at index 'index' in 'str'

Parameters:
Name Type Description
str String
index Number
chr String
Source:
Returns:

String

<static> util.setProperty(obj, property, value [, options])

Set the property 'property' from 'obj' to 'value'. Works with nested structures using a dot syntax

Parameters:
Name Type Argument Description
obj Object

to search
property String

the name of the property to look for
value any
options Object <optional>
Properties
Name Type Argument Default Description
push Object <optional>
 false

: if true push, when 'property' references an Array, push value into it instead of replacing it
Source:

<static> util.smartDeepEqual(obj1, obj2 [, ignoreOrder] [, ignoreProperties])

Deep equals that works for Object and Arrays

Parameters:
Name Type Argument Description
obj1 any
obj2 any
ignoreOrder boolean <optional>

for arrays only, default to false
ignoreProperties Array.<String> <optional>

entries or properties to ignore in the comparison
Source:
Returns:
Type
boolean

<static> util.smartEqual(obj1, obj2 [, ignoreOrder] [, ignoreProperties])

Equals that works for Object and Arrays

Parameters:
Name Type Argument Default Description
obj1 any
obj2 any
ignoreOrder boolean <optional>
 false

for arrays only, default to false
ignoreProperties Array.<String> <optional>

entries or properties to ignore in the comparison
Source:
Returns:
Type
boolean

<static> util.today(days)

Returns a Date 'days' days from today (uses local TimeZone)

Parameters:
Name Type Description
days Number
Source:
Returns:
Type
Date

<static> util.toLowerCase()

Tries to transform 'str' to lower case

Source:
Returns:

lower cased 'str' or 'str' if 'str' is not a String

Type
String

<static> util.toUpperCase()

Tries to transform 'str' to upper case

Source:
Returns:

upper cased 'str' or 'str' if 'str' is not a String

Type
String

<static> util.typeOf(obj)

Returns the type of 'obj' distinguishing properly Arrays from Object, Date from Object etc.
Any non native Object (e.g., class) will be returned as 'object'

Parameters:
Name Type Description
obj any

: obj to get the typeof
Source:
Returns:

null for null 'obj', lower case class name otherwise (object, date, array, number, ...)

Type
String | null

<static> util.values(obj)

Get all the values of 'obj' in an Array (as per the values matching each of key from Object.keys(obj))

Parameters:
Name Type Description
obj Object
Source:
Returns:

, undefined if 'obj' is not an Object, null if 'obj' is null, [] if 'obj' is empty ({})

Type
Array

<static> util.yesterday()

Convenience function; equivalent to today(-1)

Source:
Returns:
Type
Date