Forem: thomas

How Angular Dependency Injection works under the hood

thomas — Thu, 16 Nov 2023 13:23:11 +0000

Dependency Injection (DI) is one of the most beloved and powerful features of Angular, and it happens to be my personal favorite as well. Understanding and mastering it can elevate your Angular skills and grant you superpowers.
In this article, I will explain what Dependency Injection is and delve into how it operates within Angular to provide a profound understanding.

What is a Dependancy Injection

Let's start by examining an example that doesn't use Dependency Injection:

@Component({
   //...
})
export class AppComponent {
  service = new RootService();
}

In this example, we directly instantiate the RootService using the new keyword, resulting in a hardcoded dependency and a tight coupling between AppComponent and RootService. While this approach does work, it lacks flexibility, testability, and scalability in the long run, making it less maintainable.

Now, let's consider the same example using Dependency Injection, where you'll recognise a well-known Angular code snippet:

@Component({
   //...
})
export class AppComponent {
  service = inject(RootService);
// constructor(private service: RootService) {}
}

Notes: you can use either the constructor or the inject function, as both methods have the same underlying implementation.

As we can see, AppComponent is no longer directly responsible for instantiating RootService. Instead, it delegates this task to an external source, which is responsible for either returning an existing instance or creating a new instance of the requested service.

We can simplify the code for this external source, which might look like this:

export const inject = (searchClass: Class) => {
  const dependance = find(searchClass)
  if(dependance) {
    return dependance;
  } else {
    return new searchClass();
  }
}

In this example, AppComponent doesn't need to have knowledge about RootService. This reduces the coupling between classes and their dependencies, making the code more maintainable, testable, and reusable.

In Angular, this external source is referred to as an Injector. And its implementation can be compared to a dictionary of records. The structure of a record looks like this:

record:{
 //...
 [index]:{
   key: class RootService,
   value: {
    factory: ƒ RootService_Factory(t),
    value: {}
   }
 //...
}

The Injector stores information about all injectable classes, which includes anything with a decorator such as @Injectable, @Component, @Pipe, and @Directive.

Returning to the previous example, when AppComponent requests RootService, the Injector iterates over its records to locate the requested token. Once found, the Injector returns the value if it's not undefined, indicating that the service has already been instantiated. Otherwise, the Injector creates a new instance using the factory function.

As you can observe, the record is simply an object, and the value can be easily overridden. For example, if we write the following code:

@Component({
   //...
   providers: [{ provide: RootService, useClass: OtherService }]
})
export class AppComponent {
  service = inject(RootService);
}

The Injector will override the value property within the RootService record:

record:{
 //...
 [index]:{
   key: class RootService,
   value: {
    factory: ƒ OtherService_Factory(t),
    value: {}
   }
 //...
}

This means that when AppComponent requests RootService, the Injector will provide a new instance of OtherService.

Note: This example simplifies how Angular's Dependency Injection works, but it illustrates the underlying DI principle.

The next section delves into more advanced aspects, revealing the inner workings of Angular's DI system.

Angular Dependancy Injection

Angular has two categories of Injectors:

EnvironmentInjector: This category includes all global injectable classes provided through the router, modules, or using the providedIn: 'root' keyword.
NodeInjector: This category contains all local injectable classes found in each component or template.

It's important to note that each small piece of a view containing injectable classes (referred to as LView) has its own NodeInjector, and within this NodeInjector, we can locate all services provided within the component provider array or any directives used within that LView.

LView !== Component

Creation of EnvironmentInjector Tree

When we bootstrap the application, the bootstrapApplication function is called in our main.ts file. This function takes two parameters:

The root Component
A list of providers

bootstrapApplication(AppComponent, {
  providers: [GlobalService],
})

Under the hood, this function will create three EnvironmentInjectors chained together:

NullInjector: This is the end of the road. Its sole purpose is to throw an error: "NullInjectorError: No provider for …!!!"
PlatformInjector: It contains a list of tokens that inform Angular about the platform the application is running on, such as browser, server, web worker, etc.

Example: this is where the InjectionToken DOCUMENT is created. For instance, if you are on a browser, this token will return window.document, whereas on a server, Angular will build and provide a DOM using Domino. It's crucial to always work with the DOCUMENT token by injecting it instead of using window.document. This ensures compatibility if you ever need to render your application from a server.

import { DOCUMENT } from '@angular/common';

@Component()
export class FooComponent {
  document = inject(DOCUMENT) // ✅
  document = window.document // ❌
}

RootInjector: This is the most well-known of the three. It's where all our global services (injectables set as root) are stored.

Notes: If we refer back to the earlier example, the GlobalService instance will be located within this injector.

All three of these injectors are chained together.

Creation of NodeInjector Tree

In this section, we will explore examples that you likely encounter in your daily projects. The first part aims to provide a better understanding of how the NodeInjector tree is created. (The NodeInjectorTree is almost similar to the ComponentTree but not strictly identical.)

We will then see how Angular determines which dependencies to retrieve or create.

Note: In this article, we will not discuss modules since most applications are expected to transition to standalone. Furthermore, all new Angular applications will be set to standalone by default starting from v17.

Tree Creation

Let's examine how a NodeInjectorTree looks like. We'll begin with a very simple example: a Parent with one Child.

@Component({
  template: `<child />`,
  imports: [ChildComponent],
})
export class ParentComponent {}

@Component({})
export class ChildComponent {}

This results in the following tree:

Since ParentComponent and ChildComponent are annotated with @Component, it means they are injectable. Thus, each component is stored within its own NodeInjector as follows. It's important to note that ChildComponent can inject ParentComponent, but it cannot inject itself, as this would create a circular dependency.

Now, let's add another child to the parent:

@Component({
  template: `
    <child />
    <child />
   `,
  imports: [ChildComponent],
})
export class ParentComponent {}

@Component({})
export class ChildComponent {}

The structure of both trees remains similar.

However, let's encapsulate one child into a div with a directive on it.

@Directive({
  selector: '[foo]',
  standalone: true,
})
export class FooDirective {}

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ChildComponent, FooDirective],
  template: `
    <div foo>
      <child />
    </div>
    <child />
  `,
})
export class ParentComponent {}

Now, the InjectorTree begins to diverge from the ComponentTree. A new Injector has appeared. Since FooDirective is a type of @Directive, it means it's injectable, and the first ChildComponent can inject it.

From this example, we can see that a NodeInjector is not associated with a Component but with an LView (Logical View).

With these three examples, you have all you need to understand how the InjectorTree is built.

(Note: Routing and ActivatedRoute will be explained in a follow-up article.)

Now, let's explore different ways of providing an injectable service and how Angular locates the instance you are injecting.

Component provider

Within the component decorator, you have a property called providers that allows you to provide an Injectable class, as illustrated below:

@Component({
  template: `...`,
  providers: [MyComponentService],
})
export class MyComponent {}

The service provided inside the decorator will be stored within the records of the NodeInjector of MyComponent. Please note that providing your service does not instantiate it. A service is instantiated only when it is injected.

Let's now examine which instance is returned with two concrete examples:

Example 1:

@Component({
  template: `
    <child />
    <child />
   `,
  imports: [ChildComponent],
})
export class ParentComponent {}

@Component({
  providers: [MyService]
})
export class ChildComponent {
  myService = inject(MyService);
}

This results in the following NodeInjectorTree:

As we can see, MyService is present inside both ChildInjectors. When Angular creates the first ChildComponent class, it will request MyService from the DI system. The DI system will start by searching inside the record of ChildInjector, which looks like this:

record:{
 //...
 [index]:{
   key: class MyService,
   value: {
    factory: ƒ MyService_Factory(t),
    value: undefined
   }
 //...
}

Angular will iterate over all dictionary entries of the Injector to check if the key MyService is present. Since MyService is present inside this NodeInjector, it will then check if it has already been instantiated, which is not the case since the value is undefined. In this case, a new instance of MyService will be created and returned.

If the key wasn't present inside the record, the DI system will move to the next Injector until finding it or reaching the NullInjector, which will throw an error and terminate the application.

The same process will repeat for the second instance of ChildComponent. Angular will start searching inside its own NodeInjector, find the key inside the record, and since MyService has not been instantiated, a new instance will be created.

Example 2:

Now, let's provide MyService inside ParentComponent instead of inside ChildComponent.

@Component({
  providers: [MyService]
  template: `
    <child />
    <child />
   `,
  imports: [ChildComponent],
})
export class ParentComponent {}

@Component({})
export class ChildComponent {
  myService = inject(MyService);
}

Now, MyService is located inside the record of ParentInjector.

This time, when Angular creates the first ChildComponent, it won't find the key of MyService inside the record of ChildInjector. Angular will then move up to the next Injector, which is ParentInjector. The record of ParentInjector looks like this:

record:{
 //...
 [index]:{
   key: class MyService,
   value: {
    factory: ƒ MyService_Factory(t),
    value: undefined
   }
 //...
}

Since MyService has not been instantiated yet, a new instance will be created and returned.

However, things are different when the second ChildComponent is created. Angular will traverse the NodeInjectorTree until reaching ParentInjector. But this time, the ParentInjector looks like this:

record:{
 //...
 [index]:{
   key: class MyService,
   value: {
    factory: ƒ MyService_Factory(t),
    value: MyService {
      prop1: 'xxx'
      // ...
    }
   }
 //...
}

The value of MyService is no longer undefined. The DI System will return this instance to the second ChildComponent. This means that both ChildComponents are sharing the same instance of MyService, unlike in the previous example.

Note: If ParentComponent was injecting MyService, the same instance would be shared among all three components.

ProvidedIn: 'root'

The providedIn: 'root' is one of the most commonly used injectable designs within Angular applications, but not everyone fully understands the implications of these two words. This chapter aims to provide a clear explanation.

Let's create a very basic application with a parent and a child:

@Component({
  template: `<child />`,
  imports: [ChildComponent],
})
export class ParentComponent {}

@Component({})
export class ChildComponent {
  service = inject(RootService);
}

@Injectable({ providedIn: 'root' })
export class RootService {}

When we examine the NodeInjectorTree, we find that RootService is not present in any of the records. This is because Angular does not include it in any Injector until a component actually injects it.

Note: In the context of lazy-loaded routes, RootService may get tree-shaken and bundled outside the main bundle. This topic is beyond the scope of this article, but you can read more about it below.

Mastering Injectable Services: A Comprehensive Guide

thomas for Playful Programming Angular ・ Dec 19 '22

#angular

Now, when Angular creates ChildComponent, it searches for RootService starting from the ChildInjector and moving up the tree, eventually reaching the EnvironmentInjectorTree and more precisely, the RootInjector.

Note: The exact implementation is more complex, but for the sake of simplicity, we'll provide a high-level explanation here.

When the DI system reaches the RootInjector, it searches for the RootService key, similar to any other NodeInjector. However, it doesn't find it there either. Unlike NodeInjectors, before moving to the next EnvironmentInjector, it compares the scope of the Injector with the scope of the service being injected.

The code below is a portion of the get function of the RootInjector: (If you want to see the full function, you can go here)

let record: Record<T>|undefined|null = this.records.get(token);
if (record === undefined) {
  // No record, but maybe the token is scoped to this injector. Look for an injectable
  // def with a scope matching this injector.
  const def = couldBeInjectableType(token) && getInjectableDef(token);
  if (def && this.injectableDefInScope(def)) {
    // Found an injectable def and it's scoped to this injector. Pretend as if it was here
    // all along.
    record = makeRecord(injectableDefOrInjectorDefFactory(token), NOT_YET);
  } else {
    record = null;
  }
  this.records.set(token, record);
}

First, it attempts to retrieve the record of the searched token. If there is no record, it checks if the service has an InjectableDef (the providedIn property). If the service has one and if the scope matches the scope of the current EnvironmentInjector (root in our case), a new record is created and added to the Injector, then a new instance is returned.

The next time a component requests RootService, the record will be present, and the same instance will be returned.

Note: While less common, if you want to provide your service inside the PlatformInjector, you can set your Injectable to providedIn: 'platform'.

Warning: In practice, setting the providedIn: 'root' property for your Injectable service signifies that your service will be a singleton. However, if you provide your service within the providers property of one of your components, this service will be added to the record of the NodeInjector of that component. Let's see an example to better understand this:

@Component({})
export class ChildComponent {
  service = inject(RootService);
}

@Component({
  providers: [RootService]
})
export class FooComponent {
  service = inject(RootService);
}

@Component({
  template: `
    <child />
    <foo />
  `,
  imports: [ChildComponent, FooComponent],
})
export class ParentComponent {}

// injectable service
@Injectable({ providedIn: 'root' })
export class RootService {}

Here, we have a providedIn: 'root' RootService, which is injected inside both FooComponent and ChildComponent. However, we provide RootService inside the NodeInjector of FooComponent. This gives us the following graph:

ChildComponent will have an instance of the service located inside the RootInjector, whereas FooComponent will have the one from its own Injector. This can be misleading because by observing the service, one might assume that both components share the same global instance, which is not the case in this example.

In summary, providedIn: 'root' is only an information for Angular to create a record inside RootInjector only and only if the service reach that point while searching for it inside the InjectorTree.

I really hope that the Dependency Injection System of Angular will no longer hold any secrets for you. You should now be able to harness its power to create exceptional applications and understand whether an instance of a service will be shared or unique.

You can expect me to write follow-up articles on the following subjects:

Dependency Injection inside Routed Components
Injection Flags: Host, Self, SkipSelf, and Optional
All the options for overriding within the DI: useClass, useValue, useFactory, useExisting

If you would like to learn about anything else, please don't hesitate to leave a comment.

If you want to improve your Angular skill, go check out Angular Challenges. It groups a set of challenges about Angular and its ecosystem.

You can find me on Twitter or Github. Don't hesitate to reach out to me if you have any questions.

On the road to Fine-Grained Change Detection

thomas — Wed, 01 Nov 2023 14:46:54 +0000

A pull request was recently merged and will be available in the upcoming major version v17. This pull request represents the first step towards fine-grained reactivity and signal-based components.

If you want to read more, click the pull request below:

perf(core): Update LView consumer to only mark component for check #52302

atscott posted on Oct 20, 2023

This commit updates the reactive template and host binding consumers to only mark their declaration components for refresh, but not parents/ancestors.

This also updates the AfterViewChecked hook to run when a component is refreshed during change detection but its host is not. It is reasonable to expect that the ngAfterViewChecked lifecycle hook will run when a signal updates and the component is refreshed. The hooks are typically run when the host is refreshed so without this change, the update to not mark ancestors dirty would have caused ngAfterViewChecked to not run.

resolves #14628 resolves #22646

resolves #34347 - this is not the direct request of the issue but generally forcing change detection to run is necessary only because a value was updated that needs to be synced to the DOM. Values that use signals will mark the component for check automatically so accessing the ChangeDetectorRef of a child is not necessary. The other part of this request was to avoid the need to "mark all views for checking since it wouldn't affect anything but itself". This is directly addressed by this PR - updating a signal that's read in the child view's template will not cause ancestors/"all views" to be refreshed.

View on GitHub

The goal of this change is to refresh ONLY the component where the change occurred, but there are a couple of requirements:

All your components need to use OnPush.
The change has to be triggered by a Signal.

Let's take a step back and explain why we need OnPush and Signals to benefit from local change detection.

How Change Detection Works

Angular employs Zone.js to detect changes and trigger a new render. Since Zone.js doesn't track where a change occurred, Angular performs a top-to-bottom rerender. This means that Angular refreshes the RootComponent down to all ChildComponents. This operation is fast but costly since Angular rerenders all components even if only a small change occurred.

Meanwhile, ChangeDetectionStrategy.OnPush was introduced to optimize the change detection cycle. When a component is marked for check, all its ancestors are also marked for check. Then Angular triggers a top-down cycle and only refreshes the marked components.

In v16, Angular introduced Signals, a new reactive API. This API allows Angular to precisely determine where a change is occurring. Angular can now identify which components need to be refreshed. A Signal marks the component as dirty but not its ancestors. When Angular performs its top-down change detection cycle, only that specific component will be refreshed.

Notes:

Angular still needs to perform a top-down change detection to maintain backward compatibility with previous versions and with components not using Signals, relying on Zone.js instead.
Currently, Angular cannot achieve more granularity than per-component because it might disrupt how non-signal components are refreshed. In the future, the goal is to be more granular, but it will never be as granular as the binding. Refer to the RFC for more details.

Conclusion:

Now you should understand why this change will benefit applications that leverage the use of Signals and OnPush.

Signals allow Angular to precisely pinpoint where the change occurred and mark only the affected component as dirty.
OnPush is necessary because Angular still requires a top-down change detection, and it only refreshes OnPush components when marked for check. All Default components will still be rerefreshed.

// Detect dark theme var iframe = document.getElementById('tweet-1721422293723754573-254'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1721422293723754573&theme=dark" }

Update your application to v17 and start using Signals, as this is just the beginning of how Signals can enhance your Angular application.

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Thanks to Enea for reviewing it.

Function calls inside template are dangerous!

thomas — Thu, 31 Aug 2023 18:39:48 +0000

The other day, one of my coworkers detected a strange behavior inside our application. When he added RouterLinkActive to a link, the application stopped rendering. However when the directive was removed, the application worked correctly.

Instead of immediately reading the solution, I created a challenge inside AngularChallenges for those who want to try resolving and understanding the source of the bug first. After that, you can come back to this article to compare your solution with mine and understand what went wrong.

To better understand the problem, below is a small reproduction of the issue:

interface MenuItem {
  path: string;
  name: string;
}

@Component({
  selector: 'app-nav',
  standalone: true,
  imports: [RouterLink, NgFor, RouterLinkActive],
  template: `
    <ng-container *ngFor="let menu of menus">
      <a
        [routerLink]="menu.path"
        [routerLinkActive]="isSelected"
          >
        {{ menu.name }}
      </a>
    </ng-container>
  `,
})
export class NavigationComponent {
  @Input() menus!: MenuItem[];
}

@Component({
  standalone: true,
  imports: [NavigationComponent, NgIf, AsyncPipe],
  template: `
    <ng-container *ngIf="info$ | async as info">
      <ng-container *ngIf="info !== null; else noInfo">
        <app-nav [menus]="getMenu(info)" />
      </ng-container>
    </ng-container>

    <ng-template #noInfo>
      <app-nav [menus]="getMenu('')" />
    </ng-template>
  `,
})
export class MainNavigationComponent {
  private fakeBackend = inject(FakeServiceService);

