Merge pull request #2 from jbaubree/feat/add-deep-strategy

feat: add deep strategy for error format

Author: jbaubree

README.md

@@ -73,7 +73,9 @@ const {
   errorCount,
   clearErrors,
   getErrorMessage,
+  errorPaths,
   focusFirstErroredInput,
+  cleanup,
 } = useFormValidation(schema, form)
 
 // Submit your form
@@ -95,6 +97,7 @@ const options = {
     // Custom validation logic
     return {} // Return errors if any
   },
+  errorStrategy: 'flatten' // or 'deep'
 }
 
 const { validate } = useFormValidation(schema, form, options)
@@ -104,9 +107,11 @@ const { validate } = useFormValidation(schema, form, options)
 
 - validate(): Triggers the validation process.
 - clearErrors(): Resets the validation errors.
-- getErrorMessage(path: keyof F): Retrieves the error message for a specific field.
+- getErrorMessage(path: keyof F | string): Retrieves the error message for a specific field. Supports nested paths like "user.name".
+- errorPaths: Computed property that returns an array of all error paths, including nested ones (e.g., ["email", "user.name"]).
 - focusFirstErroredInput(): Focuses the first input with an error.
-- focusInput(inputName: keyof F): Focuses a specific input by its name.
+- focusInput(inputName: keyof F | string): Focuses a specific input by its name. Supports nested paths like "user.name".
+- cleanup(): Manually cleans up watchers, event listeners, and caches. Automatically called on component unmount when used inside a component context.
 
 ## API Reference
 
@@ -117,6 +122,7 @@ declare function useFormValidation<S extends InputSchema<F>, F extends Form>(
   options?: {
     mode?: 'eager' | 'lazy' | 'agressive' | 'onBlur' // lazy by default
     transformFn?: GetErrorsFn<S, F>
+    errorStrategy?: 'flatten' | 'deep'
   }
 ): ReturnType<F>
 ```
@@ -128,6 +134,7 @@ declare function useFormValidation<S extends InputSchema<F>, F extends Form>(
 - **options**: Optional configuration object.
   - **mode**: (optional) Validation mode (`'eager'` for immediate validation,`'agressive'` for validation on load, `'lazy'` for validation on form changes or `'onBlur'` for validation on input blur).
   - **transformFn**: (optional) A transformation function that can be used when integrating a different validation library. It allows you to transform data before it is validated. Use this option only if you are integrating another validation library that requires specific data handling.
+  - **errorStrategy**: (optional) Error format mode (`'flatten'` user.name has an error, `'deep'` for { user: { name: 'name has an error' } }).
 
 #### Return Value
 
@@ -139,9 +146,67 @@ Returns an object containing the following properties:
 - `isLoading`: Reactive reference indicating if the form validation is in progress.
 - `errorCount`: Reactive reference to the number of errors.
 - `clearErrors`: Function to clear validation errors.
-- `getErrorMessage`: Function to get the error message for a specific field.
+- `getErrorMessage`: Function to get the error message for a specific field. Supports nested paths like "user.name".
+- `errorPaths`: Computed property that returns an array of all error paths, including nested ones (e.g., ["email", "user.name"]).
 - `focusFirstErroredInput`: Function to focus the first input with an error.
-- `focusInput`: Function to focus a specific input.
+- `focusInput`: Function to focus a specific input. Supports nested paths like "user.name".
+- `cleanup`: Function to manually clean up watchers, event listeners, and caches. This is automatically called when the component unmounts if used within a component context, but can be called manually when needed (e.g., when using the composable outside of a component or for manual cleanup).
+
+## Deep Strategy Example
+
+When using the `errorStrategy: 'deep'` option, you can work with nested form structures and automatically get all error paths:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useFormValidation } from 'vue-use-form-validation'
+import * as z from 'zod'
+
+const schema = z.object({
+  user: z.object({
+    name: z.string().min(1, 'Name is required'),
+  }),
+  email: z.string().email('Invalid email'),
+})
+
+const form = ref({
+  user: { name: '' },
+  email: '',
+})
+
+const {
+  validate,
+  hasError,
+  errorPaths,
+  getErrorMessage,
+  focusInput,
+} = useFormValidation(schema, form, { errorStrategy: 'deep' })
+
+async function onSubmit() {
+  await validate()
+  if (!isValid.value) {
+    // errorPaths.value will contain ["user.name", "email"] when there are errors
+    console.log('Error paths:', errorPaths.value)
+  }
+}
+</script>
+
+<template>
+  <form @submit.prevent="onSubmit">
+    <input v-model="form.user.name" name="user.name" placeholder="Name">
+    <input v-model="form.email" name="email" placeholder="Email">
+
+    <!-- Display all errors with automatic deep path handling -->
+    <div v-if="hasError">
+      <div v-for="errorPath in errorPaths" :key="errorPath">
+        <button @click="focusInput({ inputName: errorPath })">
+          {{ getErrorMessage(errorPath) }}
+        </button>
+      </div>
+    </div>
+  </form>
+</template>
+```
 
 ## Example
 

