validator-fns 3.0.0-next.1 → 3.0.0-next.2
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/README.md +187 -93
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +195 -138
- package/dist/index.d.ts +195 -138
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/runkit.cjs +20 -16
package/README.md
CHANGED
|
@@ -10,9 +10,11 @@ Small asynchronous validation library. Tries to be as small as possible and use
|
|
|
10
10
|
|
|
11
11
|
- [Install](#install)
|
|
12
12
|
- [Usage](#usage)
|
|
13
|
+
- [Migrating from 2.x](#migrating-from-2x)
|
|
13
14
|
- [API Reference](#api-reference)
|
|
14
15
|
- [Validation result](#validation-result)
|
|
15
16
|
- [Validation error message](#validation-error-message)
|
|
17
|
+
- [Required and optional values](#required-and-optional-values)
|
|
16
18
|
- [Validation types](#validation-types)
|
|
17
19
|
- [Validation tests](#validation-tests)
|
|
18
20
|
- [Custom validation](#custom-validation)
|
|
@@ -30,7 +32,9 @@ yarn add validator-fns
|
|
|
30
32
|
|
|
31
33
|
## Usage
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
> **Upgrading from 2.x?** Every validator is now required unless you wrap it in `optional()`, and `required()` is gone. See [Migrating from 2.x](#migrating-from-2x).
|
|
36
|
+
|
|
37
|
+
Every type validator rejects a missing value unless it's wrapped in `optional()`. This is a fairly exhaustive example of what's possible with `validator-fns`.
|
|
34
38
|
|
|
35
39
|
<details><summary>example</summary>
|
|
36
40
|
|
|
@@ -38,6 +42,7 @@ This is a fairly exhaustive example of what's possible with `validator-fns`.
|
|
|
38
42
|
import {
|
|
39
43
|
array,
|
|
40
44
|
boolean,
|
|
45
|
+
createValidator,
|
|
41
46
|
date,
|
|
42
47
|
email,
|
|
43
48
|
exact,
|
|
@@ -50,7 +55,7 @@ import {
|
|
|
50
55
|
number,
|
|
51
56
|
object,
|
|
52
57
|
oneOf,
|
|
53
|
-
|
|
58
|
+
optional,
|
|
54
59
|
string,
|
|
55
60
|
url,
|
|
56
61
|
valid,
|
|
@@ -64,7 +69,7 @@ const TEN_DAYS = ONE_DAY * 10;
|
|
|
64
69
|
const now = new Date();
|
|
65
70
|
const tenDaysFromNow = new Date(now.getTime() + TEN_DAYS);
|
|
66
71
|
|
|
67
|
-
|
|
72
|
+
const customValidator = createValidator(async (value, field) => {
|
|
68
73
|
if (value === 'hello') {
|
|
69
74
|
return valid({ value, field });
|
|
70
75
|
}
|
|
@@ -73,24 +78,23 @@ function customValidator(value, field) {
|
|
|
73
78
|
value,
|
|
74
79
|
field,
|
|
75
80
|
});
|
|
76
|
-
}
|
|
81
|
+
});
|
|
77
82
|
|
|
78
83
|
const validate = object({
|
|
79
|
-
firstName: string(
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
),
|
|
84
|
+
firstName: string({
|
|
85
|
+
trim: true,
|
|
86
|
+
requiredMessage: 'First name is required.',
|
|
87
|
+
}),
|
|
83
88
|
emailAddress: string(
|
|
84
|
-
|
|
89
|
+
{ requiredMessage: 'Email address is required.' },
|
|
85
90
|
email('Must be a valid email address.'),
|
|
86
91
|
),
|
|
87
92
|
age: number(
|
|
88
|
-
{ round: 'floor' },
|
|
89
|
-
required('Age is required.'),
|
|
93
|
+
{ round: 'floor', requiredMessage: 'Age is required.' },
|
|
90
94
|
integer('Age must be a whole number.'),
|
|
91
95
|
min(18, 'Must be at least {min} years old.'),
|
|
92
96
|
),
|
|
93
|
-
homepage: string(url('Must be a valid URL.', ['http:', 'https:'])),
|
|
97
|
+
homepage: optional(string(url('Must be a valid URL.', ['http:', 'https:']))),
|
|
94
98
|
fruit: string(
|
|
95
99
|
{ default: 'apple' },
|
|
96
100
|
oneOf(
|
|
@@ -101,7 +105,7 @@ const validate = object({
|
|
|
101
105
|
favoriteCarMakers: array(
|
|
102
106
|
{ default: [] },
|
|
103
107
|
string(
|
|
104
|
-
|
|
108
|
+
{ requiredMessage: 'Car brand is required.' },
|
|
105
109
|
oneOf(
|
|
106
110
|
[
|
|
107
111
|
'BMW',
|
|
@@ -122,16 +126,20 @@ const validate = object({
|
|
|
122
126
|
min(2, 'Must pick at least two.'),
|
|
123
127
|
max(4, 'Must pick at most four.'),
|
|
124
128
|
),
|
|
125
|
-
startDate:
|
|
126
|
-
|
|
127
|
-
|
|
129
|
+
startDate: optional(
|
|
130
|
+
date(
|
|
131
|
+
minDate(now, 'Must be on or after today.'),
|
|
132
|
+
maxDate(tenDaysFromNow, 'Must be at most ten days from now.'),
|
|
133
|
+
),
|
|
128
134
|
),
|
|
129
|
-
optIn: boolean(
|
|
135
|
+
optIn: boolean({ requiredMessage: 'Must decide to opt in or out.' }),
|
|
130
136
|
notRobot: number(
|
|
131
|
-
|
|
137
|
+
{ requiredMessage: 'Must enter the correct answer.' },
|
|
132
138
|
exact(42, 'This is the answer.'),
|
|
133
139
|
),
|
|
134
|
-
postalCode:
|
|
140
|
+
postalCode: optional(
|
|
141
|
+
string(matches(/^[0-9]{5}$/, 'Must be a five-digit number.')),
|
|
142
|
+
),
|
|
135
143
|
custom: customValidator,
|
|
136
144
|
});
|
|
137
145
|
|
|
@@ -161,6 +169,50 @@ if (result.state === 'valid') {
|
|
|
161
169
|
|
|
162
170
|
</details>
|
|
163
171
|
|
|
172
|
+
## Migrating from 2.x
|
|
173
|
+
|
|
174
|
+
Version 3 makes every type validator required by default. In 2.x, a validator without `required()` accepted `undefined`, `null` and the other missing values; in 3.x, it rejects them with `'Required.'`.
|
|
175
|
+
|
|
176
|
+
1. **Move each `required(message)` into the config as `requiredMessage`**, merging it into a config object that's already there:
|
|
177
|
+
|
|
178
|
+
```js
|
|
179
|
+
// 2.x
|
|
180
|
+
string(required('Enter a name.'), min(2, 'Too short.'));
|
|
181
|
+
number({ round: 'floor' }, required('Enter your age.'));
|
|
182
|
+
array(string(), required('Pick some.'));
|
|
183
|
+
|
|
184
|
+
// 3.x
|
|
185
|
+
string({ requiredMessage: 'Enter a name.' }, min(2, 'Too short.'));
|
|
186
|
+
number({ round: 'floor', requiredMessage: 'Enter your age.' });
|
|
187
|
+
array({ requiredMessage: 'Pick some.' }, string());
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
2. **Wrap each validator that had no `required()` in `optional()`**, or it now rejects a missing value:
|
|
191
|
+
|
|
192
|
+
```js
|
|
193
|
+
// 2.x
|
|
194
|
+
string(email('Must be an email.'));
|
|
195
|
+
|
|
196
|
+
// 3.x
|
|
197
|
+
optional(string(email('Must be an email.')));
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
3. **Replace `required(message, true)`** (nullable): `optional()` accepts `null`, as well as the other missing values.
|
|
201
|
+
4. **Check `object()` calls with a second argument**: it's a config object or the first object-level test, as in `object(schema, { requiredMessage }, ...tests)`. A missing object now fails with its `requiredMessage` instead of reporting each field as missing; wrap it in `optional()` to accept one.
|
|
202
|
+
5. **Replace `standard()`**: remove it around built-in validators, which are Standard Schemas themselves, and change `standard(fn)` to `createValidator(fn)`:
|
|
203
|
+
|
|
204
|
+
```js
|
|
205
|
+
// 2.x
|
|
206
|
+
standard(object({ email: string() }));
|
|
207
|
+
standard(async (value, field) => valid({ value, field }));
|
|
208
|
+
|
|
209
|
+
// 3.x
|
|
210
|
+
object({ email: string() });
|
|
211
|
+
createValidator(async (value, field) => valid({ value, field }));
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
6. **In TypeScript**, a valid result's `value` no longer includes `null` or `undefined` unless the validator is wrapped in `optional()`, and `object()` makes only `optional()` keys optional. `valid()` takes a value of the validator's type, so a custom validator that returns `null` or `undefined` needs them in its type, such as `ValidatorTest<string | undefined>`.
|
|
215
|
+
|
|
164
216
|
## API Reference
|
|
165
217
|
|
|
166
218
|
### Validation result
|
|
@@ -187,24 +239,55 @@ The `message` argument in the validation tests must be a static string, a templa
|
|
|
187
239
|
|
|
188
240
|
The parsed `value` is always provided. If available, `field` is also provided. Depending on the validator, additional fields may be available.
|
|
189
241
|
|
|
242
|
+
### Required and optional values
|
|
243
|
+
|
|
244
|
+
Every validation type rejects a missing value: `undefined`, `null`, an empty string `''`, `NaN`, or an invalid date. It checks after parsing and `default`, so `string({ trim: true })` treats `' '` as missing, `number()` treats a blank string as missing, and a `default` fills a missing value before the check. The tests only run on present values.
|
|
245
|
+
|
|
246
|
+
The message is `'Required.'` unless the config sets `requiredMessage`, which takes a [validation error message](#validation-error-message):
|
|
247
|
+
|
|
248
|
+
```js
|
|
249
|
+
await string()('');
|
|
250
|
+
// { state: 'invalid', message: 'Required.', value: '', ... }
|
|
251
|
+
|
|
252
|
+
await number({ requiredMessage: '{field} is required.' })(undefined, 'age');
|
|
253
|
+
// { state: 'invalid', message: 'age is required.', ... }
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
#### optional(validator)
|
|
257
|
+
|
|
258
|
+
Returns a validator that accepts a missing value. The missing value skips the tests and becomes the result's `value` as parsed, so `optional(number())('')` is valid with `NaN`. Present values go through `validator` as usual. The validator passed in is unchanged.
|
|
259
|
+
|
|
260
|
+
```js
|
|
261
|
+
const nickname = optional(string(min(2, 'Too short.')));
|
|
262
|
+
|
|
263
|
+
await nickname(undefined); // { state: 'valid', value: undefined, ... }
|
|
264
|
+
await nickname('a'); // { state: 'invalid', message: 'Too short.', ... }
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
For a custom validator, `optional()` accepts `undefined` and `null` without calling it, and passes every other value to it.
|
|
268
|
+
|
|
269
|
+
In TypeScript, a validator's value type is `T`, and `optional()` adds `null` and `undefined`. In `object()`, a key is optional when its validator's value type includes `undefined`, so `object({ name: string(), age: optional(number()) })` is typed `{ name: string; age?: number | null | undefined }`.
|
|
270
|
+
|
|
190
271
|
### Validation types
|
|
191
272
|
|
|
192
|
-
A **validation type** is expected to parse and prepare the value for the provided validation tests. For example, the `string` validation type ensures the provided value is a string,
|
|
273
|
+
A **validation type** is expected to parse and prepare the value for the provided validation tests. For example, the `string` validation type ensures the provided value is a string, and rejects a missing value unless wrapped in [`optional()`](#optionalvalidator). It must be a function that takes a value of any type and returns a promise which resolves to a validation result (see above).
|
|
193
274
|
|
|
194
275
|
- [array(config?, itemTest, ...tests)](#arrayconfig-itemtest-tests)
|
|
195
276
|
- [boolean(config?, ...tests)](#booleanconfig-tests)
|
|
196
277
|
- [date(config?, ...tests)](#dateconfig-tests)
|
|
197
278
|
- [number(config?, ...tests)](#numberconfig-tests)
|
|
198
|
-
- [object(schema, ...tests)](#objectschema-tests)
|
|
279
|
+
- [object(schema, config?, ...tests)](#objectschema-config-tests)
|
|
199
280
|
- [string(config?, ...tests)](#stringconfig-tests)
|
|
200
281
|
|
|
282
|
+
Every validation type, and every validator `optional()` returns, is also a [Standard Schema][standard-schema], so libraries that accept one can use it directly. See [createValidator(fn)](#createvalidatorfn) for how results map to issues. In TypeScript, their type is `TypeValidator<T, E>`: a `ValidatorTest<T, E>` with a `~standard` property.
|
|
283
|
+
|
|
201
284
|
#### array(config?, itemTest, ...tests)
|
|
202
285
|
|
|
203
|
-
Casts value to an array, `null` or `undefined` if using the default
|
|
286
|
+
Casts value to an array, or keeps `null` or `undefined` if using the default array parser. `config` is optional. `itemTest` is the validation type or test to be applied on each value within the array value. All remaining `tests` are applied to the array as a whole.
|
|
204
287
|
|
|
205
288
|
A valid result's `value` holds each item as `itemTest` returned it, so `array(number())` turns `['1', '2.5']` into `[1, 2.5]`, and `array(string({ trim: true }))` trims each item.
|
|
206
289
|
|
|
207
|
-
Supported validation tests: `max
|
|
290
|
+
Supported validation tests: `max` and `min`.
|
|
208
291
|
|
|
209
292
|
For invalid results, errors are in the `errors` property. It is an array of type:
|
|
210
293
|
|
|
@@ -216,40 +299,43 @@ Where valid entries are represented as `null` and invalid entries with the error
|
|
|
216
299
|
|
|
217
300
|
<details><summary>config</summary>
|
|
218
301
|
|
|
219
|
-
| option
|
|
220
|
-
|
|
|
221
|
-
| `default`
|
|
222
|
-
| `
|
|
302
|
+
| option | type | description |
|
|
303
|
+
| :---------------- | :----------------- | :-------------------------------------------------------------------------------------- |
|
|
304
|
+
| `default` | string | Optional. Value used if the parser returns `undefined`, `null`, or an empty array `[]`. |
|
|
305
|
+
| `requiredMessage` | string or function | Optional. Message for a missing value. Defaults to `'Required.'`. |
|
|
306
|
+
| `parser` | function | Optional. Used to customize how a value is converted into a string. |
|
|
223
307
|
|
|
224
308
|
</details>
|
|
225
309
|
|
|
226
310
|
#### boolean(config?, ...tests)
|
|
227
311
|
|
|
228
|
-
Casts value to a boolean, `null` or `undefined` if using the default boolean parser. `config` is optional.
|
|
312
|
+
Casts value to a boolean, or keeps `null` or `undefined` if using the default boolean parser. `config` is optional.
|
|
229
313
|
|
|
230
|
-
Supported validation tests: `oneOf
|
|
314
|
+
Supported validation tests: `oneOf`.
|
|
231
315
|
|
|
232
316
|
<details><summary>config</summary>
|
|
233
317
|
|
|
234
|
-
| option
|
|
235
|
-
|
|
|
236
|
-
| `default`
|
|
237
|
-
| `
|
|
318
|
+
| option | type | description |
|
|
319
|
+
| :---------------- | :----------------- | :------------------------------------------------------------------- |
|
|
320
|
+
| `default` | boolean | Optional. Value used if the parser returns `undefined` or `null`. |
|
|
321
|
+
| `requiredMessage` | string or function | Optional. Message for a missing value. Defaults to `'Required.'`. |
|
|
322
|
+
| `parser` | function | Optional. Used to customize how a value is converted into a boolean. |
|
|
238
323
|
|
|
239
324
|
</details>
|
|
240
325
|
|
|
241
326
|
#### date(config?, ...tests)
|
|
242
327
|
|
|
243
|
-
Casts value to a date, `null` or `undefined` if using the default date parser. `config` is optional.
|
|
328
|
+
Casts value to a date, or keeps `null` or `undefined` if using the default date parser. A string that isn't ISO 8601, such as `'tomorrow'`, and input that isn't a `Date`, number, or string, such as `true` or `{}`, give an invalid result with the message `Failed to parse value to date.`. A blank string and an invalid `Date` become an invalid date, which counts as missing. `config` is optional.
|
|
244
329
|
|
|
245
|
-
Supported validation tests: `maxDate`, `minDate`,
|
|
330
|
+
Supported validation tests: `maxDate`, `minDate`, and `oneOf`.
|
|
246
331
|
|
|
247
332
|
<details><summary>config</summary>
|
|
248
333
|
|
|
249
|
-
| option
|
|
250
|
-
|
|
|
251
|
-
| `default`
|
|
252
|
-
| `
|
|
334
|
+
| option | type | description |
|
|
335
|
+
| :---------------- | :----------------- | :---------------------------------------------------------------------------------- |
|
|
336
|
+
| `default` | date | Optional. Value used if the parser returns `undefined`, `null`, or an invalid date. |
|
|
337
|
+
| `requiredMessage` | string or function | Optional. Message for a missing value. Defaults to `'Required.'`. |
|
|
338
|
+
| `parser` | function | Optional. Used to customize how a value is converted into a date. |
|
|
253
339
|
|
|
254
340
|
The default parser only accepts dates, numbers, and a subset of [ISO 8601][iso8601] formatted strings (excludes week formats). If you want to allow other or more complex formats you should use a third-party library such as [date-fns][date-fns].
|
|
255
341
|
|
|
@@ -257,37 +343,38 @@ The default parser only accepts dates, numbers, and a subset of [ISO 8601][iso86
|
|
|
257
343
|
|
|
258
344
|
#### number(config?, ...tests)
|
|
259
345
|
|
|
260
|
-
Casts value to a number, `null` or `undefined` if using the default number parser. `config` is optional.
|
|
346
|
+
Casts value to a number, or keeps `null` or `undefined` if using the default number parser. `config` is optional.
|
|
261
347
|
|
|
262
|
-
The default parser accepts numbers, bigints, dates (as their timestamp), strings that start with a number (read with `parseFloat`, so `'12px'` is `12`), and `Number` or `String` objects holding one. A blank string (`''` or only whitespace) gives `NaN`, which
|
|
348
|
+
The default parser accepts numbers, bigints, dates (as their timestamp), strings that start with a number (read with `parseFloat`, so `'12px'` is `12`), and `Number` or `String` objects holding one. A blank string (`''` or only whitespace) gives `NaN`, which counts as missing and which `default` replaces. Any other input gives an invalid result with the message `Failed to parse value to number.`: strings without a leading number, such as `'abc'`, booleans, symbols, and objects other than the ones above, arrays and functions included.
|
|
263
349
|
|
|
264
|
-
Supported validation tests: `exact`, `integer`, `max`, `min`,
|
|
350
|
+
Supported validation tests: `exact`, `integer`, `max`, `min`, and `oneOf`.
|
|
265
351
|
|
|
266
352
|
<details><summary>config</summary>
|
|
267
353
|
|
|
268
|
-
| option
|
|
269
|
-
|
|
|
270
|
-
| `round`
|
|
271
|
-
| `default`
|
|
272
|
-
| `
|
|
354
|
+
| option | type | description |
|
|
355
|
+
| :---------------- | :----------------- | :----------------------------------------------------------------------------------------- |
|
|
356
|
+
| `round` | string | Optional. Rounding method to use, one of `nearest`, `ceil`, `floor` |
|
|
357
|
+
| `default` | number | Optional. Value used if the parser returns `undefined`, `null` or an invalid number `NaN`. |
|
|
358
|
+
| `requiredMessage` | string or function | Optional. Message for a missing value. Defaults to `'Required.'`. |
|
|
359
|
+
| `parser` | function | Optional. Used to customize how a value is converted into a number. |
|
|
273
360
|
|
|
274
361
|
</details>
|
|
275
362
|
|
|
276
|
-
#### object(schema, ...tests)
|
|
363
|
+
#### object(schema, config?, ...tests)
|
|
277
364
|
|
|
278
|
-
The only validation type that does not cast the entered value, meaning it does not use a parser. There's also no default fallback value option here. Instead, the schema is an object where its properties are validation types such as `string`, `array`, `number`, etc. Nested `object` validators are allowed, but not recommended due to their complexity and potential performance hit.
|
|
365
|
+
The only validation type that does not cast the entered value, meaning it does not use a parser. There's also no default fallback value option here. `config` is optional; when the second argument is a function, it's the first of the `tests`. A missing object, `undefined` or `null`, fails with `config.requiredMessage`, or `'Required.'`, without checking its fields. Instead, the schema is an object where its properties are validation types such as `string`, `array`, `number`, etc. Nested `object` validators are allowed, but not recommended due to their complexity and potential performance hit.
|
|
279
366
|
|
|
280
367
|
For invalid results, errors are in the `errors` property. It matches the provided object with the same keys and strings or string records as values that contain the error messages.
|
|
281
368
|
|
|
282
|
-
In TypeScript,
|
|
369
|
+
In TypeScript, a field of the valid value is required unless its validator is wrapped in `optional()`, as in `{ name: string; age?: number | null | undefined }`. A missing optional field is still set on the value, as `undefined`.
|
|
283
370
|
|
|
284
371
|
The remaining `tests` are object-level tests. They run in order on the parsed object, only once every property is valid, and the first failure becomes the result. Use [`check`](#checkpath-test-message) to compare fields and put the error on one of them:
|
|
285
372
|
|
|
286
373
|
```ts
|
|
287
374
|
const signup = object(
|
|
288
375
|
{
|
|
289
|
-
password: string(
|
|
290
|
-
confirm: string(
|
|
376
|
+
password: string(),
|
|
377
|
+
confirm: string(),
|
|
291
378
|
},
|
|
292
379
|
check('confirm', (value) => value.confirm === value.password, 'Must match.'),
|
|
293
380
|
);
|
|
@@ -298,29 +385,38 @@ await signup({ password: 'secret', confirm: 'other' });
|
|
|
298
385
|
|
|
299
386
|
A field's own error takes precedence: object-level tests don't run while any property is invalid, so they always compare valid, parsed values.
|
|
300
387
|
|
|
388
|
+
<details><summary>config</summary>
|
|
389
|
+
|
|
390
|
+
| option | type | description |
|
|
391
|
+
| :---------------- | :----------------- | :----------------------------------------------------------------- |
|
|
392
|
+
| `requiredMessage` | string or function | Optional. Message for a missing object. Defaults to `'Required.'`. |
|
|
393
|
+
|
|
394
|
+
</details>
|
|
395
|
+
|
|
301
396
|
To use this with a library such as [Formik][formik], you can use the resulting `errors` property. It is a key-value structure with the schema property keys and their validation errors if any. Besides that, the object validation results are the same as described above.
|
|
302
397
|
|
|
303
398
|
#### string(config?, ...tests)
|
|
304
399
|
|
|
305
|
-
Casts value to a string, `null` or `undefined` if using the default string parser. `config` is optional.
|
|
400
|
+
Casts value to a string, or keeps `null` or `undefined` if using the default string parser. `config` is optional.
|
|
306
401
|
|
|
307
402
|
The default parser accepts strings, numbers, bigints, booleans, dates (as an ISO string), and `String`, `Number`, or `Boolean` objects. Any other object, including arrays and functions, and symbols give an invalid result with the message `Failed to parse value to string.`
|
|
308
403
|
|
|
309
|
-
Supported validation tests: `email`, `exact`, `matches`, `max`, `min`, `oneOf`, `
|
|
404
|
+
Supported validation tests: `email`, `exact`, `matches`, `max`, `min`, `oneOf`, `url`, and `uuid`.
|
|
310
405
|
|
|
311
406
|
<details><summary>config</summary>
|
|
312
407
|
|
|
313
|
-
| option
|
|
314
|
-
|
|
|
315
|
-
| `trim`
|
|
316
|
-
| `default`
|
|
317
|
-
| `
|
|
408
|
+
| option | type | description |
|
|
409
|
+
| :---------------- | :----------------- | :--------------------------------------------------------------------------------------- |
|
|
410
|
+
| `trim` | boolean | Optional. If true, clears whitespace from the start and end of the string. |
|
|
411
|
+
| `default` | string | Optional. Value used if the parser returns `undefined`, `null`, or an empty string `''`. |
|
|
412
|
+
| `requiredMessage` | string or function | Optional. Message for a missing value. Defaults to `'Required.'`. |
|
|
413
|
+
| `parser` | function | Optional. Used to customize how a value is converted into a string. |
|
|
318
414
|
|
|
319
415
|
</details>
|
|
320
416
|
|
|
321
417
|
### Validation tests
|
|
322
418
|
|
|
323
|
-
A **validation test** is a simplified version of a validation type. It accepts a value of a specific type
|
|
419
|
+
A **validation test** is a simplified version of a validation type. It accepts a value of a specific type and returns a promise that resolves to a validation result. Validation types only run tests on present values; called directly, the built-in tests pass `null` and `undefined` through. You can use a validation test directly without the validation type, but it's not recommended as you lose the parsing step and you can't apply multiple tests to the same field as easily.
|
|
324
420
|
|
|
325
421
|
- [check(path?, test, message)](#checkpath-test-message)
|
|
326
422
|
- [email(message)](#emailmessage)
|
|
@@ -332,7 +428,6 @@ A **validation test** is a simplified version of a validation type. It accepts a
|
|
|
332
428
|
- [min(limit, message, exclusive?)](#minlimit-message-exclusive)
|
|
333
429
|
- [minDate(limit, message, exclusive?)](#mindatelimit-message-exclusive)
|
|
334
430
|
- [oneOf(values, message)](#oneofvalues-message)
|
|
335
|
-
- [required(message, nullable?)](#requiredmessage-nullable)
|
|
336
431
|
- [url(message, protocols?)](#urlmessage-protocols)
|
|
337
432
|
- [uuid(message)](#uuidmessage)
|
|
338
433
|
|
|
@@ -469,19 +564,6 @@ Ensures value is one of the specified values. Works with strings, arrays, boolea
|
|
|
469
564
|
|
|
470
565
|
</details>
|
|
471
566
|
|
|
472
|
-
#### required(message, nullable?)
|
|
473
|
-
|
|
474
|
-
Ensures value is **not** one of: `undefined`, `null`, `NaN`, an empty string, or an invalid date. Works with all types.
|
|
475
|
-
|
|
476
|
-
<details><summary>arguments</summary>
|
|
477
|
-
|
|
478
|
-
| name | type | description |
|
|
479
|
-
| :--------- | :----------------- | :-------------------------------- |
|
|
480
|
-
| `message` | string or function | The validation error message. |
|
|
481
|
-
| `nullable` | boolean | Optional. If true, allows `null`. |
|
|
482
|
-
|
|
483
|
-
</details>
|
|
484
|
-
|
|
485
567
|
#### url(message, protocols?)
|
|
486
568
|
|
|
487
569
|
Ensures value is a valid URL with an allowed protocol. Works with strings. `protocols` defaults to `['http:', 'https:']`, so `javascript:` and `data:` URLs, which can run script when used as a link, are invalid. A list replaces the default, so `['mailto:']` allows only `mailto:`. `protocols` is provided to the message.
|
|
@@ -511,11 +593,39 @@ Ensures the value is a UUID as defined by [RFC 9562](https://www.rfc-editor.org/
|
|
|
511
593
|
|
|
512
594
|
Custom validation types and validators can be created and used as needed. There are some helpers that, while used internally, are considered part of the public API.
|
|
513
595
|
|
|
596
|
+
- [createValidator(fn)](#createvalidatorfn)
|
|
514
597
|
- [formatMessage(template, params)](#formatmessagetemplate-params)
|
|
515
598
|
- [createTypeValidatorTest(defaultConfig, applyConfig)](#createtypevalidatortestdefaultconfig-applyconfig)
|
|
516
599
|
- [valid({ value, field })](#valid-value-field-)
|
|
517
600
|
- [invalid({ message, value, field, errors, extras })](#invalid-message-value-field-errors-extras-)
|
|
518
|
-
|
|
601
|
+
|
|
602
|
+
#### createValidator(fn)
|
|
603
|
+
|
|
604
|
+
Makes a custom validator from `fn`, an async function that takes a value and a field name and returns a result made with `valid()` or `invalid()`. The validator gives the same results as `fn`, works with `optional()` and inside `object()` and `array()`, and is a [Standard Schema][standard-schema] like the validation types. `fn` itself is unchanged. A validator that's already a Standard Schema from this library, such as `string()`, is returned as it is. In TypeScript, its type is `TypeValidator<T, E>`, with `T` and `E` inferred from `fn`'s return type.
|
|
605
|
+
|
|
606
|
+
`fn` must return a promise. A synchronous function is a type error.
|
|
607
|
+
|
|
608
|
+
```ts
|
|
609
|
+
const hello = createValidator(async (value, field) =>
|
|
610
|
+
value === 'hello'
|
|
611
|
+
? valid({ value, field })
|
|
612
|
+
: invalid({ message: 'Must be "hello".', value, field }),
|
|
613
|
+
);
|
|
614
|
+
|
|
615
|
+
await hello['~standard'].validate('hi');
|
|
616
|
+
// { issues: [{ message: 'Must be "hello".' }] }
|
|
617
|
+
|
|
618
|
+
const schema = object({ email: string(email('Must be an email.')) });
|
|
619
|
+
await schema['~standard'].validate({ email: 'nope' });
|
|
620
|
+
// { issues: [{ message: 'Must be an email.', path: ['email'] }] }
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
How a validator's results map to Standard Schema results:
|
|
624
|
+
|
|
625
|
+
- `validate` always returns a promise, because every validator here is async. Libraries that only accept synchronous schemas can't use it.
|
|
626
|
+
- A valid result gives `{ value }`, the parsed value. Its type is the validator's value type, which includes `null` and `undefined` only for `optional()` validators.
|
|
627
|
+
- An invalid result gives one issue per error message. Object keys and array indexes in `errors` form each issue's `path`, and a non-empty `message`, such as an array-level error, is an issue with no path. An error with no message gets `'Invalid value.'`.
|
|
628
|
+
- An `object` field that fails both an array-level test and item tests keeps only the array-level message, because `object` stores a field's message in place of its errors, so only that message becomes an issue.
|
|
519
629
|
|
|
520
630
|
#### formatMessage(template, params)
|
|
521
631
|
|
|
@@ -523,7 +633,7 @@ Formats a string for use as an error message. `template` can be a plain string w
|
|
|
523
633
|
|
|
524
634
|
#### createTypeValidatorTest(defaultConfig, applyConfig)
|
|
525
635
|
|
|
526
|
-
Useful helper for simple validation types such as strings, numbers, etc. `defaultConfig` is the configuration object that the `applyConfig` function will use when parsing the value being validated. At least this should include a `parser` function.
|
|
636
|
+
Useful helper for simple validation types such as strings, numbers, etc. `defaultConfig` is the configuration object that the `applyConfig` function will use when parsing the value being validated. At least this should include a `parser` function. The resulting validator is required by default, takes `requiredMessage` in its config, works with `optional()`, and is a Standard Schema, like the built-in ones. Its return type is a `TypeValidator`, which is still a `ValidatorTest`, so factories typed with `ValidatorFactory` keep working.
|
|
527
637
|
|
|
528
638
|
The validation tests passed to the resulting validator report their errors as strings, as the built-in ones do; a test whose `errors` has another type is a type error.
|
|
529
639
|
|
|
@@ -562,28 +672,12 @@ const result = await money({ cents: true })('12.5');
|
|
|
562
672
|
|
|
563
673
|
#### valid({ value, field })
|
|
564
674
|
|
|
565
|
-
Formats a successful validation result. `value` is the parsed value and `field` is the name of the object schema property.
|
|
675
|
+
Formats a successful validation result. `value` is the parsed value and `field` is the name of the object schema property. In TypeScript, `value` has the validator's value type, so a custom validator that can return `null` or `undefined` needs them in that type.
|
|
566
676
|
|
|
567
677
|
#### invalid({ message, value, field, errors, extras })
|
|
568
678
|
|
|
569
679
|
Formats a failed validation result. `message` is the same as the `formatMessage`'s template. `value` and `field` is the same as above, `errors` is additional error details used by `array` and `object` validators, and `extras` are optional extra parameters that can be used in the message.
|
|
570
680
|
|
|
571
|
-
#### standard(validator)
|
|
572
|
-
|
|
573
|
-
Adds the [Standard Schema][standard-schema] interface to a validator, for libraries that accept any Standard Schema. It returns a new validator with a `~standard` property and leaves the one passed in unchanged.
|
|
574
|
-
|
|
575
|
-
```ts
|
|
576
|
-
const schema = standard(object({ email: string(email('Must be an email.')) }));
|
|
577
|
-
|
|
578
|
-
await schema['~standard'].validate({ email: 'nope' });
|
|
579
|
-
// { issues: [{ message: 'Must be an email.', path: ['email'] }] }
|
|
580
|
-
```
|
|
581
|
-
|
|
582
|
-
- `validate` always returns a promise, because every validator here is async. Libraries that only accept synchronous schemas can't use it.
|
|
583
|
-
- A valid result gives `{ value }`, the parsed value. Its type is the validator's value type or `null` or `undefined`, as in a valid result.
|
|
584
|
-
- An invalid result gives one issue per error message. Object keys and array indexes in `errors` form each issue's `path`, and a non-empty `message`, such as an array-level error, is an issue with no path. An error with no message gets `'Invalid value.'`.
|
|
585
|
-
- An `object` field that fails both an array-level test and item tests keeps only the array-level message, because `object` stores a field's message in place of its errors, so only that message becomes an issue.
|
|
586
|
-
|
|
587
681
|
## Supported environments
|
|
588
682
|
|
|
589
683
|
Supports Node versions in active or maintenance LTS at release time. Dropping one waits for the next major release.
|
package/dist/index.cjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){return e.message||e.errors===void 0?e.message:e.errors}function
|
|
1
|
+
Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});async function e(e,t,n){for(let r of e){let e=await r(t,n);if(e.state===`invalid`)return e}}function t(e){return e.message||e.errors===void 0?e.message:e.errors}function n(e){return Object.prototype.toString.call(e)===`[object Object]`}function r(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function i(e){return!!Reflect.get(Object(e),Symbol.iterator)}const a=/{(\w+)}/g;function o(e,t){return typeof e==`string`?e.replaceAll(a,(e,n)=>String(Reflect.get(t,n))):e(t)}async function s(e){return c(e)}function c({value:e,field:t}){return{state:`valid`,value:e,field:t}}async function l(e){return u(e)}function u({errors:e,field:t,message:n,value:r,extras:i}){return{state:`invalid`,message:o(n,{...i,value:r,field:t}),value:r,field:t,errors:e}}const d=`Invalid value.`;function f(e,t,n){if(typeof e==`string`)n.push({message:e||d,path:t});else if(Array.isArray(e))for(let[r,i]of e.entries())i!==null&&f(i,[...t,r],n);else if(typeof e==`object`&&e)for(let r of Object.keys(e))f(Reflect.get(e,r),[...t,r],n);else n.push({message:d,path:t})}const p=/* @__PURE__ */ new WeakSet;function m(e){return p.has(e)}function h(e){let t=Object.assign(e,{"~standard":{version:1,vendor:`validator-fns`,validate:async t=>{let n=await e(t);if(n.state===`valid`)return{value:n.value};let r=n.message?[{message:n.message}]:[];return n.errors!==void 0&&f(n.errors,[],r),{issues:r.length>0?r:[{message:d}]}}}});return p.add(t),t}function ee(e){return m(e)?e:h((t,n)=>e(t,n))}const g=Symbol(`optional`);function _(e){return e===``||typeof e==`number`&&Number.isNaN(e)||e instanceof Date&&Number.isNaN(e.getTime())}function v(e,t){let n=e===void 0?`Required.`:e,r=(e,t)=>u({message:n,value:e,field:t}),i=(e,t)=>c({value:e,field:t}),a=(e,n)=>t(e,n,r),o=(e,n)=>t(e,n,i);return Object.assign(h(a),{[g]:h(o)})}function te(e){let t=e[g];return t===void 0?h(async(t,n)=>t==null?c({value:t,field:n}):e(t,n)):t}function y(e){return Array.isArray(e)||e==null?e:i(e)?[...e]:[]}function b(e,t){let n=e.parser(t);return e.default!==void 0&&(n==null||n.length===0)&&(n=e.default),n}async function x(e,n,r){let i=!0,a=[];if(!e)return{isValid:i,errors:a,values:n};let o=[];for(let[s,c]of n.entries()){let n=await e(c,`${r||``}[${s}]`);o.push(n.value),n.state===`invalid`?(i=!1,a.push(t(n))):a.push(null)}return{isValid:i,errors:a,values:o}}function S(t,...n){let r=typeof t==`function`?[t,...n]:n,i={parser:y,...typeof t==`function`?void 0:t};return v(i.requiredMessage,async(t,n,a)=>{let o=b(i,t);if(o==null)return a(o,n);let[c,...u]=r,d=await e(u,o,n),f=await x(c,o,n);return!d&&f.isValid?s({value:f.values,field:n}):l({message:d?d.message:``,value:t,field:n,errors:f.errors})})}const C=/* @__PURE__ */ new WeakMap;function w(e,t){return(n,...r)=>{let i=e,a=r;return n!==void 0&&(typeof n==`function`?a=[n,...r]:i={...e,...n}),v(i.requiredMessage,async(e,n,r)=>{try{let o=t(e,i);if(o==null||_(o))return r(o,n);for(let e of a){let t=C.get(e),r;if(r=t?t(o,n):await e(o,n),r.state===`invalid`)return r}return c({value:o,field:n})}catch(t){return u({message:t instanceof Error?t.message:String(t),value:e,field:n})}})}}function T(e,t,n){let r=(r,i)=>e(r,i)?c({value:r,field:i}):u({message:t,value:r,field:i,extras:n?n(r):void 0}),i=async(e,t)=>r(e,t);return C.set(i,r),i}function E(e){return e==null||typeof e==`boolean`?e:!!e}function D(e,t){let n=t.parser(e);return t.default!==void 0&&n==null&&(n=t.default),n}const O=w({parser:E},D),k=/* @__PURE__ */ new Date(``),A=/^(\d{4})(?:-([0-2]\d)(?:-([0-3]\d)(?:[ T]([0-2]\d):([0-5]\d)(?::([0-5]\d)(\.\d+)?(Z|[+-][0-2]\d:?[0-5]\d)?)?)?)?)?$/,j=/^([+-])([0-2]\d):?([0-5]\d)$/;function M(e){let t=j.exec(e);if(e===`Z`||!t)return 0;let[,n,r,i]=t;return(n===`-`?-1:1)*(Number(r)*60+Number(i))}const ne=[()=>0,e=>Number(e),(e=`1`)=>Number.parseInt(e,10)-1,(e=`1`)=>Number.parseInt(e,10),(e=`0`)=>Number.parseInt(e,10),(e=`0`)=>Number.parseInt(e,10),(e=`0`)=>Number.parseInt(e,10),(e=`0`)=>Number.parseFloat(e)*1e3],N=`Failed to parse value to date.`;function P(e){if(e==null||e instanceof Date)return e;if(typeof e==`number`)return new Date(e);if(typeof e!=`string`)throw TypeError(N);return e.trim()===``?k:re(e)}function re(e){let t=A.exec(e);if(t===null)throw TypeError(N);let[,n=0,r=0,i=0,a=0,o=0,s=0,c=0]=ne.map((e,n)=>e(t[n])),l=t[8];return l?new Date(Date.UTC(n,r,i,a,o+M(l),s,c)):new Date(n,r,i,a,o,s,c)}function F(e,t){let n=t.parser(e);return t.default!==void 0&&(n==null||Number.isNaN(n.getTime()))&&(n=t.default),n}function I(e,t,n){let r=P(e);return T(e=>r!=null&&(e==null||e instanceof Date&&(n?e>r:e>=r)),t,()=>({min:r,limit:r,exclusive:n}))}function L(e,t,n){let r=P(e);return T(e=>r!=null&&(e==null||e instanceof Date&&(n?e<r:e<=r)),t,()=>({max:r,limit:r,exclusive:n}))}const R=w({parser:P},F),z=[e=>String.prototype.valueOf.call(e),e=>Number.prototype.valueOf.call(e),e=>Boolean.prototype.valueOf.call(e)];function B(e){if(typeof e!=`object`||!e)return e;for(let t of z)try{return t(e)}catch{}return e}function V(e){let t=B(e);switch(typeof t){case`string`:case`number`:case`bigint`:case`boolean`:return String(t);default:return}}function H(e){if(e==null||typeof e==`number`)return e;if(e instanceof Date)return e.getTime();let t=V(e),n=t===void 0?NaN:Number.parseFloat(t);if(Number.isNaN(n)&&(t===void 0||t.trim()!==``))throw TypeError(`Failed to parse value to number.`);return n}function U(e,t){let n=t.parser(e);if(t.default!==void 0&&(n==null||Number.isNaN(n))&&(n=t.default),t.round&&typeof n==`number`)switch(t.round){case`nearest`:n=Math.round(n);break;case`ceil`:n=Math.ceil(n);break;case`floor`:n=Math.floor(n);break;default:throw Error(`Unknown round type: ${String(t.round)}`)}return n}function W(e){return T(e=>e==null||typeof e==`number`&&Number.isFinite(e)&&Math.floor(e)===e,e)}const G=w({parser:H},U);function K(...e){let[t,n,r]=e.length===2?[[],...e]:e,i=typeof t==`string`?[t]:t;return async(e,t)=>{let a=e;return n(a)?s({value:a,field:t}):i.length===0?l({message:r,value:a,field:t}):l({message:``,value:a,field:t,errors:i.reduceRight((e,t)=>({[t]:e}),o(r,{value:a,field:t}))})}}function q(e,t,n){Object.defineProperty(e,t,{value:n,enumerable:!0,writable:!0,configurable:!0})}function J(n,i,...a){if(typeof n!=`object`||!n)throw TypeError("`properties` must be a configuration object");let o=typeof i==`function`?[i,...a]:a;return v(typeof i==`object`?i.requiredMessage:void 0,async(i,a,c)=>{if(i==null)return c(i,a);let u=Object(i),d={},f={},p=!0;for(let e in n)if(r(n,e)){let i=n[e],a=r(u,e)?Reflect.get(u,e):void 0,o=await(typeof i==`function`?i(a,e):l({field:e,message:`No validator set`,value:a}));q(f,e,o.value),o.state===`invalid`&&(p=!1,q(d,e,t(o)))}if(!p)return l({message:``,value:i,field:a,errors:d});let m=await e(o,f,a);return m?l({message:m.message,value:i,field:a,errors:m.errors}):s({value:f,field:a})})}function Y(e,t){let n=e;return T(t=>t==null||n.includes(t)||t instanceof Date&&e.some(e=>e.valueOf()===t.valueOf()),t,()=>({values:e}))}function X(e){return typeof e==`string`||Array.isArray(e)?e.length:e}function ie(e,t,n){return T(t=>{let r=X(t);return r==null||t===``||(n?r<e:r<=e)},t,t=>({max:e,limit:e,amount:X(t),exclusive:n}))}function ae(e,t,n){return T(t=>{let r=X(t);return r==null||t===``||(n?r>e:r>=e)},t,t=>({min:e,limit:e,amount:X(t),exclusive:n}))}function oe(e,t){return T(t=>{let n=X(t);return n==null||t===``||n===e},t,t=>({amount:X(t),limit:e,exact:e}))}const se=/^[\w!#$%&'*+./=?^`{|}~-]+@[\dA-Za-z](?:[\dA-Za-z-]{0,61}[\dA-Za-z])?(?:\.[\dA-Za-z](?:[\dA-Za-z-]{0,61}[\dA-Za-z])?)*$/,ce=/^(?:[\da-f]{8}-[\da-f]{4}-[1-8][\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}|0{8}-0{4}-0{4}-0{4}-0{12}|f{8}-f{4}-f{4}-f{4}-f{12})$/i;function Z(e){if(e==null||typeof e==`string`)return e;if(e instanceof Date)return e.toISOString();let t=V(e);if(t===void 0)throw TypeError(`Failed to parse value to string.`);return t}function Q(e,t){let n=t.parser(e);return t.default!==void 0&&(n==null||n===``)&&(n=t.default),t.trim&&typeof n==`string`&&(n=n.trim()),n}function $(e,t){let n=new RegExp(e);return T(e=>(n.lastIndex=0,e==null||e===``||typeof e==`string`&&n.test(e)),t,()=>({pattern:e}))}function le(e){return $(se,e)}function ue(e){return $(ce,e)}function de(e,t=[`http:`,`https:`]){return T(e=>{try{let n;if(e==null||e===``||typeof e==`string`&&(n=new URL(e)))return!n||t.includes(n.protocol)}catch{}return!1},e,()=>({protocols:t}))}const fe=w({parser:Z},Q);exports.applyArrayConfig=b,exports.applyBooleanConfig=D,exports.applyDateConfig=F,exports.applyNumberConfig=U,exports.applyStringConfig=Q,exports.array=S,exports.boolean=O,exports.check=K,exports.createTypeValidatorTest=w,exports.createValidator=ee,exports.createValidatorTest=T,exports.date=R,exports.email=le,exports.exact=oe,exports.formatMessage=o,exports.hasOwnProperty=r,exports.integer=W,exports.invalid=l,exports.invalidDate=k,exports.isObject=n,exports.matches=$,exports.max=ie,exports.maxDate=L,exports.min=ae,exports.minDate=I,exports.number=G,exports.object=J,exports.oneOf=Y,exports.optional=te,exports.parseArray=y,exports.parseBoolean=E,exports.parseDate=P,exports.parseNumber=H,exports.parseString=Z,exports.string=fe,exports.url=de,exports.uuid=ue,exports.valid=s;
|
|
2
2
|
//# sourceMappingURL=index.cjs.map
|