vest 4.0.0-dev-366a8b → 4.0.0-dev-e266d9

package/docs/exclusion.md

@@ -1,129 +0,0 @@
-# Excluding and including tests
-
-When performing validations in real world-scenarios, you may need to only run tests of a single field in your suite, or skip certain tests according to some logic. That's why Vest includes `skip()` and `only()`.
-
-`skip()` and `only()` are functions that take a name of the test, or a list of names to either include or exclude fields from being validated. They should be called from the body of suite callback, and in order for them to take effect, they should be called before anything else.
-
-!> **NOTE** When using `only()` or `skip()` you must place them before any of the tests defined in the suite. Hooks run in order of appearance, which means that if you place your `skip` hook after the field you're skipping - it won't have any effect.
-
-### Only running specific tests (including)
-
-When validating upon user interactions, you will usually want to only validate the input the user currently interacts with to prevent errors appearing in unrelated places. For this, you can use `only()` with the name of the test currently being validated.
-
-In the example below, we're assuming the argument `fieldName` is being populated with the name of the field we want to test. If none is passed, the call to `only` will be ignored, and all tests will run as usual. This allows us to test each field at a time during the interaction, but test all on form submission.
-
-```js
-import { create, enforce, test, only } from 'vest';
-
-const suite = create((data, fieldName) => {
-  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 validationResult = suite(formData, changedField);
-```
-
-### Skipping tests
-
-There are not many cases for skipping tests, but they do exist. For example, when you wish to prevent validation of a promo code when none provided.
-
-In this case, and in similar others, you can use `skip()`. When called, it will only skip the specified fields, all other tests will run as they should.
-
-```js
-import { create, enforce, test, skip } from 'vest';
-
-const suite = create(data => {
-  if (!data.promo) skip('promo');
-
-  // this test won't run when data.promo is falsy.
-  test('promo', 'Promo code is invalid', () => {
-    /* some validation logic*/
-  });
-});
-
-const validationResult = suite(formData);
-```
-
-## skipWhen: Conditionally excluding portions of the suite
-
-In some cases we might need to skip a test or a group based on a given condition, for example - based on the intermediate state of the currently running suite. To allow this, can use `skipWhen`. `skipWhen` takes a boolean expression and a callback with tests.
-If the expression is true, the tests within the callback will be skipped. Otherwise, the tests will run as normal.
-
-In the following example we're skipping the server side verification of the username if the username is invalid to begin with:
-
-```js
-import { create, test, enforce, skipWhen } from 'vest';
-
-const suite = create((data = {}) => {
-  test('username', 'Username is required', () => {
-    enforce(data.username).isNotEmpty();
-  });
-
-  skipWhen(suite.get().hasErrors('username'), () => {
-    test('username', 'Username already exists', () => {
-      // this is an example for a server call
-      return doesUserExist(data.username);
-    });
-  });
-});
-export default suite;
-```
-
-!> **Note** Using suite.get() within the suite runs returns a **DRAFT** result. This means that it may not contain the final validation result.
-
-## Including and excluding groups of tests
-
-Similar to the way you use `skip` and `only` to include and exclude tests, you can use `skip.group` and `only.group` to exclude and include whole groups.
-
-These two functions are very powerful and give you control of whole portions of your suite at once.
-
-```js
-import { create, test, group, enforce, skip } from 'vest';
-
-create(data => {
-  skip.group(data.userExists ? 'signUp' : 'signIn');
-
-  test('userName', "Can't be empty", () => {
-    enforce(data.username).isNotEmpty();
-  });
-  test('password', "Can't be empty", () => {
-    enforce(data.password).isNotEmpty();
-  });
-
-  group('signIn', () => {
-    test(
-      'userName',
-      'User not found. Please check if you typed it correctly.',
-      findUserName(data.username)
-    );
-  });
-
-  group('signUp', () => {
-    test('email', 'Email already registered', isEmailRegistered(data.email));
-
-    test('age', 'You must be at least 18 years old to join', () => {
-      enforce(data.age).largerThanOrEquals(18);
-    });
-  });
-});
-```
-
-## Things to know about how these functions work:
-
-**only.group()**:
-When using `only.group`, other groups won't be tested - but top level tests that aren't nested in any groups will. The reasoning is that the top level space is a shared are that will always be executed. If you want only your group to run, nest everything else under groups as well.
-
-If you combine `only.group` with `skip`, if you skip a field inside a group that is included, that field will be excluded during this run regardless of its group membership.
-
-**skip.group()**
-
-If you combine `skip.group` with `only` your included field declared within the skipped tests will be ignored.

