vest 4.0.0-dev-deabb8 → 4.0.0-dev-8851ff

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/node.md CHANGED
@@ -28,7 +28,7 @@ With node 14's support of [package entry points](https://nodejs.org/api/esm.html
28
28
  Both of the following should work:
29
29
 
30
30
  ```js
31
- import { test, enforce } from 'vest';
31
+ import { create, test } from 'vest';
32
32
  ```
33
33
 
34
34
  ```js
package/docs/optional.md CHANGED
@@ -1,16 +1,17 @@
1
1
  # optional fields
2
2
 
3
- > Since 3.2.0
3
+ By default, all the tests inside Vest are required in order for the suite to be considered as "valid". Sometimes your app's logic may allow tests not to be filled out and you want them not to be accounted for in the suites validity.
4
4
 
5
- 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.
6
- All fields are by default required, unless explicitly marked as optional using the `optional` function.
5
+ For cases like this, Vest provides the `optional` function which allows you to mark a a field, or multiple fields as optional. Vest's definition of "optional" is that the field did not have any test runs in the lifetime of the suite.
7
6
 
8
- ## Usage
7
+ If your app requires a more custom logic, please see the [advanced section below](#advanced).
8
+
9
+ ## Basic Usage - allowing tests not to run
9
10
 
10
11
  `optional` can take a field name as its argument, or an array of field names.
11
12
 
12
13
  ```js
13
- import { optional, only, test, enforce, create } from 'vest';
14
+ import { create, optional, only, test, enforce } from 'vest';
14
15
 
