Form persistence

packages/form-core/src/FieldApi.ts

@@ -482,7 +482,6 @@ export class FieldApi<
 
   validateSync = (value = this.state.value, cause: ValidationCause) => {
     const validates = getSyncValidatorArray(cause, this.options)
-
     // Needs type cast as eslint errantly believes this is always falsy
     let hasErrored = false as boolean
 

packages/form-core/src/FormApi.ts

@@ -8,7 +8,7 @@ import {
   isNonEmptyArray,
   setBy,
 } from './utils'
-import type { Updater } from './utils'
+import type { MaybePromise, Updater } from './utils'
 import type { DeepKeys, DeepValue } from './util-types'
 import type { FieldApi, FieldMeta } from './FieldApi'
 import type {
@@ -95,6 +95,14 @@ export interface FormOptions<
     formApi: FormApi<TFormData, TFormValidator>
   }) => void
   transform?: FormTransform<TFormData, TFormValidator>
+  // checkout @tanstack/form-persistence-core
+  persister?: Persister<TFormData>
+}
+
+export type Persister<TFormData> = {
+  persistForm(formState: FormState<TFormData>): MaybePromise<void>
+  restoreForm(): MaybePromise<FormState<TFormData> | undefined>
+  deleteForm(): MaybePromise<void>
 }
 
 export type ValidationMeta = {
@@ -136,6 +144,9 @@ export type FormState<TFormData> = {
   isValid: boolean
   canSubmit: boolean
   submissionAttempts: number
+  // Form Persistence
+  isRestored: boolean
+  isRestoring: boolean
 }
 
 function getDefaultFormState<TFormData>(
@@ -166,6 +177,8 @@ function getDefaultFormState<TFormData>(
       onMount: undefined,
       onServer: undefined,
     },
+    isRestored: false,
+    isRestoring: false,
   }
 }
 
@@ -183,6 +196,7 @@ export class FormApi<
     {} as any
 
   prevTransformArray: unknown[] = []
+  restorePromise: Promise<void> = Promise.resolve()
 
   constructor(opts?: FormOptions<TFormData, TFormValidator>) {
     this.store = new Store<FormState<TFormData>>(
@@ -195,10 +209,9 @@ export class FormApi<
         onUpdate: () => {
           let { state } = this.store
           // Computed state
-          const fieldMetaValues = Object.values(state.fieldMeta) as (
-            | FieldMeta
-            | undefined
-          )[]
+          const fieldMetaValues = Object.values<FieldMeta | undefined>(
+            state.fieldMeta,
+          )
 
           const isFieldsValidating = fieldMetaValues.some(
             (field) => field?.isValidating,
@@ -252,13 +265,44 @@ export class FormApi<
             this.store.state = this.state
             this.prevTransformArray = transformArray
           }
+
+          if (opts?.persister && !this.state.isRestoring) {
+            opts.persister.persistForm(this.state)
+          }
         },
       },
     )
 
     this.state = this.store.state
+    this.update(opts)
+  }
 
-    this.update(opts || {})
+  restore = async (opts?: FormOptions<TFormData, TFormValidator>) => {
+    if (!opts?.persister) return
+    let restorePromiseResolve: () => void
+    this.restorePromise = new Promise<void>(
+      (res) => (restorePromiseResolve = res),
+    )
+    this.store.setState((oldState) => ({
+      ...oldState,
+      isRestored: false,
+      isRestoring: true,
+    }))
+    const restoredState = await opts.persister.restoreForm()
+    if (!restoredState) {
+      return this.store.setState((oldState) => ({
+        ...oldState,
+        isRestored: true,
+        isRestoring: false,
+      }))
+    }
+    this.state = restoredState
+    this.store.batch(() =>
+      this.store.setState(() => {
+        restorePromiseResolve()
+        return restoredState
+      }),
+    )
   }
 
   runValidator<
@@ -306,15 +350,19 @@ export class FormApi<
     // Options need to be updated first so that when the store is updated, the state is correct for the derived state
     this.options = options
 
