utils

utils

Utility helper functions — id, ids, hashing, parsing, cleaning, and other general-purpose helpers

Constructor

new utils()

Source:

Members

(static, constant) currencySymbol

Source:
A function that will take a currency string and return the symbol
Example
//Returns £
sdk.utils.currencySymbol('gbp');

//Returns $
sdk.utils.currencySymbol('usd');

Methods

(static) cleanValue(data, type, options) → {*}

Source:
A helper function for cleaning an input value to match a required type
Example
sdk.utils.cleanValue({_id:'1234', title:'Item'...}, 'reference'); // returns '1234'
sdk.utils.cleanValue('true', 'boolean'); // returns true
sdk.utils.cleanValue('Mr Rogers House', 'key'); // returns 'mrRogersHouse';
sdk.utils.cleanValue('Hello.World@email.COM', 'email'); // returns 'hello.world@email.com';
Parameters:
Name Type Description
data * The input to clean
type String The data type to parse
options Object Additional options for parsing
Returns:
the resulting cleaned value
Type
*

(static) comma(array, path) → {String}

Source:
A helpful class that can take an array of values and return them as a comma seperated string, If the values are objects, then a property to use as the string representation can be specified
Example
//Returns 'cat, dog, bird'
sdk.utils.comma(['cat', 'dog', 'bird']);

//Returns 'cat, dog, bird'
sdk.utils.comma([{title:'cat'}, {title:'dog'}, {title:'bird'}], 'title');
Parameters:
Name Type Description
array Array The array of values to translate
path String An optional property key to use for each value
Returns:
The resulting comma seperated string
Type
String

(static) errorMessage(error) → {String}

Source:
Helper function for retrieving a human readable error message from server error response objects
Parameters:
Name Type Description
error Object The error object to translate
Returns:
The resulting human readable error message
Type
String

(static) exists(value) → {Boolean}

Source:
A helper function for checking whether a value is truthy/falsy
Example
sdk.utils.exists('undefined'); // false
sdk.utils.exists([]); // true
sdk.utils.exists(''); // false
sdk.utils.exists(undefined); // false
Parameters:
Name Type Description
value Anything The value to check
Returns:
whether the value is truthy
Type
Boolean

(static) extractFromArray(array, key, sum, flatten, unique, exclude, options) → {Array}

Source:
Returns a subset of values in an array that match a provided rule
Example
//Returns [12, 45] as all the values
sdk.utils.extractFromArray([{name:'Wendy', age:12}, {name:'Roger', age:45}], 'age');

//Returns 32
sdk.utils.extractFromArray([{name:'Wendy', age:12}, {name:'Roger', age:20}], 'age', {sum:true});
Parameters:
Name Type Description
array Array The array you want to extract values from
key String The path to the child property you want to extract
sum Boolean Whether to sum the extracted values together in total
flatten Boolean Whether to flatten nested child arrays
unique Boolean Whether to only return unique values
exclude Boolean Whether to exclude null or undefined values
options Object Pass through extra options for how to extract the values
Returns:
An array of all values retrieved from the array, unless provided arguments require otherwise
Type
Array

(static) formatCurrency(value, currency) → {String}

Source:
A function that will take an integer and a currency string and return a formatted numeric amount rounded to 2 decimal places
Example
//Returns £10.00
sdk.utils.formatCurrency(1000, 'gbp');

//Returns $10.00
sdk.utils.formatCurrency(1000, 'usd');
Parameters:
Name Type Description
value Integer The amount in cents
currency String The currency to format
Returns:
The formatted value
Type
String

(static) getTypeFromID(id) → {String}

Source:
A function that will take an id and return the type key
Example
// Returns 'user'
sdk.utils.getTypeFromID('52b523f775beea960013f6cd');

// Returns 'role'
sdk.utils.getTypeFromID('62b59cb572fb4772e7b5fa93');
Parameters:
Name Type Description
id String The id of an object
Returns:
The key
Type
String

(static) guid() → {String}

Source:
Generates a globally unique ID, helpful for adding unique keys for iterable loops
Example
//Returns 4323a78br-z16h-289j-zwl1-938lda334asd
sdk.utils.guid()
Returns:
The new globally unique identifier
Type
String

(static) hash(array, key) → {Object}

Source:
Creates a fast keyed hash object from an array of items
Example
//Returns { jimbo:{id:'jimbo', title:'Jim Jones'}, {id:'roger', title:'Roger Fellow'} }
sdk.utils.hash([{id:'jimbo', title:'Jim Jones'}, {id:'roger', title:'Roger Fellow'}], 'id');
Parameters:
Name Type Description
array Array The array of items to convert into a hash
key String The key or path to the property on each item to use as the hashed key
Returns:
A key/value paired object
Type
Object

(static) id(input, asObjectID) → {String}

Source:
Returns a specified _id for an object
Example
//Returns '5cb3d8b3a2219970e6f86927'
sdk.utils.id('5cb3d8b3a2219970e6f86927')

//Returns true
typeof service.id({_id:'5cb3d8b3a2219970e6f86927', title, ...}) == 'string';
//Returns true
typeof service.id({_id:'5cb3d8b3a2219970e6f86927'}, true) == 'object';
Parameters:
Name Type Description
input Object An object that is or has an _id property
asObjectID Boolean Whether to convert to a Mongo ObjectId
Returns:
Will return either a string or a Mongo ObjectId
Type
String

(static) ids(array, asObjectID) → {Array}

Source:
Cleans and maps an array of objects to an array of IDs
Example
//Returns ['5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86927', '5cb3d8b3a2219970e6f86927']
sdk.utils.ids([{_id:'5cb3d8b3a2219970e6f86927'}, {_id:'5cb3d8b3a2219970e6f86927'}, null, '5cb3d8b3a2219970e6f86927'])
Parameters:
Name Type Description
array Array An array of objects or object ids
asObjectID Boolean Whether or not to map the ids as Mongo ObjectIds
Returns:
An array of Ids
Type
Array

