DEV Community: Andrei Gatej

React: beyond useEffect

Andrei Gatej — Tue, 08 Aug 2023 15:54:22 +0000

Introduction

A while ago, I wrote an article about how Virtual DOM is implemented in React. In this article, we are going to continue our journey onto how React works under the hood(sounds like a good name for a journey, right?) by exploring a special aspect of useEffect(), namely when effects are scheduled to be run.

Although the article linked previously is not necessary in order to get the most out of this article, it is worth checking it out - it will help you get a better overall understanding of React and will most likely ease the process of exploring it further. Here is once again the link to it.

Lastly, if you’d like to embark on this React journey, I have written an article that describes a way to explore React by debugging its tests - React: how to debug the source code.

Let’s get started!

A quick note on what hooks really are

Having in mind that Virtual DOM nodes(also known as FiberNodes in React’s implementation of VDOM) are, in essence, JavaScript objects with certain properties, hooks can also thought as being among these special properties.

It’s irrelevant to mention the exact properties - the gist is that React keeps track of hooks with the help of a linked list. This entails that hooks must be called in a strict order upon subsequent re-renders and this is also part of the reason(if not the entire reason itself) as to why one can’t call hooks conditionally.

Here’s a quick illustration that might help:

Link for the above diagram.

Note: hooks is not the actual property that is responsible for keeping track of hooks. It’s there just for simplicity’s sake.

When it comes to the useEffect hook, it requires an additional property in order to be able to queue the effects need to be called at a certain point. Again, the actual name of the property is irrelevant, but it’s important to know that it exists.

In the next section, we are going to reiterate some well-known aspects of useEffect, just to recap.

What you might already know about `useEffect`

You might already have a basic idea of how useEffect works. If not, a quick Google search will reveal the gist of it: it allows you to run some logic after the browser has (re-)rendered.

Usually, developers don’t need to know more than that in order to be productive. I myself didn’t worry too much about what’s going on under the hood in the beginning. However, there is a question that keep on bothering me for a while: how does React know to schedule a task(i.e. a piece of code to be executed) after the browser finishes re-rendering?

Or, put differently, how can one schedule a task to be run after a browser’s rendering tasks?

Rendering tasks are tasks like determining the coordinates of elements, painting pixels on the screen and properly positioning elements on the Z axis. A visualization of these tasks, which are part of the browser’s rendering pipeline, can be found here.

We are going to answer this question in the next section.

What’s more to know about `useEffect`

Whenever a component uses useEffect, its corresponding FiberNode will be flagged accordingly. Such flags are set during the render phase and they are useful during the commit phase. The latter phase also represents the moment when React will schedule the action of running all the effects.

The way React ensures that effects are run after the browser finishes rendering is by using the MessageChannel API. If the name of the API does not seem intuitive for the current situation is because it really isn’t. In fact, this API is most likely to be used as a means to communicate between browser threads.

This is how React makes use of the MessageChannel API to schedule tasks:

const channel = new MessageChannel();
const port = channel.port2;
channel.port1.onmessage = performWorkUntilDeadline;
schedulePerformWorkUntilDeadline = () => {
  port.postMessage(null);
};

performWorkUntilDeadline() is where scheduled tasks(among which can be the one responsible for running the registered effects) are being processed based on their priorities
schedulePerformWorkUntilDeadline() is the function that, when invoked, will schedule performWorkUntilDeadline() to be executed after the browser finishes rendering

Now, another question arises - what’s so special about the MessageChannel API?

It’s a question I have very recently found an answer to, thanks to a very interesting blog post on webperf.tips which says that:

MessageChannel is being used here as a generic mechanism to Post a Task to the Task Queue.

Furthermore, Tasks posted to the Task Queue via MessageChannel are prioritized above most other Tasks.

Besides rendering tasks(e.g. layout, paint, composite), there are also tasks that have to be run as a result of user interaction(e.g. keyup event) or as a result of other factors(e.g. setTimeout(), parsing a file, etc.). So, we have just learned that tasks scheduled with the help of the MessageChannel API will have higher priority compared to other non-rendering tasks. Moreover, it’s important to reiterate that these non-rendering tasks will be executed after rendering tasks.

This article describes other ways to schedule tasks, such as yielding to the main thread, using the scheduler.postTask(), scheduler.yield() and requestIdleCallback(), but some of these APIs are not fully supported among popular browsers or might not fulfill some requirements. It’s definitely worth checking the article out!

Conclusion

Although this article was more about browser internals than React’s useEffect hook, I believe (and hope) it was helpful in the end. Personally, I’m very glad that I have got more acquainted with how browsers do their magic.

Thanks for reading!

References

While writing this article, I stumbled upon some very interesting resources related to how browsers work:

How React uses pragmas to run tests conditionally

Andrei Gatej — Tue, 08 Aug 2023 15:48:13 +0000

Introduction

This article is part of my learning journey as I explore React’s source code. At some point, while reading some tests, I stumbled upon something like this:

// @gate enableSuspenseList
it('warns if an unsupported revealOrder option is used', async () => {
  ....
 });

At first sight, it didn’t tell me much - just a comment and a test case. Then, I noticed this gate comment appeared more and more frequently and then I started looking into it. In this article, I’d like to share my findings, which are pretty much about Babel, Jest and a Abstract Syntax Trees.

By the end of this article, we should get some insights regarding:

the way React sets up its testing environment in a flexible way
how Jest is smartly used by React
what pragmas are as a general concept and how they can be implemented with Babel

A few prerequisites for this article would be some familiarity with Abstract Syntax Trees(henceforth AST) and some basic knowledge of Babel.

Let’s get the ball rolling!

What are pragmas and why are they useful?

In simple terms, pragmas can be thought of as additional instructions or hints given to the compiler.

Babel is a JavaScript compiler and also provides an API whereby the developer can modify AST(i.e. Abstract Syntax Trees) nodes as they’re being visited. This way, by using its API and some clever(but intuitive) logic, we can bring the concept of pragmas to Babel.

When it comes to React, pragmas are used to run tests conditionally based on the environment. For example:

// @gate enableSuspenseList
it('warns if an unsupported revealOrder option is used', async () => {
  ....
 });

The link to the actual test case can be found here.

If the variable enableSuspenseList(we well see where it is defined and how exactly it is retrieved later in the article), then the test case below it will run.

We’ll see how this can be achieved in the following sections.

An overview on React’s testing environment

React uses Jest for testing. Since the tests cases are written using the JSX syntax, React also uses Babel to transpile the JSX code into valid JavaScript code which can then be understood by Jest.

The way React achieves that is by using a custom Jest transformer that is to be applied for all the files in the code base. The Jest option that allows that is called transform and it can accept a function that decides how each file needed for the testing task should be processed.

More about code transformation in Jest can be found here.

Concretely, React specifies the custom transformer function this way:

transform: {
    '.*': require.resolve('./preprocessor.js'),
  },

The above snippet has been excerpted from this configuration file.

The file preprocessor.js leads to a function that, as previously mentioned, is responsible for properly processing every file(denoted by the '.*' regex) encountered during the testing process. Let’s take a quick look at how it is defined:

function(src, filePath) {
  if (filePath.match(/\.css$/)) {
        // ...
  }
  if (filePath.match(/\.coffee$/)) {
    // ... Compile CoffeeScript file ...
  }
  if (filePath.match(/\.ts$/) && !filePath.match(/\.d\.ts$/)) {
    // ... Compile TypeScript file ...
  }
  if (filePath.match(/\.json$/)) {
    // ...
  }

  // Transpiling the source code into valid JavaScript code.
    return babel.transform(
        src,
        otherBabelOptions
        )
}

The link to the complete implementation can be found here.

After the file has been successfully processed, it can be then loaded and executed by Jest and, as a result, the tests will finally run.

The main takeaway to take from this section is that, before letting Jest do its magic, an additional preprocessing step is carried out by Babel. As we will see in the following section, during this processing step we will be able to implement a pragma that will skip a test case based on some conditions.

What does writing a custom pragma actually involve?

As we will see, this section is heavily based on Abstract Syntax Trees(i.e AST) and their usage in Babel, so, for that, I would recommend reading a bit upon these topics from this great resource.

The short answer to the question in the title is to use a write a custom Babel plugin that will alter certain AST nodes such that, when Jest executes the resulted code, it will know it has to skip the test case in question.

Let’s take a simple example in order to get a better understanding of what we are trying to achieve:

// @gate shouldEnableFoo
fit('foo works alright', () => {})

There is no particular reason as to why fit has been used instead of it. f stands for focus.

Let’s assume the variable shouldEnableFoo has been defined in a .js file and it has the value set to true. Thus, when running Jest, the test case should run.

This is what the AST of the above snippet looks like:

The link to the above AST Explorer playground can be found here.

There a few things to be noticed:

to AST node that encapsulates fit(...) is of type ExpressionStatement
ExpressionStatement nodes can be narrowed down to even more explicit expression nodes; as can be seen in the image, fit(...) is a CallExpression(denoted by the expression property), which makes sense, because, in essence, a function is called
another example of a more specific ExpressionStatement node is BinaryExpression:

Knowing the type of the AST node is central to properly creating a plugin that will allow us to implement pragmas with the help of Babel. Additional information on how to create custom Babel plugins can be found in this resource, which has also been mentioned in the beginning of this section.

Let’s go a bit into detail on how this plugin will work:

it will handle AST nodes whose type is ExpressionStatement and their expression property is of type CallExpression - the reason is that each test case is defined by calling a function, e.g. fit('description', () => { ... }) or it('description', () => { ... })

return {
    name: 'test-gate-pragma',
    visitor: {
      ExpressionStatement(path) {
        const statement = path.node;
        const expression = statement.expression;
        if (expression.type === 'CallExpression') {
                    ...
            }
        }
    }
}

once such AST nodes are visited, the plugin will get the comments that are placed right above the line where the test case is defined - since we are dealing with AST nodes, they will also contain information such as their location(e.g. line number, column number); we also have access to all of the comments in the file(along with their location as well), so we can basically filter them out based on their line number and the line number of the CallExpression node
```
switch (callee.type) {
  case 'Identifier': {
    if (
      callee.name === 'test' ||
      callee.name === 'it' ||
      callee.name === 'fit'
    ) {
      const comments = statement.leadingComments;
            ...
        }
    }
}
```
if we are left with a comment that starts with '@gate', then we can carry on and take the expression after the string
```
for (const line of comments) {
  const commentStr = line.value.trim();
  if (commentStr.startsWith('@gate ')) {
    const code = commentStr.slice(6);
    const condition = parse(code);
    ...
  }
}
```
Some line of codes have been removed for the sake of simplicity.

the parse() function will simply parse the expression, which means it will return the AST representation of that expression; this is necessary because, at this point, we are only working with ASTs
if the expression after '@gate' is successfully parsed, then we know we have to alter this CallExpression AST node - the way we are going to do that is by:
- changing the function name to a name of a globally declared function - doing expression.callee.name = 'globally_declared_function'
- 'globally_declared_function' will have access to an object that contains all the variables based on which tests are skipped or not and will also have access to all the initial arguments passed to fit(...), which are the description string and the function that contains the assertions
```
callee.name =
  callee.name === 'fit' ? '_test_gate_focus' : '_test_gate';
expression.arguments = [
  t.arrowFunctionExpression(
    [t.identifier('ctx')],
    condition
  ),
  ...expression.arguments,
];
```
  Here, 'globally_declared_function' is either _test_gate_focus(when fit() has been used) or _test_gate(when it() has been used).
  t.arrowFunctionExpression will create an arrow function which implicitly returns condition.

The actual plugin implementation can be found here.

When Jest loads and executes the resulted code, it will call, in this example, _test_gate_focus(gateFn, descriptionString, assertionsFunc), where gateFn is the function that corresponds to the '@gate' expression. This function will be used by _test_gate_focus, which has access to all the variables(which can also be thought of as flags) based on which tests will skipped or not.

Now, the cherry on the take, the implementation of _test_gate_focus:

global._test_gate_focus = (gateFn, testName, callback) => {
    let shouldPass;
    try {
      const flags = getTestFlags();
      shouldPass = gateFn(flags);
    } catch (e) {
      test.only(testName, () => {
        throw e;
      });
      return;
    }
        if (shouldPass) {
      test.only(testName, callback);
    } else {
      test.only(`[GATED, SHOULD FAIL] ${testName}`, () =>
        expectTestToFail(callback, gatedErrorMessage));
    }
  };

The link for the above snippet can be found here.

getTestFlags() will get all the flags, which can come from different configuration files
the gateFn() is invoked in order to determine whether the test should be expected to pass or not

Until now, the notion of a test being skipped has been used, but, in reality, if the gate expression fails, the test case that corresponds to it is expected to fail as well. It is, indeed, a slight difference between a test being skipped and being expected to fail but, in my opinion, this difference is not really relevant in the context of this article.

To quickly recap what we have been talking about until now:

React uses Jest for testing and Babel for transpiling the code from JSX to valid JavaScript code, that can then be understood by Jest
we can implement pragmas by intervening in the Babel’s traspiling process by creating a custom plugin
the plugin’s logic will be invoked when the ExpressionStatement nodes are visited; the logic involves, first of all, determining whether the expression is preceded by a pragma comment and then, if that’s the case, wrap the test case’s arguments in a globally declared function which has access to all the environment flags and which also is given a function that properly describes the pragma expression; the latter function will then be called with the environment flags
Jest will stumble upon the globally declared function instead of the initial test case expression and that is enough to determine whether the test case should run or not

This entire process can be visualized with the help of this diagram:

The link the to above Excalidraw diagram can be found here.

Conclusion

In this article we have gone through many concepts and, ironically, none of them directly concerned React. At least we have got a better understanding of not only how React sets up its testing environment, but also about how Babel can be used to achieve very useful features.

Thanks for reading!

Angular Router: empty paths, named outlets and a fix that came with Angular 11

Andrei Gatej — Mon, 28 Jun 2021 21:53:05 +0000

In this article, we are going to highlight the importance of a fix that came with the 11th version of Angular Router. We will do so by examining a scenario where the lack of that fix prevents an intuitive solution from working, as well as understanding why the fix in question solves the problem.

The reader doesn't need to have more than a basic knowledge of Angular Router. Although we will make use of some advanced concepts like UrlTree, UrlSegmentGroup, they will be briefly described before being applied.

This article has been inspired by this Stack Overflow question.

Throughout the article we will not be using the example from the aforementioned Stack Overflow question. Instead, it will be a simpler example, so that it can better illustrate the problem we are trying to solve. Before going any further, we must be aware of how Angular Router resolves routes transitions. For that, we'll have to introduce the notion of UrlTree.

UrlTree

Given a URL string, it will be converted into an equivalent UrlTree, which Angular Router will further use to determine whether a configuration exists or not for that route. It can achieve that by traversing the given Routes configuration array and the UrlTree simultaneously. This is how the UrlTree structure looks like:

export class UrlTree {
/* ... */
constructor(
  /** The root segment group of the URL tree */
  public root: UrlSegmentGroup,
  /** The query params of the URL */
  public queryParams: Params,
  /** The fragment of the URL */
  public fragment: string|null) {}
}

as you can probably see, it already resembles a URL, since it has properties like queryParams and fragment. It looks like only the segments of a URL are missing. For that, there is UrlSegmentGroup, which looks as follows:

export class UrlSegmentGroup {
  /* ... */
  parent: UrlSegmentGroup|null = null;

  constructor(
    /** The URL segments of this group. See `UrlSegment` for more information */
    public segments: UrlSegment[],
    /** The list of children of this group */
    public children: {[key: string]: UrlSegmentGroup}) {
    forEach(children, (v: any, k: any) => v.parent = this);
  }
}

and with this we can understand why it's called a UrlTree, because a URL can apparently be seen as a tree of segments. Now it comes the genuine question: why would you need a tree-like structure to represent the segments of a URL? The answer is because Angular Router also supports named outlets and in fact, every property from the children object form above represents a named outlet. It should also be mentioned that when no outlet is specified, the primary outlet is used by default.

A UrlSegment is used to represent a URL segment and for each segment it keeps track of the name and the segment parameters.

