fix(form-core): infer formOptions parameter's type correctly (#1679)

a-is-4-adam · Adam Nicholson · LeCarbonator · web-flow · commit 628c5efd12cc · 2025-08-10T22:32:59.000+02:00
* fix(form-core): improve formOptions type preservation - WIP

- Add TFormData generic parameter to formOptions function
- Add test to verify listener type preservation with formOptions
- Current implementation has intentional type issues for investigation

* move tests to correct file, fix imports

* fix(form-core): use generic for formOptions parameter instead

* ci: apply automated fixes and generate docs

* chore: add intersection to formOptions parameter for type inference

---------

Co-authored-by: Adam Nicholson &lt;adam.nicholson@flightcentre.com&gt;
Co-authored-by: LeCarbonator &lt;18158911+LeCarbonator@users.noreply.github.com&gt;
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
diff --git a/packages/form-core/src/formOptions.ts b/packages/form-core/src/formOptions.ts
@@ -1,9 +1,62 @@
-import type { FormOptions } from './FormApi'
+import type {
+  FormAsyncValidateOrFn,
+  FormOptions,
+  FormValidateOrFn,
+} from './FormApi'
+
+/*
+
+These types need to do two things:
+
+1. Validator generics need to depend on the TFormData generic
+2. The resulting needs to allow overriding values
+
+The generics from formOptions almost work, except that it loses information
+about how to infer TFormData.
+If you pass a validator function, it tries to resolve the `formApi` or `value`
+inside of it, meaning that TFormData changes to `unknown`.
+
+To bypass this, the intersection for defaultOpts gives TypeScript that information again,
+without losing the benefits from the TOptions generic.
+*/
 
 export function formOptions<
-  T extends Partial<
-    FormOptions<any, any, any, any, any, any, any, any, any, any, any, any>
+  TOptions extends Partial<
+    FormOptions<
+      TFormData,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      TSubmitMeta
+    >
   >,
->(defaultOpts: T) {
+  TFormData = TOptions['defaultValues'],
+  TSubmitMeta = TOptions['onSubmitMeta'],
+>(
+  defaultOpts: Partial<
+    FormOptions<
+      TFormData,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      undefined | FormAsyncValidateOrFn<TFormData>,
+      TSubmitMeta
+    >
+  > &
+    TOptions,
+): TOptions {
   return defaultOpts
 }
diff --git a/packages/form-core/tests/FormApi.test-d.ts b/packages/form-core/tests/FormApi.test-d.ts
@@ -1,6 +1,6 @@
 import { expectTypeOf, it } from 'vitest'
 import { z } from 'zod'
-import { FormApi } from '../src'
+import { FormApi, formOptions } from '../src'
 import type {
   DeepKeys,
   GlobalFormValidationError,
@@ -375,3 +375,75 @@ it('should extract the form error type from a global form error', () => {
     )[]
   >
 })
+
+it('listeners should be typed correctly', () => {
+  type FormData = {
+    firstName: string
+    lastName: string
+  }
+
+  const form = new FormApi({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+    } as FormData,
+    listeners: {
+      onSubmit: ({ formApi }) => {
+        expectTypeOf(formApi.state.values).toEqualTypeOf<FormData>()
+      },
+    },
+  })
+
+  form.handleSubmit()
+})
+
+it('listeners should be typed correctly when using formOptions', () => {
+  type FormData = {
+    firstName: string
+    lastName: string
+  }
+
+  const formOpts = formOptions({
+    defaultValues: {
+      firstName: 'FirstName',
+      lastName: 'LastName',
+    } as FormData,
+    validators: {
+      onSubmit: () => {
+        return {
+          test: 'test',
+        }
+      },
+    },
+    listeners: {
+      onSubmit: ({ formApi }) => {
+        expectTypeOf(formApi.state.values).toEqualTypeOf<FormData>()
+      },
+    },
+  })
+
+  const form = new FormApi({
+    ...formOpts,
+    listeners: {
+      // this doesn't error since listeners return void
+      onSubmit: ({ formApi }) => {
+        console.log(formApi.state.values)
+      },
+    },
+    validators: {
+      // this errors becuase the return type is not the same as the validator return type
+      // onSubmit: () => 'custom on submit',
+
+      onSubmit: () => {
+        return {
+          test: 'can change the value!',
+        }
+      },
+      onChange: () => {
+        return 'onChange'
+      },
+    },
+  })
+
+  form.handleSubmit()
+})
