Design Doc - Angular Reactive Forms

author: Angular Community
created: 2020-05-08
status: [draft | in review | approved | implemented | obsolete]
doc url: https://hackmd.io/HHodz9FQR6mGCZxRmEimsg?both
discord discussion: https://discord.gg/gCEj4zC in #forms channel
feedback url:
design doc template version: 1.0.0

Objective

This document outlines requirements, and goals for building a new reactive forms API for Angular. A few key goals are:

Type-safe

Angular is built on top of TypeScript to provide type-safe APIs. We want to encourage usage of type-safety when consuming these forms, and provide that type-safety throughout the API.

Composeable

Simple use cases for forms will be covered, but we also want to cover complex use cases, such as:

Nested validation
Nested forms
Complex async validation

Minimal but extensible

Relying on built-in Web APIs would be preferred where possible.

Compatible with native Angular form controls and validators (NG_VALUE_ACCESSOR and NG_VALIDATORS).

Property-renaming-safe - does not need to access controls by string (e.g. formControlName='prop').

This design doc serves to gather feedback, knowledge about existing APIs, and guidance for the proposed new APIs.

Approvals

Expected User/Developer Experience

Background

[Zack DeRose] I've spoken in the past about my initial experience learning RxJS, which revolved around heavy use of BehaviorSubject's, and specifically avoiding operators by calling next() on a given BehaviorSubject within the subscription of some other BehaviorSubject.

This mixture of imperative and declarative styles lead down a dark path. Even without much complexity in the use case, using this BehaviorSubject approach is analygous to assembling a Rune-Goldberg machine. Making changes or fixes to such machine requires a heavy cognitive load on the developer, and simulatenously, the developer also loses the fine grain control over Observable streams that is normally available when using RxJS.

I see the majority of the issues with @angular/form's, is that in it's current state, a developer has no choice but to mix imperative (calling setValue() on a FormControl, implementing writeValue() in the ControlValueAccessor) with declarative when implementing reactive behavior. It's essentially the same as my above BehaviorSubject example, but with no alternative available.

I believe that rectifying this situation should be our paramount goal in @ngrx/forms.

Prior Art

Current Angular Forms libraries

Issues:

Libraries:

ngneat Forms Manager - https://github.com/ngneat/forms-manager
ngx-sub-form - https://github.com/cloudnc/ngx-sub-form
ngObservableForm - https://github.com/SanderElias/ngObservableForm
rxweb/types(Strongly Typed Reactive Form) - https://github.com/rxweb/rxweb/tree/master/client-side/angular/packages/types
Formly - https://formly.dev/
Forms Typed - https://github.com/gparlakov/forms-typed/blob/master/projects/forms/README.md

Prototype

Detailed Design

[[ I imagine this hardly qualifies as fully-detailed ]]

The core of my concept revolves around the concept of a private Observable, for now we'll call it _domValue$: Observable<T>. This property is private because due to the nature of forms, our developers don't have complete control of the domValue (as by intent, control is ceded to our users).

Rather, a developer would supply a valueOperator: Observable<T> => Observable<T>. This operator would allow the developer to define any 'developer controled' dynamic/reactive/programmatic adjustments to the value of the form, based on the _domValue$ of the form, as well as any other Observable in scope that should externally cause the form in question to adjust its value.

Additionally, a developer would supply a validationOperator: Observable<T> => Observable<ValidationErrors | null>, which would operate much like the value operator, but with Validity.

Publically, our @ngrx/forms API would then expose a readonly value$: Observable<T>, as well as a readonly errors$: Observable<ValidationErrors | null>. These would both be created by applying their respective developer-defined operators to the source _domValue$.

(Similar approaches could be used for readonly touched$: Observable<void>, readonly enabled$: Observable<'enabled' | 'disabled'>, readonly submit$: Observable<T>, and readonly blur$: Observable<void>)

Compatability with current reactive forms API

[Jan-Niklas Wortmann] I think creating an API that is compatabile with the current reactive forms is key to the success of this module. Otherwise other third party libraries (e.g. @angular/material), but also existing CustomControls will be pain to use. On top of that additional migration effort would prevent many projects to move this direction.

To establish an API that is compatible with the current reactive forms API I see two approaches.

Extending the key entities by inheritance
Wrap the key entities with a service

Extending the key entities by inheritance

Technically we could extend the key entities of the reactive forms API.