Let's see an example: given the URL 'foo/123/(a//named:b)'(where named refers to a named outlet called named), its equivalent UrlTree will be:

{
  segments: [], // The root UrlSegmentGroup never has any segments
  children: {
    primary: {
      segments: [{ path: 'foo', parameters: {} }, { path: '123', parameters: {} }],
      children: {
        primary: { segments: [{ path: 'a', parameters: {} }], children: {} },
        named: { segments: [{ path: 'b', parameters: {} }], children: {} },
      },
    },
  },
}

A structure like the one from above is then used when traversing the Routes configuration array. A configuration that would match the given URL would be this one:

{
  // app-routing.module.ts
  {
    path: 'foo/:id',
    loadChildren: () => import('./foo/foo.module').then(m => m.FooModule)
  },

  // foo.module.ts
  {
    path: 'a',
    component: AComponent,
  },
  {
    path: 'b',
    component: BComponent,
    outlet: 'named',
  },
}

You can try out the above example here.

Now that we grasped the fundamentals of UrlTree, it's time to see the problem we are trying to solve.

If you'd like to read more about UrlTree, I'd recommend having a look at Angular Router: Getting to know UrlTree, ActivatedRouteSnapshot and ActivatedRoute.

The problem

Suppose you are given a configuration that looks like this:

const routes: Routes = [
  {
    path: '',
    component: FooContainer1,
    children: [
      {
        path: '',
        component: FooContainer2,
        children: [
          {
            path: ':id',
            component: FooComponent1,
            outlet: 'test'
          },
          {
            path: '',
            pathMatch: 'full',
            component: DummyComponent1
          }
        ]
      }
    ]
  }
];

Can you think of a URL that would activate the FooComponent1 component?

If your answer is

<button [routerLink]="['/', { outlets: { test: [123] } }]"><!-- ... --></button>

then, whether you are correct or not depends on which version of Angular you're using. In both cases, the UrlTree of the above is:

{
  fragment: undefined
  queryParams: {}
  root: {
    children:
      test: {
        children: {}
        segments: [{ path: '123' }]
      }
    segments: []
  }
}

In Angular versions earlier than 11, the above solution won't work and we will have to find another approach. In Angular 11 this is fixed. Let's see each case in detail.

The process of matching `Routes` with `UrlSegmentGroup`s

It is now worth talking about the matching process between Routes configuration and a UrlSegmentGroup.

The number of segments(delimited by /) in the Route's path property does not have to be equal to the number of UrlSegmentGroup.segments. In order for a Route to be matched, the numbers of segments in the path property must be less than or equal to the length of UrlSegmentGroup.segments. If the previous condition is met, the some of the UrlSegmentGroup.segments segments are said to be consumed.

The same logic applies in case of { path: '', }:

if (route.path === '') {
  if (route.pathMatch === 'full' && (segmentGroup.hasChildren() || segments.length > 0)) {
    throw new NoMatch();
  }

  return {consumedSegments: [], lastChild: 0, parameters: {}};
}

It was necessary to briefly introduce this notion because, based on the consumed segments, there will be 3 cases:

All the UrlSegmentGroup.segments are consumed and UrlSegmentGroup.children is not empty:

An example of this is even the one we have seen at the beginning of this article:

// The `UrlTree`
{
  segments: [], // The root UrlSegmentGroup never has any segments
  children: {
    primary: {
      segments: [{ path: 'foo', parameters: {} }, { path: '123', parameters: {} }],
      children: {
        primary: { segments: [{ path: 'a', parameters: {} }], children: {} },
        named: { segments: [{ path: 'b', parameters: {} }], children: {} },
      },
    },
  },
}

// The configuration
{
  // app-routing.module.ts
  {
    path: 'foo/:id',
    loadChildren: () => import('./foo/foo.module').then(m => m.FooModule)
  },

  // foo.module.ts
  {
    path: 'a',
    component: AComponent,
  },
  {
    path: 'b',
    component: BComponent,
    outlet: 'named',
  },
}

Recall that UrlSegmentGroup.children's values are named outlets and their segments.

All the UrlSegmentGroup.segments are consumed and UrlSegmentGroup.children is empty:

const routes: Routes = [
  {
    path: 'foo/bar'
  }
];

and the URL is foo/bar.

Here's how the UrlTree for foo/bar looks like:

{
  fragment: null,
  queryParams: {},
  root: {
    children: {
      primary: {
        // It is empty
        children: {},
        // Both will be *consumed*
        segments: [{ path: 'foo', parameters: {} }, { path: 'bar', parameters: {} }]
      }
    },
    segments: [],
  }
}

Not all of the UrlSegmentGroup.segments have been consumed:

This is the point where Angular 11 and Angular <11 are different.

In this case, only a few parts of UrlSegmentGroup.segments are consumed. In this case, if the current Route object has either a children property or loadChildren, it will traverse the array found in one of these properties.

The problem here with version earlier than 11 is that when traversing the new inner Routes configuration array, it will not take into account the current outlet name. Recall that an outlet's name is a property in the UrlSegmentGroup.children object.

Coming back to our initial example:

const routes: Routes = [
  {
    path: '',
    component: FooContainer1,
    children: [
      {
        path: '',
        component: FooContainer2,
        children: [
          {
            path: ':id',
            component: FooComponent1,
            outlet: 'test'
          },
          {
            path: '',
            pathMatch: 'full',
            component: DummyComponent1
          }
        ]
      }
    ]
  }
];

and

<button [routerLink]="['/', { outlets: { test: [123] } }]"><!-- ... --></button>

Because the path is '', the UrlSegmentGroup.segments won't be consumed(here's why). The way this is handled in earlier versions is to always use the primary outlet name, although the current outlet name might be different. Since the UrlTree generated by the above RouterLink looks like this:

{
  fragment: undefined
  queryParams: {}
  root: {
    children:
      // No `primary` outlet here, only `test`.
      test: {
        children: {}
        segments: [{ path: '123' }]
      }
    segments: []
  }
}

there won't be any match and the navigation will fail.

This is the current implementation that prevents the above approach from working.

And here is a StackBlitz app with our example and there you can see the navigation fails.

The fix that came with Angular 11

With this version, the exact problem that we had before(at the third case) is fixed. The way this is done is by using the current outlet name when in the third scenario occurs.

Here is the our initial problem, but in Angular 11. As you can see, it's working.

And here's the relevant source code that fixed the problem:

/* ... */
// `childConfig` in this case refers to the content of `children` property.
const matchedOnOutlet = getOutlet(route) === outlet;
const expanded$ = this.expandSegment(
    childModule, segmentGroup, childConfig, slicedSegments,
    matchedOnOutlet ? PRIMARY_OUTLET : outlet, true);

Let's briefly visualize the process:

Because the outlet name won't always be primary and since all the paths until FooComponent1 are '', the first children array will be traversed(denoted by(1)), then the second children array(denoted by (2)) and there it will finally find the match.

Conclusion

Although the fix was a small one, it had a big impact. I had stumbled across a few bugs in the past which were caused by this, so personally I'm glad they eventually found a solution.

Thanks for reading!

Credit goes to the Stack Overflow user Dina Flies, who posted the question.

The diagrams were made with Excalidraw.

Angular Router: Getting to know UrlTree, ActivatedRouteSnapshot and ActivatedRoute

Andrei Gatej — Wed, 11 Nov 2020 13:32:21 +0000

In this part, we're going to cover why UrlTree is the foundation of a route transition and how ActivatedRouteSnapshot and ActivatedRoute provide a way to achieve features like guards, resolvers, or how an ActivatedRoute can be updated.

What is UrlParser and why it is important

Note: You can find each example here.

As we'll see in the following sections, a URL is a serialized version of a UrlTree. As a result, a UrlTree is the deserialized version of a URL.

What a UrlParser does it to convert a URL into a UrlTree and it is primarily used by DefaultUrlSerializer. DefaultUrlSerializer is the default implementation of UrlSerializer and it's used, for instance, by Router.parseUrl() method:

parseUrl(url: string): UrlTree {
  let urlTree: UrlTree;
  try {
    urlTree = this.urlSerializer.parse(url);
  } catch (e) {
    urlTree = this.malformedUriErrorHandler(e, this.urlSerializer, url);
  }
  return urlTree;
}

This also means that, if needed, we can use our custom implementation of UrlSerializer:

// In `providers` array
{ provide: UrlSerializer, useClass: DefaultUrlSerializer },

An URL can have this structure: segments?queryParams#fragment; but, before diving into some examples, let's first define what are the main components of a UrlTree:

export class UrlTree {
  constructor(
    public root: UrlSegmentGroup,
    public queryParams: Params, // Params -> {}
    public fragment: string|null
  ) { }
  /* ... */
}

From the aforementioned URL structure, we can already see that queryParams and fragment have found their pair. However, in which way does the segments part correspond with UrlSegmentsGroup?

