DEV Community: Armen Vardanyan

NgRx Use Cases, Part III: Decision-making

Armen Vardanyan — Thu, 15 Aug 2024 13:27:49 +0000

Original cover photo by Hansjörg Keller on Unsplash.

In my previous articles, we covered access restriction and handling lists with NgRx. Today, we are going to address a more general problem of decision-making across an Angular app that utilizes mainly NgRx Effects (but also a bit of reducers and selectors). In this Article, we will cover the following topics:

Error handling with NgRx
Handling redirections
Handling loading data
User interactions

Let's get started!

Error handling with NgRx

Error handling is something everyone hates (and often just forgets about), but also something everyone really, really needs. With NgRx apps, the complexity of error handling actually increases if we do not address this with proper care. Usually, errors in NgRx arise from effects, which, in most scenarios, are caused by HTTP requests.

There are usually two approaches to handling error in general: handling locally or globally. Handling locally means that we actually address the very specific error that occurred in some specific part of the app. For instance, if the user failed to log in, we might want to show a very specific error message like "Invalid username or password", instead of some generic error message like "Something went wrong".

Handling globally, on the other hand, means that we, in a way, lump all errors into one "pipeline" and use the very generic error messages we mentioned before. We could, of course, start a discussion about which idea is more suitable for what scenarios, but the harsh reality is that almost every app will need a bit of both worlds. We want to show error messages if any errors happen ("Something went wrong" is still better than a silent failure), but we also want to perform some specific actions in case of some errors. Let's address both scenarios.

Generic error handling with NgRx

In NgRx, everything that happens is triggered by an action. For activities that might involve gerring an error (HTTP calls, WebSockets, etc), we usually create several actions for a single activity:

export const DataActions = createActionGroup({
  source: 'Data',
  events: {
    'Load Data': emptyProps(),
    'Load Data Success': props<{ data: Data }>(),
    'Load Data Error': props<{ error: string }>(),
  },
});

As we can see, only to load a piece of data from an API, we need three actions. We might have dozens, if not hundreds, such "error" and "success" actions in a given application, so we might want to show a generic error message in case any of them is dispatched. We can do this by standardizing the error action's payload. For instance, we might want to add some very specific property to all actions that represent errors. In our case, the presence of the error property in the action payload can be enough to know that the action represents an error.

We can, then, subscribe to all actions that represent errors and show a generic error message. This is a very common pattern in NgRx apps, and is usually what is understood as "global error handling". In our case, we can do this by subscribing to all actions and filtering out the ones that have an error property in their payload:

