TanStack / TanStack/form

[v2] Standardize exception handling during submission

Open
#2,306 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: types scope: core v2
Dominant language
TypeScript
Stars
6.7k
Forks
682
Avg merge
5d 18h
Merged PRs (30d)
7

Description

Calling form.handleSubmit() can run several phases: field validation, form validation, and onSubmit. Any of these phases may throw because of an application error. With onSubmitInvalid being added, submission failures need consistent behavior regardless of where they originate.

Normal validation failures should remain distinguishable from unexpected exceptions, and the behavior of form.handleSubmit() should not depend on which submission phase failed.

Planned for behaviour

  • Call onSubmitInvalid for exceptions from field validation, form validation, and onSubmit, in addition to reported validation issues.
  • Pass a cause to onSubmitInvalid that identifies the failing phase, such as "field_validation" | "form_validation" | "on_submit".
  • Do not catch exceptions thrown by onSubmitInvalid. This allows consumers to throw deliberately when they want the rejected promise to reach an error screen or other error boundary.
  • Determine the rejection of the form.handleSubmit() promise before invoking onSubmitInvalid, so the callback cannot change whether the original submission error rejects.

Validation results should still be inspectable separately from exceptions:

// `cause` === `"field_validator" | "form_validator"`
const { errors, cause } = await form
  .handleSubmit()
  .catch(() => 'real error thrown')
const isInvalid = errors.length > 0

Some thoughts

The exact cause discriminator names still need to be made consistent. The proposed behavior uses the same categories regardless of whether they are ultimately named field_validation and form_validation or field_validator and form_validator.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the form.handleSubmit() entry point and trace field validation, form validation, and onSubmit through the submission flow. Define consistent onSubmitInvalid causes for each phase, preserving separate validation errors and ensuring its exceptions are not caught. Done means the handleSubmit() rejection is decided before onSubmitInvalid runs and behavior is consistent across all phases.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.