An example of a URL would be a/b/c. Here, we have no explicit groups, only two implicit groups and its segments(we'll see why a bit later). Groups are delimited by () and are very useful when we're dealing with multiple router outlets(e.g named outlets).

Let's see the structure of a UrlSegmentGroup:

export class UrlSegmentGroup {
  parent: UrlSegmentGroup|null = null;

  constructor(
    public segments: UrlSegment[],
    public children: {[key: string]: UrlSegmentGroup}
  ) { }

As stated earlier, there are 2 implicit groups. The first one is the root UrlSegmentGroup, which does not have any segments, only one child UrlSegmentGroup. The reason behind this is that it should correspond to the root of the component tree, e.g AppComponent, which is inherently not included in any route configuration. As we'll discover in the next articles from this series, the way Angular resolves route transitions is based on traversing the UrlTree, while taking into account the Routes configuration. The second UrlSegmentGroup, whose parent is the first one, is the one that actually contains the segments. We'll see how a UrlSegment looks in a minute.

We might have a more complex URL, such as foo/123/(a//named:b). The resulted UrlSegmentGroup will be this:

{
  segments: [], // The root UrlSegmentGroup never has any segments
  children: {
    primary: {
      segments: [{ path: 'foo', parameters: {} }, { path: '123', parameters: {} }],
      children: {
        primary: { segments: [{ path: 'a', parameters: {} }], children: {} },
        named: { segments: [{ path: 'b', parameters: {} }], children: {} },
      },
    },
  },
}

which would match a route configuration like this:

{
  {
    path: 'foo/:id',
    loadChildren: () => import('./foo/foo.module').then(m => m.FooModule)
  },

  // foo.module.ts
  {
    path: 'a',
    component: AComponent,
  },
  {
    path: 'b',
    component: BComponent,
    outlet: 'named',
  },
}

You can experiment with this example in this StackBlitz.

As seen from above, UrlSegmentGroup's children are delimited by (). The names of these children are the router outlet.

In /(a//named:b), because it uses a / before ((the could also be x/y/z(foo:path)), a will be segment of the primary outlet. // is the separator for router outlets. Finally, named:b follows this structure: outletName:segmentPath.

Another thing that should be mentioned is the UrlSegment's parameters property:

export class UrlSegment {
  constructor(
    public path: string,
    /** The matrix parameters associated with a segment */
    public parameters: {[name: string]: string}) {}
}

Besides positional parameters(e.g foo/:a/:b), segments can have parameters declared like this: segment/path;k1=v1;k2=v2.

So, a UrlTree can be summarized in: the root UrlSegmentGroup, the queryParams object and the fragment of the issued URL.

What is the difference between `/()` and `()`?

Let's begin with a question, what URL would match such configuration?

const routes = [
  {
    path: 'foo',
    component: FooComponent,
  },
  {
    path: 'bar',
    component: BarComponent,
    outlet: 'special'
  }
]

You can find a working example here.

It's worth mentioning that in this entire process of resolving the next route, the routes array will be iterated over once for each UrlSegmentGroup child at a certain level. This applies to the nested arrays too(e.g children, loadChildren).

So, a URL that matches the above configuration would be: foo(special:bar). This is because the root UrlSegmentGroup's child UrlSegmentGroups are:

{
  // root's children

  primary: { segments: [{ path: 'foo', /* ... */ }], children: {} },
  special: { segments: [{ path: 'bar', /* ... */ }], children: {} },
}

As specified before, for each child(in this case primary and special) it will try to find a match in the routes array.

If the URL was foo/(special:bar), then the root UrlSegmentGroup would have only one child:

{
  // root child

  primary: {
    segments: [{ path: 'foo', /* ... */ }],
    children: {
      special: { segments: [{ path: 'bar', /* ... */ }], children: {} }
    }
  }
}

Which would match this configuration:

const routes: Routes = [
  {
    path: 'foo',
    component: FooComponent,
    children: [
      {
        path: 'bar',
        component: BarComponent,
        outlet: 'special'
      }
    ],
  },
];

You can find a working example here.

Additionally, along the special UrlSegmentGroup, you can have another primary UrlSegmentGroup: foo/(a/path/primary//special:bar). Note that a/path/primary is automatically assigned to a primary UrlSegmentGroup child only if the /() syntax is used.

Exercises

In this section, we're going to go over some exercises in order to get a better understanding of how the UrlParser works.

What URL would match with this configuration ? (to match all of them)

[
  {path: 'a', component: ComponentA},
  {path: 'b', component: ComponentB, outlet: 'left'},
  {path: 'c', component: ComponentC, outlet: 'right'}
],

Solution: a(left:b//right:c)

The root UrlSegmentGroup's children are:

{
  primary: 'a',
  left: 'b',
  right: 'c'
}

What would the UrlTree look like is this case?

console.log(r.parseUrl('/q/(a/(c//left:cp)//left:qp)(left:ap)'))

Solution:

{
  // root's children

  // #1
  primary: {
    segments: ['q'],
    children: {
      // #2
      primary: {
        segments: ['a'],
        children: {
          // #3
          primary: { segments: ['c'] },
          left: { segments: ['cp'] }
        }
      },
      left: {
        segments: ['qp']
      }
    }
  },
  left: {
    segments: ['ap']
  }
}

You can find this example here as well.

/q/(...)(left:ap): #1
/q/(a/(...)//left:qp)...: #2
/q/(a/(c//left:cp)//...)...: #3

UrlTree, ActivatedRouteSnapshot and ActivatedRoute

As we've seen from the previous section, a UrlTree contains the fragment, queryParams and the UrlSegmentGroups that create the URL segments. At the same time, there are other important units that make up the process of resolving the next route: ActivatedRouteSnapshot and ActivatedRoute. This process also consists of multiple phrases, e.g: running guards, running resolvers, activating the routes(i.e updating the view accordingly); these phases will operate on 2 other tree structures: a tree of ActivatedRouteSnapshots(also named RouterStateSnapshot) and a tree of ActivatedRoutes(also named RouterState).

The ActivatedRouteSnapshot tree will be immediately created after the UrlTree has been built. One significant difference between these two tree structures is that in a UrlTree only outlets(named or primary, by default) are considered children(child = UrlSegmentGroup), whereas in RouterStateSnapshot, each matched path of a Route object determines an ActivatedRouteSnapshot child.

Let's see an example. For this route configuration:

const routes: Routes = [
  {
    path: 'foo',
    component: FooComponent,
    children: [
      {
        path: 'bar',
        component: BarComponent,
        outlet: 'special'
      }
    ],
  },
];

and the next URL foo/(special:bar), the ActivatedRouteSnapshot tree would look like this:

{
  // root
  url: 'foo/(special:bar)',
  outlet: 'primary',
  /* ... */
  children: [
    {
      url: 'foo',
      outlet: 'primary',
      /* ... */
      children: [
        { url: 'bar', outlet: 'special', children: [], /* ... */ }
      ]
    }
  ]
}

This tree is constructed by iterating through the route configuration array, while also using the previously created UrlTree. For example,

{
  path: 'foo',
  component: FooComponent,
  children: [/* ... */],
}

will match with this UrlSegmentGroup:

{
  segments: [{ path: 'foo' }]
  children: { special: /* ... */ }
}

Then, the resulted ActivatedRouteSnapshot from above will have a child ActivatedRouteSnapshot, because the matched path(i.e foo) belongs to a route configuration object which also has the children property(the same would've happened if there was loadChildren).

Based on the RouterStateSnapshot, Angular will determine which guards and which resolvers should run, and also how to create the ActivatedRoute tree. RouterState will essentially have the same structure as RouterStateSnapshot, except that, instead of ActivatedRouteSnapshot nodes, it will contain ActivatedRoute nodes. This step is necessary because the developer has the opportunity to opt for a custom RouteReuseStrategy, which is a way to store a subtree of ActivatedRouteSnapshot nodes and can be useful if we don't want do recreate components if the same navigation occurs multiple times.

Furthermore, we can also highlight the difference between ActivatedRoute and ActivatedRouteSnapshot. The ActivatedRouteSnapshot tree will always be recreated(from the UrlTree), but some nodes of the ActivatedRoute tree can be reused, which explains how it's possible to be notified, for example, when positional params(e.g foo/:id/:param) change, by subscribing to ActivatedRoute's observable properties(params, data, queryParams, url etc...).

This is achieved by comparing the current RouterState(before the navigation) and the next RouterState(after the navigation). An ActivatedRoute node can be reused if current.routeConfig === next.routeConfig, where routeConfig is the object we place inside the routes array.

To illustrate that, let's consider this route configuration:

const routes: Routes = [
  {
    path: 'empty/:id',
    component: EmptyComponent,
    children: [
      {
        path: 'foo',
        component: FooComponent,
      },
      {
        path: 'bar',
        component: BarComponent,
        outlet: 'special'
      },
      {
        path: 'beer',
        component: BeerComponent,
        outlet: 'special',
      },
    ]
  }
];

and this initial issued URL: 'empty/123/(foo//special:bar)'. If we would now navigate to empty/999/(foo//special:beer), then we could visualize the comparison between RouterState trees like this:

As you can see, the Empty node(which corresponds to path: 'empty/:id') is reused, because this expression evaluates to true: current.routeConfig === next.routeConfig, where routeConfig is:

{
  path: 'empty/:id',
  children: [/* ... */]
}

We can also see these lines from EmptyComponent:

export class EmptyComponent {
  constructor (activatedRoute: ActivatedRoute) {
    console.warn('[EmptyComponent]: constructor');

    activatedRoute.params.subscribe(console.log);
  }
}

and also from clicking these buttons:

<button (click)="router.navigateByUrl('empty/123/(foo//special:bar)')">empty/123/(foo//special:bar)</button>

<br><br>

<button (click)="router.navigateByUrl('empty/999/(foo//special:beer)')">empty/123/(foo//special:beer)</button>

The same logic can be applied for each of ActivatedRoute's observable properties:

url: Observable<UrlSegment[]>,
/** An observable of the matrix parameters scoped to this route. */
params: Observable<Params>,
/** An observable of the query parameters shared by all the routes. */
queryParams: Observable<Params>,
/** An observable of the URL fragment shared by all the routes. */
fragment: Observable<string>,
/** An observable of the static and resolved data of this route. */
data: Observable<Data>,

/**
 * An Observable that contains a map of the required and optional parameters
  * specific to the route.
  * The map supports retrieving single and multiple values from the same parameter.
  */
get paramMap(): Observable<ParamMap> {
  if (!this._paramMap) {
    this._paramMap = this.params.pipe(map((p: Params): ParamMap => convertToParamMap(p)));
  }
  return this._paramMap;
}

/**
 * An Observable that contains a map of the query parameters available to all routes.
 * The map supports retrieving single and multiple values from the query parameter.
 */
get queryParamMap(): Observable<ParamMap> {
  if (!this._queryParamMap) {
    this._queryParamMap =
        this.queryParams.pipe(map((p: Params): ParamMap => convertToParamMap(p)));
  }
  return this._queryParamMap;
}

A working example can be found here.

When is UrlTree used ?

Now that we've understood what a UrlTree is, we can explore a few use cases.

When a `UrlTree` is returned from a guard, it will result in a redirect operation

As we can see from the source code:

/* 
if `canActivate` returns `UrlTree` -> redirect
*/
checkGuards(this.ngModule.injector, (evt: Event) => this.triggerEvent(evt)),
tap(t => {
  if (isUrlTree(t.guardsResult)) {
    const error: Error&{url?: UrlTree} = navigationCancelingError(
        `Redirecting to "${this.serializeUrl(t.guardsResult)}"`);
    error.url = t.guardsResult;
    throw error;
  }
})

For example:

const routes = [
  {
    path: 'foo/:id',
    component: FooComponent,
    canActivate: ['fooGuard']
  },
  {
    path: 'bar',
    component: BarComponent
  }
];

// `providers` array
[
  {
    provide: 'fooGuard',

    // `futureARS` - future `ActivatedRouteSnapshot`
    useFactory: (router: Router) => (futureARS) => {
      return +futureARS.paramMap.get('id') === 1 ? router.parseUrl('/bar') : true;
    },
    deps: [Router]
  },
]

An example can be found here.

`Router.navigateByUrl()`

The Router.navigateByUrl(url) method converts the provided url into a UrlTree:

navigateByUrl(url: string|UrlTree, extras: NavigationExtras = {skipLocationChange: false}):
    Promise<boolean> {
  /* ... */

  // `parseUrl` -> create `UrlTree`
  const urlTree = isUrlTree(url) ? url : this.parseUrl(url);
  const mergedTree = this.urlHandlingStrategy.merge(urlTree, this.rawUrlTree);

  return this.scheduleNavigation(mergedTree, 'imperative', null, extras);
}

Router Directives

RouterLink and RouterLinkActive rely on UrlTrees in order to achieve their functionality.

RouterLinkActive will compare the current UrlTree with the one resulted from RouterLink's commands and, based on the results, will add/remove classes accordingly.

RouterLink will create a new UrlTree, based on the current UrlTree and the provided commands.

We will explore them in detail in future articles, as they are pretty complex.

If you have any suggestions or questions, you can find me on Twitter. Also, you can find more about me or the work I like to do(answering questions on Stack Overflow, projects, writing technical articles) at andreigatej.dev.

Thanks for reading!

Automating my set-up on a fresh Ubuntu by using a bash script

Andrei Gatej — Thu, 24 Sep 2020 10:39:21 +0000

Originally published at andreigatej.dev.

The Github repository can be found here.

It usually takes me around 30 minutes - 1 hour to set up everything I need in order to start working on a new OS(in this case, Ubuntu). So I figured it would be worth the time spent on building a script that would automate all of this. Moreover, bash scripting has always been something cryptic to me, so I thought this was a good opportunity to get comfortable with writing such scripts.

Usage

Open your terminal in your preferred location and create a file that will eventually be invoked in order to install the programs you'd need.

# `vim` could be replaced with your text editor of choice(e.g `gedit`)
touch setup && vim $_

Paste the content of the setup.sh file into the newly created file.

Run the script with:

sudo bash setup $HOME

We need sudo privileges because the script will install new programs on the OS and $HOME in order to properly place ZSH and to determine the user so we can add it to the docker group.

How it works

The file comprises functions that will install the needed programs. Each function follows this pattern: function installProgramToBeInstalled { }.

For example:

# ...

function installGit {
  format_output "installing git"

  sudo apt install -y git

  echo
}

function installDocker {
  format_output "installing docker"

  curl -s https://get.docker.com/ | bash

  usermod -aG docker $user

  su - $user

  echo
}
# ...

Then, in order to invoke all the functions, I've used this logic:

functions="$(cat $0 | egrep -o install[A-Z]+[A-Za-z]+)"
for f in $functions; do $f;done

$0 refers to the current file. With egrep -o install[A-Z]+[A-Za-z]+) we get all the install functions. Lastly, we loop through each function and invoke it.

Stack Overflow learnings and answers

Andrei Gatej — Sun, 23 Aug 2020 09:59:44 +0000

I've been quite active on Stack Overflow this year and I thought it would be a good idea to put together some answers along with their discoveries.

Here is the repo. Since I'm passionate Angular, I've answered questions from its ecosystem.

Thanks!

Angular: Why RouterLink adds the input to the end of current URL in bracket

Andrei Gatej — Sat, 27 Jun 2020 09:04:18 +0000

Jun 26 '20 Comments: 1 Answers: 1

Lets say my url is: http://localhost:4200/user_id/home. Here is my button code:

  <ion-button [routerLink]="['some_user_id', 'payments']" routerLinkActive="selected"&gt
    <ion-label class="label">Payments</ion-label>
  </ion-button>

Because I was getting Error: Cannot match any routes. I started to investigate the problem and I come to, that routerLink is generating such DOM element:

<a href="user_id/home/(some_user_id/payments)" class="button-native" part="native">

When (in…

Open Full Question

A thorough exploration of Angular Forms

Andrei Gatej — Mon, 20 Jan 2020 21:03:00 +0000

After delving into the @angular/forms package I've been able to get a better understanding of how things really work under the hood. In this article I'd like to share my vision with you.

Note: This article is based on Angular 8.2.x.

Base entities
- AbstractControl
- FormControl
- FormArray
- FormGroup
- AbstractControlDirective
- AbstractFormGroupDirective
- ControlValueAccessor
- Connecting FormControl with ControlValueAccessor
Template Driven Forms and Reactive Forms
- Template Driven Forms
- NgModel
- NgModelGroup
- NgForm
- Reactive Forms
- FormControlDirective
- FormGroupDirective
- FormControlName
- FormGroupName
- FormArrayName
Validators
- Usage of built-in Validators
- Validators' Composition
- Custom Validators
- Dynamic Validators
Exploring built-in ControlValueAccessors
- SelectValueAccessor
- Using <option [value]="primitiveValue">
- Using <option [ngValue]="primitiveOrNonPrimitiveValue">
- SelectMultipleValueAccessor
- RadioValueAccessor
A better understanding of the AbstractControl tree
- _pendingDirty, _pendingValue, _pendingChange
- _pendingChange
- _pendingDirty
- _pendingValue
- AbstractControl.setValue() and AbstractControl.patchValue()
- patchValue example
- setValue example
- What happens with the AbstractControl tree on submit?
- Retrieving AbstractControls from the tree
- AbstractControl.updateValueAndValidity()
- Disabling/enabling AbstractControls
- How are CSS classes added depending on AbstractControl's status ?
Conclusion

Base entities

In order to get the most out of the Forms API, we must ensure that we look over some of its essential parts.

AbstractControl

This (abstract) class contains logic shared across FormControl, FormGroup and FormArray:

running validators
changing and calculating UI status - markAsDirty(), markAsTouched(), dirty, touched, pristine etc...
resetting status
keeping track of validation status(invalid, valid)

This class, as well as its subclasses, can referred to as the model layer - it stores data related to a specific entity.

Multiple AbstractControls can be seen as tree where the leaves are always going to be FormControl instances and the other 2 (FormArray, FormGroup) can be thought of as AbstractControl containers, which entails that they can't be used as leaves because they must contain at least on AbstractControl instance.

// FG - FormGroup
// FA - FormArray
// FC - FormControl

    FG
  /   \
FC    FG
    /    \
  FC     FA
        / | \
      FC FC FC

The above tree can be the result of

<form>
  <input type="text" formControlName="companyName">

  <ng-container formGroupName="personal">
    <input type="text" formControlName="name">

    <ng-container formArrayName="hobbies">
      <input type="checkbox" formControlName="0">
      <input type="checkbox" formControlName="1">
      <input type="checkbox" formControlName="2">
    </ng-container>
  </ng-container>
</form>

You can find more about formArrayName and formGroupName in the upcoming sections.

FormControl

It extends AbstractControl, which means it will inherit all the characteristics listed above. What's important to mention here is that FormControl is put together with only one form control(a DOM element: <input>, <textarea>) or a custom component(with the help of ControlValueAccessor- more on that later!).

A FormControl can be considered standalone if it does not belong to an AbstractControl tree. As a result, it will be completely independent, meaning that its validity, value and user interaction won't be affect any of its form container ancestors(ng-run Example).

FormArray

It extends AbstractControl and its job is to group multiple AbstractControls together.

From a tree perspective, it is a node that must contain at least one descendant. Its validation status, dirtiness, touched status and value usually depend on its descendants. There could be cases, though, where a container has certain validators so errors might appear at that node's level.

Its defining characteristic is that it stores its children in an array.

FormGroup

Same as FormArray, except that it stores its descendants in an object.

AbstractControlDirective

It is the base class for form-control-based directives(NgModel, FormControlName, FormControlDirective) and contains boolean getters that reflect the current status of the bound control(valid, touched, dirty etc...).

The previously mentioned control is bound to a DOM element with the help of a concrete implementation of AbstractControlDirective(NgModel, FormControlName) and a ControlValueAccessor.

Thus, this class can be thought of as a middleman that connects ControlValueAccessor(view layer) with AbstractControl(model layer) - more on that in the forthcoming sections.

It is worth mentioning that multiple AbstractControlDirectives can bind the same AbstractControl to multiple DOM elements or custom components, to multiple ControlValueAccessors.

Consider this example:

<form>
  <input ngModel name="option" value="value1" type="radio">

  <input ngModel="value3" name="option" value="value2" type="radio">

  <input ngModel="value1" name="option" value="value3" type="radio">
</form>

As a side note, providing a default value right from the template can be achieved by setting the last ngModel directive's value to the value of the radio button you want to be checked by default. In the above snippet, the first button will be checked.

This happens because the last directive will be the one which will have the final call
of setUpControl() function.

export function setUpControl(control: FormControl, dir: NgControl): void {
  if (!control) _throwError(dir, 'Cannot find control with');
  if (!dir.valueAccessor) _throwError(dir, 'No value accessor for form control with');

  /* ... */

  dir.valueAccessor !.writeValue(control.value);

  /* ... */
}

ng-run Example.

AbstractFormGroupDirective

It's a container for AbstractFormGroupDirective and AbstractControlDirective instances and its useful when you want to create a sub-group of AbstractControls(eg: address: { city, street, zipcode }) or run validators for some specific AbstractControls(eg: min-max validator that makes sure that min control can't have a value that is greater than max control's value).

Its concrete implementations are: formGroupName, formArrayName, ngModelGroup.

<form [formGroup]="filterForm">
  <ng-container formGroupName="price">
    <input formControlName="min" type="text">
    <input formControlName="max" type="text">
  </ng-container>
</form>

FormGroupName, being a subclass of AbstractFormGroupDirective it has all the attributes listed at the beginning of this section. It acts as a container for AbstractControl instances as well.
But, FormGroup can only be the top-level container. This means, you can't use FormGroupName as a top-level container as it will result in an error.

AbstractFormGroupDirective provides a way to access to top level FormGroup instance:

get formDirective(): Form|null { return this._parent ? this._parent.formDirective : null; }

where this._parent can be another AbstractFormGroupDirective or a FormGroupDirective instance. The FormGroupDirective does not have a _parent property.

ControlValueAccessor

ControlValueAccessor is an essential part for the Forms API and can be thought of as the view layer.

Its job is to connect a DOM element(eg: <input>, <textarea>) or a custom component(eg: <app-custom-input>) with an AbstractControlDirective(eg:NgModel, FormControlName). AbstractControlDirective will eventually become a bridge between ControlValueAccessor(view layer) and AbstractControl(model layer). This way, the 2 layers can interact with each other.

For instance:

when user is typing into an input: View -> Model
when the value is set programmatically(FormControl.setValue('newValue')): Model -> View

Only FormControl instances can 'directly' interact with a ControlValueAccessor, because, in a tree of AbstractControls, a FormControl can only be the leaf node as it is not supposed to contain other nodes. Along these lines, we can deduce that updates that come from the view will start from leaf nodes.

// FG - FormGroup
// FA - FormArray
// FC - FormControl
                                  FG
                                /   \
user typing into an input  <- FC    FA
                                   / | \
                                FC  FC  FC <- user selecting checkbox

The ControlValueAccessor interface looks like this:

export interface ControlValueAccessor {
  writeValue(obj: any): void;

  registerOnChange(fn: any): void;

  registerOnTouched(fn: any): void;

  setDisabledState?(isDisabled: boolean): void;
}

writeValue() - writes a new value to an element; the new value comes from the MODEL(FormControl.setValue -> ControlValueAccessor.writeValue -> update element -> change is visible in the UI)
registerOnChange() - registers a callback function that will be called whenever the value changes in the UI and will propagate the new value to the model.
registerOnTouched() - registers a callback function that will be called when the blur event occurs; the FormControl will be notified of this event as it may need to perform some updates when this event occurs.
setDisabledState - will disable/enable the DOM element depending on the value provided; this method is usually called as a result of a change in the MODEL.

You can see these methods' usefulness in the following section: Connecting FormControl with ControlValueAccessor.

There are 3 types of ControlValueAccessors:

default

  @Directive({
  selector:
      'input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]',
  })
  export class DefaultValueAccessor implements ControlValueAccessor { }

built-in

  const BUILTIN_ACCESSORS = [
    CheckboxControlValueAccessor,
    RangeValueAccessor,
    NumberValueAccessor,
    SelectControlValueAccessor,
    SelectMultipleControlValueAccessor,
    RadioControlValueAccessor,
  ];

You can read more about built-in accessors in Exploring built-in ControlValueAccessors.

custom - when you want a custom component to be part of the AbstractControl tree

  @Component({
    selector: 'app-custom-component',
    providers: [
      {
        provide: NG_VALUE_ACCESSOR,
        useExisting: CustomInputComponent,
        multi: true,
      }
    ]
    /* ... */
  })
  export class CustomInputComponent implements ControlValueAccessor { }

  <form>
    <app-custom-component ngModel name="name"></app-custom-component>
  </form>

Remember that ngModel is a form-control-based directive, so it will become a bridge between a ControlValueAccessor(view) and FormControl(model).

Connecting `FormControl` with `ControlValueAccessor`

As mentioned in the previous sections, AbstractControlDirective is what the view layer(ControlValueAccessor) needs in order to effectively communicate with the model layer(AbstractControl, concretely FormControl) and vice versa.

This connection can be visualized like as follows:

  -------------------------- 
  |                        | 
  |  ControlValueAccessor  |  <--- View Layer
  |                        | 
  -------------------------- 
    |                 ▲
    |                 |
    |                 |
    ▼                 |
------------------------------ 
|                            | 
|  AbstractControlDirective  | 
|                            | 
------------------------------ 
        |           ▲
        |           |
        |           |
        ▼           |
      ----------------- 
      |               | 
      |  FormControl  |  <--- Model Layer
      |               | 
      -----------------

The ↓ indicates the ViewToModelPipeline, whereas ↑ indicates the ModelToViewPipeline.

AbstractControlDirective plays a critical role here. Let's examine the actual implementation!

The above diagram is the result of this code snippet:

Note: In reality, NgControl extends AbstractControlDirective and it mainly acts as a provider for form-control-based directives: NgModel, FormControlName etc..., but doesn't have any default implementation.

The setUpControl function is called every time a form-control-based directive is initialized.

export function setUpControl(control: FormControl, dir: NgControl): void {
  if (!control) _throwError(dir, 'Cannot find control with');
  if (!dir.valueAccessor) _throwError(dir, 'No value accessor for form control with');

  control.validator = Validators.compose([control.validator !, dir.validator]);
  control.asyncValidator = Validators.composeAsync([control.asyncValidator !, dir.asyncValidator]);
  dir.valueAccessor !.writeValue(control.value);

  setUpViewChangePipeline(control, dir);
  setUpModelChangePipeline(control, dir);

  setUpBlurPipeline(control, dir);

  /* ... Skipped for brevity ... */
}

// VIEW -> MODEL
function setUpViewChangePipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnChange((newValue: any) => {
    control._pendingValue = newValue;
    control._pendingChange = true;
    control._pendingDirty = true;

    if (control.updateOn === 'change') updateControl(control, dir);
  });
}

// Update the MODEL based on the VIEW's value
function updateControl(control: FormControl, dir: NgControl): void {
  if (control._pendingDirty) control.markAsDirty();

  // `{emitModelToViewChange: false}` will make sure that `ControlValueAccessor.writeValue` won't be called
  // again since the value is already updated, because this change comes from the view
  control.setValue(control._pendingValue, {emitModelToViewChange: false});

  // If you have something like `<input [(ngModel)]="myValue">`
  // this will allow `myValue` to be the new value that comes from the view
  dir.viewToModelUpdate(control._pendingValue);

  control._pendingChange = false;
}

// MODEL -> VIEW
function setUpModelChangePipeline(control: FormControl, dir: NgControl): void {
  control.registerOnChange((newValue: any, emitModelEvent: boolean) => {
    // control -> view
    dir.valueAccessor !.writeValue(newValue);

    // control -> ngModel
    if (emitModelEvent) dir.viewToModelUpdate(newValue);
  });
}

Here is once again the ControlValueAccessor interface:

export interface ControlValueAccessor {
  writeValue(obj: any): void;

  registerOnChange(fn: any): void;

  registerOnTouched(fn: any): void;

  setDisabledState?(isDisabled: boolean): void;
}

As you can see, the setUpViewChangePipeline method is how the AbstractControlDirective(the dir argument) connects the view with the model(unidirectional connection), by assigning a callback function to ControlValueAccessor.onChange. This will allow an action that happens in the view to be propagated into the model.

Here's a concrete implementation of ControlValueAccessor.registerOnChange:

@Directive({
  selector: 'input[custom-value-accessor][type=text][ngModel]',
  host: {
    '(input)': 'onChange($event.target.value)',
  }
})
export class CustomValueAccessor {
  registerOnChange(fn: (_: any) => void): void { this.onChange = fn; }
}

The setUpModelChangePipeline will allow the AbstractControlDirective to connect the model with the view. This means that every time FormControl.setValue() is invoked, all the callback functions registered within that FormControl will be invoked as well, in order to update that view based on the new model's value.

Notice that I said all the callback functions. This is because multiple AbstractControlDirective can make use of the same FormControl instance.

// Inside `FormControl`
_onChange: Function[] = [];
registerOnChange(fn: Function): void { this._onChange.push(fn); }

// FormControl.setValue
setValue(value: any, options: {
  onlySelf?: boolean,
  emitEvent?: boolean,
  emitModelToViewChange?: boolean,
  emitViewToModelChange?: boolean
} = {}): void {
  (this as{value: any}).value = this._pendingValue = value;
  if (this._onChange.length && options.emitModelToViewChange !== false) {
    this._onChange.forEach(
        (changeFn) => changeFn(this.value, options.emitViewToModelChange !== false));
  }
  this.updateValueAndValidity(options); // Update ancestors
}

Here's an example:

<form>
  <input type="radio" ngModel name="genre" value="horror">
  <input type="radio" ngModel name="genre" value="comedy">
</form>

The setUpControl(control, dir) will be called twice, once for every ngModel. But, on every call, the control(a FormControl instance) argument will be the same. This means that control.onChanges will contain 2 callback function, one for each ControlValueAccessor(<input type="radio"> has the RadioControlValueAccessor bound to it).

As a side note, the ControlValueAccessor.registerOnTouched follows the same principle as ControlValueAccessor.registerOnChange:

// Called inside `setUpControl`
function setUpBlurPipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnTouched(() => {
    control._pendingTouched = true;

    if (control.updateOn === 'blur' && control._pendingChange) updateControl(control, dir);
    if (control.updateOn !== 'submit') control.markAsTouched();
  });
}

This will allow the model to be updated whenever the blur event occurs inside the view.

Back to Contents

Template Driven Forms and Reactive Forms

Both strategies are very powerful, but, in my opinion, Reactive Forms come handy when dealing with complex, dynamic logic.

Template Driven Forms

When using this strategy, most of the logic that concerns the form's construction is performed inside the view. This means that the AbstractControl tree is being created while the view is being built.

Here are the tools we can use when following this template-driven approach:

export const TEMPLATE_DRIVEN_DIRECTIVES: Type<any>[] =
    [NgModel, NgModelGroup, NgForm];

NgModel

It's a form-control-based directive, connects the view layer with the model layer(FormControl) and vice versa and. It also registers the FormControl into the AbstractControl tree.

When using this directive, you can also specify some options:

@Input('ngModelOptions')
  options !: {name?: string, standalone?: boolean, updateOn?: 'change' | 'blur' | 'submit'};

If you want to use a standalone FormControl instance, you can follow this approach:

<form #f="ngForm">
  <input [ngModelOptions]="{ standalone: true }" #myNgModel="ngModel" name="name" ngModel type="text">
</form>

{{ myNgModel.value }}

<br>

{{ f.value | json }}

ng-run Example.

NgModelGroup

Provides a way to group multiple NgModel and NgModelGroup directives. In the model layer, this is represented by a non-top-level FormGroup instance.
It also registers the FormGroup into the AbstractControl tree.

<form> <!-- `NgForm` - automatically bound to `<form>` -->
  <input type="text" ngModel name="companyName"/>

  <div ngModelGroup="personal">
    <input type="text" ngModel name="name"/>

    <div ngModelGroup="address">
      <input type="text" ngModel name="city"/>
      <input type="text" ngModel name="street" />
    </div>
  </div>
</form>

The first occurrence of NgModelGroup must be a child of NgForm:

<!-- Valid -->
<form>
  <ng-container #myGrp="ngModelGroup" ngModelGroup="address">
    <input type="text"ngModel name="city" />
    <input type="text" ngModel name="street">
  </ng-container>
</form>

<!-- Invalid: `No provider for ControlContainer ...` -->
<div #myGrp="ngModelGroup" ngModelGroup="address">
  <input type="text"ngModel name="city" />
  <input type="text" ngModel name="street">
</div>

NgForm

It groups multiple NgModel and NgModelGroup directives. In the model layer, it is represented by a top-level instance, so it listens to form-specific events, such as reset and submit. Also, it is automatically bound to <form> tags.

In the model, this is the root FormGroup instance of the AbstractControl tree.

<form> <!-- NgForm -->
  <input ngModel name="companyName" type="text"> <!-- NgModel -->

  <div ngModelGroup="address"> <!-- NgModelGroup -->
    <input ngModel name="city" type="text"> <!-- NgModel -->
    <input ngModel name="street" type="text"> <!-- NgModel -->
  </div>
</form>

Reactive Forms

As opposed to Template Driven Forms, when using Reactive Forms the form is already created when the view is being built.

Here are the tools we can use when following this reactive approach:

export const REACTIVE_DRIVEN_DIRECTIVES: Type<any>[] =
    [FormControlDirective, FormGroupDirective, FormControlName, FormGroupName, FormArrayName];

FormControlDirective

It is a form-control-based directive, it is the bridge between the 2 main layers: view and model.

It receives a FormControl instance([formControl]="formControlInstance") which is already synced with, because formControlInstance is already part of an existing AbstractControl tree. Therefore, the important thing to do here is just to bind the formControlInstance to the current DOM element by using the value accessor.

If you want to use a standalone FormControl instance, you can follow this approach:

<input #f="ngForm" [formControl]="formControlInstance" type="text">

{{ f.value }}

FormGroupDirective

In the model layer, it is a top-level FormGroup instance(<form [formGroup]="formGroupInstance">). This also means that it listens to form-specific events, such as reset and submit. formGroupInstance is the root of an already built AbstractControl tree.

FormControlName

It receives a string as argument([formControlName]="nameOfFormControlInstance") and its task is to determine the FormControl instance depending on the provided control name(nameOfFormControlInstance) and the position in the view. If the FormControl instance is not found based on the path, an error will be thrown.

Thus, nameOfFormControlInstance must be a valid name, because it relies on the form container to correctly add this FormControl to the AbstractControl tree.

As mentioned before, the path is inferred based on the position of the DOM element(or custom component) and nameOfFormControlInstance:

// control - is, in this case, the top level `FormGroup` instance
function _find(control: AbstractControl, path: Array<string|number>| string, delimiter: string) {
  if (path == null) return null;

  if (!(path instanceof Array)) {
    path = (<string>path).split(delimiter);
  }
  if (path instanceof Array && (path.length === 0)) return null;

  return (<Array<string|number>>path).reduce((v: AbstractControl | null, name) => {
    if (v instanceof FormGroup) {
      return v.controls.hasOwnProperty(name as string) ? v.controls[name] : null;
    }

    if (v instanceof FormArray) {
      return v.at(<number>name) || null;
    }

    return null;
  }, control);
}

<form [formGroup]="myFormGroup">
  <!-- path: 'name' -->
  <input formControlName="name" type="text">

  <!-- path: 'address' -->
  <ng-container formGroupName="address">
    <!-- path: ['address', 'city'] -->
    <input formControlName="city" type="text">

    <!-- path: ['address', 'street'] -->
    <input formControlName="street" type="text">
  </ng-container>
</form>

And this is how the path of each directive is determined:

export function controlPath(name: string, parent: ControlContainer): string[] {
  return [...parent.path !, name];
}

It is worth mentioning that nameOfFormControlInstance can't be dynamic. Once the FormControl is added, it can't be changed automatically.(Example)

Here's why:

@Directive({selector: '[formControlName]', providers: [controlNameBinding]})
export class FormControlName extends NgControl implements OnChanges, OnDestroy {
  /* ... */
  ngOnChanges(changes: SimpleChanges) {
    if (!this._added) this._setUpControl();
  }

  private _setUpControl() {
    this._checkParentType();

    // formDirective - points to the top-level `FormGroup` instance
    (this as{control: FormControl}).control = this.formDirective.addControl(this);
    if (this.control.disabled && this.valueAccessor !.setDisabledState) {
      this.valueAccessor !.setDisabledState !(true);
    }
    this._added = true;
  }
  /* ... */
}

However, if you still want to change the FormControl instance when the nameOfFormControlInstance changes, you can use this:

{FormArray|FormGroup}.setControl(ctrlName, formControlInstance)

FormGroupName

It receives a string as an argument([formGroupName]="nameOfFormGroupInstance") and based on that argument, it has to find the right FormGroup instance.

It can't be used as a top-level form control container, it must be registered within an exiting FormGroupDirective.

Suppose you have a form like this:

const address = this.fb.group({
  street: this.fb.control(''),
});

this.form = this.fb.group({
  name: this.fb.control(''),
  address,
});

Writing this in the view will result in an error(Cannot find control with name: 'street'):

<form #f="ngForm" [formGroup]="form">
  <input formControlName="name" type="text">

  <input formControlName="street" type="text">
</form>

The way to solve this is to use the FormGroupName directive in order to create a sub-group, so that the view will correlate with model.

<form #f="ngForm" [formGroup]="form">
  <input formControlName="name" type="text">

  <ng-container formGroupName="address">
    <input formControlName="street" type="text">
  </ng-container>
</form>

{{ f.value | json }}

Note: when using FormControlDirective([formControl]="formControlInstance") this is not needed, because the FormControlDirective does not have to find the FormControl instance since it already receives one through formControlInstance.

FormArrayName

Same as FormGroupName, except that is has to find an existing FormArray instance in the AbstractControl tree.

this.fooForm = this.fb.group({
  movies: this.fb.array([
    this.fb.control('action'),
    this.fb.control('horror'),
    this.fb.control('mistery'),
  ]),
});

<form #f="ngForm" [formGroup]="fooForm">
  <ng-container formArrayName="movies">
    <input
      *ngFor="let _ of fooForm.controls['movies'].controls; let idx = index;"
      [formControlName]="idx"
      type="text"
    >
  </ng-container>
</form>

{{ f.value | json }}

Back to Contents

Validators

Validators allow developers to put constraints on AbstractControl instances(FormControl, FormArray, FormGroup).

Validators are set and run when the AbstractControl tree is initialized. If you want to set them after the initialization has taken place, you can use AbstractFormControl.setValidators and AbstractFormControl.setAsyncValidators to set them and AbstractFormControl.updateValueAndValidity to run them.

setValidators(newValidator: ValidatorFn|ValidatorFn[]|null): void {
  this.validator = coerceToValidator(newValidator);
}

updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
  /* ... */

  if (this.enabled) {
    this._cancelExistingSubscription();
    // Run sync validators
    // and will invoke `this.validator`
    (this as{errors: ValidationErrors | null}).errors = this._runValidator();
    // If `errors` property is not null -> status = 'INVALID'
    (this as{status: string}).status = this._calculateStatus();

    if (this.status === VALID || this.status === PENDING) {
      this._runAsyncValidator(opts.emitEvent);
    }
  }

  /* ... */

  if (this._parent && !opts.onlySelf) {
    this._parent.updateValueAndValidity(opts);
  }
}

From the above code snippet we can also deduce that async validators will not run if the sync validators returned errors.

Usage of built-in Validators

The built-in validators are available as directives or as static members of Validator class.

For example, the email validator can be used directly in the view like this:

<form>
  <input email ngModel name="email" type="text">
</form>

@Directive({
  selector: '[email][formControlName],[email][formControl],[email][ngModel]',
  providers: [EMAIL_VALIDATOR]
})
export class EmailValidator implements Validator {
  /* ... */

  validate(control: AbstractControl): ValidationErrors|null {
    return this._enabled ? Validators.email(control) : null;
  }

  /* ... */
}

Whereas with Reactive Forms you'd use it like this:

this.form = new FormGroup({
  name: new FormControl(defaultValue, [Validators.Email])
})

Although when using Reactive Forms the validators are usually set in the component class, you can still provide validators inside the view; when the AbstractControl instance is created, the validators will eventually be merged inside setUpControl

// dir.validator - sync validators provided via directives(eg: `<input email type="text">`)
// control.validator - sync validators provided through `Reactive Forms`(eg: new FormControl('', [syncValidators]))
export function setUpControl(control: FormControl, dir: NgControl): void {
  if (!control) _throwError(dir, 'Cannot find control with');
  if (!dir.valueAccessor) _throwError(dir, 'No value accessor for form control with');

  control.validator = Validators.compose([control.validator !, dir.validator]);
  control.asyncValidator = Validators.composeAsync([control.asyncValidator !, dir.asyncValidator]);

  /* ... */
}

Validators' Composition

Validators can be provided from multiple sources: either form the view, or from the class, or from both.

All the validators will be eventually be merged into a single function that, when invoked, will execute all of them sequentially and accumulate their results(returned errors).

Those which implement the Validator interface will be normalized first, meaning that will be transformed into a function that, when invoked, will execute the Validator.validate method:

export function normalizeValidator(validator: ValidatorFn | Validator): ValidatorFn {
  if ((<Validator>validator).validate) {
    return (c: AbstractControl) => (<Validator>validator).validate(c);
  } else {
    return <ValidatorFn>validator;
  }
}

Validators are set and merged(if needed) inside setUpControl function:

export function setUpControl(control: FormControl, dir: NgControl): void {
  if (!control) _throwError(dir, 'Cannot find control with');
  if (!dir.valueAccessor) _throwError(dir, 'No value accessor for form control with');

  control.validator = Validators.compose([control.validator !, dir.validator]);
  control.asyncValidator = Validators.composeAsync([control.asyncValidator !, dir.asyncValidator]);

  /* ... */
}

Let's explore the magic behind Validators.compose:

export class Validators {
  static compose(validators: (ValidatorFn|null|undefined)[]|null): ValidatorFn|null {
    if (!validators) return null;
    const presentValidators: ValidatorFn[] = validators.filter(isPresent) as any;
    if (presentValidators.length == 0) return null;

    return function(control: AbstractControl) {
      return _mergeErrors(_executeValidators(control, presentValidators));
    };
  }
}

function _executeValidators(control: AbstractControl, validators: ValidatorFn[]): any[] {
  return validators.map(v => v(control));
}

// Accumulate errors
function _mergeErrors(arrayOfErrors: ValidationErrors[]): ValidationErrors|null {
  const res: {[key: string]: any} =
      arrayOfErrors.reduce((res: ValidationErrors | null, errors: ValidationErrors | null) => {
        return errors != null ? {...res !, ...errors} : res !;
      }, {});
  return Object.keys(res).length === 0 ? null : res;
}

The same logic applies to Validator.composeAsync, with the exception of the way validators are executed. First, it will convert all the async validators into observables and then will execute them with the help of the forkJoin operator.

export class Validators {
  static composeAsync(validators: (AsyncValidatorFn|null)[]): AsyncValidatorFn|null {
    if (!validators) return null;
    const presentValidators: AsyncValidatorFn[] = validators.filter(isPresent) as any;
    if (presentValidators.length == 0) return null;

    return function(control: AbstractControl) {
      const observables = _executeAsyncValidators(control, presentValidators).map(toObservable);
      return forkJoin(observables).pipe(map(_mergeErrors));
    };
  }
}

Custom Validators

A recommended way to create a custom validator is to use it as a directive that implements the Validator interface:

// min-max-validator.directive.ts
@Directive({
  selector: '[min-max-validator]',
  providers: [
    {
      provide: NG_VALIDATORS,
      useExisting: forwardRef(() => MinMaxValidator),
      multi: true,
    }
  ]
})
export class MinMaxValidator implements Validator {

  constructor() { }

  validate (f: FormGroup): ValidationErrors | null {
    if (f.pristine) {
      return null;
    }

    const { min, max } = f.controls;

    // `min` or `max` is not a number or is empty
    if (min.invalid || max.invalid) {
      return null;
    }

    if (+min.value >= +max.value) {
      return { minGreaterMax: 'min cannot be greater than max!' };
    }

    return null;
  }
}

<form #f="ngForm">
  <ng-container min-max-validator ngModelGroup="price" #priceGrp="ngModelGroup">
    <input type="text" ngModel name="min" pattern="^\d+$" required />
    <input type="text" ngModel name="max" pattern="^\d+$" required >
  </ng-container>
</form>

ng-run Example

Dynamic Validators

The Validator interface looks like this:

export interface Validator {
  validate(control: AbstractControl): ValidationErrors|null;

  registerOnValidatorChange?(fn: () => void): void;
}

We can use the registerOnValidatorChange to register a callback function that should be called whenever the validator's inputs change. Invoking that callback function will ensure that your AbstractControl instance is in line with the updated validator.

Example: <input [required]="true"> --> <input [required]="false">

@Directive({
selector:
    ':not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]',
providers: [REQUIRED_VALIDATOR],
host: {'[attr.required]': 'required ? "" : null'}
})
export class RequiredValidator implements Validator {
  set required(value: boolean|string) {
    this._required = value != null && value !== false && `${value}` !== 'false';
    if (this._onChange) this._onChange();
  }

  registerOnValidatorChange(fn: () => void): void { this._onChange = fn; }
}

export function setUpControl(control: FormControl, dir: NgControl): void {
  /* ... */

  // re-run validation when validator binding changes, e.g. minlength=3 -> minlength=4
  dir._rawValidators.forEach((validator: Validator | ValidatorFn) => {
    if ((<Validator>validator).registerOnValidatorChange)
      (<Validator>validator).registerOnValidatorChange !(() => control.updateValueAndValidity());
  });

  dir._rawAsyncValidators.forEach((validator: AsyncValidator | AsyncValidatorFn) => {
    if ((<Validator>validator).registerOnValidatorChange)
      (<Validator>validator).registerOnValidatorChange !(() => control.updateValueAndValidity());
  });

  /* ... */
}

ng-run Example.

Back to Contents

Exploring built-in `ControlValueAccessor`s

These are the built-in value accessors that Angular provides us with:

const BUILTIN_ACCESSORS = [
  CheckboxControlValueAccessor,
  RangeValueAccessor,
  NumberValueAccessor,
  SelectControlValueAccessor,
  SelectMultipleControlValueAccessor,
  RadioControlValueAccessor,
];

In the upcoming sections we are going to explore the internals of some of the built-in value accessors.

`SelectValueAccessor`

We can use this value accessor in 2 ways: by using either [value] or [ngValue].

Using `<option [value]="primitiveValue">`

The primitiveValue argument, as its name implies, can't be something else than a primitive value. If you'd like to bind an object, [ngValue] should be your choice.

Each <option> will set its value to primitiveValue.

@Input('value')
set value(value: any) {
  this._setElementValue(value);
}

_setElementValue(value: string): void {
  this._renderer.setProperty(this._element.nativeElement, 'value', value);
}

ng-run Example.

Using `<option [ngValue]="primitiveOrNonPrimitiveValue">`

Unlike [value], [ngValue] can take both primitive and non-primitive as arguments.

It will set the value of the <option> tag depending on the value provided to [ngValue].

@Input('ngValue')
  set ngValue(value: any) {
    if (this._select == null) return;
    this._select._optionMap.set(this.id, value);
    this._setElementValue(_buildValueString(this.id, value));
    this._select.writeValue(this._select.value);
}

/* ... */

function _buildValueString(id: string | null, value: any): string {
  if (id == null) return `${value}`;
  if (value && typeof value === 'object') value = 'Object';
  return `${id}: ${value}`.slice(0, 50);
}

We can see that if we pass an object, the value will be something like '1: Object'. If we pass a primitive value, like the name of a city, the will be: 0: 'NY'

It is important to notice that when you change the value of the <select>(by using FormControl.setValue(arg)), if arg is an object, you must make sure it is the same object that you've passed to <option [ngValue]="arg"></option>. That's because, by default, SelectControlValueAccessor.writeValue(obj), it will use the === to identify the selected option.

writeValue(value: any): void {
    this.value = value;
    const id: string|null = this._getOptionId(value); // <---- Here!
    if (id == null) {
      this._renderer.setProperty(this._elementRef.nativeElement, 'selectedIndex', -1);
    }
    const valueString = _buildValueString(id, value);
    this._renderer.setProperty(this._elementRef.nativeElement, 'value', valueString);
}

_getOptionId(value: any): string|null {
  for (const id of Array.from(this._optionMap.keys())) {
    if (this._compareWith(this._optionMap.get(id), value)) return id;
  }

  return null;
}

Where _compareWith looks like this(by default):

return a === b || typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b);

Here's a StackBlitz example with a custom _compareWith function:

compareWith(existing, toCheckAgainst) {
  if (!toCheckAgainst) {
    return false;
  }
  return existing.id === toCheckAgainst.id;
}

<!-- 
  1) Try without '[compareWith]="compareWith"'
  2) select another option(`B`, or `C`)
  3) click `change`

  You should not see the value updated inside the `<select>`
  and that is because the default impl. of `compareWith` will compare the values with `===`
-->
<select
  #s="ngModel"
  [ngModel]="selectedItem"
  [compareWith]="compareWith"
>
  <option
    *ngFor="let item of items"
    [ngValue]="item"
  >
    {{item.name}}
  </option>
</select>

<br><br>

<button (click)="s.control.setValue({ id: '1', name: 'A' })">change</button>

Here is the test case for such behavior.

`SelectMultipleValueAccessor`

Each option is tracked(added to the internal _optionMap property), because

when change event occurs on the <select>, the value accessor needs to provide the right values(the value provided to [value] or [ngValue] in <option>) to the model; this can be achieved with iterating over the selected options(event.target.selectedOptions) and retrieve their values from _optionMap.

  // _ - the select element
  this.onChange = (_: any) => {
    const selected: Array<any> = [];
    if (_.hasOwnProperty('selectedOptions')) {
      const options: HTMLCollection = _.selectedOptions;
      for (let i = 0; i < options.length; i++) {
        const opt: any = options.item(i);
        const val: any = this._getOptionValue(opt.value);
        selected.push(val);
      }
    }

    this.value = selected;
    fn(selected);
  };

when value of the FormControl bound to the <select> element is changed programmatically(FormControl.setValue()), it needs to somehow determine which of the existing options match with the new provided values

  writeValue(value: any): void {
    this.value = value;
    let optionSelectedStateSetter: (opt: ɵNgSelectMultipleOption, o: any) => void;
    if (Array.isArray(value)) {
      // convert values to ids
      const ids = value.map((v) => this._getOptionId(v));
      optionSelectedStateSetter = (opt, o) => { opt._setSelected(ids.indexOf(o.toString()) > -1); };
    } else {
      optionSelectedStateSetter = (opt, o) => { opt._setSelected(false); };
    }
    this._optionMap.forEach(optionSelectedStateSetter);
  }

`RadioValueAccessor`

This value accessor keeps track of the radio buttons with the help of an internal service: RadioControlRegistry, which holds an array of [NgControl, RadioValueAccessor] pairs, where NgControl is a provider token that maps to one of the form-control-based directives: NgModel, FormControl, FormControlName.

Let's see how it actually works:

@Injectable()
export class RadioControlRegistry {
  private _accessors: any[] = [];

  add(control: NgControl, accessor: RadioControlValueAccessor) {
    this._accessors.push([control, accessor]);
  }

  remove(accessor: RadioControlValueAccessor) {
    for (let i = this._accessors.length - 1; i >= 0; --i) {
      if (this._accessors[i][1] === accessor) {
        this._accessors.splice(i, 1);
        return;
      }
    }
  }

  select(accessor: RadioControlValueAccessor) {
    this._accessors.forEach((c) => {
      if (this._isSameGroup(c, accessor) && c[1] !== accessor) {
        c[1].fireUncheck(accessor.value);
      }
    });
  }

  private _isSameGroup(
      controlPair: [NgControl, RadioControlValueAccessor],
      accessor: RadioControlValueAccessor): boolean {
    if (!controlPair[0].control) return false;
    return controlPair[0]._parent === accessor._control._parent &&
        controlPair[1].name === accessor.name;
  }
}

Keep your eyes on the RadioControlRegistry._isSameGroup method.

Let's narrow it down with a simpler example:

<form>
  <input ngModel name="option" value="value1" type="radio"> <!-- #1 NgModel._parent = the top-level `FormGroup` which results from `<form>` -->

  <ng-container ngModelGroup="foo">
    <input ngModel name="option" value="value1" type="radio"> <!-- #2 NgModel._parent = the sub-group `FormGroup` which results from `ngModelGroup` -->
  </ng-container>
</form>

Note that both radio buttons have the same value!

The RadioControlRegistry._accessors array would look like this:

[
  NgControl(-> NgModel) /* #1 */, RadioControlValueAccessor,
  NgControl(-> NgModel) /* #2 */, RadioControlValueAccessor,
]

When the user clicks on the first radio button, this method from RadioControlRegistry will be executed:

select(accessor: RadioControlValueAccessor) {
  this._accessors.forEach((c) => {
    if (this._isSameGroup(c, accessor) && c[1] !== accessor) {
      c[1].fireUncheck(accessor.value);
    }
  });
}

where accessor will be the RadioControlValueAccessor that belongs to the first radio button.

Here is once again the _isSameGroup method:

private _isSameGroup(
    controlPair: [NgControl, RadioControlValueAccessor],
    accessor: RadioControlValueAccessor): boolean {
  if (!controlPair[0].control) return false;
  return controlPair[0]._parent === accessor._control._parent &&
      controlPair[1].name === accessor.name;
}

controlPair[0]._parent === accessor._control._parent is what prevents the first radio button from affecting the second one.

With the following example, if we click on the second button, the first one will be marked as checked.

<form>
  <input ngModel name="option" value="value1" type="radio">

  <input ngModel name="option" value="value1" type="radio">
</form>

That's because out of N radio buttons with the same name and value attributes, only one can be marked as checked. In this case, it is the last one that fulfills these conditions:

this._isSameGroup(c, accessor) && c[1] !== accessor

where accessor is the RadioControlValueAccessor of the selected radio button.

ng-run Example.

Back to Contents

A better understanding of the `AbstractControl` tree

Throughout the article you might have noticed the phrase AbstractControl tree. Remember that AbstractControl is an abstract class and its concrete implementations are FormControl, FormGroup and FormArray.

In order to make things more intuitive, we can visualize their connections as a tree structure.

For instance, this

new FormGroup({
  name: new FormControl(''),
  address: new FormGroup({
    city: new FormControl(''),
    street: new FormControl(''),
  }),
});

can be pictured as follows:

   FG
  /  \
 FC  FG
    /  \
   FC  FC

Using the above diagram we are going to understand how the tree is altered by common AbstractControl actions, such as reset(), submit(), markAsDirty().

I'd recommend reading Base entities before continuing on.

`_pendingDirty`, `_pendingValue`, `_pendingChange`

These private properties of the AbstractControl class are details that you might not have to be concerned about. However, they play a significant role regarding the AbstractControl tree's effectiveness.

These properties are encountered in the context of a FormControl because their values depend on the values that are sent from the view(from the ControlValueAccessor).

`_pendingChange`

This property indicates whether or not the user has changed the FormControl's value.

Suppose you have an <input ngModel name="name" type="text"> and the user types in it. As soon as that happens, the ControlValueAccessor's onChange function will be invoked. The function that has been assigned to onChange looks as follows:

function setUpViewChangePipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnChange((newValue: any) => {
    control._pendingValue = newValue;
    control._pendingChange = true;
    control._pendingDirty = true;

    if (control.updateOn === 'change') updateControl(control, dir);
  });
}

control._pendingChange = true marks that the user has visibly interacted with the <input>.

Why is this useful anyway? It is because you can set the event on which the AbstractControl updates itself(it defaults to change).

You can se the update strategy through _updateOn property: _updateOn: 'change'|'blur'|'submit';

With this mind, what would happen if the FormControl has the update strategy set to blur, and the blur event occurs in the view, without the user typing anything in the <input>? In this case, _pendingChange prevents the tree from being redundantly traversed.

function setUpBlurPipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnTouched(() => {
    /* ... */
    if (control.updateOn === 'blur' && control._pendingChange) updateControl(control, dir);
    /* ... */
  });
}

Had the user typed anything in the <input>, the control._pendingChange would've been set to true. As a result, the FormControl and its ancestors would've been updated when the blur event had occurred.

`_pendingDirty`

A FormControl is considered dirty if the user has changed its value in the UI.

function setUpViewChangePipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnChange((newValue: any) => {
    /* ... */
    control._pendingChange = true;
    control._pendingDirty = true;

    if (control.updateOn === 'change') updateControl(control, dir);
  });
}

function updateControl(control: FormControl, dir: NgControl): void {
  if (control._pendingDirty) control.markAsDirty();
  /* ... */
}

The callback registered in with dir.valueAccessor !.registerOnChange(cb) will be invoked by the ControlValueAccessor(which resides in the view layer) whenever the value the UI changed.

The AbstractControl.markedAsDirty implementation looks like this:

markAsDirty(opts: {onlySelf?: boolean} = {}): void {
  (this as{pristine: boolean}).pristine = false;

  if (this._parent && !opts.onlySelf) {
    this._parent.markAsDirty(opts);
  }
}

So, if a FormControl is marked as dirty(due to UI change), its ancestors will be updated accordingly(in this case, they will be marked as dirty).

   FG (3)
  /  \
 FC  FG (2)
    /  \
   FC  FC (1)

(1).parent = (2)
(2).parent = (3)
(3).parent = null(root)

Assuming (1) a FormControl bound to an <input> and the user has just typed in it, the above method will be invoked from the updateControl function: control.markAsDirty(), where control is (1). This will propagate up to the root, the order being this: (1) -> (2) -> (3). Thus, the entire tree will be marked as dirty!

There is also an option to solely mark (1) as dirty: (1).markedAsDirty({ onlySelf: true }).

Now you be wondering, what's the need of _pendingDirty, if the control's dirtiness will be changed as soon as the user types something in? This is because the default strategy defaults to change, but it can be changed to something else like blur or submit.

For example, here's what happens when the blur event occurs in the view:

function setUpBlurPipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnTouched(() => {
    /* ... */
    if (control.updateOn === 'blur' && control._pendingChange) updateControl(control, dir);
    /* ... */
  });
}

`_pendingValue`

You can think of the property as being the freshest value of a FormControl.

Its value is set when the ControlValueAccessor.onChange is invoked, where ControlValueAccessor.onChange does this:

function setUpViewChangePipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnChange((newValue: any) => {
    control._pendingValue = newValue;

    /* ... */

    if (control.updateOn === 'change') updateControl(control, dir);
  });
}

function updateControl(control: FormControl, dir: NgControl): void {
  if (control._pendingDirty) control.markAsDirty();
  control.setValue(control._pendingValue, {emitModelToViewChange: false});
  dir.viewToModelUpdate(control._pendingValue);
  control._pendingChange = false;
}

However, what is the difference between _pendingValue and value? _pendingValue is the most recent value, whereas value is the value that is visible to the AbstractControl tree. The value is not always equal to _pendingValue as the FormControl might have a different update strategy than change. Of course, the view layer can hold the most recent value, but it doesn't mean that the model layer can.

For example, if the FormControl's update strategy is set to submit, the model's value(FormControl.value) won't be equal to _pendingValue(which is the value that reflects the view) until the submit event occurs.

`AbstractControl.setValue()` and `AbstractControl.patchValue()`

// {FormGroup|FormArray}.setValue
setValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}):
    void {
  this._checkAllValuesPresent(value);
  Object.keys(value).forEach(name => {
    this._throwIfControlMissing(name);
    this.controls[name].setValue(value[name], {onlySelf: true, emitEvent: options.emitEvent});
  });
  this.updateValueAndValidity(options);
}

