isnode-mod-utilities

ISNode Utilities Module

Introduction

This is just a module for the ISNode Framework. To learn how to use the framework, we strongly suggest obtaining a copy of the Hello World example.

The Utilities Module provides a variety of disparate methods that may commonly be used by other modules, or directly by services.

This includes - Random String and UUID generation, RSA Encryption and Decryption, Checking whether a string is a JSON string or object, checking how many attributes an object has, deep cloning objects, getting the current date in ISO format, and more.

Methods

uuid4()

Synchronous Function. Generates a UUID String (v4 format of the UUID standard)

Input Parameters: N/A

Returns: A UUID (v4 format) as a String

Code example

// The below use case assumes that you have an instance of the isnode master object

var uuid = isnode.module("utilities").uuid4();
console.log(uuid);
// An example result would be "f7812069-09fc-45a5-8d36-2f1247e0a48a"

isJSON(input)

Synchronous Function. Checks if an input is a JSON object, JSON string, normal string or otherwise

Input Parameters:

1. input - Can be a string or an object. Or of an unknown type

Returns:

1. output - (String). Possible values of "json_object", "json_string" or "string"

Code example

// The below use case assumes that you have an instance of the isnode master object

var example1 = {
  "attr1": "val1",
  "attr2": "val2",
  "attr3": "val3"
}
var example2 = JSON.stringify(example1);
var example3 = "Sample String"

var result1 = isnode.module("utilities").isJSON(example1);
var result2 = isnode.module("utilities").isJSON(example2);
var result3 = isnode.module("utilities").isJSON(example3);

console.log(result1); // Expect "json_object"
console.log(result2); // Expect "json_string"
console.log(result3); // Expect "string"

randomString(length)

Synchronous Function. Generates a random alphanumeric string of a defined length

Input Parameters:

1. length - (Integer) The length of the random string you would like returned

Returns:

1. output - (String). The random string that was generated. Possible characters within the string include - "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

Code example

// The below use case assumes that you have an instance of the isnode master object

var randomString = isnode.module("utilities").randomString(10);
console.log(randomString); // Possible result could be "gf7agkj5m9"

objectLength(object)

Synchronous Function. Returns the length of a defined object (ie; number of direct child properties that it has)

Input Parameters:

1. object - (Object) Takes a Javascript Object as an input

Returns:

1. output - (Integer). A count of the number of attributes within the defined object

Code example

// The below use case assumes that you have an instance of the isnode master object

var example = {
  "attr1": "val1",
  "attr2": "val2",
  "attr3": "val3"
}
var objLength = isnode.module("utilities").objectLength(example);
console.log(objLength); // Should display "3"

getCurrentDateInISO()

Synchronous Function. Returns the current date/time in ISO format

Input Parameters: N/A

Returns:

1. output - (String). A string of the current date/time in ISO format

Code example

// The below use case assumes that you have an instance of the isnode master object

var currentTimeStamp = isnode.module("utilities").getCurrentDateInISO();
console.log(currentTimeStamp); 
// An example result would be "2019-04-04T06:10:14.920Z"

validateString(text, validator)

Synchronous Function. Validates a text string according to a validator

Input Parameters:

1. text - (String). Text string to validate
2. validator - (Object). Validator object. Refer to example below for sample use cases

Returns:

1. output - (Boolean). True if string passes validator, False if it does not

Code example

