docs: Update documentation (#378)

ealush · Sep 8, 2020 · ca7bcf0 · ca7bcf0
1 parent dca5b3b
commit ca7bcf0
Show file tree

Hide file tree

Showing 6 changed files with 171 additions and 78 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -31,12 +31,12 @@ packages/
 │   ├── src/    # Vest's prebuilt source code.
 │   │   └── core/  # Modules required for vest's functionality.
 │   │   │   └── Context/     # Vest's shared runtime. Used across the whole library.
-│   │   │   └── createSuite/ # Initializes the suite and creates a context and state.
 │   │   │   └── produce/     # Generates the out put object and callbaks.
 │   │   │   └── state/       # Vest's persistent state. Used across the whole library.
-│   │   │   └── suiteResult/ # The output object is generated here.
 │   │   │   └── test/        # Contains the test function and its lifecycle.
-│   │   │   └── validate/    # Creates and runs a stateless suite.
+│   │   │   └── suite/       # Contains all the suite modules and methods
+│   │   │       └── create/      # Initializes the suite and creates a context and state.
+│   │   │       └── validate/    # Creates and runs a stateless suite.
 │   │   └── hooks/ # Functions that extend vest's functionality. They all use Context.
 │   │   │   └── draft/       # Allows access to the intermediate test result.
 │   │   │   └── exclusive/   # Allows including or excluding fields in runtime.
@@ -45,6 +45,12 @@ packages/
 │   │   │   └── group/       # Adds another nesting level within suites.
 │   │   └── lib/  # Shared helper functions.
 │   │   └── testUtils/    # Test helper functions.
+│   │   └── typings/      # Contains typescript declaration files for the exported modules.
+│   │   └── utilities/    # Single file exported modules.
+│   │       └── any/
+│   │       └── enforceExtended/
+│   │       └── classNames/
+│   │       └── promisify/
 ├── eslint-plugin-vest/   # Eslint plugin with vest specific rules
 │   ├── lib/    # Contains all rules
 ├── n4s/   # Assertion library used by vest

diff --git a/packages/n4s/docs/custom.md b/packages/n4s/docs/custom.md
@@ -1,36 +1,54 @@
 # Custom enforce rules
 
-To make it easier to reuse validations across your application, sometimes you would want to encapsulate bits of logic in rules that you can use later on, for example, "what's considered a valid email".
+To make it easier to reuse logic across your application, sometimes you would want to encapsulate bits of logic in rules that you can use later on, for example, "what's considered a valid email".
 
-Your custom rules are essentially a single javascript object containing your rules.
+Rules are called with the argument passed to enforce(x) followed by the arguments passed to `.yourRule(y, z)`.
 
 ```js
-const myCustomRules = {
-  isValidEmail: value => value.indexOf('@') > -1,
-  hasKey: (value, { key }) => value.hasOwnProperty(key),
-  passwordsMatch: (passConfirm, options) =>
-    passConfirm === options.passConfirm && options.passIsValid,
-};
+enforce.extend({
+  yourRule(x, y, z) {
+    return {
+      pass: true,
+      message: () => '',
+    };
+  },
+});
 ```
 
-Just like the predefined rules, your custom rules can accepts two parameters:
-
-- `value` The actual value you are testing against.
-- `args` (optional) the arguments which you pass on when running your tests.
-
-You can extend enforce with your custom rules by creating a new instance of `Enforce` and adding the rules object as the argument.
-
 ```js
-import enforce from 'n4s';
+import { enforce } from 'n4s';
 
-const myCustomRules = {
+enforce.extend({
   isValidEmail: value => value.indexOf('@') > -1,
   hasKey: (value, key) => value.hasOwnProperty(key),
   passwordsMatch: (passConfirm, options) =>
     passConfirm === options.passConfirm && options.passIsValid,
-};
-
-enforce.extend(myCustomRules);
+});
 
 enforce(user.email).isValidEmail();
 ```
+
+## Custom rules return value
+
+Rules can either return boolean indicating success or failure, or an object with two keys. `pass` indicates whether the validation is successful or not, and message provides a function with no arguments that return an error message in case of failure. Thus, when pass is false, message should return the error message for when enforce(x).yourRule() fails.
+
+```js
+enforce.extend({
+  isWithinRange(received, floor, ceiling) {
+    const pass = received >= floor && received <= ceiling;
+    if (pass) {
+      return {
+        message: () =>
+          `expected ${received} not to be within range ${floor} - ${ceiling}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () =>
+          `expected ${received} to be within range ${floor} - ${ceiling}`,
+        pass: false,
+      };
+    }
+  },
+});
+```
diff --git a/packages/vest/docs/enforce.md b/packages/vest/docs/enforce.md
@@ -1,26 +1,25 @@
 # Enforce
+
 For assertions, Vest is bundled with [Enforce](https://npmjs.com/package/n4s). Enforce is a validation assertion library. It allows you to run your data against rules and conditions and test whether it passes your validations. It is intended for validation logic that gets repeated over and over again and should not be written manually. It comes with a wide variety of pre-built rules, but it can also be extended to support your own repeated custom logic.
 
 The way Enforce operates is similar to most common assertion libraries. You pass it a value, and one or more rules to test your value against - if the validation fails, it throws an Error, otherwise - it will move on to the next rule in the chain.
 
 ```js