// {FormGroup|FormArray}.patchValue
patchValue(value: {[key: string]: any}, options: {onlySelf?: boolean, emitEvent?: boolean} = {}):
    void {
  Object.keys(value).forEach(name => {
    if (this.controls[name]) {
      this.controls[name].patchValue(value[name], {onlySelf: true, emitEvent: options.emitEvent});
    }
  });
  this.updateValueAndValidity(options);
}

AbstractControl.setValue will require you to provide a value for all the existing controls, whereas AbstractControl.patchValue will allow you to provide values for any of the existing controls.

{FormGroup|FormArray}.setValue will first check if you provided an object which contains of all the existing controls, then it will check if you provided any redundant controls(controls that are not among the existing ones)

When calling setValue/patchValue, if AbstractControl is FormControl, it will first update the FormControl instance, then its ancestors. Otherwise, it will first update its descendants, then its ancestors.

Updating the ancestors can be avoided with { onlySelf: true } passed as the second argument.

Here's once again the first example:

const fg = new FormGroup({
  name: new FormControl(''),
  address: new FormGroup({
    city: new FormControl(''),
    street: new FormControl(''),
  }),
});

   FG (4)
  /  \
 FC  FG (3) - address 
    /  \
   FC  FC
   (1) (2)

After performing

fg.get('address').setValue({ city: 'city', street: 'street' })

