@trayio/connector-utils

Connector-utils

Common utility functions used in connectors.

Installation

The connector-utils package will be inherently included as part of a new connector scaffold (as part of the Trayio yeoman generator).

When adding the package as part of an existing connector, in your terminal, run:

npm i @trayio/connector-utils --save

Basic Usage

To require the package, require as @trayio/connector-utils:

const utils = require('@trayio/connector-utils')

This will give full access to the library. We can then reference utilities such as UserInputError by using:

utils.error.UserInputError('custom error message')

A better usage alternative is to use destructuring, as in the example:

const { UserInputError } = require('@trayio/connector-utils').error

A full breakdown of available utilities is included in the documentation below.

Please be sure to add any discovered issues or improvement recommendations to the Issues tab of this repo.

Documentation

Classes

GenericError ⇐ Error

Class representing the base error for all connector errors

UserInputError ⇐ GenericError

Class representing a UserInputError

ConnectorError ⇐ GenericError

Class representing a ConnectorError

ApiError ⇐ GenericError

Class representing a ConnectorError

OAuthRefresh ⇐ GenericError

Class representing a ConnectorError

NoTriggerError ⇐ GenericError

Class representing a ConnectorError

Functions

mustachedDDL(object, text, value, isInteger)

Takes value paths as mustached values and returns correct DDL outputs. A custom flag is in place to allow for keeping integer types for the value key if required, as mustaching will convert an integer to string.

DDL(object, textPath, valuePath)

Takes value paths as explicit strings and returns correct DDL outputs.

deepMapKeys(collection, iteratee)

Maps object keys and formats according to specified casing.

userInputErrorRejection(message, body)

Return a User Input Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

connectorErrorRejection(message, body)

Return a Connector Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

apiErrorRejection(message, body)

Return a API Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

oauthErrorRejection(message, body)

Return a oAuth Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

noTriggerErrorRejection(message, body)

Return a No Trigger Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

lookup(message, [step_settings])

Generates a lookup object for DDL operations.

removeEmptyObjects(collection)

Recursively removes empty objects, arrays and strings from a collection. It's important to note that this method will remove objects if they become empty as a result of the nested key/value containing an empty object (the same goes for arrays).

validatePaginationRange(value, validation)

Helper for validating user pagination input for a given range.

generateInputSchema({ schema, keys, operation = 'schema' })

Helper for generating an operation input schema.

formatArray(arrayToFormat)

Helper to take an array of strings and return a comma-delimited string. Alias of formatArrayToDelimitedList({ arrayToFormat, delimiter: ',' })

formatArrayToDelimitedList({ arrayToFormat, [delimiter] })

Helper to take an array of strings and return a string that is a list, delimited by the specified delimiter (',' by default).

GenericError ⇐ Error

Class representing the base error for all connector errors

Kind: global class
Extends: Error

UserInputError ⇐ GenericError

Class representing a UserInputError

Kind: global class
Extends: GenericError

new UserInputError(message, ...errorArgs)

Custom error to throw for issues concerning User Input.

Param	Type	Description
message	String	Custom error message to return.
...errorArgs	any	Error args allowing for extra parameters native to the normal Error class.

ConnectorError ⇐ GenericError

Class representing a ConnectorError

Kind: global class
Extends: GenericError

new ConnectorError(message, ...errorArgs)

Custom error to throw for issues concerning the Connector.

Param	Type	Description
message	String	Custom error message to return.
...errorArgs	any	Error args allowing for extra parameters native to the normal Error class.

ApiError ⇐ GenericError

Class representing a ConnectorError

Kind: global class
Extends: GenericError

new ApiError(message, ...errorArgs)

Custom error to throw for issues concerning the Api;;.

Param	Type	Description
message	String	Custom error message to return.
...errorArgs	any	Error args allowing for extra parameters native to the normal Error class.

OAuthRefresh ⇐ GenericError

Class representing a ConnectorError

Kind: global class
Extends: GenericError

new OAuthRefresh(message, ...errorArgs)

Custom error to throw when an oAuth token has expired.

Param	Type	Description
message	String	Custom error message to return.
...errorArgs	any	Error args allowing for extra parameters native to the normal Error class.

NoTriggerError ⇐ GenericError

Class representing a ConnectorError

Kind: global class
Extends: GenericError

new NoTriggerError(message, ...errorArgs)

Custom error to throw for issues when a trigger request is ignored.

Param	Type	Description
message	String	Custom error message to return.
...errorArgs	any	Error args allowing for extra parameters native to the normal Error class.

mustachedDDL(arr, text, value, isInteger)

Takes value paths as mustached values and returns correct DDL outputs. A custom flag is in place to allow for keeping integer types for the value key if required, as mustaching will convert an integer to string. If there does not exist a path, the whole result will not return.

Kind: global function

Param	Type	Description
arr	Object	An array of objects with keys to iterate over and format.
text	String	The path for the required text value.
value	String	The path for the required value, value.
isInteger	Boolean	Flag for whether or not the value field needs to an integer rather than a string.

DDL(arr, textPath, valuePath, options)

Takes value paths as explicit strings and returns correct DDL outputs. If a text value does not exist, the DDL falls back to using the 'value' path.

Kind: global function

Param	Type	Description
arr	Object	An array of objects with keys to iterate over and format.
textPath	String	The path for the required text value.
valuePath	String	The path fot the required value, value.
options	String	Options to provide to the DDL

deepMapKeys(collection, iteratee)

Maps object keys and formats according to specified casing.

