Skip to content

Common utility functions used in connectors

License

Notifications You must be signed in to change notification settings

trayio/connector-utils

Repository files navigation

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

GenericErrorError

Class representing the base error for all connector errors

UserInputErrorGenericError

Class representing a UserInputError

ConnectorErrorGenericError

Class representing a ConnectorError

ApiErrorGenericError

Class representing a ApiError

OAuthRefreshGenericError

Class representing a OAuthRefresh

NoTriggerErrorGenericError

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'