export const handleErrors$ = createEffect(() => {
  const actions$ = inject(Actions);
  const notificationsService = inject(NotificationsService);
  return actions$.pipe(
    filter((action) => !!action.payload.error),
    tap((action) => {
      notificationsService.add({
        severity: 'error',
        summary: 'Error',
        detail,
      });
    }),
}, { functional: true, dispatch: false });

In this case, any "error" action we ever dispatch will result in the same notification being shown, but also with a custom message. We can go a bit further by standardizing the approach the action props are created for an error. Here is a small helper function that can be handy:

export function errorProps(error: string) {
  return function() {
    return({error});
  };
}

Now, we can use this function to create the error props for our actions:

export const DataActions = createActionGroup({
  source: 'Data',
  events: {
    'Load Data': emptyProps(),
    'Load Data Success': props<{ data: Data }>(),
    'Load Data Error': errorProps('Failed to load data'),
  },
});

This will make all the errors look the same way to avoid typos or confusion. Next, let's improve this to also be able to handle very specific errors.

Handling specific errors

In our case, we might want to be able to customize the way a generic error handler works for some specific cases. We want to be able

to tell the effect whether to show a generic error message or not
redirect to error pages with some predefined data
display error notification inside a page

Let's start with the first one. We can do this by adding a new property to the error action payload:

export function errorProps(error: string, showNotififcation = true) {
    return function() {
        return({error, showNotification});
    };
}

Now we can create an action that will later tell the effect to skip the generic notification message:

export const DataActions = createActionGroup({
  source: 'Data',
  events: {
    'Load Data': emptyProps(),
    'Load Data Success': props<{ data: Data }>(),
    'Load Data Error': errorProps('Failed to load data', false),
  },
});

Next, we should update the effect to reflect this:

export const handleErrors$ = createEffect(() => {
  const actions$ = inject(Actions);
  const notificationsService = inject(NotificationsService);
  return actions$.pipe(
    filter((action) => !!action.payload.error),
    tap((action) => {
      if (action.payload.showNotification) {
        notificationsService.add({
          severity: 'error',
          summary: 'Error',
          detail,
        });
      }
    }),
  );
}, { functional: true, dispatch: false });

Notice we did not add the checking of the showNotification property to the filter operator. This is because we will have scenarios where a notification should not be shown, but another action still has to be performed (like redirecting to an error page). Let's do precisely this by adding a new parameter to our error action:

export function errorProps(error: string, showNotification = true, redirectTo?: string) {
  return function() {
    return({error, showNotification, redirectTo});
  };
}

Now, we can create an action that will later tell the effect to redirect to an error page:

export const DataActions = createActionGroup({
  source: 'Data',
  events: {
    'Load Data': emptyProps(),
    'Load Data Success': props<{ data: Data }>(),
    'Load Data Error': errorProps('Failed to load data', false, '/error'),
  },
});

Next, let's finalize our effect by adding a redirection to the error page if the redirectTo property is present in the action payload:

export const handleErrors$ = createEffect(() => {
  const actions$ = inject(Actions);
  const notificationsService = inject(NotificationsService);
  const router = inject(Router);
  return actions$.pipe(
    filter((action) => !!action.payload.error),
    tap((action) => {
      if (action.payload.showNotification) {
        notificationsService.add({
          severity: 'error',
          summary: 'Error',
          detail,
        });
      }
      if (action.payload.redirectTo) {
        router.navigateByUrl(action.payload.redirectTo);
      }
    }),
  );
}, { functional: true, dispatch: false });

And that is it to this. Of course, if we need something really custom for a particular error action, we can just write a completely separate effect to handle that. Sometimes, if we want to also do something in the UI in relation to an error, we can also add the error message (and any other data) to the store and use them via a selector anywhere.

Next, let us discuss loading data into our component, and several approaches to it.

Handling loading data

Before we proceed, we should first understand that the approaches listed in this section are not better or worse than one another. Instead, they are approaches for different situations, depending on what we want for our UX. Let's examine them step by step.

Selecting data in the component to use

The most straightforward way we can get some data (presumably from an API) is by just selecting it in the component. With the latest APIs, we can select a signal of our data and use it directly in the template. Here is a very simple example:

@Component({
  selector: 'app-my',
  template: `
    <div>
      <h1>Data</h1>
      <p>{{ data() }}</p>
    </div>
  `,
})
export class MyComponent {
  data = this.store.selectSignal(dataFeature.selectData);
}

Of course, in real life, we often need to deal with scenarios like loading, errors, and so on. In this case, our state might look like this:

export interface State {
  data: Data | null;
  loading: boolean;
  error: string | null;
}

If we are using the createFeature function to register our state, we can make use of the selectDataState function that the feature automatically creates for us. This will return the entire state with loading, error, and data properties. We can then use this in our component:

@Component({
  selector: 'app-my',
  template: `
    <div>
    @if (vm().loading) {
      <p>Loading...</p>
    }
    @if (vm().error) {
      <p>Error: {{ vm().error }}</p>
    } @else {
      <h1>Data</h1>
      <p>{{ vm().data }}</p>
    }
    </div>
  `,
})
export class MyComponent {
  vm = this.store.selectSignal(dataFeature.selectDataState);
}

This is very useful in most scenarios. However, sometimes we might not want to display the entire page if this important piece of data is not loaded. In Angular, this is commonly achieved with the use of routing resolvers, functions that return some Observables that routing waits for to emit before displaying a particular page. This is easy with the use of the HttpClient service, however, this becomes a bit complicated with NgRx (because we only make HTTP calls inside effects), resulting in lots of developers skipping resolvers entirely. However, there is an easy way to achieve this functionality. Let's build a simple resolver that utiliuzes the Store and the Actions Observable to know when the data is actually loaded:

export const dataResolver: ResolveFn<Data[]> = () => {  
  const store = inject(Store);
  const actions$ = inject(Actions);
  store.dispatch(DataActions.loadData());
  return store.select(dataFeature.selectData).pipe(
    skipUntil(actions.pipe(ofType(DataActions.loadDataSuccess))),
  );
}

Here, we first dispatch the action that actually initiates the HTTP call, then we just return the selected data from the store as an Observable, but with a catch - we tell it to wait until the action signaling that the data has been loaded is dispatched. Given that effects are guaranteed to run after reducers, this will ensure that the data is actually put into the store before the resolver returns it. We can then just pick this data up in our component:

@Component({
  selector: 'app-my',
  template: `
    <div>
      <h1>Data</h1>
      <p>{{ vm.data() }}</p>
    </div>
  `,
})
export class MyComponent {
  private readonly route = inject(ActivatedRoute);
  readonly vm = toSignal(this.route.data, {
    initialValue: null,
  }) as Signal<{data: Data}>;
}

We used ActivatedRoute instead of the Store because we already returned this data in the resolver. This makes our components even leaner - we don't even have to inject the Store and in unit testing, it can be often easier to mock the ActivatedRoute than the Store.

Finally, let's take a look at advanced decision-making with NgRx actions and effects, and see how this can help work with complex cases in large applications.

User interactions

NgRx is very useful when writing declarative code, as it allows us to just select the relevant state, and use it in our templates. However, sometimes, especially when dealing with third-party libraries, we need to perform some "imperative actions" which is tangentially related to our store. Consider this code which uses the Angular Material MatDialog service to open a confirmation dialog:

export class MyComponent {
  private readonly dialog = inject(MatDialog);
  private readonly store = inject(Store);

  openConfirmationDialog() {
    const dialogRef = this.dialog.open(ConfirmationDialogComponent, {
      data: {
        title: 'Confirmation',
        message: 'Are you sure you want to do this?',
      },
    });

    dialogRef.componentInstance.confirm.subscribe(() => {
      this.store.dispatch(DataActions.deleteData());
    });

    dialogRef.componentInstance.cancel.subscribe(() => {
      dialogRef.close();
    });
  }
}

As we can see, there is a lot of imperative code in just this one method, there are two subscriptions, and they aren't even particularly simple (we just omitted unsubscription logic). Also, we must consider that in a normal application, we might have a dozen different places where the same confirmation dialog is used, with the only difference being the action that is performed when the user confirms/rejects.

Let's now approach this with an NgRx mindset, and try to create an action that can handle such a scenario, with callbacks as payloads.

export function confirmAction(callbacks: {confirm: () => void, reject: () => void}) {
  return function() {
    return({type: 'Open Confirmation Dialog', callbacks});
  };
}

Now, we can create an action that will later tell the effect to redirect to an error page:

export const DataActions = createActionGroup({
  source: 'Data',
  events: {
    'Delete Data': confirmAction({
      confirm: () => {
        return({action: 'Delete Data Confirmed'});
      },
      reject: () => {
        return({action: 'Delete Data Rejected'});
      },
    }),
  },
});

Now, we can create an effect that will handle all such actions:

export const handleConfirmationDialog$ = createEffect(() => {
  const actions$ = inject(Actions);
  const dialog = inject(MatDialog);
  return actions$.pipe(
    ofType(DataActions.openConfirmationDialog),
    tap((action) => {
      const dialogRef = dialog.open(ConfirmationDialogComponent, {
        data: {
          title: 'Confirmation',
          message: 'Are you sure you want to do this?',
        },
      });

      dialogRef.componentInstance.confirm.subscribe(() => {
        action.payload.callbacks.confirm();
      });

      dialogRef.componentInstance.cancel.subscribe(() => {
        action.payload.callbacks.reject();
      });
    }),
  );
}, { functional: true, dispatch: false });

Finally, we can really simplify our component:

export class MyComponent {
  private readonly store = inject(Store);

  openConfirmationDialog() {
    this.store.dispatch(DataActions.openConfirmationDialog({
      confirm: () => {
        this.store.dispatch(DataActions.deleteData());
      },
      reject: () => {
        // Do nothing
      },
    }));
  }
}

And that is it. However... we might face a problem if we try to make our application as fine as possible. In NgRx, it is a good practice to keep everything serializable, which is a fancy way of saying "easily convertible to JSON". In the app configuration, it is possible to set specific options to help safeguard us from, for example, putting functions in the store. This is done with two options, strictStoreSerializability and strictActionSerializability.

export const config: ApplicationConfig = {
  providers: [
    provideStore({}, {
      runtimeChecks: {
        strictActionSerializability: true,
        strictStoreSerializability: true,
      },
    }),
};

This goes a long mile to help keep our applications maintainable and prevent hard-to-debug issues.

[!NOTE] You can read more about runtime checks in the NgRx docs.

However, if we make actions strictly serializable, our confirmAction action will not work with the callbacks we passed! So, what can we do about it? Well, the easiest way is to give it other actions for confirm/reject options to handle by the effect. Because the nested actions will also be required to be serializable, this will help us bring everything back to a workable state, an approach that I personally call "higher-order actions".

export function confirmAction(confirmAction: string, rejectAction: string, callbackActions: {
  confirm: ActionCreator<any, any>,
  reject: ActionCreator<any, any>
}) {
  return function() {
    return({type: 'Open Confirmation Dialog', callbackActions});
  };
}

Next, we need to do a major update to our effect:

export const handleConfirmationDialog$ = createEffect(() => {
  const actions$ = inject(Actions);
  const dialog = inject(MatDialog);
  return actions$.pipe(
    ofType(DataActions.openConfirmationDialog),
    map(({callbackActions}) => {
      const dialogRef = dialog.open(ConfirmationDialogComponent, {
        data: {
          title: 'Confirmation',
          message: 'Are you sure you want to do this?',
        },
      });

      return merge([
        dialogRef.componentInstance.confirm.pipe(
          map(() => callbackActions.confirm()),
        ),
        dialogRef.componentInstance.cancel.pipe(
          tap(() => dialogRef.close()),
          map(() => callbackActions.reject()),
        ),
      ])
    }),
  );
}, { functional: true, dispatch: false });

Let's deconstruct what goes on here.

The ConfirmationDialogComponent exposes the confirm and cancel observables.
We open a MatDialog with the ConfirmationDialogComponent and every time an action created by the confirmAction is dispatched, we subscribe to the confirm observable and dispatch the action that was passed to the confirmAction function.
We also subscribe to the cancel observable and dispatch the action that was passed to the confirmAction function.
We return a merge of the two observables so that when either of them emits, the whole effect will emit.

With this implementation, it is easy to perform complex decision-making just using several actions in a component:

export class MyComponent {
  private readonly store = inject(Store);

  openConfirmationDialog() {
    this.store.dispatch(DataActions.openConfirmationDialog({
      confirm: DataActions.deleteData,
      reject: DataActions.cancelDeleteData,
    }));
  }
}

And that is it. With higher-order actions, we can easily delegate decision-making further to other effects and reducers as necessary, making the component code as declarative as possible.

Conclusion

In this article, we covered a few approaches to complex logic in Angular applications utilizing NgRx. NgRx is a huge tapestry of opportunities, and often we can easily transform ugly code into something understandable and maintainable. Such approaches are underappreciated, and with this piece, I try to bring them forth to help developers improve their state management solutions.

Signals: the Do-s and the Don't-s

Armen Vardanyan — Tue, 06 Feb 2024 09:43:10 +0000

Original cover photo by Shyam on Unsplash.

If we ask any Angular developer "What is the hottest topic in Angular right now?", with almost 100% certainty everyone would respond "Signals!". And they would be right. Signals are the hottest topic in Angular right now.

Of course, there is now a multitude of articles, videos, blog posts and so on, describing in deep detail what signals are, how they work, and different use cases, so we can safely assume almost everyone in the Angular community now knows about signals, and maybe at least has tried them out. But a fact that became quite obvious recently is that the community needs a specific set of rules for working with them, a set of Do-s and Don't-s, if you will. In today's article, let's dive into the world of signals, and find out examples of use cases where using signals in a specific way is not a good idea, and see what we should do instead. Let's get started!

Don't use setters for inputs to turn them into signals

When signals first dropped in v16, support for lots of features was limited (as signals themselves were experimental). For instance, it was impossible to use signals as inputs to components. So, the community came up with a workaround: using setters to turn inputs into signals. The idea is simple: we create a setter for an input and a separate signal, and inside the setter we set that signal's value to be the value of the input. Then, we can use the signal as an input to the component.

@Component({
  selector: 'app-my-component',
  template: `
    <div>
      {{ inputSignal() }}
    </div>
  `
})
export class SomeComponent {
  inputSignal = signal<string>();

  @Input() set input(value: string) {
    this.inputSignal.set(value);
  }

}

Obviously, this is quite verbose, especially if we have lots of inputs. This is really a lot of boilerplate, so let's see what we can do about it.

Do use signal inputs

Starting from Angular v17.1, a new way of declaring input properties for components and directives has emerged: the input function. This function declares an input, but its value is a signal, rather than a plain property. We can simplify our example now:

@Component({
  selector: 'app-my-component',
  template: `
    <div>
      {{ inputSignal() }}
    </div>
  `
})
export class SomeComponent {
    inputSignal = input<string>('default value');
}

Note: input signals are not stable as of v17.1, but will move to stable soon.

Of course, this is much, much better. This also supports all the features we have with regular inputs, for instance, to create a required input, we can do this:

export class SomeComponent {
  inputSignal = input.required<string>(); // we do not need to provide a default value here
}

We can also use transformers:

export class SomeComponent {
  booleanSignal = input(true, {transform: booleanAttribute});
}

And aliases:

export class SomeComponent {
  inputSignal = input.required({alias: 'condition'});
}

Warning: signal inputs are read-only, it is not possible to set another value to it in the child component

Of course, the previous approach was a workaround for a missing feature, and with time all Angular developers will move to signal inputs. Now, let's focus on some more serious stuff, that can happen in any codebase.

Don't retrieve data via HTTP calls in effects

This is a common mistake that can happen in any codebase. Let's say we have an input in our template, and we want to make an HTTP call when the input changes. We can do this:

@Component({
  selector: 'app-my-component',
  template: `
    <input (input)="query.set($event.target.value)" />
    <ul>
      @for (item of items) {
        <li>{{ item.name }}</li>
      }
    </ul>
  `
}) 
export class SomeComponent {
  query = signal<string>();
  items: Item[] = [];

    constructor(private http: HttpClient) {
        effect(() => {
            this.http.get<Item[]>(`/api/items?q=${this.query()}`).subscribe(items => {
                this.items = items;
            });
        });
    }
}

However, this poses several problems. First of all, the items collection is not a signal (we can make it into a signal, but then we would have to set {allowSignalWrites: true} on the effect, which is an even worse practice), which will make it hard to work with zoneless change detection in the future. Next, the declaration of items is separate from the place where its value is actually set, making it a bit harder to understand how it works; and finally, the triggering of the effect is decoupled from RxJS, meaning we cannot really harness the power of timing operators (like debounceTime in order to prevent unnecessary HTTP calls), as each change to the query signal will create a separate Observable.

Do use `toSignal` + `toObservable`

However, there is an easy way to circumvent all of those problems by utilizing the interoperability between signals and RxJS. Let's make a cleaner and more powerful way of doing this:

@Component({
  selector: 'app-my-component',
  template: `
    <input (input)="query.set($event.target.value)" />
    <ul>
      @for (item of items()) {
        <li>{{ item.name }}</li>
      }
    </ul>
  `
})
export class SomeComponent {
  http = inject(HttpClient);
  query = signal<string>();
  items = toSignal(
    toObservable(this.query).pipe(
      debounceTime(500),
      switchMap(query => this.http.get<Item[]>(`/api/items?q=${query}`))
    ),
  );
}

Here, we first move to the RxJS land with toObservable, make our asynchronous stuff there, and then move back to signals with toSignal. This way, we can use all the power of RxJS, and still have a signal in the end, and additionally, we solve the timing issue of multiple requests being made when the user types fast.

Let's move towards a more obscure example.

Don't forget about `untracked`

Let's imagine we have a CompanyDetailsComponent page that displays company data, and a list of its employees, and allows general editing, for instance, we can change the description text of the company. There can be a lot of employees, so we want to be able to search through them with a query, as in the previous example. However, we are not searching through the entirety of employees, but only through the ones that are employed at this particular company, meaning that every time we search for an employee, we have to use the company ID too. We can do this:

@Component({
  selector: 'app-company-details',
  template: `
    <div>
      <h2>{{ company().title }}</h2>
      <input placeholder="Company description" 
      [ngModel]="company().description" 
      (ngModelChange)="updateCompanyDescription($event)" />
    </div>
    <input (input)="query.set($event.target.value)" />
    <ul>
      @for (employee of companyEmployees()) {
        <li>{{ item.name }}</li>
      }
    </ul>
  `
})
export class CompanyDetailsComponent {
  http = inject(HttpClient);
  query = signal<string>();
  company = input.required<Company>();
  employees = input.required<Employee>();
  companyEmployees = computed(() => {
    return this.employees().filter(employee => employee.companyId === this.company().id && employee.name.includes(this.query()));
  });
  @Output() companyUpdated = new EventEmitter<Company>();

  updateCompanyDescription(description: string) {
    this.companyUpdated.emit({
      ...this.company(),
      description
    });
  }
}

We can see that this example is somewhat complex. Let's break it down to simplify:

The component receives the list of all employees and the company details
We use a computed signal to get the list of employees working at this particular company and match the query
We can update the company description, and emit an event when it happens so that the parent makes necessary HTTP requests
We use the computed signal in the template

This will work just fine, however, we overlooked something: when the description gets updated, it is sent to the parent component, which will then send a new reference to the company signal input, and because it is also used in the computed companyEmployees signal, this will trigger the computation unnecessarily, as we know the id cannot change, and we don't really care about the description, or any other property for that matter.

This can become even worse if we use an effect to trigger an HTTP call to make the search through employees, resulting in a lot of unnecessary HTTP calls every time the user types something in the unrelated description input.

Do use `untracked`

Thankfully, this issue has a very simple solution: using the untracked function to read the signal's value instead of calling it the usual way. untracked will return the current value of the signal without marking it as a dependency of the current computed signal/effect, meaning that the computation will not be triggered when the value of that signal changes. Here we go:

companyEmployees = computed(() => {
  return this.employees().filter(employee => employee.companyId === untracked(this.company).id && employee.name.includes(this.query()));
});

Note: in general, be careful with signals being called in the computed or effect function callbacks, rigorously check if they really need to be a dependency, and use untracked if they don't.

Problem solved! Now, let's move to a really complex example, one that most people will overlook unless they are explicitly aware of this issue.

Don't use `toSignal` in services to expose Observables as signals.

Lots of Angular applications do not use dedicated state management libraries like NgRx or Akita, and instead use services to manage the state of the application. This is a perfectly valid approach and can work really well. Most of such services use RxJS Observable-s (more specifically Subject-s or BehaviorSubject-s) to propagate changes to the state throughout the application. Of course, now, it might be tempting to use toSignal to expose the Observable as a signal, so that the rest of the application can consume it directly. However, this can lead to a bunch of problems. One glaring one is that the signal will not be automatically disposed of when the component which uses it is destroyed, and the Observable will keep emitting values, which might not be the desired outcome. Also, Observable-s in general are way more versatile, and some components might choose to handle such values in a slightly different way, which will not be possible if the value is exposed as a signal. Let's view an example:

@Injectable({
  providedIn: 'root'
})
export class MessagesStore {
  private messagesService = inject(MessagesService);
  private messages$ = this.messagesService.getMessages();
  messages = toSignal(this.messages$);

  unreadMessages = computed(() => {
    return this.messages().filter(message => !message.read);
  });

  addMessage(message: Message) {
    this.messagesService.addMessage(message);
  }
}

In this scenario, we are reading messages in a live stream from some external service (FireBase, WebSocket, does not matter), and the source will connect to the service when the first subscriber appears, and disconnect when the last subscriber is gone. This is a perfect use case for an Observable, but not really for a signal. While we got some benefits like using computed, we also made sure that the connection starts as soon as the service is created, and does not really ever stop, even when the components that consume those signals are destroyed, as it is the MessagesStore that is the subscriber, and it will not be destroyed until the application is closed.

Do use `toSignal` in components or expose state via connecting methods

So, what can we do about this problem? Well, one straightforward way of achieving this can be just not exposing signals from services at all and only call toSignal in components that consume the state. This way, we can be sure that the connection to the source will be established only when the component is created, and will be destroyed when all the consumer components are destroyed. This is a normal approach for most apps, however, it can be a bit tedious, as we might end up copy-pasting computed signals here and there (for instance, unreadMessages in the previous example).

So, instead we can opt for using specific methods that "connect" a component to the Observable, while still returning a signal that lives in the component's injection context, and not the service's. Let's see how we can modify the previous example to use this approach:

@Injectable({
  providedIn: 'root'
})
export class MessagesStore {
  private messagesService = inject(MessagesService);
  private messages$ = this.messagesService.getMessages();

  addMessage(message: Message) {
    this.messagesService.addMessage(message);
  }

  messages() {
    return toSignal(this.messages$);
  }

  unreadMessages(messages: Signal<Message[]>) {
    return computed(() => {
      return messages().filter(message => !message.read);
    });
  }
}

This way, we use the messages method to actually get the overall messages, and in the case of other computed properties, we can use other methods that return computed properties. In the component, we can simply do this:

@Component({
  selector: 'app-messages',
  template: `
    <ul>
      @for (message of unreadMessages(messages())) {
        <li>{{ message.text }}</li>
      }
    </ul>
  `
})
export class MessagesComponent {
  private readonly messages = inject(MessagesStore);
  messages = this.messagesStore.messages();
  unreadMessages = this.messagesStore.unreadMessages(this.messages);
}

This way, we can ensure the stream we subscribe to in the component is safely disposed of when the component is gone. Of course, there are other ways of achieving this, but we list the simplest ones here. You can try and find other ways that best suit your project and codebase, but remember not to use the toSignal function in a shared service.

Conclusion

This article is meant to be a small ruleset for Angular developers when they deal with signals. Signals truly are exciting, and lots of teams now increasingly adopt them in their projects, but they can have caveats, and it is important to be careful about them. If you know more such issues, feel free to comment - let's see how we can solve them together!

Small promotion

As you might already know, I was very busy writing a book last year. It is called "Modern Angular" and it is a comprehensive guide to all the new amazing features we got in recent versions (v14-v17), including standalone, improved inputs, signals (of course!), better RxJS interoperability, SSR, and much more. If this interested you, you can find it here. The manuscript is already entirely finished, with some polishing left to do, so it is currently in Early Access, with the first 5 chapters already published, and more to drop soon. If you want to keep yourself updated on the progress, you can follow me on Twitter or LinkedIn, where I will be posting whenever there are new chapters or promotions available.

Superpowers with Directives and Dependency Injection: Part 7

Armen Vardanyan — Tue, 30 Jan 2024 10:52:52 +0000

Original cover photo by Jr Korpa on Unsplash.

Lots of time has passed since I wrote my previous article covering the most powerful features of Angular directives (especially coupled with dependency injection), as I was focused on writing my book (more about it in the end), so this series was left essentially unfinished. However, having completed the book's draft, and with it being in Early Access now, I decided to go back to writing articles, as it is high time this series receives a useful ending. Today, there won't be much about dependency injection, however, we will dive deep into the world of Angular directive selectors, and see how we can use them to create really powerful directives.

Directive Selectors

All Angular directives have a selector, which specifies which HTML elements will the directive work with. Most often (in my experience, around 95% of scenarios), the selector is an attribute selector, which means that the directive will essentially be a custom HTML attribute.

However, in previous articles, we saw that directives can be much more than just custom attributes. So, let us finish this series by exploring all of the other selector types, how they can be used, and some possible pitfalls, all with real-life, useful examples.

Non-custom attribute selectors

In this scenario, instead of inventing a new attribute, we use an existing, valid HTML attribute. This is useful when we want to extend the functionality of an existing HTML element, without having to create a new attribute for it.

For instance, we might put ids on our HTML elements to mark things that are needed for E2E testing or something like that. However, some E2E test runners might be using different attributes, like data-test-id or data-qa-id. Instead of copy-pasting the same id attribute with a different value, we can create a directive that will add the attribute we need based on the id attribute:

@Directive({
  selector: '[id]',
  standalone: true,
})
export class TestingIdDirective {
  private readonly elRef = inject<ElementRef<HTMLElement>>(ElementRef);

  get id() {
    return this.elRef.nativeElement.id;
  }

  @HostBinding('attr.data-qa-id') get dataQaId() {
    return this.id;
  }
  @HostBinding('attr.data-test-id') get dataTestId() {
    return this.id;
  }
}

In this example, we just pick any element that has an id property, and then set its value unto two new attributes data-qa-id and data-test-id using a HostBinding. In the end, it does not matter what type of element we are working with, as long as it has an id property, we can use this directive on it. You can find a working reproduction of this example here.

Of course, this example is very broad, and that is why we have to discuss our next, more narrow one.

Attribute selectors with values

As we saw, the previous example targeted elements that just had an id attribute, without much regard as to what that particular id is. However, there can be other motives for us to use an attribute selector. Let's consider the following example: we have many inputs of type number, but in our application, we only want to allow positive numbers. If the user inputs a negative number, we want to outline the input with the color red. We have a CSS style that does exactly that when encountering a .invalid class, so, what is left to us is to target inputs of type number, check their value, and add or remove the .invalid class based on that. We can do that with the following directive:

@Directive({
  selector: 'input[type="number"]',
  standalone: true,
})
export class PositiveNumberDirective {
  private readonly elRef = inject<ElementRef<HTMLInputElement>>(ElementRef);
  @HostBinding('class.invalid') value = false;

  @HostListener('input') 
  onInput() {
    const value = this.elRef.nativeElement.value ?? 0;
    this.value = (+value) < 0;
  }
}

Again, we do not have to do much here other than importing the directive into the component we want to use it with, as it will automatically bind to the inputs of type number and add the .invalid class to them if the value is negative, which we will know because of the HostBinding. You can find a working reproduction of this example here.

Next, let us discuss an often-overlooked use case of directive selectors.

Class selectors

Yes, you might have not heard about them, but directives can actually bind to CSS classes too! Consider the following scenario: in the previous example, we added the .invalid class to the input, but now we want to add some logic to all the .invalid elements in the application. For example, we might want to add a tooltip to them, which is also accomplished with a separate directive that already exists. We can achieve this with the power of Host Directives combined with a class selector:

@Directive({
  selector: '.invalid',
  standalone: true,
  hostDirectives: [TooltipDirective],
})
export class InvalidTooltipDirective implements AfterViewInit {
  private readonly tooltipRef = inject(TooltipDirective);

  ngAfterViewInit() {
    this.tooltipRef.title = 'The value is invalid';
  }
}

This will kinda achieve what we want, however has a glaring problem, which we will discuss shortly after we cover all the selector types. At the moment, let's focus on our next level of knowledge about directive selectors - that is way more complex and versatile ones.

Complex selectors

So far, we discussed selectors that specifically target some HTML elements. This is handy, but there are scenarios where we might want to target more than one type of element, or maybe exclude some elements from an otherwise too broad selector. Let's see how we can achieve that.

Combining selectors

There are two ways of combining selectors to either broaden the "target audience", so to speak, of a directive: specifying a more concrete attribute or using multiple selectors. We already discussed the first scenario (the input[type="number"] in the PositiveNumberDirective two examples prior), so let us just talk about using multiple selectors.

Let's say we have a social media application built with Angular, where users can interact and talk to each other. Each user has an online status, which is determined by a number of things (just having a page open is not enough to consider a user to be "online" at the moment). One of those things is whether the user is typing something. There are a number of places where a user can type, for example, input-s and textarea-s. We want a directive that will capture that event and send a quick HTTP call to the server notifying that the user is currently online (there are a bunch of optimizations we can do about this, for instance, checking if the user is not already marked as "online", and making sure we do not send an HTTP call on each keystroke, but we will skip them for the sake of brevity, as those are out of the scope of this article). Let's build such a directive:

@Directive({
  selector: 'input, textarea',
  standalone: true,
})
export class OnlineStatusDirective {
  private readonly userService = inject(UserService);

  @HostListener('input') 
  onInput() {
    this.userService.setOnlineStatus(true);
  }
}

And again, as with other directives, just importing it into the component we want to use it with will be enough to make it work and target multiple types of elements. You can find a working reproduction of this example here. Let's now move on to our final entry, which helps narrow down the selector's specificity instead of broadening it.

Selector negation

Sometimes, we write a selector that targets all the elements that we want but encounters this one element that it just shouldn't apply to, despite matching. For instance, in the second example in this article, the PositiveNumberDirective, targeted all the inputs of type number, but we might have a specific input that we do not want to apply this directive to.

Our first thought might be to add an Input property to signify if the directive should actually work or not:

@Directive({
  selector: 'input[type="number"]',
  standalone: true,
})
export class PositiveNumberDirective {
  @Input() enabled = true;
  private readonly elRef = inject(ElementRef);

  @HostBinding('class.invalid') get value() {
    const value = this.elRef.nativeElement.value ?? 0;
    return this.enabled && (+value) < 0;
  }
}

This works, but it has three downsides:

We have to provide the boolean with a value each time we don't want the directive to work, which is not a big deal, but it is still a bit of a hassle.
We might have to use the enabled property multiple times in the directive, as it possibly can have several @HostListener-s, @HostBinding-s, etc. This makes the directive harder to read and understand.
Finally, the directive still gets applied, making Angular spend some unnecessary computational power on it.

Now, let's see how we can solve this problem with a selector negation, more commonly known as the :not() selector. We can use it like this:

@Directive({
  selector: 'input[type="number"]:not([allowNegative])',
  standalone: true,
})
export class PositiveNumberDirective {
  private readonly elRef = inject(ElementRef);

  @HostBinding('class.invalid') get value() {
    const value = this.elRef.nativeElement.value ?? 0;
    return (+value) < 0;
  }
}

As we can see, the directive's code/logic remained the same, we just changed the selector, excluding all elements that have the allowNegative attribute. Now, we can apply this "negative" attribute whenever we want to allow negative numbers, and the directive will not apply to that input.

<input type="number" allowNegative />

The :not() selector specifier can accept any type of selector that is valid for a directive selector. You can find a working reproduction of this example here.

Finally, as we have covered all of the scenarios, it is time we briefly discuss some pitfalls we might encounter when working with directives.

The Pitfalls

With all the power of the selectors we saw in this article, it might be tempting to assume that it works exactly like a CSS selector. However, this could not be further from the truth. Let's see three main scenarios where this falls short.

Cannot target child-parent relations

While it certainly would be useful, it is impossible to target elements that are children of some specific parents only. We could try this:

@Directive({
  selector: 'div > button',
  standalone: true,
})
export class ParentChildDirective {
  @HostListener('click')
  onClick() {
    console.log('clicked')
  }
}

And then put this template:

<div>
  <button>Directive is applied</button>
</div>
<button>Directive should not be applied</button>

When we click on the first button, we might rejoice as it will log "clicked". However, it will also log when we click on the second button, which is not inside a div element. This is because Angular just picked the last element from the confusing (from its perspective) selector, and applied the directive to it. So, no complex parent-child (or sibling, ancestor, descendant, etc.) relations for directive selectors. Remember, Angular directive selectors are not exactly CSS selectors.

Directives cannot be applied dynamically

While it might certainly seem so, directives won't be "added" and "removed" as soon as an HTML element begins to match a certain selector. This becomes readily obvious with classes as directive selectors. When we built the InvalidTooltipDirective, we mentioned that it has a glaring problem; the thing is, it might create the impression that whenever an element obtains the invalid class, the directive will automatically apply to it; this is simply not the case: Angular directives get applied at compile-time, meaning this directive will be applied to elements that already have the invalid class, but not to those that will obtain it later. You can see an example of how this works (or not works) here.

Structural directives can only be attributes

With structural directives, what happens is that Angular uses some clever syntactic sugar: an element marked with an asterisk automatically becomes wrapped in an <ng-template>. So, if we just type, say, <div * class="some-class">Text</div>, it will automatically translate to <ng-template [class]="some-class"><div>Text</div></ng-template>. This is why structural directives can only be attributes, as they are applied to the <ng-template> element, not the element that is inside it. We cannot, for instance, target the div element in the previous example with a structural directive, as it is not the element that is marked with the asterisk. While this certainly restricts us from accomplishing some things, it is not very big of a deal, as we rarely need to do any logic in this regard.

Conclusion

I enjoyed writing this article series, and I hope it proved useful to readers as well. Angular directives are super powerful and underused, so I hope that this series will help you everyone them more often. My experience proved that doing this greatly simplifies codebases, especially the templates.

Small promotion

As I mentioned at the beginning of the article, I was busy writing a book. It is called "Modern Angular" and it is a comprehensive guide to all the new amazing features we got in recent versions (v14-v17), including standalone, improved inputs, signals (of course!), better RxJS interoperability, SSR, and much more. If this interested you, you can find it here. The manuscript is already entirely finished, with some polishing left to do, so it is currently in Early Access, with the first 5 chapters already published, and more to drop soon. If you want to keep yourself updated on the progress, you can follow me on Twitter or LinkedIn, where I will be posting whenever there are new chapters or promotions available.

Superpowers with Directives and Dependency Injection: Part 6

Armen Vardanyan — Tue, 02 May 2023 09:08:42 +0000

Original cover photo by Ivan Bandura on Unsplash.

It's time for the 6th installment of this article series about Angular directives - and their almost magical superpowers.
Today we are going to explore a less popular, but very, very common and valid use case scenario - bringing business logic into the directives.

Introduction

First of all, let's reflect on what we have already done, and understand how today's cases are fundamentally different.

In previous articles, we created directives that did some specific, reusable, and very useful things.

For example, we built a directive that

checked for password strength
emitted custom events when the host element scrolled into view
transported a template view into another component
displayed a loader
added some default inputs onto existing components

As you can see, there is a common theme for all these cases - all those directives are super-reusable in the sense that they can be dropped in any project and just work; non of them really contain any business logic. But in a lot of cases, with real-life projects, it is the business logic that we want to be reusable and easily shareable. So what scenarios are there?

Using directives to handle permissions

Imagine that our app has permissions to enable or disable certain features. For example, we might have a feature that allows users to edit their profile, but only if they have the right permissions. We have a few PermissionService that has a hasPermission method that takes a permission name and returns a boolean. We could use this service in our component like this:

@Component({
  selector: 'app-profile',
  template: `
    <div *ngIf="hasPermission('edit-profile')">
      <button (click)="editProfile()">Edit profile</button>
    </div>
  `
})
export class ProfileComponent {
  constructor(private permissionService: PermissionService) {}

  hasPermission(permissionName: string) {
    return this.permissionService.hasPermission(permissionName);
  }

  editProfile() {
    // ...
  }
}

But now every time we want to check for this or that permission, we need to inject the service, maybe write a wrapper method, call it from the template, or some other mildly cumbersome way. Also, if the way how we access those permissions changes (for example, the service now has a different API interface), we might face a pretty large refactoring. Also, if were have some sort of state management solution that works with Observables (like NgRx, for instance), our code will become even more complex.

So how do we deal with this?

Well, wouldn't it be nice if we could just do this:

@Component({
  selector: 'app-profile',
  template: `
    <div *hasPermission="'edit-profile'">
      <button (click)="editProfile()">Edit profile</button>
    </div>
  `
})
export class ProfileComponent {
  editProfile() {
    // ...
  }
}

So now we can pass the permission name as an input to the directive, and the directive will handle the rest. Let's see how we can do this.

First, we need to create a directive that injects the PermissionService and has an input property that will accept the permission name
next, we will add ngIf as a HostDirective so it can handle showing/hiding the template
and finally, we will inject the reference to the NgIf directive, and pass the resulting boolean to it

Let's do this:

@Directive({
  selector: '[hasPermission]',
  standalone: true,
  hostDirectives: [NgIf],
})
export class HasPermissionDirective {
  private readonly permissionService = inject(PermissionService);
  private readonly ngIfRef = inject(NgIf);

  @Input() 
  set hasPermission(permissionName: string) {
    // we can use any other approach here
    this.ngIfRef.ngIf = this.permissionService.hasPermission(
      permissionName,
    );
  }
}

Now, our directive works almost perfectly. What do we need to add? Of course, a possibility to handle the case when the user does not have the permission. We can do this by adding an else template to our directive:

@Directive({
  selector: '[hasPermission]',
  standalone: true,
  hostDirectives: [NgIf],
})
export class HasPermissionDirective {
  private readonly permissionService = inject(PermissionService);
  private readonly ngIfRef = inject(NgIf);

  @Input() 
  set hasPermission(permissionName: string) {
    this.ngIfRef.ngIf = this.permissionService.hasPermission(
      permissionName,
    );
  }

  // the improtant part
  @Input() 
  set hasPermissionElse(template: TemplateRef<any>) {
    this.ngIfRef.ngIfElse = template;
  }
}

Now, we essentially just do the business logic and pass the result to the NgIf directive. Here is a working example with a preview:

Using directives to handle shared data in components

Imagine we use some UI library that allows us to show dropdowns:

@Component({
  selector: 'app-profile',
  template: `
    <div>
      <third-party-dropdown
        [items]="dropdownItems"></third-party-dropdown>
    </div>
  `
})
export class ProfileComponent {
  dropdownItems = [
    {
        label: 'Item 1',
        value: 1
    },
    {
        label: 'Item 2',
        value: 2
    }
  ];

}

And in some cases, we need to pass the same list of options to multiple dropdowns. For example, the same list of permissions we encountered earlier in this article could be really useful in lots of places:

@Component({
  selector: 'app-profile',
  template: `
    <div>
      <third-party-dropdown
        [items]="permissions"></third-party-dropdown>
    </div>
    <div>
  `
})
export class SomeComponent {
    permissionService = inject(PermissionService);
    permissions = this.permissionService.getPermissions();
}

And then we could really see this same code in multiple places throughout our app. So how can we make this more reusable? Well, we could create a component that will wrap the dropdown and accept the list of items as an input:

<app-wrapper-around-third-party-dropdown
  [items]="permissions"></app-wrapper-around-third-party-dropdown>

But that would introduce a set of problems:

CSS encapsulation
Having to pass eventually all of the third-party dropdown's inputs and outputs up and down
More complexity in our templates

So what can we do instead? Well, we can create a directive that will inject the list of items into the third-party dropdown:

@Directive({
  selector: 'third-party-dropdown[permissionList]',
  standalone: true,
})
export class PermissionsDropdownDirective implements OnInit {
  thirdPartyDropdown = inject(ThirdPartyDropdown);
  permissionService = inject(PermissionService);

  ngOnInit() {
    this.thirdPartyDropdown.items = 
      this.permissionService.getPermissions();
  }
}

And now we can use it like this:

<third-party-dropdown permissionList></third-party-dropdown>

And that's it! Now our template is simple, the third-party-dropdown is still as it used to be, and we got additional reusable functionality for it.

Here is the example with a preview:

Conclusion

We have explored a huge amount of possibilities that directives give us. While there are plenty more, this much is fairly enough for projects of different sizes, so this article series is nearing its end. In the next and last one, we will talk in detail about directive selectors, what we can use, how can we combine different selectors, and what are some pitfalls or where we cannot use a certain selector. Stay tuned!

Signals: what this means for NgRx

Armen Vardanyan — Mon, 17 Apr 2023 10:33:01 +0000

Original cover photo by Carlos Alberto Gómez Iñiguez on Unsplash.

On April 4th, 2023, the Angular team officially launched an RFC for the new reactive primitive, signals, that will arrive as a developer preview in Angular v16. This could mean a beginning of a new era of Angular development, less dependence on RxJS, more granular change detection, and maybe even zoneless applications.

But what this means for us, NgRx enthusiasts? Let's find out.

Note: we assume that the reader is already familiar with the concept of Signals. If not, I suggest reading the aforementioned RFC, or at least the Sub-RFC 2 (which talks about the signals themselves) and Sub-RFC 4 (which talks about the RxJS-signals interoperability).

How NgRx might work with signals

First of all, we need to keep in mind that Angular v16 is going to introduce a new package, rxjs-interop, which will contain functions that will allow to conversion of RxJS observables to signals and vice versa. As NgRx is built on top of Observable-s, NgRx itself doesn't really need an innate support of signals. Essentially, instead of this:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data$ | async }}</p>
  `,
})
export class DataComponent {
  store = inject(Store);  
  data$ = this.store.select(selectData);
}

We can do this:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data() }}</p>
  `,
})
export class DataComponent {
  store = inject(Store);  
  data = toSignal(this.store.select(selectData));
}

