feat(form-core): add array method field.filterValues and form.filterFieldValues

Pascalmh · LeCarbonator · Pascalmh · commit 506523e76e41 · 2025-04-17T08:47:05.000+02:00
Co-authored-by: LeCarbonator &lt;18158911+LeCarbonator@users.noreply.github.com&gt;
diff --git a/packages/form-core/src/FieldApi.ts b/packages/form-core/src/FieldApi.ts
@@ -1288,6 +1288,27 @@ export class FieldApi<
     this.triggerOnChangeListener()
   }
 
+  /**
+   * Filter values in the array using the provided predicate callback.
+   * @param predicate — The predicate callback to pass to the array's filter function.
+   * @param opts
+   */
+  filterValues = (
+    predicate: (
+      value: TData extends Array<any> ? TData[number] : never,
+      index: number,
+      array: TData,
+    ) => boolean,
+    opts?: UpdateMetaOptions & {
+      /** `thisArg` — An object to which the `this` keyword can refer in the predicate function. If thisArg is omitted, undefined is used as the `this` value. */
+      thisArg?: any
+    },
+  ) => {
+    this.form.filterFieldValues(this.name, predicate, opts)
+
+    this.triggerOnChangeListener()
+  }
+
   /**
    * @private
    */
diff --git a/packages/form-core/src/FormApi.ts b/packages/form-core/src/FormApi.ts
@@ -1962,6 +1962,87 @@ export class FormApi<
     this.validateField(`${field}[${index2}]` as DeepKeys<TFormData>, 'change')
   }
 
+  /**
+   * Filter the array values by the provided predicate.
+   * @param field
+   * @param predicate — The predicate callback to pass to the array's filter function.
+   * @param opts
+   */
+  filterFieldValues = <
+    TField extends DeepKeys<TFormData>,
+    TData extends DeepValue<TFormData, TField>,
+  >(
+    field: TField,
+    predicate: (
+      value: TData extends Array<any> ? TData[number] : never,
+      index: number,
+      array: TData,
+    ) => boolean,
+    opts?: UpdateMetaOptions & {
+      /** `thisArg` — An object to which the `this` keyword can refer in the predicate function. If thisArg is omitted, undefined is used as the `this` value. */
+      thisArg?: any
+    },
+  ) => {
+    const { thisArg, ...metaOpts } = opts ?? {}
+    const fieldValue = this.getFieldValue(field)
+
+    const arrayData = {
+      previousLength: Array.isArray(fieldValue)
+        ? (fieldValue as unknown[]).length
+        : null,
+      validateFromIndex: null as number | null,
+    }
+
+    const remainingIndeces: number[] = []
+
+    const filterFunction =
+      opts?.thisArg === undefined ? predicate : predicate.bind(opts.thisArg)
+
+    this.setFieldValue(
+      field,
+      (prev: any) =>
+        prev.filter((value: any, index: number, array: TData) => {
+          const keepElement = filterFunction(value, index, array)
+          if (!keepElement) {
+            // remember the first index that got filtered
+            arrayData.validateFromIndex ??= index
+            return false
+          }
+          remainingIndeces.push(index)
+          return true
+        }),
+      metaOpts,
+    )
+
+    // Shift meta accounting for filtered values
+    metaHelper(this).handleArrayFieldMetaShift(
+      field,
+      remainingIndeces,
+      'filter',
+    )
+
+    // remove dangling fields if the filter call reduced the length of the array
+    if (
+      arrayData.previousLength !== null &&
+      remainingIndeces.length !== arrayData.previousLength
+    ) {
+      for (let i = remainingIndeces.length; i < arrayData.previousLength; i++) {
+        const fieldKey = `${field}[${i}]`
+        this.deleteField(fieldKey as never)
+      }
+    }
+
+    // validate the array and the fields starting from the shifted elements
+    this.validateField(field, 'change')
+    if (arrayData.validateFromIndex !== null) {
+      this.validateArrayFieldsStartingFrom(
+        field,
+        arrayData.validateFromIndex,
+        'change',
+      )
+    }
+  }
+
   /**
    * Resets the field value and meta to default state
    */