export class ReactiveFormControl<T> extends FormControl {}

This way we could support all the existing features in a compatible way. There could be some drawbacks about the strict template type checking.

Benefits

compatibility
new features will work more or less out of the box
fairly easy migration (could be provided with factory methods and schematics)
easy to determine boundaries

Drawbacks

tight coupling (might break in upcoming versions)

Wrap the key entities with a service

I think this is the approach the ngneat forms manager took. By creating a service that wraps the forms API we could extend type safety, but also generate formControls, etc. to establish a compatible way of working with existing API.

Benefits

Composition over inheritance (lose coupling)
easier to test (DI vs. classes and POJOs)

Drawbacks

no easy migration
sounds like more effort
features added to the reactive forms API might need to be added manually to the service too

Registration of Controls

Validation/Error Handling

See validityOperator and errors$ described above.

Testing

I envision the unit testing would look like controlling/defining the _domValue$ (to model a user's various potential behavior), as well as mocking or defining any other streams the developer would expect to have an affect, and using marble-diagrams/the test scheduler to assert that the public observables (value$/errors$/touched$/enabled$) exposed are as expected.

Caveats

Performance Considerations

Documentation Plan

Style Guide Impact

N/A

Developer Impact

Public API Surface Impact

Developer Experience Impact

Breaking Changes

N/A

Rollout Plan

Integration with existing APIs?
Angular Material integration?

Rollback Plan

N/A

Maintenance Plan

TBD

Ajay Ojha

2020/06/26 01:48:11

Nested validation

Would like to know the complex use case for Nested Validation. (Edited)

2020/06/26 01:48:52

Complex async validation

What do you mean complex async validation? (Edited)

Lars Gyrup Brink Nielsen

2020/08/21 22:04:21

Would we want to be compatible with `ControlValuesAccessor`, `NG_VALIDATORS`, and `NG_ASYNC_VALIDATORS`? (Edited)

James Hollowell

2020/08/24 15:36:17

If not (I think it would be hard to do and cleanly achieve other goals), there should be some kind of optional interop layer so we can still use form controls from other libraries.

Alex Okrushko

2020/08/25 13:54:00

I think we'd want to be compatible. Personally, I'd definitely would want to reuse Angular Material components and not be creating our-own-lib-compatible ones.

Jan-Niklas W.

2020/08/25 15:07:07

I completely agree and from my point of view this should be one of the main goals as the reactive forms API is barely reactive. Just exposing `valueChange` and `statusChange` doesn't make an API reactive. I can't count how many times I was nexting into a subject to use this as a trigger and combine it with `exhaustMap` just to get a consistent submit behavior (Edited)

Zachary DeRose

2020/08/25 15:26:04

:+1:

2020/08/25 15:09:31

alueOperator: Observable<T> => Observable<T>

This is interesting. I am expecting it to be something like `map` most of the times but it also provides the opportunity to enrich formValue with other sources (Edited)

2020/08/25 15:28:37

Exactly!

2020/08/25 15:10:39

readonly touched$: Observable<void>

`submit$` and `blur$` are also common events that occur in a form (Edited)

2020/08/25 15:30:29

:+1: added

2020/08/25 15:12:20

Integration with existing APIs? -

technically there could also be and `@ngrx/forms-store` similar to `@ngrx/router-store` (Edited)

2020/08/25 16:20:07

What do you think about being able to pass form controls around like we pass observables around in our Angular applications? (Edited)

2020/08/26 13:41:41

a `valueOperator: Observable<T> => Observable<T>

I think the types of this should actually be `Observable<T> => Observable<U>` where U defaults to T. This would allow for example a DOM value of a String and an output of a Number or Object (Edited)

Design Doc - Angular Reactive Forms

Objective

Approvals

Expected User/Developer Experience

Background

Prior Art

Prototype

Detailed Design

Compatability with current reactive forms API

Extending the key entities by inheritance

Benefits

Drawbacks

Wrap the key entities with a service

Benefits

Drawbacks

Registration of Controls

Validation/Error Handling

Testing

Caveats

Performance Considerations

Documentation Plan

Style Guide Impact

Developer Impact

Public API Surface Impact

Developer Experience Impact

Breaking Changes

Rollout Plan

Rollback Plan

Maintenance Plan

Read more

Signals with NgRx

The road to NgRx 13