@trayio/connector-utils v0.4.6

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.

ConnectorError ⇐ GenericError

Class representing a ConnectorError

Kind: global class Extends: GenericError

new ConnectorError(message, ...errorArgs)

Custom error to throw for issues concerning the Connector.

ApiError ⇐ GenericError

Class representing a ConnectorError

Kind: global class Extends: GenericError

new ApiError(message, ...errorArgs)

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

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.

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.

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

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

deepMapKeys(collection, iteratee)

Maps object keys and formats according to specified casing.

Kind: global function

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

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

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

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

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

lookup(message, step_settings)

Generates a lookup object for DDL operations.

Kind: global function

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

removeAuthKeys(collection, additionalKeys)

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

Kind: global function

validatePaginationRange(value, validation)

Helper for validating user pagination input for a given range.

Kind: global function

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

Helper for generating an operation input schema.

Kind: global function

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

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

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

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

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'