Strongly typed definitions for Angulars @angular/forms
npm install ngx-strongly-typed-formsbash
npm install ngx-strongly-typed-forms
`
Attention: Since version 7.2 this project does no longer follow semver version numbers.
The major and minor version represents the compatible Angular version and patch versions are bugfixes in this library.
Now you can import generic FormControl, FormGroup and FormArray and use them instead of the classes from @angular/forms
`typescript
import {FormArray, FormControl, FormGroup} from 'ngx-strongly-typed-forms';
`
If you want to use the FormBuilder you have to provide it from your app module
`typescript
import { ReactiveFormsModule } from '@angular/forms';
import { NgxStronglyTypedFormsModule } from 'ngx-strongly-typed-forms';
@NgModule({
imports: [ ReactiveFormsModule, NgxStronglyTypedFormsModule ]
})
export class AppModule {
}
`
All usages of AbstractControl and its subclasses now supports generic types.
This change is not backwards compatible with Angulars AbstractControl. All occurrence at minimum must be typed with AbstractControl, or at best with an interface which describes all form fields.
How does it work
This project does not modify any angular classes but provides new strongly typed definitions for Angulars own forms.
For convenience it re-exports these classes directly from Angular.
$3
* When working with FormBuilder and FormGroups always mention the type you want, or else the TypeScript compiler tries to match
every property, which does not work with nested FormArrays or FormGroups.
`
form = fb.group({
foo: null,
bar: ["bar", Validators.required],
baz: fb.array([])
})
`
* FormArray extends AbstractControl. So if you have a FormArray you can assign it to an AbstractControl. This is necessary, because for instance FormArray.get returns a single instance of type T but FormArray.value returns T[].
It's also important when working with FormArrays as part of complex FormGroups. The generic type of the FormArray must always be the same as the generic of the Array in the model.
Alternatives
* Angulars own effort to create typed forms (https://github.com/angular/angular/pull/20040).
But it's not yet merged and has - in my opinion - the drawback to fall back to untyped forms too easy. At the current state it also does not support typed FormBuilder.
* ngx-typed-form provides typed FormBuilder, but does not enforce the structure of any parameters.
Because of the chosen implementation FormControl, FormGroup and FormArray are only interfaces and can not be used directly
Something does not work as expected
Beside the known limitations, everything that is possible with the native Angular Forms should be possible too.
If you find something not working as expected then there might be a problem in my type definitions. Please open an issue with an minimal example to reproduce the problem and I will try to fix it asap.
Limitations
* AbstractControl#value is not correctly typed for TypeScript strict mode. For FormGroup it returns only values of FormControls that are not disabled. So the correct type should be a DeepPartial.
TypeScript 2.8 supports conditional types to build this structure like
`
type DeepPartial = {
[P in keyof T]?: T[P] extends Array
? Array>
: T[P] extends ReadonlyArray
? ReadonlyArray>
: DeepPartial
};
`
When Angular uses TypeScript 2.8 the return value should be changed.
* The get method on AbstractControl AbstractControl#get(path: string|number []) is impossible to statically type, because every subclass has a different implementation.
FormControl always return null, FormGroup only works with string keys and FormArray only with a numerical index.
Because I never needed a deeply nested access with both number and string, only string key up to a depth of 5 levels are currently supported. If this is not sufficient for you, please open an issue and explain your situation.
* Because of it's nature to support only strongly typed forms, forms with dynamically added fields can not be built an a typesafe way.
Workaround: Use AbstractControl