fix(forms): Add a nonNullable option to FormControl for consistency.

DEPRECATED:

The `initialValueIsDefault` option has been deprecated and replaced with the otherwise-identical `nonNullable` option, for the sake of naming consistency.

Author: dylhunn

aio/content/guide/typed-forms.md

@@ -72,10 +72,10 @@ email.reset();
 console.log(email.value); // null
 ```
 
-TypeScript will enforce that you always handle the possibility that the control has become `null`. If you want to make this control non-nullable, you may use the `initialValueIsDefault` option. This will cause the control to reset to its intial value, instead of `null`:
+TypeScript will enforce that you always handle the possibility that the control has become `null`. If you want to make this control non-nullable, you may use the `nonNullable` option. This will cause the control to reset to its intial value, instead of `null`:
 
 ```ts
-const email = new FormControl('angularrox@gmail.com', {initialValueIsDefault: true});
+const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
 email.reset();
 console.log(email.value); // angularrox@gmail.com
 ```
@@ -125,8 +125,8 @@ Consider again a login form:
 
 ```ts
 const login = new FormGroup({
-    email: new FormControl('', {initialValueIsDefault: true}),
-    password: new FormControl('', {initialValueIsDefault: true}),
+    email: new FormControl('', {nonNullable: true}),
+    password: new FormControl('', {nonNullable: true}),
 });
 ```
 
@@ -149,8 +149,8 @@ interface LoginForm {
 }
 
 const login = new FormGroup<LoginForm>({
-    email: new FormControl('', {initialValueIsDefault: true}),
-    password: new FormControl('', {initialValueIsDefault: true}),
+    email: new FormControl('', {nonNullable: true}),
+    password: new FormControl('', {nonNullable: true}),
 });
 
 login.removeControl('password');
@@ -175,7 +175,7 @@ If you need a `FormGroup` that is both dynamic (open-ended) and heterogenous (th
 
 The `FormBuilder` class has been upgraded to support the new types as well, in the same manner as the above examples.
 
-Additionally, an additional builder is available: `NonNullableFormBuilder`. This type is shorthand for specifying `{initialValueIsDefault: true}` on every control, and can eliminate significant boilerplate from large non-nullable forms. You can access it using the `nonNullable` property on a `FormBuilder`:
+Additionally, an additional builder is available: `NonNullableFormBuilder`. This type is shorthand for specifying `{nonNullable: true}` on every control, and can eliminate significant boilerplate from large non-nullable forms. You can access it using the `nonNullable` property on a `FormBuilder`:
 
 ```ts
 const fb = new FormBuilder();
