@tanstack/form-core 0.10.3 → 0.12.0

package/src/tests/FormApi.spec.ts

@@ -24,7 +24,12 @@ describe('form api', () => {
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
-      formValidationCount: 0,
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+      },
     })
   })
 
@@ -53,7 +58,12 @@ describe('form api', () => {
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
-      formValidationCount: 0,
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+      },
     })
   })
 
@@ -80,7 +90,12 @@ describe('form api', () => {
       isValid: true,
       isValidating: false,
       submissionAttempts: 30,
-      formValidationCount: 0,
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+      },
     })
   })
 
@@ -118,7 +133,13 @@ describe('form api', () => {
       isValid: true,
       isValidating: false,
       submissionAttempts: 300,
-      formValidationCount: 0,
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+        onServer: undefined,
+      },
     })
   })
 
@@ -152,7 +173,12 @@ describe('form api', () => {
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
-      formValidationCount: 0,
+      validationMetaMap: {
+        onChange: undefined,
+        onBlur: undefined,
+        onSubmit: undefined,
+        onMount: undefined,
+      },
     })
   })
 
@@ -234,7 +260,7 @@ describe('form api', () => {
       employees: Partial<Employee>[]
     }
 
-    const form = new FormApi<Form, unknown>()
+    const form = new FormApi<Form>()
 
     const field = new FieldApi({
       form,
@@ -262,7 +288,7 @@ describe('form api', () => {
       employees: Partial<Employee>[]
     }
 
-    const form = new FormApi<Form, unknown>()
+    const form = new FormApi<Form>()
 
     const field = new FieldApi({
       form,
@@ -362,7 +388,9 @@ describe('form api', () => {
     const field = new FieldApi({
       form,
       name: 'name',
-      onChange: (v) => (v.length > 0 ? undefined : 'required'),
+      validators: {
+        onChange: ({ value }) => (value.length > 0 ? undefined : 'required'),
+      },
     })
 
     form.mount()
@@ -390,9 +418,11 @@ describe('form api', () => {
       defaultValues: {
         name: 'test',
       },
-      onChange: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onChange: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
 
@@ -418,10 +448,12 @@ describe('form api', () => {
       defaultValues: {
         name: 'test',
       },
-      onChangeAsync: async (value) => {
-        await sleep(1000)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onChangeAsync: async ({ value }) => {
+          await sleep(1000)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -449,11 +481,13 @@ describe('form api', () => {
       defaultValues: {
         name: 'test',
       },
-      onChangeAsyncDebounceMs: 1000,
-      onChangeAsync: async (value) => {
-        await sleepMock(1000)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onChangeAsyncDebounceMs: 1000,
+        onChangeAsync: async ({ value }) => {
+          await sleepMock(1000)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -485,10 +519,12 @@ describe('form api', () => {
         name: 'test',
       },
       asyncDebounceMs: 1000,
-      onChangeAsync: async (value) => {
-        await sleepMock(1000)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onChangeAsync: async ({ value }) => {
+          await sleepMock(1000)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -516,9 +552,11 @@ describe('form api', () => {
       defaultValues: {
         name: 'other',
       },
-      onBlur: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onBlur: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -544,10 +582,12 @@ describe('form api', () => {
       defaultValues: {
         name: 'test',
       },
-      onBlurAsync: async (value) => {
-        await sleep(1000)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onBlurAsync: async ({ value }) => {
+          await sleep(1000)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -575,11 +615,13 @@ describe('form api', () => {
       defaultValues: {
         name: 'test',
       },
-      onBlurAsyncDebounceMs: 1000,
-      onBlurAsync: async (value) => {
-        await sleepMock(10)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onBlurAsyncDebounceMs: 1000,
+        onBlurAsync: async ({ value }) => {
+          await sleepMock(10)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -612,10 +654,12 @@ describe('form api', () => {
         name: 'test',
       },
       asyncDebounceMs: 1000,
-      onBlurAsync: async (value) => {
-        await sleepMock(10)
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onBlurAsync: async ({ value }) => {
+          await sleepMock(10)
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -644,13 +688,15 @@ describe('form api', () => {
       defaultValues: {
         name: 'other',
       },
-      onBlur: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
-      },
-      onChange: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onBlur: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
+        onChange: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -678,9 +724,11 @@ describe('form api', () => {
       defaultValues: {
         name: 'other',
       },
-      onChange: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onChange: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -706,9 +754,11 @@ describe('form api', () => {
       defaultValues: {
         name: 'other',
       },
-      onMount: (value) => {
-        if (value.name === 'other') return 'Please enter a different value'
-        return
+      validators: {
+        onMount: ({ value }) => {
+          if (value.name === 'other') return 'Please enter a different value'
+          return
+        },
       },
     })
     const field = new FieldApi({
@@ -736,13 +786,19 @@ describe('form api', () => {
     const field = new FieldApi({
       form,
       name: 'firstName',
-      onChange: (v) => (v.length > 0 ? undefined : 'first name is required'),
+      validators: {
+        onChange: ({ value }) =>
+          value.length > 0 ? undefined : 'first name is required',
+      },
     })
 
     const lastNameField = new FieldApi({
       form,
       name: 'lastName',
-      onChange: (v) => (v.length > 0 ? undefined : 'last name is required'),
+      validators: {
+        onChange: ({ value }) =>
+          value.length > 0 ? undefined : 'last name is required',
+      },
     })
 
     field.mount()
@@ -770,11 +826,14 @@ describe('form api', () => {
     const field = new FieldApi({
       form,
       name: 'firstName',
-      onChange: (v) => (v.length > 0 ? undefined : 'first name is required'),
-      onBlur: (v) =>
-        v.length > 3
-          ? undefined
-          : 'first name must be longer than 3 characters',
+      validators: {
+        onChange: ({ value }) =>
+          value.length > 0 ? undefined : 'first name is required',
+        onBlur: ({ value }) =>
+          value.length > 3
+            ? undefined
+            : 'first name must be longer than 3 characters',
+      },
     })
 
     field.mount()
@@ -798,7 +857,10 @@ describe('form api', () => {
     const field = new FieldApi({
       form,
       name: 'firstName',
-      onSubmit: (v) => (v.length > 0 ? undefined : 'first name is required'),
+      validators: {
+        onSubmit: ({ value }) =>
+          value.length > 0 ? undefined : 'first name is required',
+      },
     })
 
     field.mount()
@@ -828,7 +890,10 @@ describe('form api', () => {
     const field = new FieldApi({
       form,
       name: 'firstName',
-      onChange: (v) => (v.length > 0 ? undefined : 'first name is required'),
+      validators: {
+        onChange: ({ value }) =>
+          value.length > 0 ? undefined : 'first name is required',
+      },
     })
 
     field.mount()
@@ -839,4 +904,48 @@ describe('form api', () => {
     await form.validateAllFields('change')
     expect(field.getMeta().errorMap.onChange).toEqual('first name is required')
   })
+
+  it('should show onSubmit errors', async () => {
+    const form = new FormApi({
+      defaultValues: {
+        firstName: '',
+      },
+      validators: {
+        onSubmit: ({ value }) =>
+          value.firstName.length > 0 ? undefined : 'first name is required',
+      },
+    })
+
+    const field = new FieldApi({
+      form,
+      name: 'firstName',
+    })
+
+    field.mount()
+
+    await form.handleSubmit()
+    expect(form.state.errors).toStrictEqual(['first name is required'])
+  })
+
+  it('should run onChange validation during submit', async () => {
+    const form = new FormApi({
+      defaultValues: {
+        firstName: '',
+      },
+      validators: {
+        onChange: ({ value }) =>
+          value.firstName.length > 0 ? undefined : 'first name is required',
+      },
+    })
+
+    const field = new FieldApi({
+      form,
+      name: 'firstName',
+    })
+
+    field.mount()
+
+    await form.handleSubmit()
+    expect(form.state.errors).toStrictEqual(['first name is required'])
+  })
 })

package/src/tests/mutateMergeDeep.spec.ts

@@ -0,0 +1,32 @@
+import { describe } from 'vitest'
+import { mutateMergeDeep } from '../mergeForm'
+
+describe('mutateMergeDeep', () => {
+  test('Should merge two objects by mutating', () => {
+    const a = { a: 1 }
+    const b = { b: 2 }
+    mutateMergeDeep(a, b)
+    expect(a).toStrictEqual({ a: 1, b: 2 })
+  })
+
+  test('Should merge two objects including overwriting with undefined', () => {
+    const a = { a: 1 }
+    const b = { a: undefined }
+    mutateMergeDeep(a, b)
+    expect(a).toStrictEqual({ a: undefined })
+  })
+
+  test('Should merge two object by merging arrays', () => {
+    const a = { a: [1] }
+    const b = { a: [2] }
+    mutateMergeDeep(a, b)
+    expect(a).toStrictEqual({ a: [1, 2] })
+  })
+
+  test('Should merge two deeply nested objects', () => {
+    const a = { a: { a: 1 } }
+    const b = { a: { b: 2 } }
+    mutateMergeDeep(a, b)
+    expect(a).toStrictEqual({ a: { a: 1, b: 2 } })
+  })
+})

package/src/tests/utils.ts

@@ -1,5 +1,5 @@
 export function sleep(timeout: number): Promise<void> {
-  return new Promise((resolve, _reject) => {
+  return new Promise((resolve) => {
     setTimeout(resolve, timeout)
   })
 }

package/src/types.ts

@@ -2,6 +2,15 @@ export type ValidationError = undefined | false | null | string
 
 // If/when TypeScript supports higher-kinded types, this should not be `unknown` anymore
 export type Validator<Type, Fn = unknown> = () => {
-  validate(value: Type, fn: Fn): ValidationError
-  validateAsync(value: Type, fn: Fn): Promise<ValidationError>
+  validate(options: { value: Type }, fn: Fn): ValidationError
+  validateAsync(options: { value: Type }, fn: Fn): Promise<ValidationError>
+}
+
+// "server" is only intended for SSR/SSG validation and should not execute anything
+export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount' | 'server'
+
+export type ValidationErrorMapKeys = `on${Capitalize<ValidationCause>}`
+
+export type ValidationErrorMap = {
+  [K in ValidationErrorMapKeys]?: ValidationError
 }

package/src/utils.ts

@@ -1,3 +1,7 @@
+import type { ValidationCause, Validator } from './types'
+import type { FormValidators } from './FormApi'
+import type { FieldValidators } from './FieldApi'
+
 export type UpdaterFn<TInput, TOutput = TInput> = (input: TInput) => TOutput
 
 export type Updater<TInput, TOutput = TInput> =
@@ -141,6 +145,125 @@ export function isNonEmptyArray(obj: any) {
   return !(Array.isArray(obj) && obj.length === 0)
 }
 
+interface AsyncValidatorArrayPartialOptions<T> {
+  validators?: T
+  asyncDebounceMs?: number
+}
+
+interface AsyncValidator<T> {
+  cause: ValidationCause
+  validate: T
+  debounceMs: number
+}
+
+export function getAsyncValidatorArray<T>(
+  cause: ValidationCause,
+  options: AsyncValidatorArrayPartialOptions<T>,
+): T extends FieldValidators<any, any>
+  ? Array<
+      AsyncValidator<T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']>
+    >
+  : T extends FormValidators<any, any>
+    ? Array<
+        AsyncValidator<
+          T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']
+        >
+      >
+    : never {
+  const { asyncDebounceMs } = options
+  const {
+    onChangeAsync,
+    onBlurAsync,
+    onSubmitAsync,
+    onBlurAsyncDebounceMs,
+    onChangeAsyncDebounceMs,
+    onSubmitAsyncDebounceMs,
+  } = (options.validators || {}) as
+    | FieldValidators<any, any>
+    | FormValidators<any, any>
+
+  const defaultDebounceMs = asyncDebounceMs ?? 0
+
+  const changeValidator = {
+    cause: 'change',
+    validate: onChangeAsync,
+    debounceMs: onChangeAsyncDebounceMs ?? defaultDebounceMs,
+  } as const
+
+  const blurValidator = {
+    cause: 'blur',
+    validate: onBlurAsync,
+    debounceMs: onBlurAsyncDebounceMs ?? defaultDebounceMs,
+  } as const
+
+  const submitValidator = {
+    cause: 'submit',
+    validate: onSubmitAsync,
+    debounceMs: onSubmitAsyncDebounceMs ?? defaultDebounceMs,
+  } as const
+
+  switch (cause) {
+    case 'submit':
+      return [changeValidator, blurValidator, submitValidator] as never
+    case 'server':
+      return [] as never
+    case 'blur':
+      return [blurValidator] as never
+    case 'change':
+    default:
+      return [changeValidator] as never
+  }
+}
+
+interface SyncValidatorArrayPartialOptions<T> {
+  validators?: T
+}
+
+interface SyncValidator<T> {
+  cause: ValidationCause
+  validate: T
+}
+
+export function getSyncValidatorArray<T>(
+  cause: ValidationCause,
+  options: SyncValidatorArrayPartialOptions<T>,
+): T extends FieldValidators<any, any>
+  ? Array<SyncValidator<T['onChange'] | T['onBlur'] | T['onSubmit']>>
+  : T extends FormValidators<any, any>
+    ? Array<SyncValidator<T['onChange'] | T['onBlur'] | T['onSubmit']>>
+    : never {
+  const { onChange, onBlur, onSubmit } = (options.validators || {}) as
+    | FieldValidators<any, any>
+    | FormValidators<any, any>
+
+  const changeValidator = { cause: 'change', validate: onChange } as const
+  const blurValidator = { cause: 'blur', validate: onBlur } as const
+  const submitValidator = { cause: 'submit', validate: onSubmit } as const
+
+  // Allows us to clear onServer errors
+  const serverValidator = {
+    cause: 'server',
+    validate: () => undefined,
+  } as const
+
+  switch (cause) {
+    case 'submit':
+      return [
+        changeValidator,
+        blurValidator,
+        submitValidator,
+        serverValidator,
+      ] as never
+    case 'server':
+      return [serverValidator] as never
+    case 'blur':
+      return [blurValidator, serverValidator] as never
+    case 'change':
+    default:
+      return [changeValidator, serverValidator] as never
+  }
+}
+
 export type RequiredByKey<T, K extends keyof T> = Omit<T, K> &
   Required<Pick<T, K>>
 
@@ -166,24 +289,24 @@ type AllowedIndexes<
 > = Tuple extends readonly []
   ? Keys
   : Tuple extends readonly [infer _, ...infer Tail]
-  ? AllowedIndexes<Tail, Keys | Tail['length']>
-  : Keys
+    ? AllowedIndexes<Tail, Keys | Tail['length']>
+    : Keys
 
 export type DeepKeys<T, TDepth extends any[] = []> = TDepth['length'] extends 5
   ? never
   : unknown extends T
-  ? string
-  : object extends T
-  ? string
-  : T extends readonly any[] & IsTuple<T>
-  ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
-  : T extends any[]
-  ? DeepKeys<T[number], [...TDepth, any]>
-  : T extends Date
-  ? never
-  : T extends object
-  ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
-  : never
+    ? string
+    : object extends T
+      ? string
+      : T extends readonly any[] & IsTuple<T>
+        ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth>
+        : T extends any[]
+          ? DeepKeys<T[number], [...TDepth, any]>
+          : T extends Date
+            ? never
+            : T extends object
+              ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth>
+              : never
 
 type DeepKeysPrefix<
   T,