Skip to content

Commit ba66490

Browse files
LeCarbonatorLeCarbonator
authored
feat(form-core): add parseValueWithSchema() stateless method (#1421)
* feat(FormApi): add standard schema validator wrapper * feat(form-core): add parseValueWithSchema methods * docs: add parseValueWithSchema documentation * refactor(form-core): rename FormApi#parseValuesWithSchema This is to be consistent with other methods that include the word Values. * refactor(form-core): adjust unit tests for parseValuesWithSchema * refactor(FormApi): rename parseFieldValuesWithSchema Since we don't pass a field to the method, the term shouldn't be included in the method name. * docs: generate
1 parent 24edab3 commit ba66490

21 files changed

+655
-46
lines changed

‎docs/framework/angular/guides/validation.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -499,6 +499,41 @@ export class AppComponent {
499499
}
500500
```
501501

502+
If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
503+
504+
```angular-ts
505+
@Component({
506+
selector: 'app-root',
507+
standalone: true,
508+
imports: [TanStackField],
509+
template: `
510+
<ng-container
511+
[tanstackField]="form"
512+
name="age"
513+
[validators]="{ onChangeAsync: ageValidator }"
514+
#age="field"
515+
>
516+
<!-- ... -->
517+
</ng-container>
518+
`,
519+
})
520+
export class AppComponent {
521+
ageValidator: FieldValidateAsyncFn<any, string, number> = async ({
522+
value,
523+
fieldApi,
524+
}) => {
525+
const errors = fieldApi.parseValueWithSchema(
526+
z.number().gte(13, 'You must be 13 to make an account'),
527+
)
528+
if (errors) return errors
529+
530+
// continue with your validation
531+
}
532+
533+
// ...
534+
}
535+
```
536+
502537
## Preventing invalid forms from being submitted
503538

504539
The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

‎docs/framework/react/guides/validation.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,27 @@ Async validations on form and field level are supported as well:
503503
/>
504504
```
505505
506+
If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
507+
508+
```tsx
509+
<form.Field
510+
name="age"
511+
asyncDebounceMs={500}
512+
validators={{
513+
onChangeAsync: async ({ value, fieldApi }) => {
514+
const errors = fieldApi.parseValueWithSchema(
515+
z.number().gte(13, 'You must be 13 to make an account'),
516+
)
517+
if (errors) return errors
518+
// continue with your validation
519+
},
520+
}}
521+
children={(field) => {
522+
return <>{/* ... */}</>
523+
}}
524+
/>
525+
```
526+
506527
## Preventing invalid forms from being submitted
507528
508529
The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

‎docs/framework/solid/guides/validation.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,28 @@ Async validations on form and field level are supported as well:
390390
/>
391391
```
392392

393+
If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
394+
395+
```tsx
396+
<form.Field
397+
name="age"
398+
validators={{
399+
onChange: ({ value, fieldApi }) => {
400+
const errors = fieldApi.parseValueWithSchema(
401+
z.number().gte(13, 'You must be 13 to make an account'),
402+
)
403+
404+
if (errors) return errors
405+
406+
// continue with your validation
407+
},
408+
}}
409+
children={(field) => {
410+
return <>{/* ... */}</>
411+
}}
412+
/>
413+
```
414+
393415
## Preventing invalid forms from being submitted
394416

395417
The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

‎docs/framework/vue/guides/validation.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,33 @@ Async validations on form and field level are supported as well:
442442
</template>
443443
```
444444

445+
If you need even more control over your Standard Schema validation, you can combine a Standard Schema with a callback function like so:
446+
447+
```vue
448+
<template>
449+
<!-- ... -->
450+
<form.Field
451+
name="age"
452+
:validators="{
453+
onChange: ({ value, fieldApi }) => {
454+
const errors = fieldApi.parseValueWithSchema(
455+
z.number().gte(13, 'You must be 13 to make an account'),
456+
)
457+
458+
if (errors) return errors
459+
460+
// continue with your validation
461+
},
462+
}"
463+
>
464+
<template v-slot="{ field }">
465+
<!-- ... -->
466+
</template>
467+
</form.Field>
468+
<!-- ... -->
469+
</template>
470+
```
471+
445472
## Preventing invalid forms from being submitted
446473

447474
The `onChange`, `onBlur` etc... callbacks are also run when the form is submitted and the submission is blocked if the form is invalid.

‎docs/reference/classes/fieldapi.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,63 @@ Moves the value at the first specified index to the second specified index.
343343
344344
***
345345
346+
### parseValueWithSchema()
347+
348+
```ts
349+
parseValueWithSchema(schema):
350+
| undefined
351+
| StandardSchemaV1Issue[]
352+
```
353+
354+
Defined in: [packages/form-core/src/FieldApi.ts:1651](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1651)
355+
356+
Parses the field's value with the given schema and returns
357+
issues (if any). This method does NOT set any internal errors.
358+
359+
#### Parameters
360+
361+
##### schema
362+
363+
[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
364+
365+
The standard schema to parse this field's value with.
366+
367+
#### Returns
368+
369+
\| `undefined`
370+
\| [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]
371+
372+
***
373+
374+
### parseValueWithSchemaAsync()
375+
376+
```ts
377+
parseValueWithSchemaAsync(schema): Promise<
378+
| undefined
379+
| StandardSchemaV1Issue[]>
380+
```
381+
382+
Defined in: [packages/form-core/src/FieldApi.ts:1663](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1663)
383+
384+
Parses the field's value with the given schema and returns
385+
issues (if any). This method does NOT set any internal errors.
386+
387+
#### Parameters
388+
389+
##### schema
390+
391+
[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TData`, `unknown`\>
392+
393+
The standard schema to parse this field's value with.
394+
395+
#### Returns
396+
397+
`Promise`\<
398+
\| `undefined`
399+
\| [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>
400+
401+
***
402+
346403
### pushValue()
347404
348405
```ts

‎docs/reference/classes/formapi.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -422,6 +422,75 @@ Moves the value at the first specified index to the second specified index withi
422422
423423
***
424424
425+
### parseValuesWithSchema()
426+
427+
```ts
428+
parseValuesWithSchema(schema):
429+
| undefined
430+
| {
431+
fields: Record<string, StandardSchemaV1Issue[]>;
432+
form: Record<string, StandardSchemaV1Issue[]>;
433+
}
434+
```
435+
436+
Defined in: [packages/form-core/src/FormApi.ts:2075](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L2075)
437+
438+
Parses the form's values with a given standard schema and returns
439+
issues (if any). This method does NOT set any internal errors.
440+
441+
#### Parameters
442+
443+
##### schema
444+
445+
[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TFormData`, `unknown`\>
446+
447+
The standard schema to parse the form values with.
448+
449+
#### Returns
450+
451+
\| `undefined`
452+
\| \{
453+
`fields`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
454+
`form`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
455+
\}
456+
457+
***
458+
459+
### parseValuesWithSchemaAsync()
460+
461+
```ts
462+
parseValuesWithSchemaAsync(schema): Promise<
463+
| undefined
464+
| {
465+
fields: Record<string, StandardSchemaV1Issue[]>;
466+
form: Record<string, StandardSchemaV1Issue[]>;
467+
}>
468+
```
469+
470+
Defined in: [packages/form-core/src/FormApi.ts:2087](https://github.com/TanStack/form/blob/main/packages/form-core/src/FormApi.ts#L2087)
471+
472+
Parses the form's values with a given standard schema and returns
473+
issues (if any). This method does NOT set any internal errors.
474+
475+
#### Parameters
476+
477+
##### schema
478+
479+
[`StandardSchemaV1`](../type-aliases/standardschemav1.md)\<`TFormData`, `unknown`\>
480+
481+
The standard schema to parse the form values with.
482+
483+
#### Returns
484+
485+
`Promise`\<
486+
\| `undefined`
487+
\| \{
488+
`fields`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
489+
`form`: `Record`\<`string`, [`StandardSchemaV1Issue`](../interfaces/standardschemav1issue.md)[]\>;
490+
\}\>
491+
492+
***
493+
425494
### pushFieldValue()
426495

427496
```ts

‎docs/reference/functions/isstandardschemavalidator.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ title: isStandardSchemaValidator
1111
function isStandardSchemaValidator(validator): validator is StandardSchemaV1<unknown, unknown>
1212
```
1313

14-
Defined in: [packages/form-core/src/standardSchemaValidator.ts:75](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L75)
14+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:90](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L90)
1515

1616
## Parameters
1717

‎docs/reference/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ title: "@tanstack/form-core"
5959
- [Nullable](type-aliases/nullable.md)
6060
- [ObjectAccessor](type-aliases/objectaccessor.md)
6161
- [StandardSchemaV1](type-aliases/standardschemav1.md)
62+
- [TStandardSchemaValidatorIssue](type-aliases/tstandardschemavalidatorissue.md)
6263
- [TStandardSchemaValidatorValue](type-aliases/tstandardschemavalidatorvalue.md)
6364
- [TupleAccessor](type-aliases/tupleaccessor.md)
6465
- [UnknownAccessor](type-aliases/unknownaccessor.md)

‎docs/reference/interfaces/standardschemav1issue.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ title: StandardSchemaV1Issue
77

88
# Interface: StandardSchemaV1Issue
99

10-
Defined in: [packages/form-core/src/standardSchemaValidator.ts:144](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L144)
10+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:159](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L159)
1111

1212
The issue interface of the failure output.
1313

@@ -19,7 +19,7 @@ The issue interface of the failure output.
1919
readonly message: string;
2020
```
2121

22-
Defined in: [packages/form-core/src/standardSchemaValidator.ts:148](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L148)
22+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:163](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L163)
2323

2424
The error message of the issue.
2525

@@ -31,6 +31,6 @@ The error message of the issue.
3131
readonly optional path: readonly (PropertyKey | StandardSchemaV1PathSegment)[];
3232
```
3333

34-
Defined in: [packages/form-core/src/standardSchemaValidator.ts:152](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L152)
34+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:167](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L167)
3535

3636
The path of the issue, if any.

‎docs/reference/type-aliases/standardschemav1.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ title: StandardSchemaV1
1111
type StandardSchemaV1<Input, Output> = object;
1212
```
1313

14-
Defined in: [packages/form-core/src/standardSchemaValidator.ts:83](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L83)
14+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:98](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L98)
1515

1616
The Standard Schema interface.
1717

‎docs/reference/type-aliases/tstandardschemavalidatorissue.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
id: TStandardSchemaValidatorIssue
3+
title: TStandardSchemaValidatorIssue
4+
---
5+
6+
<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7+
8+
# Type Alias: TStandardSchemaValidatorIssue\<TSource\>
9+
10+
```ts
11+
type TStandardSchemaValidatorIssue<TSource> = TSource extends "form" ? object : TSource extends "field" ? StandardSchemaV1Issue[] : never;
12+
```
13+
14+
Defined in: [packages/form-core/src/standardSchemaValidator.ts:11](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L11)
15+
16+
## Type Parameters
17+
18+
• **TSource** *extends* [`ValidationSource`](validationsource.md) = [`ValidationSource`](validationsource.md)

‎docs/reference/type-aliases/tstandardschemavalidatorvalue.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@ title: TStandardSchemaValidatorValue
55

66
<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
77

8-
# Type Alias: TStandardSchemaValidatorValue\<TData\>
8+
# Type Alias: TStandardSchemaValidatorValue\<TData, TSource\>
99

1010
```ts
11-
type TStandardSchemaValidatorValue<TData> = object;
11+
type TStandardSchemaValidatorValue<TData, TSource> = object;
1212
```
1313

1414
Defined in: [packages/form-core/src/standardSchemaValidator.ts:3](https://github.com/TanStack/form/blob/main/packages/form-core/src/standardSchemaValidator.ts#L3)
@@ -17,12 +17,14 @@ Defined in: [packages/form-core/src/standardSchemaValidator.ts:3](https://github
1717

1818
• **TData**
1919

20+
• **TSource** *extends* [`ValidationSource`](validationsource.md) = [`ValidationSource`](validationsource.md)
21+
2022
## Type declaration
2123

2224
### validationSource
2325

2426
```ts
25-
validationSource: ValidationSource;
27+
validationSource: TSource;
2628
```
2729

2830
### value

0 commit comments

Comments
 (0)