@@ -185,7 +185,7 @@ const login = fb.nonNullable.group({
 });
 ```
 
-On the above example, both inner controls will be non-nullable (i.e. `initialValueIsDefault` will be set).
+On the above example, both inner controls will be non-nullable (i.e. `nonNullable` will be set).
 
 You can also inject it using the name `NonNullableFormBuilder`.
 

goldens/public-api/forms/index.md

@@ -277,11 +277,15 @@ export class FormArrayName extends ControlContainer implements OnInit, OnDestroy
 // @public
 export class FormBuilder {
     array<T>(controls: Array<T>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormArray<ɵElement<T, null>>;
-    // (undocumented)
+    // @deprecated (undocumented)
     control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & {
         initialValueIsDefault: true;
     }): FormControl<T>;
     // (undocumented)
+    control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & {
+        nonNullable: true;
+    }): FormControl<T>;
+    // (undocumented)
     control<T>(formState: T | FormControlState<T>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormControl<T | null>;
     group<T extends {}>(controls: T, options?: AbstractControlOptions | null): FormGroup<{
         [K in keyof T]: ɵElement<T[K], null>;
@@ -374,7 +378,9 @@ export class FormControlName extends NgControl implements OnChanges, OnDestroy {
 
 // @public
 export interface FormControlOptions extends AbstractControlOptions {
+    // @deprecated (undocumented)
     initialValueIsDefault?: boolean;
+    nonNullable?: boolean;
 }
 
 // @public

packages/forms/src/form_builder.ts

@@ -27,7 +27,8 @@ function isFormControlOptions(options: FormControlOptions|{[key: string]: any}|n
                               undefined): options is FormControlOptions {
   return !!options &&
       (isAbstractControlOptions(options) ||
-       (options as FormControlOptions).initialValueIsDefault !== undefined);
+       (options as FormControlOptions).initialValueIsDefault !== undefined ||
+       (options as FormControlOptions).nonNullable !== undefined);
 }
 
 /**
@@ -85,7 +86,7 @@ export class FormBuilder {
   /**
    * @description
    * Returns a FormBuilder in which automatically constructed @see FormControl} elements
-   * have `{initialValueIsDefault: true}` and are non-nullable.
+   * have `{nonNullable: true}` and are non-nullable.
    *
    * **Constructing non-nullable controls**
    *
@@ -205,10 +206,14 @@ export class FormBuilder {
     return new FormGroup(reducedControls, {asyncValidators, updateOn, validators}) as any;
   }
 
+  /** @deprecated Use `nonNullable` instead. */
   control<T>(formState: T|FormControlState<T>, opts: FormControlOptions&{
     initialValueIsDefault: true
   }): FormControl<T>;
 
+  control<T>(formState: T|FormControlState<T>, opts: FormControlOptions&{nonNullable: true}):
+      FormControl<T>;
+
   control<T>(
       formState: T|FormControlState<T>,
       validatorOrOpts?: ValidatorFn|ValidatorFn[]|FormControlOptions|null,
@@ -217,7 +222,7 @@ export class FormBuilder {
   /**
    * @description
    * Construct a new `FormControl` with the given state, validators and options. Set
-   * `{initialValueIsDefault: true}` in the options to get a non-nullable control. Otherwise, the
+   * `{nonNullable: true}` in the options to get a non-nullable control. Otherwise, the
    * control will be nullable. Accepts a single generic argument, which is the type  of the
    * control's value.
    *
@@ -256,7 +261,7 @@ export class FormBuilder {
       newOptions.validators = validatorOrOpts;
       newOptions.asyncValidators = asyncValidator;
     }
-    return new FormControl<T>(formState, {...newOptions, initialValueIsDefault: true});
+    return new FormControl<T>(formState, {...newOptions, nonNullable: true});
   }
 
   /**
@@ -314,7 +319,7 @@ export class FormBuilder {
 /**
  * @description
  * `NonNullableFormBuilder` is similar to {@link FormBuilder}, but automatically constructed
- * {@link FormControl} elements have `{initialValueIsDefault: true}` and are non-nullable.
+ * {@link FormControl} elements have `{nonNullable: true}` and are non-nullable.
  *
  * @publicApi
  */
@@ -325,7 +330,7 @@ export class FormBuilder {
 export abstract class NonNullableFormBuilder {
   /**
    * Similar to `FormBuilder#group`, except any implicitly constructed `FormControl`