-import { enforce } from 'vest'
+import { enforce } from 'vest';
 
-enforce(4)
-    .isNumber();
+enforce(4).isNumber();
 // passes
 
-enforce(4)
-    .isNumber()
-    .greaterThan(2);
+enforce(4).isNumber().greaterThan(2);
 // passes
 
 enforce(4)
-    .lessThan(2) // throws an error, will not carry on to the next rule
-    .greaterThan(3);
+  .lessThan(2) // throws an error, will not carry on to the next rule
+  .greaterThan(3);
 ```
 
 ## Content
+
 - [List of Enforce rules](#list-of-enforce-rules) - All default enforce rules
 - [Custom Enforce Rules](#custom-enforce-rules) - How to extend enforce with your rules
 - [Business Related Rules](#business-related-rules) - Using more rules such as isEmail and isCreditCard
@@ -996,38 +995,61 @@ enforce([0]).isEven();
 // throws
 ```
 
-
 # Custom enforce rules
+
 To make it easier to reuse logic across your application, sometimes you would want to encapsulate bits of logic in rules that you can use later on, for example, "what's considered a valid email".
 
-Your custom rules are essentially a single javascript object containing your rules.
+Rules are called with the argument passed to enforce(x) followed by the arguments passed to `.yourRule(y, z)`.
+
 ```js
-const myCustomRules = {
-    isValidEmail: (value) => value.indexOf('@') > -1,
-    hasKey: (value, {key}) => value.hasOwnProperty(key),
-    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
-}
+enforce.extend({
+  yourRule(x, y, z) {
+    return {
+      pass: true,
+      message: () => '',
+    };
+  },
+});
 ```
-Just like the predefined rules, your custom rules can accepts two parameters:
-* `value` The actual value you are testing against.
-* `args` (optional) the arguments which you pass on when running your tests.
-
-You can extend enforce with your custom rules by creating a new instance of `Enforce` and adding the rules object as the argument.
 
 ```js
 import { enforce } from 'vest';
 
-const myCustomRules = {
-    isValidEmail: (value) => value.indexOf('@') > -1,
-    hasKey: (value, key) => value.hasOwnProperty(key),
-    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
-}
-
-enforce.extend(myCustomRules);
+enforce.extend({
+  isValidEmail: value => value.indexOf('@') > -1,
+  hasKey: (value, key) => value.hasOwnProperty(key),
+  passwordsMatch: (passConfirm, options) =>
+    passConfirm === options.passConfirm && options.passIsValid,
+});
 
 enforce(user.email).isValidEmail();
 ```
 
+## Custom rules return value
+
+Rules can either return boolean indicating success or failure, or an object with two keys. `pass` indicates whether the validation is successful or not, and message provides a function with no arguments that return an error message in case of failure. Thus, when pass is false, message should return the error message for when enforce(x).yourRule() fails.
+
+```js
+enforce.extend({
+  isWithinRange(received, floor, ceiling) {
+    const pass = received >= floor && received <= ceiling;
+    if (pass) {
+      return {
+        message: () =>
+          `expected ${received} not to be within range ${floor} - ${ceiling}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () =>
+          `expected ${received} to be within range ${floor} - ${ceiling}`,
+        pass: false,
+      };
+    }
+  },
+});
+```
+
 # Business Related Rules
 
 Along with the existing rules, you might need different business related rules, for email, phone number, credit card validations, and more.
@@ -1073,6 +1095,7 @@ import enforce, {
 To read the full documentation on these rules and the options they take, please visit [validator.js](https://github.com/validatorjs/validator.js).
 
 ### validator.js license:
+
 ```
 Copyright (c) 2018 Chris O'Hara <cohara87@gmail.com>
 

diff --git a/packages/vest/docs/enforce.md.bak b/packages/vest/docs/enforce.md.bak
@@ -1,26 +1,25 @@
 # Enforce
