vest 3.2.4-dev-c9788a → 3.2.7

package/docs/utilities.md

@@ -0,0 +1,105 @@
+# Utilities and helpers
+
+## `classNames` for simplifying UI code
+
+After validating user input, you usually need to also indicate the validation result on the page - most of the times by adding a class to your input element. One of the difficulties you are likely to face is that the logic for setting the class is not always the negation of `hasErrors`.
+
+```js
+const addIsValidClass = !res.hasErrors('fieldName'); // this does not ALWAYS mean 'valid'
+```
+
+What about when the field is skipped or not validated yet? It does not have errors, so `res.hasErrors('fieldName')` will return `false`, and by that logic, you might mistakenly add a `is-valid` class to your element.
+
+In this case you will also need to check if the test actually ran - so:
+
+```js
+const addIsValidClass = res.tests[fieldName] && !res.hasErrors('fieldName');
+```
+
+But this can get pretty cumbersome when added to multiple fields with different criteria (untested, invalid, hasWarning...).
+
+This is what `vest/classNames` is for. It is a tiny utility function, that allows you to specify classnames to be added for each criteria.
+
+The way it works is simple. You call `classNames` with your result object, and the list of classes you want to be added for whenever the field is tested, untested, has warning or is invalid. It then returns a function that when called with a field name, returns a space delimited string of classes. If more than one class applies (both tested and invalid, for example) they will both be added to the string.
+
+```js
+import classNames from 'vest/classNames';
+import suite from './suite';
+
+const res = suite(data);
+
+const cn = classNames(res, {
+  untested: 'is-untested', // will only be applied if the provided field did not run yet
+  tested: 'some-tested-class', // will only be applied if the provided field did run
+  invalid: 'my_invalid_class', // will only be applied if the provided field ran at least once and has an error
+  valid: 'my_valid_class', // will only be applied if the provided field ran at least once does not have errors or warnings
+  warning: 'my_warning_class', // will only be applied if the provided field ran at least once and has a warning
+});
+
+const fieldOneClasses = cn('field_1'); // "is-untested"
+const fieldTwoClasses = cn('field_2'); // "some-tested-class my_invalid_class"
+const fieldThreeClasses = cn('field_3'); // "some-tested-class my_warning_class"
+```
+
+## `any()` for OR relationship tests
+
+Sometimes you need to have `OR` (`||`) relationship in your validations, this is tricky to do on your own, and `any()` simplifies this process.
+
+The general rule for using `any()` in your validation is when you can say: "At least one of the following has to pass".
+
+A good example would be: When your validated field can be either empty (not required), but when field - has to pass some validation.
+
+### Usage
+
+`any()` accepts an infinite number of arguments, all of which are functions. It returns a boolean, that can be used as the return value of a test function.
+
+The only difference is - if any of the supplied tests passes, the success condition is met and `any()` returns true.
+
+```js
+import { create, test, enforce } from 'vest';
+import any from 'vest/any';
+
+create('Checkout', () => {
+  test('coupon', 'When filled, must be at least 5 chars', () =>
+    any(
+      () => enforce(data.coupon).isEmpty(),
+      () => enforce(data.coupon).longerThanOrEquals(5)
+    )
+  );
+});
+```
+
+## `promisify()`
+
+Promisify is a function that enables you to run your async validations as a [Javascript Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+This can be useful when running async validations on the server, or when you do not need the partial validation results.
+
+!> **NOTE** The Promise is resolved when all tests finish running.
+
+### Usage
+
+`promisify()` accepts a validation suite declaration, and returns a function that when called, returns a Promise.
+
+```js
+import { create, test, skipWhen } from 'vest';
+import promisify from 'vest/promisify';
+
+const suite = promisify(
+  create('CreateNewUser', data => {
+    test('email', 'The email already exists', () => doesEmailExist(data.email));
+    test('username', 'The username already exists', () =>
+      doesUsernameExist(data.username)
+    );
+  })
+);
+
+suite(data).then(res => {
+  skipWhen(res.hasErrors('email'), () => {
+    /* ... */
+  });
+
+  skipWhen(res.hasErrors('username'), () => {
+    /* ... */
+  });
+});
+```

package/docs/warn.md

@@ -0,0 +1,82 @@
+# Warn only tests
+
+By default, a failing test has a severity of `error`. Sometimes you may need to lower the severity level of a given test to `warn` so that even when it fails, it should not prevent submission. An example of this would be validating password strength.
+
+To set a test's severity level to `warn`, you need to simply call Vest's warn function from your test body.
+
+```js
+import { create, test, enforce, warn } from 'vest';
+
+const suite = create('Password', data => {
+  test('password', 'A password must have at least 6 characters', () => {
+    enforce(data.password).longerThan(5);
+  }); // this test has a severity level of `error`
+
+  test('password', 'Your password strength is: WEAK', () => {
+    warn();
+
+    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', () => {
+    warn();
+
+    enforce(data.password).matches(
+      /^(?=.*[A-Za-z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]$/
+    );
+  }); // this test has a severity level of `warn`
+});
+
+const validationResult = suite(data);
+```
+
+**Limitations when using warn()**
+
+- You may only use warn from within the body of a `test` function.
+- When using `warn()` in an async test you should call the `warn` function in the sync portion of your test (and not after an `await` call or in the Promise body). Ideally, you want to call `warn()` at the top of your test function.
+
+```js
+// ✔
+test('password', async () => {
+  warn();
+  return await someAsyncFunction();
+});
+
+// ✔
+test('password', () => {
+  warn();
+  return anAsyncFunction();
+});
+
+// 🚨 This will result in an your warn() call not taking effect
+test('password', async () => {
+  await someAsyncFunction();
+
+  warn(); // 🚨
+});
+
+// 🚨 This will result in an your warn() call not taking effect
+test('password', () => {
+  return anAsyncFunction().then(() => {
+    warn(); // 🚨
+  });
+});
+```
+
+### Using warning in the result object
+
+Just like you do with errors, you can access the errors in your validation warnings using these methods:
+
+```js
+result.hasWarnings(); // Returns whether any warnings are present in the suite.
+result.hasWarnings('password'); // Returns whether any warnings are present in the 'password' field.
+
+result.getWarnings(); // Returns an object with all the fields that have warnings, and an array of warnings for each.
+result.getWarnings('password'); // Returns an array of warnings for the password field.
+```
+
+**Read next about:**
+
+- [Vest's result object](./result).

package/enforce.d.ts

@@ -0,0 +1,230 @@
+type EnforceExtendMap<T> = {
+  [K in keyof T]: (...args: any[]) => RuleReturn<T>;
+};
+
+interface IEnforceRunResult {
+  hasErrors?: boolean;
+  hasWarnings?: boolean;
+  message?: string;
+  warn?: boolean | void;
+  isArray?: boolean;
+  children?: {
+    [key: string]: IEnforceRunResult;
+  };
+}
+
+interface ILazy {
+  test: (...args: any[]) => boolean;
+  run: (...args: any[]) => IEnforceRunResult;
+}
+
+interface IEnforceTemplateReturn extends ILazy {
+  (value: any): IEnforceRules;
+}
+
+type RuleReturn<T> = IEnforceRules<T> & EnforceExtendMap<T>;
+
+type TNumeral = number | string;
+type RuleNumeral<T> = (expected: TNumeral) => RuleReturn<T>;
+type RuleRange<T> = (start: TNumeral, end: TNumeral) => RuleReturn<T>;
+type RuleNoExpectedValue<T> = () => RuleReturn<T>;
+type RuleString<T> = (str: string) => RuleReturn<T>;
+type RuleMatches<T> = (expected: string | RegExp) => RuleReturn<T>;
+type RuleAny<T> = (expected: any) => RuleReturn<T>;
+type RuleInside<T> = (
+  expected: Array<string | number | boolean> | string
+) => RuleReturn<T>;
+
+type TLazyOrTemplate = TEnforceLazy | IEnforceTemplateReturn;
+
+type CompoundListOfRules<T> = (...rules: TLazyOrTemplate[]) => RuleReturn<T>;
+type TShapeObject = {
+  [key: string]: TLazyOrTemplate;
+};
+interface IEnforceRules<T = {}> {
+  [key: string]: (...args: any[]) => RuleReturn<T>;
+  equals: RuleAny<T>;
+  notEquals: RuleAny<T>;
+  numberEquals: RuleNumeral<T>;
+  greaterThan: RuleNumeral<T>;
+  greaterThanOrEquals: RuleNumeral<T>;
+  lessThan: RuleNumeral<T>;
+  lessThanOrEquals: RuleNumeral<T>;
+  longerThan: RuleNumeral<T>;
+  longerThanOrEquals: RuleNumeral<T>;
+  shorterThan: RuleNumeral<T>;
+  shorterThanOrEquals: RuleNumeral<T>;
+  gt: RuleNumeral<T>;
+  gte: RuleNumeral<T>;
+  lt: RuleNumeral<T>;
+  lte: RuleNumeral<T>;
+  isBetween: RuleRange<T>;
+  endsWith: RuleString<T>;
+  startsWith: RuleString<T>;
+  doesNotEndWith: RuleString<T>;
+  doesNotStartWith: RuleString<T>;
+  numberNotEquals: RuleNumeral<T>;
+  matches: RuleMatches<T>;
+  notMatches: RuleMatches<T>;
+  isUndefined: RuleNoExpectedValue<T>;
+  isArray: RuleNoExpectedValue<T>;
+  isEmpty: RuleNoExpectedValue<T>;
+  isEven: RuleNoExpectedValue<T>;
+  isBoolean: RuleNoExpectedValue<T>;
+  isNotBoolean: RuleNoExpectedValue<T>;
+  isNumber: RuleNoExpectedValue<T>;
+  isNaN: RuleNoExpectedValue<T>;
+  isNotNaN: RuleNoExpectedValue<T>;
+  isNull: RuleNoExpectedValue<T>;
+  isNotNull: RuleNoExpectedValue<T>;
+  isNumeric: RuleNoExpectedValue<T>;
+  isOdd: RuleNoExpectedValue<T>;
+  isTruthy: RuleNoExpectedValue<T>;
+  isFalsy: RuleNoExpectedValue<T>;
+  isString: RuleNoExpectedValue<T>;
+  isNotArray: RuleNoExpectedValue<T>;
+  isNotEmpty: RuleNoExpectedValue<T>;
+  isNotNumber: RuleNoExpectedValue<T>;
+  isNotNumeric: RuleNoExpectedValue<T>;
+  isNotBetween: RuleRange<T>;
+  isNotString: RuleNoExpectedValue<T>;
+  inside: RuleInside<T>;
+  notInside: RuleInside<T>;
+  lengthEquals: RuleNumeral<T>;
+  lengthNotEquals: RuleNumeral<T>;
+  isNegative: RuleNumeral<T>;
+  isPositive: RuleNumeral<T>;
+  loose: <T>(shape: TShapeObject) => RuleReturn<T>;
+  shape: <T>(
+    shape: TShapeObject,
+    options?: {
+      loose?: boolean;
+    }
+  ) => RuleReturn<T>;
+  isArrayOf: CompoundListOfRules<T>;
+  anyOf: CompoundListOfRules<T>;
+  allOf: CompoundListOfRules<T>;
+  oneOf: CompoundListOfRules<T>;
+}
+
+interface IEnforce {
+  /**
+   * Assertion function. Throws an error on failure.
+   * @param value Value being enforced
+   */
+  (value: any): IEnforceRules;
+
+  /**
+   * Adds custom rules to enforce
+   * @param rules Rules object to add onto enforce
+   *
+   * @example
+   *
+   * const customEnforce = enforce.extend({
+   *  isValidEmail: (email) => email.includes('@')
+   * });
+   *
+   * customEnforce('notAnEmail') // throws an error
+   */
+  extend<
+    T extends {
+      [key: string]: (
+        value: any,
+        ...args: any[]
+      ) =>
+        | boolean
+        | {
+            pass: boolean;
+            message?: string | (() => string);
+          };
+    }
+  >(
+    obj: T
+  ): (value: any) => IEnforceRules<T> & EnforceExtendMap<T>;
+
+  template: (...rules: Array<TLazyOrTemplate>) => IEnforceTemplateReturn;
+}
+
+type LazyNumeral = (expected: TNumeral) => TEnforceLazyReturn;
+type LazyEnforceWithNoArgs = () => TEnforceLazyReturn;
+type LazyString = (str: string) => TEnforceLazyReturn;
+type LazyRange = (start: number, end: number) => TEnforceLazyReturn;
+type LazyMatches = (expected: string | RegExp) => TEnforceLazyReturn;
+type LazyAny = (expected: any) => TEnforceLazyReturn;
+type LazyInside = (
+  expected: Array<string | number | boolean> | string
+) => TEnforceLazyReturn;
+type LazyCopmoundListOfRules = <T>(
+  ...rules: TLazyOrTemplate[]
+) => TEnforceLazyReturn;
+
+type TEnforceLazyReturn = TEnforceLazy & ILazy;
+
+type TEnforceLazy = {
+  [key: string]: (...args: any[]) => TEnforceLazyReturn;
+  equals: LazyAny;
+  notEquals: LazyAny;
+  numberEquals: LazyNumeral;
+  greaterThan: LazyNumeral;
+  greaterThanOrEquals: LazyNumeral;
+  lessThan: LazyNumeral;
+  lessThanOrEquals: LazyNumeral;
+  longerThan: LazyNumeral;
+  longerThanOrEquals: LazyNumeral;
+  shorterThan: LazyNumeral;
+  shorterThanOrEquals: LazyNumeral;
+  gt: LazyNumeral;
+  gte: LazyNumeral;
+  lt: LazyNumeral;
+  lte: LazyNumeral;
+  isBetween: LazyRange;
+  endsWith: LazyString;
+  startsWith: LazyString;
+  doesNotEndWith: LazyString;
+  doesNotStartWith: LazyString;
+  numberNotEquals: LazyNumeral;
+  matches: LazyMatches;
+  notMatches: LazyMatches;
+  isUndefined: LazyEnforceWithNoArgs;
+  isArray: LazyEnforceWithNoArgs;
+  isEmpty: LazyEnforceWithNoArgs;
+  isEven: LazyEnforceWithNoArgs;
+  isNumber: LazyEnforceWithNoArgs;
+  isNaN: LazyEnforceWithNoArgs;
+  isNotNaN: LazyEnforceWithNoArgs;
+  isNull: LazyEnforceWithNoArgs;
+  isNotNull: LazyEnforceWithNoArgs;
+  isNumeric: LazyEnforceWithNoArgs;
+  isOdd: LazyEnforceWithNoArgs;
+  isTruthy: LazyEnforceWithNoArgs;
+  isFalsy: LazyEnforceWithNoArgs;
+  isString: LazyEnforceWithNoArgs;
+  isNotArray: LazyEnforceWithNoArgs;
+  isNotEmpty: LazyEnforceWithNoArgs;
+  isNotNumber: LazyEnforceWithNoArgs;
+  isNotNumeric: LazyEnforceWithNoArgs;
+  isNotBetween: LazyRange;
+  isNotString: LazyEnforceWithNoArgs;
+  inside: LazyInside;
+  notInside: LazyInside;
+  lengthEquals: LazyNumeral;
+  lengthNotEquals: LazyNumeral;
+  isNegative: LazyEnforceWithNoArgs;
+  isPositive: LazyEnforceWithNoArgs;
+  isBoolean: LazyEnforceWithNoArgs;
+  isNotBoolean: LazyEnforceWithNoArgs;
+  loose: <T>(shape: TShapeObject) => TEnforceLazyReturn;
+  shape: <T>(
+    shape: TShapeObject,
+    options?: {
+      loose?: boolean;
+    }
+  ) => TEnforceLazyReturn;
+  optional: LazyCopmoundListOfRules;
+  isArrayOf: LazyCopmoundListOfRules;
+  anyOf: LazyCopmoundListOfRules;
+  allOf: LazyCopmoundListOfRules;
+  oneOf: LazyCopmoundListOfRules;
+};
+
+export type TEnforce = IEnforce & TEnforceLazyReturn;

package/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}