And that would be it.

However, there are two concerns

The code looks a bit verbose, and it will be tedious to call toSignal all the time, raising a question - why are we even using Observable-s at all?
What if I want to build an entire store on signals?

Let's see how the NgRx team proposes addressing these issues. We will go chronologically, so will start with the second point.

NgRx Signal Store

On March 6, just 2 days after the Signals RFC, the NgRx core team published their own Signals RFC, titled NgRx SignalStore. Give it a read if you want more details, but here we will cover it in a shorter way.

You will be able to define a store via a special function, createSignalStore, and add properties and features to it with other helper functions, like withState, withEffects, etc. Here is a small snippet:

export const counterStore = createSignalStore(
    withState<CounterState>({ count: 0 }),
    withComputed((state) => ({
        doubleCount: state.count * 2,
    })),
);

So if we inject this into our component, we would have access to the count and doubleCount signals, which we can use in our template:

@Component({
  selector: 'app-counter',
  template: `
    <p>{{ counterStore.count() }}</p>
    <p>{{ counterStore.doubleCount() }}</p>
  `,
})
export class CounterComponent {
  counterStore = inject(CounterStore);
}

And we could update the state with the update function:

counterStore.update((state) => ({ count: state.count + 1 }));

Or we could choose to add custom updater methods:

export const counterStore = createSignalStore(
    withState<CounterState>({ count: 0 }),
    withComputed((state) => ({
        doubleCount: state.count * 2,
    })),
    withUpdaters(() => ({
        increment: (state) => ({ count: state.count + 1 }),
    })),
);

And use these updater methods in components and so on. It has way more functionality to it, so feel free to explore the RFC, or ask questions either there or here in the comments.

Existing NgRx stores

Let's now address the first bullet point. If we already have an existing application that uses the conventional, RxJS-based NgRx Store, but we really want to seamlessly use signals instead of Observable-s an async pipe without too much code, will NgRx help? Turns out they will

On March 12, the NgRx team published another RFC, that sheds light on how it will support signals for the conventional NgRx Store. The RFC is titled Integration with Angular Signals and NgRx packages, so again, give it a read if you want more details. But in two words, essentially the Store "service" will get another method apart from select, named selectSignal, which will work in exactly the same way as select, but will return a Signal instead of an Observable. The same method will also be added to ComponentStore, working in the same fashion.

So continuing the previous example, now we can just do the following:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data() }}</p>
  `,
})
export class DataComponent {
  store = inject(Store);  
  data = this.store.selectSignal(selectData);
}

And that's it. The rest of the store will remain exactly as before, no hassle, no heavy migrations.

What all of this means?

I would like to address two points:

1. Store values would now be directly accessible everywhere.

If we visit the NgRx Store source code and take a look at the store itself, we might see that the Store injectable extends RxJS Observable, and not BehaviorSubject, meaning it does not really "hold on to", or at least, give access to the current state in the Store. So something like this would be impossible:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data$ | async }}</p>
  `,
})
export class DataComponent {
  store = inject(Store);  
  someService = inject(SomeService);
  data$ = this.store.select(selectData);

  useData() {
    // do something with this.data
    this.someService.doSomething(this.data$);
  }
}