  readonly info$ = this.fakeBackend.getInfoFromBackend();

  getMenu(prop: string) {
    return [
      { path: '/foo', name: `Foo ${prop}` },
      { path: '/bar', name: `Bar ${prop}` },
    ];
  }
}

MainNavigationComponent will display NavigationComponent and pass a list of MenuItem as an argument depending on the return of an HTTP request. When our HTTP request returns, we call the getMenu function with an empty string if there is no info, or with info if it's not empty.

NavigationComponent will iterate over MenuItem and create a link for each item using RouterLink and RouterLinkActive for routing.

At first sight, this code seems correct, but applying RouterLinkActive to each link breaks the rendering with no errors in the console.

What could be happening? 🤯

To better understand the issue, let's break down RouterLinkActive with the code that is causing the infinite rendering loop:

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

@Directive({
  selector: '[fake]',
  standalone: true,
})
export class FakeRouterLinkActiveDirective {
  constructor(private readonly cdr: ChangeDetectorRef) {
    queueMicrotask(() => {
      this.cdr.markForCheck();
    });
  }
}

Inside RouterLinkActive, we call this.cdr.markForCheck() to mark our component as dirty. However, we make this function call within a different micro task. Once our current macro task ends, Angular will trigger a new change detection cycle within the following micro task.

Having this information, can you spot the issue now ?

Since Angular runs a new change detection cycle, the framework rechecks every binding, causing new function calls. This means that the getMenu function inside our MainNavigationComponent will be called again, and it returns a new instance of MenuItems.

But that's not all.

NavigationComponent iterates over the array using the NgFor directive. As a new instance of MenuItem is passed as an Input to the component, NgFor recreates its list. NgFor destroys all DOM elements inside the list and recreates them. This causes the recreation of the RouterLinkActive instance, leading to another round of change detection, and this will be infinite.

We can avoid this by using the trackBy function inside the NgFor directive. This function tracks one property on the element, and checks if that property still exists within the new array. NgFor will only DESTROY or CREATE an element if the property no longer exists or did not exist previously. Adding the trackBy function in our case will correct the issue of infinite re-rendering.

If you are always forgetting the trackBy function, I invite you to read this article.

Make TrackBy Easy to Use!

thomas for Playful Programming Angular ・ Jul 21 '23

#angular

However, even if the trackBy function resolves this error, creating a new instance of MenuItem at each change detection cycle is bad practice.

One way of avoiding this would be to create a menuItem class property, but this would create imperative code and lead to spaghetti code.

The best way is to take a more declarative approach. Let's see how to refactor the code in a more declarative way:

@Component({
  standalone: true,
  imports: [NavigationComponent, AsyncPipe],
  template: ` <app-nav [menus]="(menus$ | async) ?? []" /> `,
})
export class MainNavigationComponent {
  private fakeBackend = inject(FakeServiceService);

  readonly menus$ = this.fakeBackend
    .getInfoFromBackend()
    .pipe(map((info) => this.getMenu(info ?? '')));

  getMenu(prop: string) {
    return [
      { path: '/foo', name: `Foo ${prop}` },
      { path: '/bar', name: `Bar ${prop}` },
    ];
  }
}

Our menus$ property is now defined in a single place, and will update when getInfoFromBackend returns. menu$ will not get recomputed at each change detection cycle and only a single instance will be created during the entire lifetime of MainNavigationComponent. The code looks simpler, doesn't it ?

You have probably heard that calling functions inside templates is a bad practice, and in most cases, it is. While you can call a function to access nested properties of an object, that should be one of the only exceptions. Try to avoid calling functions inside your template bindings, or be sure to really understand what you are doing and all the side effects that can be created by this function call. When attempting to mutate data through a function call, it should trigger a warning inside your head. Most of the time, there is a better declarative approach to your problem. Declarative programming is a different state of mind, but you should aim for it. Persist, and your code will become clearer and simpler, and both your coworkers and your future self will thank you for that.

I hope this article sheds some light on the consequences of calling functions within template bindings.

Notes: In the future, Angular with "signal" will reduce that risk. With "signal" being memoized, it will save you from recreating new instances. 🔥

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

New input binding for NgComponentOutlet

thomas — Thu, 31 Aug 2023 18:39:13 +0000

In Angular, you can create dynamic components using the NgComponentOutlet directive. However when your component has inputs, it was cumbersome to pass them through. In version 16.2.0-next.4, a new feature has been introduced, allowing you to bind your inputs much more easily.

In this article, we will explore how to achieve input binding in previous versions of Angular and the new approach introduced in version 16.2.0-next.4. Additionally, we will demonstrate another method to create dynamic components.

Before v16.2.0-next.4

Prior to version 16.2.0-next.4, you had to create an injector to set up your inputs and inject it into your dynamic component to access them.

Let's look at an example to better understand this process.

First we need an InjectionToken for better type safety:

interface TitleInputs {
  title: string;
  subTitle: string;
}

const INPUTS = new InjectionToken<TitleInputs>('title inputs');

Now in our component we can create a custom injector to set up our inputs.

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgComponentOutlet],
  template: `
    <ng-template *ngComponentOutlet="template; injector: customInjector" />
  `,
})
export class AppComponent implements OnInit {
  template = OldTitleComponent;

  titleInputs = {
    title: 'Inputs for Component outlets',
    subTitle: `That's awesome`,
  };

  customInjector = Injector.create({
    providers: [{ provide: INPUTS, useValue: this.titleInputs }],
  });
}

Finally, in OldTitleComponent , we can inject our token to retrieve our inputs.

@Component({
  selector: 'app-title',
  standalone: true,
  template: `OldWay: {{ inputs.title }} {{ inputs.subTitle }}`,
})
export class OldTitleComponent {
  inputs = inject(INPUTS);
}

This solution doesn't feel very natural but there was no other way available at that time.

After v16.2.0-next.4

Now, since input binding has been implemented, we can simply pass our inputs object to our directive and retrieve our inputs using the @Input decorator, as we would expect it to be.
Let's see this in action.

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgComponentOutlet],
  template: `
    <ng-template *ngComponentOutlet="template; inputs: titleInputs" />
  `,
})
export class AppComponent implements OnInit {
  template = TitleComponent;

  titleInputs = {
    title: 'Inputs for Component outlets',
    subTitle: `That's awesome`,
  };
}

@Component({
  selector: 'app-title',
  standalone: true,
  template: `NewWay: {{ title }} {{ subTitle }}`,
})
export class TitleComponent{
  @Input() title!: string;
  @Input() subTitle?: string;
}

So much simpler, isn't it?

Moreover, if any inputs change inside the titleInputs object, TitleComponent will be notified. 👍

Note: Inputs binding is not typed. Anything can be pass to inputs property.

Using CreateComponent

In Angular, there's another API to dynamically create components. Instead of doing it inside the template, you can achieve it in the TypeScript part using the createComponent function.

@Component({
  selector: 'app-root',
  standalone: true,
  template: ``,
})
export class AppComponent implements OnInit {
  ref = inject(ViewContainerRef);
  envInjector = inject(EnvironmentInjector);

  ngOnInit(): void {
    const comp = this.ref.createComponent(TitleComponent, {
      environmentInjector: this.envInjector,
    });
    comp.setInput('title', 'Inputs with createComponent');
    comp.setInput('subTitle', 'Still works!');
  }
}

To bind inputs, you need to use the setInput function. While you could do comp.instance.title =...` , if your input change,TitleComponent` will not be notified.

Note: NgComponentOutlet is using createComponent and setInput under the hood. 😉

Enjoy creating dynamic component in an easier way !! 🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Share / ShareReplay / RefCount

thomas — Tue, 01 Aug 2023 11:32:07 +0000

share and ShareReplay are two RxJs operators that we always struggle to use correctly. We know that we can reach for them when we want to multicast a costly observable or cache a value that will be used at multiple places. But what are the key differences between both, and what is the refCount flag and how can we leverage its behavior?

In this article, I will try to explain them for you so that you will not need to ask this question again.

Example 1

I posted the following question on Twitter which unfortunately received zero responses. This really highlights the lack of understanding regarding share and shareReplay.

// Detect dark theme var iframe = document.getElementById('tweet-1683193488060416000-111'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1683193488060416000&theme=dark" }

The exercice looks like this:

@Component({
  selector: 'app-count',
  standalone: true,
  imports: [NgIf, AsyncPipe],
  template: `
    <ng-container *ngIf="flag"> {{ count1$ | async }} </ng-container>
    <ng-container *ngIf="!flag"> {{ count2$ | async }} </ng-container>
  `,
})
export class CountComponent implements OnInit {
  flag = true;

  readonly count$ = interval(1000).pipe(
    take(7),
    shareReplay({ bufferSize: 1, refCount: false }) // 👈 line: 15
  );

  readonly count1$ = this.count$.pipe(
    take(3),
    map((c) => `count1: ${c}`)
  );
  readonly count2$ = this.count$.pipe(
    take(3),
    map((c) => `count2: ${c}`)
  );

  ngOnInit(): void {
    setTimeout(() => {
      this.flag = false;
    }, 5500);
  }
}

Note: This code snippet is written using Angular, but the behavior of both operator is the same outside the framework.