diff --git a/packages/form-core/src/metaHelper.ts b/packages/form-core/src/metaHelper.ts
@@ -6,7 +6,8 @@ import type {
 import type { AnyFieldMeta } from './FieldApi'
 import type { DeepKeys } from './util-types'
 
-type ArrayFieldMode = 'insert' | 'remove' | 'swap' | 'move'
+type ValueFieldMode = 'insert' | 'remove' | 'swap' | 'move'
+type ArrayFieldMode = 'filter'
 
 export const defaultFieldMeta: AnyFieldMeta = {
   isValidating: false,
@@ -45,34 +46,63 @@ export function metaHelper<
 ) {
   function handleArrayFieldMetaShift(
     field: DeepKeys<TFormData>,
-    index: number,
+    remainingIndeces: number[],
     mode: ArrayFieldMode,
+  ): void
+  function handleArrayFieldMetaShift(
+    field: DeepKeys<TFormData>,
+    index: number,
+    mode: ValueFieldMode,
+    secondIndex?: number,
+  ): void
+  function handleArrayFieldMetaShift(
+    field: DeepKeys<TFormData>,
+    index: number | number[],
+    mode: ArrayFieldMode | ValueFieldMode,
     secondIndex?: number,
   ) {
-    const affectedFields = getAffectedFields(field, index, mode, secondIndex)
-
-    const handlers = {
-      insert: () => handleInsertMode(affectedFields, field, index),
-      remove: () => handleRemoveMode(affectedFields),
-      swap: () =>
-        secondIndex !== undefined &&
-        handleSwapMode(affectedFields, field, index, secondIndex),
-      move: () =>
-        secondIndex !== undefined &&
-        handleMoveMode(affectedFields, field, index, secondIndex),
-    }
+    if (Array.isArray(index)) {
+      if (mode === 'filter') {
+        return handleFilterMode(field, index)
+      }
+    } else {
+      const affectedFields = getAffectedFields(
+        field,
+        index,
+        mode as ValueFieldMode,
+        secondIndex,
+      )
 
-    handlers[mode]()
+      switch (mode as ValueFieldMode) {
+        case 'insert':
+          return handleInsertMode(affectedFields, field, index)
+        case 'remove':
+          return handleRemoveMode(affectedFields)
+        case 'swap':
+          return (
+            secondIndex !== undefined &&
+            handleSwapMode(affectedFields, field, index, secondIndex)
+          )
+        case 'move':
+          return (
+            secondIndex !== undefined &&
+            handleMoveMode(affectedFields, field, index, secondIndex)
+          )
+      }
+    }
   }
 
-  function getFieldPath(field: DeepKeys<TFormData>, index: number): string {
-    return `${field}[${index}]`
+  function getFieldPath(
+    field: DeepKeys<TFormData>,
+    index: number,
+  ): DeepKeys<TFormData> {
+    return `${field}[${index}]` as DeepKeys<TFormData>
   }
 
   function getAffectedFields(
     field: DeepKeys<TFormData>,
     index: number,
-    mode: ArrayFieldMode,
+    mode: ValueFieldMode,
     secondIndex?: number,
   ): DeepKeys<TFormData>[] {
     const affectedFieldKeys = [getFieldPath(field, index)]
@@ -148,6 +178,30 @@ export function metaHelper<
     shiftMeta(fields, 'up')
   }
 
+  const handleFilterMode = (
+    field: DeepKeys<TFormData>,
+    remainingIndices: number[],
+  ) => {
+    if (remainingIndices.length === 0) return
+
+    // create a map between the index and its new location
+    remainingIndices.forEach((fromIndex, toIndex) => {
+      if (fromIndex === toIndex) return
+      // assign it the original meta
+      const fieldKey = getFieldPath(field, toIndex)
+      const originalFieldKey = getFieldPath(field, fromIndex)
+      const originalFieldMeta = formApi.getFieldMeta(originalFieldKey)
+      if (originalFieldMeta) {
+        formApi.setFieldMeta(fieldKey, originalFieldMeta)
+      } else {
+        formApi.setFieldMeta(fieldKey, {
+          ...getEmptyFieldMeta(),
+          isTouched: originalFieldKey as unknown as boolean,
+        })
+      }
+    })
+  }
+
   const handleMoveMode = (
     fields: DeepKeys<TFormData>[],
     field: DeepKeys<TFormData>,
diff --git a/packages/form-core/tests/FieldApi.spec.ts b/packages/form-core/tests/FieldApi.spec.ts
@@ -1195,6 +1195,9 @@ describe('field api', () => {
 
     field.moveValue(0, 1)
     expect(arr).toStrictEqual(['middle', 'end', 'start'])
+
+    field.filterValues((value) => value !== 'start')
+    expect(arr).toStrictEqual(['middle', 'end'])
   })
 
   it('should reset the form on a listener', () => {
@@ -2051,4 +2054,120 @@ describe('field api', () => {
       field.parseValueWithSchemaAsync(z.any())
     }).not.toThrowError()
   })
+
+  it('should filter array values using the predicate when calling filterValues', async () => {
+    const form = new FormApi({
+      defaultValues: {
+        names: ['one', 'two', 'three'],
+      },
+    })
+
+    form.mount()
+
+    const field = new FieldApi({
+      form,
+      name: 'names',
+    })
+
+    field.mount()
+
+    field.filterValues((value) => value !== 'two')
+    expect(field.state.value).toStrictEqual(['one', 'three'])
+
+    field.filterValues((value) => value !== 'never')
+    expect(field.state.value).toStrictEqual(['one', 'three'])
+  })
+
+  it('should bind the predicate to the provided thisArg when calling filterValues', async () => {
+    // Very dirty way, but quick way to enforce lost `this` context
+    function SomeClass(this: any) {
+      this.check = 'correct this'
+    }
+    SomeClass.prototype.filterFunc = function () {
+      return this?.check === 'correct this'
+    }
+    // @ts-expect-error The 'new' expression expects class stuff, but
+    // we're trying to force ugly code in this unit test.
+    const instance = new SomeClass()
+
+    const predicate = instance.filterFunc
+
+    const form = new FormApi({
+      defaultValues: {
+        names: ['one', 'two', 'three'],
+      },
+    })
+
+    const field = new FieldApi({
+      form,
+      name: 'names',
+    })
+
+    form.mount()
+    field.mount()
+
+    field.filterValues(predicate, { thisArg: instance })
+    // thisArg was bound, expect it to have returned true
+    expect(field.state.value).toStrictEqual(['one', 'two', 'three'])
+    field.filterValues(predicate)
+    // thisArg wasn't bound, expect it to have returned false
+    expect(field.state.value).toStrictEqual([])
+  })
+
+  it('should run onChange validation on the array when calling filterValues', async () => {
+    vi.useFakeTimers()
+    const form = new FormApi({
+      defaultValues: {
+        names: ['one', 'two', 'three', 'four', 'five'],
+      },
+    })
+    form.mount()
+    function getField(i: number) {
+      return new FieldApi({
+        name: `names[${i}]`,
+        form,
+        validators: {
+          onChange: () => 'error',
+        },
+      })
+    }
+
+    const arrayField = new FieldApi({
+      form,
+      name: 'names',
+      validators: {
+        onChange: () => 'error',
+      },
+    })
+    arrayField.mount()
+
+    const field0 = getField(0)
+    const field1 = getField(1)
+    const field2 = getField(2)
+    const field3 = getField(3)
+    const field4 = getField(4)
+    field0.mount()
+    field1.mount()
+    field2.mount()
+    field3.mount()
+    field4.mount()
+
+    arrayField.filterValues((value) => value !== 'three')
+    // validating fields is separate from filterValues and done with a promise,
+    // so make sure they resolve first
+    await vi.runAllTimersAsync()
+
+    expect(arrayField.getMeta().errors).toStrictEqual(['error'])
+
+    // field 0 and 1 weren't shifted, so they shouldn't trigger validation
+    expect(field0.getMeta().errors).toStrictEqual([])
+    expect(field1.getMeta().errors).toStrictEqual([])
+
+    // but the following fields were shifted
+    expect(field2.getMeta().errors).toStrictEqual(['error'])
+    expect(field3.getMeta().errors).toStrictEqual(['error'])
+
+    // field4 no longer exists, so it shouldn't have errors
+    expect(field4.getMeta().errors).toStrictEqual([])
+  })
 })
diff --git a/packages/form-core/tests/FormApi.spec.ts b/packages/form-core/tests/FormApi.spec.ts
