DEV Community: Jrubzjeknf

Using a single interface with Angular Typed Forms

Jrubzjeknf — Fri, 29 Jul 2022 13:27:00 +0000

In my previous post about typed forms I mentioned two utility types which make it easier to work with typed forms.

Here I'll make a three recommendations that will make it a LOT easier to work with typed forms.

🔧 Create a type for your FormGroups

Like this:



type UserForm = FormGroup<{
    name: FormControl<string | null>;
}>;

A typed form like this is much easier to use in code and pass around between components when you have to.




@Component({
    selector: 'my-form',
    template: ` {{ userForm.value }} `,
})
export class MyFormComponent {
    @Input() userForm!: UserForm;
}

@Component({
    selector: 'my-app',
    template: ` <my-form [userForm]="userForm"></my-form>`,
})
export class MyAppComponent {
    userForm: UserForm = new FormGroup(...);
}

You can nest your forms more easily too.



type AddressForm = FormGroup<{
    street: FormControl<string | null>
}>

type UserForm = FormGroup<{
    name: FormControl<string | null>;
    address?: AddressForm
}>;

This way you get concise and clean code, which makes anyone a happy developer. 👍
It also makes it much easier to instantiate FormGroups, since you can infer the types of the controls and the value. We just need a bit of help.

🔨 Infer the control types of your FormGroup

Creating a FormGroup without providing a type causes issues. For example, this throws an error:



type UserForm = FormGroup<{
    name: FormControl<string | null>;
}>;

const userForm: UserForm = new FormGroup({
    name: new FormControl(null)
})

It doesn't know name is of type FormControl<string | null>, because Typescript can't infer that. We need to tell what kind of controls our FormGroup exists of, and we need to use a utility type.



/**
 * Produces the controls for a typed FormGroup or FormArray.
 * Can be used to create a new FormGroup or FormArray.
 *
 * @example const myForm: MyForm = new FormGroup<Controls<MyForm>>({...});
 */
export type Controls<TAbstractControl> = TAbstractControl extends FormGroup<infer TControls>
    ? {
            [K in keyof TControls]: TControls[K];
      }
    : TAbstractControl extends FormArray<infer TControls>
    ? TControls[]
    : TAbstractControl extends FormControl
    ? TAbstractControl
    : never;

type UserForm = FormGroup<{
    name: FormControl<string | null>;
    address?: AddressForm
}>;

const userForm: UserForm = new FormGroup<Controls<UserForm>>({
    name: new FormControl(null)
})

This works wonderfully! name is now a FormControl<string | null> and the code compiles. The additional benefit is that, when making a mistake in the FormControl's type, an error is shown on the control and not the entire group. This makes hunting down errors much quicker and easier.

🛠 Enable the strictTemplates compiler option

Because we can infer the control types and value type from our own FormGroup type, we create a wonderful developer experience where everything is strongly typed and with brevity! With the strictTemplates (or the deprecated fullTemplateTypeCheck) compiler option on, your components are strongly typed as well. As a bonus, you can quickly navigate to controls and values using F12 (Go To Definition), because it relates those types!

To take full advantage, do this:

