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

Functions

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'