From 67c5fe06e630b0a02cc0c6700bfa53f1773cbbd5 Mon Sep 17 00:00:00 2001 From: cexbrayat Date: Thu, 3 Dec 2020 13:11:41 +0100 Subject: [PATCH] docs: improve FormBuilder.group deprecation message (#39946) This expands the deprecation message that started to pop up in v11.0.3 after the landing of commit e148382bd0c6ba5c442fd6fa8c95f957205b5d01, that deprecated the `{[key: string]: any}` type for the options property of the `FormBuilder.group` method. It turns out that having a custom validator declared as `{ validators: (group: FormGroup) => ValidationErrors|null }` works in practice, but is now inferred by TS as the deprecated version of `group` (because `FormGroup` is a subclass of `AbstractControl` that `ValidatorFn` expects). We considered the possibility of tweaking the forms API to accept such validators, but it turns out to generate too many changes in the framework or possible breaking changes for Angular users. We settled for a more explicit deprecation message, elaborated with the help of @petebacondarwin. This will hopefully help developers to understand why the deprecation warning is showing up when they think they are already using the non-deprecated overload. PR Close #39946 --- packages/forms/src/form_builder.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/forms/src/form_builder.ts b/packages/forms/src/form_builder.ts index 342de58432..c64f4683b8 100644 --- a/packages/forms/src/form_builder.ts +++ b/packages/forms/src/form_builder.ts @@ -54,8 +54,14 @@ export class FormBuilder { * @description * Construct a new `FormGroup` instance. * - * @deprecated This api is not typesafe and can result in issues with Closure Compiler renaming. - * Use the `FormBuilder#group` overload with `AbstractControlOptions` instead. + * @deprecated This API is not typesafe and can result in issues with Closure Compiler renaming. + * Use the `FormBuilder#group` overload with `AbstractControlOptions` instead. + * Note that `AbstractControlOptions` expects `validators` and `asyncValidators` to be valid + * validators. If you have custom validators, make sure their validation function parameter is + * `AbstractControl` and not a sub-class, such as `FormGroup`. These functions will be called with + * an object of type `AbstractControl` and that cannot be automatically downcast to a subclass, so + * TypeScript sees this as an error. For example, change the `(group: FormGroup) => + * ValidationErrors|null` signature to be `(group: AbstractControl) => ValidationErrors|null`. * * @param controlsConfig A collection of child controls. The key for each child is the name * under which it is registered.