feat(useAsyncValidator): add manual option (#2903)

Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>

packages/integrations/useAsyncValidator/index.test.ts

@@ -1,6 +1,6 @@
 import type { Rules } from 'async-validator'
 import type { Ref } from 'vue-demi'
-import { ref } from 'vue-demi'
+import { nextTick, ref } from 'vue-demi'
 import { useAsyncValidator } from '.'
 
 describe('useAsyncValidator', () => {
@@ -211,5 +211,107 @@ describe('useAsyncValidator', () => {
     `)
 
     form.value.name = 'okxiaoliang4'
+    await nextTick()
+    expect(pass.value).toBe(true)
+    expect(errors.value).toMatchObject([])
+  })
+})
+
+describe('set manual true', () => {
+  let form: {
+    name: string
+    age: number
+  }
+
+  beforeEach(() => {
+    form = {
+      name: 'jelf',
+      age: 24,
+    }
+  })
+
+  it('set immediate and manual at the same time', async () => {
+    const rules: Rules = {
+      name: {
+        type: 'string',
+        min: 5,
+        max: 20,
+        message: 'name length must be 5-20',
+      },
+      age: {
+        type: 'number',
+      },
+    }
+    const { pass, errors, then } = useAsyncValidator(form, rules, { immediate: false, manual: true })
+    expect(pass.value).toBe(true)
+    expect(errors.value).toMatchObject([])
+    then(() => {
+      expect(pass.value).toBe(true)
+      expect(errors.value).toMatchObject([])
+    })
+  })
+
+  it('set manual, do not run validator automatically', async () => {
+    const rules: Rules = {
+      name: {
+        type: 'string',
+        min: 5,
+        max: 20,
+        message: 'name length must be 5-20',
+      },
+      age: {
+        type: 'number',
+      },
+    }
+    const { pass, errors, then } = useAsyncValidator(form, rules, { manual: true })
+    expect(pass.value).toBe(true)
+    expect(errors.value).toMatchObject([])
+    then(() => {
+      expect(pass.value).toBe(true)
+      expect(errors.value).toMatchObject([])
+    })
+  })
+
+  it('manual trigger validator', async () => {
+    const form = ref({
+      name: 'jelf',
+      age: 24,
+    })
+
+    const rules = ref({
+      name: {
+        type: 'string',
+        min: 5,
+        max: 20,
+        message: 'name length must be 5-20',
+      },
+      age: {
+        type: 'number',
+      },
+    }) as Ref<Rules>
+
+    const { execute, pass, errors } = useAsyncValidator(form, rules, { manual: true })
+
+    expect(pass.value).toBe(true)
+    expect(errors.value).toMatchObject([])
+
+    // first trigger
+    await execute()
+    expect(pass.value).toBe(false)
+    expect(errors.value).toMatchInlineSnapshot(`
+      [
+        {
+          "field": "name",
+          "fieldValue": "jelf",
+          "message": "name length must be 5-20",
+        },
+      ]
+    `)
+
+    // second trigger
+    form.value.name = 'okxiaoliang4'
+    await execute()
+    expect(pass.value).toBe(true)
+    expect(errors.value).toMatchObject([])
   })
 })

packages/integrations/useAsyncValidator/index.ts

@@ -34,7 +34,17 @@ export interface UseAsyncValidatorOptions {
    * @see https://github.com/yiminghe/async-validator#options
    */
   validateOption?: ValidateOption
+  /**
+   * The validation will be triggered right away for the first time.
+   * Only works when `manual` is not set to true.
+   *
+   * @default true
+   */
   immediate?: boolean
+  /**
+   * If set to true, the validation will not be triggered automatically.
+   */
+  manual?: boolean
 }
 
 /**
@@ -51,13 +61,14 @@ export function useAsyncValidator(
   const {
     validateOption = {},
     immediate = true,
+    manual = false,
   } = options
 
   const valueRef = resolveRef(value)
 
   const errorInfo = shallowRef<AsyncValidatorError | null>(null)
   const isFinished = ref(true)
-  const pass = ref(!immediate)
+  const pass = ref(!immediate || manual)
   const errors = computed(() => errorInfo.value?.errors || [])
   const errorFields = computed(() => errorInfo.value?.fields || {})
 
@@ -87,11 +98,13 @@ export function useAsyncValidator(
     }
   }
 
-  watch(
-    [valueRef, validator],
-    () => execute(),
-    { immediate, deep: true },
-  )
+  if (!manual) {
+    watch(
+      [valueRef, validator],
+      () => execute(),
+      { immediate, deep: true },
+    )
+  }
 
   const shell = {
     isFinished,