package/docs/getting_started.md

@@ -1,72 +0,0 @@
-# Installation
-
-To install the stable version of Vest:
-
-```
-npm install vest
-```
-
-You can also add Vest directly as a script tag to your page:
-
-```html
-<script src="https://unpkg.com/vest@4"></script>
-```
-
-Vest tests are very much like unit tests, with only slight differences. Instead of using `describe/it/expect`, you will use `validate/[test](./test)/[enforce](./enforce)`.
-
-- `test`: A single validation unit, validating a field or a single value. It takes the name of the field being validated, a failure message (to display to the user), and a callback function that contains the validation logic. [Read more about test].
-- `enforce`: This is our assertion function. We’ll use it to make sure our validations pass. [Read more about enforce].
-
-## Writing tests
-
-First, you need to initialize your validation suite using `create()`. This initializes your validation suite state and allows validation results to be merged with future validations.
-
-```js
-import { create } from 'vest';
-
-const suite = create(() => {
-  // validation suite content goes here.
-});
-
-const validationResult = suite();
-```
-
-`create()` takes a callback that contains your tests, and returns a "suite" function which runs your validation suite. All the arguments you pass to it are being forwarded 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
-// suite.js
-import { create, test, enforce } from ‘vest’;
-
-const suite = create((formData) => {
-    test('username', 'Must be between 2 and 10 chars', () => {
-        enforce(formData.username)
-            .longerThanOrEquals(2)
-            .shorterThan(10);
-    });
-
-    test('password', 'Must contain at least one digit', () => {
-        enforce(formData.password)
-            .matches(/(?=.*[0-9])/);
-    });
-});
-
-export default suite;
-```
-
-```js
-// myFeature.js
-
-import suite from './suite.js';
-
-const res = suite(formData);
-```
-
-In the above example, we validate a form containing username and a password.
-
-**Read next about:**
-
-- [Vest's result object](./result).
-- [Using the test function](./test).
-- [Asserting with enforce](./enforce).

package/docs/group.md

@@ -1,142 +0,0 @@
-# Grouping tests
-
-In many cases it can be helpful to group tests together so you can include or exclude a portion of the suite with a single condition.
-Similar to the `describe` and `context` features provided by unit testing frameworks, Vest provides `group`.
-
-[Try on CodeSandbox (React)](https://codesandbox.io/s/vest-group-example-react-4i2ne)
-
-```js
-import { create, test, group, enforce, skip } from 'vest';
-
-create(data => {
-  skip.group(data.userExists ? 'signUp' : 'signIn');
-
-  test('userName', "Can't be empty", () => {
-    enforce(data.username).isNotEmpty();
-  });
-  test('password', "Can't be empty", () => {
-    enforce(data.password).isNotEmpty();
-  });
-
-  group('signIn', () => {
-    test(
-      'userName',
-      'User not found. Please check if you typed it correctly.',
-      findUserName(data.username)
-    );
-  });
-
-  group('signUp', () => {
-    test('email', 'Email already registered', isEmailRegistered(data.email));
-
-    test('age', 'You must be at least 18 years old to join', () => {
-      enforce(data.age).largerThanOrEquals(18);
-    });
-  });
-});
-```
-
-## Why use `group` and not just wrap the tests with an `if` statement?
-
-In many cases it is sufficient to just use an `if` statement. The benefit of using `group` is that when skipping (either using [skip or only](./exclusion)), Vest will merge the previous group result with the current suite. This is mostly suitable for cases like demonstrated in the first example of the multi stage form.
-
-## Use cases
-
-### 1. Multi stage form
-
-You may have in your application a multi-screen form, in which you want to validate each screen individually, but submit it all at once.
-
-```js
-// suite.js
-import { create, test, group, enforce, only } from 'vest';
-
-const suite = create((data, currentTab) => {
-  only.group(currentScreen);
-
-  group('overview_tab', () => {
-    test('productTitle', 'Must be at least 5 chars.', () => {
-      enforce(data.productTitle).longerThanOrEquals(5);
-    });
-
-    test('productDescription', "Can't be longer than 2500 chars.", () => {
-      enforce(data.productDescription).shorterThanOrEquals(2500);
-    });
-
-    test('productTags', 'Please provide up to 5 tags', () => {
-      enforce(data.tags).lengthEquals(5);
-    });
-  });
-
-  group('pricing_tab', () => {
-    test('price', '5$ or more.', () => {
-      enforce(data.price).lte(5);
-    });
-
-    test('productExtras', "Can't be empty.", () => {
-      enforce(data.extras).isNotEmpty();
-    });
-  });
-});
-
-export default suite;
-```
-
-```js
-// myFeature.js
-
-suite(data, 'overview_tab'); // will only validate 'overview_tab' group
-suite(data, 'pricing_tab'); // will only validate 'pricing_tab' group
-```
-
-### 2. Skipping tests with shared fields
-
-You sometimes want to skip some tests on a certain condition, but still run other tests with the same field-name.
-
-In the example below, we don't mind skipping the `balance` field directly, but if we skip the `quantity` field directly, it won't be tested at all - even though it has one test outside of the group. That's why we skip the `used_promo`.
-
-```js
-import { create, test, group, enforce, skip } from 'vest';
-
-const suite = create(data => {
-  if (!data.usedPromo) skip.group('used_promo');
-  if (!data.paysWithBalance) skip.group('balance');
-
-  test(
-    'balance',
-    'Balance is lower than product price',
-    hasSufficientFunds(data.productId)
-  );
-
-  test('quantity', `Quantity on this item is limited to ${data.limit}`, () => {
-    enforce(data.quantity).lessThanOrEquals(data.limit);
-  });
-
-  group('used_promo', () => {
-    test(
-      'quantity',
-      'promo code purchases are limited to one item only',
-      () => {
-        enforce(data.quantity).equals(1);
-      }
-    );
-
-    test(
-      'promoCode',
-      'Promo code can only be used once',
-      isPromoCodeUsed(data.usedPromo)
-    );
-  });
-});
-```
-
-## Querying the result object for groups
-
-Groups represent a portion of your validation suite, so when using `group`, you are likely to need to get the group-specific validation results.
-Your result object exposes the following methods:
-
-- [_hasErrorsByGroup_](./result#haserrorsbygroup-and-haswarningsbygroup-functions)
-- [_hasWarningsByGroup_](./result#haserrorsbygroup-and-haswarningsbygroup-functions)
-- [_hasErrorsByGroup_](./result#geterrorsbygroup-and-getwarningsbygroup-functions)
-- [_hasWarningsByGroup_](./result#geterrorsbygroup-and-getwarningsbygroup-functions)
-
-Read more about these methods in [the result object](./result).

package/docs/index.html

@@ -1,41 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Vest - Declarative Validations</title>
-    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-    <meta name="description" content="Validation Test" />
-    <meta
-      name="viewport"
-      content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
-    />
-    <link rel="icon" href="./_assets/favicon.ico" />
-    <link
-      rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"
-    />
-    <link
-      rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/prismjs@1.22.0/themes/prism-tomorrow.css"
-    />
-  </head>
-  <body>
-    <div id="app"></div>
-    <script>
-      window.$docsify = {
-        name: 'vest',
-        logo: '/_assets/vest-logo.png',
-        repo: 'https://github.com/ealush/vest',
-        search: 'auto',
-        loadSidebar: true,
-        subMaxLevel: 2,
-        themeColor: '#5BA9D8',
-      };
-    </script>
-    <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
-    <script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
-    <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
-    <script src="//unpkg.com/vest"></script>
-    <script src="./_assets/index.js"></script>
-  </body>
-</html>

package/docs/migration.md

@@ -1,202 +0,0 @@
-# Migration guides
-
-## V3 to V4
-
-Vest 4.0 is a major release that contains several breaking changes. Most should be pretty simple to migrate, but there are a few things that require a bit more attention.](https://
-
-### Removed: Default import support
-
-For better tree shaking, we removed the default import support. This means that if you need a part of the library, you will need to import it explicitly, resulting in a smaller eventual bundle size.
-
-### V3
-
-```js
-import vest from 'vest';
-```
-
-### V4
-
-```js
-import * as vest from 'vest';
-// OR:
-import { create, test, enforce } from 'vest';
-```
-
-### Removed: Suite name from suite declaration
-
-From now on, suites do not accept a name when being declared. The name used to serve a purpose in V2 when accessing properties from the suite, but it serves no purpose anymore.
-
-#### V3
-
-```js
-import { create } from 'vest';
-
-create('my-suite', () => {});
-```
-
-### V4
-
-```js
-import { create } from 'vest';
-
-create(() => {});
-```
-
-### Renamed: classNames to classnames
-
-Vest 3 included the `vest/classNames` import. It is now renamed to `vest/classnames`.
-
-### V3
-
-```js
-import classNames from 'vest/classNames';
-```
-
-### V4
-
-```js
-import classnames from 'vest/classnames';
-```
-
-### Changed: Do not use if/else statements to conditionally run tests
-
-Vest version 4 relies on order of execution and remembers the result of each test based on its location in the suite, similar to the way [hooks in react](https://reactjs.org/docs/hooks-rules.html) work. This means that tests wrapped in an if/else statement make Vest go out of sync with the suite order, and unexecuted test results will be recorded. Instead of using if/else statements, you should use the `skipWhen` function that achieves the same result.
-
-### V3
-
-```js
-if (!suite.get().hasErrors('password')) {
-  test('confirm', 'passwords do not match', () => {
-    /*...*/
-  });
-}
-```
-
-### V4
-
-```js
-import { skipWhen, test } from 'vest';
-
-// ...
-
-skipWhen(suite.hasErrors('password'), () => {
-  test('confirm', 'passwords do not match', () => {
-    /*...*/
-  });
-});
-
-// ...
-```
-
-**Note**
-If you want to completely omit a test from your suite, and you know that it won't appear at all during the lifetime of your suite, you may use `if/else`.
-
-### Removed: enforce.template
-
-enforce.template was mostly a shorthand for a "and" style enforcements. In reality it did not provide any substantial functionality that was not achievable without it, while it contributed to confusion regarding the api.
-
-## V2 to V3
-
-Vest version 3 comes with many new features, yet with a reduced bundle size. To achieve this, some redundant interfaces were removed. All v2 capabilities still exist, but the way to use some of them changed.
-
-**Replaced interfaces**
-
-### Removed: vest.get()
-
-From now on, use suite.get() to get the latest validation result.
-
-#### v2
-
-```js
-const suite = vest.create('user_form', () => {
-  /*...*/
-});
-
-vest.get('user_form'); // Returns the most recent validation result
-```
-
-#### v3
-
-```js
-const suite = create(() => {
-  /*...*/
-});
-
-suite.get(); // Returns the most recent validation result
-```
-
-### Removed: vest.reset() // To reset suite state
-
-From now on, use suite.reset() to reset the validation result.
-
-#### v2
-
-```js
-const suite = vest.create('user_form', () => {
-  /*...*/
-});
-
-vest.reset('user_form'); // Resets the validity state
-```
-
-#### v3
-
-```js
-const suite = create(() => {
-  /*...*/
-});
-
-suite.reset(); // Resets the validity state
-```
-
-### Removed: vest.draft() // To retrieve intermediate result
-
-From now on, use suite.get() to get the validation result.
-
-#### v2
-
-```js
-const suite = vest.create('user_form', () => {
-  if (vest.draft().hasErrors('username')) {
-    /* ... */
-  }
-});
-```
-
-#### v3
-
-```js
-const suite = create('user_form', () => {
-  skipWhen(suite.get().hasErrors('username'), () => {
-    /* ... */
-  });
-});
-```
-
-### Removed: validate() // For non persistent validations
-
-The stateless validate export is not needed anymore due to a change in the state structure.
-
-#### v2
-
-```js
-import { validate } from 'vest';
-
-const result = data =>
-  validate('user_form', () => {
-    /*...*/
-  })();
-```
-
-#### v3
-
-```js
-import { create } from 'vest';
-
-const suite = data =>
-  create(() => {
-    /* ... */
-  })();
-
-const result = suite({ username: 'example' });
-```