Now this will not work, because this.data$ is an Observable, so an event-driven wrapper of the value, and not the value itself. So if we want to use the value in a synchronous manner, we would have to subscribe to it, and then unsubscribe, which is not ideal. Or we can do something like this:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data$ | async }}</p>
    <button *ngIf="data$ | async as data"
            (click)="useData(data)">
       Use data
    </button>
  `,
})
export class DataComponent {
  store = inject(Store);  
  someService = inject(SomeService);
  data$ = this.store.select(selectData);

  useData(data: Data) {
    // do something with data
    this.someService.doSomething(data);
  }
}

This will work, but not every scenario is addressed with this solution, and things can be more complex. However, with Signals, we can always access the current value:

@Component({
  selector: 'app-data',
  template: `
    <p>{{ data() }}</p>
    <button (click)="useData()">Use data</button>
  `,
})
export class DataComponent {
  store = inject(Store);  
  someService = inject(SomeService);
  data = this.store.selectSignal(selectData);

  useData(data: Data) {
    // we can now read from the signal
    this.someService.doSomething(data()); 
  }
}

And this is something that can (and probably will) mean some overhaul in how we use the store data in the component code itself.

2. Some best practices might need to be rethinked

NgRx has its own eslint plugin, which introduces some (rather strict) rules. One rule is that we should not use RxJS operators to map and modify the state, and instead rely on custom selectors. So the following is considered a bad practice:

export class Component {
  name$ = this.store
    .select(selectLoggedInUser)
    .pipe(map((user) => ({ name: user.name })));
}

And instead, we should do something like this:

// in selectors.ts:
export selectLoggedInUserName = createSelector(
  selectLoggedInUser,
  (user) => user.name
)

// in component:
export class Component {
  name$ = this.store.select(selectLoggedInUserName)
}

So the plugin will successfully prevent us from doing this with RxJS-based store data, but with signals, we can kinda work around it using the computed function:

export class Component {
  user = this.store.selectSignal(selectLoggedInUser);

  name = computed(() => ({ name: this.user().name }));
}

Whether this is a bad practice or not still remains to be seen, and is up for debate. In my opinion, we should stick with the previous practice of keeping store calculations on the store side of things, and use the component only for presentation. But this is just my opinion, and I would love to hear yours in the comments computed only for combining store signals with local signals.

Conclusion

First of all, I would like to extend my appreciation to the NgRx Core Team and all other contributors for once again staying on top of the things and delivering top-notch features quickly and efficiently. I am really excited to see how this will play out, and I am sure that the community will benefit from this greatly.

Signals are super exciting, and we are in an era of lots of discussion, decision-making, and experimentation. I am sure that we will see more and more of this in the future, and I am really looking forward to it. In this spirit, you are welcome to comment on this article, NgRx RFC-s, and Angular Signal RFC-s to discuss, understand, and learn

Stay tuned for other developments!

Superpowers with Directives and Dependency Injection: Part 5

Armen Vardanyan — Mon, 03 Apr 2023 09:50:18 +0000

Original cover photo by Pawel Czerwinski on Unsplash.

Here we are, part 5 of our series dedicated to Angular's directives! In previous articles we have already explored various applications of directives and dependency injection. This time around we shall see how we can use directives to help components communicate on the most hard-to-reuse level - the template.

So, let's get started with today's use case.

Dynamic shared templates

Imagine a fairly standard application UI structure: we have a header, a footer, maybe a sidebar, and some content in a main tag. The header component is of high interest to us, because while it is the same for all pages, for certain pages it might require the addition of some custom templates. For example, if we are on the "Order Details" page, it may display the relevant product list, while on the "Shopping Cart" page it may display the cart summary. In other words, we need to be able to dynamically add some content to the header.

A relatively naive thing to do would be to subscribe in some way to the router and change the header template accordingly. But this has a couple of downsides:

Header component will become bloated
There won't be a clear way for components to communicate data to the header for their related pieces of the template
We might need this sort of solution for other pages, meaning more bloat

What if we could just create the template in the component itself, and then somehow tell it to display that content in the header instead of its own template?

Turns out, this is entirely possible!

Let's see how

The Idea

For this example, we are going to use Angular Material, and specifically, its Portals feature. Portals come from the @angular/cdk package and allow us to render a template outside of its original context. In our case, we will use them to render a template in the header component.

Note: this could be done without portals, or, anyway, without the @angular/cdk package, but this approach would simplify a couple of things. You are welcome to try this out with just ng-template-s

So, what is the general idea behind our solution? Three things

An ng-template in the header in the correct place where want the dynamic content to be rendered, with the portal directive added to it
Our own custom directive that will capture a template from any other component
A service that would communicate from the directive instance to any component (the header in our particular place) that wants to use the template

Let's start with the service, that actually shares the portal between consumers:

The Implementation

The Service

@Injectable({providedIn: 'root'})
export class PortalService {
    private readonly portal$ = new Subject<
      {portal: Portal<unknown> | null, name: string}
    >();

    sendPortal(name: string, portal: Portal<unknown> | null) {
        this.portal$.next({portal, name});
    }

    getPortal(name: string) {
        return this.portal$.pipe(
            filter(portalRef => portalRef.name === name),
            map(portalRef => portalRef.portal),
        );
    }
}

Let's understand what goes on here. First of all, we have the portal$ subject, which will take an object that describes the portal; it will receive a name (where we want to show the template, say, header), and the portal itself. The sendPortal method is used to send the portal to the service so that subscribers can use it, and the getPortal method is used to get a particular portal from the service. The getPortal method is quite simple, but it makes the service (and directive that will use it) very reusable so that we can send different templates to different places throughout the application.

So now, that we have the service, let's create the header component and use this service to display the content:

The Header Component

@Component({
    selector: 'app-header',
    standalone: true,
    template: `
        <mat-toolbar>
            <span>Header</span>
            <ng-template [cdkPortalOutlet]="portal$ | async"/>
        </mat-toolbar>
    `,
    imports: [MatToolbarModule, PortalModule, AsyncPipe],
})
export class HeaderComponent {
    private readonly portalService = inject(PortalService);
    portal$ = this.portalService.getPortal('header');
}

As you can see, the component selects its specific portal template via our service, then uses the cdkPortalOutlet directive to render it. We then use the async pipe to subscribe to the portal observable and render the template when it is available. (note: if we pass null to cdkPortalOutlet, it will render nothing, that is going to be important in the directive).

As now we have ourselves on the receiving side of things, we can go on and create the directive that does the heavy lifting.

The Directive

As we are going to work with templates, the directive will be a structural one. We will call it portal, and it will take an input with the same name, which will be the name of the portal we want to send the template to.

@Directive({
    selector: "[portal]",
    standalone: true,
})
export class PortalDirective implements AfterViewInit, OnDestroy {
    private readonly templateRef = inject(TemplateRef);
    private readonly vcRef = inject(ViewContainerRef);
    private readonly portalService = inject(PortalService);
    @Input() portal!: string;

    ngAfterViewInit() {
        const portalRef = new TemplatePortal(
          this.templateRef,
          this.vcRef,
        );
        this.portalService.sendPortal(this.portal, portalRef);
    }

    ngOnDestroy() {
        this.portalService.sendPortal(this.portal, null);
    }
}

As you can see, we inject both TemplateRef and ViewContainerRef to create a TemplatePortal instance, which we then send to the service in the ngAfterViewInit lifecycle hook. Actually, we do not do any manipulations on the portal, or the template, we delegate it all to the TemplatePortal constructor. On ngOnDestroy, we send null to the service, so that the header component will remove the now obsolete template.

Now, we can try this in action:

The Usage

@Component({
    selector: 'app-some-page',
    standalone: true,
    template: `
        <main>
            <span *portal="'header'">
                Custom header content
            </span>
            <span>Some content</span>
        </main>
    `,
    imports: [PortalDirective],
})
export class SomePageComponent {}

So in this example, the "Custom header content" text will not be rendered in this component, but rather, in the header component. Notice we did not import the HeaderComponent, we did not put it in the template of the SomePageComponent, or do anything else boilerplate-ish, we just dropped the portal directive on some template, and that's it.

Another cool aspect of this is that the template that was "teleported" is still "owned" by the component in which it was written, meaning data bindings work as expected so that we can have dynamically changing data "portal-ed" somewhere else, like this:

@Component({
    selector: 'app-some-page',
    standalone: true,
    template: `
        <main>
            <span *portal="'header'">{{someData}}</span>
            <button (click)="changeContent()">
                Change Content
            </button>
        </main>
    `,
    imports: [PortalDirective],
})
export class SomePageComponent {
    someData = 'Custom header content';

    changeContent() {
        this.someData = 'New content';
    }
}

Now, if we go on and click on the button, the header will change its content to "New content".

You can view this example in action here:

Click on the links to navigate from one page to another, and notice how the content in the header is changed dynamically

Conclusion

This time, we explored a more specific use case for an Angular directive. Directives, as mentioned multiple times throughout this series, are a very powerful tool, and one that is criminally underused. I hope this article will help you to understand how to use them, and how to create your own custom directives. Stay tuned for more use cases in the future!

Superpowers with Directives and Dependency Injection: Part 4

Armen Vardanyan — Mon, 27 Mar 2023 08:24:29 +0000

Original cover photo by Justin Wolff on Unsplash.

Welcome to the fourth part of my exploration of Angular directives! We have explored directive usage in template-local logic, structural directives instead of components, and using directives to extend the functionality of existing components and/or elements. This time around, we are going to find out how directives can be used to work with events and add events to components that do not really exist.

Let's get started with two interesting use cases!

A click-away directive

Sometimes we need to know when the user clicked outside of a given element. This is a common use case for dropdowns, modals, and other components that need to be closed when the user clicks outside of them. This can also be useful in a gaming app, or an app that shows videos (clicking away pauses the video, etc). We could do something inside of the component that has this functionality, but that would not be a very reusable piece of logic, considering we might need something like that in other components too. So, let's build a directive for this!

It is going to:

take the target element
inject the Renderer2 instance to be able to listen to events
listen to all click events on the document element
if the target is not a descendant of the clicked element (thus being outside of it), emit an event
dispose of the event listener when the directive is destroyed

Here is our implementation:

@Directive({
  selector: '[clickAway]',
  standalone: true,
})
export class ClickOutsideDirective implements OnInit, OnDestroy {
  private readonly elRef: ElementRef<HTMLElement> = inject(
    ElementRef,
  );
  private readonly renderer = inject(Renderer2);
  private readonly document = inject(DOCUMENT);

  @Output() clickAway = new EventEmitter<void>();
  dispose: () => void;

  ngOnInit() {
    this.dispose = this.renderer.listen(
      this.document.body,
      'click',
      (event: MouseEvent) => {
        if (!this.elRef.nativeElement.contains(
          event.target as HTMLElement
        )) {
          this.clickAway.emit();
        }
      }
    );
  }

  ngOnDestroy() {
    this.dispose();
  }
}

As you can see, the logic is very straightforward. We inject the ElementRef instance to get the target element, the Renderer2 instance to be able to listen to events, and the DOCUMENT token to get the document element. We then listen to all click events on the document element, and if the target is not a descendant of the clicked element (we check it using the Node.contains method), we emit a clickAway event. We then dispose of the event listener in ngOnDestroy.

Now, the cool thing about naming the EventEmitter the same as the directive selector is that we can just add this custom event on any element we like:

<div (clickAway)="onOutsideClick()">
  <h1>Click outside of me!</h1>
</div>

Works like magic, as if it were a native event like (click) or (mouseover)!

Here is a working example with a preview:

Now, on to our next example.

Handling scrolling

Now, an often guest in different web apps is the ability to perform actions (like loading more content) when certain elements become visible in the view. This is a common use case for infinite scrolling, lazy loading, and other similar features. Again, as in the previous example, let us explore solutions that would allow us to reuse this logic in multiple places. Essentially, what we want is to have a custom event that would fire as soon as the element enters the viewport.

We are going to use an IntersectionObserver for this, which allows observing whether a given element is intersecting with (essentially being visible inside) another element or the entire viewport. This will be a simplified example (lots of nuances can be present based on how exactly we want this to work), but the basic is that we can

take a target element
listen to all of its intersection changes
If it is interesecting with the viewport, emit an event

Now, here is an implementation:

@Directive({
  selector: '[scrollIntoView]',
  standalone: true,
})
export class ScrollIntoViewDirective implements OnInit, OnDestroy {
  @Input() threshold = 0.25;
  @Output() scrollIntoView = new EventEmitter<void>();
  elRef = inject(ElementRef);
  observer: IntersectionObserver;

  ngOnInit() {
    this.observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            this.scrollIntoView.emit();
          }
        });
      },
      { threshold: this.threshold }
    );

    this.observer.observe(this.elRef.nativeElement);
  }

  ngOnDestroy() {
    this.observer.disconnect();
  }
}

Here, we create an IntersectionObserver instance, and we listen to all of its changes. If the target element is intersecting with the viewport, we emit a scrollIntoView event. We then disconnect the observer in ngOnDestroy. As you can see, the implementation is fairly similar to what we did with the ClickAway directive, the difference being the "business logic". Here is how we can use it in a template:

<div>
  Really long content goes here
  <div (scrollIntoView)="loadMoreContent()">
    Dynamic content goes here
  </div>
</div>

Again, works like magic as any other native event!

Here is the preview:

Note: the example shows a long list of div-s, scroll to the bottom to see a text message being logged into the console.

Conclusion

As our exploration goes on, we learn more and more interesting use cases for Angular directives. In the next one, we will learn how to show templates outside of our components using directives and the concept of Portals. Stay tuned!

Superpowers with Directives and Dependency Injection: Part 3

Armen Vardanyan — Tue, 21 Mar 2023 12:31:15 +0000

Original cover photo by USGS on Unsplash.

So here we are, at the third part of my article series about directives and dependency injection. In previous parts, we explored how to use directives to maintain and export local state in templates and reuse it, and how to use structural directives to simplify our templates. In this one, we are going explore how we can use directives to hijack existing elements and components to add or modify functionality.

So, let's explore use cases.

Use case 1: Hijacking existing elements

Imagine the following scenario - we are maintaining a website that displays lots of content, and also has lots of internal pages. That content often contains links to external resources, and also obviously links for internal navigation between pages. Now, imagine, we want to (almost) always open external links in a new tab (for example, not to disrupt the user's reading flow and general UX). So, obviously, the simplest solution would be to just add target="_blank" to all external links. This is okay, but obviously is a bit tedious, and also will require the developers always to remember to do that and pass this knowledge to future team members. What if we could automate it?

So, naturally, we need a directive that will

Bind to all a elements
Determine if the link in its href attribute is external
Add target="_blank" to the element if it is
Possible add a way to exclude some links from this behavior
Also keep in mind that some links can change dynamically

So, let's first examine how we can determine if a link is external or not. It can be done by a fairly simple function:

function isLinkExternal(url: string) {
  return new URL(url).origin !== location.origin;
}

We are leveraging the URL constructor to parse the URL and check its origin.

Next, let's build a simple directive that can add target="_blank" to external links:

@Directive({
  selector: 'a',
  standalone: true,
})
export class ExternalLinkDirective implements 
  OnInit, AfterViewInit, OnDestroy {
  private readonly elRef: ElementRef<HTMLAnchorElement> = inject(
    ElementRef,
  );
  @HostBinding('target') 
  target: '_blank' | '_self' | '_parent' | '_top' | '';

  ngOnInit() {
    this.setAnchorTarget();
  }

  private setAnchorTarget() {
    if (isLinkExternal(this.elRef.nativeElement.href)) {
      this.target = '_blank';
    }
  }
}

Now, this directive actually does 80% of what we want to achieve and doesn't require any changes in the template. We use HostBinging to set the target attribute on the targeted a element. You can read more about how the HostBinding decorator works in the official documentation.

Now, let's make it so we can exclude some links from this behavior. We can do it by adding an exclude input to the directive, but that would actually not be the best approach. See, this would require passing an actual boolean value in the template, and we (obviously) are too lazy for that. We can do the following:

@Directive({
  selector: 'a:not([noBlank])',
  standalone: true,
})
export class ExternalLinkDirective implements
  OnInit, AfterViewInit, OnDestroy {
  private readonly elRef: ElementRef<HTMLAnchorElement> = inject(
    ElementRef,
  );
  @HostBinding('target') 
  target: '_blank' | '_self' | '_parent' | '_top' | '';

  ngOnInit() {
    this.setAnchorTarget();
  }

  private setAnchorTarget() {
    if (isLinkExternal(this.elRef.nativeElement.href)) {
      this.target = '_blank';
    }
  }
}

The :not() selector is a css selector supported by Angular Directive's API-s which allows the exclusion of some elements. Here we exclude all elements with noBlank attribute. Now, we can just add noBlank to the links we don't want to open in a new tab:

<a href="https://google.com">Google</a>
<a href="https://google.com" noBlank>Google</a>

The first link will open in a new tab, the second one won't. Now, most of our issues are completed, but here is a catch. What if we have something like this:

<a [href]="someUrl">Google</a>

Here, the href attribute is dynamically bound to the someUrl property, therefore, if the link changes in the future dynamically, the directive will not reevaluate the link, possibly resulting in bugs.

So what we want is to be notified about the href attribute change, and reevaluate the link. Notably, Angular does not have a built-in way to do that, but we can use the MutationObserver API to do exactly this. A MutationObserver is a class that can take an HTML element, observe changes to its attributes, child nodes, and so on, and notify us about them, allowing us to run callbacks on those events. So, let's add a MutationObserver to our directive and make it interop with Angular:

@Directive({
  selector: 'a:not([noBlank])',
  standalone: true,
})
export class ExternalLinkDirective implements
  OnInit, AfterViewInit, OnDestroy {
  private readonly elRef: ElementRef<HTMLAnchorElement> = inject(
    ElementRef,
  );
  private readonly observer = new MutationObserver(() =>
    this.setAnchorTarget()
  );
  @HostBinding('target') 
  target: '_blank' | '_self' | '_parent' | '_top' | '';

  ngOnInit() {
    this.setAnchorTarget();
  }

  ngAfterViewInit() {
    this.observer.observe(this.elRef.nativeElement, {
      attributes: true,
      subtree: false,
      childList: false,
    });
  }

  ngOnDestroy() {
    this.observer.disconnect();
  }

  private setAnchorTarget() {
    if (isLinkExternal(this.elRef.nativeElement.href)) {
      this.target = '_blank';
    } else if (this.elRef.nativeElement.target === '_blank') {
      this.target = '';
    }
  }
}

This code might feel a bit overwhelming, so let's examine what is being done here:

We create a MutationObserver instance, and pass a callback to it. This callback will be called every time the observed element changes. In our case, we want to reevaluate the link every time it changes, so we just call setAnchorTarget in it.
In the ngAfterViewInit lifecycle hook, we start observing the element. We pass an object with the following options:
1. attributes: true - we want to observe attribute changes
2. subtree: false - we don't want to observe changes in child nodes
3. childList: false - we don't want to observe changes in direct child nodes
In ngOnDestroy we disconnect the observer, so it stops observing the element - obviously, it no longer exists
We made a slight modification to the setAnchorTarget method. Now, if the link is not external, we remove the target attribute from the element. This is needed for the cases when another value is provided in the template for the target attribute, like target="_self" or whatever.

Here is a full working example of this directive with a preview:

Use case 2: hijacking existing components

This part is completely inspired by a blog post written by Tim Deschryver, where he discusses how to use directives to extend functionality on components that we didn;t write. In that example, a directive is used to hijack the functionality of a Calendar component from the PrimeNG UI library. Here is the example from this article:

import { Directive } from '@angular/core';
import { Calendar } from 'primeng/calendar';

@Directive({
    selector: 'p-calendar',
})
export class CalenderDirective {
    constructor(private calendar: Calendar) {
        this.calendar.dateFormat = 'dd/mm/yy';
        this.calendar.showIcon = true;
        this.calendar.showButtonBar = true;
        this.calendar.monthNavigator = true;
        this.calendar.yearNavigator = true;
        this.calendar.yearRange = '1900:2050';
        this.calendar.firstDayOfWeek = 1;
    }
}

Meaning we do not need to provide default inputs when working with the p-calendar component, as they are already set by the directive. This is a great example of how to use directives to extend the functionality of existing components.

Give a read to Tim's article, it has lots of other very interesting use cases

The same approach can be used to modify existing components that we wrote in our application.

Conclusion

As we have seen. directives are also powerful when dealing with existing functionality, and can be used to extend it, thus avoiding the need to wrap everything in components. In the next part, we are going to explore how directives can be used to work with events - both custom and native. Stay tuned!

Superpowers with Directives and Dependency Injection: Part 2

Armen Vardanyan — Thu, 16 Mar 2023 07:51:31 +0000

Original cover photo by Markus Spiske on Unsplash.

In the previous post we took a look at how we can use dependency injection + directives to both simplify our templates and achieve reusability. In this one, we are going to explore structural directives and how we can make components and directives interoperate and reduce clutter in our .html files even further.

Let's build a loader component!

The Use Case

Imagine the following scenario: we have a component that loads some data, and we want to show a loading indicator while the data is being fetched. The following criteria should be met:

We should be able to wrap any template inside our loader component, and it will display a spinner when needed
The component should receive an input property indicating whether the data is being loaded or not
The template should be covered by an overlay, so that the user cannot interact (and potentially trigger other HTTP calls) while the data is being loaded

Here is a pretty simple implementation:

@Component({
  selector: 'app-loader',
  template: `
    <div class="loading-container">
      <ng-content/>
      <div *ngIf="loading" class="blocker">
        <p-progressSpinner/>
      </div>
    </div>`,
  standalone: true,
  styles: [
    `
      .loading-container {
        position: relative;
      }
      .blocker {
        background-color: black;
        position: absolute;
        top: 0;
        z-index: 9999;
        width: 100%;
        height: 100%;
        opacity: 0.4;
      }
    `,
  ],
  imports: [NgIf, ProgressSpinnerModule],
})
export class LoaderComponent {
  @Input() loading = false;
}

Note: I am using PrimeNG for the examples in this article, but you can easily reuse them with any other implementation

So, here we just project any content that we receive into ng-content and the rest is some simple CSS + PrimeNG ProgressSpinner component. The loading input property is used to toggle the spinner on and off.

Now we can use it in the template as follows:

<app-loader [loading]="loading">
  <p>Some content</p>
</app-loader>

Wait, I thought this article is about directives?

Well, good news: it is about directives. But what's the problem with the component? Well, the example of its usage we saw was quite optimistic: real-life scenarios usually are not that simple. Consider this piece of template:

<app-loader [loading]="loading">
  <div class="p-grid">
    <div class="p-col-12">
      <p>Some content</p>
    </div>
    <app-loader [loading]="otherLoading">
        <div class="p-col-12">
            <p>Some other content</p>
            <app-loader [loading]="evenMoreLoading">
                <div class="p-col-12">
                    <p>Even more content</p>
                </div>
            </app-loader>
        </div>
    </app-loader>
  </div>
</app-loader>

Now, here, when we have some nested elements, and the template keeps unnecessarily growing, adding more indentation levels, more closing tags, and so on, and so on. What I personally would really love to be able to do is the following:

<p *loading="loading">Some content</p>

But how can we achieve this? Well, we need a directive that does the following things:

Creates a LoaderComponent instance dynamically
Somehow projects the nested template into it
Keeps them in sync - when the loading input property changes, the directive should update the LoaderComponent instance accordingly
Render the whole stuff

Let's dive into it!

Structural Directives

Structural directives are really cool, because they allow us to reference some templates via TemplateRef and do all sorts of magic with it.

Also, we can use the ViewContainerRef to create components dynamically. What will be left for us is to project the template into the component, And yes, this is possible! Let's start simple:

@Directive({
  selector: '[loading]',
  standalone: true,
})
export class LoaderDirective {
  private readonly templateRef = inject(TemplateRef);
  private readonly vcRef = inject(ViewContainerRef);
  @Input() loading = false;
  templateView: EmbeddedViewRef<any>;
  loaderRef: ComponentRef<LoaderComponent>;
}

Here we injected the things we need (TemplateRef and ViewContainerRef), added a loading input, naturally, and created two properties: templateView and loaderRef. The first one will be used to store the reference to the template that we get, and the second one will be used to store the reference to the ComponentRef instance that we are going to create - we have to store both.

Next, left do some initial heavy lifting to set the whole thing up:

@Directive({
  selector: '[loading]',
  standalone: true,
})
export class LoaderDirective implements OnInit {
  private readonly templateRef = inject(TemplateRef);
  private readonly vcRef = inject(ViewContainerRef);
  @Input() loading = false;
  templateView: EmbeddedViewRef<any>;
  loaderRef: ComponentRef<LoaderComponent>;

  ngOnInit() {
    this.templateView = this.templateRef.createEmbeddedView({});
    this.loaderRef = this.vcRef.createComponent(LoaderComponent, {
      injector: this.vcRef.injector,
      projectableNodes: [this.templateView.rootNodes],
    });

    this.loaderRef.setInput('loading', this.loading);
  }
}

Here, our ngOnInit lifecycle method does four things:

Make the template into an embedded view, so we can render it dynamically
Create a LoaderComponent instance
Project the template into the LoaderComponent instance via projectableNodes - here is where the magic is happening!
Set the loading input property on the LoaderComponent instance

Now, this way it will kinda work, but we need two more things to make it work properly:

We need to update the LoaderComponent instance when the loading input property changes
We need to ensure change detection still works on the projected template despite it being "detached" from the parent view and projected into a new component. We will use ngDoCheck for this

Let's finalize the implementation:

@Directive({
  selector: '[loading]',
  standalone: true,
})
export class LoaderDirective implements OnInit, DoCheck, OnChanges {
  private readonly templateRef = inject(TemplateRef);
  private readonly vcRef = inject(ViewContainerRef);
  @Input() loading = false;
  templateView: EmbeddedViewRef<any>;
  loaderRef: ComponentRef<LoaderComponent>;

  ngOnInit() {
    this.templateView = this.templateRef.createEmbeddedView({});
    this.loaderRef = this.vcRef.createComponent(LoaderComponent, {
      injector: this.vcRef.injector,
      projectableNodes: [this.templateView.rootNodes],
    });

    this.loaderRef.setInput('loading', this.loading);
  }

  ngOnChanges() {
    this.loaderRef?.setInput('loading', this.loading);
  }

  ngDoCheck() {
    this.templateView?.detectChanges();
  }
}

Those additions are fairly simple: when the loading property of the component changes, we update the LoaderComponent instance accordingly, and when there is change detection running for the directive instance, we also notify the child template in the ngDoCheck lifecycle method via templateView.detectChanges(). If you are unfamiliar with how ngDoCheck works or why it is used, you can read the official docs, or this tutorial.

Now we can simply use it in the template, even when we have multiple nested elements:

<p *loading="loading">
    Some content
    <span *loading="otherLoading">
        Some other content
    </span>
    <p *loading="evenMoreLoading">
        Even more content
    </p>
</p>

And so, there is no nested template, no unnecessary indentation, and no unnecessary closing tags. It's just a simple directive that does the job.

You can view the full example with a live demo on StackBlitz:

Conclusion

As mentioned previously, I believe directives are very, very powerful, but sadly underused in the wider community. With this series of articles I want us to explore different use cases where directives help us simplify our templates and improve readability. In the next piece, we will explore using directives to hack into existing components. Stay tuned!

Superpowers with Directives and Dependency Injection: Part 1

Armen Vardanyan — Mon, 13 Mar 2023 07:35:47 +0000

Original cover photo by Lucas Kapla on Unsplash.

Introduction

I have been saying this for a looong while: Directives are the most underutilized part of Angular.
They provide a powerful toolset for doing magic in templates, and yet in most projects, it is used in the most common, "attribute directives that do some limited business logic" style.

The next most underutilized thing is dependency injection. It is an awesome concept for building reusable stuff, yet 95% of DI usage in Angular is for services.

I have written a bunch of articles on both topics, and here is a list of them. I recommend you read those before diving into this one, although that is not a requirement:

In this series of articles (yes, there are going to be more than one!) we will dive deeper and explore how both of those concepts can be utilized (often together) to significantly simplify our templates. We will do so on use case examples, in a step-by-step format.

Note: I do not choose these examples specifically because they are very common or very useful; often, solutions in form of third-party libraries exist; these examples are just good from the learning perspective, as they allow to showcase a lot of concepts in a relatively small amount of code.

So, without further ado, let's get started!

Building a password strength meter

A functionality that exists in lots of modern-day web apps is checking for a user's password strength. Of course, solutions for this exist in the open. but let's build something of our own, and in a way that it would be really customizable.

Let's start with the simplest possible scenario: we add some class on the input element so it can be shown visually:

type PasswordStrength = 'weak' | 'medium' | 'strong';

@Directive({
  selector: '[appPasswordStrength]',
  standalone: true,
})
export class PasswordStrengthDirective {
  private readonly el: inject(ElementRef);

  @HostListener('input', ['$event'])
  onInput(event: InputEvent) {
    const input = event.target as HTMLInputElement;
    const value = input.value;
    const strength = this.evaluatePasswordStrength(value);
    this.el.nativeElement.classList.add(
      `password-strength-${strength}`
    );
  }

  evaluatePasswordStrength(password: string): PasswordStrength {
    if (password.length < 6) {
      return 'weak';
    } else if (password.length < 10) {
      return 'medium';
    }
    return 'strong';
  }
}

And then we can use it in the template like this:

<input type="password" appPasswordStrength>

Fairly simple. (Ignore the simplicity of the logic behind evaluation; it is really irrelevant and we can put any logic there - our aim is to make this directive maximally customizable).

But now we have several issues:

Why the selector? If we forget to out the [appPasswordStrength] attribute, the directive will not work. Can we make it work automatically on all password inputs?
What if we need logic that is not just adding a class, but also adding some text to the DOM, for example? Can we make the directive just tell the template about the strength of the password and then let it handle in a custom way?
What about customizing the evaluator function? Can we make it so that the user can provide their own function to evaluate the password strength?
If the developer provides the logic for evaluation, can we make it possible to both provide the logic application-wide, from one place, and customize it on a per-input basis?

Let's explore all of these issues and improve our directive. Let's start with the first, simplest one:

@Directive({
  selector: 'input[type="password"]',
  standalone: true,
})
// directive implementation

Now we can just drop the attribute selector:

<input type="password">

Now it will work automatically. But what if, in some cases, we want to ignore the checking? We can add an input for that:

@Directive({
  selector: 'input[type="password"]',
  standalone: true,
})
export class PasswordStrengthDirective {
  @Input() noStrengthCheck = false;
  private readonly el: inject(ElementRef);

  @HostListener('input', ['$event'])
  onInput(event: InputEvent) {
    if (this.noStrengthCheck) {
      return;
    }
    // logic goes here
  }

  // the other methods
}

And then we can use it like this:

<input type="password" [noStrengthCheck]="true">

Cool, the first improvement is done. Let's now make it so the component, rather than add a class, just informs the template about the strength of the password and lets it do the job itself. We could do that by adding an output, but that would mean more boilerplate for the developers in the template to capture the strength in a variable before using it. So instead we will use exportAs to work with the directive instance directly:

@Directive({
  selector: 'input[type="password"]',
  standalone: true,
  exportAs: 'passwordStrength',
})
export class PasswordStrengthDirective {
  @Input() noStrengthCheck = false;
  // property to capture in the template
  strength: PasswordStrength = 'weak'; 
  // no need for ElementRef anymore

  @HostListener('input', ['$event'])
  onInput(event: InputEvent) {
    if (this.noStrengthCheck) {
      return;
    }
    this.strength = this.evaluatePasswordStrength(value);
  }

  evaluatePasswordStrength(password: string): PasswordStrength {
    if (password.length < 6) {
      return 'weak';
    } else if (password.length < 10) {
      return 'medium';
    }
    return 'strong';
  }
}

Now we only write the strength itself to a property to let the developer capture it in the template. Here is how it is done:

<input type="password" #evaluator="passwordStrength">
<div *ngIf="evaluator.strength === 'weak'">Weak password</div>
<div *ngIf="evaluator.strength === 'medium'">Medium password</div>
<div *ngIf="evaluator.strength === 'strong'">Strong password</div>

We use exportAs to capture the directive instance in a template variable, and then we can use it to access the strength property. You can read more about it in the official documentation.

Now, let's make it so the developer can provide their own logic for evaluating the password strength. Again, we could do it using a standard Input property, but that would mean we would have to provide that function every time we have a password input, and that is cumbersome and error-prone - easy to forget. So instead we will use an InjectionToken together with a small helper function to provide the logic application-wide:

type PasswordEvaluatorFn = (password: string) => PasswordStrength;

export const evaluatorFnToken = new InjectionToken<
  PasswordEvaluatorFn
>(
  'PasswordEvaluatorFn',
);

export function providePasswordEvaluatorFn(
  evaluatorFn: PasswordEvaluatorFn,
) {
  return [{
    provide: evaluatorFnToken,
    useValue: evaluatorFn,
  }];
}

@Directive({
  // eslint-disable-next-line @angular-eslint/directive-selector
  selector: 'input[type="password"]',
  exportAs: 'passwordEvaluator',
  standalone: true,
})
export class PasswordEvaluatorDirective {
  strength: PasswordStrength = 'weak';
  @Input() evaluatorFn = inject(evaluatorFnToken);
  @Input() noStrengthCheck = false;

  @HostListener('input', ['$event'])
  onInput(event: InputEvent) {
    if (this.noStrengthCheck) {
      return;
    }
    const input = event.target as HTMLInputElement;
    const value = input.value;
    this.strength = this.evaluatorFn(value);
  }
}

Now we can just provide a custom evaluation function application-wide:

bootstrapApplication(AppComponent, {
  providers: [
    providePasswordEvaluatorFn((password: string) => {
      if (password.length < 6) {
        return 'weak';
      } else if (password.length < 10) {
        return 'medium';
      }
      return 'strong';
    }),
  ],
  // the rest of the application
});

And use it as we please.

But here comes a problem: what if the user does not provide a custom evaluator function? We can make it so the directive throws an error if it is not provided, but that might not be the best solution. So, let's instead make the directive use a default evaluator function if the user has not provided one. But, right now, if there is no custom function provided, the dependency injection mechanism will throw a NullInjectorError error. Here, the optional flag comes to the rescue:

@Directive({
  //...
})
export class PasswordEvaluatorDirective {
  //...
  evaluatorFn = inject(evaluatorFnToken, { optional: true });
  //...
}

Now the inject function will return null instead of throwing an error if the token is not provided. We can use that to provide a default evaluator function:


export const defaultEvaluatorFn: PasswordEvaluatorFn = (
  password: string,
): PasswordStrength => {
    if (password.length < 6) {
        return 'weak';
    } else if (password.length < 10) {
        return 'medium';
    }
    return 'strong';
}

@Directive({
  //...
})
export class PasswordEvaluatorDirective {
  //...
  evaluatorFn = inject(
   evaluatorFnToken,
   { optional: true },
  ) ?? defaultEvaluatorFn;
  //...
}

So now, if the user is satisfied with the default evaluator function, they don't have to provide anything. But if they want to provide their own, they can do that as well, both at the component level and application-wide.

So now, that last question remains: how to provide a custom evaluator on an input basis? Meaning, we can have several password inputs in the same component, but we want some of them to work differently. Because of how the inject function works, we can just decorate our evaluatorFn with @Input and it will work:

@Directive({
  //...
})
export class PasswordEvaluatorDirective {
  //...
  @Input() evaluatorFn = inject(
    evaluatorFnToken,
    { optional: true },
  ) ?? defaultEvaluatorFn;
  //...
}

And now we can use it like this:

<input type="password" 
       #evaluator="passwordEvaluator"
       [evaluatorFn]="myEvaluatorFn"/>

Here is the final version of our component, with a live demo:

Conclusion

In this article, we have explored how to use InjectionToken to provide custom logic to a directive, how to use an exported instance of the directive, and use a custom selector for matching. In the next one, we will dive into using structural directives and performing advanced DOM manipulations.

Angular Misconceptions

Armen Vardanyan — Mon, 06 Mar 2023 09:05:36 +0000

Original cover photo by Kendall Ruth on Unsplash.

Angular is a huge framework with lots of built-in functionality and lots of features and tweaks. While the documentation and a myriad of training resources explain how it works and all of its components in great detail, there are still some misconceptions about certain aspects of Angular that are worth clearing up.

So, in this article, we will explore concepts that are sometimes misinterpreted, even by the most seasoned Angular developers.

1. Zone.js is doing change detection

"You need zone.js to have change detection, without it, your application will be frozen in time" - this is what often is said to newcomers in Angular, and it is entirely true. But... that is only true in the most basic sense. Zone.js is not doing change detection, it is just enabling it.

Let's understand how it works in detail:

Angular updates the UI only if some changes have been met to the application state.
Angular assumes (quite correctly) that any change to the application can occur only when something asynchronous happens (e.g. a user clicks a button, or a network request completes, or a setTimeout fires, and so on).
Zone.js monkey-patches all the asynchronous APIs in the browser, so those can be hijacked and made to dispatch notifications
Angular listens to those notifications, and if something happens, it triggers a top-down change detection process, moving through components, finding out what changed, and, if needed, updating the UI.

So in essence Zone.js tells Angular "something async happened, so some app state might have changed (maybe not though)", Angular hears this, starts checking component data, and, if a change is found, updates the UI

Note: this is an oversimplification, in reality, Angular does some other stuff during change detection runs too, but those are out of the scope of this discussion.

So, change detection is a process completely detached from Zone.js. It is possible that we have used ChangeDetectorRef to manually trigger change detection, like this:

import { Component, ChangeDetectorRef, inject } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <h1>My App</h1>
    <p>Counter: {{ counter }}</p>
    <button (click)="increment()">Increment</button>
  `
})
export class AppComponent {
  private readonly cdRef = inject(ChangeDetectorRef);
  counter = 0;