Prefer navigating to controls using userForm.controls.address instead of userForm.get('address'). The latter will not warn you in case of mistakes. Deep selecting can become tedious (userForm.controls.address.controls.street instead of userForm.get('address.street'), but it is type safe, so make your own decision what you find more important;
For FormGroups you use in multiple files, create a type and create your FormGroup with new FormGroup<Controls<...>>(...) or with a FormBuilder: fb.group<Controls<...>>(...);
If you use a FormBuilder, you have to use fb.control(...) for the controls. The shorthand for creating controls unfortunately doesn't work well with the typed controls.
As mentioned in the previous article, be mindful of the FormValue's type: all its properties are optional, because controls can be disabled, and you must choose how to deal with that.

💻 Code example

I've created a StackBlitz with a single file containing the types and a code example. Don't look at the suggestions of StackBlitz, it pales in comparison to VS Code. You can paste the file straight into any Angular project's .ts file and it will work with correct typing. Be sure to have strictTemplates enabled in order to get type information in the component's template.

Thanks for reading!

I hope it can help you making your code base a tad more type safe. 😊

Making typed forms a bit more consistent

Jrubzjeknf — Tue, 19 Jul 2022 12:24:00 +0000

Angular typed forms are pretty awesome. Strongly typing your forms bring a lot of benefits, but one issue is holding it back: allowing you to define a single interface from which you can create a typed form and infer the form value from it.

Consider the following code:

interface UserFormControls {
  firstName: FormControl<string>;
  lastName: FormControl<string>;
  email: FormControl<string | null>;
  age: FormControl<number | null>;
}

interface User {
  firstName: string;
  lastName: string;
  email: string | null;
  age: number | null;
}

function processUser(user: User): void {
    // ...
}

const userForm = new FormGroup<UserFormControls>({
    firstName: new FormControl('foo', { nonNullable: true }),
    lastName: new FormControl('bar', { nonNullable: true }),
    email: new FormControl('foo@bar.com', { nonNullable: true }),
    age: new FormControl(null)
});

processUser(userForm.value); // This won't actually compile, keep reading

Ideally, you don't want to be forced to maintain two separate interfaces defining the same thing. The User interface can be inferred from the UserFormControls, so let's do that. We use two new types for this.

type FormValue<T extends AbstractControl> = 
    T extends AbstractControl<infer TValue, any>
    ? TValue
    : never;
type FormRawValue<T extends AbstractControl> = 
    T extends AbstractControl<any, infer TRawValue> 
    ? TRawValue 
    : never;

Let's see what happens when we apply these to our UserFormControls.

interface UserFormControls {
    firstName: FormControl<string>;
    lastName: FormControl<string>;
    email: FormControl<string | null>;
    age: FormControl<number | null>;
}
type UserForm = FormGroup<UserFormControls>;
type User = FormValue<UserForm>;
// type User = {
//  firstName?: string | undefined;
//  lastName?: string | undefined;
//  email?: string | null | undefined;
//  age?: number | null | undefined;
// }

type UserRaw = FormRawValue<UserForm>;
// type UserRaw = {
//  firstName: string;
//  lastName: string;
//  email: string | null;
//  age: number | null;
// }

Note that the User type now has all it's properties as optional. This is because controls can be disabled and those won't show up in the final form value. The raw value is typed exactly how we specified our User interface earlier. It is also why the processUser(userForm.value); in the first code block won't compile.

Make your choice

Here you must make a choice:

You can either use the FormValue<..> and deal with every property being potentially undefined, or;
Use the FormRawValue<..> with care. As long as all the controls that can be disabled are marked as optional, your typing will be sound.

My recommendation would be the latter. In that case, we'll end up with the following solution:

type User = FormRawValue<UserForm>;
// type User = {
//  firstName: string;
//  lastName: string;
//  email: string | null;
//  age: number | null;
// }

// ...

function processUser(user: User): void {
    // ...
}

processUser(userForm.value as User);
// or:
processUser(userForm.getRawValue());

Good luck!

Always receive Date objects from a web api

Jrubzjeknf — Wed, 18 Aug 2021 09:27:29 +0000

One of the major downsides of JSON is that a date is received as a string. This usually leads to a lot of code that will cast a Date | string type to a Date object, but it can be done a lot easier.

Using a HttpInterceptor, you can make sure all your date strings will be cast to a Date object. Here is the code:

import {
  HttpEvent,
  HttpHandler,
  HttpInterceptor,
  HttpRequest,
  HttpResponse
} from '@angular/common/http';
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

/**
 * Interceptor which instructs Angular to not parse the JSON it receives and instead uses its own JSON parser.
 * Used to revive dates, which sounds a lot more dubious than it actually is.
 */
@Injectable()
export class JsonParserHttpInterceptor implements HttpInterceptor {
  constructor(private readonly jsonParser: JsonParser) {}

  intercept(
    httpRequest: HttpRequest<any>,
    next: HttpHandler
  ): Observable<HttpEvent<any>> {
    return httpRequest.responseType === 'json'
      ? this.handleJsonResponses(httpRequest, next)
      : next.handle(httpRequest);
  }

  private handleJsonResponses(
    httpRequest: HttpRequest<any>,
    next: HttpHandler
  ): Observable<HttpEvent<any>> {
    return next
      .handle(httpRequest.clone({ responseType: 'text' })) // Tells Angular to not process this request as JSON.
      .pipe(map(event => this.parseResponse(event))); // Use the custom parser instead.
  }

  private parseResponse(event: HttpEvent<any>): HttpEvent<any> {
    return event instanceof HttpResponse
      ? event.clone({ body: this.jsonParser.parse(event.body) })
      : event;
  }
}

/** Custom JSON parser */
@Injectable()
export abstract class JsonParser {
  abstract parse<T = any>(json: string): T;
}

/** JSON parser that can revive dates. Sounds more disturbing than it is. */
@Injectable()
export class JsonDateParser implements JsonParser {
  parse<T = any>(json: string): T {
    return JSON.parse(json, jsonDateReviver);
  }
}

// Matching any ISO8601 string with timezone notation. Milliseconds optional. See tests for examples.
const dateStringRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:.\d+)?(?:Z|(\+|-)([\d|:]*))?$/;

