@tanstack/form-core 1.6.2 → 1.7.0

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["import type { GlobalFormValidationError, ValidationCause } from './types'\nimport type { FormValidators } from './FormApi'\nimport type { AnyFieldMeta, FieldValidators } from './FieldApi'\n\nexport type UpdaterFn<TInput, TOutput = TInput> = (input: TInput) => TOutput\n\nexport type Updater<TInput, TOutput = TInput> =\n  | TOutput\n  | UpdaterFn<TInput, TOutput>\n\n/**\n * @private\n */\nexport function functionalUpdate<TInput, TOutput = TInput>(\n  updater: Updater<TInput, TOutput>,\n  input: TInput,\n): TOutput {\n  return typeof updater === 'function'\n    ? (updater as UpdaterFn<TInput, TOutput>)(input)\n    : updater\n}\n\n/**\n * Get a value from an object using a path, including dot notation.\n * @private\n */\nexport function getBy(obj: any, path: any) {\n  const pathObj = makePathArray(path)\n  return pathObj.reduce((current: any, pathPart: any) => {\n    if (current === null) return null\n    if (typeof current !== 'undefined') {\n      return current[pathPart]\n    }\n    return undefined\n  }, obj)\n}\n\n/**\n * Set a value on an object using a path, including dot notation.\n * @private\n */\nexport function setBy(obj: any, _path: any, updater: Updater<any>) {\n  const path = makePathArray(_path)\n\n  function doSet(parent?: any): any {\n    if (!path.length) {\n      return functionalUpdate(updater, parent)\n    }\n\n    const key = path.shift()\n\n    if (\n      typeof key === 'string' ||\n      (typeof key === 'number' && !Array.isArray(parent))\n    ) {\n      if (typeof parent === 'object') {\n        if (parent === null) {\n          parent = {}\n        }\n        return {\n          ...parent,\n          [key]: doSet(parent[key]),\n        }\n      }\n      return {\n        [key]: doSet(),\n      }\n    }\n\n    if (Array.isArray(parent) && typeof key === 'number') {\n      const prefix = parent.slice(0, key)\n      return [\n        ...(prefix.length ? prefix : new Array(key)),\n        doSet(parent[key]),\n        ...parent.slice(key + 1),\n      ]\n    }\n    return [...new Array(key), doSet()]\n  }\n\n  return doSet(obj)\n}\n\n/**\n * Delete a field on an object using a path, including dot notation.\n * @private\n */\nexport function deleteBy(obj: any, _path: any) {\n  const path = makePathArray(_path)\n\n  function doDelete(parent: any): any {\n    if (!parent) return\n    if (path.length === 1) {\n      const finalPath = path[0]!\n      if (Array.isArray(parent) && typeof finalPath === 'number') {\n        return parent.filter((_, i) => i !== finalPath)\n      }\n      const { [finalPath]: remove, ...rest } = parent\n      return rest\n    }\n\n    const key = path.shift()\n\n    if (typeof key === 'string') {\n      if (typeof parent === 'object') {\n        return {\n          ...parent,\n          [key]: doDelete(parent[key]),\n        }\n      }\n    }\n\n    if (typeof key === 'number') {\n      if (Array.isArray(parent)) {\n        if (key >= parent.length) {\n          return parent\n        }\n        const prefix = parent.slice(0, key)\n        return [\n          ...(prefix.length ? prefix : new Array(key)),\n          doDelete(parent[key]),\n          ...parent.slice(key + 1),\n        ]\n      }\n    }\n\n    throw new Error('It seems we have created an infinite loop in deleteBy. ')\n  }\n\n  return doDelete(obj)\n}\n\nconst reFindNumbers0 = /^(\\d*)$/gm\nconst reFindNumbers1 = /\\.(\\d*)\\./gm\nconst reFindNumbers2 = /^(\\d*)\\./gm\nconst reFindNumbers3 = /\\.(\\d*$)/gm\nconst reFindMultiplePeriods = /\\.{2,}/gm\n\nconst intPrefix = '__int__'\nconst intReplace = `${intPrefix}$1`\n\n/**\n * @private\n */\nexport function makePathArray(str: string | Array<string | number>) {\n  if (Array.isArray(str)) {\n    return [...str]\n  }\n\n  if (typeof str !== 'string') {\n    throw new Error('Path must be a string.')\n  }\n\n  return str\n    .replace(/\\[/g, '.')\n    .replace(/\\]/g, '')\n    .replace(reFindNumbers0, intReplace)\n    .replace(reFindNumbers1, `.${intReplace}.`)\n    .replace(reFindNumbers2, `${intReplace}.`)\n    .replace(reFindNumbers3, `.${intReplace}`)\n    .replace(reFindMultiplePeriods, '.')\n    .split('.')\n    .map((d) => {\n      if (d.indexOf(intPrefix) === 0) {\n        return parseInt(d.substring(intPrefix.length), 10)\n      }\n      return d\n    })\n}\n\n/**\n * @private\n */\nexport function isNonEmptyArray(obj: any) {\n  return !(Array.isArray(obj) && obj.length === 0)\n}\n\ninterface AsyncValidatorArrayPartialOptions<T> {\n  validators?: T\n  asyncDebounceMs?: number\n}\n\n/**\n * @private\n */\nexport interface AsyncValidator<T> {\n  cause: ValidationCause\n  validate: T\n  debounceMs: number\n}\n\n/**\n * @private\n */\nexport function getAsyncValidatorArray<T>(\n  cause: ValidationCause,\n  options: AsyncValidatorArrayPartialOptions<T>,\n): T extends FieldValidators<any, any, any, any, any, any, any, any, any, any>\n  ? Array<\n      AsyncValidator<T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']>\n    >\n  : T extends FormValidators<any, any, any, any, any, any, any, any>\n    ? Array<\n        AsyncValidator<\n          T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']\n        >\n      >\n    : never {\n  const { asyncDebounceMs } = options\n  const {\n    onChangeAsync,\n    onBlurAsync,\n    onSubmitAsync,\n    onBlurAsyncDebounceMs,\n    onChangeAsyncDebounceMs,\n  } = (options.validators || {}) as\n    | FieldValidators<any, any, any, any, any, any, any, any, any, any>\n    | FormValidators<any, any, any, any, any, any, any, any>\n\n  const defaultDebounceMs = asyncDebounceMs ?? 0\n\n  const changeValidator = {\n    cause: 'change',\n    validate: onChangeAsync,\n    debounceMs: onChangeAsyncDebounceMs ?? defaultDebounceMs,\n  } as const\n\n  const blurValidator = {\n    cause: 'blur',\n    validate: onBlurAsync,\n    debounceMs: onBlurAsyncDebounceMs ?? defaultDebounceMs,\n  } as const\n\n  const submitValidator = {\n    cause: 'submit',\n    validate: onSubmitAsync,\n    debounceMs: 0,\n  } as const\n\n  const noopValidator = (\n    validator:\n      | typeof changeValidator\n      | typeof blurValidator\n      | typeof submitValidator,\n  ) => ({ ...validator, debounceMs: 0 }) as const\n\n  switch (cause) {\n    case 'submit':\n      return [\n        noopValidator(changeValidator),\n        noopValidator(blurValidator),\n        submitValidator,\n      ] as never\n    case 'blur':\n      return [blurValidator] as never\n    case 'change':\n      return [changeValidator] as never\n    case 'server':\n    default:\n      return [] as never\n  }\n}\n\ninterface SyncValidatorArrayPartialOptions<T> {\n  validators?: T\n}\n\n/**\n * @private\n */\nexport interface SyncValidator<T> {\n  cause: ValidationCause\n  validate: T\n}\n\n/**\n * @private\n */\nexport function getSyncValidatorArray<T>(\n  cause: ValidationCause,\n  options: SyncValidatorArrayPartialOptions<T>,\n): T extends FieldValidators<any, any, any, any, any, any, any, any, any, any>\n  ? Array<\n      SyncValidator<T['onChange'] | T['onBlur'] | T['onSubmit'] | T['onMount']>\n    >\n  : T extends FormValidators<any, any, any, any, any, any, any, any>\n    ? Array<\n        SyncValidator<\n          T['onChange'] | T['onBlur'] | T['onSubmit'] | T['onMount']\n        >\n      >\n    : never {\n  const { onChange, onBlur, onSubmit, onMount } = (options.validators || {}) as\n    | FieldValidators<any, any, any, any, any, any, any, any, any, any>\n    | FormValidators<any, any, any, any, any, any, any, any>\n\n  const changeValidator = { cause: 'change', validate: onChange } as const\n  const blurValidator = { cause: 'blur', validate: onBlur } as const\n  const submitValidator = { cause: 'submit', validate: onSubmit } as const\n  const mountValidator = { cause: 'mount', validate: onMount } as const\n\n  // Allows us to clear onServer errors\n  const serverValidator = {\n    cause: 'server',\n    validate: () => undefined,\n  } as const\n\n  switch (cause) {\n    case 'mount':\n      return [mountValidator] as never\n    case 'submit':\n      return [\n        changeValidator,\n        blurValidator,\n        submitValidator,\n        serverValidator,\n      ] as never\n    case 'server':\n      return [serverValidator] as never\n    case 'blur':\n      return [blurValidator, serverValidator] as never\n    case 'change':\n    default:\n      return [changeValidator, serverValidator] as never\n  }\n}\n\nexport const isGlobalFormValidationError = (\n  error: unknown,\n): error is GlobalFormValidationError<unknown> => {\n  return !!error && typeof error === 'object' && 'fields' in error\n}\n\nexport function shallow<T>(objA: T, objB: T) {\n  if (Object.is(objA, objB)) {\n    return true\n  }\n\n  if (\n    typeof objA !== 'object' ||\n    objA === null ||\n    typeof objB !== 'object' ||\n    objB === null\n  ) {\n    return false\n  }\n\n  if (objA instanceof Map && objB instanceof Map) {\n    if (objA.size !== objB.size) return false\n    for (const [k, v] of objA) {\n      if (!objB.has(k) || !Object.is(v, objB.get(k))) return false\n    }\n    return true\n  }\n\n  if (objA instanceof Set && objB instanceof Set) {\n    if (objA.size !== objB.size) return false\n    for (const v of objA) {\n      if (!objB.has(v)) return false\n    }\n    return true\n  }\n\n  const keysA = Object.keys(objA)\n  if (keysA.length !== Object.keys(objB).length) {\n    return false\n  }\n\n  for (let i = 0; i < keysA.length; i++) {\n    if (\n      !Object.prototype.hasOwnProperty.call(objB, keysA[i] as string) ||\n      !Object.is(objA[keysA[i] as keyof T], objB[keysA[i] as keyof T])\n    ) {\n      return false\n    }\n  }\n  return true\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sources":["../../src/utils.ts"],"sourcesContent":["import type {\n  GlobalFormValidationError,\n  ValidationCause,\n  ValidationError,\n  ValidationSource,\n} from './types'\nimport type { FormValidators } from './FormApi'\nimport type { AnyFieldMeta, FieldValidators } from './FieldApi'\n\nexport type UpdaterFn<TInput, TOutput = TInput> = (input: TInput) => TOutput\n\nexport type Updater<TInput, TOutput = TInput> =\n  | TOutput\n  | UpdaterFn<TInput, TOutput>\n\n/**\n * @private\n */\nexport function functionalUpdate<TInput, TOutput = TInput>(\n  updater: Updater<TInput, TOutput>,\n  input: TInput,\n): TOutput {\n  return typeof updater === 'function'\n    ? (updater as UpdaterFn<TInput, TOutput>)(input)\n    : updater\n}\n\n/**\n * Get a value from an object using a path, including dot notation.\n * @private\n */\nexport function getBy(obj: any, path: any) {\n  const pathObj = makePathArray(path)\n  return pathObj.reduce((current: any, pathPart: any) => {\n    if (current === null) return null\n    if (typeof current !== 'undefined') {\n      return current[pathPart]\n    }\n    return undefined\n  }, obj)\n}\n\n/**\n * Set a value on an object using a path, including dot notation.\n * @private\n */\nexport function setBy(obj: any, _path: any, updater: Updater<any>) {\n  const path = makePathArray(_path)\n\n  function doSet(parent?: any): any {\n    if (!path.length) {\n      return functionalUpdate(updater, parent)\n    }\n\n    const key = path.shift()\n\n    if (\n      typeof key === 'string' ||\n      (typeof key === 'number' && !Array.isArray(parent))\n    ) {\n      if (typeof parent === 'object') {\n        if (parent === null) {\n          parent = {}\n        }\n        return {\n          ...parent,\n          [key]: doSet(parent[key]),\n        }\n      }\n      return {\n        [key]: doSet(),\n      }\n    }\n\n    if (Array.isArray(parent) && typeof key === 'number') {\n      const prefix = parent.slice(0, key)\n      return [\n        ...(prefix.length ? prefix : new Array(key)),\n        doSet(parent[key]),\n        ...parent.slice(key + 1),\n      ]\n    }\n    return [...new Array(key), doSet()]\n  }\n\n  return doSet(obj)\n}\n\n/**\n * Delete a field on an object using a path, including dot notation.\n * @private\n */\nexport function deleteBy(obj: any, _path: any) {\n  const path = makePathArray(_path)\n\n  function doDelete(parent: any): any {\n    if (!parent) return\n    if (path.length === 1) {\n      const finalPath = path[0]!\n      if (Array.isArray(parent) && typeof finalPath === 'number') {\n        return parent.filter((_, i) => i !== finalPath)\n      }\n      const { [finalPath]: remove, ...rest } = parent\n      return rest\n    }\n\n    const key = path.shift()\n\n    if (typeof key === 'string') {\n      if (typeof parent === 'object') {\n        return {\n          ...parent,\n          [key]: doDelete(parent[key]),\n        }\n      }\n    }\n\n    if (typeof key === 'number') {\n      if (Array.isArray(parent)) {\n        if (key >= parent.length) {\n          return parent\n        }\n        const prefix = parent.slice(0, key)\n        return [\n          ...(prefix.length ? prefix : new Array(key)),\n          doDelete(parent[key]),\n          ...parent.slice(key + 1),\n        ]\n      }\n    }\n\n    throw new Error('It seems we have created an infinite loop in deleteBy. ')\n  }\n\n  return doDelete(obj)\n}\n\nconst reFindNumbers0 = /^(\\d*)$/gm\nconst reFindNumbers1 = /\\.(\\d*)\\./gm\nconst reFindNumbers2 = /^(\\d*)\\./gm\nconst reFindNumbers3 = /\\.(\\d*$)/gm\nconst reFindMultiplePeriods = /\\.{2,}/gm\n\nconst intPrefix = '__int__'\nconst intReplace = `${intPrefix}$1`\n\n/**\n * @private\n */\nexport function makePathArray(str: string | Array<string | number>) {\n  if (Array.isArray(str)) {\n    return [...str]\n  }\n\n  if (typeof str !== 'string') {\n    throw new Error('Path must be a string.')\n  }\n\n  return str\n    .replace(/\\[/g, '.')\n    .replace(/\\]/g, '')\n    .replace(reFindNumbers0, intReplace)\n    .replace(reFindNumbers1, `.${intReplace}.`)\n    .replace(reFindNumbers2, `${intReplace}.`)\n    .replace(reFindNumbers3, `.${intReplace}`)\n    .replace(reFindMultiplePeriods, '.')\n    .split('.')\n    .map((d) => {\n      if (d.indexOf(intPrefix) === 0) {\n        return parseInt(d.substring(intPrefix.length), 10)\n      }\n      return d\n    })\n}\n\n/**\n * @private\n */\nexport function isNonEmptyArray(obj: any) {\n  return !(Array.isArray(obj) && obj.length === 0)\n}\n\ninterface AsyncValidatorArrayPartialOptions<T> {\n  validators?: T\n  asyncDebounceMs?: number\n}\n\n/**\n * @private\n */\nexport interface AsyncValidator<T> {\n  cause: ValidationCause\n  validate: T\n  debounceMs: number\n}\n\n/**\n * @private\n */\nexport function getAsyncValidatorArray<T>(\n  cause: ValidationCause,\n  options: AsyncValidatorArrayPartialOptions<T>,\n): T extends FieldValidators<any, any, any, any, any, any, any, any, any, any>\n  ? Array<\n      AsyncValidator<T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']>\n    >\n  : T extends FormValidators<any, any, any, any, any, any, any, any>\n    ? Array<\n        AsyncValidator<\n          T['onChangeAsync'] | T['onBlurAsync'] | T['onSubmitAsync']\n        >\n      >\n    : never {\n  const { asyncDebounceMs } = options\n  const {\n    onChangeAsync,\n    onBlurAsync,\n    onSubmitAsync,\n    onBlurAsyncDebounceMs,\n    onChangeAsyncDebounceMs,\n  } = (options.validators || {}) as\n    | FieldValidators<any, any, any, any, any, any, any, any, any, any>\n    | FormValidators<any, any, any, any, any, any, any, any>\n\n  const defaultDebounceMs = asyncDebounceMs ?? 0\n\n  const changeValidator = {\n    cause: 'change',\n    validate: onChangeAsync,\n    debounceMs: onChangeAsyncDebounceMs ?? defaultDebounceMs,\n  } as const\n\n  const blurValidator = {\n    cause: 'blur',\n    validate: onBlurAsync,\n    debounceMs: onBlurAsyncDebounceMs ?? defaultDebounceMs,\n  } as const\n\n  const submitValidator = {\n    cause: 'submit',\n    validate: onSubmitAsync,\n    debounceMs: 0,\n  } as const\n\n  const noopValidator = (\n    validator:\n      | typeof changeValidator\n      | typeof blurValidator\n      | typeof submitValidator,\n  ) => ({ ...validator, debounceMs: 0 }) as const\n\n  switch (cause) {\n    case 'submit':\n      return [\n        noopValidator(changeValidator),\n        noopValidator(blurValidator),\n        submitValidator,\n      ] as never\n    case 'blur':\n      return [blurValidator] as never\n    case 'change':\n      return [changeValidator] as never\n    case 'server':\n    default:\n      return [] as never\n  }\n}\n\ninterface SyncValidatorArrayPartialOptions<T> {\n  validators?: T\n}\n\n/**\n * @private\n */\nexport interface SyncValidator<T> {\n  cause: ValidationCause\n  validate: T\n}\n\n/**\n * @private\n */\nexport function getSyncValidatorArray<T>(\n  cause: ValidationCause,\n  options: SyncValidatorArrayPartialOptions<T>,\n): T extends FieldValidators<any, any, any, any, any, any, any, any, any, any>\n  ? Array<\n      SyncValidator<T['onChange'] | T['onBlur'] | T['onSubmit'] | T['onMount']>\n    >\n  : T extends FormValidators<any, any, any, any, any, any, any, any>\n    ? Array<\n        SyncValidator<\n          T['onChange'] | T['onBlur'] | T['onSubmit'] | T['onMount']\n        >\n      >\n    : never {\n  const { onChange, onBlur, onSubmit, onMount } = (options.validators || {}) as\n    | FieldValidators<any, any, any, any, any, any, any, any, any, any>\n    | FormValidators<any, any, any, any, any, any, any, any>\n\n  const changeValidator = { cause: 'change', validate: onChange } as const\n  const blurValidator = { cause: 'blur', validate: onBlur } as const\n  const submitValidator = { cause: 'submit', validate: onSubmit } as const\n  const mountValidator = { cause: 'mount', validate: onMount } as const\n\n  // Allows us to clear onServer errors\n  const serverValidator = {\n    cause: 'server',\n    validate: () => undefined,\n  } as const\n\n  switch (cause) {\n    case 'mount':\n      return [mountValidator] as never\n    case 'submit':\n      return [\n        changeValidator,\n        blurValidator,\n        submitValidator,\n        serverValidator,\n      ] as never\n    case 'server':\n      return [serverValidator] as never\n    case 'blur':\n      return [blurValidator, serverValidator] as never\n    case 'change':\n    default:\n      return [changeValidator, serverValidator] as never\n  }\n}\n\nexport const isGlobalFormValidationError = (\n  error: unknown,\n): error is GlobalFormValidationError<unknown> => {\n  return !!error && typeof error === 'object' && 'fields' in error\n}\n\nexport function shallow<T>(objA: T, objB: T) {\n  if (Object.is(objA, objB)) {\n    return true\n  }\n\n  if (\n    typeof objA !== 'object' ||\n    objA === null ||\n    typeof objB !== 'object' ||\n    objB === null\n  ) {\n    return false\n  }\n\n  if (objA instanceof Map && objB instanceof Map) {\n    if (objA.size !== objB.size) return false\n    for (const [k, v] of objA) {\n      if (!objB.has(k) || !Object.is(v, objB.get(k))) return false\n    }\n    return true\n  }\n\n  if (objA instanceof Set && objB instanceof Set) {\n    if (objA.size !== objB.size) return false\n    for (const v of objA) {\n      if (!objB.has(v)) return false\n    }\n    return true\n  }\n\n  const keysA = Object.keys(objA)\n  if (keysA.length !== Object.keys(objB).length) {\n    return false\n  }\n\n  for (let i = 0; i < keysA.length; i++) {\n    if (\n      !Object.prototype.hasOwnProperty.call(objB, keysA[i] as string) ||\n      !Object.is(objA[keysA[i] as keyof T], objB[keysA[i] as keyof T])\n    ) {\n      return false\n    }\n  }\n  return true\n}\n\n/**\n * Determines the logic for determining the error source and value to set on the field meta within the form level sync/async validation.\n * @private\n */\nexport const determineFormLevelErrorSourceAndValue = ({\n  newFormValidatorError,\n  isPreviousErrorFromFormValidator,\n  previousErrorValue,\n}: {\n  newFormValidatorError: ValidationError\n  isPreviousErrorFromFormValidator: boolean\n  previousErrorValue: ValidationError\n}): {\n  newErrorValue: ValidationError\n  newSource: ValidationSource | undefined\n} => {\n  // All falsy values are not considered errors\n  if (newFormValidatorError) {\n    return { newErrorValue: newFormValidatorError, newSource: 'form' }\n  }\n\n  // Clears form level error since it's now stale\n  if (isPreviousErrorFromFormValidator) {\n    return { newErrorValue: undefined, newSource: undefined }\n  }\n\n  // At this point, we have a preivous error which must have been set by the field validator, keep as is\n  if (previousErrorValue) {\n    return { newErrorValue: previousErrorValue, newSource: 'field' }\n  }\n\n  // No new or previous error, clear the error\n  return { newErrorValue: undefined, newSource: undefined }\n}\n\n/**\n * Determines the logic for determining the error source and value to set on the field meta within the field level sync/async validation.\n * @private\n */\nexport const determineFieldLevelErrorSourceAndValue = ({\n  formLevelError,\n  fieldLevelError,\n}: {\n  formLevelError: ValidationError\n  fieldLevelError: ValidationError\n}): {\n  newErrorValue: ValidationError\n  newSource: ValidationSource | undefined\n} => {\n  // At field level, we prioritize the field level error\n  if (fieldLevelError) {\n    return { newErrorValue: fieldLevelError, newSource: 'field' }\n  }\n\n  // If there is no field level error, and there is a form level error, we set the form level error\n  if (formLevelError) {\n    return { newErrorValue: formLevelError, newSource: 'form' }\n  }\n\n  return { newErrorValue: undefined, newSource: undefined }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/form-core",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Powerful, type-safe, framework agnostic forms.",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -40,9 +40,9 @@
     "@tanstack/store": "^0.7.0"
   },
   "devDependencies": {
-    "arktype": "^2.1.19",
+    "arktype": "^2.1.20",
     "valibot": "^1.0.0",
-    "zod": "^3.24.2"
+    "zod": "^3.24.3"
   },
   "scripts": {}
 }