It will first update (1) and (2), then it will update the value and validity of their container(3) and then it will finally update its ancestors.

`patchValue` example

const c = new FormControl('');
const c2 = new FormControl('');
const a = new FormArray([c, c2]);

a.patchValue(['andrei']);
console.log(a.value) // ['andrei', '']

`setValue` example

const c1 = new FormControl('c1');
const c2 = new FormControl('c2');

const a = new FormArray([c1, c2]);

a.setValue(['c1-updated', 'c2-updated', 'c3']); // Error: Cannot find form control at index 2
a.setValue(['c1-updated']); // Error: Must supply a value for form control at index: 1

a.setValue(['c1-updated', 'c2-updated']);

console.log(a.value); // ["c1-updated", "c2-updated"]

What happens with the `AbstractControl` tree on submit?

Note: Only FormGroupDirective and NgForm can call onSubmit.

onSubmit($event) {
  (this as{submitted: boolean}).submitted = true;
  syncPendingControls(this.form, this.directives);
  this.ngSubmit.emit($event);
  return false;
}

Some AbstractControl instances might have set the option updateOn differently. Therefore, if one FormControl has the updateOn option set to submit, it means that its value and UI status(dirty, untouched etc...) will only be updated when the submit event occurs. This is what syncPendingControls() does.

