@tanstack/form-core 0.3.6 → 0.4.0

package/src/FieldApi.ts

@@ -1,57 +1,126 @@
 import { type DeepKeys, type DeepValue, type Updater } from './utils'
-import type { FormApi, ValidationError, ValidationErrorMap } from './FormApi'
+import type { FormApi, ValidationErrorMap } from './FormApi'
 import { Store } from '@tanstack/store'
+import type { Validator, ValidationError } from './types'
 
 export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount'
 
-type ValidateFn<TParentData, TName extends DeepKeys<TParentData>, TData> = (
+type ValidateFn<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  ValidatorType,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = (
   value: TData,
-  fieldApi: FieldApi<TParentData, TName>,
+  fieldApi: FieldApi<TParentData, TName, ValidatorType, TData>,
 ) => ValidationError
 
+type ValidateOrFn<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  ValidatorType,
+  FormValidator,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = ValidatorType extends Validator<TData>
+  ?
+      | Parameters<ReturnType<ValidatorType>['validate']>[1]
+      | ValidateFn<TParentData, TName, ValidatorType, TData>
+  : FormValidator extends Validator<TData>
+  ?
+      | Parameters<ReturnType<FormValidator>['validate']>[1]
+      | ValidateFn<TParentData, TName, ValidatorType, TData>
+  : ValidateFn<TParentData, TName, ValidatorType, TData>
+
 type ValidateAsyncFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  TData,
+  ValidatorType,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = (
   value: TData,
-  fieldApi: FieldApi<TParentData, TName>,
+  fieldApi: FieldApi<TParentData, TName, ValidatorType, TData>,
 ) => ValidationError | Promise<ValidationError>
 
+type AsyncValidateOrFn<
+  TParentData,
+  TName extends DeepKeys<TParentData>,
+  ValidatorType,
+  FormValidator,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> = ValidatorType extends Validator<TData>
+  ?
+      | Parameters<ReturnType<ValidatorType>['validate']>[1]
+      | ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
+  : FormValidator extends Validator<TData>
+  ?
+      | Parameters<ReturnType<FormValidator>['validate']>[1]
+      | ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
+  : ValidateAsyncFn<TParentData, TName, ValidatorType, TData>
+
 export interface FieldOptions<
   TParentData,
-  /**
-   * This allows us to restrict the name to only be a valid field name while
-   * also assigning it to a generic
-   */
   TName extends DeepKeys<TParentData>,
-  /**
-   * If TData is unknown, we can use the TName generic to determine the type
-   */
-  TData = DeepValue<TParentData, TName>,
+  ValidatorType,
+  FormValidator,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
-  name: DeepKeys<TParentData>
+  name: TName
   index?: TData extends any[] ? number : never
   defaultValue?: TData
   asyncDebounceMs?: number
   asyncAlways?: boolean
-  onMount?: (formApi: FieldApi<TParentData, TName>) => void
-  onChange?: ValidateFn<TParentData, TName, TData>
-  onChangeAsync?: ValidateAsyncFn<TParentData, TName, TData>
+  validator?: ValidatorType
+  onMount?: (
+    formApi: FieldApi<TParentData, TName, ValidatorType, TData>,
+  ) => void
+  onChange?: ValidateOrFn<
+    TParentData,
+    TName,
+    ValidatorType,
+    FormValidator,
+    TData
+  >
+  onChangeAsync?: AsyncValidateOrFn<
+    TParentData,
+    TName,
+    ValidatorType,
+    FormValidator,
+    TData
+  >
   onChangeAsyncDebounceMs?: number
-  onBlur?: ValidateFn<TParentData, TName, TData>
-  onBlurAsync?: ValidateAsyncFn<TParentData, TName, TData>
+  onBlur?: ValidateOrFn<TParentData, TName, ValidatorType, FormValidator, TData>
+  onBlurAsync?: AsyncValidateOrFn<
+    TParentData,
+    TName,
+    ValidatorType,
+    FormValidator,
+    TData
+  >
   onBlurAsyncDebounceMs?: number
-  onSubmitAsync?: ValidateAsyncFn<TParentData, TName, TData>
+  onSubmitAsync?: AsyncValidateOrFn<
+    TParentData,
+    TName,
+    ValidatorType,
+    FormValidator,
+    TData
+  >
   defaultMeta?: Partial<FieldMeta>
 }
 
 export interface FieldApiOptions<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  TData = DeepValue<TParentData, TName>,