(static) isValidEmailAddress(emailAddress) → {Boolean}

Source:
A helper function for getting a number from some input
Example
sdk.utils.isValidEmailAddress('123.com'); // Returns false
sdk.utils.isValidEmailAddress('hello@world.com'); // Returns true
sdk.utils.isValidEmailAddress('something@special.io'); // Returns true
Parameters:
Name Type Description
emailAddress String The email to validate
Returns:
whether or not the input is a valid email address
Type
Boolean

(static) loadExternalScript(url) → {Promise}

Source:
A function that dynamically include an external javascript resource ensuring that it will only be included once
Example
await sdk.utils.loadExternalScript('https://cdn.javascript.com/external/script.js');
Parameters:
Name Type Description
url String The url of the external script
Returns:
A promise that will be resolved once the script has been loaded
Type
Promise

(static) loadExternalStyle(url) → {Promise}

Source:
A function that dynamically include an external css resource ensuring that it will only be included once
Example
await sdk.utils.loadExternalStyle('https://cdn.css.com/external/style.css');
Parameters:
Name Type Description
url String The url of the external css
Returns:
A promise that will be resolved once the css has been loaded
Type
Promise

(static) machineName(string) → {String}

Source:
Helper function for cleaning strings to use as database ids
Parameters:
Name Type Description
string String The string to clean eg. (Awesome Event!)
Returns:
A cleaned and formatted string eg. (awesomeEvent)
Type
String

(static) mapParameters(parameters) → {String}

Source:
A helpful function that can take a keyed object literal and map it to url query string parameters
Example
//Returns &this=that&hello=world
sdk.utils.mapParameters({"this":"that", "hello":"world"})
Parameters:
Name Type Description
parameters Object The object you want to transalte
Returns:
The query string
Type
String

(static) matchInArray(array, key, value, comparator) → {Array}

Source:
A function that can return a selection of values that were found in an array that match a specific rule, This is often used to evaluate expressions within form fields
Example
//Returns [{name:'Michael', age:45}] as that is only item in the array that matches the criteria
sdk.utils.matchInArray([{name:'Wendy', age:12}, {name:'Michael', age:45}], 'age', 45, '>=');
Parameters:
Name Type Description
array Array The array to check
key String The javascript dot notation path to extract
value String The value to compare against
comparator String The logical operator to use to compare the extracted value with the provided value ('>', '<', '>=', '<=', 'in', '==') Defaults to '==' (Is equal to)
Returns:
Returns an array of matching values
Type
Array

(static) parseBoolean(value) → {Boolean}

Source:
A helper function for parsing input as boolean values
Example
sdk.utils.parseBoolean('true'); // returns true
sdk.utils.parseBoolean('y'); // returns true
sdk.utils.parseBoolean('YES'); // returns true
sdk.utils.parseBoolean('1'); // returns true
sdk.utils.parseBoolean('t'); // returns true
sdk.utils.parseBoolean(''); // returns false
sdk.utils.parseBoolean('0'); // returns false
sdk.utils.parseBoolean('n'); // returns false
sdk.utils.parseBoolean('no'); // returns false
sdk.utils.parseBoolean('f'); // returns false
sdk.utils.parseBoolean('null'); // returns false
Parameters:
Name Type Description
value * The input to parse
Returns:
the resulting true/false value
Type
Boolean

(static) parseDate(input) → {Date}

Source:
A helper function for getting a javascript date object from some input returns undefined if it can not be parsed
Example
sdk.utils.parseDate(input);
Parameters:
Name Type Description
input String | Number The value to parse as a date
Returns:
the javascript date object
Type
Date

(static) parseEmail(emailAddress) → {String|Boolean}

Source:
A helper function for getting a formatted email address
Example
sdk.utils.parseEmail('ToMack@gmail.com'); // returns 'tomack@gmail.com'
sdk.utils.isValidEmailAddress('hello.world.com'); // Returns false
Parameters:
Name Type Description
emailAddress String The input to parse as an email
Returns:
a valid email address in lowercase, or false if parse is not possible
Type
String | Boolean

(static) parseInt(input) → {Integer}

Source:
A helper function for getting an integer
Example
sdk.utils.parseInt('134'); // returns 134
sdk.utils.parseInt('cows'); // returns 0
sdk.utils.parseInt(); // returns 0
Parameters:
Name Type Description
input String | Number The input to parse as an integer
Returns:
the resulting integer or 0
Type
Integer

(static) parseNumber(value, decimalPoints) → {Number}

Source:
A helper function for getting a number from some input
Example
sdk.utils.parseNumber('123'); // Returns 123
sdk.utils.parseNumber('75.501', 2); // Returns 75.5
sdk.utils.parseNumber(''); // Returns 0
sdk.utils.parseNumber(null); // Returns 0
sdk.utils.parseNumber(); // Returns 0
Parameters:
Name Type Description
value String The input value
decimalPoints Number The number of decimal points to round to
Returns:
the parsed number value
Type
Number

(static) parseURL(input) → {String}

Source:
A helper function for getting a full url string from some input
Example
sdk.utils.parseURL('google.com'); // Returns https://google.com
sdk.utils.parseURL('mailto:hello@qik.dev'); // Returns 'mailto:hello@qik.dev'
sdk.utils.parseURL('://hello.com'); // Returns '://hello.com'
sdk.utils.parseURL('hello@email.com'); // Returns 'mailto:hello@email.com'
Parameters:
Name Type Description
input String The input value
Returns:
the fully parsed URL
Type
String