  increment() {
    this.counter++;
    this.cdRef.detectChanges();
  }
}

Now if we go to the angular.json file and remove zone.js from the polyfills array, and then add {ngZone: 'noop'} to the bootstrapModule options in main.ts, our app will no longer ship Zone.js, but this component will continue to work as expected. Let's inspect an excerpt from the Angular's async pipe's source code:


@Pipe({
  name: 'async',
  pure: false,
  standalone: true,
})
export class AsyncPipe implements OnDestroy, PipeTransform {
  private _ref: ChangeDetectorRef|null;
  private _latestValue: any = null;
  private _obj: Subscribable<any>|Promise<any>|EventEmitter<any>
   |null = null;

  constructor(private ref: ChangeDetectorRef) { }

  transform<T>(
    obj: Observable<T>|Subscribable<T>|Promise<T>|null|undefined,
  ): T|null {
    if (!this._obj) {
      if (obj) {
        this._subscribe(obj);
      }
      return this._latestValue;
    }

    if (obj !== this._obj) {
      this._dispose();
      return this.transform(obj);
    }

    return this._latestValue;
  }

  private _subscribe(
    obj: Subscribable<any>|Promise<any>|EventEmitter<any>
  ): void {
    // this method performs subscriptions to
    // Observable or Promise
    // and then calls _updateLatestValue
    // omitted for brevity
  }

