vest 3.2.8-dev-6d7c74 → 3.2.8

package/docs/group.md

@@ -0,0 +1,142 @@
+# 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('authentication_form', 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('product-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('checkout_form', 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

@@ -0,0 +1,41 @@
+<!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

@@ -0,0 +1,107 @@
+# Migration guides
+
+## 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' });
+```

package/docs/n4s/compound.md

@@ -0,0 +1,187 @@
+# Shape and schema validation
+
+Alongside the list of rules that only accept data provided by the user, enforce also supports compound rules - these are rules that accept other rules as their arguments. These rules let you validate more complex scenarios with the ergonomics of enforce.
+
+- [enforce.anyOf() - either/or validations](#anyof)
+- [enforce.allOf() - all/and validations](#allof)
+- [enforce.shape() - Object's shape matching](#shape)
+  - [enforce.optional() - nullable keys](#optional)
+- [enforec.loose() - loose shape matching](#loose)
+- [enforce.isArrayOf() - array shape matching](#isarrayof)
+
+## enforce.anyOf() - either/or validations :id=anyof
+
+Sometimes a value has more than one valid possibilities, `any` lets us validate that a value passes _at least_ one of the supplied rules.
+
+```js
+enforce(value).anyOf(enforce.isString(), enforce.isArray()).isNotEmpty();
+// A valid value would either an array or a string.
+```
+
+## enforce.allOf() - all/and validations :id=allof
+
+`allOf` lets us validate that a value passes _all_ of the supplied rules or templates.
+
+enforce(value).allOf(
+enforce.isArray(),
+enforce.longerThan(2)
+);
+
+This can be even more useful when combined with shapes and templates:
+
+```js
+const User = enforce.template(
+  enforce.loose({
+    id: enforce.isNumber()
+    name: enforce.shape({
+      first: enforce.isString(),
+      last: enforce.isString(),
+      middle: enforce.optional(enforce.isString()),
+    }),
+  })
+);
+
+const DisabledAccount = enforce.template(
+  enforce.loose({
+    disabled: enforce.equals(true)
+  })
+)
+
+enforce(value).allOf(
+  User,
+  DisabledAccount
+);
+// A valid is string and longer then 5.
+```
+
+## enforce.shape() - Lean schema validation. :id=shape
+
+`enforce.shape()` validates the structure of an object.
+
+```js
+enforce({
+  firstName: 'Rick',
+  lastName: 'Sanchez',
+  age: 70,
+}).shape({
+  firstName: enforce.isString(),
+  lastName: enforce.isString(),
+  age: enforce.isNumber(),
+});
+```
+
+You may also chain your validation rules:
+
+```js
+enforce({
+  age: 22,
+}).shape({
+  age: enforce.isNumber().isBetween(0, 150),
+});
+```
+
+You may also nest calls to shape in order to validate a deeply nested object.
+
+```js
+enforce({
+  user: {
+    name: {
+      first: 'Joseph',
+      last: 'Weil',
+    },
+  },
+}).shape({
+  user: enforce.shape({
+    name: enforce.shape({
+      first: enforce.isString(),
+      last: enforce.isString(),
+    }),
+  }),
+});
+```
+
+### enforce.optional() - nullable keys :id=optional
+
+-- Optional can only be used within enforce.shape().
+
+In regular cases, a missing key in the data object would cause an error to be thrown. To prevent that from happening, mark your optional keys with `enforce.optional`.
+
+enforce.optional will pass validations of a key that's either not defined, undefined or null.
+
+`enforce.optional` takes as its arguments all the rules that the value must pass.
+
+```js
+enforce({
+  user: {
+    name: {
+      first: 'Joseph',
+      last: 'Weil',
+    },
+  },
+}).shape({
+  user: enforce.shape({
+    name: enforce.shape({
+      first: enforce.isString(),
+      last: enforce.isString(),
+      middle: enforce.optional(enforce.isString(), enforce.longerThan(3)),
+    }),
+  }),
+});
+```
+
+## enforec.loose() - loose shape matching :id=loose
+
+By default, shape will treat excess keys in your data object as validation errors. If you wish to allow support for excess keys in your object's shape, you can use `enforce.loose()` which is a shorthand to `enforce.shape(data, shape, { loose: true })`.
+
+```js
+enforce({ name: 'Laura', code: 'x23' }).shape({ name: enforce.isString() });
+// 🚨 This will throw an error because `code` is not defined in the shape
+```
+
+```js
+enforce({ name: 'Laura', code: 'x23' }).loose({ name: enforce.isString() });
+// ✅ This will pass with `code` not being validated
+```
+
+## enforce.isArrayOf() - array shape matching :id=isarrayof
+
+enforce.isArrayOf can be used to determine the allowed types and values within an array. It will run against each element in the array, and will only pass if all items meet at least one of the validation rules.
+
+```js
+enforce([1, 2, 'hello!']).isArrayOf(enforce.isString(), enforce.isNumber());
+```
+
+You can also combine `isArrayOf` with other rules to validate other array properties:
+
+```js
+enforce(someArrayValue)
+  .isArrayOf(enforce.isString(), enforce.isNumber().lessThan(3))
+  .longerThan(2);
+```
+
+And as part of shape:
+
+```js
+enforce({ data: [1, 2, 3] }).shape({
+  data: enforce.isArrayOf(enforce.isNumber()),
+});
+```
+
+## enforce.oneOf()
+
+enforce.oneOf can be used to determine if _exactly_ one of the rules applies. It will run against rule in the array, and will only pass if exactly one rule applies.
+
+```js
+enforce(value).oneOf(
+  enforce.isString(),
+  enforce.isNumber(),
+  enforce.longerThan(1)
+);
+
+/*
+value = 1      -> ✅ (value is a number)
+value = "1"    -> ✅ (value is string)
+value = [1, 2] -> ✅ (value is longer than 1)
+value = "12"   -> 🚨 (value is both a string and longer than 1)
+*/
+```

package/docs/n4s/custom.md

@@ -0,0 +1,52 @@
+# Creating Custom 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".
+
+Rules are called with the argument passed to enforce(x) followed by the arguments passed to `.yourRule(y, z)`.
+
+```js
+enforce.extend({
+  yourRule(x, y, z) {
+    return {
+      pass: true,
+      message: () => '',
+    };
+  },
+});
+```
+
+```js
+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,
+      };
+    }
+  },
+});
+```

package/docs/n4s/external.md

@@ -0,0 +1,54 @@
+# Consuming external rules
+
+Enforce comes with the bare minimum of rules needed for input validation, not assuming your business logic constraints.
+
+In some cases you might require more validations such as `isEmail` or `isPhoneNumber`. Enforce intentionally does not include those, since those validations may not necessarily reflect the way those validations should work in your app.
+
+Luckily, there are numerous packages that can be used along with enforce to add those validations. One of the most popular, and most compatible is `validator.js`.
+
+```
+npm i validator
+```
+
+Validator.js is a pretty big package. To prevent it from unnecessarily increasing your bundle size for rules you don't use, import the ones you use individually.
+
+Then add those rules with `enforce.extend`:
+
+```js
+import isEmail from 'validator/es/lib/isEmail';
+import isMobilePhone from 'validator/es/lib/isMobilePhone';
+
+enforce.extend({ isEmail, isMobilePhone });
+
+enforce('example@example.com').isEmail(); // ✅
+enforce('example[at]example[dot]com').isEmail(); // 🚨
+```
+
+A full list of the supported validator.js rules can be found on [npmjs.com/package/validator](https://www.npmjs.com/package/validator). Some common rules are:
+
+- isAfter
+- isBefore
+- isBtcAddress
+- isCreditCard
+- isCurrency
+- isDate
+- isEmail
+- isFQDN
+- isIBAN
+- isIdentityCard
+- isIP
+- isIPRange
+- isJSON
+- isJWT
+- isMACAddress
+- isMD5
+- isMimeType
+- isMobilePhone
+- isMongoId
+- isPassportNumber
+- isPort
+- isPostalCode
+- isSlug
+- isURL
+- isTaxID
+- isUUID