// FormControl
_syncPendingControls(): boolean {
  if (this.updateOn === 'submit') {
    if (this._pendingDirty) this.markAsDirty();
    if (this._pendingTouched) this.markAsTouched();
    if (this._pendingChange) {
      this.setValue(this._pendingValue, {onlySelf: true, emitModelToViewChange: false});
      return true;
    }
  }
  return false;
}

// FormArray - FormGroup works in a very similar fashion
_syncPendingControls(): boolean {
    let subtreeUpdated = this.controls.reduce((updated: boolean, child: AbstractControl) => {
      return child._syncPendingControls() ? true : updated;
    }, false);
    if (subtreeUpdated) this.updateValueAndValidity({onlySelf: true});
    return subtreeUpdated;
  }

Consider this example:

this.form = this.fb.group({ name: this.fb.control('', { updateOn: 'submit' }) });

this.form.valueChanges.subscribe(console.warn);

When having a view like this

<form [formGroup]="form" (ngSubmit)="onSubmit()">
  <input [formControl]="form.get('name')" type="text">
  <button type="submit">Submit</button>
</form>

you get the same values every time the submit event occurs, whereas with this view

<form [formGroup]="form" (ngSubmit)="onSubmit()">
  <input formControlName="name" type="text">

  <br><br>
  <button type="submit">Submit</button>
</form>

you get the values only once, when the submit event occurs

That's because of the way FormControlName directives work inside a FormGroupDirective. A FormGroupDirective will keep track of FormControlName directives with the help of directives property. When the submit event occurs, each FormControlName will set the _pendingChange property of their bound FormControl to false.

directives.forEach(dir => {
  const control = dir.control as FormControl;
  if (control.updateOn === 'submit' && control._pendingChange) {
    /* ... */
    control._pendingChange = false;
  }
});

FormControl._pendingChange is set to true every time the change event occurs in the UI.

function setUpViewChangePipeline(control: FormControl, dir: NgControl): void {
  dir.valueAccessor !.registerOnChange((newValue: any) => {
    control._pendingValue = newValue;
    control._pendingChange = true;
    control._pendingDirty = true;

    if (control.updateOn === 'change') updateControl(control, dir);
  });
}

You can find more about _pendingChange here.

ng-run Example.

Retrieving `AbstractControl`s from the tree

const fg = new FormGroup({
  name: new FormControl(''),
  address: new FormGroup({
    city: new FormControl(''),
    street: new FormControl(''),
  }),
});

There are a couple of ways to retrieve an AbstractControl.

If the AbstractControl you want to retrieve is a direct descendant of a form control container(fg in this case), you can do this:

fg.controls[nameOfCtrl];

// In our example
fg.controls['name']
fg.controls['address']

However, if the AbstractControl is a few levels deep, you might find it annoying to write such things:

fg.controls['address'].controls['city']

You can use the AbstractControl.get() method instead

fg.get('address.city')

// Or

fg.get(['address', 'street'])

AbstractControl.get() will internally call a function _find which will traverse the tree downwards based on the path provided.


function _find(control: AbstractControl, path: Array<string|number>| string, delimiter: string) {
  if (path == null) return null;

  if (!(path instanceof Array)) {
    path = (<string>path).split(delimiter);
  }
  if (path instanceof Array && (path.length === 0)) return null;

  return (<Array<string|number>>path).reduce((v: AbstractControl | null, name) => {
    if (v instanceof FormGroup) {
      return v.controls.hasOwnProperty(name as string) ? v.controls[name] : null;
    }

    if (v instanceof FormArray) {
      return v.at(<number>name) || null;
    }

    return null;
  }, control);
}

As you might have noticed, if fg had been a FormArray instance, you could've retrieved its descendants by specifying an index, as opposed to a property name(like you'd do with FormGroup)

fg.get('1.city');

// Or

fg.get(['1', 'city']);

AbstractControl.updateValueAndValidity()

updateValueAndValidity(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
  this._setInitialStatus();
  this._updateValue();

  if (this.enabled) {
    this._cancelExistingSubscription();
    (this as{errors: ValidationErrors | null}).errors = this._runValidator(); // Sync validators
    (this as{status: string}).status = this._calculateStatus(); // VALID | INVALID | PENDING | DISABLED

    if (this.status === VALID || this.status === PENDING) {
      this._runAsyncValidator(opts.emitEvent);
    }
  }

  if (opts.emitEvent !== false) {
    (this.valueChanges as EventEmitter<any>).emit(this.value);
    (this.statusChanges as EventEmitter<string>).emit(this.status);
  }

  if (this._parent && !opts.onlySelf) {
    this._parent.updateValueAndValidity(opts);
  }
}

As shown above, this method is responsible for multiple things:

1) updating the current AbstractControl's value
2) running validators(sync & async)
3) calculating status based on what validators return
4) emitting the new value and the new status to the subscribers(unless emitEvent = false)
5) repeating 1-4 for the parent(unless onlySelf = true)

const fg = new FormGroup({
  name: new FormControl(''),
  address: new FormGroup({
    city: new FormControl(''),
    street: new FormControl(''),
  }),
});

   FG (3)
  /  \
 FC  FG (2)
    /  \
   FC  FC (1)

(1) - fg.get('address.street')
(2) - fg.get('address')
(3) - fg

As soon as you do (1).setValue('new value'), (1).updateValueAndValidity() will be invoked.

setValue(value: any, options: {
  onlySelf?: boolean,
  emitEvent?: boolean,
  emitModelToViewChange?: boolean,
  emitViewToModelChange?: boolean
} = {}): void {
  (this as{value: any}).value = this._pendingValue = value;
  if (this._onChange.length && options.emitModelToViewChange !== false) {
    this._onChange.forEach(
        (changeFn) => changeFn(this.value, options.emitViewToModelChange !== false));
  }
  this.updateValueAndValidity(options);
}

After (1) has been updated, (2) will be updated and so on.. until the root is reached.

Disabling/enabling `AbstractControl`s

An AbstractControl can be disabled/enabled from the model. The change can be seen in the view with the help of ControlValueAccessor.setDisabledState:

export function setUpControl(control: FormControl, dir: NgControl): void {
  /* ... */

  if (dir.valueAccessor !.setDisabledState) {
    control.registerOnDisabledChange(
        (isDisabled: boolean) => { dir.valueAccessor !.setDisabledState !(isDisabled); });
  }

  /* ... */
}

When disabling an AbstractControl instance you can choose not to update its ancestors by using this.control.disable({ onlySelf: true }). This might be the case when a FormControl might be part of the a FormGroup and because of this control being invalid, the entire FormGroup is marked as invalid.

const fg = this.fb.group({
  name: this.fb.control('', Validators.required),
  age: '',
  city: this.fb.control('', Validators.required)
});


fg.controls['name'].disable();
fg.controls['city'].disable({ onlySelf: true });

console.log(fg.valid) // false

Had we omitted { onlySelf: true }, the entire form group(fg) would've been valid(fg.valid === true).

disable(opts: {onlySelf?: boolean, emitEvent?: boolean} = {}): void {
  // If parent has been marked artificially dirty we don't want to re-calculate the
  // parent's dirtiness based on the children.
  const skipPristineCheck = this._parentMarkedDirty(opts.onlySelf);

  (this as{status: string}).status = DISABLED;
  (this as{errors: ValidationErrors | null}).errors = null;
  this._forEachChild(
      (control: AbstractControl) => { control.disable({...opts, onlySelf: true}); });
  this._updateValue();

  if (opts.emitEvent !== false) {
    (this.valueChanges as EventEmitter<any>).emit(this.value);
    (this.statusChanges as EventEmitter<string>).emit(this.status);
  }

  // Will update the value, validity, dirtiness, and touch status
  this._updateAncestors({...opts, skipPristineCheck});
  this._onDisabledChange.forEach((changeFn) => changeFn(true));
}

private _updateAncestors(
    opts: {onlySelf?: boolean, emitEvent?: boolean, skipPristineCheck?: boolean}) {
  if (this._parent && !opts.onlySelf) {
    this._parent.updateValueAndValidity(opts);
    if (!opts.skipPristineCheck) {
      this._parent._updatePristine();
    }
    this._parent._updateTouched();
  }
}

When an AbstractControl is disabled, its validators won't run and its errors will be marked as null and its children are also going to be disabled.

If a parent has been marked artificially dirty(dirtiness is not determined by its children: manually doing {FormGroup|FormArray}.markAsDirty), there is no need to recalculate the parent's dirtiness based on the children because they don't have any effect on the parent:

this.form = this.fb.group({
  name: this.fb.control({ value: 'andrei', disabled: false }),
  age: this.fb.control(''),
});

const nameCtrl = this.form.controls['name'];

// Now, its ancestors will be marked as dirty as well
// In this case, there is only one `FormGroup`(this.form)
nameCtrl.markAsDirty();

nameCtrl.disable();

// Now, `this.form` will be marked as `pristine`, because 
// the child that influenced the parent's dirtiness is disabled

Also, if a form-control-container(FormGroup or FormArray) is disabled, its value will the value collected from all its descendants, regardless of their disabled value:

const g = new FormGroup({
  name: new FormControl('name'),
  address: new FormGroup({
    city: new FormControl('city'),
    street: new FormControl('street'),
  }),
});

g.get('address.city').disable();
g.controls['name'].disable();

console.log(g.value);
/* 
{
  "address": {
    "street": "street"
  }
}
*/

g.disable();
console.log(g.value)
/* 
{
  "name": "name",
  "address": {
    "city": "city",
    "address": "address"
  }
}

The reason behind this is the way AbstractControl.disable() works. Starting from the current AbstractControl it will first disable all its descendants, then collect their value. For example, here is how a FormArray would accumulate the values from its descendants:

_updateValue(): void {
  (this as{value: any}).value =
      this.controls.filter((control) => control.enabled || this.disabled)
          .map((control) => control.value);
}

The control.enabled || this.disabled expression allows us to get the value, even though the child control might be disabled.

However, if the container is not disabled and the child control is, its value won't be taken into account.

If you still want to get the form value, including the disabled controls you can use {FormGroup|FormArray}.getRawValue():

// FormArray.getRawValue()
getRawValue(): any[] {
  return this.controls.map((control: AbstractControl) => {
    return control instanceof FormControl ? control.value : (<any>control).getRawValue();
  });
}

How are CSS classes added depending on AbstractControl's status ?

CSS classes(ng-valid, ng-pristine, ng-touched etc) are added with the help of NgControlStatus directive, which is automatically bound to a form control element when using ngModel, formControl, formControlName.

Additionally, NgControlStatusGroup is added to the form group(<form>, formGroupName, formGroup, ngModelGroup, formArrayName).

Both NgControlStatus and NgControlStatusGroup will be updated when change detection occurs.

export class AbstractControlStatus {
  private _cd: AbstractControlDirective;

  constructor(cd: AbstractControlDirective) { this._cd = cd; }

  get ngClassUntouched(): boolean { return this._cd.control ? this._cd.control.untouched : false; }
  get ngClassTouched(): boolean { return this._cd.control ? this._cd.control.touched : false; }
  get ngClassPristine(): boolean { return this._cd.control ? this._cd.control.pristine : false; }
  get ngClassDirty(): boolean { return this._cd.control ? this._cd.control.dirty : false; }
  get ngClassValid(): boolean { return this._cd.control ? this._cd.control.valid : false; }
  get ngClassInvalid(): boolean { return this._cd.control ? this._cd.control.invalid : false; }
  get ngClassPending(): boolean { return this._cd.control ? this._cd.control.pending : false; }
}

export const ngControlStatusHost = {
  '[class.ng-untouched]': 'ngClassUntouched',
  '[class.ng-touched]': 'ngClassTouched',
  '[class.ng-pristine]': 'ngClassPristine',
  '[class.ng-dirty]': 'ngClassDirty',
  '[class.ng-valid]': 'ngClassValid',
  '[class.ng-invalid]': 'ngClassInvalid',
  '[class.ng-pending]': 'ngClassPending',
};

@Directive({selector: '[formControlName],[ngModel],[formControl]', host: ngControlStatusHost})
export class NgControlStatus extends AbstractControlStatus {
  constructor(@Self() cd: NgControl) { super(cd); }
}

With that in mind you can add your custom css class depending on form control's(or form-control-container's) validity or user interaction status by using a custom directive

constructor (private ngControlStatus: NgControlStatus) { }

@HostBinding('[class.card__price--incorrect]') this.ngControlStatus.ngClassInvalid();

Note: in order for this to work, your element(or component), besides the above directive, must include one of these form-control-based directives: [formControlName],[ngModel],[formControl]

Back to Contents

Conclusion

I hope this article has clarified some concepts and emphasized how powerful this package can be.

Thanks for reading!

Photo by O12 on Unsplash.

Exploring the HttpClientModule in Angular

Andrei Gatej — Mon, 30 Dec 2019 22:11:10 +0000

In this post, we are going to understand how the HttpClientModule actually works behind the scenes and find answers to some questions that might have arisen while using this module.

Note: This article is based on Angular 8.2.x.

Content

Setting up
- Installing Angular on your machine
- StackBlitz
What is HttpClientModule?
Let's start exploring 🚧
- Let's explore HttpXhrBackend
How can a request be canceled?
How can interceptors retry requests?
Why is it sometimes necessary to clone the request object inside an interceptor?
Why is it recommended to load the HttpClientModule only once in AppModule or CoreModule?
How can interceptors be completely bypassed?
- TLDR;
- Detailed Explanation
What is the difference between setHeaders and headers?
- setHeaders
- headers
What's the magic behind HttpHeaders?
What about HttpClientJsonpModule?
Conclusion

Setting up

My favorite way to understand how things really work is by using the debugger while having the source code in my text editor so that I can explore and make assumptions easily.

Installing Angular on your machine

git clone -b 8.2.x --single-branch https://github.com/angular/angular.git

StackBlitz

You can find a StackBlitz demo here.

We are going to use it throughout the article in order to get a better understanding of how entities are connecting with each other.

What is HttpClientModule?

The HttpClientModule is a service module provided by Angular that allows us to perform HTTP requests and easily manipulate those requests and their responses. It is called a service module because it only instantiates services and does not export any components, directives or pipes.

Back to content.

Let's start exploring 🚧

Once in the StackBlitz project:

open the dev tools
head over to token.interceptor.ts(CTRL + P) and put a breakpoint next to the console.warn()
refresh the StackBlitz browser

Now, you should see something like this:

By clicking on the anonymous function from client.ts, you are now in the HttpClient class, which is the one you usually inject in your services.

As you might have expected, this class comprises the methods for the well-known HTTP verbs.

export class HttpClient {
    constructor (private handler: HttpHandler) { }

    /* ... Method overloads ... */
    request(first: string | HttpRequest<any>, url?: string, options: {/* ... */}): Observable<any> {
        /* ... */
    }

    /* ... Method overloads ... */
    delete(url: string, options: {/* ... */}): Observable<any> {
        return this.request<any>('DELETE', url, options as any);
    }

    /* ... Method overloads ... */
    get(url: string, options: {/* ... */}): Observable<any> {
        return this.request<any>('GET', url, options as any);
    }

    /* ... Method overloads ... */
    post(url: string, body: any | null, options: {/* ... */}): Observable<any> {
        return this.request<any>('POST', url, addBody(options, body));
    }

    /* ... Method overloads ... */
    put(url: string, body: any | null, options: {/* ... */}): Observable<any> {
        return this.request<any>('PUT', url, addBody(options, body));
    }
}