  private _updateLatestValue(async: any, value: Object): void {
    if (async === this._obj) {
      this._latestValue = value;
      this._ref!.markForCheck();
    }
  }
}

So, as you may see, the transform method actually doesn't do much, it just subscribes (if not already subscribed) and then returns the latest value. The subscription is done by the _subscribe method, which in its turn, well, subscribes, and calls _updateLatestValue when a new value is emitted. And this is where the magic happens: the _updateLatestValue method calls markForCheck on ChangeDetectorRef. So, the async pipe is not using Zone.js at all and is manually triggering change detection.

Thus, if you had a hypothetical application that only ever uses RxJS Observable-s with the async pipe, you can kinda drop zone.js from your app, and it will still work.

Note: the code example from the async pipe is incomplete and simplified, read more here

Yet another note: Angular is adding Signals, so in the future, this might be a whole other kind of discussion

2. OnPush change detection works only when inputs are updated

Over the course of my own career, I have done multiple interviews for Angular developer positions, and approximately 90% of the candidates I interviewed had a misconception that the OnPush change detection strategy works only when component inputs have been changed. Let's first view a simple counterexample:

In this short example, the text property of the ChildComponent is set to "some text", and when the button is clicked, it is updated to "other text". The ChildComponent is using the OnPush change detection strategy, and has no inputs, but that does not prevent it from updating the UI when the button is clicked.

So what does ChangeDetectionStrategy.OnPush actually do? What it does is

First and foremost, it removes deep-checking on change detection, meaning if we pass inputs to a component with OnPush change detection, it will not readily update (it might update in the future). So to make sure updates to the UI are correct, we would need to change the reference to the input object. Let's examine this in another example:

So, in here we have two components: AppComponent and ChildComponent, and the child one has an array as an Input. Now, in the parent component, there are two buttons, one is called "Push to array from parent", and the other one is "Change array reference". Now clicking the first one (and only it) will not update the UI. Clicking the second one, however, will yield immediate results. Meaning with ChangeDetectionStrategy.OnPush only referential equality is checked in the case of objects, and no deeper checks are being performed.

In the child component, the rules are a bit different, because if we click the "Push to array" button, located in the child component, we would get an immediate update - that is because with OnPush, local events trigger a change detection cycle.
Changes are not gone - now this time we can try clicking the "Push to array from parent" button, maybe even several times, and then clicking the "Push to array" button in the child component. Now we will see an update with several items added to the array - that is because the changes are there, just have not been detected until we triggered them from the child component.

Of course, some other nuances are present, and you can read about more of them here. But as we have already seen, the OnPush change detection strategy is not limited to inputs, and it is not limited to referential equality checks either.

3. Calling methods in templates is a crime

We have heard it a lot: DO NOT CALL METHOD IN ANGULAR TEMPLATES. But why should it be like this?

Well, the main reason is that because the value of the method (whatever it returns) is not readily available, Angular has to run call the function to extract the value and see if the UI needs to be updated, which in turn might result in a costly computation. Notice the wording here: costly computation. So what about not-so-costly computations? Consider these two examples:

@Component({
  template: `
    {{a + b}}
  `,
})
export class AppComponent {
  a = 1;
  b = 2;
}

@Component({
  template: `
    {{sum()}}
  `,
})
export class AppComponent {
  a = 1;
  b = 2;

  sum() {
    return this.a + this.b;
  }
}

In both cases, we are going to get the same result, and the computation isn't really that bad. As a matter of fact, in both cases, Angular is going to perform the same computation, and the only difference is that in the second case, Angular is going to call the sum method, which will add some very negligible milliseconds of adding the function to the call stack and so on to the process.

Another interesting piece of Angular trivia: some built-in properties that exist on different Angular classes are, in fact, getters (thus functions), but we keep using them in templates without any issues. Here is a fun example: FormControl.valid, which we might often use in a template, is actually a getter. (also all the other properties there are getters too), that just returns a simple computation result.

So what are the rules?

Simply one rule - avoid costly operations, iterating over arrays, calling APIs, and so on. Everything else can be fair game.

Note: when signals are introduced and stable, the best approach would be to use a computed property to avoid all unnecessary function runs

4. Pipes should be pure

This is the continuation of the previous point: pure pipes (which all pipes are by default) will only calculate a new result when the input properties change. Impure pipes will run on every change detection cycle. But then again, the same argument can be made here: depends on the calculation. Sometimes we need impure pipes - especially when working with reactivity, and some built-in pipes are already impure, most famously the async pipe. So, impure pipes are not a bad practice.

5. We can use an `EventEmitter` as a `Subject`

EventEmitter is well known in the Angular community - after all, it is one of the first ways of communicating between components that we learn. If we look at the source code, we can see that it extends RxJS Subject, and if we try, we can see that we can not only call the emit method on its instance but also subscribe to it and in general use it as an Observable. But, in reality, we shouldn't really do that. The problem is, the Angular team does not confirm that an EventEmitter will always be an Observable, so they might change this in the future. So, if you are using an EventEmitter as a Subject, you might be in for a surprise in the future. As a matter of fact, with signals being introduced, there is already an ongoing discussion of maybe changing the mechanism by which components can emit events.

6. We should always use Reactive Forms

Reactive Forms are pretty good - most of the functionality they provide is really helpful. But they come with a mental model that is harder than just using NgModel - and that can slow down development in some cases. If anything, a better approach would be to use template-driven forms for simple forms, such as ones that do not really require complex validation and save Reactive forms for really heavy cases.

In Conclusion

Angular is a really rich ecosystem - and there are a lot of things that we can learn from it. But, as we have seen, there are lots of conflicting ideas out there - so in this article, I tried to sort some of them out and maybe clarify some things. If you know other things that Angular developers tend to misuse/misunderstand, feel free to share them in the comments below.

Don't fight the framework: Angular Edition

Armen Vardanyan — Thu, 16 Feb 2023 07:45:56 +0000

Original cover photo by Issy Bailey on Unsplash.

What this article is about

When developing complex software, we often resort to using front-end frameworks, like React, Vue, Angular, and so on. Then we often also adopt UI libraries, testing tools, small libraries that solve specific problems, and more, and more, and more. These tools provide easy, out-of-the-box solutions to common problems, often so in spectacular fashion. Of course, there is a raging debate on whether one should adopt third-party solutions, whether is it costly, does it make the developer experience better, does it make the user experience better, the size of node_modules, etc.

But this article is not about that debate

So what is it about?

This article is about when we have already adopted those tools, but want to use them in as much harmony as possible. See, after the initial excitement of lots of our problems just going away in a pulp of smoke, we discover a simple material reality: those frameworks and libraries (all of them!) have limitations and rules too. So sometimes we will end up in situations like the following:

We want to implement a feature
To do it, we want to do something with a component/service/function coming from a library
Oops, the library either does not support it, or has a bug, or requires lots of code to actually handle this particular problem
Now starts a discussion: should we abandon the feature, should we abandon the framework (is it even possible?), or should we adapt in a way?

Of course, this is only one scenario, there are plenty of others: the library just has a bug, the feature we want to implement requires us to do something that is actively discouraged by the core maintainer of the library, and so on.

So what is the solution?

Let's discuss several options that we have when it comes to this, specifically in the context of Angular and its ecosystem.

Plan ahead, but
Don't overengineer
Stay aware of future possible scenarios and leave doors to be able to implement them when necessary
Do not implement features (components, methods, and so on) only because you think they will be useful in the future - only do that when you are absolutely sure they are needed
Prefer to extend functionality instead of wrapping it
If you can't extend, and absolutely have to wrap, do it in a way that is as transparent as possible, but does not monkey-patch
If you absolutely have to monkey patch something, document it extensively. We will talk about it in a separate section

So let's now start going over these options in more detail.

1. Planning ahead

Imagine you are just starting a new project, and you are thinking about choosing an Angular UI library. There are plenty of options - Angular Material, PrimeNG, NgBoostrap, and so on - we are not going to discuss which one is "better" - it is a pointless debate - but instead, we will focus on some ground rules that will help you make a decision.

Choose a UI library closest to the design at hand - in your mind, in a Figma file, or another. It is virtually impossible to have a UI library that will 100% be like the design you want - you will need some changes in the components that the library provides, so pick carefully there
If you know you are going to change a bunch of stuff, choose a library that is easier to change, but be careful not to end up with a styles.scss file that is thousands of lines of code long.
If you want customization, look into tools that the library itself (or the community) provides for generating custom themes. For example, there is a tool for Angular Material that allows you to generate a custom theme, and then use it in your project.
When customizing, use the code-level tools that the library gives. As an example, PrimeNG always puts an Input property on its components where you can pass a CSS class to it and then use it

Of course, this example is only about UI libraries, but you can apply it to other tools you struggle to choose from too; be sure that the tool you end up with fits best, is extensible, and is easy to customize.

2. Avoiding overengineering

This one is straightforward: don't overengineer. If you are building a small app, sometimes reinventing a relatively small wheel can be a more cost-effective approach than trying to integrate a library that might come with other requirements and even maybe a paradigm shift. If you have a large app, don't immediately assume you need a huge tool that solves multiple problems and has a myriad of blows and whistles. Sometimes a simple, -solves-exactly-one-problem library is the best choice.