+
 For assertions, Vest is bundled with [Enforce](https://npmjs.com/package/n4s). Enforce is a validation assertion library. It allows you to run your data against rules and conditions and test whether it passes your validations. It is intended for validation logic that gets repeated over and over again and should not be written manually. It comes with a wide variety of pre-built rules, but it can also be extended to support your own repeated custom logic.
 
 The way Enforce operates is similar to most common assertion libraries. You pass it a value, and one or more rules to test your value against - if the validation fails, it throws an Error, otherwise - it will move on to the next rule in the chain.
 
 ```js
-import { enforce } from 'vest'
+import { enforce } from 'vest';
 
-enforce(4)
-    .isNumber();
+enforce(4).isNumber();
 // passes
 
-enforce(4)
-    .isNumber()
-    .greaterThan(2);
+enforce(4).isNumber().greaterThan(2);
 // passes
 
 enforce(4)
-    .lessThan(2) // throws an error, will not carry on to the next rule
-    .greaterThan(3);
+  .lessThan(2) // throws an error, will not carry on to the next rule
+  .greaterThan(3);
 ```
 
 ## Content
+
 - [List of Enforce rules](#list-of-enforce-rules) - All default enforce rules
 - [Custom Enforce Rules](#custom-enforce-rules) - How to extend enforce with your rules
 - [Business Related Rules](#business-related-rules) - Using more rules such as isEmail and isCreditCard
@@ -30,36 +29,60 @@ Enforce exposes all predefined and custom rules. You may use chaining to make mu
 {{LIST_OF_ENFORCE_RULES}}
 
 # Custom enforce rules
+
 To make it easier to reuse logic across your application, sometimes you would want to encapsulate bits of logic in rules that you can use later on, for example, "what's considered a valid email".
 
-Your custom rules are essentially a single javascript object containing your rules.
+Rules are called with the argument passed to enforce(x) followed by the arguments passed to `.yourRule(y, z)`.
+
 ```js
-const myCustomRules = {
-    isValidEmail: (value) => value.indexOf('@') > -1,
-    hasKey: (value, {key}) => value.hasOwnProperty(key),
-    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
-}
+enforce.extend({
+  yourRule(x, y, z) {
+    return {
+      pass: true,
+      message: () => '',
+    };
+  },
+});
 ```
-Just like the predefined rules, your custom rules can accepts two parameters:
-* `value` The actual value you are testing against.
-* `args` (optional) the arguments which you pass on when running your tests.
-
-You can extend enforce with your custom rules by creating a new instance of `Enforce` and adding the rules object as the argument.
 
 ```js
 import { enforce } from 'vest';
 
-const myCustomRules = {
-    isValidEmail: (value) => value.indexOf('@') > -1,
-    hasKey: (value, key) => value.hasOwnProperty(key),
-    passwordsMatch: (passConfirm, options) => passConfirm === options.passConfirm && options.passIsValid
-}
-
-enforce.extend(myCustomRules);
+enforce.extend({
+  isValidEmail: value => value.indexOf('@') > -1,
+  hasKey: (value, key) => value.hasOwnProperty(key),
+  passwordsMatch: (passConfirm, options) =>
+    passConfirm === options.passConfirm && options.passIsValid,
+});
 
 enforce(user.email).isValidEmail();
 ```
 
+## Custom rules return value
+
+Rules can either return boolean indicating success or failure, or an object with two keys. `pass` indicates whether the validation is successful or not, and message provides a function with no arguments that return an error message in case of failure. Thus, when pass is false, message should return the error message for when enforce(x).yourRule() fails.
+
+```js
+enforce.extend({
+  isWithinRange(received, floor, ceiling) {
+    const pass = received >= floor && received <= ceiling;
+    if (pass) {
+      return {
+        message: () =>
+          `expected ${received} not to be within range ${floor} - ${ceiling}`,
+        pass: true,
+      };
+    } else {
+      return {
+        message: () =>
+          `expected ${received} to be within range ${floor} - ${ceiling}`,
+        pass: false,
+      };
+    }
+  },
+});
+```
+
 # Business Related Rules
 
 Along with the existing rules, you might need different business related rules, for email, phone number, credit card validations, and more.
@@ -105,6 +128,7 @@ import enforce, {
 To read the full documentation on these rules and the options they take, please visit [validator.js](https://github.com/validatorjs/validator.js).
 
 ### validator.js license:
+
 ```
 Copyright (c) 2018 Chris O'Hara <cohara87@gmail.com>
 

diff --git a/packages/vest/docs/result.md b/packages/vest/docs/result.md
@@ -27,9 +27,9 @@ A result object would look somewhat like this:
 }
 ```
 
-## Accessing the last result object with `vest.get`
+## Accessing the last result object with `.get`
 
-Alternatively, if you need to access your validation results out of context - for example, from a different UI component or function, you can use `vest.get`.
+If you need to access your validation results out of context - for example, from a different UI component or function, you can use `vest.get`
 
 Vest exposes the `vest.get` function that is able to retrieve the most recent validation result of [**stateful**](./state) suites (suites created using vest.create()).
 
@@ -45,6 +45,16 @@ const res = vest.get('suite_name');
 res.hasErrors('fieldName');
 ```
 
+Alternatively, you can access your suite's state from the `get` property on your suite function:
+
+```js
+const v = vest.create('my_form', () => {
+  /*...*/
+});
+
+v.get(); // -> returns the same value as vest.get('my_form');
+```
+
 # Result Object Methods:
 
 Along with these values, the result object exposes the following methods:

diff --git a/packages/vest/docs/state.md b/packages/vest/docs/state.md
@@ -48,3 +48,15 @@ validate(); // validation result is added to the state.
 
 vest.reset('suite_name'); // validation result is removed
 ```
+
+Alternatively, if you have access to your suite, you can call `suite.reset` directly without providing the suite name:
+
+```js
+import vest from 'vest';
+
+const v = vest.create('suite_name', () => {
+  // Your tests go here
+});
+
+v.reset(); // validation result is removed from Vest's state.
+```