Support for Precognition in <Form> component

packages/core/src/debounce.ts

@@ -1,7 +1,3 @@
-export default function debounce<F extends (...params: any[]) => ReturnType<F>>(fn: F, delay: number): F {
-  let timeoutID: NodeJS.Timeout
-  return function (...args: unknown[]) {
-    clearTimeout(timeoutID)
-    timeoutID = setTimeout(() => fn.apply(this, args), delay)
-  } as F
-}
+import { debounce } from 'lodash-es'
+
+export default debounce

packages/core/src/files.ts

@@ -1,11 +1,49 @@
 import { FormDataConvertible, RequestPayload } from './types'
 
+export function isFile(value: unknown): boolean {
+  return (
+    (typeof File !== 'undefined' && value instanceof File) ||
+    value instanceof Blob ||
+    (typeof FileList !== 'undefined' && value instanceof FileList && value.length > 0)
+  )
+}
+
 export function hasFiles(data: RequestPayload | FormDataConvertible): boolean {
   return (
-    data instanceof File ||
-    data instanceof Blob ||
-    (data instanceof FileList && data.length > 0) ||
+    isFile(data) ||
     (data instanceof FormData && Array.from(data.values()).some((value) => hasFiles(value))) ||
     (typeof data === 'object' && data !== null && Object.values(data).some((value) => hasFiles(value)))
   )
 }
+
+export function forgetFiles(data: Record<string, unknown>): Record<string, unknown> {
+  const newData = { ...data }
+
+  Object.keys(newData).forEach((name) => {
+    const value = newData[name]
+
+    if (value === null) {
+      return
+    }
+
+    if (isFile(value)) {
+      delete newData[name]
+
+      return
+    }
+
+    if (Array.isArray(value)) {
+      newData[name] = Object.values(forgetFiles({ ...value }))
+
+      return
+    }
+
+    if (typeof value === 'object') {
+      newData[name] = forgetFiles(newData[name] as Record<string, unknown>)
+
+      return
+    }
+  })
+
+  return newData
+}

packages/core/src/index.ts

@@ -1,11 +1,13 @@
 import { Router } from './router'
 
 export { getScrollableParent } from './domUtils'
+export { hasFiles } from './files'
 export { objectToFormData } from './formData'
 export { formDataToObject } from './formObject'
 export { default as createHeadManager } from './head'
 export { default as useInfiniteScroll } from './infiniteScroll'
 export { shouldIntercept, shouldNavigate } from './navigationEvents'
+export { default as usePrecognition } from './precognition'
 export { hide as hideProgress, progress, reveal as revealProgress, default as setupProgress } from './progress'
 export { resetFormFields } from './resetFormFields'
 export * from './types'

packages/core/src/precognition.ts