+    this.restore(options)
+
     this.store.batch(() => {
       const shouldUpdateValues =
         options.defaultValues &&
         options.defaultValues !== oldOptions.defaultValues &&
-        !this.state.isTouched
+        !this.state.isTouched &&
+        !this.state.isRestoring
 
       const shouldUpdateState =
         options.defaultState !== oldOptions.defaultState &&
-        !this.state.isTouched
+        !this.state.isTouched &&
+        !this.state.isRestoring
 
       this.store.setState(() =>
         getDefaultFormState(
@@ -335,32 +383,35 @@ export class FormApi<
     })
   }
 
-  reset = () =>
+  reset = () => {
+    this.options.persister?.deleteForm()
     this.store.setState(() =>
       getDefaultFormState({
         ...(this.options.defaultState as any),
         values: this.options.defaultValues ?? this.options.defaultState?.values,
       }),
     )
+  }
 
   validateAllFields = async (cause: ValidationCause) => {
-    const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
+    const fieldValidationPromises: Promise<ValidationError[]>[] = []
     this.store.batch(() => {
-      void (
-        Object.values(this.fieldInfo) as FieldInfo<any, TFormValidator>[]
-      ).forEach((field) => {
-        if (!field.instance) return
-        const fieldInstance = field.instance
+      const fieldInfoValues = Object.values<FieldInfo<any, TFormValidator>>(
+        this.fieldInfo,
+      )
+      for (const field of fieldInfoValues) {
+        if (!field.instance) continue
+        const instance = field.instance
         // Validate the field
         fieldValidationPromises.push(
-          Promise.resolve().then(() => fieldInstance.validate(cause)),
+          Promise.resolve().then(() => instance.validate(cause)),
         )
         // If any fields are not touched
-        if (!field.instance.state.meta.isTouched) {
+        if (!instance.state.meta.isTouched) {
           // Mark them as touched
-          field.instance.setMeta((prev) => ({ ...prev, isTouched: true }))
+          instance.setMeta((prev) => ({ ...prev, isTouched: true }))
         }
-      })
+      }
     })
 
     const fieldErrorMapMap = await Promise.all(fieldValidationPromises)
@@ -492,10 +543,7 @@ export class FormApi<
       )
     }
 
-    let results: ValidationError[] = []
-    if (promises.length) {
-      results = await Promise.all(promises)
-    }
+    const results = promises.length > 0 ? await Promise.all(promises) : []
 
     this.store.setState((prev) => ({
       ...prev,

packages/form-core/src/tests/FieldApi.spec.ts

@@ -635,11 +635,14 @@ describe('field api', () => {
         onSubmit: ({ value }) =>
           value.length > 0 ? undefined : 'first name is required',
       },
+      defaultMeta: { isTouched: true },
     })
 
+    form.mount()
     field.mount()
 
     await form.handleSubmit()
+
     expect(field.getMeta().errors).toStrictEqual(['first name is required'])
   })
 

packages/form-core/src/tests/FormApi.spec.ts

@@ -12,24 +12,27 @@ describe('form api', () => {
       values: {},
       fieldMeta: {},
       canSubmit: true,
-      isFieldsValid: true,
+      isFieldsValid: false,
       isFieldsValidating: false,
       isFormValid: true,
       isFormValidating: false,
       isSubmitted: false,
       errors: [],
       errorMap: {},
+      isRestored: false,
+      isRestoring: false,
       isSubmitting: false,
       isTouched: false,
       isPristine: true,
       isDirty: false,
-      isValid: true,
+      isValid: false,
       isValidating: false,
       submissionAttempts: 0,
       validationMetaMap: {
         onChange: undefined,
         onBlur: undefined,
         onSubmit: undefined,
+        onServer: undefined,
         onMount: undefined,
       },
     })
@@ -61,6 +64,8 @@ describe('form api', () => {
       isDirty: false,
       isValid: true,
       isValidating: false,
+      isRestored: false,
+      isRestoring: false,
       submissionAttempts: 0,
       validationMetaMap: {
         onChange: undefined,
@@ -87,6 +92,8 @@ describe('form api', () => {
       isFieldsValid: true,
       isFieldsValidating: false,
       isFormValid: true,
+      isRestored: false,
+      isRestoring: false,
       isFormValidating: false,
       isSubmitted: false,
       isSubmitting: false,
@@ -101,6 +108,7 @@ describe('form api', () => {
         onBlur: undefined,
         onSubmit: undefined,
         onMount: undefined,
+        onServer: undefined,
       },
     })
   })
@@ -139,6 +147,8 @@ describe('form api', () => {
       isPristine: true,
       isDirty: false,
       isValid: true,
+      isRestored: false,
+      isRestoring: false,
       isValidating: false,
       submissionAttempts: 300,
       validationMetaMap: {
@@ -182,10 +192,13 @@ describe('form api', () => {
       isDirty: false,
       isValid: true,
       isValidating: false,
+      isRestored: false,
+      isRestoring: false,
       submissionAttempts: 0,
       validationMetaMap: {
         onChange: undefined,
         onBlur: undefined,
+        onServer: undefined,
         onSubmit: undefined,
         onMount: undefined,
       },
@@ -834,6 +847,7 @@ describe('form api', () => {
         onChange: ({ value }) =>
           value.length > 0 ? undefined : 'first name is required',
       },
+      defaultMeta: { isTouched: true },
     })
 
     const lastNameField = new FieldApi({
@@ -843,8 +857,10 @@ describe('form api', () => {
         onChange: ({ value }) =>
           value.length > 0 ? undefined : 'last name is required',
       },
+      defaultMeta: { isTouched: true },
     })
 
+    form.mount()
     field.mount()
     lastNameField.mount()
 
@@ -878,8 +894,10 @@ describe('form api', () => {
             ? undefined
             : 'first name must be longer than 3 characters',
       },
+      defaultMeta: { isTouched: true },
     })
 
+    form.mount()
     field.mount()
 
     await form.handleSubmit()
@@ -905,8 +923,9 @@ describe('form api', () => {
         onSubmit: ({ value }) =>
           value.length > 0 ? undefined : 'first name is required',
       },
+      defaultMeta: { isTouched: true },
     })
-
+    form.mount()
     field.mount()
 
     await form.handleSubmit()
@@ -938,6 +957,7 @@ describe('form api', () => {
         onChange: ({ value }) =>
           value.length > 0 ? undefined : 'first name is required',
       },
+      defaultMeta: { isTouched: true },
     })
 
     field.mount()

packages/form-core/src/utils.ts

@@ -2,6 +2,8 @@ import type { ValidationCause } from './types'
 import type { FormValidators } from './FormApi'
 import type { FieldValidators } from './FieldApi'
 
+export type MaybePromise<T> = T | Promise<T>
+
 export type UpdaterFn<TInput, TOutput = TInput> = (input: TInput) => TOutput
 
 export type Updater<TInput, TOutput = TInput> =

packages/form-persist-core/.eslintrc.cjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: './tsconfig.eslint.json',
+  },
+}
+
+module.exports = config