I'd kindly recommend switching over to your text editor and start exploring this HttpClient.request method a little.

Continuing on, put a breakpoint on the line 492 and refresh the browser. The most interesting part is just about to begin!

At this point, we can't step into this.handler.handle() because the observable is just being built and has no subscribers yet. So, we must manually set a breakpoint inside the handle method.

To do so, switch over to your text editor and scroll up to the constructor.
The HttpHandler is a DI token that maps to HttpInterceptingHandler.

Here's a list of all providers:

@NgModule({
    /* ... */

    providers: [
        HttpClient,
        { provide: HttpHandler, useClass: HttpInterceptingHandler },
        HttpXhrBackend,
        { provide: HttpBackend, useExisting: HttpXhrBackend },
        BrowserXhr,
        { provide: XhrFactory, useExisting: BrowserXhr },
    ],
})
export class HttpClientModule {
}

What's left to do is to go into HttpInterceptingHandler class and set a breakpoint inside the handle method.

After successufully identifying its location, switch back to your dev tools, add your breakpoint and resume the execution!

BarInterceptor is provided in app.module

Here we are able to grab all the interceptors by injecting the HTTP_INTERCEPTOR(a multi-provider token) inside our method.

The next step consists of creating the injectors chain.

But first, let's have a quick look at HttpInterceptorHandler:

export class HttpInterceptorHandler implements HttpHandler {
    constructor(private next: HttpHandler, private interceptor: HttpInterceptor) { }

    handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
        return this.interceptor.intercept(req, this.next);
    }
}

I like to think of this chain as a linked list that is built starting off from the tail node.

In order to get a better overview of this, I'd suggest that you keep resuming the execution until you reach line 42, while paying attention to what's going on in the Scope tab.

Now, after the chain has been built, we can go through the list starting off from the head node by stepping into the handle function from line 42.

Here's how this linked list could look like:

Judging by the image above, we can tell that every next.handle() returns an observable.
What this means is that every interceptor can add custom behavior to the returned observable. Those changes will propagate in the precedent interceptors in the chain.

Before going any further, let's focus our attention on this.backend. Where does it come from? If you take a look at the constructor, you should see that is provided by HttpBackend, which maps to HttpXhrBackend(if not sure why, check what this module provides).

Let's explore `HttpXhrBackend`

Setting some breakpoints here and there will definitely lead to a better understanding! :)

export class HttpXhrBackend implements HttpBackend {
  constructor(private xhrFactory: XhrFactory) {}

  handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
    // Everything happens on Observable subscription.
    return new Observable((observer: Observer<HttpEvent<any>>) => {
      const xhr = this.xhrFactory.build();

        /* ... Setting up the headers ... */
        /* ... Setting up the response type & serializing the body ... */

      // partialFromXhr extracts the HttpHeaderResponse from the current XMLHttpRequest
      // state, and memoizes it into headerResponse.
      const partialFromXhr = (): HttpHeaderResponse => { /* ... */ };

      // First up is the load event, which represents a response being fully available.
      const onLoad = () => { /* ... */ };

      const onError = (error: ProgressEvent) => { /* ... */ };

      xhr.addEventListener('load', onLoad);
      xhr.addEventListener('error', onError);

      // Fire the request, and notify the event stream that it was fired.
      xhr.send(reqBody !);
      observer.next({type: HttpEventType.Sent});

      // This is the return from the Observable function, which is the
      // request cancellation handler.
      return () => {
        xhr.removeEventListener('error', onError);
        xhr.removeEventListener('load', onLoad);
        xhr.abort();
      };
    });
  }
}

The first thing that leaps to the eye is the handle() method, which is also the last method called in the interceptor chain because it sits in the tail node. It is also responsible for dispatching the request to the backend.

partialFromXhr - extracts the HttpHeaderResponse from the current XMLHttpRequest and memoizes it; this object needs to be computed only once can be used in multiple places. For example, it used in the onLoad and onError events
onLoad - the callback function triggered when the response is fully available; it also parses and validates the body of the response

const onLoad = () => {
  // Read response state from the memoized partial data.
  let { headers, status, statusText, url } = partialFromXhr();

  // The body will be read out if present.
  let body: any | null = null;

  let ok = status >= 200 && status < 300;

  /* ... Parse body and check its validity ... */

  if (ok) {
      // A successful response is delivered on the event stream.
      observer.next(new HttpResponse({
          body,
          headers,
          status,
          statusText,
          url: url || undefined,
      }));
      // The full body has been received and delivered, no further events
      // are possible. This request is complete.
      observer.complete();
  } else {
      // An unsuccessful request is delivered on the error channel.
      observer.error(new HttpErrorResponse({
          // The error in this case is the response body (error from the server).
          error: body,
          headers,
          status,
          statusText,
          url: url || undefined,
      }));
  }
}

onError - the callback function called when a network error occurred during the request

const onError = (error: ProgressEvent) => {
  const {url} = partialFromXhr();
  const res = new HttpErrorResponse({
    error,
    status: xhr.status || 0,
    statusText: xhr.statusText || 'Unknown Error',
    url: url || undefined,
  });
  observer.error(res);
};

Lastly, it is important to mention that the returned observable from HttpXhrBackend.handle() will dispatch the request when we subscribe to one of the HttpClient's methods(get, post etc). This means that HttpXhrBackend.handle() returns a cold observable which can be subscribed to by using concatMap:

this.httpClient.get(url).subscribe() -> of(req).pipe(concatMap(req => this.handler.handle))

The callback returned from the observable

return () => {
  xhr.removeEventListener('error', onError);
  xhr.removeEventListener('load', onLoad);
  xhr.abort();
};

will be invoked when the observable stops emitting values. That is, when an error or a complete notification occurs.

onComplete

const obsBE$ = new Observable(obs => {
  timer(1000)
    .subscribe(() => {
      obs.next({ response: { data: ['foo', 'bar'] } });

      // Stop receiving values!
      obs.complete();
    })

    return () => {
      console.warn("I've had enough values!");
    }
});

obsBE$.subscribe(console.log)
/* 
-->
response
I've had enough values!
*/

onError

const be$ = new Observable(o => {
  o.next('foo');

  return () => {
    console.warn('NO MORE VALUES!');
  }
});

be$
 .pipe(
    flatMap(v => throwError('foo')),
 )
  .subscribe(null, console.error)
/* 
-->
foo
NO MORE VALUES
*/

Back to content

How can a request be canceled?

A common case is the typeahead feature:

this.keyPressed
    .pipe(
        debounceTime(300),
        switchMap(v => this.http.get(url + '?key=' + v))
    )

It is advised to do things this way. The reason is due to switchMap's magic, which will unsubscribe from the inner observable to handle the next emitted value.

const src = new Observable(obs => {
  obs.next('src 1');
  obs.next('src 2');

  setTimeout(() => {
    obs.next('src 3');
    obs.complete(); 
  }, 1000);

  return () => {
    console.log('called on unsubscription')
  };
});

of(1, 2)
  .pipe(
    switchMap(() => src)
  )
  .subscribe(console.log)

/* 
src 1
src 2
called on unsubscription ---> unsubscribed from because the next value(`2`) kicked in
src 1
src 2
src 3
called on unsubscription ---> completion
*/

1 is emitted and while we are waiting for the inner observable to complete, another value, 2, comes straight away and will make switchMap unsubscribe from the current inner observable which in turn will invoke the returned function from the observable.

Here is what is going on inside the function returned from the observable that dispatches the request(found in HttpXhrBackend.handle):

return () => {
    /* Skipped some lines for brevity... */

    xhr.removeEventListener('error', onError);
    xhr.removeEventListener('load', onLoad);

    // Finally, abort the in-flight request.
    xhr.abort();
}

Thus, we can infer that if the observable that made the request is unsubscribed from, the above callback will be invoked.

Back to content

How can interceptors retry requests?

A token interceptor might look like this:

intercept (req: HttpRequest<any>, next: HttpHandler) {
  /* ... Attach token and all that good stuff ... */

  return next.handle()
    .pipe(
      catchError(err => {
        if (err instanceof HttpErrorResponse && err.status === 401) {
          return this.handle401Error(req, next)
        }

        // Simply propagate the error to other interceptors or to the consumer
        return throwError(err);
      })
    )
}

private handle401Error (req: HttpRequest<any>, next: HttpHandler) {
  return this.authService.refreshToken()
    .pipe(
      tap(token => this.authService.setToken(token)),
      map(token => this.attachToken(req, token))
      switchMap(req => next.handle(req))
    )
}

private attachToken(req: HttpRequest<any>, token: string): HttpRequest<any> {
  return req.clone({ setHeaders: { 'x-access-token': token } })
}

The retry logic can be achieved with switchMap(() => next.handle(req)).

If we reach the code inside catchError, it means that the consumer will unsubscribe from the observable(the one that is returned from HttpXhrBackend.handle).
This will allow us to re-subscribe to that observable, which will cause the request to be sent again as well as the interceptors that follow this interceptor to run their intercept function again.

Let's narrow it down to a simpler example:

const obsBE$ = new Observable(obs => {
  timer(1000)
    .subscribe(() => {
      // console.log('%c [OBSERVABLE]', 'color: red;');

      obs.next({ response: { data: ['foo', 'bar'] } });

      // Stop receiving values!
      obs.complete();
    })

    return () => {
      console.warn("I've had enough values!");
    }
});

// Composing interceptors the chain
const obsI1$ = obsBE$
  .pipe(
    tap(() => console.log('%c [i1]', 'color: blue;')),
    map(r => ({ ...r, i1: 'intercepted by i1!' }))
  );

let retryCnt = 0;
const obsI2$ = obsI1$
  .pipe(
    tap(() => console.log('%c [i2]', 'color: green;')),
    map(r => { 
      if (++retryCnt <=3) {
        throw new Error('err!') 
      }

      return r;
    }),
    catchError((err, caught) => {
      return getRefreshToken()
        .pipe(
          switchMap(() => /* obsI2$ */caught),
        )
    })
  );

const obsI3$ = obsI2$
  .pipe(
    tap(() => console.log('%c [i3]', 'color: orange;')),
    map(r => ({ ...r, i3: 'intercepted by i3!' }))
  );

function getRefreshToken () {
  return timer(1500)
    .pipe(q
      map(() => ({ token: 'TOKEN HERE' })),
    );
}

function get () {
  return obsI3$
}

get()
  .subscribe(console.log)

/* 
-->
[i1]
[i2]
I've had enough values!
[i1]
[i2]
I've had enough values!
[i1]
[i2]
I've had enough values!
[i1]
[i2]
[i3]
{
  "response": {
    "data": [
      "foo",
      "bar"
    ]
  },
  "i1": "intercepted by i1!",
  "i3": "intercepted by i3!"
}
I've had enough values!
*/

StackBlitz

This is, in my view, the effect of next.handle() inside each interceptor(Image here). Imagine that instead of const obsI3$ = obsI2$ we would have something like this:

// Interceptor Nr.2
const next = {
  handle(req) {
    /* ... Some logic here ... */

    return of({ response: '' })
  }
}

const obsI3$ = next.handle(req)
  .pipe(
    map(r => ({ ...r, i3: 'this is interceptor 3!!' })),
    /* ... */
  )

obsI3$ will now be the observable returned by next.handle() which means it can add now its own custom behavior and if something goes wrong, it can reinvoke the source observable.

When using interceptors you would want to retry the request by using switchMap(() => next.handle(req)(as it is done in the first code snippet), because, besides the each interceptor's returned observable, you would also want to run their logic that sits inside their intercept() function.

From this line switchMap(() => /* obsI2$ */caught) we can see that catchError can have a second argument, caught, which is the source observable.(More on this here).

Back to content

Why is it sometimes necessary to clone the request object inside an interceptor?

The process of adding the JWT token to your request might look like this:

if (token) {
  request = request.clone({
    setHeaders: { [this.AuthHeader]: token },
  });
}

return next.handle(request)

The most important reason would be immutability. You wouldn't want to mutate the request object from multiple places. Thus, every interceptor should configure the request independently.
The cloned request would eventually be passed to the next interceptor in the chain.

Back to content

Why is it recommended to load the HttpClientModule only once in AppModule or CoreModule?

A lazy-loaded module A will create its own child injector which will resolve the providers from that module. This means that the providers provided inside A and those provided by modules imported by A will be scoped to module A.

Importing HttpClientModule in A will result in only applying the interceptors that are provided inside A, excluding anything that is up in the injector tree. This is because HttpClientModule comes with its own providers which, as mentioned above, will be scoped to A.

             { provide: HttpHandler, useClass: ... }
  AppModule {    /
    imports: [  /
      HttpClientModule
    ]
  }
                  { provide: HttpHandler, useClass: HttpInterceptingHandler } <- where interceptors are gathered
  FeatureModule { /  <- lazy-loaded                  |
    imports: [   /                                   |
      HttpClientModule <------------------           |
    ]                                     |          |
                                          |          |
    declarations: [FeatureComponent]       <------------------------
    providers: [                                     |              |
                                                    /               |
      { provide: HTTP_INTERCEPTORS, useClass: FeatInterceptor_1 },  |
      { provide: HTTP_INTERCEPTORS, useClass: FeatInterceptor_2 }   |
    ]                                      ------------------------>
  }                                       |
                                          | httpClient.get()
  FeatureComponent {                      |
    constructor (private httpClient: HttpClient) { }
  }

If HttpClientModule was not imported in A, it would look up the injector tree until it finds the needed providers(in this case, it would be in AppModule). This also means that any interceptors provided in A will be excluded.

Back to content

How can interceptors be completely bypassed?

TLDR;

Make sure that HttpHandler maps to HttpXhrBackend:

@NgModule({
  imports: [
    /* ... */
    HttpClientModule,
    /* ... */
  ],
  declarations: [ /* ... */ ],
  providers: [
    /* ... */
    {
      provide: HttpHandler,
      useExisting: HttpXhrBackend,
    },
    /* ... */
  ]
})
export class AppModule { }

Detailed Explanation

It is recommended to first explore the HttpClientModule.

Whenever you do something like HttpClient.get()(or any other HTTP verb), the HttpClient.request() method will be eventually called. In this method, this line will be reached:

const events$: Observable<HttpEvent<any>> =
        of (req).pipe(concatMap((req: HttpRequest<any>) => this.handler.handle(req)));

Let's see how this.handler is retrieved:

@Injectable()
export class HttpClient {
  constructor(private handler: HttpHandler) {}

  /* ... */
}

If we take a look at HttpClientModule's providers,

@NgModule({
    /* ... */

    providers: [
        HttpClient,
        { provide: HttpHandler, useClass: HttpInterceptingHandler },
        HttpXhrBackend,
        { provide: HttpBackend, useExisting: HttpXhrBackend },
        BrowserXhr,
        { provide: XhrFactory, useExisting: BrowserXhr },
    ],
})
export class HttpClientModule {
}

we can tell that HttpHandler maps to HttpInterceptingHandler:

@Injectable()
export class HttpInterceptingHandler implements HttpHandler {
  private chain: HttpHandler|null = null;

  constructor(private backend: HttpBackend, private injector: Injector) {}

  handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
    if (this.chain === null) {
      const interceptors = this.injector.get(HTTP_INTERCEPTORS, []);
      this.chain = interceptors.reduceRight(
          (next, interceptor) => new HttpInterceptorHandler(next, interceptor), this.backend);
    }
    return this.chain.handle(req);
  }
}

HttpInterceptingHandler constructs the interceptor chain, which will in the end allow us to apply all the registered interceptors to the request.

We can also see that HttpInterceptingHandler implements HttpHandler:

export abstract class HttpHandler {
  abstract handle(req: HttpRequest<any>): Observable<HttpEvent<any>>;
}

HttpHandler is implemented by HttpBackend

export abstract class HttpBackend implements HttpHandler {
  abstract handle(req: HttpRequest<any>): Observable<HttpEvent<any>>;
}

HttpBackend is implemented by HttpXhrBackend, which will eventually send the request to the server(More on this here).

@Injectable()
export class HttpXhrBackend implements HttpBackend {
  constructor(private xhrFactory: XhrFactory) {}

  handle(req: HttpRequest<any>): Observable<HttpEvent<any>> {
    /* ... */
  }
}

As you can see, both HttpInterceptingHandler and HttpXhrBackend will have to implement the handle() method.
Consequently, the solution to this problem would be to make HttpHandler map to HttpXhrBackend.

@NgModule({
  imports: [
    /* ... */
    HttpClientModule,
    /* ... */
  ],
  declarations: [ /* ... */ ],
  providers: [
    /* ... */
    {
      provide: HttpHandler,
      useExisting: HttpXhrBackend,
    },
    /* ... */
  ]
})
export class AppModule { }

Back to content

What is the difference between `setHeaders` and `headers`?

`setHeaders`

req = req.clone({
  setHeaders: { foo: 'bar' },
})

With setHeaders, we can append the provided headers to the existing ones.

`headers`

req = req.clone({
  setHeaders: { foo: 'bar' },
})

With headers(an instance of HttpHeaders), we can override the existing headers.