15
16
  const suite = create((data, currentField) => {
16
17
  only(currentField); // only validate this specified field
@@ -22,7 +23,7 @@ const suite = create((data, currentField) => {
22
23
  **/
23
24
 
24
25
  test('pet_name', 'Pet Name is required', () => {
25
- enforce(data.name).isNotEmpty();
26
+ enforce(data.pet_name).isNotEmpty();
26
27
  });
27
28
 
28
29
  test('pet_color', 'If provided, pet color must be a string', () => {
@@ -41,6 +42,57 @@ suite({ age: 'Five' }, /* -> only validate pet_age */ 'pet_age').isValid();
41
42
  // 🚨 When erroring, optional fields still make the suite invalid
42
43
  ```
43
44
 
45
+ ## Advanced Usage - Supplying custom omission function :id=advanced
46
+
47
+ Since every app is different, your app's logic may require some other definition of "optional", for example - if the user typed inside the field and then removed its content, or alternatively - if a field may be empty only if a different field is supplied - then Vest cannot be aware of this logic, and you will have to tell Vest to conditionally omit the results for this field by supplying `optional` with a custom omission function.
48
+
49
+ To provide a custom optional function, instead of passing a list of fields, you need to provide an object with predicate functions. These functions will be run when your suite finishes its **synchronous** run, and when they evaluate to true - will omit _any_ failures your field might have from the suite.
50
+
51
+ !> **IMPORTANT** You should avoid using the custom omission function along with async tests. This is unsupported and may cause unexpected behavior. The reason for this limitation is due to the fact that the omission conditionals are calculated at the end of the suite, while the async tests may keep running afterwards. Allowing it will require re-calculation for each async test that finishes, which could be expensive.
52
+
53
+ ### Examples
54
+
55
+ **An example allowing a field to be empty even if its `touched` or `dirty`**
56
+
57
+ ```js
58
+ const suite = create(data => {
59
+ optional({
60
+ pet_name: () => !data.pet_name,
61
+ });
62
+
63
+ test('pet_name', 'Pet Name may be left empty', () => {
64
+ enforce(data.pet_name).isNotEmpty();
65
+ });
66
+ });
67
+ ```
68
+
69
+ **An example allowing a field to be empty if a different field is filled**
70
+
71
+ ```js
72
+ const suite = create(data => {
73
+ optional({
74
+ pet_name: () => !suite.get().hasErrors('owner_name'),
75
+ owner_name: () => !suite.get().hasErrors('pet_name'),
76
+ });
77
+
78
+ test(
79
+ 'pet_name',
80
+ 'Pet Name may be left empty only if owner name is supplied',
81
+ () => {
82
+ enforce(data.pet_name).isNotEmpty();
83
+ }
84
+ );
85
+
86
+ test(
87
+ 'owner_name',
88
+ 'Owner Name may be left empty only if pet name is supplied',
89
+ () => {
90
+ enforce(data.owner_name).isNotEmpty();
91
+ }
92
+ );
93
+ });
94
+ ```
95
+
44
96
  ## Difference between `optional` and `warn`
45
97
 
46
98
  While on its surface, optional might seem similar to warn, they are quite different.
package/docs/result.md CHANGED
@@ -46,12 +46,12 @@ Along with these values, the result object exposes the following methods:
46
46
 
47
47
  ## `isValid` function
48
48
 
49
- `isValid` returns whether the validation suite as a whole is valid or not.
49
+ `isValid` returns whether the validation suite as a whole or a single field is valid or not.
50
50
 
51
- A suite is considered valid if the following conditions are met:
51
+ A _suite_ is considered valid if the following conditions are met:
52
52
 
53
53
  - There are no errors (`hasErrors() === false`) in the suite - warnings are not counted as errors.
54
- - All non optional fields have passing tests.
54
+ - All non [optional](./optional) fields have passing tests.
55
55
  - There are no pending async tests.
56
56
 
57
57
  ```js
@@ -60,6 +60,18 @@ result.isValid();
60
60
  suite.get().isValid();
61
61
  ```
62
62
 
63
+ A _field_ is considered valid if the following conditions are met:
64
+
65
+ - The field has no errors (`hasErrors() === false`) or the field is omitted via the functional "optional" API.
66
+ - All non optional tests for the field are passing.
67
+ - The field has no pending tests.
68
+
69
+ ```js
70
+ result.isValid('username');
71
+
72
+ suite.get().isValid('username');
73
+ ```
74
+
63
75
  ?> **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.
64
76
 
65
77
  ## `hasErrors` and `hasWarnings` functions
@@ -231,3 +243,7 @@ result.done(() => {
231
243
  }
232
244
  });
233
245
  ```
246
+
247
+ ### Read more on:
248
+
249
+ [Optional tests](./optional)
package/docs/state.md CHANGED
@@ -42,9 +42,9 @@ In some cases, such as form reset, you want to discard of previous validation re
42
42
  `.rese()` Is a property on your validation suite, calling it will remove your suite's state.
43
43
 
44
44
  ```js
45
- import * as vest from 'vest';
45
+ import { create } from 'vest';
46
46
 
47
- const suite = vest.create(() => {
47
+ const suite = create(() => {
48
48
  // Your tests go here
49
49
  });
50
50
 
@@ -60,9 +60,9 @@ When your form contains dynamically added fields, for example - when a customer
60
60
  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.
61
61
 
62
62
  ```js
63
- import * as vest from 'vest';
63
+ import { create, test } from 'vest';
64
64
 
65
- const suite = vest.create(() => {
65
+ const suite = create(() => {
66
66
  // Your tests go here
67
67
 
68
68
  test('username', 'must be at least 3 chars long', () => {
@@ -86,10 +86,10 @@ To do that, all you need to do is wrap your suite initialization with a wrapper
86
86
  ### Example
87
87
 
88
88
  ```js
89
- import * as vest from 'vest';
89
+ import { create } from 'vest';
90
90
 
91
91
  function suite(data) {
92
- return vest.create(() => {
92
+ return create(() => {
93
93
  test('username', 'username is required', () => {
94
94
  enforce(data.username).isNotEmpty();
95
95
  });
package/docs/test.md CHANGED
@@ -122,7 +122,7 @@ Memoized tests are almost identical to regular tests, only with the added depend
122
122
  ### Example:
123
123
 
124
124
  ```js
125
- import { test, create } from 'vest';
125
+ import { vest, test } from 'vest';
126
126
  export default create(data => {
127
127
  test.memo(
128
128
  'username',
@@ -137,7 +137,7 @@ export default create(data => {
137
137
 
138
138
  Use test.each when you need to dynamically create tests from data, or when you have multiple tests that have the same overall structure.
139
139
 
140
- test.each takes an array of arrays. The inner array contains the arguments that each of the tests will recieve.
140
+ test.each takes an array of arrays. The inner array contains the arguments that each of the tests will receive.
141
141
 
142
142
  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.
143
143
 
package/docs/utilities.md CHANGED
@@ -60,8 +60,8 @@ A good example would be: When your validated field can be either empty (not requ
60
60
  The only difference is - if any of the supplied tests passes, the success condition is met and `any()` returns true.
61
61
 
62
62
  ```js
63
- import { test, enforce, create } from 'vest';
64
- import { any } from 'anyone';
63
+ import { create, test, enforce } from 'vest';
64
+ import any from 'vest/any';
65
65
 
66
66
  create(() => {
67
67
  test('coupon', 'When filled, must be at least 5 chars', () =>
@@ -85,11 +85,11 @@ This can be useful when running async validations on the server, or when you do
85
85
  `promisify()` accepts a validation suite declaration, and returns a function that when called, returns a Promise.
86
86
 
87
87
  ```js
88
- import * as vest from 'vest';
88
+ import { create, test, skipWhen } from 'vest';
89
89
  import promisify from 'vest/promisify';
90
90
 
91
91
  const suite = promisify(
92
- vest.create(data => {
92
+ create(data => {
93
93
  test('email', 'The email already exists', () => doesEmailExist(data.email));
94
94
  test('username', 'The username already exists', () =>
95
95
  doesUsernameExist(data.username)
@@ -98,12 +98,12 @@ const suite = promisify(
98
98
  );
99
99
 
100
100
  suite(data).then(res => {
101
- if (res.hasErrors('email')) {
101
+ skipWhen(res.hasErrors('email'), () => {
102
102
  /* ... */
103
- }
103
+ });
104
104
 
105
- if (res.hasErrors('username')) {
105
+ skipWhen(res.hasErrors('username'), () => {
106
106
  /* ... */
107
- }
107
+ });
108
108
  });
109
109
  ```
package/docs/warn.md CHANGED
@@ -5,7 +5,7 @@ By default, a failing test has a severity of `error`. Sometimes you may need to
5
5
  To set a test's severity level to `warn`, you need to simply call Vest's warn function from your test body.
6
6
 
7
7
  ```js
8
- import { test, enforce, create, warn } from 'vest';
8
+ import { create, test, enforce, warn } from 'vest';
9
9
 
10
10
  const suite = create(data => {
11
11
  test('password', 'A password must have at least 6 characters', () => {
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "4.0.0-dev-deabb8",
2
+ "version": "4.0.0-dev-8851ff",
3
3
  "license": "MIT",
4
4
  "name": "vest",
5
5
  "author": "ealush",
@@ -11,9 +11,19 @@
11
11
  "main": "./dist/cjs/vest.js",
12
12
  "types": "./types/vest.d.ts",
13
13
  "module": "./dist/es/vest.production.js",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "https://github.com/ealush/vest.git",
17
+ "directory": "packages/vest"
18
+ },
19
+ "bugs": {
20
+ "url": "https://github.com/ealush/vest.git/issues"
21
+ },
22
+ "homepage": "https://vestjs.dev/",
14
23
  "exports": {
15
24
  "./classnames": {
16
25
  "production": {
26
+ "types": "./types/classnames.d.ts",
17
27
  "browser": "./dist/es/classnames.production.js",
18
28
  "umd": "./dist/umd/classnames.production.js",
19
29
  "import": "./dist/es/classnames.production.js",
@@ -23,6 +33,7 @@
23
33
  "default": "./dist/cjs/classnames.production.js"
24
34
  },
25
35
  "development": {
36
+ "types": "./types/classnames.d.ts",
26
37
  "browser": "./dist/es/classnames.development.js",
27
38
  "umd": "./dist/umd/classnames.development.js",
28
39
  "import": "./dist/es/classnames.development.js",
@@ -31,6 +42,7 @@
31
42
  "module": "./dist/es/classnames.development.js",
32
43
  "default": "./dist/cjs/classnames.development.js"
33
44
  },
45
+ "types": "./types/classnames.d.ts",
34
46
  "browser": "./dist/es/classnames.production.js",
35
47
  "umd": "./dist/umd/classnames.production.js",
36
48
  "import": "./dist/es/classnames.production.js",
@@ -41,6 +53,7 @@
41
53
  },
42
54
  "./parser": {
43
55
  "production": {
56
+ "types": "./types/parser.d.ts",
44
57
  "browser": "./dist/es/parser.production.js",
45
58
  "umd": "./dist/umd/parser.production.js",
46
59
  "import": "./dist/es/parser.production.js",
@@ -50,6 +63,7 @@
50
63
  "default": "./dist/cjs/parser.production.js"
51
64
  },
52
65
  "development": {
66
+ "types": "./types/parser.d.ts",
53
67
  "browser": "./dist/es/parser.development.js",
54
68
  "umd": "./dist/umd/parser.development.js",
55
69
  "import": "./dist/es/parser.development.js",
@@ -58,6 +72,7 @@
58
72
  "module": "./dist/es/parser.development.js",
59
73
  "default": "./dist/cjs/parser.development.js"
60
74
  },
75
+ "types": "./types/parser.d.ts",
61
76
  "browser": "./dist/es/parser.production.js",
62
77
  "umd": "./dist/umd/parser.production.js",
63
78
  "import": "./dist/es/parser.production.js",
@@ -68,6 +83,7 @@
68
83
  },
69
84
  "./promisify": {
70
85
  "production": {
86
+ "types": "./types/promisify.d.ts",
71
87
  "browser": "./dist/es/promisify.production.js",
72
88
  "umd": "./dist/umd/promisify.production.js",
73
89
  "import": "./dist/es/promisify.production.js",
@@ -77,6 +93,7 @@
77
93
  "default": "./dist/cjs/promisify.production.js"
78
94
  },
79
95
  "development": {
96
+ "types": "./types/promisify.d.ts",
80
97
  "browser": "./dist/es/promisify.development.js",
81
98
  "umd": "./dist/umd/promisify.development.js",
82
99
  "import": "./dist/es/promisify.development.js",
@@ -85,6 +102,7 @@
85
102
  "module": "./dist/es/promisify.development.js",
86
103
  "default": "./dist/cjs/promisify.development.js"
87
104
  },
105
+ "types": "./types/promisify.d.ts",
88
106
  "browser": "./dist/es/promisify.production.js",
89
107
  "umd": "./dist/umd/promisify.production.js",
90
108
  "import": "./dist/es/promisify.production.js",
@@ -94,6 +112,17 @@
94
112
  "default": "./dist/cjs/promisify.js"
95
113
  },
96
114
  ".": {
115
+ "development": {
116
+ "types": "./types/vest.d.ts",
117
+ "browser": "./dist/es/vest.development.js",
118
+ "umd": "./dist/umd/vest.development.js",
119
+ "import": "./dist/es/vest.development.js",
120
+ "require": "./dist/cjs/vest.development.js",
121
+ "node": "./dist/cjs/vest.development.js",
122
+ "module": "./dist/es/vest.development.js",
123
+ "default": "./dist/cjs/vest.development.js"
124
+ },
125
+ "types": "./types/vest.d.ts",
97
126
  "browser": "./dist/es/vest.production.js",
98
127
  "umd": "./dist/umd/vest.production.js",
99
128
  "import": "./dist/es/vest.production.js",
@@ -104,14 +133,5 @@
104
133
  },
105
134
  "./package.json": "./package.json",
106
135
  "./": "./"
107
- },
108
- "repository": {
109
- "type": "git",
110
- "url": "https://github.com/ealush/vest.git",
111
- "directory": "packages/vest"
112
- },
113
- "bugs": {
114
- "url": "https://github.com/ealush/vest.git/issues"
115
- },
116
- "homepage": "https://vestjs.dev/"
136
+ }
117
137
  }
@@ -3,10 +3,19 @@ import { useTestObjects } from 'stateHooks';
3
3
 
4
4
  export function emptyTestObjects(): void {
5
5
  const [, setTestObjects] = useTestObjects();
6
- setTestObjects(() => []);
6
+ setTestObjects(({ prev }) => ({ prev, current: [] }));
7
7
  }
8
8
 
9
9
  export function setTestObjects(...args: VestTest[]): void {
10
10
  const [, setTestObjects] = useTestObjects();
11
- setTestObjects(() => [...args]);
11
+ setTestObjects(({ prev }) => ({ prev, current: [...args] }));
12
+ }
13
+
14
+ export function addTestObject(addedTests: VestTest[] | VestTest): void {
15
+ const [, setTestObjects] = useTestObjects();
16
+
17
+ setTestObjects(({ prev, current }) => ({
18
+ prev,
19
+ current: current.concat(addedTests),
20
+ }));
12
21
  }
package/types/vest.d.ts CHANGED
@@ -58,6 +58,7 @@ declare function inside(value: unknown, arg1: string | unknown[]): boolean;
58
58
  // We may need to revisit this in the future.
59
59
  declare function isArray(value: unknown): value is Array<unknown>;
60
60
  declare function isBetween(value: number | string, min: number | string, max: number | string): boolean;
61
+ declare function isBlank(value: unknown): boolean;
61
62
  declare function isBoolean(value: unknown): value is boolean;
62
63
  declare function isEmpty(value: unknown): boolean;
63
64
  declare function isNaN(value: unknown): boolean;
@@ -94,6 +95,7 @@ declare const baseRules: {
94
95
  inside: typeof inside;
95
96
  isArray: typeof isArray;
96
97
  isBetween: typeof isBetween;
98
+ isBlank: typeof isBlank;
97
99
  isBoolean: typeof isBoolean;
98
100
  isEmpty: typeof isEmpty;
99
101
  isEven: (value: any) => boolean;
@@ -102,6 +104,7 @@ declare const baseRules: {
102
104
  isNegative: typeof isNegative;
103
105
  isNotArray: (value: unknown) => boolean;
104
106
  isNotBetween: (value: string | number, min: string | number, max: string | number) => boolean;
107
+ isNotBlank: (value: unknown) => boolean;
105
108
  isNotBoolean: (value: unknown) => boolean;
106
109
  isNotEmpty: (value: unknown) => boolean;
107
110
  isNotNaN: (value: unknown) => boolean;
@@ -250,12 +253,15 @@ declare class VestTest {
250
253
  fail(): void;
251
254
  done(): void;
252
255
  warn(): void;
256
+ isFinalStatus(): boolean;
253
257
  skip(): void;
254
258
  cancel(): void;
259
+ omit(): void;
255
260
  valueOf(): boolean;
256
261
  hasFailures(): boolean;
257
262
  isPending(): boolean;
258
263
  isTested(): boolean;
264
+ isOmitted(): boolean;
259
265
  isUntested(): boolean;
260
266
  isFailing(): boolean;
261
267
  isCanceled(): boolean;
@@ -266,7 +272,7 @@ declare class VestTest {
266
272
  type TAsyncTest = Promise<string | void>;
267
273
  type TTestResult = TAsyncTest | boolean | void;
268
274
  type TTestFn = () => TTestResult;
269
- type KStatus = "UNTESTED" | "SKIPPED" | "FAILED" | "WARNING" | "PASSING" | "PENDING" | "CANCELED";
275
+ type KStatus = "UNTESTED" | "SKIPPED" | "FAILED" | "WARNING" | "PASSING" | "PENDING" | "CANCELED" | "OMITTED";
270
276
  type TExclusionItem = string | string[] | undefined;
271
277
  /**
272
278
  * Adds a field or multiple fields to inclusion group.
@@ -282,16 +288,18 @@ declare function skip(item: TExclusionItem): void;
282
288
  declare namespace skip {
283
289
  var group: (item: TExclusionItem) => void;
284
290
  }
291
+ declare function skipWhen(conditional: boolean | ((...args: any[]) => boolean), callback: (...args: any[]) => void): void;
285
292
  /**
286
293
  * Sets a running test to warn only mode.
287
294
  */
288
295
  declare function warn(): void;
289
- declare function skipWhen(conditional: boolean | ((...args: any[]) => boolean), callback: (...args: any[]) => void): void;
290
296
  /**
291
297
  * Runs a group callback.
292
298
  */
293
299
  declare function group(groupName: string, tests: () => void): void;
294
- declare function optional$0(optionals: string | string[]): void;
300
+ declare function optional$0(optionals: TOptionalsInput): void;
301
+ type TOptionalsInput = string | string[] | TOptionalsObject;
302
+ type TOptionalsObject = Record<string, () => boolean>;
295
303
  declare function testBase(fieldName: string, ...args: [
296
304
  message: string,
297
305
  cb: TTestFn
@@ -310,5 +318,5 @@ declare const _default: typeof testBase & {
310
318
  };
311
319
  };
312
320
  declare const test: typeof _default;
313
- declare const VERSION = "4.0.0-dev-deabb8";
321
+ declare const VERSION = "4.0.0-dev-8851ff";
314
322
  export { test, create, only, skip, warn, group, optional$0 as optional, skipWhen, enforce, VERSION };