vest 3.2.8-dev-6d7c74 → 3.2.8

package/docs/n4s/template.md

@@ -0,0 +1,53 @@
+# Enforce templates
+
+When you have common patterns you need to repeat in multiple places, it might be simpler to store them as templates.
+
+For example, let's assume that all across our systems, a username must be a non-numeric string that's longer than 3 characters.
+
+```js
+enforce(username).isString().isNotEmpty().isNotNumeric().longerThan(3);
+```
+
+This is quite simple to understand, but if you have to keep it up-to-date in every place you validate a username, you may eventually have inconsistent or out-of-date validations.
+
+It can be beneficial in that case to keep this enforcement as a template for later use:
+
+```js
+const Username = enforce.template(
+  enforce.isString().isNotEmpty().isNotNumeric().longerThan(3)
+);
+```
+
+And then, anywhere else you can use your new `Username` template to validate usernames all across your application:
+
+```js
+Username('myUsername'); // passes
+Username('1234'); // throws
+Username('ab'); // throws
+```
+
+You can also use templates inside other compound rules, such as `shape`, `isArrayOf` ,`anyOf` or `allOf`.
+
+```js
+enforce({
+  username: 'someusername',
+}).shape({ username: Username });
+
+enforce(['user1', 'user2']).isArrayOf(Username);
+```
+
+Templates can also be nested and composited:
+
+```js
+const RequiredField = enforce.template(enforce.isNotEmpty());
+const NumericString = enforce.template(enforce.isNumeric().isString());
+
+const EvenNumeric = enforce.template(
+  RequiredField,
+  NumericString,
+  enforce.isEven()
+);
+
+EvenNumeric('10'); // pases
+EvenNumeric('1'); // throws
+```

package/docs/node.md