/** Returns a date object for any ISO8601 string with timezone notation. Milliseconds optional. */
export function jsonDateReviver(_key: string, value: string): any {
  if (typeof value === 'string' && dateStringRegex.test(value)) {
    return new Date(value);
  }

  return value;
}

The HttpInterceptor is used to disable Angular's default JSON parsing and use our custom parsing. The custom parser uses the JSON.parse() reviver parameter to revive dates.

The Angular team has stated they will not provide JSON Date parsing out of the box, since it is easily solved using an interceptor. So use this solution!

A working example can be found on this stackblitz:

Angular: template inside template

Jrubzjeknf — Tue, 11 May 2021 10:18:09 +0000

You can use a template inside a template to allow a parent component to replace a wrapper around important content.

TL;DR

See this stackblitz.

Why a template inside a template?

In my case, I have a highly reusable component with two important parts, which are tightly coupled. The issue arose when a wrapper around the second part needed to be replaced.

Here I want to be able to optionally replace the wrapper for part B, while being able to keep part B, like this.

Providing a template

For optionally replacing parts of a component, providing a template using a directive and reading it using @ContentChild is standard procedure.

The directive:

...

@Directive({
  selector: '[appWrapper]'
})
export class WrapperDirective {
  constructor(public template: TemplateRef<any>) {}
}

Providing the template using the directive:

<subcomponent>
  <ng-template appWrapper ...>
    ...
  </ng-template>
</subcomponent>

Reading the directive with the template inside the component:

...

export class SubComponent {
  @ContentChild(WrapperDirective, { static: true }) wrapper?: WrapperDirective;
}

And finally rendering the template, using a fallback whenever none is provided:

<ng-container
  *ngTemplateOutlet="wrapper?.template || defaultWrapperTemplate">
</ng-container>

<ng-template #defaultWrapperTemplate>
  ...
</ng-template>

Sweet, step 1 is done. 🚀 Time for the interesting part. 🙂

Providing the template inside the template

A template can be given context. This is an object for passing parameters to your template, which allows it to be more dynamic. For example, a component that shows a list of items could be provided a template to render each item, where the context object is the item's data.

<list>
  <ng-template listItem let-item="item">
  <div class="{{item.class}}">
    {{ item.name }}
  </div>
  </ng-template>
</list

The cool thing is that a variable within that context object can also be a template. 👍

By passing the part B template to the wrapper template, the wrapper template can show it inside itself where it wants.

Providing the part B template to the wrapper template:

<ng-container
  *ngTemplateOutlet="wrapper?.template || defaultWrapperTemplate; context: { partBTemplate: partBTemplate }">
</ng-container>

<ng-template #partBTemplate>
  ...
</ng-template>

And showing the part B template inside the wrapper template:

  <ng-template appWrapper let-partBTemplate="partBTemplate">
    ...

    <ng-container *ngTemplateOutlet="partBTemplate"></ng-container>
  </ng-template>

This is all you need! 🎉

By using the template inside a template, you can easily replace a wrapper. It is very powerful and can be provided more context information to make richer wrapping templates based on information inside the component.

To see the full thing in action, see this stackblitz:

Thanks for reading!