Kind: global function

Param	Type	Description
collection	Object	The collection with keys to iterate over and format.
iteratee	function	The format function used to format keys IE Lodash _.camelCase('some_string').

userInputErrorRejection(message, body)

Return a User Input Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

Kind: global function

Param	Type	Description
message	String	The error message to be returned.
body	any	Custom body to be returned when providing more error context.

connectorErrorRejection(message, body)

Return a Connector Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

Kind: global function

Param	Type	Description
message	String	The error message to be returned.
body	any	Custom body to be returned when providing more error context.

apiErrorRejection(message, body)

Return a API Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

Kind: global function

Param	Type	Description
message	String	The error message to be returned.
body	any	Custom body to be returned when providing more error context.

oauthErrorRejection(message, body)

Return a oAuth Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

Kind: global function

Param	Type	Description
message	String	The error message to be returned.
body	any	Custom body to be returned when providing more error context.

noTriggerErrorRejection(message, body)

Return a No Trigger Error with option to pass a body argument. The use case for this over the custom Error class is to pass a body to provide error context.

Kind: global function

Param	Type	Description
message	String	The error message to be returned.
body	any	Custom body to be returned when providing more error context.

lookup(message, [step_settings])

Generates a lookup object for DDL operations.

Kind: global function

Param	Type	Default	Description
message	String		The DDL operation that is run when the lookup is executed.
[step_settings]	Object	{}	The custom step settings for the lookup.

removeEmptyObjects(collection)

Recursively removes empty objects, arrays and strings from a collection. It's important to note that this method will remove objects if they become empty as a result of the nested key/value containing an empty object (the same goes for arrays).

Kind: global function

Param	Type	Description
collection	Object	The collection from which to remove empty objects.

removeAuthKeys(collection, additionalKeys)

Removes top levels '#' keys and additional top level keys if supplied.

Kind: global function

Param	Type	Description
collection	Object	The collection to remove '#' keys and additional given keys from.
additionalKeys	Array	An array of additional key names (strings) to remove.

validatePaginationRange(value, validation)

Helper for validating user pagination input for a given range.

Kind: global function

Param	Type	Description
value	Integer | String	The value specified by user input.
validation	Object	Values relating specifically to the validation requirements.
validation.minRange	Integer | String	The minimum range specified by the API.
validation.maxRange	Integer | String	The maximum range specified by the API.
validation.inputName	String	The name of the input the range is associated with.

generateInputSchema({ schema, keys, operation = 'schema' })

Helper for generating an operation input schema.

Will log to the console if:

• a requested key does not exist, or
• type or description keys are missing

Will not log to the console if requested key does not exist, but is overridden with at least a type and description.

• @param {Object} schema The full connector schema definition.
• @param {Object} keys The keys that you wish to extract from the schema with any override values.
• @param {String} operation The name of the connector operation that you are generating the schema for.
• This will be used as the root of the object path when logging validation issues.
• @return {object} A copy of the requested schema elements. */

Kind: global function

Param	Type	Description
schema	Object	The full connector schema definition.
keys	Object	The keys that you wish to extract from the schema with any override values.
operation	String	The name of the connector operation that you are generating the schema for.

For more information on how to use the schema generator, please see schema-generation.md.

Example

generateInputSchema({
	operation: 'operationName',
	schema: fullSchema,
	keys: {
		full_schema_key_1: {},
		full_schema_key_2: {},
		full_schema_key_3: {},
	},
});
/**
 *	`fullSchema` is the complete schema definition for the connector
 *	`full_schema_key_1` is extracted from the full schema without modification
 *	`full_schema_key_2` is extracted from the full schema without modification
 *	`full_schema_key_3` is extracted from the full schema without modification
 */

generateInputSchema({
	operation: 'operationName',
	schema: fullSchema,
	keys: {
		full_schema_key_1: {},
		full_schema_key_2: {
			required: true,
			description: 'Override key values.',
			default: 'value',
		},
		new_key: {
			type: 'string',
			description: 'New date key, not in full schema.',
			format: 'datetime',
			date_mask: 'X',
		},
	},
});
/**
 *	`fullSchema` is the complete schema definition for the connector
 *	`full_schema_key_1` is extracted from the full schema without modification
 *	`full_schema_key_2` is extracted from the full schema and extended/overridden with extra keys and values
 *	`new_key` is not in the full schema but it's full keys and values are supplied
 */

formatArrayToDelimitedList({ arrayToFormat, [delimiter] })

Helper that takes an array and returns a string that is a delimited list of the given array.

Alternatively, you can instead use formatArray(arrayToFormat), which is an alias of formatArrayToDelimitedList({ arrayToFormat }) and simply uses the default delimiter (,).

Using formatArrayToDelimitedList({ arrayToFormat, [delimiter] }) will allow you to specify an alternative delimiter.

The envisioned use-case is in an operation model to format user array input into a delimited string to assign to a parameter. If it was an optional input and not supplied then the parameter should be undefined. This is reflected by the function returning undefined if it does not receive an array.

Kind: global function

Param	Type	Default	Description
arrayToFormat	Array		Usually an array of Strings, or else equivalent string representations are used.
[delimiter]	String	,	A string that will be used to separate the values.

Example:

const inputArray = [1, 2, 'third', 'fourth'];

formatArrayToDelimitedList({ arrayToFormat: inputArray });

// returns '1,2,third,fourth'

formatArrayToDelimitedList({ arrayToFormat: undefined });

// returns undefined