package/src/FieldApi.ts

@@ -4,7 +4,12 @@ import {
   standardSchemaValidators,
 } from './standardSchemaValidator'
 import { defaultFieldMeta } from './metaHelper'
-import { getAsyncValidatorArray, getBy, getSyncValidatorArray } from './utils'
+import {
+  determineFieldLevelErrorSourceAndValue,
+  getAsyncValidatorArray,
+  getBy,
+  getSyncValidatorArray,
+} from './utils'
 import type { DeepKeys, DeepValue, UnwrapOneLevelOfArray } from './util-types'
 import type {
   StandardSchemaV1,
@@ -25,6 +30,7 @@ import type {
   ValidationCause,
   ValidationError,
   ValidationErrorMap,
+  ValidationErrorMapSource,
 } from './types'
 import type { AsyncValidator, SyncValidator, Updater } from './utils'
 
@@ -561,6 +567,10 @@ export type FieldMetaBase<
     UnwrapFieldValidateOrFn<TName, TOnSubmit, TFormOnSubmit>,
     UnwrapFieldAsyncValidateOrFn<TName, TOnSubmitAsync, TFormOnSubmitAsync>
   >
+  /**
+   * @private allows tracking the source of the errors in the error map
+   */
+  errorSourceMap: ValidationErrorMapSource
   /**
    * A flag indicating whether the field is currently being validated.
    */
@@ -1101,6 +1111,11 @@ export class FieldApi<
               ...prev,
               // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
               errorMap: { ...prev?.errorMap, onMount: error },
+              errorSourceMap: {
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                ...prev?.errorSourceMap,
+                onMount: 'field',
+              },
             }) as never,
         )
       }