playground/src/App.vue

@@ -7,26 +7,34 @@ import * as z from 'zod'
 const toast = useToast()
 
 const schema = z.object({
+  user: z.object({
+    name: z.string().min(1),
+  }),
   email: z.string().email(),
   password: z.string().min(8),
 })
 
 const form = ref({
+  user: {
+    name: '',
+  },
   email: '',
   password: '',
 })
 
 const {
-  errors,
   errorCount,
   hasError,
   isLoading,
   isValid,
   focusFirstErroredInput,
   focusInput,
   getErrorMessage,
+  errorPaths,
   validate,
-} = useFormValidation(schema, form)
+  clearErrors,
+  cleanup,
+} = useFormValidation(schema, form, { errorStrategy: 'deep' })
 
 async function onSubmit() {
   await validate()
@@ -42,28 +50,31 @@ async function onSubmit() {
   <UContainer class="py-5">
     <UText as="h1" label="Form example" class="mb-5" :ui="{ font: 'font-bold', size: 'text-2xl' }" />
     <form class="flex flex-col gap-3 mb-5">
+      <UFormGroup label="User Name" :error="getErrorMessage('user.name')" is-required>
+        <UInput v-model="form.user.name" name="user.name" type="text" placeholder="Enter your name" autofocus size="md" />
+      </UFormGroup>
       <UFormGroup label="Email" :error="getErrorMessage('email')" is-required>
-        <UInput v-model="form.email" name="email" type="email" placeholder="[email protected]" autofocus size="md" />
+        <UInput v-model="form.email" name="email" type="email" placeholder="[email protected]" size="md" />
       </UFormGroup>
       <UFormGroup label="Password" :error="getErrorMessage('password')" is-required>
         <UInput v-model="form.password" name="password" type="password" placeholder="**********" size="md" />
       </UFormGroup>
       <UButton label="Submit" color="pilot" is-block :is-loading="isLoading" @click="onSubmit" />
+      <UButton label="Clear errors" color="orange" is-block @click="clearErrors()" />
+      <UButton label="Cleanup form validation" color="red" is-block @click="cleanup()" />
     </form>
     <UCard v-if="hasError" :ui="{ background: 'bg-red-200 dark:bg-red-600', body: { base: 'flex flex-col items-start gap-2' } }">
       <UText :label="`Form has ${errorCount} ${errorCount > 1 ? 'errors' : 'error'}:`" :ui="{ font: 'font-bold', size: 'text-lg' }" class="mb-1" />
       <div
-        v-for="
-          error, i in Object.keys(errors) as Array<keyof typeof errors>
-        "
+        v-for="errorPath, i in errorPaths"
         :key="i"
         class="flex items-center"
       >
         <UIcon name="icon-ph-dot-bold" color="dark" />
         <UButton
           class="ml-3" color="dark" :is-padded="false" variant="link"
-          :label="getErrorMessage(error)"
-          @click="focusInput({ inputName: error })"
+          :label="getErrorMessage(errorPath)"
+          @click="focusInput({ inputName: errorPath })"
         />
       </div>
     </UCard>

src/errors.ts

@@ -1,20 +1,21 @@
 import type { MaybeRefOrGetter } from 'vue'
-import type { FieldErrors, Form, GetErrorsFn, InputSchema } from './types'
+import type { ErrorStrategy, FieldErrors, Form, GetErrorsFn, InputSchema } from './types'
 import { toValue } from 'vue'
 import { validators } from './validators'
 
 export async function getErrors<S extends InputSchema<F>, F extends Form>(
   schema: S,
   form: MaybeRefOrGetter<F>,
   transformFn: GetErrorsFn<S, F> | null,
+  errorStrategy: ErrorStrategy,
 ): Promise<FieldErrors<F>> {
   const formValue = toValue(form)
   const schemaValue = toValue(schema)
   if (transformFn)
-    return await transformFn(schemaValue, formValue)
+    return await transformFn(schemaValue, formValue, errorStrategy)
   for (const validator of Object.values(validators)) {
     if (validator.check(schemaValue)) {
-      return await validator.getErrors(schemaValue, formValue)
+      return await validator.getErrors(schemaValue, formValue, errorStrategy)
     }
   }
   return {}

src/types.ts

@@ -19,9 +19,24 @@ interface SuperstructSchema<F> extends AnyObject {
 export type Validator = 'Joi' | 'SuperStruct' | 'Valibot' | 'Yup' | 'Zod'
 export type ValidationMode = 'eager' | 'lazy' | 'agressive' | 'onBlur'
 export type Awaitable<T> = T | PromiseLike<T>
-export type FieldErrors<F> = Partial<Record<keyof F, string>>
+export type ErrorStrategy = 'flatten' | 'deep'
+
+type DeepErrors<T> = {
+  [K in keyof T]?: T[K] extends Record<string, any>
+    ? DeepErrors<T[K]>
+    : string
+}
+export type FieldErrors<F, Strategy extends ErrorStrategy = ErrorStrategy> =
+  Strategy extends 'flatten'
+    ? Partial<Record<keyof F, string>>
+    : {
+        [K in keyof F]?: F[K] extends Record<string, any>
+          ? DeepErrors<F[K]>
+          : string
+      }
+
 export type Form = Record<string, unknown>
-export type GetErrorsFn<S, F extends Form> = (schema: S, form: F) => Awaitable<FieldErrors<F>>
+export type GetErrorsFn<S, F extends Form> = (schema: S, form: F, errorStrategy: ErrorStrategy) => Awaitable<FieldErrors<F>>
 
 export type InputSchema<F extends Form> =
   | ZodSchema<F>
@@ -30,15 +45,17 @@ export type InputSchema<F extends Form> =
   | Schema<F>
   | SuperstructSchema<F>
 
-export interface ReturnType<F> {
-  validate: () => Promise<FieldErrors<F>>
-  errors: Ref<FieldErrors<F>>
+export interface ReturnType<F, Strategy extends ErrorStrategy = ErrorStrategy> {
+  validate: () => Promise<FieldErrors<F, Strategy>>
+  errors: Ref<FieldErrors<F, Strategy>>
   errorCount: ComputedRef<number>
   isLoading: Ref<boolean>
   isValid: ComputedRef<boolean>
   hasError: ComputedRef<boolean>
   clearErrors: () => void
-  getErrorMessage: (path: keyof F) => string | undefined
+  getErrorMessage: (path: keyof F | string) => string | undefined
+  errorPaths: ComputedRef<string[]>
   focusFirstErroredInput: () => void
-  focusInput: (options: { inputName: keyof F }) => void
+  focusInput: (options: { inputName: keyof F | string }) => void
+  cleanup: () => void
 }