Here is the excerpt from the sources:

// Headers and params may be appended to if `setHeaders` or
// `setParams` are used.
let headers = update.headers || this.headers;
let params = update.params || this.params;

// Check whether the caller has asked to add headers.
if (update.setHeaders !== undefined) {
  // Set every requested header.
  headers =
      Object.keys(update.setHeaders)
          .reduce((headers, name) => headers.set(name, update.setHeaders ![name]), headers);
}

Note: The same goes for setParams & params;.

Back to content

What's the magic behind `HttpHeaders`?

HttpHeaders is a class that allows us to manipulate(perform CRUD operations on) headers for our requests.

Have a look at this example:

const headers = new HttpHeaders({
  foo: 'foo',
  bar: 'bar',
});

const newHeaders = headers
  .append('name', 'andrei')
  .set('city', 'tgv')
  .delete('foo')
  .has('abcd');

The magic about this is that it will only initialize the headers(key-value pairs) when they are actually needed. That is, when you want to query for their current state(HttpHeaders.forEach(), HttpHeaders.get() etc...).

Here's how the constructor looks like:

constructor(headers?: string|{[name: string]: string | string[]}) {
  if (!headers) {
    this.headers = new Map<string, string[]>();
  } else if (typeof headers === 'string') {
    this.lazyInit = () => { /* ... */ }
  } else {
    this.lazyInit = () => { /* ... */ }
  }
}

As we can see, the lazyInit function is initialized in the constructor of HttpHeaders.

As a result, in order to perform actions such as HttpHeaders.append, HttpHeaders.set or HttpHeaders.delete, which would eventually mutate the initial state that was provided to the constructor, there will be a clone created that will store the new actions(create -> set, update -> append, delete -> delete).
These stored actions will be merged with the initial state in the end.

Here's how the HttpHeaders.clone looks like:

// action
interface Update {
  name: string;
  value?: string|string[];
  op: 'a'|'s'|'d';
}

private clone(update: Update): HttpHeaders {
  const clone = new HttpHeaders();
  // Preserve the initialization across multiple clones
  clone.lazyInit =
      (!!this.lazyInit && this.lazyInit instanceof HttpHeaders) ? this.lazyInit : this;
  // Accumulate actions 
  clone.lazyUpdate = (this.lazyUpdate || []).concat([update]);
  return clone;
}

Let's understand this logic by using our initial example:

const headers = new HttpHeaders({
  foo: 'foo',
  bar: 'bar',
});
/* 
-->
h1.lazyInit = () => {
  // Initialize headers
}
*/

const newHeaders = headers
  .append('name', 'andrei')
  /* 
  -->
  // Creating a clone
  h2.lazyInit = h1 // Preserving the first `instance` across multiple clones
  h2.lazyUpdate = { "name": "name", "value": "andrei", "op": "a" }
  */
  .set('city', 'tgv')
  /* 
  -->
  // Creating a clone
  // h2.lazyInit = h1
  h3.lazyInit = h2.lazyInit // Preserving the first `instance` across multiple clones
  h3.lazyUpdate = [
    { "name": "name", "value": "andrei", "op": "a" }, // append
    { "name": "city", "value": "tgv", "op": "s" } // set
  ]
  */
  .delete('foo')
  /* 
  -->
  // Creating a clone
  // h3.lazyInit = h2.lazyInit
  h4.lazyInit = h3.lazyInit // Preserving the first `instance` across multiple clones
  h4.lazyUpdate = [
    { "name": "name", "value": "andrei", "op": "a" },
    { "name": "city", "value": "tgv", "op": "s" },
    { "name": "foo", "op": "d" }
  ]
  */
  .has('abcd');
  /* 
  -->
  Here is where the initialization takes place
  */

The merging process would look like this:

private init(): void {
  if (!!this.lazyInit) {
    if (this.lazyInit instanceof HttpHeaders) {
      this.copyFrom(this.lazyInit);
    } else {
      this.lazyInit();
    }
    this.lazyInit = null;
    if (!!this.lazyUpdate) {
      this.lazyUpdate.forEach(update => this.applyUpdate(update));
      this.lazyUpdate = null;
    }
  }
}

private copyFrom(other: HttpHeaders) {
  other.init();
  Array.from(other.headers.keys()).forEach(key => {
    this.headers.set(key, other.headers.get(key) !);
    this.normalizedNames.set(key, other.normalizedNames.get(key) !);
  });
}

The HttpHeaders.init() method is called when querying for the state of the headers(by using methods like HttpHeaders.get(), HttpHeaders.has())

In HttpHeaders.copyFrom(), other will be the first instance of HttpHeaders, which contains the initialization logic: lazyInit. Calling other.init() will eventually reach this part of the HttpHeaders.init(): this.lazyInit();. Here the initial state is created into the first instance.

We are then left with two other things to do:

1) copy the state of the first instance into this current instance(last clone); this is achieved in these lines from HttpHeaders.copyFrom():

Array.from(other.headers.keys()).forEach(key => {
  this.headers.set(key, other.headers.get(key) !);
  this.normalizedNames.set(key, other.normalizedNames.get(key) !);
});

2) apply the collected actions onto the copied state:

// HttpHeaders.init()
if (!!this.lazyUpdate) {
  this.lazyUpdate.forEach(update => this.applyUpdate(update));
  this.lazyUpdate = null;
}

Back to content

What about `HttpClientJsonpModule`?

JSONP is a way to solve the well-known CORS issue. It does so by treating the resource as a script file.

When we are requesting a resource with the script tag we can pass along a defined callback which the resource will eventually wrap the json response in. The callback will be called while the script is loading.

This module provides as a way to use JSONP without worrying too much about the aforementioned details.

Let's quickly explore it and see why it is awesome!

@NgModule({
  providers: [
    JsonpClientBackend,
    {provide: JsonpCallbackContext, useFactory: jsonpCallbackContext},
    {provide: HTTP_INTERCEPTORS, useClass: JsonpInterceptor, multi: true},
  ],
})
export class HttpClientJsonpModule {
}

JsonpCallbackContext maps to jsonpCallbackContext which will return either the window object or an empty object(used in a testing environment). The returned object is used to store the callback which will in the end be called by script.

It also provides an interceptor, namely JsonpInterceptor. What this interceptor does is that it makes sure that our request never reaches the HttpBackend(which will contain completely different logic) when the request method is JSONP.

@Injectable()
export class JsonpInterceptor {
  constructor(private jsonp: JsonpClientBackend) {}

  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    if (req.method === 'JSONP') {
      return this.jsonp.handle(req as HttpRequest<never>);
    }

    // Fall through for normal HTTP requests.
    return next.handle(req); // Next interceptor in the chain
  }
}

JsonpClientBackend is where the magic happens. It automatically generates a callback that will be called later by the script. It does so by replacing the JSONP_CALLBACK parameter value in the url with the newly generated callback name.

export class JsonpClientBackend implements HttpBackend {
  private nextCallback(): string { return `ng_jsonp_callback_${nextRequestId++}`; }

  /* ... */

  handle (/* ... */) {
    return new Observable<HttpEvent<any>>((observer: Observer<HttpEvent<any>>) => {
      /* ... */
      const callback = this.nextCallback();
      const url = req.urlWithParams.replace(/=JSONP_CALLBACK(&|$)/, `=${callback}$1`);
    });
  }
}

Then, it stores the callback function in the object returned by jsonpCallbackContext using the generated callback name.

this.callbackMap[callback] = (data?: any) => {
  delete this.callbackMap[callback];

  if (cancelled) {
    return;
  }

  body = data;
  finished = true;
};

It is important to notice once again that the above callback should be called before the script finished downloading. This way, we can determine whether the provided callback was called or not in case we decide to provide the callback name ourselves.
This is done when the script has finished loading:

// Inside `JsonpClientBackend.handle`
const onLoad = (event: Event) => {
    // Maybe due to `switchMap`
    if (cancelled) {
      return;
    }

    cleanup();

    // Was the callback called with the response?
    if (!finished) {
      // If not, send the error response to the stream

      return;
    }

    // If yes, sent the response to the stream - everything was successful
}

Back to content

Conclusion

I hope exploring this module was a fun adventure!

Thanks for reading!

Photo by Anton Repponen on Unsplash.

Special thanks to @wassimchegham and @pietrucha.

Angular: Dynamically configure an injector for dynamic views

Andrei Gatej — Mon, 04 Nov 2019 22:50:57 +0000

Imagine you are in a situation the requires you to work with complex views(host views, embedded views).

As if it wasn't enough...you might also want to change these views' parent injector at runtime.

Let's see an example:

app.module.ts

@NgModule({
 /* ... */
 providers: [
  {
   provide: FooToken,
   useValue: { message: 'default foo value' }
  },
 ],
})
export class AppModule { }

app.component.ts

@Component({
  selector: 'my-app',
  template: `
    <ng-container #vcr></ng-container>
  `,
  styleUrls: [ './app.component.css' ]
})
export class AppComponent  {
  @ViewChild('vcr', { static: true, read: ViewContainerRef })
  vcr: ViewContainerRef;

  ngAfterViewInit () {
    const compFactory = this.cfr.resolveComponentFactory(FooComp);

    this.vcr.createComponent(compFactory);
  }
}

foo.component.ts

@Component({
  selector: 'foo',
  template: `Foo!!`
})
export class FooComp {
  constructor (@Inject(FooToken) private fooToken) {
    console.log('[FOO]', this.fooToken)
  }
}

As you can see, this.fooToken will be the value defined in AppModule's injector: { message: 'default foo value' }.

However, now you want to change this behavior, maybe you want to alter the FooToken's value depending on a certain action.
Imagine you have multiple tabs and you would like to dynamically display some content, depending on which tab is active. Now, in this case, each tab will have its own component that will make use of the value provided by FooToken and this value can result from other condition.

Let's see how we can achieve this:

app.component.ts

/* ... */
ngAfterViewInit() {
    const compFactory = this.cfr.resolveComponentFactory(FooComp);

    const inj = Injector.create({
        providers: [
            {
                provide: FooToken,
                useValue: { message: this.getMessageOfCurrentTab() }
            }
        ]
    })

    this.vcr.createComponent(compFactory, 0, inj);
}

We're using Injector.create() to create a custom injector for the tab components.

You can read more about ViewContainerRef's API here.

Now, this.fooToken's value will depend on the returned value from this.getMessageOfCurrentTab().

Wrapping Up

Of course, this example is rather trivial, but I think knowing such things can come in handy in certain situations.

A similar example can be found in my dependency-injection-playground.

Thanks for reading!

Angular: ActivatedRoute does not update the child route data on route changes

Andrei Gatej — Mon, 04 Nov 2019 06:28:13 +0000

Nov 3 '19 Comments: 1 Answers: 3

I'm tying to get the child route data('layout') from parent component using ActivatedRoute. I have tried the following example and I'm able to get the data I'm looking for but only for one time. During child route changes, I don't see the updated 'layout' value.

Routes

const routes: Routes

…

Open Full Question

Angular: Understanding how interceptors act on HttpRequest and HttpResponse

Andrei Gatej — Sat, 12 Oct 2019 10:23:56 +0000

You can find a working example here.

Generalization

Assuming that a request will be intercepted by these interceptors:

@NgModule({
    /* ... */
    providers: [
        {
            provide: HTTP_INTERCEPTORS,
            useClass: Interceptor1
            multi: true,
        },
        {
            provide: HTTP_INTERCEPTORS,
            useClass: Interceptor2
            multi: true,
        },
        /* ... */
        {
            provide: HTTP_INTERCEPTORS,
            useClass: InterceptorN
            multi: true,
        }
    ]
    /* ... */
})

When you perform a request by using HttpClient, the provided interceptors will act symmetrically on the whole action(HttpRequest & HttpResponse).

This means that the actual request(HttpRequest) will be intercepted by the interceptors in this order:

INTERCEPTOR_1 -> INTERCEPTOR_2 -> INTERCEPTOR_3 -> ... -> INTERCEPTOR_n

whereas, the path of the response(HttpResponse) will be this:

INTERCEPTOR_n -> ... -> INTERCEPTOR_3 -> INTERCEPTOR_2 -> INTERCEPTOR_1

A practical example

Supposing you have these interceptors:

{ type: 0 } - the request has been dispatched to the backend

export class FooInterceptor implements HttpInterceptor {
  intercept (req: HttpRequest<any>, next: HttpHandler) {
    console.log('[FOO]: request! ')

    return next.handle(req)
      .pipe(
        // Skip `sent` event
        filter(e => e.type !== 0),
        tap((e) => console.log('[FOO]: response!', e)),
      );
  }
}

export class BarInterceptor implements HttpInterceptor {
  intercept (req: HttpRequest<any>, next: HttpHandler) {
    console.log('[BAR]: request! ')

    return next.handle(req)
      .pipe(
        // Skip `sent` event
        filter(e => e.type !== 0),
        tap((e) => console.log('[BAR]: response!', e)),
      );
  }
}

export class BazInterceptor implements HttpInterceptor {
  intercept (req: HttpRequest<any>, next: HttpHandler) {
    console.log('[BAZ]: request! ')

    return next.handle(req)
      .pipe(
        // Skip `sent` event
        filter(e => e.type !== 0),
        tap((e) => console.log('[BAZ]: response!', e)),
      );
  }
}

After dispatching an HTTP request, this will be printed to the console:

[FOO]: request!
[BAR]: request!
[BAZ]: request!

[BAZ]: response!
HttpResponse { … }

[BAR]: response!
HttpResponse { … }

[FOO]: response!
HttpResponse { … }

{userId: 1, id: 1, title: "delectus aut autem", completed: false…}

I hope you found this useful. Thanks for reading! :)

DEV Community: Andrei Gatej

React: beyond useEffect

Introduction

A quick note on what hooks really are

What you might already know about useEffect

What’s more to know about useEffect

Conclusion

References

How React uses pragmas to run tests conditionally

Introduction

What are pragmas and why are they useful?

An overview on React’s testing environment

What does writing a custom pragma actually involve?

Conclusion

Angular Router: empty paths, named outlets and a fix that came with Angular 11

UrlTree

The problem

The process of matching Routes with UrlSegmentGroups

The fix that came with Angular 11

Conclusion

Angular Router: Getting to know UrlTree, ActivatedRouteSnapshot and ActivatedRoute

What is UrlParser and why it is important

What is the difference between /() and ()?

Exercises

UrlTree, ActivatedRouteSnapshot and ActivatedRoute

When is UrlTree used ?

When a UrlTree is returned from a guard, it will result in a redirect operation

Router.navigateByUrl()

Router Directives

Automating my set-up on a fresh Ubuntu by using a bash script

Usage

How it works

Stack Overflow learnings and answers

Angular: Why RouterLink adds the input to the end of current URL in bracket

A thorough exploration of Angular Forms

Contents

Base entities

AbstractControl

FormControl

FormArray

FormGroup

AbstractControlDirective

AbstractFormGroupDirective

ControlValueAccessor

Connecting FormControl with ControlValueAccessor

Template Driven Forms and Reactive Forms

Template Driven Forms

NgModel

NgModelGroup

NgForm

Reactive Forms

FormControlDirective

FormGroupDirective

FormControlName

FormGroupName

FormArrayName

Validators

Usage of built-in Validators

Validators' Composition

Custom Validators

Dynamic Validators

Exploring built-in ControlValueAccessors

SelectValueAccessor

Using <option [value]="primitiveValue">

Using <option [ngValue]="primitiveOrNonPrimitiveValue">

SelectMultipleValueAccessor

RadioValueAccessor

A better understanding of the AbstractControl tree

_pendingDirty, _pendingValue, _pendingChange

_pendingChange

_pendingDirty

_pendingValue

AbstractControl.setValue() and AbstractControl.patchValue()

patchValue example

setValue example

What happens with the AbstractControl tree on submit?

Retrieving AbstractControls from the tree

AbstractControl.updateValueAndValidity()

Disabling/enabling AbstractControls

How are CSS classes added depending on AbstractControl's status ?

What you might already know about `useEffect`

What’s more to know about `useEffect`

The process of matching `Routes` with `UrlSegmentGroup`s

What is the difference between `/()` and `()`?

When a `UrlTree` is returned from a guard, it will result in a redirect operation

`Router.navigateByUrl()`

Connecting `FormControl` with `ControlValueAccessor`

Exploring built-in `ControlValueAccessor`s

`SelectValueAccessor`

Using `<option [value]="primitiveValue">`

Using `<option [ngValue]="primitiveOrNonPrimitiveValue">`

`SelectMultipleValueAccessor`

`RadioValueAccessor`

A better understanding of the `AbstractControl` tree

`_pendingDirty`, `_pendingValue`, `_pendingChange`

`_pendingChange`

`_pendingDirty`

`_pendingValue`

`AbstractControl.setValue()` and `AbstractControl.patchValue()`

`patchValue` example

`setValue` example

What happens with the `AbstractControl` tree on submit?

Retrieving `AbstractControl`s from the tree

Disabling/enabling `AbstractControl`s

Let's explore `HttpXhrBackend`

What is the difference between `setHeaders` and `headers`?

`setHeaders`

`headers`

What's the magic behind `HttpHeaders`?

What about `HttpClientJsonpModule`?