@@ -1345,39 +1360,43 @@ export class FieldApi<
       ) => {
         const errorMapKey = getErrorMapKey(validateObj.cause)
 
-        const error =
-          /*
-            If `validateObj.validate` is `undefined`, then the field doesn't have
-            a validator for this event, but there still could be an error that
-            needs to be cleaned up related to the current event left by the
-            form's validator.
-          */
-          validateObj.validate
-            ? normalizeError(
-                field.runValidator({
-                  validate: validateObj.validate,
-                  value: {
-                    value: field.store.state.value,
-                    validationSource: 'field',
-                    fieldApi: field,
-                  },
-                  type: 'validate',
-                }),
-              )
-            : errorFromForm[errorMapKey]
+        const fieldLevelError = validateObj.validate
+          ? normalizeError(
+              field.runValidator({
+                validate: validateObj.validate,
+                value: {
+                  value: field.store.state.value,
+                  validationSource: 'field',
+                  fieldApi: field,
+                },
+                type: 'validate',
+              }),
+            )
+          : undefined
+
+        const formLevelError = errorFromForm[errorMapKey]
 
-        if (field.state.meta.errorMap[errorMapKey] !== error) {
+        const { newErrorValue, newSource } =
+          determineFieldLevelErrorSourceAndValue({
+            formLevelError,
+            fieldLevelError,
+          })
+
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (field.state.meta.errorMap?.[errorMapKey] !== newErrorValue) {
           field.setMeta((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [getErrorMapKey(validateObj.cause)]:
-                // Prefer the error message from the field validators if they exist
-                error ? error : errorFromForm[errorMapKey],
+              [errorMapKey]: newErrorValue,
+            },
+            errorSourceMap: {
+              ...prev.errorSourceMap,
+              [errorMapKey]: newSource,
             },
           }))
         }
