feat: Separate vest.create from its result function by making validat…

…e accept arguments (#151)
ealush · May 23, 2020 · c4e827c · c4e827c
1 parent 4839ac8
commit c4e827c
Show file tree

Hide file tree

Showing 13 changed files with 143 additions and 127 deletions.
diff --git a/README.md b/README.md
@@ -22,30 +22,26 @@ The idea behind Vest is that your validations can be described as a 'spec' or a
 // validation.js
 import vest, { test, enforce } from 'vest';
 
-const validation = data => {
-  const validate = vest.create('NewUserForm', () => {
-    test('username', 'Must be at least 3 chars', () => {
-      enforce(data.username).longerThanOrEquals(3);
-    });
-
-    test('email', 'Is not a valid email address', () => {
-      enforce(data.email)
-        .isNotEmpty()
-        .matches(/[^@]+@[^\.]+\..+/g);
-    });
+const validate = vest.create('NewUserForm', data => {
+  test('username', 'Must be at least 3 chars', () => {
+    enforce(data.username).longerThanOrEquals(3);
   });
 
-  return validate();
-};
+  test('email', 'Is not a valid email address', () => {
+    enforce(data.email)
+      .isNotEmpty()
+      .matches(/[^@]+@[^\.]+\..+/g);
+  });
+});
 
-export default validation;
+export default validate;
 ```
 
 ```js
 // myFeature.js
-import validation from './validation.js';
+import validate from './validation.js';
 
-const res = validation({
+const res = validate({
   username: 'example',
   email: 'email@example.com',
 });

diff --git a/docs/README.md b/docs/README.md
@@ -21,30 +21,26 @@ The idea behind Vest is that your validations can be described as a 'spec' or a
 // validation.js
 import vest, { test, enforce } from 'vest';
 
-const validation = data => {
-  const validate = vest.create('NewUserForm', () => {
-    test('username', 'Must be at least 3 chars', () => {
-      enforce(data.username).longerThanOrEquals(3);
-    });
-
-    test('email', 'Is not a valid email address', () => {
-      enforce(data.email)
-        .isNotEmpty()
-        .matches(/[^@]+@[^\.]+\..+/g);
-    });
+const validate = vest.create('NewUserForm', data => {
+  test('username', 'Must be at least 3 chars', () => {
+    enforce(data.username).longerThanOrEquals(3);
   });
 
-  return validate();
-};
+  test('email', 'Is not a valid email address', () => {
+    enforce(data.email)
+      .isNotEmpty()
+      .matches(/[^@]+@[^\.]+\..+/g);
+  });
+});
 
-export default validation;
+export default validate;
 ```
 
 ```js
 // myFeature.js
-import validation from './validation.js';
+import validate from './validation.js';
 
-const res = validation({
+const res = validate({
   username: 'example',
   email: 'email@example.com',
 });

diff --git a/docs/exclusion.md b/docs/exclusion.md
@@ -17,23 +17,21 @@ In the example below, we're assuming the argument `fieldName` is being populated
 ```js
 import vest, { enforce, test } from 'vest';
 
-const myValidation = (data, fieldName) => {
-  const validate = vest.create('New User', () => {
-    vest.only(fieldName);
-
-    test('username', 'Username is invalid', () => {
-      /* some validation logic*/
-    });
-    test('email', 'Email is invalid', () => {
-      /* some validation logic*/
-    });
-    test('password', 'Password is invalid', () => {
-      /* some validation logic*/
-    });
+const validate = vest.create('New User', (data, fieldName) => {
+  vest.only(fieldName);
+
+  test('username', 'Username is invalid', () => {
+    /* some validation logic*/
+  });
+  test('email', 'Email is invalid', () => {
+    /* some validation logic*/
+  });
+  test('password', 'Password is invalid', () => {
+    /* some validation logic*/
   });
+});
 
-  return validate();
-};
+const validationResult = validate(formData, changedField);
 ```
 
 ### Skipping tests
@@ -45,20 +43,18 @@ In this case, and in similar others, you can use `vest.skip()`. When called, it
 ```js
 import vest, { enforce, test } from 'vest';
 
-const myValidation = data => {
-  const validate = vest.create('purchase', () => {
-    if (!data.promo) {
-      vest.skip('promo');
-    }
+const validate = vest.create('purchase', data => {
+  if (!data.promo) {
+    vest.skip('promo');
+  }
 
-    // this test won't run when data.promo is falsy.
-    test('promo', 'Promo code is invalid', () => {
-      /* some validation logic*/
-    });
+  // this test won't run when data.promo is falsy.
+  test('promo', 'Promo code is invalid', () => {
+    /* some validation logic*/
   });
+});
 
-  return validate();
-};
+const validationResult = validate(formData);
 ```
 
 **Read next about:**

diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -24,41 +24,50 @@ First, you need to initialize your validation suite using `vest.create()`. This
 ```js
 import vest from 'vest';
 
-const validation = data => {
-  const validate = vest.create('formName', () => {
-    // validation suite content goes here.
-  });
+const validate = vest.create('formName', () => {
+  // validation suite content goes here.
+});
 
-  return validate();
-};
+const validationResult = validate();
 ```
 
 `vest.create()` takes the following arguments:
 
-- `name`: The name of the current validation suite. _Must be unique_.
-- `callback`: The validation suite's body where your tests reside.
+| Name     | Type       | Optional | Description                                                    |
+| -------- | ---------- | -------- | -------------------------------------------------------------- |
+| `name`   | `string`   | No       | Suite name. _Must be unique_.                                  |
+| callback | `function` | No       | Your validation suite's body. This is where your tests reside. |
+
+vest.create returns a `validate` function which runs your validation suite. All the arguments you pass to it are being forwared to your tests callback. You can use it to pass form data to your validation, excluded fields, and anything required for during your validation runtime.
 
 A simple validation suite would look somewhat like this:
 
 ```js
+// validation.js
 import { test, enforce } from ‘vest’;
 
-export default (data) => {
-  const validate = vest.create('NewUserForm', () => {
+const validate = vest.create('NewUserForm', (formData) => {
     test('username', 'Must be between 2 and 10 chars', () => {
-        enforce(data.username)
+        enforce(formData.username)
             .longerThanOrEquals(2)
             .shorterThan(10);
     });
 
     test('password', 'Must contain at least one digit', () => {
-        enforce(data.password)
+        enforce(formData.password)
             .matches(/(?=.*[0-9])/);
     });
-  });
+});
+
+export default validate;
+```
+
+```js
+// myFeature.js
+
+import validate from './validation.js';
 
-  return validate();
-};
+const res = validate(formData);
 ```
 
 In the above example, we validate a form called `NewUserForm` containing username and a password.

diff --git a/docs/result.md b/docs/result.md
@@ -92,21 +92,21 @@ In the below example, the `done` callback for `UserName` may run before the whol
 ```js
 import vest, { test, enforce } from 'vest';
 
-const validate = vest.create('SendEmailForm', () => {
+const validate = vest.create('SendEmailForm', data => {
   test(
     'UserEmail',
     'Marked as spam address',
-    async () => await isKnownSpammer(address)
+    async () => await isKnownSpammer(data.address)
   );
 
   test(
     'UserName',
     'must not be blacklisted',
-    async () => await isBlacklistedUser(username)
+    async () => await isBlacklistedUser(data.username)
   );
 });
 
-validate()
+const validationResult = validate(data)
   .done('UserName', res => {
     if (res.hasErrors('UserName')) {
       showUserNameErrors(res.errors);

diff --git a/docs/state.md b/docs/state.md
@@ -41,7 +41,7 @@ In some cases, such as form reset, you want to discard of previous validation re
 import vest from 'vest';
 
 const validate = vest.create('suite_name', () => {
-  // your tests here
+  // Your tests go here
 });
 
 validate(); // validation result is added to the state.

diff --git a/docs/warn.md b/docs/warn.md
@@ -7,27 +7,29 @@ To set a test's severity level to `warn`, you need to simply call Vest's warn fu
 ```js
 import vest, { test, enfroce } from 'vest';
 
-const validate = vest.create('Password', () => {
+const validate = vest.create('Password', data => {
   test('password', 'A password must have at least 6 characters', () => {
-    enforce(password).longerThan(5);
+    enforce(data.password).longerThan(5);
   }); // this test has a severity level of `error`
 
   test('password', 'Your password strength is: WEAK', () => {
     vest.warn();
 
-    enforce(password).matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]$/);
+    enforce(data.password).matches(
+      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]$/
+    );
   }); // this test has a severity level of `warn`
 
   test('password', 'Your password strength is: MEDIUM', () => {
     vest.warn();
 
-    enforce(password).matches(
+    enforce(data.password).matches(
       /^(?=.*[A-Za-z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]$/
     );
   }); // this test has a severity level of `warn`
 });
 
-validate();
+const validationResult = validate(data);
 ```
 
 **Limitations when using vest.warn()**