03 Mar 2022
2 min

Angular Extended Diagnostics

You will often come across statistics presented as an exponential function that show the increasing costs of detection and fixing of software bugs.

Finding and fixing a software problem after delivery is often 100 times more expensive than finding and fixing it during the requirements and design phase.

Software Defect Reduction Top 10 List”, Barry Boehm, University of Southern California, Victor R. Basili, University of Maryland

This is why it’s so important to minimize the risk of new bugs at the earliest possible stage of software development. Fortunately, there are a lot of automated techniques, tools and processes supporting us in this matter (starting with tools integrated in the IDE, all plugins, auto-formatters, linters, through restrictions during transpilation/compilation, extensive static code analysis, scanning external libraries for vulnerabilities, ending with a pyramid of automated tests). Some of these provide us with out-of-the-box support, some require additional resources (time for proper tools configuration, resources to maintain the continuous integration process, etc.).

Angular 13.2.0 version gives us a new functionality called Extended Diagnostics. It’s a tool built into the compilation process of Angular view templates (it’s a part of the compiler itself), it doesn't require any additional infrastructure, any additional scripts – it’s present and it simply works (also with ng serve during transpilation).

Its task is to detect potential anomalies which are not bugs (in the sense that they don’t cause a compilation error and meet all syntax requirements), but at the same time objections might occur and they might not necessarily reflect what the programmer had in mind. It serves as a kind of additional linter for angular view template syntax.

invalidBananaInBox

{ 
  "angularCompilerOptions": {
    "strictTemplates": true,
    "extendedDiagnostics": {
      "checks": {
        "invalidBananaInBox": "error" 
      },
    "defaultCategory": "error"
  }
}

This diagnostic requires enabling strictTemplates. It detects reverse "banana-in-box" syntax at two-way-data-binding (so the use of "([…])" instead of "[(…)]").

// invalid 
<component ([foo])="bar"></component> 
// valid 
<component [(foo)]="bar"></component>

In both cases the syntax is correct, but in the first case we don't use two-way-data-binding, we only attach a handler to the event named "[foo]".

nullishCoalescingNotNullable

{ 
  "compilerOptions": { 
    "strictNullChecks": true, 
    "angularCompilerOptions": {
      "strictTemplates": true,
      "extendedDiagnostics": {
        "checks": {
          "nullishCoalescingNotNullable": "error" 
        },
      "defaultCategory": "error"
    }
  }
}

This diagnostic requires strictTemplates and strictNullChecks to be enabled. It detects the redundant use of the non-nullish coalescing operator "??".

import {Component} from '@angular/core';

@Component({ 
  template: `
    <div>{{ foo ?? 'xxx' }</div> 
    <div>{{ bar ?? 'zzz' }</div>
  `,
  …
})
class MyComponent {
  foo: string | null = 'test'; 
  bar: string = 'test'; 
}

Regarding the "foo" field, the use of the non-nullish coalescing operator is reasonable (the field itself is nullable), but in case of the "bar" (with enabled strictTemplates and strictNullChecks) it’s pointless.

What’s next?

Angular team plans to add new diagnostics in minor releases of the framework. New diagnostics and new bugs may appear along with version upgrades, so by default detected anomalies are returned as warnings (this can be controlled with the "angularCompilerOptions.extendedDiagnostics.defaultCategory" field in the tsconfig file). Ideas for new diagnostics can be submitted via the github feature requests (https://github.com/angular/angular/issues/new?template=2-feature-request.yaml). Full documentation regarding the Extended Diagnostics can be found here: https://angular.io/extended-diagnostics.

References:

Frequently asked questions

How do I configure Angular Extended Diagnostics in tsconfig.json?

Add an extendedDiagnostics object under angularCompilerOptions in tsconfig.json, then set each diagnostic name under checks to a category such as error. The defaultCategory field sets the severity for anomalies that are not listed in checks, and by default detected anomalies are returned as warnings. The diagnostics covered here also require strictTemplates, so enable that flag first. This configuration has been available since Angular 13.2.0.

How do I make Angular extended diagnostic warnings fail the build?

Set the diagnostic's entry under angularCompilerOptions.extendedDiagnostics.checks to error, as in the invalidBananaInBox example. By default, detected anomalies are returned as warnings, which do not stop compilation. Setting defaultCategory to error applies that severity to every diagnostic, which is useful when you want the template linter to block the build across the board.

What is the invalidBananaInBox diagnostic in Angular and why does it flag ([foo])?

The invalidBananaInBox diagnostic flags reverse banana-in-a-box syntax, where ([foo])="bar" is written instead of [(foo)]="bar". The first form is valid syntax, but it only attaches an event handler to an event named [foo] and does not create two-way data binding. The check requires strictTemplates to be enabled. Use [(foo)] whenever you intend two-way binding.

When does Angular report a redundant nullish coalescing operator in templates?

Angular reports a redundant ?? through the nullishCoalescingNotNullable diagnostic when the value on the left side can never be null or undefined. This check requires both strictTemplates and strictNullChecks in the tsconfig. For a field typed string | null, the fallback is reasonable, but for a field typed string, {{ bar ?? 'zzz' }} is pointless and gets flagged. Remove the operator or make the field nullable if a fallback is needed.

Do Angular Extended Diagnostics work with ng serve without extra tooling?

Yes. Extended Diagnostics are part of the Angular compiler's template compilation, so they need no additional scripts, plugins, or infrastructure and run during ng serve as well as during a regular build. They detect anomalies that are not compilation errors but may not reflect what the programmer intended, acting as an additional linter for template syntax. Ideas for new checks can be submitted through the Angular GitHub feature request template.

Share this post

Sign up for our newsletter

Stay up-to-date with the trends and be a part of a thriving community.