-> extends FieldOptions<TParentData, TName, TData> {
-  form: FormApi<TParentData>
+  ValidatorType,
+  FormValidator,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
+> extends FieldOptions<
+    TParentData,
+    TName,
+    ValidatorType,
+    FormValidator,
+    TData
+  > {
+  form: FormApi<TParentData, FormValidator>
 }
 
 export type FieldMeta = {
@@ -76,22 +145,28 @@ export type ResolveName<TParentData> = unknown extends TParentData
 export class FieldApi<
   TParentData,
   TName extends DeepKeys<TParentData>,
-  TData = DeepValue<TParentData, TName>,
+  ValidatorType,
+  FormValidator,
+  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
   uid: number
-  form: FieldApiOptions<TParentData, TName, TData>['form']
+  form: FieldApiOptions<TParentData, TName, ValidatorType, TData>['form']
   name!: DeepKeys<TParentData>
-  options: FieldApiOptions<TParentData, TName> = {} as any
+  options: FieldApiOptions<TParentData, TName, ValidatorType, TData> = {} as any
   store!: Store<FieldState<TData>>
   state!: FieldState<TData>
   prevState!: FieldState<TData>
 
   constructor(
-    opts: FieldApiOptions<TParentData, TName, TData> & {
-      form: FormApi<TParentData>
-    },
+    opts: FieldApiOptions<
+      TParentData,
+      TName,
+      ValidatorType,
+      FormValidator,
+      TData
+    >,
   ) {
-    this.form = opts.form
+    this.form = opts.form as never
     this.uid = uid++
     // Support field prefixing from FieldScope
     // let fieldPrefix = ''
@@ -99,7 +174,11 @@ export class FieldApi<
     //   fieldPrefix = `${this.form.fieldName}.`
     // }
 
-    this.name = opts.name as any
+    this.name = opts.name as never
+
+    if (opts.defaultValue !== undefined) {
+      this.form.setFieldValue(this.name, opts.defaultValue as never)
+    }
 
     this.store = new Store<FieldState<TData>>(
       {
@@ -163,12 +242,14 @@ export class FieldApi<
       unsubscribe()
       delete info.instances[this.uid]
       if (!Object.keys(info.instances).length) {
-        delete this.form.fieldInfo[this.name]
+        delete this.form.fieldInfo[this.name as never]
       }
     }
   }
 
-  update = (opts: FieldApiOptions<TParentData, TName, TData>) => {
+  update = (
+    opts: FieldApiOptions<TParentData, TName, ValidatorType, TData>,
+  ) => {
     // Default Value
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (this.state.value === undefined) {
@@ -234,10 +315,10 @@ export class FieldApi<
 
   getSubField = <
     TSubName extends DeepKeys<TData>,
-    TSubData = DeepValue<TData, TSubName>,
+    TSubData extends DeepValue<TData, TSubName> = DeepValue<TData, TSubName>,
   >(
     name: TSubName,
-  ): FieldApi<TData, TSubName, TSubData> =>
+  ): FieldApi<TData, TSubName, ValidatorType, TSubData> =>
     new FieldApi({
       name: `${this.name}.${name}` as never,
       form: this.form,
@@ -247,13 +328,36 @@ export class FieldApi<
     const { onChange, onBlur } = this.options
     const validate =
       cause === 'submit' ? undefined : cause === 'change' ? onChange : onBlur
+
     if (!validate) return
 
     // Use the validationCount for all field instances to
     // track freshness of the validation
     const validationCount = (this.getInfo().validationCount || 0) + 1
     this.getInfo().validationCount = validationCount
-    const error = normalizeError(validate(value as never, this as never))
+
+    const doValidate = () => {
+      if (this.options.validator && typeof validate !== 'function') {
+        return (this.options.validator as Validator<TData>)().validate(
+          value,
+          validate,
+        )
+      }
+
+      if (this.form.options.validator && typeof validate !== 'function') {
+        return (this.form.options.validator as Validator<TData>)().validate(
+          value,
+          validate,
+        )
+      }
+
+      return (validate as ValidateFn<TParentData, TName, ValidatorType, TData>)(
+        value,
+        this as never,
+      )
+    }
+
+    const error = normalizeError(doValidate())
     const errorMapKey = getErrorMapKey(cause)
     if (this.state.meta.errorMap[errorMapKey] !== error) {
       this.setMeta((prev) => ({
@@ -271,7 +375,7 @@ export class FieldApi<
     }
   }
 
-  #leaseValidateAsync = () => {
+  __leaseValidateAsync = () => {
     const count = (this.getInfo().validationAsyncCount || 0) + 1
     this.getInfo().validationAsyncCount = count
     return count
@@ -279,7 +383,7 @@ export class FieldApi<
 
   cancelValidateAsync = () => {
     // Lease a new validation count to ignore any pending validations
-    this.#leaseValidateAsync()
+    this.__leaseValidateAsync()
     // Cancel any pending validation state
     this.setMeta((prev) => ({
       ...prev,
@@ -313,12 +417,13 @@ export class FieldApi<
           asyncDebounceMs ??
           0
 
-    if (this.state.meta.isValidating !== true)
+    if (this.state.meta.isValidating !== true) {
       this.setMeta((prev) => ({ ...prev, isValidating: true }))
+    }
 
     // Use the validationCount for all field instances to
     // track freshness of the validation
-    const validationAsyncCount = this.#leaseValidateAsync()
+    const validationAsyncCount = this.__leaseValidateAsync()
 
     const checkLatest = () =>
       validationAsyncCount === this.getInfo().validationAsyncCount
@@ -334,11 +439,31 @@ export class FieldApi<
       await new Promise((r) => setTimeout(r, debounceMs))
     }
 
+    const doValidate = () => {
+      if (this.options.validator && typeof validate !== 'function') {
+        return (this.options.validator as Validator<TData>)().validateAsync(
+          value,
+          validate,
+        )
+      }
+
+      if (this.form.options.validator && typeof validate !== 'function') {
+        return (
+          this.form.options.validator as Validator<TData>
+        )().validateAsync(value, validate)
+      }
+
+      return (validate as ValidateFn<TParentData, TName, ValidatorType, TData>)(
+        value,
+        this as never,
+      )
+    }
+
     // Only kick off validation if this validation is the latest attempt
     if (checkLatest()) {
       const prevErrors = this.getMeta().errors
       try {
-        const rawError = await validate(value as never, this as never)
+        const rawError = await doValidate()
         if (checkLatest()) {
           const error = normalizeError(rawError)
           this.setMeta((prev) => ({
@@ -374,12 +499,18 @@ export class FieldApi<
   ): ValidationError[] | Promise<ValidationError[]> => {
     // If the field is pristine and validatePristine is false, do not validate
     if (!this.state.meta.isTouched) return []
+
+    // Store the previous error for the errorMapKey (eg. onChange, onBlur, onSubmit)
+    const errorMapKey = getErrorMapKey(cause)
+    const prevError = this.getMeta().errorMap[errorMapKey]
+
     // Attempt to sync validate first
     this.validateSync(value, cause)
 
-    const errorMapKey = getErrorMapKey(cause)
-    // If there is an error mapped to the errorMapKey (eg. onChange, onBlur, onSubmit), return the errors array, do not attempt async validation
-    if (this.getMeta().errorMap[errorMapKey]) {
+    // If there is a new error mapped to the errorMapKey (eg. onChange, onBlur, onSubmit), return the errors array, do not attempt async validation
+    const newError = this.getMeta().errorMap[errorMapKey]
+
+    if (prevError !== newError) {
       if (!this.options.asyncAlways) {
         return this.state.meta.errors
       }

package/src/FormApi.ts

@@ -1,37 +1,49 @@
 import { Store } from '@tanstack/store'
-//
 import type { DeepKeys, DeepValue, Updater } from './utils'
 import { functionalUpdate, getBy, isNonEmptyArray, setBy } from './utils'
 import type { FieldApi, FieldMeta, ValidationCause } from './FieldApi'
+import type { ValidationError, Validator } from './types'
 
-export type FormOptions<TData> = {
+type ValidateFn<TData, ValidatorType> = (
+  values: TData,
+  formApi: FormApi<TData, ValidatorType>,
+) => ValidationError
+
+type ValidateOrFn<TData, ValidatorType> = ValidatorType extends Validator<TData>
+  ? Parameters<ReturnType<ValidatorType>['validate']>[1]
+  : ValidateFn<TData, ValidatorType>
+
+type ValidateAsyncFn<TData, ValidatorType> = (
+  value: TData,
+  fieldApi: FormApi<TData, ValidatorType>,
+) => ValidationError | Promise<ValidationError>
+
+export type FormOptions<TData, ValidatorType> = {
   defaultValues?: TData
   defaultState?: Partial<FormState<TData>>
   asyncDebounceMs?: number
-  onMount?: (values: TData, formApi: FormApi<TData>) => ValidationError
-  onMountAsync?: (
-    values: TData,
-    formApi: FormApi<TData>,
-  ) => ValidationError | Promise<ValidationError>
+  validator?: ValidatorType
+  onMount?: ValidateOrFn<TData, ValidatorType>
+  onMountAsync?: ValidateAsyncFn<TData, ValidatorType>
   onMountAsyncDebounceMs?: number
-  onChange?: (values: TData, formApi: FormApi<TData>) => ValidationError
-  onChangeAsync?: (
-    values: TData,
-    formApi: FormApi<TData>,
-  ) => ValidationError | Promise<ValidationError>
+  onChange?: ValidateOrFn<TData, ValidatorType>
+  onChangeAsync?: ValidateAsyncFn<TData, ValidatorType>
   onChangeAsyncDebounceMs?: number
-  onBlur?: (values: TData, formApi: FormApi<TData>) => ValidationError
-  onBlurAsync?: (
-    values: TData,
-    formApi: FormApi<TData>,
-  ) => ValidationError | Promise<ValidationError>
+  onBlur?: ValidateOrFn<TData, ValidatorType>
+  onBlurAsync?: ValidateAsyncFn<TData, ValidatorType>
   onBlurAsyncDebounceMs?: number
-  onSubmit?: (values: TData, formApi: FormApi<TData>) => any | Promise<any>
-  onSubmitInvalid?: (values: TData, formApi: FormApi<TData>) => void
+  onSubmit?: (
+    values: TData,
+    formApi: FormApi<TData, ValidatorType>,
+  ) => any | Promise<any>
+  onSubmitInvalid?: (
+    values: TData,
+    formApi: FormApi<TData, ValidatorType>,
+  ) => void
 }
 
-export type FieldInfo<TFormData> = {
-  instances: Record<string, FieldApi<TFormData, any, any>>
+export type FieldInfo<TFormData, ValidatorType> = {
+  instances: Record<string, FieldApi<TFormData, any, unknown, ValidatorType>>
 } & ValidationMeta
 
 export type ValidationMeta = {
@@ -42,8 +54,6 @@ export type ValidationMeta = {
   validationReject?: (errors: unknown) => void
 }
 
-export type ValidationError = undefined | false | null | string
-
 export type ValidationErrorMapKeys = `on${Capitalize<ValidationCause>}`
 
 export type ValidationErrorMap = {
@@ -92,18 +102,19 @@ function getDefaultFormState<TData>(
   }
 }
 
-export class FormApi<TFormData> {
+export class FormApi<TFormData, ValidatorType> {
   // // This carries the context for nested fields
-  options: FormOptions<TFormData> = {}
+  options: FormOptions<TFormData, ValidatorType> = {}
   store!: Store<FormState<TFormData>>
   // Do not use __state directly, as it is not reactive.
   // Please use form.useStore() utility to subscribe to state
   state!: FormState<TFormData>
-  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>> = {} as any
+  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData, ValidatorType>> =
+    {} as any
   fieldName?: string
   validationMeta: ValidationMeta = {}
 
-  constructor(opts?: FormOptions<TFormData>) {
+  constructor(opts?: FormOptions<TFormData, ValidatorType>) {
     this.store = new Store<FormState<TFormData>>(
       getDefaultFormState({
         ...(opts?.defaultState as any),
@@ -157,7 +168,7 @@ export class FormApi<TFormData> {
     this.update(opts || {})
   }
 
-  update = (options?: FormOptions<TFormData>) => {
+  update = (options?: FormOptions<TFormData, ValidatorType>) => {
     if (!options) return
 
     this.store.batch(() => {
@@ -202,21 +213,21 @@ export class FormApi<TFormData> {
   validateAllFields = async (cause: ValidationCause) => {
     const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
     this.store.batch(() => {
-      void (Object.values(this.fieldInfo) as FieldInfo<any>[]).forEach(
-        (field) => {
-          Object.values(field.instances).forEach((instance) => {
-            // If any fields are not touched
-            if (!instance.state.meta.isTouched) {
-              // Mark them as touched
-              instance.setMeta((prev) => ({ ...prev, isTouched: true }))
-              // Validate the field
-              fieldValidationPromises.push(
-                Promise.resolve().then(() => instance.validate(cause)),
-              )
-            }
-          })
-        },
-      )
+      void (
+        Object.values(this.fieldInfo) as FieldInfo<any, ValidatorType>[]
+      ).forEach((field) => {
+        Object.values(field.instances).forEach((instance) => {
+          // If any fields are not touched
+          if (!instance.state.meta.isTouched) {
+            // Mark them as touched
+            instance.setMeta((prev) => ({ ...prev, isTouched: true }))
+            // Validate the field
+            fieldValidationPromises.push(
+              Promise.resolve().then(() => instance.validate(cause)),
+            )
+          }
+        })
+      })
     })
 
     return Promise.all(fieldValidationPromises)
@@ -290,7 +301,7 @@ export class FormApi<TFormData> {
 
   getFieldInfo = <TField extends DeepKeys<TFormData>>(
     field: TField,
-  ): FieldInfo<TFormData> => {
+  ): FieldInfo<TFormData, ValidatorType> => {
     // eslint-disable-next-line  @typescript-eslint/no-unnecessary-condition
     return (this.fieldInfo[field] ||= {
       instances: {},
@@ -338,7 +349,9 @@ export class FormApi<TFormData> {
 
   pushFieldValue = <TField extends DeepKeys<TFormData>>(
     field: TField,
-    value: DeepValue<TFormData, TField>[number],
+    value: DeepValue<TFormData, TField> extends any[]
+      ? DeepValue<TFormData, TField>[number]
+      : never,
     opts?: { touch?: boolean },
   ) => {
     return this.setFieldValue(
@@ -351,7 +364,9 @@ export class FormApi<TFormData> {
   insertFieldValue = <TField extends DeepKeys<TFormData>>(
     field: TField,
     index: number,
-    value: DeepValue<TFormData, TField>[number],
+    value: DeepValue<TFormData, TField> extends any[]
+      ? DeepValue<TFormData, TField>[number]
+      : never,
     opts?: { touch?: boolean },
   ) => {
     this.setFieldValue(

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './FormApi'
 export * from './FieldApi'
 export * from './utils'
+export * from './types'

package/src/tests/FieldApi.spec.ts

@@ -20,6 +20,22 @@ describe('field api', () => {
     expect(field.getValue()).toBe('test')
   })
 
+  it('should use field default value first', () => {
+    const form = new FormApi({
+      defaultValues: {
+        name: 'test',
+      },
+    })
+
+    const field = new FieldApi({
+      form,
+      defaultValue: 'other',
+      name: 'name',
+    })
+
+    expect(field.getValue()).toBe('other')
+  })
+
   it('should get default meta', () => {
     const form = new FormApi()
     const field = new FieldApi({
@@ -535,7 +551,7 @@ describe('field api', () => {
     interface Form {
       name: string
     }
-    const form = new FormApi<Form>()
+    const form = new FormApi<Form, unknown>()
 
     const field = new FieldApi({
       form,

package/src/tests/FieldApi.test-d.ts

@@ -2,24 +2,21 @@ import { assertType } from 'vitest'
 import { FormApi } from '../FormApi'
 import { FieldApi } from '../FieldApi'
 
-it('should type a subfield properly', () => {
+it('should type value properly', () => {
   const form = new FormApi({
     defaultValues: {
-      names: {
-        first: 'one',
-        second: 'two',
-      },
-    } as const,
-  })
+      name: 'test',
+    },
+  } as const)
 
   const field = new FieldApi({
     form,
-    name: 'names',
+    name: 'name',
   })
 
-  const subfield = field.getSubField('first')
-
-  assertType<'one'>(subfield.getValue())
+  assertType<'test'>(field.state.value)
+  assertType<'name'>(field.options.name)
+  assertType<'test'>(field.getValue())
 })
 
 it('should type onChange properly', () => {
@@ -39,3 +36,21 @@ it('should type onChange properly', () => {
     },
   })
 })
+
+it('should type onChangeAsync properly', () => {
+  const form = new FormApi({
+    defaultValues: {
+      name: 'test',
+    },
+  } as const)
+
+  const field = new FieldApi({
+    form,
+    name: 'name',
+    onChangeAsync: async (value) => {
+      assertType<'test'>(value)
+
+      return undefined
+    },
+  })
+})

package/src/tests/FormApi.spec.ts

@@ -119,7 +119,7 @@ describe('form api', () => {
       },
     })
 
-    form.pushFieldValue('name', 'other')
+    form.setFieldValue('name', 'other')
     form.state.submissionAttempts = 300
 
     form.reset()

package/src/types.ts

@@ -0,0 +1,7 @@
+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>
+}

package/build/legacy/chunk-4QZDOMDG.js

@@ -1,19 +0,0 @@
-var __accessCheck = (obj, member, msg) => {
-  if (!member.has(obj))
-    throw TypeError("Cannot " + msg);
-};
-var __privateGet = (obj, member, getter) => {
-  __accessCheck(obj, member, "read from private field");
-  return getter ? getter.call(obj) : member.get(obj);
-};
-var __privateAdd = (obj, member, value) => {
-  if (member.has(obj))
-    throw TypeError("Cannot add the same private member more than once");
-  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-};
-
-export {
-  __privateGet,
-  __privateAdd
-};
-//# sourceMappingURL=chunk-4QZDOMDG.js.map