@@ -0,0 +1,151 @@
+import { default as axios, AxiosRequestConfig } from 'axios'
+import { get, isEqual } from 'lodash-es'
+import debounce from './debounce'
+import { forgetFiles, hasFiles } from './files'
+import { objectToFormData } from './formData'
+import { Errors, FormComponentValidateOptions, RequestData, Visit } from './types'
+
+interface UsePrecognitionOptions {
+  timeout: number
+  onStart: () => void
+  onFinish: () => void
+}
+
+type PrecognitionValidateOptions = Pick<Visit<RequestData>, 'method' | 'data' | 'only' | 'errorBag' | 'headers'> &
+  Pick<FormComponentValidateOptions, 'onBefore' | 'onException' | 'onFinish'> & {
+    url: string
+    onPrecognitionSuccess: () => void
+    onValidationError: (errors: Errors) => void
+    simpleValidationErrors?: boolean
+  }
+
+interface PrecognitionValidator {
+  setOldData: (data: RequestData) => void
+  validateFiles: (value: boolean) => void
+  validate: (options: PrecognitionValidateOptions) => void
+  setTimeout: (value: number) => void
+  cancelAll: () => void
+}
+
+export default function usePrecognition(precognitionOptions: UsePrecognitionOptions): PrecognitionValidator {
+  let debounceTimeoutDuration = precognitionOptions.timeout
+  let validateFiles: boolean = false
+
+  let oldData: RequestData = {}
+  let oldTouched: string[] = []
+  const abortControllers: Record<string, AbortController> = {}
+
+  const cancelAll = () => {
+    Object.entries(abortControllers).forEach(([key, controller]) => {
+      controller.abort()
+      delete abortControllers[key]
+    })
+  }
+
+  const setTimeout = (value: number) => {
+    if (value !== debounceTimeoutDuration) {
+      cancelAll()
+      debounceTimeoutDuration = value
+      validateFunction = createValidateFunction()
+    }
+  }
+
+  const createFingerprint = (options: PrecognitionValidateOptions) => `${options.method}:${options.url}`
+
+  const toSimpleValidationErrors = (errors: Errors): Errors => {
+    return Object.keys(errors).reduce(
+      (carry, key) => ({
+        ...carry,
+        [key]: Array.isArray(errors[key]) ? errors[key][0] : errors[key],
+      }),
+      {},
+    )
+  }
+
+  const createValidateFunction = () =>
+    debounce(
+      (options: PrecognitionValidateOptions) => {
+        const changed = options.only.filter((field) => !isEqual(get(options.data, field), get(oldData, field)))
+        const data = validateFiles ? options.data : (forgetFiles(options.data) as RequestData)
+
+        if (options.only.length > 0 && changed.length === 0) {
+          return
+        }
+
+        const beforeValidatonResult = options.onBefore?.(
+          { data: options.data, touched: options.only },
+          { data: oldData, touched: oldTouched },
+        )
+
+        if (beforeValidatonResult === false) {
+          return
+        }
+
+        const fingerprint = createFingerprint(options)
+
+        if (abortControllers[fingerprint]) {
+          abortControllers[fingerprint].abort()
+          delete abortControllers[fingerprint]
+        }
+
+        abortControllers[fingerprint] = new AbortController()
+
+        precognitionOptions.onStart()
+
+        const submitOptions: AxiosRequestConfig = {
+          method: options.method,
+          url: options.url,
+          data: hasFiles(data) ? objectToFormData(data) : { ...data },
+          signal: abortControllers[fingerprint].signal,
+          headers: {
+            ...(options.headers || {}),
+            'X-Requested-With': 'XMLHttpRequest',
+            Precognition: true,
+            ...(options.only.length ? { 'Precognition-Validate-Only': options.only.join(',') } : {}),
+          },
+        }
+
+        axios(submitOptions)
+          .then((response) => {
+            if (response.status === 204 && response.headers['precognition-success'] === 'true') {
+              options.onPrecognitionSuccess()
+            }
+          })
+          .catch((error) => {
+            if (error.response?.status === 422) {
+              const errors = error.response.data?.errors || {}
+              const scopedErrors = (options.errorBag ? errors[options.errorBag] || {} : errors) as Errors
+              const formattedErrors =
+                options.simpleValidationErrors === false ? scopedErrors : toSimpleValidationErrors(scopedErrors)
+              return options.onValidationError(formattedErrors)
+            }
+
+            if (options.onException) {
+              options.onException(error)
+              return
+            }
+
+            throw error
+          })
+          .finally(() => {
+            oldData = { ...data }
+            oldTouched = [...options.only]
+            delete abortControllers[fingerprint]
+            options.onFinish?.()
+            precognitionOptions.onFinish()
+          })
+      },
+      debounceTimeoutDuration,
+      { leading: true, trailing: true },
+    )
+
+  let validateFunction = createValidateFunction()
+
+  return {
+    setOldData: (data) => (oldData = { ...data }),
+    validateFiles: (value) => (validateFiles = value),
+    setTimeout,
+    validate: (options) => validateFunction(options),
+    cancelAll,
+  }
+}

packages/core/src/types.ts

@@ -99,7 +99,8 @@ export type FormDataError<T> = Partial<Record<FormDataKeys<T>, ErrorValue>>
 
 export type Method = 'get' | 'post' | 'put' | 'patch' | 'delete'
 
-export type RequestPayload = Record<string, FormDataConvertible> | FormData
+export type RequestData = Record<string, FormDataConvertible>
+export type RequestPayload = RequestData | FormData
 
 export interface PageProps {
   [key: string]: unknown
@@ -476,6 +477,23 @@ export type FormComponentProps = Partial<
   resetOnSuccess?: boolean | string[]
   resetOnError?: boolean | string[]
   setDefaultsOnSuccess?: boolean
+  validateFiles?: boolean
+  validateTimeout?: number
+  simpleValidationErrors?: boolean
+}
+
+type RevalidatePayload = {
+  data: RequestData
+  touched: string[]
+}
+
+export type FormComponentValidateOptions = {
+  only?: string | string[]
+  onBefore?: (newRequest: RevalidatePayload, oldRequest: RevalidatePayload) => boolean | undefined
+  onSuccess?: () => void
+  onError?: (errors: Errors) => void
+  onFinish?: () => void
+  onException?: (error: Error) => void
 }
 
 export type FormComponentMethods = {
@@ -486,6 +504,15 @@ export type FormComponentMethods = {
   reset: (...fields: string[]) => void
   submit: () => void
   defaults: () => void
+  valid: (field: string) => boolean
+  invalid: (field: string) => boolean
+  validate: (
+    only?: string | string[] | FormComponentValidateOptions,
+    maybeOptions?: FormComponentValidateOptions,
+  ) => void
+  touch: (field: string | string[]) => void
+  touched(field?: string): boolean
+  cancelValidation: () => void
 }
 
 export type FormComponentonSubmitCompleteArguments = Pick<FormComponentMethods, 'reset' | 'defaults'>
@@ -498,6 +525,7 @@ export type FormComponentState = {
   wasSuccessful: boolean
   recentlySuccessful: boolean
   isDirty: boolean
+  validating: boolean
 }
 
 export type FormComponentSlotProps = FormComponentMethods & FormComponentState