-        if (error || errorFromForm[errorMapKey]) {
+        if (newErrorValue) {
           hasErrored = true
         }
       }
@@ -1398,7 +1417,8 @@ export class FieldApi<
     const submitErrKey = getErrorMapKey('submit')
 
     if (
-      this.state.meta.errorMap[submitErrKey] &&
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      this.state.meta.errorMap?.[submitErrKey] &&
       cause !== 'submit' &&
       !hasErrored
     ) {
@@ -1408,6 +1428,10 @@ export class FieldApi<
           ...prev.errorMap,
           [submitErrKey]: undefined,
         },
+        errorSourceMap: {
+          ...prev.errorSourceMap,
+          [submitErrKey]: undefined,
+        },
       }))
     }
 
@@ -1521,22 +1545,33 @@ export class FieldApi<
             rawError = e as ValidationError
           }
           if (controller.signal.aborted) return resolve(undefined)
-          const error = normalizeError(rawError)
-          const fieldErrorFromForm =
+
+          const fieldLevelError = normalizeError(rawError)
+          const formLevelError =
             asyncFormValidationResults[this.name]?.[errorMapKey]
-          const fieldError = error || fieldErrorFromForm
+
+          const { newErrorValue, newSource } =
+            determineFieldLevelErrorSourceAndValue({
+              formLevelError,
+              fieldLevelError,
+            })
+
           field.setMeta((prev) => {
             return {
               ...prev,
               errorMap: {
                 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
                 ...prev?.errorMap,
-                [errorMapKey]: fieldError,
+                [errorMapKey]: newErrorValue,
+              },
+              errorSourceMap: {
+                ...prev.errorSourceMap,
+                [errorMapKey]: newSource,
               },
             }
           })
 