When the flag is true, we subscribe to count1$ and after 3 emissions, the observable completes. Then after 5500ms, the flag is set to false and we subscribe to count2$ which also completes after 3 emissions. Both observables are chained with count$.

The goal is to predict the result displayed on the screen after 10s, depending on the operator used in line 15.

Let's start with the share operator.
The share operator will multicast each value emitted by the source observable, which means we won't re-execute the source observable for each new subscription.

Moreover, when the count of subscribers drops to 0, the source observable will be unsubscribed.

Inside this operator, we use a Subject as a connector between the source observable and the subscribers. This means that every late subscriber will NOT have access to the previously emitted data.

You should use this operator if you know that you will not use previously emitted data and are only interested in upcoming ones.

Solution

If we go back to our exemple:

count$ will be triggered when count1$ subscribes to it.
After count$ emits 3 values, count1$ completes due to the take(3) operator. Consequently count$ will also complete since the number of subscribers drops to 0 and the inner Subject will reset.
After 5500ms count2$ starts. It will subscribe to count$ and count$ will start emitting from the beginning.
Since we have a take(3) on the observable, the final answer is 3.

ShareReplay with refCount: true

Both share and shareReplay operators behave almost the same: ShareReplay use share under the hood. The crucial difference lies in the connector: shareReplay uses a ReplaySubject instead of a Subject. This distinction becomes significant when dealing with late subscribers, as they will have access to previously emitted data.

Another difference is the ability to toggle the refCount flag. When refCount=true, it allows unsuscribing from the source observable when the subscriber count drops to 0. The share operator's refCount flag is defaulted to true.

In this scenario with refCount set to true, the source observable will get unsubscribed when the subscriber count drops to 0.

Solution

If we go back to our exemple:

count$ will be triggered when count1$ subscribes to it.
After count$ emits 3 times, count1$ completes due to the take(3) operator. Consequently count$ will also complete since the number of subscribers drops to 0 and the refCount flag is set to true.
After 5500ms count2$ starts, it will subscribe to count$ again and count$ will start emitting from the beginning.
Since we have a take(3) on the observable, the final answer is 3. In this example, both share and shareReplay bahave exactly the same. However, we will see more examples below to understand the differences between them.

ShareReplay with refCount: false

As explained above, setting the refCount flag to false will keep the source observable alive even if the subscriber count drops to 0.

This is dangerous because if the source observable never completes, this can create memory leaks.

However in some cases, you may not want to re-execute the source observable if a new subscriber subscribes, such as in the case of an HTTP request.

Solution

If we go back to our exemple:

count$ will be triggered when count1$ subscribes to it.
After count$ emits 3 times, count1$ completes due to the take(3) operator, BUT count$ will NOT complete and continue to emit a value every 1s.
After 5500ms count2$ starts, it will subscribe to count$ and receive the last emitted value which is 4.
Since we have a take(3) on the observable, the final answer is 6.

Note: Since all observables completes, we don't have any memory leaks issues

Example 2

Let's take another example to better understand the difference between share and shareReplay. This distinction becomes more evident when we apply the operators to an observable that never completes, such as a BehaviorSubject.

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgIf, AsyncPipe],
  template: `
    <ng-container *ngIf="!flagFinalize">
      <ng-container> {{ count1$ | async }} </ng-container>
      <ng-container *ngIf="flag"> {{ count2$ | async }} </ng-container>
    </ng-container>
    <button (click)="flagFinalize = !flagFinalize">FINALIZE</button>
    <button (click)="subject.next(subject.value + 1)">INCREMENT</button>
  `,
})
export class AppComponent implements OnInit {
  flag = false;
  flagFinalize = false;

  subject = new BehaviorSubject(0);

  readonly count$ = this.subject.pipe(
    tap({
      next: (t) => console.log('I get next value of count', t),
      complete: () => console.log('complete count'),
      finalize: () => console.log('finalize count'),
    }),
    share() // 👈
  );

  readonly count1$ = this.count$.pipe(
    tap({
      next: (t) => console.log('I get next value of count1', t),
      complete: () => console.log('complete count1'),
      finalize: () => console.log('finalize count1'),
    }),
    map((c) => `count1: ${c}`)
  );
  readonly count2$ = this.count$.pipe(
    tap({
      next: (t) => console.log('I get next value count2', t),
      complete: () => console.log('complete count2'),
      finalize: () => console.log('finalize count2'),
    }),
    map((c) => `count2: ${c}`)
  );

  ngOnInit(): void {
    setTimeout(() => {
      this.flag = true;
    }, 1000);
  }
}

This time we are using a BehaviorSubject and we have an INCREMENT button to emit a value to the Subject.

Additionally, we have added a tap operator to log the next, complete and finalize events.

The FINALIZE button allows us to unsubscribe from the count1$ and count2$ observables.

Scenario

When the app is loaded, count1$ subscribes to count$, and after 1s count2$ also subscribes to count1$.

Next, we click once on the INCREMENT button, and finally we click on the FINALIZE button.

Before reading the article further, I invite you to try to guess what the behavior of this scenario will be with each operator. Once you are done, compare your ideas with the solution.

When count1$ subscribes to count$, the count$ observable will start emitting values and count1$ will receive the initial value 0.
In this scenario, count1$ doesn't complete so the number of subscribers will not drop to 0, and count$ will not complete either.
After 1s, count2$ starts subscribing to count$, but since we are using the share operator, the inner observable is a Subject which will not replay the previous emitted value. Therefore count2$ will not receive any value.
We now click on the INCREMENT button, and both count1$ and count2$will be notified with the value 1.
Finally we click on the FINALIZE button, and both count1$ and count2$ will get unsubscribed (due to the asyncPipe) and finalized. Since the share operator unsubscribes the source when all subscribers drop to 0, count$ will finalize as well.

ShareReplay with refCount: true

We replace the share operator with shareReplay({bufferSize: 1, refCount: true})

same behavior as previously
same thing
After 1s, count2$ starts subscribing to count$. However this time, count2$ gets the previous emitted value (0 in our case), because shareReplay uses a ReplaySubject as the connector. This is the significant difference between both operators

4 and 5 are identical since the refCount flag is set to true.

ShareReplay with refCount: false

1 to 4 is identical to the previous scenario, and all differences are seen in point 5 when we unsubscribe from the subscribers.

When we click on the FINALIZE button, count1$ and count2$ will be unsubscribed correctly due to the asyncPipe. However count$ will not finalize because shareReplay will not unsubscribe the inner source and count$ will continue to exist indefinitely, which might cause a memory leak.

Important note: If you have noticed, I said that this might cause a memory leak. If you lose the reference to your running observable, such as when destroying a component, a new count$ observable will be instantiated next time you initialize the particular component. This can lead to memory leaks.

In the above example, switching back the flag, count1$ and count2$ will resubscribe to the existing observable. ShareReplay with refCount set to false is useful when you don't want to re-execute a costly observable like an HTTP request. You can set your shared observable in a global service and inject it anywhere in your application. The instance will never be unsubscribed, but when new subscribers subscribe to the observable, they will use the existing instance.

Note: We often see the shorthand synthax replaySubject(1), which is the shorthand for replaySubject({bufferSize: 1, refCount: false}). So you need to be careful about using this synthax. You will more often reach for refCount set to true to avoid memory leak issues.

Example 3

In the last example, we will use a source observable that completes, similar to an HTTP request. To simplify the example, we will use the of operator.

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgIf, AsyncPipe],
  template: `
    <ng-container> {{ request1$ | async }} </ng-container>
    <ng-container *ngIf="flag"> {{ request2$ | async }} </ng-container>
  `,
})
export class AppComponent implements OnInit {
  flag = false;

  readonly http$ = of('trigger http request').pipe(
    tap({
      next: (t) => console.log('http response', t),
      complete: () => console.log('complete http'),
      finalize: () => console.log('finalize http'),
    }),
    share() // 👈
  );

  readonly request1$ = this.http$.pipe(
    tap({
      next: (t) => console.log('request1 response', t),
      complete: () => console.log('complete request1'),
      finalize: () => console.log('finalize request1'),
    }),
    map((c) => `request1: ${c}`)
  );
  readonly request2$ = this.http$.pipe(
    tap({
      next: (t) => console.log('request2 response', t),
      complete: () => console.log('complete request2'),
      finalize: () => console.log('finalize request2'),
    }),
    map((c) => `request2: ${c}`)
  );

  ngOnInit(): void {
    setTimeout(() => {
      this.flag = true;
    }, 1000);
  }
}

Scenario

When we load the component, we trigger a first HTTP request using the observable http$. After 1s, we want to get the result of the same request. To achieve this, we consider using either share or shareReplay operator to cache the result.

Same exercice as previously, I encourage you to think first before reading the solution below.

request1$ subscribes to http$ which triggers an HTTP call. Once the response comes back, the HTTP call completes, causing http$ and request1$ to complete as well.
After 1s, request2$ subscribes to http$ hoping to get the result of the same HTTP call. However, since share uses a Subject under the hood, nothing is cached, and http$ is re-executed, resulting in a new HTTP call.

ShareReplay

In this scenario, the refCount doesn't change the behavior since the source observable (http$) completes on its own, irrespective of the number of subscribers.

