Add extendValidator prop or extending validator parameters

[btea]

• Start Date: (2025-01-19)
• Target Major Version: (3.x)
• Reference Issues: (fill in existing related issues, if any)
• Implementation PR: (leave this empty)

Summary

Expand the warning information of validator verification to provide clearer error prompts.

Basic example

<script setup>
defineProps({
  num: {
    type: Number,
    extendValidator(name, value, props, warn) {
	  if (typeof value !== 'number') {
		warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected type number, but got ${typeof value}`)
	  } else (!Number.isInteger(value)) {
		warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected an integer.`)
	  }
    }
  }
})
</script>

Motivation

In custom components, we usually validate many props for a better user experience. Currently, the validator function will only return true or false. If it is false, it means that the validation has failed and a warning message will be thrown inside vue.

However, the warning message only indicates that a prop check failed, but users cannot customize and expand more specific error descriptions.

Detailed design

In order not to affect the original users, it may be a good idea to add a new function to give users more customization space.

refer #Basic example

Drawbacks

In most cases, the current validator function will suffice. (This proposal is merely to optimize the development experience based on the original one.)

Alternatives

Add new parameters based on the original validator and make different processing according to different parameters.

Adoption strategy

Unresolved questions

N/A

[jacekkarczmarczyk]

Can't you just add console.warn in normal validator?

[btea]

In the current implementation second argument of validator is props object, calling an object would throw an exception

Yes, I know, so I changed the warn in your example to the third parameter, passed the warn function inside vue in, and called it directly. The result is shown in the figure above.

- if (validator && !validator(value, props))
+ if (validator && !validator(value, props, warn))

https://github.com/vuejs/core/blob/82da43d167462bc36c5e94e4a99dca12ea15d08b/packages/runtime-core/src/componentProps.ts#L708

[jacekkarczmarczyk]

But the warn function you're passing doesn't suppress the original warning as I suggested in my comment with examples

[btea]

So what you mean is actually to modify the internal logic of warn, and then decide whether to print warning information inside vue based on the parameters you pass in. Right?

[jacekkarczmarczyk]

No, you can create a new function that calls the original warn with custom message and optionally surpresses the original validator warning and pass this function instead of original warn

[btea]

I seem to understand what you mean. However, I think it is better to add a new method according to my current implementation, without changing the original logic, and basically will not cause any impact on the original users. vuejs/core#12738

[pikax]

I personally don't use validators nor ever use them extensible, I mostly rely on Typescript to statically check things.

IMO this can be done in a watch without changing the API and purely on the userland.

eg:

export function doValidation<T extends Record<string, any>, N extends keyof T>(props: T, name: N, validator: (name: N, value: T[N], props: T) => void) {
  watch(() => props[name], (v) => {
    validator(name, v, props)
  }, {
    immediate: true,
    flush: 'sync'
  })
}

export function extendedNumberValidator<T extends Record<string, any>, N extends keyof T & string, V extends T[N]>(name: N, value: V, props: T) {
  if (typeof value !== 'number') {
    warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected type number, but got ${typeof value}`);
  } else if (!Number.isInteger(value)) {
    warn(`[Custom Component]: Invalid prop: custom validator check failed for prop "${name}", expected an integer.`)
  }
}

const props = defineProps({
 num: Number 
})
doValidation(props, 'num', extendedNumberValidator)

Playground

[btea]

Why don't you warn and then return true in the validator()? That way the default message is suppressed, since you're already warning the user?

I think it is counterintuitive to output a warning message and then return true, which is not in line with the validator's original design. (Returning false means the validation failed, and returning true means the validation succeeded.)

if that can be added in the UserLand or even with the correct behaviour, I personally don't see the need for this specific behaviour.

Personally, I still hope to put the verification logic in the validator function as much as possible.

[pikax]

I think it is counterintuitive to output a warning message and then return true, which is not in line with the validator's original design. (Returning false means the validation failed, and returning true means the validation succeeded.)

Yes it is counterintuitive, but is also by design if the validation fails we log the warning message, but you don't want to log the default message which is also counterintuitive, based that the validation return only logs the warning, IMO is fair to return true if you're already logging the warning.

Personally, I still hope to put the verification logic in the validator function as much as possible.

You can still do it, you just get 2 warn messages instead of 1 warn message.

IMO adding an extra function extendValidator is also counterintuitive and changing the validator to only warn if the result is false is a breaking change.

[jacekkarczmarczyk]

IMHO 2 messages is not a bad thing. If want only 1 custom message it be simple ("Something must be greater than 5") or you can mimic Vue's message ("[Custom Component]: Invalid prop: custom validator check...."). First one may won't include the information that Vue gives you and it will suffer inconsistency by looking differently than messages from other non-custom validation, second one might be too tedious to repeat every time. By having 2 messages you can keep the original information coming from Vue and add a short custom message.

[btea]

OK, I got your point: do not modify the existing logic, nor add a new API, but import warn, when the verification condition is false, output the custom warning message and the warning message inside vue at the same time.

Let's see what other people think.

[Justineo]

1. I believe we shouldn’t change the return type of validator, as truthy values indicate success.
2. If we want to introduce new behavior, it should be done through a new API, perhaps for breaking changes in the next major version. However, I’m not suggesting we add one right now.
3. While I also prefer TS-flavored defineProps, the runtime validators do something types cannot check.
4. I’ve always hoped Vue would provide the ability to include custom error messages together with the error messages for built-in runtime checks. Two messages aren’t unacceptable, but better integration would also be nice to have.