-          resolve(fieldError)
+          resolve(newErrorValue)
         }),
       )
     }
@@ -1669,6 +1704,10 @@ export class FieldApi<
 
   private triggerOnBlurListener() {
     const debounceMs = this.options.listeners?.onBlurDebounceMs
+    this.form.options.listeners?.onBlur?.({
+      formApi: this.form,
+      fieldApi: this,
+    })
 
     if (debounceMs && debounceMs > 0) {
       if (this.timeoutIds.listeners.blur) {
@@ -1692,6 +1731,11 @@ export class FieldApi<
   private triggerOnChangeListener() {
     const debounceMs = this.options.listeners?.onChangeDebounceMs
 
+    this.form.options.listeners?.onChange?.({
+      formApi: this.form,
+      fieldApi: this,
+    })
+
     if (debounceMs && debounceMs > 0) {
       if (this.timeoutIds.listeners.change) {
         clearTimeout(this.timeoutIds.listeners.change)

package/src/FormApi.ts

@@ -1,6 +1,7 @@
 import { Derived, Store, batch } from '@tanstack/store'
 import {
   deleteBy,
+  determineFormLevelErrorSourceAndValue,
   functionalUpdate,
   getAsyncValidatorArray,
   getBy,
@@ -21,7 +22,12 @@ import type {
   StandardSchemaV1Issue,
   TStandardSchemaValidatorValue,
 } from './standardSchemaValidator'
-import type { AnyFieldMeta, AnyFieldMetaBase, FieldApi } from './FieldApi'
+import type {
+  AnyFieldApi,
+  AnyFieldMeta,
+  AnyFieldMetaBase,
+  FieldApi,
+} from './FieldApi'
 import type {
   FormValidationError,
   FormValidationErrorMap,
@@ -232,6 +238,81 @@ export interface FormTransform<
   deps: unknown[]
 }
 
+export interface FormListeners<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData>,
+  TOnChange extends undefined | FormValidateOrFn<TFormData>,
+  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
+  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta = never,
+> {
+  onChange?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+    fieldApi: AnyFieldApi
+  }) => void
+
+  onBlur?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+    fieldApi: AnyFieldApi
+  }) => void
+
+  onMount?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+  }) => void
+
+  onSubmit?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+  }) => void
+}
+
 /**
  * An object representing the options for a form.
  */