-   * will be non-nullable (i.e. it will have `initialValueIsDefault` set to true). Note
+   * will be non-nullable (i.e. it will have `nonNullable` set to true). Note
    * that already-constructed controls will not be altered.
    */
   abstract group<T extends {}>(
@@ -335,7 +340,7 @@ export abstract class NonNullableFormBuilder {
 
   /**
    * Similar to `FormBuilder#array`, except any implicitly constructed `FormControl`
-   * will be non-nullable (i.e. it will have `initialValueIsDefault` set to true). Note
+   * will be non-nullable (i.e. it will have `nonNullable` set to true). Note
    * that already-constructed controls will not be altered.
    */
   abstract array<T>(
@@ -344,7 +349,7 @@ export abstract class NonNullableFormBuilder {
 
   /**
    * Similar to `FormBuilder#control`, except this overridden version of `control` forces
-   * `initialValueIsDefault` to be `true`, resulting in the control always being non-nullable.
+   * `nonNullable` to be `true`, resulting in the control always being non-nullable.
    */
   abstract control<T>(
       formState: T|FormControlState<T>,

packages/forms/src/model/form_control.ts

@@ -37,6 +37,11 @@ export interface FormControlOptions extends AbstractControlOptions {
    * When a FormControl is reset without an explicit value, its value reverts to
    * its default value.
    */
+  nonNullable?: boolean;
+
+  /**
+   * @deprecated Use `nonNullable` instead.
+   */
   initialValueIsDefault?: boolean;
 }
 
@@ -50,7 +55,7 @@ export interface FormControlOptions extends AbstractControlOptions {
  *
  * `FormControl` takes a single generic argument, which describes the type of its value. This
  * argument always implicitly includes `null` because the control can be reset. To change this
- * behavior, set `initialValueIsDefault` or see the usage notes below.
+ * behavior, set `nonNullable` or see the usage notes below.
  *
  * See [usage examples below](#usage-notes).
  *
@@ -114,7 +119,7 @@ export interface FormControlOptions extends AbstractControlOptions {
  *
  * You might notice that `null` is always added to the type of the control.
  * This is because the control will become `null` if you call `reset`. You can change
- * this  behavior by setting `{initialValueIsDefault: true}`.
+ * this behavior by setting `{nonNullable: true}`.
  *
  * ### Configure the control to update on a blur event
  *
@@ -151,10 +156,10 @@ export interface FormControlOptions extends AbstractControlOptions {
  * ### Reset the control to its initial value
  *
  * If you wish to always reset the control to its initial value (instead of null),
- * you can pass the `initialValueIsDefault` option:
+ * you can pass the `nonNullable` option:
  *
  * ```
- * const control = new FormControl('Nancy', {initialValueIsDefault: true});
+ * const control = new FormControl('Nancy', {nonNullable: true});
  *
  * console.log(control.value); // 'Nancy'
  *
@@ -180,7 +185,7 @@ export interface FormControlOptions extends AbstractControlOptions {
 export interface FormControl<TValue = any> extends AbstractControl<TValue> {
   /**
    * The default value of this FormControl, used whenever the control is reset without an explicit
-   * value. See {@link FormControlOptions#initialValueIsDefault} for more information on configuring
+   * value. See {@link FormControlOptions#nonNullable} for more information on configuring
    * a default value.
    */
   readonly defaultValue: TValue;
@@ -246,19 +251,19 @@ export interface FormControl<TValue = any> extends AbstractControl<TValue> {
   /**
    * Resets the form control, marking it `pristine` and `untouched`, and resetting
    * the value. The new value will be the provided value (if passed), `null`, or the initial value
-   * if `initialValueIsDefault` was set in the constructor via {@link FormControlOptions}.
+   * if `nonNullable` was set in the constructor via {@link FormControlOptions}.
    *
    * ```ts
    * // By default, the control will reset to null.
    * const dog = new FormControl('spot');
    * dog.reset(); // dog.value is null
    *
    * // If this flag is set, the control will instead reset to the initial value.
-   * const cat = new FormControl('tabby', {initialValueIsDefault: true});
+   * const cat = new FormControl('tabby', {nonNullable: true});
    * cat.reset(); // cat.value is "tabby"
    *
    * // A value passed to reset always takes precedence.
-   * const fish = new FormControl('finn', {initialValueIsDefault: true});
+   * const fish = new FormControl('finn', {nonNullable: true});
    * fish.reset('bubble'); // fish.value is "bubble"
    * ```
    *
@@ -368,6 +373,11 @@ export interface ɵFormControlCtor {
    *
    * @param asyncValidator A single async validator or array of async validator functions
    */
+  new<T = any>(value: FormControlState<T>|T, opts: FormControlOptions&{nonNullable: true}):
+      FormControl<T>;
+  /**
+   * @deprecated Use `nonNullable` instead.
+   */
   new<T = any>(value: FormControlState<T>|T, opts: FormControlOptions&{
     initialValueIsDefault: true
   }): FormControl<T>;
@@ -421,7 +431,8 @@ export const FormControl: ɵFormControlCtor =
           // `emitEvent` to `true` to allow that during the control creation process.
           emitEvent: !!this.asyncValidator
         });
-        if (isOptionsObj(validatorOrOpts) && validatorOrOpts.initialValueIsDefault) {
+        if (isOptionsObj(validatorOrOpts) &&
+            (validatorOrOpts.nonNullable || validatorOrOpts.initialValueIsDefault)) {
           if (isFormControlState(formState)) {
             this.defaultValue = formState.value;
           } else {

packages/forms/test/form_control_spec.ts

@@ -817,7 +817,7 @@ describe('FormControl', () => {
     });
 
     it('should reset to the initial value if specified in FormControlOptions', () => {
-      const c2 = new FormControl('foo', {initialValueIsDefault: true});
+      const c2 = new FormControl('foo', {nonNullable: true});
       expect(c2.value).toBe('foo');
       expect(c2.defaultValue).toBe('foo');
 
@@ -829,7 +829,7 @@ describe('FormControl', () => {
       expect(c2.value).toBe('foo');
       expect(c2.defaultValue).toBe('foo');
 
-      const c3 = new FormControl('foo', {initialValueIsDefault: false});
+      const c3 = new FormControl('foo', {nonNullable: false});
       expect(c3.value).toBe('foo');
       expect(c3.defaultValue).toBe(null);
 
@@ -858,7 +858,7 @@ describe('FormControl', () => {
 
     it('should not alter the disabled state when resetting, even if a default value is provided',
        () => {
-         const c2 = new FormControl({value: 'foo', disabled: true}, {initialValueIsDefault: true});
+         const c2 = new FormControl({value: 'foo', disabled: true}, {nonNullable: true});
          expect(c2.value).toBe('foo');
          expect(c2.defaultValue).toBe('foo');
          expect(c2.disabled).toBe(true);