Add coerceArray method (#40)

* Add coerceArray method

* Add tests

* Cleanup unused import

* Update docs

* Fix typo

docs/API.md

@@ -4,6 +4,8 @@
 
 -   [coerce][1]
     -   [Parameters][2]
+-   [coerceArray][3]
+    -   [Parameters][4]
 
 ## coerce
 
@@ -13,17 +15,39 @@ Validate an object is an instance of the expected type, or is a valid constructo
 
 -   `value` **any** The value for validation
 -   `Type` **any** The type for instance of comparison
--   `message` **[string][3]** The message to be displayed if coercion fails
+-   `message` **[string][5]** The message to be displayed if coercion fails
 
 
--   Throws **[TypeError][4]** If the value is not coercable.
+-   Throws **[TypeError][6]** If the value is not coercable.
 
 Returns **any** Instance of provided Type
 
+## coerceArray
+
+Validate an array of objects are an instance of the expected type, or are a valid constructor object for the requested type
+
+### Parameters
+
+-   `values` **[Array][7]<any>** The array of values for validation
+-   `Type` **any** The type for instance of comparison
+-   `message` **[string][5]** The message to be displayed if coercion fails
+
+
+-   Throws **[TypeError][6]** If values is not an array
+-   Throws **[TypeError][6]** One of the array values is not coercable.
+
+Returns **[Array][7]<any>** Array of instances of provided Type
+
 [1]: #coerce
 
 [2]: #parameters
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[3]: #coercearray
+
+[4]: #parameters-1
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError
 
-[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

package.json

@@ -9,7 +9,8 @@
     "docs": "documentation build src/index.js -f md > docs/API.md",
     "postversion": "git push --follow-tags",
     "pretest": "npm outdated && npm audit && eslint src/",
-    "test": "jest /src"
+    "test": "jest /src",
+    "test:live": "jest /src --watch"
   },
   "repository": {
     "type": "git",

src/index.js

@@ -6,7 +6,7 @@
  * @returns {*} - Instance of provided Type
  * @throws {TypeError} - If the value is not coercable.
  */
-export default function coerce (value, Type, message) {
+export function coerce (value, Type, message) {
     if (value instanceof Type) {
         return value;
     }
@@ -17,4 +17,22 @@ export default function coerce (value, Type, message) {
     catch (error) {
         throw new TypeError(`${message} Inner Error: ${error.message}`);
     }
+}
+export default coerce;
+
+/**
+ * Validate an array of objects are an instance of the expected type, or are a valid constructor object for the requested type
+ * @param {Array<*>} values - The array of values for validation
+ * @param {*} Type - The type for instance of comparison
+ * @param {string} message - The message to be displayed if coercion fails
+ * @returns {Array<*>} - Array of instances of provided Type
+ * @throws {TypeError} - If values is not an array
+ * @throws {TypeError} - One of the array values is not coercable.
+ */
+export function coerceArray (values, Type, message) {
+    if(!Array.isArray(values)) {
+        throw new TypeError(`values must be an Array. Provided value: ${values}`);
+    }
+
+    return values.map(value => coerce(value, Type, message));
 }

src/index.spec.js

@@ -1,4 +1,4 @@
-import coerce from './index';
+import { coerce, coerceArray } from './index';
 
 const ERROR_MESSAGE = 'You failing the hardest';
 class FakeClassForTesting {}
@@ -37,4 +37,38 @@ describe('coerce', () => {
         const errorMessageRegex = new RegExp(`${errorMessage}.*${ERROR_MESSAGE}`);
         expect(() => coerce({}, FailingClassForTesting, errorMessage)).toThrowError(errorMessageRegex);
     });
+});
+
+describe('coerceArray', () => {
+    it('should be a function', () => {
+        expect(coerceArray).toEqual(jasmine.any(Function));
+    });
+
+    it('should throw if values is not an array', () => {
+        expect(() => coerceArray({}, FakeClassForTesting, 'Yay!')).toThrowError(/Array/);
+    });
+
+    it('should coerce every value in the array', () => {
+        const values = [
+            { hooray: 'yes'},
+            { oh: 'no'},
+            { OHHH: 'YEAHHH!!'}
+        ];
+
+        const result = coerceArray(values, FakeClassForTesting, 'Yay!');
+
+        expect(result).toEqual(jasmine.arrayContaining([
+            jasmine.any(FakeClassForTesting),
+            jasmine.any(FakeClassForTesting),
+            jasmine.any(FakeClassForTesting)
+        ]));
+    });
+
+    it('should throw if coercion fails', () => {
+        const values = [
+            { hooray: 'yes'}
+        ];
+
+        expect(() => coerceArray(values, FailingClassForTesting, 'Yay!')).toThrow();
+    });
 });