Proposal for withValidation: Advanced Prop Validation in Vue 3

[onmax]

• Start Date: 2024-02-20
• Target Major Version: 3.x
• Reference Issues: N/A
• Implementation PR:

Summary

This RFC introduces withValidation, a feature that aims to enhance Vue 3's prop validation mechanism. It allows for collective prop validation, allowing developers to apply complex validation rules that consider multiple props simultaneously. This method improves the existing validation capabilities by providing a more expressive and readable syntax, facilitating early validation, and better supporting component libraries.

Basic example

<script setup lang="ts">
withValidation(defineProps({
    defaultValue: String | Array,
    type: String,
}), ({ defaultValue, type }) => {
    if (type === 'single' && typeof defaultValue !== 'string') {
        return "defaultValue should be a string for type 'single'";
    } else if (type === 'multiple' && !Array.isArray(defaultValue)) {
        return "defaultValue should be an array for type 'multiple'";
    }
    return true;
});
</script>

This code snippet illustrates how withValidation can be used to ensure that the type of the defaultValue prop matches the specified type prop, increasing the clarity and effectiveness of prop validation.

For a real-world and more complex example, see this PR.

Motivation

• Code readability and maintainability: By enabling collective prop validation, developers can write more readable and maintainable validation logic.
• Early validation capabilities: This feature allows props to be validated prior to component mounting, allowing earlier detection of problems and reducing run-time errors.
• Enhanced component library support: Component libraries benefit significantly from this feature by incorporating more robust validation rules, improving component reliability.

Detailed design

The withValidation function wraps around the prop definition and allows developers to define a second argument - a validation function. This function evaluates the props based on the provided rules and returns either true for a pass or a string error message for a fail. This design supports a wide range of validation scenarios, from simple type checks to complex dependencies between props.

function withValidation<T>(props: T, validate: (props: T) => true | string): T;

This approach integrates seamlessly into the Vue component definition process, offering an elegant solution to include advanced validation logic.

Drawbacks

• Potential Verbosity: Utilizing withValidation in conjunction with withDefaults could lead to verbose code, especially in complex components.
• Implementation Complexity: The introduction of withValidation adds complexity to the Vue core, potentially increasing the learning curve for new developers.
• Increase in Library Size: Adding new features like this may slightly enlarge the Vue library's footprint.
• Refactoring Requirements: Existing projects might need to undergo refactoring to incorporate this validation method, although it is not a breaking change.
• Difference with validator function: Unlike the Validator function, which returns a boolean, withValidation returns true | string, encouraging developers to write an error messages in their components

Alternatives

1. The most straight-forward alternative is to use onBeforeMount and onBeforeUpdate hooks to validate props and handle the error:

Expand to see code

<script setup lang="ts">
import { onBeforeMount, onBeforeUpdate } from 'vue'

interface Props {
	defaultValue: string | string[]
    type: string
}

const props = defineProps<Props>();

function validateProps(p: Props) {
	if (type === 'single' && typeof defaultValue !== 'string') {
        throw new Error("defaultValue should be a string for type 'single'");
    } else if (type === 'multiple' && !Array.isArray(defaultValue)) {
        return throw new Error("defaultValue should be an array for type 'multiple'");
    }
    return true;
}

onBeforeMount(() => validateProps(props))
onBeforeUpdate(() => validateProps(props))
</script>

2. Rely on generics. Since Vue 3.3, we can use generics like <script setup lang="ts" generic="...">. This is a great solution it does not apply in runtime. JS users cannot take advantage of this.

3. Another approach is to continue to rely on external validation libraries, keeping the component and validation logic separate.

Adoption strategy

withValidation is accompanied by extensive documentation, including examples covering a range of validation scenarios. The feature is designed to be backward compatible, allowing developers to adopt it at their own pace without the need for immediate refactoring of existing components.

Unresolved questions

• Establish a comprehensive set of best practices for using withValidation in complex component ecosystems
• In line with composability, we could debate whether or not we could deprecate validator within the defineProp for the streamlined withValidation, simplifying Vue's validation approach.
• API changes: The current API is just a draft, it can be completely modified depending on the feedback of the community and the team
• Similar to the Vue Macro defineEmit, withValidation could be also used for defineEmit, but this should be part of another RFC.