[RFC] form-core: Handling Array Methods Called on `null` or `undefined`

[LeCarbonator]

RFC (form-core): Handling Array Methods Called on null or undefined

Background

TanStack Form provides several helper methods for working with array fields.
In version form-core@1.24.4, these include:

• moveFieldValues
• pushFieldValue
• swapFieldValues
• clearFieldValues
• insertFieldValue
• removeFieldValue
• replaceFieldValue

Currently, these methods can only be used if the field type explicitly extends unknown[]. However, there have been requests (#1588 ) to support optional arrays.

The Problem

TypeScript allows us to express such optional arrays easily, but at runtime the behavior is inconsistent.
Consider this example:

const form = useForm({
  defaultValues: {
    people: null as null | string[]
  }
})

form.pushFieldValue('people', 'New person')

In the current version:

• Some methods error,
• Some methods don't do anything,
• Some methods silently create a new array

There are no runtime checks ensuring consistent behavior when array methods are called on null or undefined

Goal

We want consistent, predictable behavior across all array helper methods when the field value is null or undefined.

This RFC plans to define that behaviour and make it guarantee the runtime behaviour.
Once a decision is made, all array methods (swapFieldValues, removeFieldValue etc.) will follow this rule and be tested for it.

Your Feedback

If you currently use arrays in your forms, please share your expectations for how the following code should behave:

form.pushFieldValue('people', 'New person')

Here are some of our proposed options. If you have other suggestions or proposals, feel free to share!

1. Throw an error: The operation should explicitly fail if it encountered null or undefined.
2. Create an empty array: The operation should first initialize an array, and then apply the changes if possible.
   • pushFieldValue('people', 'New Person') transforms null -> ['New Person']
   • swapFieldValues('people', 1, 2) transforms null -> []
3. Do nothing: The operation should not apply any changes if the field is not an array.

Frequently Asked Questions

Will this be a breaking change?

Possibly. The current type definitions don't allow you to call these methods on optional arrays. If a field called the array method, it was an inconsistent mix of doing nothing, throwing an error or creating an array.
With the plans to provide optional array support, we want to enforce consistent behaviour.

[alexisdorosz]

We use GO for our backend and usually use backend response as our default values for forms.
Since GO slices are pointers with a zero value of nil, we treat all our arrays as nullable() for safety.

It is also quite common in UI library to have null represent the default value for Select or Combobox, some of which have a "multiple" mode allowing to pick multiple choices.

For users of such components, I assume it would be convenient for an array field to start as null or undefined.

We believe Option 2. Create an empty array upon using an array method would be the most convenient behaviour for these scenarios. 😊