form.update() silently wipes onSubmit and other options - need way to update defaultValues safely

[derekbking]

I'd like to share my use case of having a component that automatically saves via a debounce mechanism.

Use Case: Auto-Save Form

I have a form that auto-saves when the user stops typing for 2 seconds. After a successful save, I need to update defaultValues so that:

• isDefaultValue becomes true (my button shows "Saved")
• I can detect if the form is dirty (user made new changes)

function FormSaver({ form, mutation }) {
  const debounced = useDebouncedCallback(() => {
    form.handleSubmit()
  }, 2000)

  const { values, isDefaultValue } = useStore(form.store)

  useEffect(() => {
    if (!isDefaultValue) {
      debounced()
    }
  }, [values, isDefaultValue])

  return <Button disabled={isDefaultValue}>{isDefaultValue ? "Saved" : "Save pending"}</Button>
}

The Problem: Race Condition Window

There's an important window where the mutation is pending and users can still modify fields:

Timeline:
─────────────────────────────────────────────────────────────────────────────►

User edits     Debounce       Mutation         User edits      onSuccess
field A        fires          in flight        field B         returns
   │              │               │                │               │
   ▼              ▼               ▼                ▼               ▼
┌──────┐      ┌──────┐      ┌──────────────────────────┐      ┌──────┐
│ A=1  │ ──►  │submit│ ──►  │   Saving A=1...          │ ──►  │ ???  │
└──────┘      └──────┘      └──────────────────────────┘      └──────┘
                                       │
                                       │  User changes B=2
                                       │  during this window
                                       ▼
                            ┌──────────────────┐
                            │ Form now has:    │
                            │   A=1, B=2       │
                            │                  │
                            │ Server saved:    │
                            │   A=1 (no B)     │
                            └──────────────────┘

If onSuccess calls reset(savedData):
  - Form values become A=1 (from server)
  - User's B=2 edit is lost

What I want:
  - defaultValues update to A=1 (what was saved)
  - Form values stay A=1, B=2 (preserve user's edits)
  - isDefaultValue becomes false (form is dirty)
  - Debounce fires again to save B=2

If you call reset() in onSuccess, the user's changes to field B get wiped. I want to call reset so my button can show "Saved" and detect whether the form is dirty. If the user makes changes during this window, the debounce should fire again to save those changes.

Ideally I want to load server data when the form is initialized and then keep the state client-only. I know there are discussions about how the client should not own state, but this feels like the simplest way to implement auto-saving. I don't have many users accessing this form simultaneously, so conflicts aren't a concern.

What I Want

I want to call reset with a preserveValues option to keep the current values but update defaultValues:

// Proposed API
mutation.onSuccess((savedData) => {
  form.reset(savedData, { preserveValues: true })
  // defaultValues = savedData
  // form values = unchanged (user's edits preserved)
  // isDefaultValue = recalculated (true if values match new defaults, false otherwise)
})

What I Was Doing (Broken)

Previously I was using form.update() with defaultValues:

mutation.onSuccess((savedData) => {
  form.update({
    defaultValues: savedData
  })
})

This silently broke my form. The first save worked, but all subsequent saves failed because update() replaces the entire options object:

// Inside FormApi.js
this.update = (options) => {
  this.options = options  // Replaces everything!
}

// After my update() call:
// form.options.onSubmit === undefined ❌
// form.options.validators === undefined ❌

What I Should Do (Workaround)

The workaround is to spread the existing options:

mutation.onSuccess((savedData) => {
  form.update({
    ...form.options,  // Preserve onSubmit and other options
    defaultValues: savedData
  })
})

This works but took a bit to debug. The failure is completely silent handleSubmit gets called, passes all validation, then does nothing because onSubmit is undefined.

Suggestions

1. update() should merge options instead of replacing. I completely recognize that merging could be just as confusing this was just the assumption I made about it.

// Current (surprising behavior):
this.options = options

// Suggested (safer default):
this.options = { ...this.options, ...options }

2. Add preserveValues option to reset()

form.reset(savedData, { preserveValues: true })

This would update defaultValues and recalculate isDefaultValue without touching the current form values.

---

Maybe the update() behavior is expected, but I wanted to share how I misunderstood the API. I spent a long time debugging why my second save silently failed. I'm wondering if the behavior should be different, or at minimum documented more clearly.

Thanks for the great library!