same as previously
After 1s, request2$ subscribes to http$ but this time, shareReplay uses a ReplaySubject as the connector, allowing it to store the last value emitted by http$. Therefore http$ doesn't need to be re-executed, and request2$ received the cached value without triggering a new HTTP call.

Note: Be careful when using shareReplay inside a global service behind a http call. Each new subscriber will receive the cached value and the HTTP request will NEVER fire again. As a result, your data will NEVER get refreshed.

Conclusion

In summary, shareReplay is useful in scenarios where you want to cache and replay the last emitted value of an observable, especially in situations like HTTP requests, to avoid unnecessary re-execution and improve performance. But be careful, this is useful inside a component scope, generally not within the global scope.

You need to think carefully about the refCount flag when using shareReplay on observables that don't complete on their own.

share is useful when you want to multicast a long-living observable and you don't need to access previously emitted data.

As you can see, understanding exactly how this two operators work under the hood can help you improve your application's performance.

I hope you now have a better understanding of the differences between share and shareReplay and the importance of the refCount flag. With this knowledge, you should be able to use them correctly and truly understand what is happening behind the scenes.

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Make TrackBy Easy to Use!

thomas — Fri, 21 Jul 2023 09:37:00 +0000

If you are an Angular user, you must have heard about the trackByfunction inside an *NgFor loop. If you have never heard of it, it’s not too late to learn about it.

The trackBy function lets Angular know how to identify items in an Array to refresh the DOM correctly when you update that array. Without trackBy, the entire DOM elements get deleted and added again. If you want to preserve your DOM from unnecessary re-rendering when adding, deleting or reordering list elements, use the trackBy function.

However adding this property to your NgFor directive requires a lot of boilerplate. You need to create a function that returns the property that identifies your list element and pass that function to the directive in your template.

interface Photo {
  id: string;
  url: string;
  name: string;
}

