Merge pull request #36 from trayio/release-CSP-2414-add-formatarrayto…

…delimitedlist-to-utils

Release branch: [CSP-2414] Add formatArrayToDelimitedList to utils

README.md

@@ -110,6 +110,12 @@ for arrays).</p>
 <dt><a href="#generateInputSchema">generateInputSchema({ schema, keys, operation = 'schema' })</a></dt>
 <dd><p>Helper for generating an operation input schema.</p>
 </dd>
+<dt><a href="#formatArrayToDelimitedList">formatArray(arrayToFormat)</a></dt>
+<dd><p>Helper to take an array of strings and return a comma-delimited string. Alias of <code><a href="#formatArrayToDelimitedList">formatArrayToDelimitedList({ arrayToFormat, delimiter: ',' })</a></code></p>
+</dd>
+<dt><a href="#formatArrayToDelimitedList">formatArrayToDelimitedList({ arrayToFormat, [delimiter] })</a></dt>
+<dd><p>Helper to take an array of strings and return a string that is a list, delimited by the specified delimiter ('<code>,</code>' by default).</p>
+</dd>
 </dl>
 
 <a name="GenericError"></a>
@@ -376,6 +382,8 @@ Helper for validating user pagination input for a given range.
 | validation.maxRange  | <code>Integer</code> \| <code>String</code> | The maximum range specified by the API.                      |
 | validation.inputName | <code>String</code>                         | The name of the input the range is associated with.          |
 
+<a name="generateInputSchema"></a>
+
 ## generateInputSchema({ schema, keys, operation = 'schema' })
 
 Helper for generating an operation input schema.
@@ -448,3 +456,39 @@ generateInputSchema({
  *	`new_key` is not in the full schema but it's full keys and values are supplied
  */
 ```
+
+<a name="formatArrayToDelimitedList"></a>
+
+## 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 | <code>Array</code>  |                | Usually an array of Strings, or else equivalent string representations are used. |
+| [delimiter]   | <code>String</code> | <code>,</code> | A string that will be used to separate the values.                               |
+
+**Example**:
+
+```js
+const inputArray = [1, 2, 'third', 'fourth'];
+
+formatArrayToDelimitedList({ arrayToFormat: inputArray });
+
+// returns '1,2,third,fourth'
+```
+
+```js
+
+formatArrayToDelimitedList({ arrayToFormat: undefined });
+
+// returns undefined
+```

lib/formatters.js

@@ -0,0 +1,35 @@
+const { UserInputError } = require('./errors');
+
+const setErrorMessage = input =>
+	`Expected an array but instead received input of type '${typeof input}'.`;
+
+/**
+ * Given an array of strings, returns it as a string delimited by a delimiter.
+ *
+ * @param {Array} arrayToFormat An array of strings.
+ * @param {String} [delimiter=','] The string that will separate the values
+ * @return {String} Delimited string.
+ */
+
+const formatArrayToDelimitedList = ({ arrayToFormat, delimiter = ',' }) => {
+	if (arrayToFormat) {
+		if (Array.isArray(arrayToFormat)) {
+			return arrayToFormat.join(delimiter);
+		}
+		throw new UserInputError(setErrorMessage(arrayToFormat));
+	}
+
+	return undefined;
+};
+
+/**
+ * Given an array of strings, returns it as a comma-delimited string.
+ *
+ * @param {Array} arrayToFormat An array of strings.
+ * @return {String} Delimited string.
+ */
+
+const formatArray = arrayToFormat =>
+	formatArrayToDelimitedList({ arrayToFormat });
+
+module.exports = { formatArrayToDelimitedList, formatArray };

lib/index.js

@@ -4,6 +4,7 @@ const removeEmptyObjects = require('./removeEmptyObjects');
 const lookup = require('./lookup');
 const validatePaginationRange = require('./validatePaginationRange');
 const generateInputSchema = require('./generateInputSchema');
+const formatters = require('./formatters');
 // const xmlFormatter = require('./xmlFormatter');
 const { mustachedDDL, DDL } = require('./ddl');
 const {
@@ -61,13 +62,16 @@ module.exports = {
 			return DDL(object, textPath, valuePath);
 		},
 	},
+
 	deepMapKeys,
 	removeEmptyObjects,
 	lookup,
 	mustachedDDL,
 	DDL,
 	validatePaginationRange,
 	generateInputSchema,
+	formatters,
+
 	// Commenting for initial release pending functionality to add paths to treatAsArray
 	// xml: {
 	// 	xmlFormatter,

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@trayio/connector-utils",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"description": "Common utility functions used in connectors.",
 	"main": "lib/index.js",
 	"scripts": {

tests/methods/formatters.test.js

@@ -0,0 +1,65 @@
+const { UserInputError } = require('../../lib/errors');
+const {
+	formatArray,
+	formatArrayToDelimitedList,
+} = require('../../lib/index').formatters;
+
+describe('Array should be correctly formatted as a delimited list', () => {
+	describe('formatArray', () => {
+		it('should return a comma delimited list, given an array of strings', () => {
+			const arrayOfStrings = [1, 2, 'third', 'fourth'];
+			expect(formatArray(arrayOfStrings)).toEqual('1,2,third,fourth');
+		});
+
+		it('should return "undefined" if argument is undefined', () => {
+			expect(formatArray(undefined)).toBeUndefined();
+		});
+
+		it('should throw error if input exists but is not an array', () => {
+			const notArray = 'not an array';
+
+			expect(() => formatArray(notArray)).toThrow(
+				new UserInputError(
+					"Expected an array but instead received input of type 'string'.",
+				),
+			);
+		});
+	});
+
+	describe('formatArrayToDelimitedList', () => {
+		it('should return a comma delimited list, given an array of strings', () => {
+			const arrayOfStrings = [1, 2, 'third', 'fourth'];
+			expect(
+				formatArrayToDelimitedList({ arrayToFormat: arrayOfStrings }),
+			).toEqual('1,2,third,fourth');
+		});
+
+		it('should return a list delimited by the specified delimiter "//", given an array of strings', () => {
+			const arrayOfStrings = [1, 2, 'third', 'fourth'];
+			expect(
+				formatArrayToDelimitedList({
+					arrayToFormat: arrayOfStrings,
+					delimiter: '//',
+				}),
+			).toEqual('1//2//third//fourth');
+		});
+
+		it('should return "undefined" if value of "arrayToFormat" is undefined', () => {
+			expect(
+				formatArrayToDelimitedList({ arrayToFormat: undefined }),
+			).toBeUndefined();
+		});
+
+		it('should throw error if input exists but is not an array', () => {
+			const notArray = {};
+
+			expect(() =>
+				formatArrayToDelimitedList({ arrayToFormat: notArray }),
+			).toThrow(
+				new UserInputError(
+					"Expected an array but instead received input of type 'object'.",
+				),
+			);
+		});
+	});
+});