@@ -0,0 +1,43 @@
+# Using Vest in node
+
+Using Vest in node is mostly the same as it is in the browser, but you should consider your runtime.
+
+## Validation state
+
+When running your validations in your api, you usually want to have stateless validations to prevent leakage between requests.
+
+Read more about [Vest's state](./state).
+
+## require vs import
+
+Depending on your node version and the module system you support you can use different syntax to include Vest.
+
+### Most compatible: commonjs
+
+To be on the safe side and compatible with all node versions, use a `require` statement.
+
+```js
+const vest = require('vest');
+const { test, enforce } = vest;
+```
+
+Depending on your node version and used flag, your require statement might default to Vest's minified es5 bundle. If you want to make sure to use the non-minified es6 commonjs bundle, you can require it directly.
+
+```js
+const vest = require('vest/vest.cjs.production.js');
+const { test, enforce } = vest;
+```
+
+### Node 14
+
+With node 14's support of [package entry points](https://nodejs.org/api/esm.html#esm_package_entry_points), node should be able to detect on its own which import style you use and load the correct bundle.
+
+Both of the following should work:
+
+```js
+import { create, test } from 'vest';
+```
+
+```js
+const vest = require('vest');
+```

package/docs/optional.md

@@ -0,0 +1,51 @@
+# optional fields
+
+> Since 3.2.0
+
+It is possible to mark fields in your suite as optional fields. This means that when they are skipped, the suite may still be considered as valid.
+All fields are by default required, unless explicitly marked as optional using the `optional` function.
+
+## Usage
+
+`optional` can take a field name as its argument, or an array of field names.
+
+```js
+import { create, optional, only, test, enforce } from 'vest';
+
+const suite = create('RegisterPet', (data, currentField) => {
+  only(currentField); // only validate this specified field
+
+  optional(['pet_color', 'pet_age']);
+  /** Equivalent to:
+   * optional('pet_color')
+   * optional('pet_age')
+   **/
+
+  test('pet_name', 'Pet Name is required', () => {
+    enforce(data.name).isNotEmpty();
+  });
+
+  test('pet_color', 'If provided, pet color must be a string', () => {
+    enforce(data.color).isString();
+  });
+
+  test('pet_age', 'If provided, pet age must be numeric', () => {
+    enforce(data.age).isNumeric();
+  });
+});
+
+suite({ name: 'Indie' }, /* -> only validate pet_name */ 'pet_name').isValid();
+// ✅ Since pet_color and pet_age are optional, the suite may still be valid
+
+suite({ age: 'Five' }, /* -> only validate pet_age */ 'pet_age').isValid();
+// 🚨 When erroring, optional fields still make the suite invalid
+```
+
+## Difference between `optional` and `warn`
+
+While on its surface, optional might seem similar to warn, they are quite different.
+optional, like "only" and "skip" is set on the field level, which means that when set - all tests of an optional field are considered optional. Warn, on the other hand - is set on the test level, so the only tests affected are the tests that have the "warn" option applied within them.
+
+Another distinction is that warning tests cannot set the suite to be invalid.
+
+There may be rare occasions in which you have an optional and a warning only field, in which case, you may combine the two.

package/docs/result.md

@@ -0,0 +1,238 @@
+# Vest's result object
+
+Vest validations return a results object that holds all the information regarding the current run, and methods to easily interact with the data.
+
+A result object would look somewhat like this:
+
+```js
+{
+  'name': 'formName',              // The name of the validation suite
+  'errorCount': Number 0,          // Overall count of errors in the suite
+  'warnCount': Number 0,           // Overall count of warnings in the suite
+  'testCount': Number 0,           // Overall test count for the suite (passing, failing and warning)
+  'tests': Object {                // An object containing all non-skipped tests
+    'fieldName': Object {          // Name of each field
+      'errorCount': Number 0,      // Error count per field
+      'errors': Array [],          // Array of error messages fer field (may be undefined)
+      'warnings': Array [],        // Array of warning messages fer field (may be undefined)
+      'warnCount': Number 0,       // Warning count per field
+      'testCount': Number 0,       // Overall test count for the field (passing, failing and warning)
+    },
+    'groups': Object {             // An object containing groups declared in the suite
+      'fieldName': Object {        // Subset of res.tests[fieldName] only containing tests
+        /*... */                   // only containing tests that ran within the group
+      }
+    }
+  }
+}
+```
+
+## Accessing the recent result object with `.get`
+
+If you need to access your validation results out of context - for example, from a different UI component or function, you can use `.get()` - a function that exists as a property of your validation suite.
+
+In case your validations did not run yet, `.get` returns an empty validation result object - which can be helpful when trying to access validation result object when rendering the initial UI, or setting it in the initial state of your components.
+
+```js
+const suite = create('my_form', () => {
+  /*...*/
+});
+
+suite.get(); // -> returns the most recent result object for the current suite
+```
+
+# Result Object Methods:
+
+Along with these values, the result object exposes the following methods:
+
+## `isValid` function
+
+`isValid` returns whether the validation suite as a whole is valid or not.
+
+A suite is considered valid if the following conditions are met:
+
+- There are no errors (`hasErrors() === false`) in the suite - warnings are not counted as errors.
+- All non [optional](./optional) fields have passing tests.
+- There are no pending async tests.
+
+```js
+result.isValid();
+
+suite.get().isValid();
+```
+
+?> **Note** when `isValid` equals `false`, it does not necessarily mean that the form is inValid, but that it might not be valid _yet_. For example, if not all the fields are filled, the form is simply not valid, even though it may not be strictly invalid.
+
+## `hasErrors` and `hasWarnings` functions
+
+If you only need to know if a certain field has validation errors or warnings but don't really care which they are, you can use `hasErrors` or `hasWarnings` functions.
+
+```js
+resultObject.hasErrors('username');
+// true
+
+resultObject.hasWarnings('password');
+// false
+```
+
+In case you want to know whether the whole suite has errors or warnings (to prevent submit, for example), you can use the same functions, just without specifying a field
+
+```js
+resultObject.hasErrors();
+// true
+
+resultObject.hasWarnings();
+// true
+```
+
+## `hasErrorsByGroup` and `hasWarningsByGroup` functions
+
+Similar to `hasErrors` and `hasWarnings`, but returns the result for a specified [group](./group)
+
+To get the result for a given field in the group:
+
+```js
+resultObject.hasErrorsByGroup('groupName', 'fieldName');
+// true
+
+resultObject.hasWarningsByGroup('groupName', 'fieldName');
+// false
+```
+
+And to get the result for a whole group.
+
+```js
+resultObject.hasErrorsByGroup('groupName');
+// true
+
+resultObject.hasWarningsByGroup('groupName');
+// true
+```
+
+[Read more about groups](./group)
+
+## `getErrors` and `getWarnings` functions
+
+These functions return an array of errors for the specified field. If no field specified, it returns an object with all fields as keys and their error arrays as values.
+
+```js
+resultObject.getErrors('username');
+// ['Username is too short', `Username already exists`]
+
+resultObject.getWarnings('password');
+// ['Password must contain special characters']
+```
+
+If there are no errors for the field, the function defaults to an empty array:
+
+```js
+resultObject.getErrors('username');
+// []
+
+resultObject.getWarnings('username');
+// []
+```
+
+You can also call these functions without a field name, which will return you an array per field:
+
+```js
+resultObject.getErrors();
+
+// {
+//   username: ['Username is too short', `Username already exists`],
+//   password: ['Password must contain special characters']
+// }
+```
+
+!> **NOTE** If you did not specify error messages for your tests, your errors array will be empty as well. In such case you should always rely on `.hasErrors()` instead.
+
+## `getErrorsByGroup` and `getWarningsByGroup` functions
+
+Just like get `getErrors` and `getWarnings`, but narrows the result to a specified [group](./group).
+
+```js
+resultObject.getErrorsByGroup('groupName', 'fieldName');
+resultObject.getWarningsByGroup('groupName', 'fieldName');
+resultObject.getErrorsByGroup('groupName'');
+resultObject.getWarningsByGroup('groupName'');
+```
+
+[Read more about groups](./group).
+
+## `.done()`
+
+Done is a function that can be chained to your validation suite, and allows invoking callbacks whenever a specific, or all, tests finish their validation - regardless of the validation result.
+
+If we specify a field name in our `done` call, vest will not wait for the whole suite to finish before running our callback. It will invoke immediately when all tests with that given name finished running.
+
+`.done()` calls can be infinitely chained after one another, and as the validation suite completes - they will all run immediately.
+
+`done` takes one or two arguments:
+
+| Name        | Type       | Optional | Description                                                                                                                     |
+| ----------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `fieldName` | `String`   | Yes      | If passed, the current done call will not wait for the whole suite to complete, but instead wait for a certain field to finish. |
+| `callback`  | `Function` | No       | A callback to be run when either the whole suite or the specified field finished running.                                       |
+
+The result object is being passed down to the `done` object as an argument.
+
+**Example**
+
+In the below example, the `done` callback for `UserName` may run before the whole suite finishes. Only when the rest of the suite finishes, it will call the other two done callbacks that do not have a field name specified.
+
+```js
+import { create, test, enforce } from 'vest';
+
+const suite = create('SendEmailForm', data => {
+  test(
+    'UserEmail',
+    'Marked as spam address',
+    async () => await isKnownSpammer(data.address)
+  );
+
+  test(
+    'UserName',
+    'must not be blacklisted',
+    async () => await isBlacklistedUser(data.username)
+  );
+});
+
+const validationResult = suite(data)
+  .done('UserName', res => {
+    if (res.hasErrors('UserName')) {
+      showUserNameErrors(res.errors);
+    }
+  })
+  .done(output => {
+    reportToServer(output);
+  })
+  .done(output => {
+    promptUserQuestionnaire(output);
+  });
+```
+
+!> **IMPORTANT** .done calls must not be used conditionally - especially when involving async tests. This might cause unexpected behavior or missed callbacks. Instead, if needed, perform your conditional logic within your callback.
+
+```js
+// 🚨 This might not work as expected when working with async validations
+
+if (field === 'username') {
+  result.done(() => {
+    /*do something*/
+  });
+}
+```
+
+```js
+// ✅ Instead, perform your checks within your done callback
+
+result.done(() => {
+  if (field === 'username') {
+    /*do something*/
+  }
+});
+```
+
+### Read more on:
+
+[Optional tests](./optional)

package/docs/state.md

@@ -0,0 +1,102 @@
+# Understanding Vest's state
+
+Vest is designed to help perform validations on user inputs. The nature of user inputs is that they are filled one by one by the user. In order to provide good user experience, the best approach is to validate fields as the user type, or when they leave the field.
+
+The difficult part when validating upon user interaction is that we want to only validate the field that the user is currently interacting with, and not the rest of the form. This
+This can be done with Vest's [`only()` hook](./exclusion). That's where the state mechanism is becoming useful.
+
+When you have skipped fields in your validation suite, vest will try to see if those skipped fields ran in the previous suite, and merge them into the currently running suite result - so the result object you get will include all the fields that your user interacted with.
+
+## What Vest's state does
+
+- _Skipped field merge_
+
+As mentioned before - whenever you skip a field, vest will look for it in your previously ran validations and add it to the current result.
+
+- _Lagging async `done` callback blocking_
+
+In case you have an async test that didn't finish from the previous suite run - and you already ran another async test for the same field - vest will block the [`done()`]('./result#done) callbacks for that field from running for the previous suite result.
+
+# Drawbacks when using stateful validations
+
+When the validations are stateful, you get the benefit of not having to know which fields have already been validated, or keeping track of their previous results.
+
+The drawback of this approach is that when you run the same form in multiple-unrelated contexts, the previous validation state still holds the previous result.
+
+Here are a few examples and their solutions:
+
+## Single Page Application - suite result retention
+
+This scenario applies for cases when your form is a part of an SPA with client side routing. Let's assume your user successfuly submits the form, navigates outside of the page, and then sometime and then, later in the same session, they navigate back to the form.
+
+The form will then have a successful validation state since the previous result is stored in the suite state.
+
+### Solution: Resetting suite state with `.reset();`
+
+In some cases, such as form reset, you want to discard of previous validation results. This can be done with `vest.reset()`.
+
+`.reset` disables all pending async tests in your suite and empties the state out.
+
+### Usage:
+
+`.rese()` Is a property on your validation suite, calling it will remove your suite's state.
+
+```js
+import { create } from 'vest';
+
+const suite = create(() => {
+  // Your tests go here
+});
+
+suite.reset(); // validation result is removed from Vest's state.
+```
+
+## Dynamically added fields
+
+When your form contains dynamically added fields, for example - when a customer can add fields to their checkout form on the fly, those items would still exist in the suite state when the user removed them from the form. This means that you may have an unsuccessful suite result, even though it should be successful.
+
+### Solution: Removing a single field from the validation result
+
+Instead of resetting the whole suite, you can alternatively remove just one field. This is useful when dynamically adding and removing fields upon user interaction - and you want to delete a deleted field from the state.
+
+```js
+import { create, test } from 'vest';
+
+const suite = create(() => {
+  // Your tests go here
+
+  test('username', 'must be at least 3 chars long', () => {
+    /*...*/
+  });
+});
+
+suite.remove('username'); // validation result is removed from Vest's state.
+```
+
+## Server side validations
+
+When running your validations on the server, you want to keep each request isolated with its own state, and not update the same validation state between requests. Doing that can cause failed validations to seem successful or vice versa due to different requests relying on the same state.
+
+### Solution: Treat validations as stateless
+
+While when on the browser you usually want to treat validations as statefull - even though it might sometimes not be the case - on the server you almost always want to treat your validations as stateless.
+
+To do that, all you need to do is wrap your suite initialization with a wrapper function. Whenever you call that function, a new suite state will be created.
+
+### Example
+
+```js
+import { create } from 'vest';
+
+function suite(data) {
+  return create(() => {
+    test('username', 'username is required', () => {
+      enforce(data.username).isNotEmpty();
+    });
+  })();
+  // Note that we're immediately invoking our suite
+  // so what we return is actually the suite result
+}
+
+const result = suite({ username: 'Mike123' });
+```

package/docs/test.md

@@ -0,0 +1,172 @@
+# Using the `test` function
+
+The `test` function is represents a single case in your validation suite. It accepts the following arguments:
+
+| Name       | Type       | Optional | Description                                                   |
+| ---------- | ---------- | -------- | ------------------------------------------------------------- |
+| `name`     | `String`   | No       | The name of the value or field being validated.               |
+| `message`  | `String`   | Yes      | An error message to display to the user in case of a failure. |
+| `callback` | `Function` | No       | The actual validation logic for the given test.               |
+
+A test can either be synchronous or asynchronous, and it can either have a [severity](./warn) of `error` or of `warn`.
+
+## Failing a test
+
+There are three ways to fail a test:
+
+### Throwing inside your test body (using enforce)
+
+Just like in most unit testing frameworks, a validation fails whenever the test body throws an exception. [`Enforce`](./enforce) throws on failed validations.
+When thrown with a string
+
+```js
+// const username = 'Gina.Vandervort';
+// const password = 'Q3O';
+
+test('username', 'Should be at least 3 characters long', () => {
+  enforce(username).longerThanOrEquals(3);
+}); // this test passes
+
+test('password', 'Should be at least 6 characters long', () => {
+  enforce(password).longerThanOrEquals(6); // an error is thrown here
+}); // this test fails
+```
+
+Alternatively, you can also throw a string value to use it as your test message. To do that, you need to omit the test message, and throw a string, for example - when using enforce.extend.
+
+```js
+enforce.extend({
+  isChecked: value => {
+    return {
+      pass: !!value.checked,
+      message: () => 'value must be checked',
+    };
+  },
+});
+
+/*...*/
+
+/*
+  tost = { checked: false }
+*/
+
+test('tos', () => {
+  enforce(tos).isChecked(); // will fail with the message: "value must be checked"
+});
+```
+
+### Explicitly returning false
+
+To make it easy to migrate your existing validation logic into Vest, it also supports validations explicitly returning `false` (and not any other falsy value) to represent failures.
+
+```js
+// const username = 'Gina.Vandervort';
+// const password = 'Q3O';
+
+test('username', 'Should be at least 3 characters long', () => {
+  return username.length >= 3; // = true
+}); // this test passes
+
+test('password', 'Should be at least 6 characters long', () => {
+  return password.length >= 6; // = false
+}); // this test fails
+```
+
+### Rejecting a Promise
+
+This is only true for async tests, more on that below.
+
+## Asynchronous Tests
+
+Sometimes you need to validate your data with information not present in your current context, for example - data from the server, such as username availability. In those cases, you need to go out to the server and fetch data as part of your validation logic.
+
+An async test is declared by returning a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) from your test body. When the promise resolves, your test passes, and when your promise rejects, it fails.
+
+```js
+// Example using a promise
+test('name', 'I always fail', () => Promise.reject());
+
+// Example using async/await
+test('name', 'Already Taken', async () => {
+  return await doesUserExist(user);
+});
+```
+
+### Rejecting with a message
+
+When performing validations on the server, your server might need to respond with different error messages. When rejecting with a string value, your string value will be picked up as the message to show to the user.
+
+```js
+test('name', () =>
+  new Promise((resolve, reject) => {
+    fetch(`/checkUsername?name=${name}`)
+      .then(res => res.json)
+      .then(data => {
+        if (data.status === 'fail') {
+          reject(data.message); // rejects with message and marks the test as failing
+        } else {
+          resolve(); // completes. doesn't mark the test as failing
+        }
+      });
+  }));
+```
+
+## test.memo for memoized tests
+
+In order to improve performance and runtime in heavy or long-running tests (such as async tests that go to the server), tests individual test results can be cached and saved for a later time, so whenever the exact same params appear again in the same runtime, the test result will be used from cache, instead of having to be re-evaluated.
+
+### Usage:
+
+Memoized tests are almost identical to regular tests, only with the added dependency array as the last argument. The dependency array is an array of items, that when identical (strict equality, `===`) to a previously presented array in the same test, its previous result will be used. You can see it as your cache key to the test result.
+
+### Example:
+
+```js
+import { vest, test } from 'vest';
+export default create('form-name', data => {
+  test.memo(
+    'username',
+    'username already exists',
+    () => doesUserExist(data.username),
+    [data.username]
+  );
+});
+```
+
+## test.each for dynamically creating tests from a table
+
+Use test.each when you need to dynamically create tests from data, or when you have multiple tests that have the same overall structure.
+
+test.each takes an array of arrays. The inner array contains the arguments that each of the tests will recieve.
+
+Because of the dynamic nature of the iterative tests, you can also dynamically construct the fieldName and the test message by providing a function instead of a string. Your array's content will be passed over as arguments to each of these functions.
+
+```js
+/*
+const data = {
+  products: [
+    ['Game Boy Color', 25],
+    ['Speak & Spell', 22.5],
+    ['Tamagotchi', 15],
+    ['Connect Four', 7.88],
+  ]
+}
+*/
+
+const suite = create('store_edit', data => {
+  test.each(data.products)(
+    name => name,
+    'Price must be numeric and above zero.',
+    (_, price) => {
+      enforce(price).isNumeric().greaterThan(0);
+    }
+  );
+});
+```
+
+**Read next about:**
+
+- [Warn only tests](./warn).
+- [Grouping tests](./group).
+- [Asserting with enforce](./enforce).
+- [Skipping or including tests](./exclusion).