Custom error message from prop validator

[znck]

What problem does this feature solve?

Currently, if a custom validator fails, we get a console error log saying Invalid prop: custom validator check failed for prop 'email' which is not helpful if you're using a third-party component. The only way to find out what failed is to jump into the source code of the component and try to understand what does this custom validator do. If the custom validator can provide a custom message that immensely changes developer experience e.g. Instead of Invalid prop: custom validator check failed for prop 'email', it can say, Invalid prop: the prop 'email' should be a valid GMail address.

What does the proposed API look like?

No change in API signature only behavior of validator function. If a validator function throws an error, use it as a custom message for prop validation. Also, allow {{name}} interpolation in error message. So the email can be defined as:

...
  props: {
    email: {
      validator(value) {
        if (!value.endsWith('@gmail.com')) throw new Error('the prop '{{name}}' should be a valid GMail address.')
        return true
     }
   }
...

[posva]

Duplicate of #8726 tho 😆
I think we should talk about the api a bit first

[znck]

It was one-liner but I agree on finalizing the API first. With custom validation messages, we can have user-land packages shipping complex validation helpers. I, myself, can use it in znck/prop-types.

[dietergeerts]

FYI: At the moment, there is a way to have a better warning though, one where you can add the value passed to the prop in the warning message:

/**
 * @type {RegExp}
 */
const validatorWarningRegExp = /Invalid prop: custom validator check failed for prop "(.*?)"\./;

/**
 * Better warn messages than the built-ins (adds value for invalid prop, ...).
 *
 * @see {@link https://vuejs.org/v2/api/#warnHandler}
 *
 * @function
 * @param {VueConstructor} vue
 * @param {function(...*)} handler
 */
export const initGlobalWarnHandlerForVue = (vue, handler) => {
  vue.config.warnHandler = (message, vm, trace) => {
    const validatorWarning = validatorWarningRegExp.exec(message);
    if (validatorWarning) {
      handler('[APP] Vue:', message, '\nValue:', vm[validatorWarning[1]], trace);
    } else {
      handler('[APP] Vue:', message, trace);
    }
  };
};

[chrisvfritz]

When the returned value from a validator is truthy, I wonder if it would be simpler to check if what's returned is a string, then if it is, make that the warning message. Thoughts?

[diachedelic]

@chrisvfritz that would break validators that look like val => val.name, i personally expect only the truthiness of a validation result to be checked.

[chrisvfritz]

@diachedelic That's true. I like the thrown error better then. 🙂

@posva As for the API, I think it can be discussed separately if throwing an error could be an acceptable solution. Though my personal thought is that unless we're using this for something else in validators, I think it might be most intuitive to just bind props (and $props) directly to the function, so they can be accessed the same way as anywhere else in the component.

[posva]

But right now validation takes place in order so not all props are available to validate. I don't think validators should have access to this though

[chrisvfritz]

@posva Yes, the change would require postponing prop validation until after the first pass of processing props. Regarding validators having access to this, what are your concerns?

[posva]

It would allow people to test against anything related to the component and I don't think we should allow that because a validator should be a pure function. Apart from props and maybe slots presence, what would you use from this

[chrisvfritz]

@posva That's it - probably just props and maybe slots. I wouldn't expect the entire instance to be initialized at that point, similar to how not everything is available on this in beforeCreate. When you say "a validator should be a pure function", what are the disadvantages or edge cases you're trying to avoid?

[posva]

I want to avoid access to other properties, for example the $router, $store or other things.