3. Leaving doors open

The following scenario happens too often not to think there is a pattern to it:

Developer builds a component/directive/service for a specific feature
Provides the most basic functionality
Couples it too tightly with the feature
When something like that is needed elsewhere, it is almost impossible to reuse; future developers either copy-paste the solution and make slight changes, or introduce huge configuration objects that are hard to understand (and even document)

Or, on the other hand, to avoid this scenario, someone might just start off with a huge configuration object and go on to add more and more complexity to it. So how to avoid it, specifically working with Angular?

Think about whether the functionality can be useful in the future. If you think "yes", then go on to the next step
Is it possible to make that functionality with a directive, rather than a component? Directives are often underutilized, and have way more powers than one might expect - see this article by Tim Deschryver for more details. Directives are also simpler than components (in general), and are easier to reuse.
Avoid using dependency injection, and when I say avoid, I mean just avoid, do not absolutely prohibit it. If we use a business logic-specific service in a component/directive/anything else that is supposed to be reusable, then it is tightly coupled with only certain components/pages in our app. So using a generic service like the localStorage wrapper is fine, but the UserService might not be.

4. Avoiding feature creep

As mentioned in the very first bullet point of this article, we should generally plan for the future; however, we also need to keep in mind that more features = more complexity = more bugs = more maintenance. So we need to be careful not to overdo it. How do we differentiate?

As Angular has dependency injection, we can be tempted to wrap third-party library code, especially services, into our own services with an API more suitable for our needs. We will talk more about this in the next section, for now, remember to write methods in such wrappers that you actually need, and not to just wrap every single method from a library.
When we notice that a certain component/directive is behaving very differently based on an input (usually a boolean named in lines of isSomething), we should think about whether it is possible to split it into two components/directives. This is a very common scenario, and it is usually a sign that the component/directive is doing too much. Remember the single responsibility principle.
Avoid methods that combine functionality when writing your own services; encourage the same methods when wrapping third-party libraries; for example, if a third-party library you use provides methods for both setting some data and setting a loading state, and you overwhelmingly use those methods together, just wrap them as one in tour wrapper; but if you are the one providing such functionality, provide separate methods, as in the future it might be unclear how it is going to be used.

5. Extending functionality

Notice that when we say extend functionality, we do not literally mean extend as in OOP or anything to do with classes. For example, starting from Angular v15, it is possible to extend existing directives using hostDirectives properties (read more about it here), so make use of a mechanism such as that one. Use dependency injection to compose functionality, and not to couple components/directives/services to each other.

Also, when we work with third-party components, especially UI components, there is often a temptation to wrap them inside our own components and maybe provide default values for some of their inputs. Imagine this piece of code:

<div>
    <third-party-dialog
        [open]="isOpen"
        [modal]="true"
        [closable]="true"
        [closeOnEsc]="true">
        <app-other-component/>
    </third-party-dialog>
</div>

So it might be tempting to wrap it in our own component:

@Component({
    selector: 'app-dialog',
    template: `
        <div>
            <third-party-dialog
                [open]="isOpen"
                [modal]="modal"
                [closable]="closable"
                [closeOnEsc]="closeOnEsc">
                <ng-content></ng-content>
            </third-party-dialog>
        </div>
    `
})
export class DialogComponent {
    @Input() isOpen: boolean;
    @Input() modal: boolean = true;
    @Input() closable: boolean = true;
    @Input() closeOnEsc: boolean = true;
}

And use it like this:

<div>
    <app-dialog [isOpen]="true">
        <app-other-component/>
    </app-dialog>
</div>

Surely this works and is kind of an improvement over what we had previously; for instance, we do not need to provide all of the input values constantly, and there is less boilerplate code.

However, there is a couple of problems:

We need to kind of, to be future-proof, write and pass down all the third-party component inputs in the wrapper component, and a third-party UI library component is probably going to have a bunch of inputs
Outputs! Events from the third-party component are not passed up to the end user, so we need to catch and re-emit them manually
If we forget to do something from the previous two points; if we want to implement something that uses a "forgotten" input/output, now our feature will also involve updating the wrapper component

So to avoid it, it is better to extend the component using a directive as described in the above-mentioned article by Tim Deschryver, like this:

@Directive({
    selector: 'third-party-dialog'
})
export class DialogDirective {

    constructor(
        private dialog: ThirdPartyDialogComponent,
    ) {
        if (dialog.modal === undefined) {
            dialog.modal = true;
        }

        if (dialog.closable === undefined) {
            dialog.closable = true;
        }

        if (dialog.closeOnEsc === undefined) {
            dialog.closeOnEsc = true;
        }
    }
}

Here we are sort of hijacking the ThirdPartyDialogComponent and setting default values for its inputs if the values are not provided. This way, we do not need to pass down all of the inputs, and we do not need to re-emit events at all:

<div>
    <third-party-dialog 
        [open]="isOpen"
        (someEventNotHandledInTheDirective)="handleEvent($event)">
        <app-other-component/>
    </third-party-dialog>
</div>

Another popular example of this is HTTP Interceptors in Angular. Sometimes Angular developers would wrap the HttpClient service inside their own implementation in the hope to add new functionality, for example, adding headers, dealing with cookies, checkings, and so on. But instead, intercepting requests/responses and adding functionality "on-the-flight" is on 99% of occasions way more than enough. Here is an interceptor that sends the client's timezone offset with each request in a header:

@Injectable()
export class TimezoneInterceptor implements HttpInterceptor {

    intercept(
        request: HttpRequest<any>,
        next: HttpHandler,
    ): Observable<HttpEvent<any>> {
        const timezoneOffset = new Date().getTimezoneOffset();
        const modifiedRequest = request.clone({
            headers: request.headers.set(
                'X-Timezone-Offset',
                timezoneOffset.toString(),
            ),
        });

        return next.handle(modifiedRequest);
    }
}

So requests can be fashioned in this way in multiple scenarios, once again proving that wrapping even services in Angular is rarely the best solution.

6. Wrapping? Wrapping!

So if we are past the scenario where the framework allows for an extension instead of wrapping, say, it is not possible, do we wrap, or do we just use the service as is? I argue we must wrap.

Here are a couple of reasons for this:

We can provide a more suitable API for our needs - we might not like method names, for example, they might be inconsistent with our project's naming conventions or ideas, so wrapping would allow overcoming this (albeit minor) obstacle
If the third-party service does not have some functionality that we want, or we want to modify the behavior we want, we can do it in the wrapper
This approach is future-proof: if the library goes out of maintenance, or we decide to switch to a different library, we can do it without changing the code that uses the wrapper - just change the wrapper with the new library's service
No need to mock third-party dependencies in unit tests - we can just mock the wrapper

So if we are comfortable with the above-mentioned reasons, we now need some ground rules for the wrapper

The wrapper should be as thin as possible, mainly just a thin layer that calls the third-party service and returns the result (of course with some minor modifications if needed)
No business logic here - the wrapper is just a gateway to the third-party service, it should not do anything else, thus keeping it reusable in multiple places
Unit test extensively - this will save lots of trouble down the road
Never monkey patch the third-party service - functionality provided by the third-party service should not be modified, only extended, as already mentioned a couple of times. This will help avoid confusion by future developments and also prevent unintended behavior/bugs from being added to the dependency

Here is an example of a service that wraps the localStorage API:

@Injectable()
export class LocalStorageService {
    get(key: string): string | null {
        return localStorage.getItem(key);
    }

    set(key: string, data: string) {
        localStorage.setItem(key, data);
    }

    remove(key: string) {
        localStorage.removeItem(key);
    }

    clear() {
        localStorage.clear();
    }

    has(key: string): boolean {
        return this.get(key) !== null;
    }

    get length(): number {
        return localStorage.length;
    }
}

So as you can see here, we made a very thin wrapper around localStorage, mostly just calling the methods, but changed a name to shorter versions in our liking, and added a has method for convenience. Most API erappers are going to look like this.

Thus, after all those rules have been kept, we can finally approach the hardest problem of them all.

7. What if we really want to monkey-patch something?

Sometimes though, we encounter a really nasty issue - the third-party library has a bug that cannot be worked around and is impeding a vital feature. So what do we do in this scenario? Here is a list of steps that need to be done before considering just monkey-patching the problem.

Check if the issue exists for other environments or users/machines
Check if the issue still persists on the later versions of the library
Check if the issue has been submitted to GitHub and if there is a discussion on it
Check if your requirement cannot be changed in order to avoid dealing with the "buggy?" part of the third-party library
Submit an issue on GitHub and see how it is being discussed
Consider submitting a PR to fix the issue - that would be great for the community and yourself
Consider if extending, wrapping, or otherwise interfering with the library might fix the issue

If all those steps didn't yield the necessary results (the library is no longer maintained, the team won't accept your PR, you are low on time, and so on), go for monkey patching the issue. After that, follow these steps:

Document extensively the logic and reasoning behind the monkey-patching:
- Describe the problem
- If there is a GitHub issue, put a link to it
- If a future version is promised to fix the issue, put a link to that statements
- Put a // TODO comment
- Describe how exactly the monkey-patching is done
Write unit tests for the monkey-patching - again, very extensive, while mocking the other behavior of the library
Put the idea of one day removing this patch somewhere in your backlog
DO NOT under any circumstance add business logic in the monkey-patching code - this would be almost impossible to remove in the future and is probably the most tightest coupling that one can imagine.

Here is an example of monkey-patching a bug in the PrimeNG UI library:

Note - this is a real-life example that is harder to comprehend, so the specifics of the fix are omitted, main focus is on the documentation and overall approach around it:

/**
 * @description
 * This directive is for fixing a bug on PrimeNG 
 * (github link to issue)
 * InputNumber component to alow add -(minus) 
 * sign with prefix attribute. <br>
 * This works by monkey-patching the InputNumber component's 
 * insert and update methods.
 * 
 * TODO: Remove this directive when the bug is fixed in PrimeNG
 * <b>Author:</b> Maybe put your name so 
 * people know who to address if they have questions
*/
@Directive({
  selector: 'p-inputNumber', // find all the p-inputNumber elements
})
export class InputNumberDirective implements AfterContentInit {
  constructor(private inputNumber: InputNumber) {}

  ngAfterContentInit() {
    // first we keep the native methods 
    // we want to monkey-patch bound to the instance
    const updateInput = this.inputNumber.updateInput.bind(
        this.inputNumber,
    );
    const insert = this.inputNumber.insert.bind(this.inputNumber);

    // now we monkey patch it
    this.inputNumber.insert = (
        event,
        text,
        sign = {
            isDecimalSign: false,
            isMinusSign: false
        }
    ) => {
      // we do some monkey patching logic
      // Prevent the prefix sign from being deleted
      // some heavy lifting
      // we call the native method then
      insert(event, text, { ...sign, isMinusSign: false });
    }
    this.inputNumber.updateInput = (
        value,
        insertedValueStr,
        operation,
    ) => {
        // perform the native method first
      updateInput(value, insertedValueStr, operation);
      // preventing navigation of cursor 
      // to the end of input after entering negative value
      // a bunch of other heavy lifting
    };
  }
}

And that is about it.

In Conclusion

Working with libraries and frameworks can be both fun and challenging, so in this article, we tried to approach some problems when doing so in Angular. One last piece of advice - always remember no advice is 100% perfect and think about the problem at hand.

DEV Community: Armen Vardanyan

NgRx Use Cases, Part III: Decision-making

Error handling with NgRx

Generic error handling with NgRx

Handling specific errors

Handling loading data

Selecting data in the component to use

User interactions

Conclusion

Signals: the Do-s and the Don't-s

Don't use setters for inputs to turn them into signals

Do use signal inputs

Don't retrieve data via HTTP calls in effects

Do use toSignal + toObservable

Don't forget about untracked

Do use untracked

Don't use toSignal in services to expose Observables as signals.

Do use toSignal in components or expose state via connecting methods

Conclusion

Small promotion

Superpowers with Directives and Dependency Injection: Part 7

Directive Selectors

Non-custom attribute selectors

Attribute selectors with values

Class selectors

Complex selectors

Combining selectors

Selector negation

The Pitfalls

Cannot target child-parent relations

Directives cannot be applied dynamically

Structural directives can only be attributes

Conclusion

Small promotion

Superpowers with Directives and Dependency Injection: Part 6

Introduction

Using directives to handle permissions

Using directives to handle shared data in components

Conclusion

Signals: what this means for NgRx

How NgRx might work with signals

NgRx Signal Store

Existing NgRx stores

What all of this means?

1. Store values would now be directly accessible everywhere.

2. Some best practices might need to be rethinked

Conclusion

Superpowers with Directives and Dependency Injection: Part 5

Dynamic shared templates

The Idea

The Implementation

The Service

The Header Component

The Directive

The Usage

Conclusion

Superpowers with Directives and Dependency Injection: Part 4

A click-away directive

Handling scrolling

Conclusion

Superpowers with Directives and Dependency Injection: Part 3

Use case 1: Hijacking existing elements

Use case 2: hijacking existing components

Conclusion

Superpowers with Directives and Dependency Injection: Part 2

The Use Case

Structural Directives

Conclusion

Superpowers with Directives and Dependency Injection: Part 1

Introduction

Building a password strength meter

Conclusion

Angular Misconceptions

1. Zone.js is doing change detection

2. OnPush change detection works only when inputs are updated

3. Calling methods in templates is a crime

4. Pipes should be pure

5. We can use an EventEmitter as a Subject

6. We should always use Reactive Forms

In Conclusion

Do use `toSignal` + `toObservable`

Don't forget about `untracked`

Do use `untracked`

Don't use `toSignal` in services to expose Observables as signals.

Do use `toSignal` in components or expose state via connecting methods

5. We can use an `EventEmitter` as a `Subject`