@@ -298,6 +379,22 @@ export interface FormOptions<
    */
   onSubmitMeta?: TSubmitMeta
 
+  /**
+   * form level listeners
+   */
+  listeners?: FormListeners<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnServer,
+    TSubmitMeta
+  >
+
   /**
    * A function to be called when the form is submitted, what should happen once the user submits a valid form returns `any` or a promise `Promise<any>`
    */
@@ -733,22 +830,6 @@ export class FormApi<
    */
   prevTransformArray: unknown[] = []
 
-  /**
-   * @private Persistent store of all field validation errors originating from form-level validators.
-   * Maintains the cumulative state across validation cycles, including cleared errors (undefined values).
-   * This map preserves the complete validation state for all fields.
-   */
-  cumulativeFieldsErrorMap: FormErrorMapFromValidator<
-    TFormData,
-    TOnMount,
-    TOnChange,
-    TOnChangeAsync,
-    TOnBlur,
-    TOnBlurAsync,
-    TOnSubmit,
-    TOnSubmitAsync
-  > = {}
-
   /**
    * Constructs a new `FormApi` instance with the given form options.
    */
@@ -1064,6 +1145,9 @@ export class FormApi<
       cleanupFieldMetaDerived()
       cleanupStoreDerived()
     }
+
+    this.options.listeners?.onMount?.({ formApi: this })
+
     const { onMount } = this.options.validators || {}
     if (!onMount) return cleanup
     this.validateSync('mount')
