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.

Deploying

Once a PR is merged into master, you will need to go into GitHub Actions UI and trigger the NPM Publish workflow manually providing the input of major, minor or patch depending on what version bump you want to publish - this will automatically build, tag, and publish the new version.

Once the pipeline is done, a github tag will appear with the new version number. You will need to merge in the automatically generated pull request which bumps the package version. You can then use this tag to create a Github release with some release notes.

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 ApiError

OAuthRefresh ⇐ GenericError

Class representing a OAuthRefresh

NoTriggerError ⇐ GenericError

Class representing a NoTriggerError

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).

removeAuthKeys(collection, additionalKeys)

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

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).

generateAllTypes({ exclude = '' })

Helper for generating all available JSON schema types.

convertCustomFieldsArrToObj({ customFields, key, value, keyCase = 'camel', })

Helper to convert an array into an object of key and values pairs.

prettyTitle(name)

Create a user friendly text value.

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', arrayMergeType = 'concatenate' })

Helper for generating an operation input schema.

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. This will be used as the root of the object path when logging validation issues. Optional.
arrayMergeType	String	The type of merging algorithm to be used for arrays. Possible algorithms are concatenate (default), combineByIndex, overwriteByIndex or overwrite. Optional.
returns	Object	A copy of the requested schema elements.

Array merge types:

• concatenate - merge arrays by concatenating values (default)
• combineByIndex - merge/combine arrays by index value
  • arrays of objects will merge by index (if possible)
  • other types will concatenate (ignoring value duplication overlap)
• overwriteByIndex - merge/overwrite arrays by index value
  • arrays of objects will merge by index (if possible)
  • other types will overwrite by index value
• overwrite - overwrite original array with specified array

Will log to the console if:

• a requested key does not exist, or
• type or description keys are missing, or
• a description does not end with valid punctuation

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

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: {},
	},
	arrayMergeType: 'concatenate',
});
/**
 *	`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',
			alias: 'key_2',
		},
		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. The key name will be changed to `key_2' by use of an alias.
 *	`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

generateAllTypes({ exclude = '' })

Helper for generating all available JSON schema types. You may use the "exclude" parameter to exclude any unwanted type.

Kind: global function

Param	Type	Default	Description
exclude	String	''	String of types separated by comma to be excluded.

Example:

generateAllTypes();

// returns ['string','number','object','array','boolean','null']

generateAllTypes({ exclude: 'null, boolean' });

// returns ['string','number','object','array']

convertCustomFieldsArrToObj({customFields, key, value, keyCase = 'camel' })

Helper to convert an array into an object of key and values.

Kind: global function

Param	Type	Default	Description
customFields	Object		Array of objects that demonstrate key value pairs.
key	String		The name of the key e.g. field_name.
value	String		The value of the key e.g. field_value.
keyCase	String	'camel'	Key case formatter. Options are: camel (Default), snake, and any other value for custom cases (Recommended value: custom) Optional.
returns	Object		An object with key value pairs.

Example:

const customFields = [
	{
		field_name: 'some key',
		field_value: 'some value',
	},
	{
		field_name: 'helloWorld',
		field_value: 'hello world',
	},
	{
		field_name: 'foo_bar',
		field_value: 'foo bar',
	},
];

convertCustomFieldsArrToObj({
	customFields,
	key: 'field_name',
	value: 'field_value',
});

// returns { someKey: 'some value', helloWorld: 'hello world', fooBar: 'foo bar' }

convertCustomFieldsArrToObj({
	customFields,
	key: 'field_name',
	value: 'field_value',
	keyCase: 'snake',
});

// returns { some_key: 'some value', hello_world: 'hello world', foo_bar: 'foo bar' }

prettyTitle(name)

Create a user-friendly text value.

Kind: global function

Param	Type	Description
name	String	A text value.

Example:

prettyTitle('list-name');

// returns 'List name'

prettyTitle('list_name');

// returns 'List name'

prettyTitle('list_id_name');

//returns 'List ID name'

prettyTitle('list_url_name');

// returns 'List URL name'