@Component({
  selector: 'list',
  standalone: true,
  imports: [NgFor],
  template: `
    <div *ngFor="let photo of photos; trackBy: trackById"> // 👈
      {{ photo.name }}
      <img [src]="photo.url" [alt]="photo.name" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListComponent {
  @Input() photos!: Photo[];

  trackById(index: number, photo: Photo) { // 👈
    return photo.id;
  }
}

Simplify the boilerplate

To simplify the boilerplate, we can create an additional directive that handles the instantiation of this trackById function.

@Directive({
  selector: '[ngForTrackById]', // 1
  standalone: true
})
export class NgForTrackByIdDirective<T extends { id: string | number }> {
  @Input() ngForOf!: NgIterable<T>; // 2

  private ngFor = inject(NgForOf<T>, { self: true }); // 3

  constructor() {
    this.ngFor.ngForTrackBy = (index: number, item: T) => item.id; // 4
  }
}

Let’s go though the code:

Line 1

We prefix our directive selector with ngFor , this way we can combine it with the NgFor directive like this:

<div *ngFor="let photo of photos; trackById"></div>

If you are not familiar with the shorthand syntax of structural directive, the above is the simplification of:

<ng-template ngFor let-photo [ngForOf]="photos" ngForTrackById"></ng-template>

We can now easily see why we need to prefix our directive with ngFor 😇

Line 2

The @Input is only useful for type checking. We need to obtain the type of the array to enforce strong type safety within our directive. If the type Photo doesn’t have an id property, and since the generic T extends id, we will get a Typescript error.

If we remove the id property from the type Photo, we will see the following error:

Line 3

The goal of the directive is to set the trackBy function of the built-in NgForDirective. Thus we need to access the current instance of the directive NgFor. Since we know that we are using the directive on the same VIEW element, we set the self flag to true. This means we are only going to look for the NgFor instance on this element.

<div *ngFor="let item of items; trackById"> 
   // ☝️ ------------------------- 👈
  <div *ngFor="let photo of photos; trackById"> 
       // ☝️ ------------------------- 👈

  </div>
</div>

If you want to use trackById outside an NgFor directive, the property ngFor inside your NgForTrackByIdDirective will be null even if you have something like this:

<div *ngFor="let photo of photos">
  <div ngFortrackById> // 👈 will not work
    //
  </div>
</div>

Note: If we don’t set any flags, or use a different flag such as the host flag, we will obtain the instance of the line above in the example provided. However, that is not the instance we want to work with.

Line 4

We instantiate the trackBy function of NgFor to track the id of our Photo list.

Result

Now, our code becomes:

@Component({
  selector: 'list',
  standalone: true,
  imports: [NgFor, NgForTrackByIdDirective], // 👈
  template: `
    <div *ngFor="let photo of photos; trackById"> // 👈
      {{ photo.name }}
      <img [src]="photo.url" [alt]="photo.name" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListComponent {
  @Input() photos!: Photo[];
}

But you may say this only works for objects with an id property. That’s true, which is why we can create a more general directive to accept any properties.

NgForTrackByPropDirective

The only small difference we need to apply to our directive is that we cannot set the trackBy function inside the constructor since it relies on an input property. To resolve this, we will create a setter:

@Directive({
  selector: '[ngForTrackByProp]',
  standalone: true
})
export class NgForTrackByPropDirective<T> {
  @Input() ngForOf!: NgIterable<T>;

  @Input()
  set ngForTrackByProp(ngForTrackBy: keyof T) { // setter
    this.ngFor.ngForTrackBy = (index: number, item: T) => item[ngForTrackBy];
  }

  private ngFor = inject(NgForOf<T>, { self: true });
}

This directive is type safe as well.

Simplify imports

Last but not least, we can simplify the import array by creating a module that imports both directive combined with NgFor

export const NgForTrackByDirective: Provider[] = [NgForTrackByIdDirective, NgForTrackByPropDirective];

@NgModule({
  imports: [NgFor, NgForTrackByDirective],
  exports: [NgFor, NgForTrackByDirective]
})
export class NgForTrackByModule {}

Now you are well-equipped and have no more excuses to forget the trackBy function or omit it due to boilerplate code.

Those two directives can be easily integrated into your project’s source code.

Enjoy using them! 🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Extending an existing NX generator

thomas — Mon, 10 Jul 2023 08:35:04 +0000

Nx provides a wide range of built-in tools that automatically generate code for you. These code generation tools are called generators in Nx. However, there may be instances where you need to generate code that is almost the same as the existing generator, but with some slight differences.

In Nx, it is easy to reuse a built-in generator and customize it to better suit your company’s needs. Since all generators are JS functions, overriding them becomes a child game.

In this article, I will explain how to generate the boilerplate code for a generator (thanks to another generator 😇). Then, we will extend the built-in @nx/angular:library generator and override the generated Jest and lint configurations. Often, we need to modify the library configuration file to better align with our company’s requirements. By creating this custom library generator, we can facilitate our team’s workflow by ensuring that all files are correctly set within the Nx monorepo.

This article provides a step-by-step explanation of the process.

Create a custom plugin:

First, to create your own generator, you need to install the package @nx/plugin by executing the following command:

npm i @nx/plugin -D

Once the package is installed, it provides access to 7 built-in generators.

The next step is to create a custom plugin that will serve as a container for all our future generators or executors.

To do this, open the Nx Console (if you don’t have it, I strongly recommend installing it as a plugin in VSCode or Webstorm). Then, click on the generate button and search for @nx/plugin:plugin.

By selecting this option, a new library called demo will be created inside your lib folder.

Create the boilerplate code of our generator.

Go back to the Nx Console and click on generate again. This time, search for @nx/plugin:generator.

This will create the necessary boilerplate code for your generator inside your demo/src/generators folder.

schema.d.ts contains the interface for your input schema. It defines the structure and types of the properties that can be set for your generator.
schema.json is defines how all the properties of your generator will be set and displayed within the Nx Console. (You can refer to the list of options available [here](https://nx.dev/plugins/recipes/generator-options#schema) to configure this file.)
generator.ts is where you will write the code for your generator.

Now that we have all the necessary files set up for our generator, we can proceed to start creating its functionality.

Creation of our generator:

In order to extend the default @nx/angular:library generator, we need to locate the generator function within the Nx GitHub source code (You can find it here). As you can see, the structure of the default generator is identical to ours.

Inside library.ts the libraryGenerator has been exported as a public API. We can simply use it to replicate what the Nx generator does, as shown below:

import { libraryGenerator } from '@nx/angular/generators';
import { Tree, formatFiles } from '@nx/devkit';
import { LibraryGeneratorSchema } from './schema';

export async function mylibraryGenerator(tree: Tree, options: LibraryGeneratorSchema) {
  await libraryGenerator(tree, options);

  await formatFiles(tree);
}

export default mylibraryGenerator;

Note: To simplify things, you can copy/paste the schema.d.ts and schema.json to your own repository.

Alternatively, you can select the properties you want to customize when invoking your generator, and the rest can be passed to the Nx generator as default properties, as shown below:

import { libraryGenerator } from '@nx/angular/generators';
import { Tree, formatFiles } from '@nx/devkit';
import { LibraryGeneratorSchema } from './schema';
import { Linter } from '@nx/linter';

export async function mylibraryGenerator(tree: Tree, options: LibraryGeneratorSchema) {
  await libraryGenerator(tree, {
    ...options,
    addTailwind: true,
    buildable: true,
    linter: Linter.EsLint
  });

  await formatFiles(tree);
}

export default mylibraryGenerator;

In the above code, addTailwind, buildable and linter will not be editable. If we want to provide default values while still allowing them to be edited, we can:

use the default property inside the schema.json
set a default value inside nx.json at the root of our project.

{
  "generators": {
    "@my-workspace/demo:library": {
      "linter": "eslint",
      "buildable": true,
      "addTailwind": true
    }
  }
}

Now that we have created the same default set of files that the Nx generator creates, we can customize some files according to our needs.

If you want to learn by practicing and challenge yourself, try out Angular Challenges. It’s a library that lists multiples Angular, Nx, Rxjs and more Challenges.

Customize Jest Configuration File:

If we want to generate a different jest.contig.ts file with additional properties, we have two options:

Option 1:

We can skip the generation of all Jest configuration through the Nx generator by setting the following inside the libraryGenerator function.

import { UnitTestRunner } from '@nx/angular/generators';

unitTestRunner: UnitTestRunner.None,

This option is suitable if you have many modifications to apply to the default Jest configuration, but keep in mind that you will have to manually update all the necessary files yourself, such as project.json with the new test target, tsconfig.json with the a tsconfig.spec.ts and create additional required files.

Option 2:

In most cases, this option is preferred as it allows you to update only what needs to be changed. In our case, we only want to update the jest.config.ts file.

To achieve this, follow these steps:

Add a template file named jest.config.ts__tmpl__ inside the files directory of your generator folder. To avoid syntax compilation errors in our IDE, we append tmpl at the end of the file name. The content of the template file can be as follows:

/* eslint-disable */
export default {
  displayName: '<%= project %>', // 👈 variable
  preset: '<%= offsetFromRoot %>jest.preset.js', // 👈 variable
  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
  transform: {
    '^.+\\.(ts|mjs|js|html)$': [
      'jest-preset-angular',
      {
        tsconfig: '<rootDir>/tsconfig.spec.json',
        stringifyContentPathRegex: '\\.(html|svg)$',
      },
    ],
  },
  transformIgnorePatterns: ['node_modules/(?!(.*\\.mjs$|lodash-es))'],
};

This template file sets two variables that can be edited based on your configuration.

Finally, add the following code to your generator:

const projectConfig = readProjectConfiguration(tree, options.project);

tree.delete(join(projectConfig.root, './jest-config.ts'));

generateFiles(
tree,
joinPathFragments(__dirname, 'file'),
projectConfig.root,
{
  tmpl: '',
  project: options.project,
  offsetFromRoot: offsetFromRoot(projectConfig.root),
}
);

Let’s go through the code:

We read the project configuration.
We delete the configuration file generated by the built-in Nx generator.
We generate our new configuration file by providing the path to the template file, the path where we want to create this file, and the definition of each variable used inside our template. By following these steps, you can customize the any TS file according to your needs.

Customize eslint configuration file:

For this one, we want to add the rule@typescript-eslint/member-ordering: ‘off’ to all our eslintrc file.

We could do the same as above, replacing the generated file with our new custom file. But since the eslintrc file is a JSON file, we can easily manipulate it.

We will just add the line at the right position inside the file.

Using the utilities provided by @nx/devkit, we can use the updateJson function to update our file. This function takes three arguments: the Nx tree, the path to the JSON file, and a callback function that manipulate the JSON object.

Here’s the function to achieve this:

  updateJson(tree, eslintPath, (json) => {
    json.overrides[0].rules = {
      ...json.overrides[0].rules,
      '@typescript-eslint/member-ordering': 'off',
    };
    return json;
  });

In the above code, we update the rulesproperty inside the first override object of the ESLint configuration file. We add the rule @typescript-eslint/member-ordering with the value off.

To check out the full working example, it’s here. 👇

Answer:25 generator extending lib #70

tomalaforge posted on Jun 27, 2023

code to create a generator that extends the built-in Nx library generator

View on GitHub

Now we have a fully functional generator. If you go back to your NX Console and navigate to the generate command, you should see our custom generator listed there.

Note: If you don’t see it, simply restart your IDE to allow Nx to detect your new generator.

You did it! You have built a fantastic generator that will save you a lot of errors and time. Enjoy the full power of these generators and create as many as your team needs. 🚀🚀🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Migrating an Angular project to an Nx workspace: Ng-Morph to the rescue!

thomas — Mon, 05 Jun 2023 21:37:16 +0000

I am currently migrating multiple projects and shared libraries within an Nx workspace to take advantage of the power, tooling, and developer experience (DX) provided by Nx. I won't explain the process in this article, but during this transition, I had to perform numerous tedious and repetitive tasks. Fortunately, I discovered an amazing library called Ng-Morph that allows us to write scripts for automating such repetitive tasks within our project tree.

In this article, I will explain three examples of scripts I wrote to speed up my work and make it less painful.

Delete all unnecessary test files.

When generating a component, directive, or pipe using the Angular CLI, it creates a spec file with a single "should create" test. In my current workspace, many of these files were kept but are actually unnecessary and slow down the execution time of the test command. The goal is to delete all the files that only contain the "should create" test.

Using Ng-morph, we start by defining the file tree and the type of files we want to work with. It's mandatory to set our active project with the following line:

setActiveProject(createProject(new NgMorphTree(), '/', ['**/*.spec.ts']));

const sourceFiles = getSourceFiles(['apps/**/*.spec.ts', 'libs/**/*.spec.ts']);

sourceFiles.forEach(s => {
  const text = s.getFullText();
  if (text.match(new RegExp("(it\\('should be created'|it\\('should create)", 'g'))) {
    const secondTest = text.match(new RegExp("(it\\(')", 'g'));
    if (secondTest && secondTest.length === 1) {
      s.delete();
    }
  }
});

Next we load all spec files using getSourceFiles. Once done, we iterate through each file, check if it matches our criteria (using a basic regex search on the file's text), and delete it if it does.

Finally, we save our changes by calling saveActiveProject.

As you can see, the script is simple and easy to write and read. It took me less than 15 minutes to write it, even without prior knowledge of the library. With practice, you can write this script in just 5 minutes. If you were to do this manually, it would take much longer and be less enjoyable.

One important thing to note is that there's no need to spend time writing the script with well-named variables or maintainable code, as the script is meant to be run once to accomplish the desired task.

Finally, to run the script, we use ts-node:

npx ts-node path/to/script

Exporting all files to the public api file:

In Nx, we create libs/packages/modules (name them as you like) to encapsulate code. To expose the code externally, we need to export it within a barrel file or public API file. In the current project I'm working on, each function/class is imported directly from its respective file, resulting in paths like this:

import { FooComponent } from 'src/path/to/foo.component';

However in Nx, if you want to use FooComponentin another library, we need to export it from the file that exports our library's API. Manually doing this can be tedious, as we would need to find and export the paths of all the files within the library.

With Ng-Morph, we can automate this task quickly. Let's take a look at the script:

const project = process.argv[2];

const folder = `libs/${project}`;

const fs = require('fs');
if (!fs.existsSync(folder)) {
  console.log("name of project doesn't exist");
  process.exit();
}

This time, I decided to make the script accept one argument, as it can be used for many other libraries.

setActiveProject(createProject(new NgMorphTree(), '/', ['**/*.ts']));

As mentionned before, we must setup the active project to register our tree.

const sourceFiles = getSourceFiles([`/${folder}/src/lib/**/*.ts`, `!/${folder}/src/lib/**/*.spec.ts`])
  .map(s => s.getFilePath().replace(`/${folder}/src`, '.').replace('.ts', ''))
  .map(n => `export * from '${n}';`);

const barrelFile = sourceFiles.reduce((acc, file) => `${acc}\n${file}`, '');

createSourceFile(`/${folder}/src/index.ts`, barrelFile, {
  overwrite: true
});

saveActiveProject();

All the logic is contained inside this few lines.

We load all TS files except spec files and we remove the .ts extenstion and add export * from statement to each file path.

Next, we concatenate all these strings into one and overwrite the barrel file of the library.

Finally, we don't forget to call setActiveProjectto save our changes.

Note: This script is basic and can be optimized. It exports all files, including those not used outside the library. However, we are currently migrating multiple projects within Nx, and our priority is to make it work quickly. Other team members are working with the old setup, and the longer the branches diverge, the more challenging the merge will be.

In a following step, we can optimize the process by splitting the library and removing any unnecessary export files from the public API.

Renaming file imports:
This situation occurs frequently when files and functions are moved around. For example, we may have a large utils file and want to split it, moving some functions outside of that file and into a shared/utils library. As a result, the old imports must be removed and replaced with the new ones.

We can find imports like this:

import { addDate, removeDate } from '@test/shared'
import { addDate } from '@test/shared'

The second case can be easily handled with the search and replace feature in any IDE. However, the first case is more challenging because we need to remove addDatefrom the import array while keeping removeDateintact.

With Ng-morph, this task can be easily automated.

const importToReplace = 'addDate';
const newNamespace = '@test/shared/date-utils';

function importIfNotPresent(source: string) {
  addImports(source, [
    {
      namedImports: [importToReplace],
      moduleSpecifier: newNamespace
    }
  ]);
}

setActiveProject(createProject(new NgMorphTree(), '/', ['**/*.ts']));

const sourceFiles = getSourceFiles([`**/*.ts`]).map(s => s.getFilePath());

sourceFiles.forEach(s => {
  const imports = getImports(s, { namedImports: importToReplace }).filter(
    s => s.getModuleSpecifier().getText().replace(/'/g, '') !== newNamespace
  );

  imports.forEach(i => {
    const namedImports = i.getNamedImports();

    if (namedImports.length === 1) {
      i.remove();
      importIfNotPresent(s);
    } else {
      namedImports.forEach(n => {
        if (n.getName() === importToReplace) {
          n.remove();
          importIfNotPresent(s);
        }
      });
    }
  });
});

saveActiveProject();

The script is very easy to read and understand but let's break it:

First, we define the import we want to replace importToReplaceand the new namespace newNamespacewhere the function will be located.

As usual, we start by calling setActiveProjectto initiate our script. We load all TS file and iterate over them.

We search for occurrences addDatewithin the imports of each file and filter to ensure that the namespace hasn't already been updated.

Then, we iterate over the named imports. If there is only one import, we delete the entire import statement and replace it with the new one.

If there are multiple imports, we delete the desired function and add the new import statement to the file.

Note: As you can see, we don't need to work with complex AST function or perform complex searches. Ng-Morph allows us to access and modify our files in a simple and straightforward way.

Once you understand how to use Ng-Morph, working with your entire repository becomes easy and enjoyable.

Documentation of Ng-Morph can be found here.

I hope you have a better understanding of this amazing library and have seen all the incredible things you can achieve with it. 🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Accessing route params in Angular

thomas — Mon, 29 May 2023 20:35:28 +0000

There are various scenarios in which you may need to read parameters from your route. These parameters can be query parameters (e.g.: test?username=…) or route parameters (e.g.: test/:testId).

Additionally, you can pass any desired value via the data property inside the Route object in Angular routing as shown below:

export const appRoutes: Route[] = [
  {
    path: 'test/:testId',
    loadComponent: () => import('./test.component'),
    data: {
      permission: 'admin',
    },
  },
];

ActivatedRoute

In all scenarios, you will start by injecting the ActivatedRoute into your component. This class gives access to the route on which your component is defined.

private activatedRoute = inject(ActivatedRoute);

Within this class, you have two options for retrieving your route parameters.

Snapshot

The first option is using the snapshot object. As the name suggests, it allows you to take a snapshot of the route state and work with it.

testId = this.activatedRoute.snapshot.params['testId'];
permission = this.activatedRoute.snapshot.data['permission'];
user = this.activatedRoute.snapshot.queryParams['user'];

Using the snapshot object provides static values, meaning that if the parameters change, you will not be notified unless you reload your component.

It is generally considered safer to choose the next option:

Observable

Alternatively, each parameter can be listened to as an observable. Although this may feel more complex, it provides the advantage of being notified when the value changes.

testId$ = this.activatedRoute.params.pipe(map((p) => p['testId']));
permission$ = this.activatedRoute.data.pipe(map((d) => d['permission']));
user$ = this.activatedRoute.queryParams.pipe(map((q) => q['user']));

By using observables, you can subscribe to these streams (using asyncPipe or subscribe function) and receive notifications whenever the values of the parameters change.
This allows for more dynamic and responsive behavior in your components.

Ngrx Router Store

If you are using Ngrx within your application, you might be interested in retrieving route parameters through Selectors.
First, you need to add the @ngrx/router-store npm package and include it in your bootstrapApplication function in the main.ts file:

import { provideStore } from '@ngrx/store';
import { provideRouterStore, routerReducer } from '@ngrx/router-store';

import { AppComponent } from './app.component';

bootstrapApplication(AppComponent, {
  providers: [
    //...
    provideStore({
      router: routerReducer,
    }),
    provideRouterStore()
  ],
});

Next, Ngrx provides a getRouterSelectorfunction with a variety of selectors that you can use. You can destructure the function as follow:

import { getRouterSelectors, RouterReducerState } from '@ngrx/router-store';

// Other selectors are available:
// https://next.ngrx.io/guide/router-store/selectors
export const {
    selectQueryParam,
    selectRouteParam,
    selectRouteDataParam, 
} = getRouterSelectors();

Finally, within your component, you can access your route parameter properties as follows:

testId$ = this.store.select(selectRouteParam('testId'));
permission$ = this.store.select(selectRouteDataParam('permission'));
user$ = this.store.select(selectQueryParam('user'));

You end up with observables and you must subscribe to them to get notified.

RouterInput in Angular v16

Angular v16 was released with a lots of new features aiming to improve the developer experience (DX). One of these features is RouterInput, which allows you to retrieve route information through inputs.

If you haven't yet explored AngularChallenges or completed the router input challenge, I encourage you to do so now or at a later time to practice using this new API. You can find the challenge details here: AngularChallenges - Router Input.

To take advantage of RouterInput, you need to update your route provider in the main.ts file as follows:

import { provideRouter, withComponentInputBinding } from '@angular/router';

bootstrapApplication(AppComponent, 
  providers: [provideRouter(appRoutes, 
      withComponentInputBinding() // 👈
    )]
)

With the updated route provider, you can now listen to route parameters through input bindings in your component:

@Input() testId!: string;
@Input() permission!: string;
@Input() user!: string;

Notes:

if the testId input changes, your component will be notified (as an observable stream).
Router Inputs are only accessible within the routed component. If you need to access these parameters within a child component, you can use one of the methods mentioned earlier or pass the input through input binding between the parent and child components.
If you prefer a more descriptive decorator name, you can remap it in its definition as follow:

import {Input as RouterInput} from '@angular/router'

export class Component {
 @RouterInput() testId!: string;
}

Feel free to explore and test your new skill on my Angular challenge #22, and enjoy experimenting with its capabilities in your projects.

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Future of Change Detection in Angular with Signals

thomas — Wed, 24 May 2023 08:15:00 +0000

Default Strategy

If you’re using Angular, you’ve probably heard about Zone.js. It’s an amazing library which does a lot of magic but feels somewhat unnecessary. The library’s only purpose is to monkey-patch events to detect all changes made inside your application and magically rerender the view.

The idea behind Zone.js is that you don’t have to worry about how and when to rerender the view. While Zone.js works pretty well, it does require a lot of JavaScript code to be shipped before your application even starts. Additionally, Zone.js doesn’t really know where each change occurs and needs to dirty check and refresh the entire component tree whenever a change is detected.

For example, when you click a button or update a property in any component, Zone.js will detect that change and check the entire component tree starting from the parent component down to each component. While Zone.js is well-optimized and this process is really fast, Angular ends up recalculating and rechecking a lot of unnecessary code because we don’t really know where the change occurred. All we know is that a click event or update event has been triggered somewhere, and the view might need to be rerendered somewhere.

OnPush Strategy

To optimize the change detection process, Angular introduced the ChangeDetectionStrategy.OnPush. This strategy checks only the component branch that was impacted by the change, down to the component where the change occurred.

✅ This approach saves unnecessary calculations and improves performance.

❌ However, using the OnPush strategy requires developers to have more knowledge of Angular in order to trigger change detection correctly. (manual markForCheck, async pipe, new instance of Input, …).

(Please note that this article does not focus on the workings of the OnPush strategy.)

Signals Change Detection

A more optimized change detection mechanism is the reason why Angular needed a new system to detect changes more precisely. To accomplish this, Angular introduced a new primitive called “Signal”.

A Signal is a primitive that encapsulates an object, string, or other type of data. When the encapsulated variable is updated, the framework can precisely determine which View is impacted and needs to be refreshed.

As of the time of writing (Angular v16), the Signal component has not yet been introduced, and Signal change detection still relies on Zone.js. The following section is based only on the RFC.

If we simplify the concept of **View **to its component template, and update a signal listen to inside the template, we have the following schema:

When a signal is updated using the set , update or mutate method, any templates that listen to that signal are notified and the Views and only those Views are refreshed.

Only Signals that are listened to inside a template trigger a new cycle of change detection. If a Signal is only called inside a function, no rerender will happen on the UI side.
The entire template gets refreshed, not only the Signal binding. This means that all functions and properties will get reevaluated.

Why update the entire view instead of each binding individually?

It’s a tradeoff that the Angular team has made. They decided to reduce the granularity of an application to its Views. Setting the dependency graph is expensive because it takes up memory. A View is already a small enough fragment of the UI to provide good rerender performance. (Remember that with Zone.js, Angular rerenders the entire application.)

What does VIEW mean ?

A View is a piece of code encapsulated inside a ng-template. Every structural directive, such as ngIf, ngForcreates a new VIEW. So if your template has a large data table created with ngFor, each row will have a separate view and only the row impacted by a signal change will be rerendered.

If we take our previous illustration and create two Views inside our component X, we will get the following:

👉 All of this will be working with and **without **Zone.js on signal based component in future version of Angular.

That’s it for this article! I hope you now have a better understanding of how signals will improve the performance of your Angular application in the near future. Get ready to start experimenting with signals, as the API is already available in Angular v16.

The future of Angular is looking very bright. 🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Flattening and Transforming Observable Arrays with RxJs

thomas — Fri, 28 Apr 2023 08:25:40 +0000

Rxjs is an open-source library use to handle streams of events. It's a very powerful tool but it has a steep learning curve and can be tricky at times.

The issue we will be discussing in this article is when dealing with a list of objects inside a stream, and needing to execute another async operation on one property of those objects. This can result in a Observable<Array<Observable<T>>>, which can be challenging to subscribe to. We'll explore different solutions to overcome this challenge and transform it into an Observable<Observable<Array<T>>>.

This article will also help you to resolve challenge #11 of Angular Challenges, which is intended for developers who already have a strong understanding of observables. However anyone can read this article and learn from it. If you want to try this challenge first, I encourage you to do so then come back to compare your solution with the guidance provided here. (You can also submit a PR that I'll review)

Let's start with a very basic exemple to understand the issue more clearly.

readonly persons$ = this.service.get(selectPersons);
         // ^? Observable<Persons[]> where Person = {id: number, name: string}

We have a readonly persons$ observable that retrieves a list of persons from our store, which could be NgRx, RxAngular, or a simple service using a Subject. In this example, the implementation details are hidden behind this.service.

The goal is to fetch the address of each person from our backend and return a list of persons with their corresponding addresses.

Imperative approach:

The approach I see the most often inside codebase is to use imperative style and nest the subscribe callbacks, like this:

let personWithAddress: PersonWithAddress[];

this.persons$.subscribe((persons) => {
  persons.forEach((person) => {
    this.http.getAddress(person.id).subscribe((address) => {
      personWithAddress.push({...person, ...address});
    });
  });
});

However, this approach is discouraged as it results in nested subscribes and can quickly become messy, even in this simple example.

Naive approach with Rxjs:

Let's try again with a more reactive approach, using rxjs operators.

What I often see when teaching people on that type of issue is this code :

 personWithAddress$ = this.persons$.pipe(
  // ?^ Observable<Observable<PersonWithAddress>>
    mergeMap((persons) => 
        persons.map((p) =>
                //^ map is not a rxjs operator but a Array function
            this.http.getAddress(p.id).pipe(map(address => ({...p, ...address})))))
                        // ^return an observable we never subscribe to  
);

People often struggle with trying to use mergeMap, switchMap,... to flatten the Observable<Observable<T>> structure. However, this is not possible since persons.map returns an array of Observables, not a single Observable.

Forkjoin:

Another well-known option is the forkJoin operator, often used when working with an array of Observables that complete (note that the word "complete" is crucial, as forkJoin will only emit once all Observables have completed).

Here's an example using forkJoin:

  personWithAddress$ = this.persons$.pipe(
    mergeMap((persons) =>
      forkJoin(
        persons.map((p) =>
          this.http.getAddress(p.id).pipe(map((address) => ({ ...p, ...address })))
        )
      )
    )
  );

Heyy, this code compiles and works as intended. However, it can be difficult to read and debug due to the high level of nesting inside the block of code.

The final trick:

One very important piece of advice to remember when working with streams of object arrays is to first flatten the structure to work with a stream of simple objects. Working with arrays can create a lot of overhead, while working with a simple stream of objects is what we are used to working with every day.

The two magical operators for achieving this are mergeAll and toArray. The first one lets us flatten the array to a stream of simple objects, and the second one puts the stream back into an array when it's finished.

Here's an example of how we can use these operators in action:

  personWithAddress$ = this.persons$.pipe(
    mergeAll(), // flatten to Observable<Person>
    mergeMap((p) =>
      this.getAddress(p.id).pipe(map((address) => ({ ...p, ...address })))
    ),
    toArray() // back to Observable<PersonWithAddress[]>
  );

Notes:

Only one level of nesting
Working with a simple object is preferred over working with an array of objects.

That's it for this article! I hope you have learned a new trick to ease your usage of rxjs and become a better reactive programmer. 🚀

You can find me on Twitter or Github.Don't hesitate to reach out to me if you have any questions.

Boost Your App's Performance by Wrapping Your Functions Inside a Pipe

thomas — Fri, 07 Apr 2023 07:50:00 +0000

The purpose of this article is to provide you with a small, strongly-typed utility pipe that you can easily incorporate into your project to improve its performance.

This article will also provide the solution for challenge #9 of Angular Challenges, which is intended for intermediate-level developers seeking to enhance their understanding of pipes. If you haven’t tried it yet, I encourage you to do so before coming back to compare your solution with mine. (You can also submit a PR that I’ll review)

In this article, we will not delve into the workings of pipes or how they can benefit your Angular application. If you wish to learn more about these topics, please refer to my previous article.

Deep dive into Angular pipes

thomas for Playful Programming Angular ・ Feb 28 '23

#angular

As mentioned in the previous article, calling a function inside a template can have a significant impact on performance as the function will be recomputed every time change detection is executed. We can mitigate this by adding a memo function to cache the input value, as described in the above article. However, this approach has a limitation in that we can only use the memo function once per input.

The solution to this problem is to move our function inside a pipe. However, if we have multiple functions to move, we would need to create a new pipe for each function, which could become cumbersome.

In challenge #9 of Angular Challenge, we have the following component:

@Component({
  standalone: true,
  imports: [NgFor],
  selector: 'app-root',
  template: `
    <div *ngFor="let person of persons; let index = index; let isFirst = first">
      {{ showName(person.name, index) }}
      {{ isAllowed(person.age, isFirst) }}
    </div>
  `,
})
export class AppComponent {
  persons = [
    { name: 'Toto', age: 10 },
    { name: 'Jack', age: 15 },
    { name: 'John', age: 30 },
  ];

  showName(name: string, index: number) {
    // very heavy computation
    return `${name} - ${index}`;
  }

  isAllowed(age: number, isFirst: boolean) {
    if (isFirst) {
      return 'always allowed';
    } else {
      return age > 25 ? 'allowed' : 'declined';
    }
  }
}

The for loop in our code is currently calling two functions for each person in the array. These functions are being recomputed at each change detection cycle, which can cause performance issues.

As mentioned previously, we could create a separate ShowNamePipe and IsAllowedPipe for each function, but this would require creating a large number of pipes for every component in our application.

To solve this problem, we can wrap our function inside a generic pipe called WrapFnPipe, as shown below:

@Pipe({
  name: 'wrapFn',
  standalone: true,
})
export class WrapFnPipe implements PipeTransform {
  transform(func: (...arg: any[]) => R, ...args: any[]): R {
    return func(...args);
  }
}

To refactor our HTML with this pipe, the first argument is the function we want to wrap, then we pass all the function arguments separated by :. We can now rewrite our HTML to the following:

<div *ngFor="let person of persons; let index = index; let isFirst = first">
  {{ showName | wrapFn : person.name : index }}
  {{ isAllowed | wrapFn : person.age : isFirst }}
</div>

By using this method, we can obtain all the benefits of Angular pipe without creating a specific pipe for each function. Each function is wrapped inside its own instance of the WrapFnPipe, which means each person has its own cached value. Therefore, when a new change detection is executed, the function is not re-executed and the last cached value is returned, resulting in an immediate performance boost.

However, introducing this wrapping function removes all type safety as it remaps all types to any. To add type safety, let’s explore some options.

A naive approach to adding type safety would be to use generics and replace all any types with a generic type:

transform<ARG, R>(func: (...arg: ARG[]) => R, ...args: ARG[]): R {
  return func(...args);
}

However, this approach will only work if all arguments of the function are of the same type.

In our case, we will encounter an error because the generic type ARG only takes the first type, which is string in our case, and not string | undefined. This approach would not be very type safe either because we would be able to invert both arguments.

To address this issue, we need to explore TypeScript’s function overloading feature and take advantage of it. If you are not familiar with function overloading or how it works, you should read the following article first and come back to this article afterwards.

Function Overloading in Typescript

thomas for Playful Programming Angular ・ Mar 27 '23

#typescript #angular

Using function overloading, we end up with this pipe transform function:

@Pipe({
  name: 'wrapFn',
  standalone: true,
})
export class WrapFnPipe implements PipeTransform {
  transform<ARG, R>(func: (arg: ARG) => R, args: ARG): R;
  transform<ARG1, ARG2, R>(
    func: (arg1: ARG1, arg2: ARG2) => R,
    arg1: ARG1,
    arg2: ARG2
  ): R;
  transform<ARG1, ARG2, ARG3, R>(
    func: (arg1: ARG1, arg2: ARG2, arg3: ARG3) => R,
    arg1: ARG1,
    arg2: ARG2,
    arg3: ARG3
  ): R;
  transform<ARG1, ARG2, ARG3, R>(
    func: (arg1: ARG1, arg2: ARG2, arg3: ARG3, ...arg: any[]) => R,
    arg1: ARG1,
    arg2: ARG2,
    arg3: ARG3,
    ...arg: any[]
  ): R;

  transform<R>(func: (...arg: unknown[]) => R, ...args: unknown[]): R {
    return func(...args);
  }
}

Note:

The first 4 functions are just definitions for different transform methods. The last one is the actual implementation that combines all of the definitions.
The first definition is for a one argument function, the second for a two arguments function and so on. We stop at 4 because it is bad design to have too many arguments, but if you want to, more definitions can be added.

By doing so, we have strong type safety in our template for any function. This includes type safety on the number of parameters, as well as type safety on the type of each input, as shown in the following screenshot:

I hope this article has helped you understand the power of pipes and what can be achieved with TypeScript. This pipe is a quick win and can be added to your project right away to boost some very costly operations without the need to refactor everything. 🚀

You can find me on Twitter or Github.