@@ -1306,56 +1390,56 @@ export class FormApi<
 
         const errorMapKey = getErrorMapKey(validateObj.cause)
 
-        if (fieldErrors) {
-          for (const [field, fieldError] of Object.entries(fieldErrors) as [
-            DeepKeys<TFormData>,
-            ValidationError,
-          ][]) {
-            const oldErrorMap = this.cumulativeFieldsErrorMap[field] || {}
-            const newErrorMap = {
-              ...oldErrorMap,
-              [errorMapKey]: fieldError,
-            }
-            currentValidationErrorMap[field] = newErrorMap
-            this.cumulativeFieldsErrorMap[field] = newErrorMap
+        for (const field of Object.keys(
+          this.state.fieldMeta,
+        ) as DeepKeys<TFormData>[]) {
+          const fieldMeta = this.getFieldMeta(field)
+          if (!fieldMeta) continue
+
+          const {
+            errorMap: currentErrorMap,
+            errorSourceMap: currentErrorMapSource,
+          } = fieldMeta
+
+          const newFormValidatorError = fieldErrors?.[field]
+
+          const { newErrorValue, newSource } =
+            determineFormLevelErrorSourceAndValue({
+              newFormValidatorError,
+              isPreviousErrorFromFormValidator:
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                currentErrorMapSource?.[errorMapKey] === 'form',
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              previousErrorValue: currentErrorMap?.[errorMapKey],
+            })
 
-            const fieldMeta = this.getFieldMeta(field)
-            if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
-              this.setFieldMeta(field, (prev) => ({
-                ...prev,
-                errorMap: {
-                  ...prev.errorMap,
-                  [errorMapKey]: fieldError,
-                },
-              }))
+          if (newSource === 'form') {
+            currentValidationErrorMap[field] = {
+              ...currentValidationErrorMap[field],
+              [errorMapKey]: newFormValidatorError,
             }
           }
-        }
 
-        for (const field of Object.keys(this.cumulativeFieldsErrorMap) as Array<
-          DeepKeys<TFormData>
-        >) {
-          const fieldMeta = this.getFieldMeta(field)
           if (
-            fieldMeta?.errorMap[errorMapKey] &&
-            !currentValidationErrorMap[field]?.[errorMapKey]
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            currentErrorMap?.[errorMapKey] !== newErrorValue
           ) {
-            this.cumulativeFieldsErrorMap[field] = {
-              ...this.cumulativeFieldsErrorMap[field],
-              [errorMapKey]: undefined,
-            }
-
             this.setFieldMeta(field, (prev) => ({
               ...prev,
               errorMap: {
                 ...prev.errorMap,
-                [errorMapKey]: undefined,
+                [errorMapKey]: newErrorValue,
+              },
+              errorSourceMap: {
+                ...prev.errorSourceMap,
+                [errorMapKey]: newSource,
               },
             }))
           }
         }
 
-        if (this.state.errorMap[errorMapKey] !== formError) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (this.state.errorMap?.[errorMapKey] !== formError) {
           this.baseStore.setState((prev) => ({
             ...prev,
             errorMap: {
@@ -1376,7 +1460,8 @@ export class FormApi<
        */
       const submitErrKey = getErrorMapKey('submit')
       if (
-        this.state.errorMap[submitErrKey] &&
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        this.state.errorMap?.[submitErrKey] &&
         cause !== 'submit' &&
         !hasErrored
       ) {
@@ -1422,7 +1507,7 @@ export class FormApi<
      */
     const promises: Promise<ValidationPromiseResult<TFormData>>[] = []
 
-    let fieldErrors:
+    let fieldErrorsFromFormValidators:
       | Partial<Record<DeepKeys<TFormData>, ValidationError>>
       | undefined
 
@@ -1473,26 +1558,56 @@ export class FormApi<
             normalizeError<TFormData>(rawError)
 
           if (fieldErrorsFromNormalizeError) {
-            fieldErrors = fieldErrors
-              ? { ...fieldErrors, ...fieldErrorsFromNormalizeError }
+            fieldErrorsFromFormValidators = fieldErrorsFromFormValidators
+              ? {
+                  ...fieldErrorsFromFormValidators,
+                  ...fieldErrorsFromNormalizeError,
+                }
               : fieldErrorsFromNormalizeError
           }
           const errorMapKey = getErrorMapKey(validateObj.cause)
 
-          if (fieldErrors) {
-            for (const [field, fieldError] of Object.entries(fieldErrors)) {
-              const fieldMeta = this.getFieldMeta(field as DeepKeys<TFormData>)
-              if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
-                this.setFieldMeta(field as DeepKeys<TFormData>, (prev) => ({
-                  ...prev,
-                  errorMap: {
-                    ...prev.errorMap,
-                    [errorMapKey]: fieldError,
-                  },
-                }))
-              }
+          for (const field of Object.keys(
+            this.state.fieldMeta,
+          ) as DeepKeys<TFormData>[]) {
+            const fieldMeta = this.getFieldMeta(field)
+            if (!fieldMeta) continue
+
+            const {
+              errorMap: currentErrorMap,
+              errorSourceMap: currentErrorMapSource,
+            } = fieldMeta
+
+            const newFormValidatorError = fieldErrorsFromFormValidators?.[field]
+
+            const { newErrorValue, newSource } =
+              determineFormLevelErrorSourceAndValue({
+                newFormValidatorError,
+                isPreviousErrorFromFormValidator:
+                  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                  currentErrorMapSource?.[errorMapKey] === 'form',
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                previousErrorValue: currentErrorMap?.[errorMapKey],
+              })
+
+            if (
+              // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+              currentErrorMap?.[errorMapKey] !== newErrorValue
+            ) {
+              this.setFieldMeta(field, (prev) => ({
+                ...prev,
+                errorMap: {
+                  ...prev.errorMap,
+                  [errorMapKey]: newErrorValue,
+                },
+                errorSourceMap: {
+                  ...prev.errorSourceMap,
+                  [errorMapKey]: newSource,
+                },
+              }))
             }
           }
+
           this.baseStore.setState((prev) => ({
             ...prev,
             errorMap: {
@@ -1501,7 +1616,11 @@ export class FormApi<
             },
           }))
 
-          resolve(fieldErrors ? { fieldErrors, errorMapKey } : undefined)
+          resolve(
+            fieldErrorsFromFormValidators
+              ? { fieldErrors: fieldErrorsFromFormValidators, errorMapKey }
+              : undefined,
+          )
         }),
       )
     }
@@ -1587,7 +1706,7 @@ export class FormApi<
   }
 
   /**
-   * Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
+   * Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.
    */
   handleSubmit(): Promise<void>
   handleSubmit(submitMeta: TSubmitMeta): Promise<void>
@@ -1656,6 +1775,8 @@ export class FormApi<
       )
     })
 
+    this.options.listeners?.onSubmit?.({ formApi: this })
+
     try {
       // Run the submit code
       await this.options.onSubmit?.({

package/src/metaHelper.ts

@@ -16,6 +16,7 @@ export const defaultFieldMeta: AnyFieldMeta = {
   isPristine: true,
   errors: [],
   errorMap: {},
+  errorSourceMap: {},
 }
 
 export function metaHelper<