// The below example checks a string to ensure it only contains characters that exist within a defined whitelist:
var validate = isnode.module("utilities").validateString
var result = validate("test123", {whitelist: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"});
console.log(result) // Returns true because the characters from "test123" are all present in the defined whitelist
var result = validate("test{*}", {whitelist: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"});
console.log(result) // Returns false because the characters "{*}" from "test{*}" are are not present in the defined whitelist

// The below example checks a string to make sure that its a valid email:
var validate = isnode.module("utilities").validateString
var result = validate("[e-mail]", {email: true});
console.log(result) // Returns true because "[e-mail]" is an email address of valid format
var result = validate("john^gmail.com", {email: true});
console.log(result) // Returns false because "john^gmail.com" is NOT an email address of valid format

// The below example checks a string to make sure it validates against a defined regex
var validate = isnode.module("utilities").validateString
var result = validate("abc", {regex: \abc+\});
console.log(result) // Returns true because "abc" matches the defined regex
var result = validate("abd", {regex: \abc+\});
console.log(result) // Returns false because "abd" does not match the defined regex

cloneObject(src)

Synchronous Function. Deep clones an object (makes a copy of it) and returns the copy (rather than a reference)

Input Parameters:

1. src - (Object) The source object

Returns:

1. output - (Object). A copy of the source object (rather than simply a reference)

Code example

// The below use case assumes that you have an instance of the isnode master object

var example1 = {
  "attr1": "val1",
  "attr2": "val2",
  "attr3": "val3"
}

var example2 = isnode.module("utilities").cloneObject(example1);

example2.attr3 = "altered"
example1String = JSON.stringify(example1);
example2String = JSON.stringify(example2);

console.log(example1String) 
// Should return a string - {"attr1":"val1", "attr2":"val2", "attr3":"val3"}

console.log(example2String) 
// Should return a string - {"attr1":"val1", "attr2":"val2", "attr3":"altered"}

modules.load(name)

Synchronous Function. First attempts to load binary compiled version of a module (js/jsc file), and if that fails, it attempts to load the Javascript source version

Input Parameters:

1. name - (Object) Name of file (without extension)

Returns:

1. output - (Object/Function). Exported object/function from the JS module/library

Code example

/* First attempts to load test.jsc compiled module.
 * If this fails, then it attempts to load test.js source file module.
 * If this fails, then it returns false.
*/

var test = isnode.module("utilities").modules.load("./test");

parseCsv(inputString, options, cb)

Asynchronous Function. Parses a CSV string in to a JSON array

Input Parameters:

1. inputString - (String) A string containing CSV (comma-separated value) formatted data
2. options - (Object) An object containing options.
   1. options.delimiter - (String) The delimiter that separates each value within a given row. Eg; ","
   2. options.header - (Boolean) Defines whether to expect a header row or not
3. cb - (Function) Callback Function. Expect a single object parameter - eg; cb(res)

Returns:

1. output - (Boolean). True if successful, False if it failed. Rely on content of callback function rather than the actual return value

Callback Function:

1. res - (Object). Object containing three child properties:
   1. success - (Boolean) True if it succeeded, False if it failed
   2. message - (String) A free text description of why it failed or that it succeeded\
   3. output - (Array, Optional) Contains an array of records from the CSV string. Will only be present if success=true. If header row was defined then each element of the array will be an object containing a series of attributes/values. If no header row was defined then each element of the array will be another array of strings - each string containing a record/column value

Example CSV File (example.csv)

First Name,Last Name,Age
John,Jameson,52
James,Peters,19
Alice,Jones,20

Code example

// The below use case assumes that you have an instance of the isnode master object

var fs = require('fs');
var contents = fs.readFileSync('example.csv', 'utf8');
var options = {header: true, delimiter: ","};
isnode.module("utilities").parseCsv(contents, options, function(result){
  console.log(result);
});

/* Console Log Should display a string. Something like: 
 * [
 *	{"First Name": "John", "Last Name": "Jameson", "Age": 52},
 *  {"First Name": "James", "Last Name": "Peters", "Age": 19},
 *  {"First Name": "Alice", "Last Name": "Jones", "Age": 20},
 * ]
 */

crypto.encrypt(text, key, encoding)

Synchronous Function. Symmetrically encrypts a string of unencoded text using an RSA private key

Input Parameters:

1. text - (String) An unencrypted string of text that you would like to encrypt
2. key - (String) An RSA private key. In string format. Ie; if it was stored in a file, you must load that file first in to a string and use the string
3. encoding - (String) Encoding type for output. Options of "buffer", "binary", "hex" or "base64"

Returns:

1. output - (String). The encrypted string

Code example

// The below use case assumes that you have an instance of the isnode master object

var fs = require('fs');
var key = fs.readFileSync('key.pem', 'utf8');
var decryptedString = "This is a sample string";
var encryptedString = isnode.module("utilities").crypto.encrypt(decryptedString, key, "base64");
console.log(encryptedString);

/* 
Should display something like:

KkoY1g9ztWhSZsilWC21U+Eg7q1TLFIDHmSq8lEAbxIzdHxcUiJWG9ICsRAlK8G1gjkRoeFaz7GtU5JD9H+lclc5ifi93Lkq5s7Y/NQRqnK54mxiPWjMSC/z29q3jdOVOhKFwI1ePKYWY5rusbfg/f1vHQMKXPGg9iyUzIVLM6geb+FcvwcETqicadERTYwyV6d4U83NQ6rGDh5Px0gRb9xfXziYC+kIsGOR7pp9YDSeWPd+eJcp1FqMJAxld3mM7wyZr7vuYaeK6JwzmpPFZ1v7DsEzqPMLMkMKbFsUrbmrSxrdtppWKPSWHTD0Pij32m8C8Q6soiBxdbw+rcBTLA==
*/

crypto.decrypt(text, key, encoding)

Synchronous Function. Symmetrically decrypts a string of encoded text using an RSA private key

Input Parameters:

1. text - (String) An encrypted string of text that you would like to decrypt
2. key - (String) An RSA private key. In string format. Ie; if it was stored in a file, you must load that file first in to a string and use the string
3. encoding - (String) Encoding type for output. Options of "buffer", "json" or "utf8"

Returns:

1. output - (Object). A copy of the source object (rather than simply a reference)

Code example

// The below use case assumes that you have an instance of the isnode master object

var fs = require('fs');
var key = fs.readFileSync('key.pem', 'utf8');
var encryptedString = "KkoY1g9ztWhSZsilWC21U+Eg7q1TLFIDHmSq8lEAbxIzdHxcUiJWG9ICsRAlK8G1gjkRoeFaz7GtU5JD9H+lclc5ifi93Lkq5s7Y/NQRqnK54mxiPWjMSC/z29q3jdOVOhKFwI1ePKYWY5rusbfg/f1vHQMKXPGg9iyUzIVLM6geb+FcvwcETqicadERTYwyV6d4U83NQ6rGDh5Px0gRb9xfXziYC+kIsGOR7pp9YDSeWPd+eJcp1FqMJAxld3mM7wyZr7vuYaeK6JwzmpPFZ1v7DsEzqPMLMkMKbFsUrbmrSxrdtppWKPSWHTD0Pij32m8C8Q6soiBxdbw+rcBTLA==";
var decryptedString = isnode.module("utilities").crypto.decrypt(encryptedString, key, "utf8");
console.log(decryptedString);

// Should display something like: "This is a sample string"