mirror of
https://github.com/odoo/owl.git
synced 2025-10-06 19:59:41 +07:00
[IMP] component: rewrite props validation code
This commit reworks the props validation code in order to extract a generic validate utility function. The validation should be more robust, with better error messages, and at the same time, it supports `*` in a shape object. And as a bonus, it is now typesafe, and the static props object is now typed. closes #1190
This commit is contained in:
Géry Debongnie
@@ -1,7 +1,8 @@
|
||||
import { BDom, multi, text, toggler, createCatcher } from "../blockdom";
|
||||
import { validateProps } from "../component/props_validation";
|
||||
import { Markup } from "../utils";
|
||||
import { html } from "../blockdom/index";
|
||||
import { isOptional, validateSchema } from "../validation";
|
||||
import { ComponentConstructor } from "../component/component";
|
||||
|
||||
/**
|
||||
* This file contains utility functions that will be injected in each template,
|
||||
@@ -182,6 +183,49 @@ function multiRefSetter(refs: RefMap, name: string): RefSetter {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate the component props (or next props) against the (static) props
|
||||
* description. This is potentially an expensive operation: it may needs to
|
||||
* visit recursively the props and all the children to check if they are valid.
|
||||
* This is why it is only done in 'dev' mode.
|
||||
*/
|
||||
export function validateProps<P>(name: string | ComponentConstructor<P>, props: P, parent?: any) {
|
||||
const ComponentClass =
|
||||
typeof name !== "string"
|
||||
? name
|
||||
: (parent.constructor.components[name] as ComponentConstructor<P> | undefined);
|
||||
|
||||
if (!ComponentClass) {
|
||||
// this is an error, wrong component. We silently return here instead so the
|
||||
// error is triggered by the usual path ('component' function)
|
||||
return;
|
||||
}
|
||||
|
||||
const schema = ComponentClass.props;
|
||||
if (!schema) {
|
||||
return;
|
||||
}
|
||||
const defaultProps = ComponentClass.defaultProps;
|
||||
if (defaultProps) {
|
||||
let isMandatory = (name: string) =>
|
||||
Array.isArray(schema)
|
||||
? schema.includes(name)
|
||||
: name in schema && !("*" in schema) && !isOptional(schema[name]);
|
||||
for (let p in defaultProps) {
|
||||
if (isMandatory(p)) {
|
||||
throw new Error(
|
||||
`A default value cannot be defined for a mandatory prop (name: '${p}', component: ${ComponentClass.name})`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const errors = validateSchema(props, schema);
|
||||
if (errors.length) {
|
||||
throw new Error(`Invalid props for component '${ComponentClass.name}': ` + errors.join(", "));
|
||||
}
|
||||
}
|
||||
|
||||
export const helpers = {
|
||||
withDefault,
|
||||
zero: Symbol("zero"),
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { Schema } from "../validation";
|
||||
import type { ComponentNode } from "./component_node";
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
@@ -9,7 +10,7 @@ type Props = { [key: string]: any };
|
||||
interface StaticComponentProperties {
|
||||
template: string;
|
||||
defaultProps?: any;
|
||||
props?: any;
|
||||
props?: Schema;
|
||||
components?: { [componentName: string]: ComponentConstructor };
|
||||
}
|
||||
|
||||
|
||||
@@ -13,7 +13,6 @@ import { batched, Callback } from "../utils";
|
||||
import { Component, ComponentConstructor } from "./component";
|
||||
import { fibersInError, handleError } from "./error_handling";
|
||||
import { Fiber, makeChildFiber, makeRootFiber, MountFiber, MountOptions } from "./fibers";
|
||||
import { applyDefaultProps } from "./props_validation";
|
||||
import { STATUS } from "./status";
|
||||
|
||||
let currentNode: ComponentNode | null = null;
|
||||
@@ -29,6 +28,18 @@ export function useComponent(): Component {
|
||||
return currentNode!.component;
|
||||
}
|
||||
|
||||
/**
|
||||
* Apply default props (only top level).
|
||||
*
|
||||
* Note that this method does modify in place the props
|
||||
*/
|
||||
function applyDefaultProps<P>(props: P, defaultProps: Partial<P>) {
|
||||
for (let propName in defaultProps) {
|
||||
if ((props as any)[propName] === undefined) {
|
||||
(props as any)[propName] = defaultProps[propName];
|
||||
}
|
||||
}
|
||||
}
|
||||
// -----------------------------------------------------------------------------
|
||||
// Integration with reactivity system (useState)
|
||||
// -----------------------------------------------------------------------------
|
||||
@@ -165,7 +176,10 @@ export class ComponentNode<P extends Props = any, E = any> implements VNode<Comp
|
||||
this.parent = parent;
|
||||
this.parentKey = parentKey;
|
||||
this.level = parent ? parent.level + 1 : 0;
|
||||
applyDefaultProps(props, C);
|
||||
const defaultProps = C.defaultProps;
|
||||
if (defaultProps) {
|
||||
applyDefaultProps(props, defaultProps);
|
||||
}
|
||||
const env = (parent && parent.childEnv) || app.env;
|
||||
this.childEnv = env;
|
||||
for (const key in props) {
|
||||
@@ -284,7 +298,10 @@ export class ComponentNode<P extends Props = any, E = any> implements VNode<Comp
|
||||
const fiber = makeChildFiber(this, parentFiber);
|
||||
this.fiber = fiber;
|
||||
const component = this.component;
|
||||
applyDefaultProps(props, component.constructor as any);
|
||||
const defaultProps = (component.constructor as any).defaultProps;
|
||||
if (defaultProps) {
|
||||
applyDefaultProps(props, defaultProps);
|
||||
}
|
||||
|
||||
currentNode = this;
|
||||
for (const key in props) {
|
||||
|
||||
@@ -1,176 +0,0 @@
|
||||
import { ComponentConstructor } from "./component";
|
||||
|
||||
/**
|
||||
* Apply default props (only top level).
|
||||
*
|
||||
* Note that this method does modify in place the props
|
||||
*/
|
||||
export function applyDefaultProps<P>(props: P, ComponentClass: ComponentConstructor<P>) {
|
||||
const defaultProps = ComponentClass.defaultProps;
|
||||
if (defaultProps) {
|
||||
for (let propName in defaultProps) {
|
||||
if ((props as any)[propName] === undefined) {
|
||||
(props as any)[propName] = defaultProps[propName];
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
//------------------------------------------------------------------------------
|
||||
// Prop validation helper
|
||||
//------------------------------------------------------------------------------
|
||||
function getPropDescription(staticProps: any) {
|
||||
if (staticProps instanceof Array) {
|
||||
return Object.fromEntries(
|
||||
staticProps.map((p) => (p.endsWith("?") ? [p.slice(0, -1), false] : [p, true]))
|
||||
);
|
||||
}
|
||||
return staticProps || { "*": true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate the component props (or next props) against the (static) props
|
||||
* description. This is potentially an expensive operation: it may needs to
|
||||
* visit recursively the props and all the children to check if they are valid.
|
||||
* This is why it is only done in 'dev' mode.
|
||||
*/
|
||||
export function validateProps<P>(name: string | ComponentConstructor<P>, props: P, parent?: any) {
|
||||
const ComponentClass =
|
||||
typeof name !== "string"
|
||||
? name
|
||||
: (parent.constructor.components[name] as ComponentConstructor<P> | undefined);
|
||||
|
||||
if (!ComponentClass) {
|
||||
// this is an error, wrong component. We silently return here instead so the
|
||||
// error is triggered by the usual path ('component' function)
|
||||
return;
|
||||
}
|
||||
applyDefaultProps(props, ComponentClass);
|
||||
|
||||
const defaultProps = ComponentClass.defaultProps || {};
|
||||
let propsDef = getPropDescription(ComponentClass.props);
|
||||
const allowAdditionalProps = "*" in propsDef;
|
||||
|
||||
for (let propName in propsDef) {
|
||||
if (propName === "*") {
|
||||
continue;
|
||||
}
|
||||
const propDef = propsDef[propName];
|
||||
let isMandatory = !!propDef;
|
||||
if (typeof propDef === "object" && "optional" in propDef) {
|
||||
isMandatory = !propDef.optional;
|
||||
}
|
||||
if (isMandatory && propName in defaultProps) {
|
||||
throw new Error(
|
||||
`A default value cannot be defined for a mandatory prop (name: '${propName}', component: ${ComponentClass.name})`
|
||||
);
|
||||
}
|
||||
if ((props as any)[propName] === undefined) {
|
||||
if (isMandatory) {
|
||||
throw new Error(`Missing props '${propName}' (component '${ComponentClass.name}')`);
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
let whyInvalid;
|
||||
try {
|
||||
whyInvalid = whyInvalidProp((props as any)[propName], propDef);
|
||||
} catch (e) {
|
||||
(e as Error).message = `Invalid prop '${propName}' in component ${ComponentClass.name} (${
|
||||
(e as Error).message
|
||||
})`;
|
||||
throw e;
|
||||
}
|
||||
if (whyInvalid !== null) {
|
||||
whyInvalid = whyInvalid.replace(/\${propName}/g, propName);
|
||||
throw new Error(
|
||||
`Invalid Prop '${propName}' in component '${ComponentClass.name}': ${whyInvalid}`
|
||||
);
|
||||
}
|
||||
}
|
||||
if (!allowAdditionalProps) {
|
||||
for (let propName in props) {
|
||||
if (!(propName in propsDef)) {
|
||||
throw new Error(`Unknown prop '${propName}' given to component '${ComponentClass.name}'`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check why an invidual prop value doesn't match its (static) prop definition
|
||||
*/
|
||||
function whyInvalidProp(prop: any, propDef: any): string | null {
|
||||
if (propDef === true) {
|
||||
return null;
|
||||
}
|
||||
if (typeof propDef === "function") {
|
||||
// Check if a value is constructed by some Constructor. Note that there is a
|
||||
// slight abuse of language: we want to consider primitive values as well.
|
||||
//
|
||||
// So, even though 1 is not an instance of Number, we want to consider that
|
||||
// it is valid.
|
||||
if (typeof prop === "object") {
|
||||
if (prop instanceof propDef) {
|
||||
return null;
|
||||
}
|
||||
return `\${propName} is not an instance of ${propDef.name}`;
|
||||
}
|
||||
if (typeof prop === propDef.name.toLowerCase()) {
|
||||
return null;
|
||||
}
|
||||
return `type of \${propName} is not ${propDef.name}`;
|
||||
} else if (propDef instanceof Array) {
|
||||
// If this code is executed, this means that we want to check if a prop
|
||||
// matches at least one of its descriptor.
|
||||
let reasons: string[] = [];
|
||||
for (let i = 0, iLen = propDef.length; i < iLen; i++) {
|
||||
const why = whyInvalidProp(prop, propDef[i]);
|
||||
if (why === null) {
|
||||
return null;
|
||||
}
|
||||
reasons.push(why);
|
||||
}
|
||||
if (reasons.length > 1) {
|
||||
return reasons.slice(0, -1).join(", ") + " and " + reasons[reasons.length - 1];
|
||||
} else {
|
||||
return reasons[0];
|
||||
}
|
||||
}
|
||||
// propsDef is an object
|
||||
if (propDef.optional && prop === undefined) {
|
||||
return null;
|
||||
}
|
||||
if (propDef.type) {
|
||||
const why = whyInvalidProp(prop, propDef.type);
|
||||
if (why !== null) {
|
||||
return why;
|
||||
}
|
||||
}
|
||||
if (propDef.validate && !propDef.validate(prop)) {
|
||||
return "${propName} could not be validated by `validate` function";
|
||||
}
|
||||
if (propDef.type === Array && propDef.element) {
|
||||
for (let i = 0, iLen = prop.length; i < iLen; i++) {
|
||||
const why = whyInvalidProp(prop[i], propDef.element);
|
||||
if (why !== null) {
|
||||
return why.replace(/\${propName}/g, `\${propName}[${i}]`);
|
||||
}
|
||||
}
|
||||
}
|
||||
if (propDef.type === Object && propDef.shape) {
|
||||
const shape = propDef.shape;
|
||||
for (let key in shape) {
|
||||
const why = whyInvalidProp(prop[key], shape[key]);
|
||||
if (why !== null) {
|
||||
return why.replace(/\${propName}/g, `\${propName}['${key}']`);
|
||||
}
|
||||
}
|
||||
for (let propName in prop) {
|
||||
if (!(propName in shape)) {
|
||||
return `unknown prop \${propName}['${propName}']`;
|
||||
}
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -0,0 +1,161 @@
|
||||
type BaseType =
|
||||
| typeof String
|
||||
| typeof Boolean
|
||||
| typeof Number
|
||||
| typeof Date
|
||||
| typeof Object
|
||||
| typeof Array
|
||||
| true
|
||||
| "*";
|
||||
|
||||
type UnionType = (TypeInfo | BaseType)[];
|
||||
type TypeDescription = BaseType | UnionType | TypeInfo;
|
||||
|
||||
interface TypeInfo {
|
||||
type?: TypeDescription;
|
||||
optional?: boolean;
|
||||
validate?: Function;
|
||||
shape?: Schema;
|
||||
element?: TypeDescription;
|
||||
}
|
||||
|
||||
type SimplifiedSchema = string[];
|
||||
type NormalizedSchema = { [key: string]: TypeDescription };
|
||||
export type Schema = SimplifiedSchema | NormalizedSchema;
|
||||
|
||||
// -----------------------------------------------------------------------------
|
||||
// helpers
|
||||
// -----------------------------------------------------------------------------
|
||||
const isUnionType = (t: TypeDescription): t is UnionType => Array.isArray(t);
|
||||
const isBaseType = (t: TypeDescription): t is BaseType => typeof t !== "object";
|
||||
|
||||
export function isOptional(t: TypeDescription): Boolean {
|
||||
return typeof t === "object" && "optional" in t ? t.optional || false : false;
|
||||
}
|
||||
|
||||
function describeType(type: BaseType): string {
|
||||
return type === "*" || type === true ? "value" : type.name.toLowerCase();
|
||||
}
|
||||
|
||||
function describe(info: TypeDescription): string {
|
||||
if (isBaseType(info)) {
|
||||
return describeType(info);
|
||||
} else if (isUnionType(info)) {
|
||||
return info.map(describe).join(" or ");
|
||||
}
|
||||
if ("element" in info) {
|
||||
return `list of ${describe({ type: info.element, optional: false })}s`;
|
||||
}
|
||||
if ("shape" in (info as TypeInfo)) {
|
||||
return `object`;
|
||||
}
|
||||
return describe(info.type || "*");
|
||||
}
|
||||
|
||||
function toSchema(spec: SimplifiedSchema): NormalizedSchema {
|
||||
return Object.fromEntries(
|
||||
spec.map((e) =>
|
||||
e.endsWith("?") ? [e.slice(0, -1), { optional: true }] : [e, { type: "*", optional: false }]
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Main validate function
|
||||
*/
|
||||
export function validate(obj: { [key: string]: any }, spec: Schema) {
|
||||
let errors = validateSchema(obj, spec);
|
||||
if (errors.length) {
|
||||
throw new Error("Invalid object: " + errors.join(", "));
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Helper validate function, to get the list of errors. useful if one want to
|
||||
* manipulate the errors without parsing an error object
|
||||
*/
|
||||
export function validateSchema(obj: { [key: string]: any }, schema: Schema): string[] {
|
||||
if (Array.isArray(schema)) {
|
||||
schema = toSchema(schema);
|
||||
}
|
||||
let errors = [];
|
||||
// check if each value in obj has correct shape
|
||||
for (let key in obj) {
|
||||
if (key in schema) {
|
||||
let result = validateType(key, obj[key], schema[key]);
|
||||
if (result) {
|
||||
errors.push(result);
|
||||
}
|
||||
} else if (!("*" in schema)) {
|
||||
errors.push(`unknown key '${key}'`);
|
||||
}
|
||||
}
|
||||
// check that all specified keys are defined in obj
|
||||
for (let key in schema) {
|
||||
const spec = schema[key];
|
||||
if (key !== "*" && !isOptional(spec) && !(key in obj)) {
|
||||
const isObj = typeof spec === "object" && !Array.isArray(spec);
|
||||
const isAny = spec === "*" || (isObj && "type" in spec ? spec.type === "*" : isObj);
|
||||
let detail = isAny ? "" : ` (should be a ${describe(spec)})`;
|
||||
errors.push(`'${key}' is missing${detail}`);
|
||||
}
|
||||
}
|
||||
return errors;
|
||||
}
|
||||
|
||||
function validateBaseType(key: string, value: any, type: BaseType): string | null {
|
||||
if (typeof type === "function") {
|
||||
if (typeof value === "object") {
|
||||
if (!(value instanceof type)) {
|
||||
return `'${key}' is not a ${describeType(type)}`;
|
||||
}
|
||||
} else if (typeof value !== type.name.toLowerCase()) {
|
||||
return `'${key}' is not a ${describeType(type)}`;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function validateArrayType(key: string, value: any, descr: TypeDescription): string | null {
|
||||
if (!Array.isArray(value)) {
|
||||
return `'${key}' is not a list of ${describe(descr)}s`;
|
||||
}
|
||||
for (let i = 0; i < value.length; i++) {
|
||||
const error = validateType(`${key}[${i}]`, value[i], descr);
|
||||
if (error) {
|
||||
return error;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function validateType(key: string, value: any, descr: TypeDescription): string | null {
|
||||
if (value === undefined) {
|
||||
return isOptional(descr) ? null : `'${key}' is undefined (should be a ${describe(descr)})`;
|
||||
} else if (isBaseType(descr)) {
|
||||
return validateBaseType(key, value, descr);
|
||||
} else if (isUnionType(descr)) {
|
||||
let validDescr = descr.find((p) => !validateType(key, value, p));
|
||||
return validDescr ? null : `'${key}' is not a ${describe(descr)}`;
|
||||
}
|
||||
let result: string | null = null;
|
||||
if ("element" in descr) {
|
||||
result = validateArrayType(key, value, descr.element!);
|
||||
} else if ("shape" in descr && !result) {
|
||||
if (typeof value !== "object" || Array.isArray(value)) {
|
||||
result = `'${key}' is not an object`;
|
||||
} else {
|
||||
const errors = validateSchema(value, descr.shape!);
|
||||
if (errors.length) {
|
||||
result = `'${key}' has not the correct shape (${errors.join(", ")})`;
|
||||
}
|
||||
}
|
||||
}
|
||||
if ("type" in descr && !result) {
|
||||
result = validateType(key, value, descr.type!);
|
||||
}
|
||||
if ("validate" in descr && !result) {
|
||||
result = !descr.validate!(value) ? `'${key}' is not valid` : null;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
Reference in New Issue
Block a user