Forem: Evgeniy OZ

Reactivity in Angular

Evgeniy OZ — Wed, 18 Jun 2025 08:42:03 +0000

This article explains why we should build our Angular apps with reactivity in mind and how immutability helps with it.

The Magic

Look at this example:

    @Component({
      template: `
        <div>Name: {{user.name}}</div>
        <div>Age: {{user.age}}</div>

         <button (click)="updateName()">Set Random Name</button>
         <button (click)="updateAge()">Set Random Age</button>
      `,
    })
    export class App {
      user = {
        name: 'Alice',
        age: 25,
      }

      updateName() {
        const i = Math.floor(Math.random() * names.length);
        this.user.name = names[i];
      }

      updateAge() {
        this.user.age = Math.floor(Math.random() * 20 + 20);
      }
    }

It works, but it only works because of magic. Dark magic. I wish it didn’t work :) What’s much worse is that code like this is scattered across Angular tutorials for beginners, so it shouldn’t be surprising that many Angular apps have similar code, and that many readers right now are asking, “What the hell is wrong with this code, dude? It just works. Chill, man.”

What works

In our template, we have bindings:

    <div>Name: {{user.name}}</div>
    <div>Age: {{user.age}}</div>

When user.name changes, Angular reflects this change and updates the HTML element. That seems quite reasonable and logical.

But how does Angular know that user.name has changed? We didn’t call anything like heyAngularWeChangedTheUserObject() or even checkBindingsPlease(). This is where the dark magic hides — and this magic has its price.

What is the price

The magic tricks here are “dirty checking” and “monkey patching”.

They hurt performance and can cause data pollution (undesired mutations) in non-trivial apps. But they work just fine in small apps, especially in the simple examples provided in tutorials.

To cast the “dirty checking” spell, Angular has to check every binding (and every “input”) in every component of your application. Some of these components are used in “for” loops, some are reused multiple times, so the number of rendered components might be higher than the total number of components your app has.

And Angular doesn’t know when your bindings might change. So Angular reacts to every change of every [input] and (output) and DOM event listeners like (click). And still, it is not enough.

Data in your app might change asynchronously. Not right after the (output) has emitted (for example), but a little bit later, after loading some data. And Angular will run its dirty checking too early to notice the changes.

For that, Angular uses another spell: “monkey patching.”

A special tool, Zone.js, wraps asynchronous APIs like setTimeout, requestAnimationFrame, Promise, MutationObserver, and events like click, change, mousemove, and many others [1]. So when they are called, Zone.js notifies Angular — and that’s how it knows when to cast the “dirty checking” spell.

Did you just say mousemove?

Yes. And scroll is also patched. Now you can imagine how many times Angular has to check every binding in your components.

The existence of this dark magic led to a special rule:

Thou shalt not call functions in your templates! ☝️

Even beginners know this rule, because it’s practically a commandment in many tutorials.

The reason: comparing two variables by reference is a very cheap operation in terms of performance. But if a binding involves a function, that function will be called, and computing its value might not be so cheap.

This rule is nothing but an adaptation to the shortcomings of the dark magic we just explored.

Is the OnPush Change Detection Strategy Enough?

There are two change detection strategies in Angular that components can use, and one of them, OnPush, instructs the framework to check not every component in the app, but only the modified component and its ancestors.

But just changing the strategy in an existing component is not enough. First, every binding should be reactive — otherwise, we’ll do more harm than good.

Let’s modify our example a bit:

    @Component({
      changeDetection: ChangeDetectionStrategy.OnPush,
    // ...

      updateAge() {
        // Any asynchronous code.
        // Imagine we are loading the allowed ages list.
        setTimeout(() => {
          this.user.age = Math.floor(Math.random() * 70 + 20);
        }, 1);
      }
    }

Now, if you click “Set Age” first, you will see no changes. But if you click “Set Name” afterwards, you’ll see both the name and the age updated.

Explanation of the bug:

When we click the button, the event handler not only calls updateAge(), but also marks our component as “dirty” and schedules a Change Detection cycle;
Change Detection runs, but can’t see any changes because they will be applied later (asynchronously). It removes the “dirty” mark from our component;
setTimeout() is patched by Zone.js, so after 1ms, it schedules a Change Detection cycle;
Change Detection runs, but our component has the OnPush strategy and is not marked as “dirty” (see step 2), so the component is skipped;
When we click another button, the event handler calls updateName(), marks our component as dirty, and schedules a Change Detection cycle;
Change Detection runs and sees changes in both of our bindings: user.name, which we just changed, and user.age, which we changed previously. Both changes are then reflected.

This is an example of why we should not use OnPush with non-reactive bindings.
We should only use OnPush when every binding in our template is reactive.

As you can see from the steps 3 and 4, Zone.js can notify the framework about when, but not where a change detection is required.

Angular is moving away from black magic. In the Zone.js repo, you can find [2]:

As Angular moves towards a zoneless application development model, Zone.js is no longer accepting new features, including additional patches for native platform APIs. The team will also not be accepting any low priority bug fixes. Any critical bug fixes that relate to Angular’s direct use of Zone.js will still be accepted.

And this is the direction we all should move as well — towards…

Pure Reactivity

If we notify the framework that some parts of our templates have changed, then the framework will not need all that dark magic and can:

Check only the modified parts;
Only when needed;
Optimize DOM updates even with asynchronous changes;
Stop using monkey patching.

It might sound too good to be true, but we can do this already — starting with Angular version 20! We’ll need 3 things:

bindings in our templates should use only Signals;
every component should use OnPush change detection strategy;
provideZonelessChangeDetection() in bootstrapApplication() providers.

If, for some reason, you can’t use Angular v20 yet, or some old libraries are not compatible with zoneless change detection — don’t worry. If you can use Signals for bindings (or at least the async pipe with Observables), and all your components use the OnPush change detection strategy, the performance of your app will be quite close to that of a zoneless app.

An additional benefit of a zoneless app: it forces your code not to rely on Zone.js and to be purely reactive.

Reactive bindings

The point of reactive bindings is to notify Angular about the changes (when and where they happened), so Angular can react (pun intended) and reflect the changes with minimal performance costs.

Let’s fix our bug by replacing our non-reactive bindings with reactive ones:

Let’s analyze our code:

    @Component({
      selector: 'app-root',
      changeDetection: ChangeDetectionStrategy.OnPush,
      template: `
        <div>Name: {{name()}}</div>
        <div>Age: {{age()}}</div>
        ...
      `,
    })
    export class App {
      user = signal<User>({
        name: 'Alice',
        age: 25,
      });

      name = computed(() => this.user().name);
      age = computed(() => this.user().age);

      updateName() {
        const i = Math.floor(Math.random() * names.length);
        this.user.update((user) => ({
          ...user,
          name: names[i],
        }));
      }

      updateAge() {
        setTimeout(() => {
          this.user.update((user) => ({
            ...user,
            age: Math.floor(Math.random() * 70 + 20),
          }));
        }, 1);
      }
    }

Now user is a signal, we have two derived (computed) signals: name and age, and our updateName() and updateAge() methods have been modified a little.

Every time we modify the user signal, it sends notifications to name and age, and they send notifications to the template.
When this happens, the template marks our component as “dirty” and schedules a Change Detection cycle.

Without any magic, we let Angular know where and when changes happened, so Angular can granularly update only the needed parts — and only when it’s needed.

But wait, we are calling functions in our template! 😱

Yes, and it’s ok. Signals are functions, but their call is super cheap because they don’t compute their value on every call. They memoize their value, so calling them doesn’t hurt performance.
In fact, any function that memoizes its value can be safely called from the template [3]. Signals just guarantee this out of the box.

Immutability

In the updateName() and updateAge() methods, we use the update() method of an Angular Signal and create a shallow copy of the existing object. Why not just mutate the fields of the existing object?

Because when we update an Angular Signal using set() or update(), Angular compares the new value with the old one. A notification will be sent only if they are not equal. And they are compared by reference (===).

Two references to the same object are always considered equal — and that’s why we create a shallow copy: to trigger the value change notification.

You can verify this behavior in the following new methods:

    mutateAge() {
      const user = this.user();
      user.age = Math.floor(Math.random() * 70 + 20);
    }

    mutateAgeAndSet() {
      const user = this.user();
      user.age = Math.floor(Math.random() * 70 + 20);
      this.user.set(user);
    }

In mutateAge(), we mutate the field of a signal value. As you can check, this will not work.

In mutateAgeAndSet(), we mutate the field and call the signal’s set() method. It will compare two user objects, they are equal by reference, so this will not trigger any changes either.

You can read more about Angular Signals reactivity and mutations in my other article [4].

There is an easy trick to protect ourselves from this mistake:

    export type User = {
      readonly name: string;
      readonly age: number;
    };

There are more advanced tools to provide immutability, but this one doesn’t require any libraries to use.

Immutability is not only helpful for reactivity. It has other benefits: your data will not be polluted (modified by code that has no clue it’s modifying shared data), it protects from unexpected side effects, and it makes testing easier.

It is possible to override the default equality check function in Angular Signals (in most of their kinds), but you should only do this in exceptional cases, when providing the new values in an immutable way is more expensive than checking equality manually.
Checking equality in nested objects recursively can be quite expensive in terms of performance and might require special handling if the objects have circular references.

Performance

Let’s explore why the Signals in Templates + OnPush + Zoneless formula provides the best possible performance for your Angular app.

A template is a consumer of signals and behaves similarly to effect(), but it also schedules a Change Detection cycle when a signal is updated.

Unlike the async pipe [9], the template will not be triggered on every update of the signal. As we learned above, only non-equal values will trigger an update.
Also, if a signal is updated 100 times synchronously (each time with a new value), the template will schedule just one Change Detection cycle.

Here is the difference in how Observables and Signals deliver their update notifications:

Observables emit every time we ask them to. They don’t check if the next value is equal to the previous one. When an Observable emits a value, the subscriber must handle it, because it can’t predict whether there will be another. We could use debounceTime(0), but that would introduce unnecessary asynchrony when a synchronous update would be sufficient;
Consumers of signals receive only a notification about the update, not the new value. To get the new value, they must read the updated signal — and they are free to do this whenever they want. In the case of computed signals, this means that the new value will be recomputed not at the moment when the signals used in the computation are updated, but when the consumer reads the value of that computed signal. This can eliminate a lot of unnecessary computations, because consumers (effect(), templates) schedule the reads of the signals they are subscribed to, so they don’t read more often than needed. You can read more about signals timings in the article linked below [6].

When the OnPush strategy is combined with signals (your template uses only signals for reactivity and all components use the OnPush strategy), Angular applies an optimization called “Local Change Detection” [5]. It doesn’t mark every ancestor as “dirty”; instead, it marks only the component as “dirty” and marks each ancestor “for traversal.”
This means that non-dirty ancestors will not be checked.

And when every binding (that can change) in our templates uses a signal, we simply don’t need Zone.js and its performance overhead — Angular already knows where and when changes happened.

Combined with the “Single Source of Truth” and “Template First” approaches ([7], [8]), this article will help you create super-performant, declarative, and scalable code. **To the stars! 🚀**

Examples of linkedSignal() usage in Angular applications

Evgeniy OZ — Mon, 09 Jun 2025 16:00:52 +0000

Angular 20 has been released, linkedSignal() is now stable, and I want to share my experience using this powerful function.

The main use case

linkedSignal() is a perfect tool when you want to compute some initial value, then let the user modify it, and still keep it in a reactive signal.

    export class CategoriesComponent {
      categories = input.required<Category[]>();

      selectedCategory = linkedSignal(() => this.categories()[0]);

      pickCategory(cat: Category) {
        this.selectedCategory.set(cat);
      }
    }

How it works: the initial value of the selectedCategory signal will be computed as this.categories()[0].

this.categories is a signal, and every time this signal changes, selectedCategory will be re-computed.

Technically, it is a bit more complicated: linkedSignal() will not re-compute its value at the moment when any of the signals it consumes notifies about a possible change, but rather when a consumer of the linkedSignal() reads it and the linkedSignal() has unchecked notifications about changes. However, stating this every time would make it much more difficult to read.

Those who are familiar with computed() might say that linkedSignal() works the same, but there are two important differences between them.

Look at the pickCategory() method: Here we set the new value for the selectedCategory signal, and this value will remain until the categories signal “emits” a new value — then selectedCategory will be recomputed again, and the value we previously set in that method will be overridden.

It is very useful for:

displaying pre-computed forms (using previously saved data or default values) and letting the user change the values (to save them later, or just to affect other parts of the app);
pages where the initial properties should be loaded from the API or default values, not the URL, and the URL cannot be the source of truth (large tables with filters and pagination, games, 3D scenes), and the user is supposed to modify the values;
components where one input control might restrict the range of allowed values of other input controls. For example, a date picker where the user picks the year, month, and date separately;
computed (derived) signals that should know the previously computed value.

And that is the second important difference: linkedSignal() not only returns a WritableSignal, but also lets us use the previous value.

Example:

    export class VehiclesComponent {
      showAtv = linkedSignal<boolean, boolean>({
        source: () => this.store.hasATVInfo(),
        computation: (source, previous) => {
          if (source === false) {
            /**
             * If other fields of the form were changed and
             * we no longer have ATV vehicle info,
             * but we are displaying it as "yes,"
             * leave it as "yes" - do not reset this switch.
             * Otherwise, the opened form will be unexpectedly
             * (for the user) closed, and the user might still
             * want to edit this form, bringing in the new ATV info.
             */
            if (previous?.value === true) {
              return true;
            }
          }
          return source;
        }
      });
    }

Sometimes you don’t need a WritableSignal, and you would like to use computed(), but you absolutely need the previous value to compute the new one, even if computed() is supposed to be pure. It’s not an idiomatic example, but for these exceptional cases, you can use this trick:

    export class Example {
      someInput = input<string>();

      myComputedSignal = linkedSignal<string, string>({
        source: this.someInput,
        computation: (source, previous) => {
          if (previous?.value === 'SOME VALUE') {
            return 'SOMETHING ELSE';
          }
          return source;
        }
      }).asReadOnly(); // <- and it's not writable anymore
    }

With great power…

When we have more than one source of truth, things become less declarative and less safe. We should use linkedSignal() with care.

Look at this example:

If a user doesn’t want to be named “Goblin,” they will enter something else, for example, “Wizard.” Now they see in the form that their favorite color is Green and their nickname is “Wizard.” But their favorite color is purple, they input “Purple,” and now they are named “Purple Goblin.” Not an expected behavior, to say the least!

In this form, after “nickname” was edited, it should not be derived (computed) anymore.

linkedSignal() is a wonderful tool that can be extremely useful sometimes. Happy coding!

Starting a Modern Angular Application

Evgeniy OZ — Sun, 16 Feb 2025 09:20:59 +0000

The initial architecture of a web application is fundamentally important — it will affect your app for multiple years, impacting not only development but also the user experience. Things like lazy loading, bundle size, icon reuse, and other small details will influence the user experience, not just CI time, code reuse, or the onboarding process.

In this article, I’ll review the tools and options we have when creating a new Angular app and which of them, in my opinion, should be chosen.

Workspace

So the first thing we should create is a “workspace”. We should decide what structure our application will have — where all the components, services, and other things will be located.

Let’s discuss 3 ways of creating an initial structure:

Using Angular CLI, without separation by sub-modules/packages/libraries;
Using Angular CLI to create a monorepo, all the code is in libraries;
Using Nx to create a monorepo.

There are other tools to create a monorepo, but that would take another article to describe them all :)

So let’s compare what pros and cons every option has:

Angular CLI, without separation by sub-modules/packages/libraries

Pros:

Very easy to follow. Developers of any level can create a new component in the correct folder;
No additional dependencies.

Cons:

Very fragile because of tight coupling. Imports use relative paths: import { NavbarComponent } from '../../../shared-components/navbar/navbar.component', and if something is moved or renamed, many dependent components/services might need an update. A smart IDE can help with this, but not with a 100% guarantee. Moving and renaming things become dangerous;
Easy to create circular dependencies and ruin lazy-loading. See the example below;
Lack of modularity. Moving some code to a separate library requires enormous effort in checking dependencies, and often this task remains forever in the backlog, with functionality just being copy-pasted to another app or project;
test, lint, and build will always handle all the code you have. The more code you have, the longer these commands take, even if only one line in one component was changed;
Upgrades of tools like linters are not handled by ng update - configs will remain the same, even if a linter or test runner library has a major version upgrade and requires modifications in configs.

Example of how the lazy-loading can be broken with this structure:

Component A imports Component B
Component B imports Service S and Component C
Component D imports Component A and Component B
When any component imports just a single Component D, every part listed above is imported as well. This happens very often in real apps. Ruining a lazy-loading is especially easy with this structure.

Angular CLI to create a monorepo, all the code is in libraries

Pros:

Modular. Every library can be reused by multiple apps or even moved to its own repo and published to a registry. Then, it can be added to dependencies with 0 changes required in the code of other apps/libraries (because all imports are already non-relative);
No additional dependencies.

Cons:

Every time you create a library you’ll need to manually modify the paths in tsconfig.json, because Angular CLI will generate paths to dist folder, so to get updates from any library, you need to build it first. And because all of the code is libraries, that would be a nightmare in ng serve mode, so you’ll change the path in tsconfig to the public-api.ts file of a library you created
No module boundaries tracking. Developers should create a document that explains the connections across modules to avoid circular dependencies. This document should be kept up to date and strictly followed every time a developer creates a library. There are tools such as madge which help with this, but they still should be run manually.
test, lint, and build will always build every existing library and app. The more code you have, the longer these commands take, even if only one line in one library was changed.
test, lint, and build can only run consecutively, handling one library/app per run.
Upgrades of tools like linters are not handled by ng update - configs will remain the same, even if a linter or test runner library has a major version upgrade and requires modifications in configs.

Using Nx to create a monorepo.

Pros:

Modular. Every library can be reused by multiple apps or even moved to its own repo and published to a registry. Then, it can be added to dependencies with 0 changes required in the code of other apps/libraries (because all imports are already non-relative).
Easy to configure e2e-testing with Playwright (comes out of the box with Nx).
test, lint, and build will:
handle libraries in parallel (the more cores your machine has, the sooner all the steps will be completed);
only run for modified code — if just one library is modified, just that library will be linted and tested;
use local cache — if code is not changed, results will be reused, even if commands are executed for all libraries (this behavior can be modified with --skipNxCache).
Nx automatically controls module boundaries.
nx migrate updates configs of linters and test runners when their version is updated.

Cons:

Nx as an additional dependency.

You can read here how Nx recommends organizing your workspace.

There is also an excellent article, “Managing TypeScript Packages in Monorepos”.

What you choose from these options is up to you. My recommendations:

Do not pick option 1, even if your app is small and you’re intimidated by the amount of boilerplate that other options bring — you’ll generate it once and forget about it;
If you decide that the maintenance cost of the Nx dependency is too high compared to the benefits it provides, use option 2, and you can add Nx later. If you go this route, generate a multi-project workspace — switching from a single-project to a multi-project workspace might take more time than expected, but doing it from the start will cost you nothing;
I recommend option 3, as it significantly improves maintenance (not only of your code but also of your tools) and reduces generated boilerplate.

Style

First of all, use Tailwind CSS!

It is an excellent tool. If your team is more familiar with Bootstrap, it might be difficult to make the switch, but consider this argument: at the time of writing, Tailwind CSS has more than twice the weekly downloads on npm than Bootstrap.

You’ll also need UI components (date picker, tabs, and so on). Here we have a lot of libraries, you can easily find them. Some of them:

PrimeNG: has a lot of components, can be styled using CSS variables, and has a plugin for Tailwind CSS support;
Angular Material: has a lot of components and tools, can be styled using CSS variables (including the variables generated by Tailwind CSS), maintained by the Angular team, and they put a lot of effort into supporting accessibility features;
spartan/ui: based on TailwindCSS, not so many components, in alpha stage;
daysiUI: framework-agnostic, based on Tailwind CSS.

If you wonder why some libraries you know and love are not on this list, the answer is “for brevity” - enlisting them all would be pointless when we have so many search tools.

When picking a library, I recommend checking the following:

If it can be styled using CSS variables;
If it doesn’t require additional dependencies, that are maintained by someone else;
If Angular is the only JS part that it requires;
If it’s popular and actively maintained.

When the tool you picked asks you what format of CSS files you want, pick CSS — Tailwind works better with CSS, and in modern browsers, CSS can do things that were implemented only in SASS before, like nesting or variables.

SSR

When the workspace generator asks you if you want SSR, answer “yes” even if you are 100% sure your app will never use Server Side Rendering.

The code you write should be compatible with SSR anyway. Because when you want to reuse some of the libraries you created for this app, you might be surprised how much effort and how many breaking changes are required to make the existing code compatible with SSR. And if you turn on SSR mode for the serve command, you’ll quickly learn what things to avoid to make code SSR compatible, and it will cost you nothing to write such code from the beginning.

If your app doesn’t need SSR, you can just set "ssr": false in the configuration file for the build command and forget about it. But your code will still be reusable in any app.

Standalone

Modern Angular and Nx will generate standalone components, directives, pipes, and libraries by default, without NgModule. Do not try to change it — this is the direction the framework is moving towards, and creating NgModules at this point is pointless. There are still modules, of course, in the libraries and the framework itself, and you’ll use them, just don’t create new modules.

Reactivity

You are creating a new app, so it should use the latest features of Angular and be aligned with the trends in Angular evolution. Create a “zoneless” application. At the time of writing this article, it means that you’ll have to add provideExperimentalZonelessChangeDetection() to your list of providers in the application config.

Don’t be afraid of the “experimental” part — it works very well, even in the most complicated cases, and it might only require some workarounds if the libraries you use have usages of NgZone.onMicrotaskEmpty, NgZone.onUnstable, and NgZone.onStable. Because you are creating a new app, the chances of encountering such cases are low, as Angular is moving toward zoneless architecture, and libraries will support it. Right now, if a library supports the OnPush strategy and doesn’t use the methods of NgZone mentioned above, such a library is fully compatible with “zoneless” Angular apps.

If your app is zoneless, every component has a change detection strategy OnPush and you use only signals in your template — Angular will benefit you with the best possible performance. And in the future, such apps will get even more performance optimizations in the framework core.

State Management

I’ve built multiple apps using the approach explained in this article of mine: Application State Management with Angular Signals.

If you feel that your app is going to be quite complicated and you don’t think createEffect() and signals will be enough — I would recommend giving a try to SignalStore — some professionals I know and respect use this library and love it.

That's it, you definitely will not need more complicated solutions.

And, of course, I recommend my libraries as helpers:

Collection for managing the state of lists/collections;
Reactive Storage for synchronizing data across tabs/windows using Signals, Observables, or Promises.

Testing

For e2e, I recommend Playwright, and if your team really loves to test things — Storybook (in addition).

For unit tests, I recommend Vitest. If you prefer something else — pick a tool that runs tests in a real browser (headless). That makes a huge difference.

Strict TypeScript + Linters

Here are options in tsconfig I use as basis and recommend for your project:

    {
      "strict": true,
      // DO NOT remove 'emitDecoratorMetadata'! '@typescript-eslint/consistent-type-imports' rule requires it
      "emitDecoratorMetadata": true,
      "importHelpers": true,
      "noFallthroughCasesInSwitch": true,
      "noImplicitAny": true,
      "noImplicitThis": true,
      "noImplicitReturns": true,
      "noImplicitOverride": true,
      "noUnusedLocals": true,
      "noUnusedParameters": true,
      "strictNullChecks": true,
      "strictPropertyInitialization": true,
      "useUnknownInCatchVariables": true,
      "noPropertyAccessFromIndexSignature": true,
      "angularCompilerOptions": {
        "strictInjectionParameters": true,
        "strictInputAccessModifiers": true,
        "strictTemplates": true,
        "strictStandalone": true,
        "fullTemplateTypeCheck": true,
        "enableI18nLegacyMessageIdFormat": false,
        "disableTypeScriptVersionCheck": true,
        "extendedDiagnostics": {
          "checks": {
            "optionalChainNotNullable": "suppress",
            "nullishCoalescingNotNullable": "suppress",
            "suffixNotSupported": "warning",
            "textAttributeNotBinding": "warning",
            "invalidBananaInBox": "error",
            "missingControlFlowDirective": "error",
            "missingNgForOfLet": "error",
            "controlFlowPreventingContentProjection": "error",
            "unusedStandaloneImports": "warning"
          },
          "defaultCategory": "error"
        }
      }
    }

That’s not the whole config, just options related to code check.

And ESLint rules:

    {
        'no-extra-boolean-cast': 'error',
        'no-case-declarations': 'error',
        '@typescript-eslint/consistent-type-exports': 'error',
        '@typescript-eslint/consistent-type-imports': 'error',
        '@typescript-eslint/ban-ts-comment': ['off'],
        '@typescript-eslint/no-explicit-any': ['error'],
        '@typescript-eslint/no-non-null-assertion': ['error'],
        '@typescript-eslint/no-unused-vars': [
          'error',
          {
            argsIgnorePattern: '^_',
            varsIgnorePattern: '^_',
            caughtErrorsIgnorePattern: '^_',
          },
        ],
        'rxjs-angular-x/prefer-takeuntil': [
          'error',
          {
            checkComplete: false,
            checkDecorators: ['Component', 'Directive', 'Injectable'],
            alias: ['takeUntilDestroyed'],
            checkDestroy: false,
          },
        ],
        'rxjs/ban-observables': ['error'],
        'rxjs/ban-operators': ['error'],
        'rxjs/no-connectable': ['error'],
        'rxjs/no-cyclic-action': ['error'],
        'rxjs/no-compat': ['error'],
        'rxjs/no-ignored-replay-buffer': ['error'],
        'rxjs/no-unsafe-catch': ['error'],
        'rxjs/no-unsafe-first': ['error'],
        'rxjs/no-unsafe-switchmap': ['error'],
        'rxjs/no-async-subscribe': ['error'],
        'rxjs/no-create': ['error'], //
        'rxjs/no-ignored-observable': ['error'],
        'rxjs/no-exposed-subjects': ['error'],
        'rxjs/no-nested-subscribe': ['error'],
        'rxjs/no-ignored-notifier': ['error'],
        'rxjs/no-redundant-notify': ['error'],
        'rxjs/no-subject-unsubscribe': ['error'],
        'rxjs/no-unbound-methods': ['error'],
        'rxjs/no-unsafe-subject-next': ['error'],
        'rxjs/no-unsafe-takeuntil': ['error'],
        eqeqeq: ['error', 'smart'],
        'prefer-const': 'error',
        'no-unused-expressions': 'error',
        '@angular-eslint/use-lifecycle-interface': 'error',
        '@angular-eslint/no-input-rename': 'off',
        '@angular-eslint/no-empty-lifecycle-method': ['error'],
      }

Plugins for RxJS:

As always, linters’ rules are a very opinionated thing, but if you are looking for an initial setup — this will be helpful and will help you avoid a lot of errors.

Immutability

Make your data structures immutable by default. Don’t expect that your view will be updated because you mutated some field of a large structure — that contradicts how Angular change detection works, so it’s the wrong approach.

Reactivity in Angular works best with Signals, and Signals compare their values by reference (you can change it, but deep checks are expensive and not always safe). This means that you need to create a new value for a signal every time you want to see any changes in your view.

In this article of mine, you can read more about how to implement the simplest kind of immutability without any additional tools.

Nice Little Things

If you haven’t tried it yet, try mat-icon from Angular Material + icons registry. The SVG will be inlined, so you can affect currentColor and set CSS variables, which opens up a lot of possibilities. It is much better than icon fonts — you are not limited by a predefined set of images and can use literally any image you want, even with animations (for some very fancy cases). And they look sharper :)

Nice source of SVG icons: Lucide.

type-fest is a great tool that will add 0 bytes to your bundle.

Try tailwindcss-safe-area if you care about how your app looks in landscape mode on mobile devices.

Things to Avoid

Some Angular features might stay here for a while, but will not be actively developed. I recommend avoiding the following:

Angular Animations — use CSS animations instead. Yes, “leave” animations can’t be replaced, but that’s the only thing;
Old control flow directives: ngIf, ngSwitch*, and, especially ngFor;
If you use Angular Material, only style it using CSS variables, do not create CSS rules with their class names in selectors. It might cause very painful breaking changes.

That’s what I use to create super-performant modern Angular apps. I hope this information will be useful for your awesome apps as well!

Improving Code Reusability in Angular Projects

Evgeniy OZ — Mon, 06 May 2024 11:34:54 +0000

In this article, you’ll find recommendations on how to make your Angular components and services more reusable, maintainable, and scalable.

Pure Functions

The most effective way to make your code reusable is to move as much code as possible to pure functions.

Such functions have no side effects, have no state, and don’t mutate their arguments. Every time we call a pure function with the same arguments, it will return the same result.

Let’s refactor a component’s method into a pure function:

    export class ExampleComponent {
      @Input() items: Item[];
      @Input() users: User[];

      @Output() connected = new EventEmitter<Item>();

      private readonly errEmptyItemMsg = 'Item data can not be empty';

      //...

      protected addConnection(toItem: Item) {
        if (!toItem.data) {
          this.displayError(this.errEmptyItemMsg);
          return;
        }

        let hasNewConnection = false;

        for (const user of this.users) {
          if (!user.itemRefs.includes(toItem.id)) {
            user.itemRefs.push(toItem.id);
            hasNewConnection = true;
          }
        }

        if (hasNewConnection) {
          this.connected.emit(toItem);
        }
      }

      private displayError(errMsg: string) {
        // ...
      }
    }

Method addConnection() validates toItem, then adds a new item ID to every user. It can display an error and emit an event.

Let’s imagine that this method has not 18 lines, but 180, with complex validation rules. And suddenly, we need exactly this logic, with exactly the same validation (or a new data construction) in a completely different module of our application. Do not look at the “Copy” and “Paste” menu items in your editor — if validation logic is changed in one place, it should be modified in every other place.

Even if we were to swear to update this code in every place on every change, it’s still tightly coupled to our component. So, we simply cannot copy this code to any other place without also copying dependent parts of the component. You can easily spot this by looking for the usages of this.:

    this.displayError()
    this.errEmptyItemMsg
    this.users
    this.connected

We can split addConnection() into two methods: validation and linking.

    export class ExampleComponent {
      //...
      @Output() usersChange = new EventEmitter<User[]>();

      protected addConnection(toItem: Item) {
        if (!isItemConnectable(toItem)) {
          this.displayError(this.errEmptyItemMsg);
          return;
        }

        const { users, hasNewConnection } = addItemToUsers(toItem, this.users);

        if (hasNewConnection) {
          this.connected.emit(toItem);
          this.usersChange.emit(users);
        }
      }

      // ...
    }

    export function isItemConnectable(item: Item): boolean {
      // here we have 100 lines of validation...
      // ...
      // ... very complex logic here ...
      // ...
      // ... not like this :)
      return !!item.data;
    }

    export function addItemToUsers(item: Item, users: User[]): {
      hasNewConnection: boolean,
      users: User[],
    } {
      let hasNewConnection = false;
      const updatedUsers = [] as User[];
      for (const user of users) {
        if (!user.itemRefs.includes(item.id)) {
          updatedUsers.push({ ...user, itemRefs: [...user.itemRefs, item.id] });
          hasNewConnection = true;
        } else {
          updatedUsers.push(user);
        }
      }
      return {
        users: updatedUsers,
        hasNewConnection
      };
    }

Because the new functions should be pure, they cannot modify their arguments. So, in addItemToUsers(), we had to create a new array of users and make a shallow copy for the users we want to connect, instead of mutating them directly.

    // before
    if (!user.itemRefs.includes(toItem.id)) {
      user.itemRefs.push(toItem.id);
    }

    // after
    if (!user.itemRefs.includes(item.id)) {
      updatedUsers.push({ ...user, itemRefs: [...user.itemRefs, item.id] });
    } else {
      updatedUsers.push(user);
    }

    this.usersChange.emit(users);

This way, we actually fixed quite a nasty bug of data de-synchronization, described in more detail in this article. Now we will emit a new array of users every time a new connection is created, so the parent component will have the correct data. Bingo!

Now we can reuse our super complex logic in other places — the new functions have no dependencies, all they need are their arguments.

When refactoring your code into pure functions, require as little information in arguments as possible. If your function requires product: HugeProductDataStructure and in its code it uses product just for product.id and product.price, then it is much better to define arguments like productId and productPrice, rather than requiring a structure that might be difficult to fetch in some places of your code. But don’t over-explode your list of arguments ;)

Component State Management

Some methods just can not avoid using this because they have to modify the state of your component. You can still make such code reusable, by moving this logic into a separate file, called “local store”.

A local store might be represented as a class or as a function (see examples in NgRx SignalStore docs).

Here is an example of how we could move logic, responsible for saving users, to a local store:

    @Injectable()
    export class ExampleStore {
      private readonly api = inject(ApiService);

      readonly saveUsers = sideEffect<User[]>(_ => _.pipe(
        exhaustMap((users) => this.api.saveUsers(users)),
        catchError((err) => {
          this.displayError(err.msg);
          return EMPTY;
        })
      ));
    }

    @Component({
      selector: 'app-example',
      // ...
      providers: [ExampleStore]
    })
    export class ExampleComponent {
      // ...
      private readonly store = inject(ExampleStore);

      protected saveUsers() {
        this.store.saveUsers(this.users);
      }
    }

Because of this refactoring, we now can reuse logic, responsible for saving users' data (which often is not as primitive as this example) in other places of our code, simply by injecting the ExampleStore.

You can read more about the benefits that this refactoring brings, and about different kinds of stores, in this article.

In the previous code example, you might notice that saveUsers() has just one line, and some of you may ask, “Maybe we could just call this method directly from the template? Why the extra wrapping?”

The answer here is: it is up to you to decide. Some developers trust their local stores and IDEs, so if the store’s method name or signature changes, the IDE will automatically update it in the template. Other developers say that templates calling only component’s methods look cleaner and more reliable to them. This topic is very subjective, and there cannot be only one correct answer.

Miscellaneous

Prefer composition to inheritance. Never extend components (yes, never). In some very rare cases, when you see that only inheritance can be used, it is okay to extend stores. However, never extend components. We might think that we increase code reusability this way, but there are other ways to achieve the same result without inheritance. What we sacrifice when we extend components is maintainability, and that is a very important aspect of the code.
Even if ::ng-deep is un-deprecated, try to avoid it. When it’s not possible (and there are such cases), use it with extreme care. To help your future self, use very specific selectors inside ::ng-deep. When you reuse components that use ::ng-deep, and these components have multiple levels of sub-components, things might quickly go out of control if the selectors inside ::ng-deep are not specific enough.
When using Observables, avoid nested subscriptions. Additionally, methods of your services that return observables are much more reusable than methods that subscribe. You don’t always need that level of reusability, but sometimes you might want to reuse code that is inside a method that subscribes and unsubscribes. In such cases, just refactor that method into two: one that returns an observable, and the second one that uses that observable.

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Angular Inputs and Single Source of Truth

Evgeniy OZ — Sun, 05 May 2024 12:41:54 +0000

The main way for Angular components to receive external data is through “inputs.” In this article, I’ll explain why the Single Source of Truth principle should be applied to inputs.

Wikipedia provides a scientific description of the Single Source of Truth, but if we apply it to Angular components and their inputs, it will sound like this:

Inputs of a component should only be modified from outside the component.

This simple rule can save your code from very weird bugs. Let’s explore the simplest case:

In this small demo (source code), you can add items to your shopping cart, but after 10 seconds, the list will be replaced with some items you didn’t pick.

This demo emulates a situation where the shopping cart data is loaded from the server, but while the request was loading, the user was able to add some items to the cart. Maybe it’s not the best demo, but I hope it illustrates the idea. Creating code with bugs intentionally is not as easy as it happens unintentionally 😉

Generally speaking, the state of our component is globally mutable. We should avoid it everywhere, not only in components. But let’s see how we can avoid it in components.

Immutable Inputs

Thankfully, Angular gives us two ways to create inputs, that can not be modified inside the component: accessors and signals.

In Angular before v17 accessors were the only way:

    @Component()
    export class ShoppingCart {
      private _items: Item[] = [];

      @Input() set items(items: Item[]) {
        this._items = items;
      }

      get items() {
        return this._items;
      }
    }

In Angular v17.1 we got Signal Inputs:

    @Component()
    export class ShoppingCart {
      items = input<Item[]>([]);
    }

Fewer lines, more awesomeness.

There are also more practical reasons to use signal inputs over setters, you can read about them in this article by Matthieu Riegler.

Now if we try to update items inside the component:

    @Component()
    export class ShoppingCart {
      items = input<Item[]>([]);

      private readonly api = inject(Api);

      constructor() {
        this.api.getCartItems().subscribe((items) => {
          this.items.set(items);
          //         ^^:
          // 🔴 Property 'set' does not exist on type 'InputSignal<Item[]>'.
        });
      }
    }

TypeScript generates an error and protects our code.

If you encounter an error like this, do not try to find a workaround — Angular and TypeScript are on your side here and trying to help you. Modify your code to fix the bug. Sometimes it will require effort and time, but you’ll fix one of the nastiest kinds of bugs.

To fix our example, we should decide which part of our code should be the source of truth for the list of items in our shopping cart. Only that code will be allowed to modify (mutate) the list of items. Also, this code should be responsible for protecting the list from undesired modifications.

In our example, the root component doesn’t need to know what items are in the shopping cart, so it should either the Api service (which is shared globally), or the ShoppingCart component.

In real apps, we might need information about the shopping cart items not only in the ShoppingCart, but also in the navigation components.

So, let’s make the Api service the source of truth for this list:

Now, if you explore the source code, you’ll find that most of the logic is moved to the Api service, and this service now has the only source of truth for the shopping cart items. And now, this service protects this source of truth from unintentional modifications.

      addItemToCart(item: Item) {
        if (untracked(this.$isLoading)) {
          return;
        }
        this._$cartItems.update((items) => Array.from(new Set([...items, item])));
      }

If you are curious why untracked() is used here, this article will be interesting for you.

The code of our components becomes much more compact, and the ShoppingCart component is now a “dumb” component.

    export class ShoppingCart {
      items = input<Item[]>([]);
      removeItem = output<Item>();

      protected remove(item: Item) {
        this.removeItem.emit(item);
      }
    }

The Api service has a little more code now, but for a very good reason — we’ve fixed a bug!

This article uses new features of Angular v17.1, but you could achieve it with just accessors and observables in any version of Angular. Code examples are far from perfect, and it was done intentionally to illustrate how a bug can be introduced and fixed.

The “Signal Source of Truth” architecture (or “rule,” or “principle”) states that if some information is shared across the application, there should be only one part of the code that can mutate this information. This principle can protect your application from bugs, which, as is often the case in practice, are much worse than theoretical examples in articles. Apply it to your components and services to make them more robust!

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Angular Signals, Reactive Context, and Dynamic Dependency Tracking

Evgeniy OZ — Wed, 24 Apr 2024 09:24:42 +0000

To effectively use Angular Signals, it’s crucial to understand the concept of the “reactive context” and how dependency tracking works. In this article, I’ll explain both these things, and show how to avoid some related bugs.

Dependency Tracking

When you use Angular Signals, you don’t need to worry about subscribing and unsubscribing. To understand how it works, we’ll need a few terms:

Dependency Graph: graph of nodes, every node implements ReactiveNode interface;
Producers: nodes that contain values and notify about new values (they “produce reactivity”);
Consumers: nodes that read produced values (they “consume reactivity”);

Signals are producers, computed() is producer and consumer simultaneously, effect() is consumer, templates are consumers.

You can read a more detailed article about the Dependency Graph in Angular Signals (with animated graph example).

How automatic dependency tracking works: there is a variable, global for all the reactive nodes, activeConsumer, and every time computed() runs its computation function, every time effect() runs its side-effects function, or a template is being checked for changes, they:

Read the value of activeConsumer (to remember the previous consumer);
Register themselves as an activeConsumer;
Run the function or execute a template (some signals might be read during this step);
Register the previous consumer (from Step 1) as an activeConsumer.

When any producer is read, it retrieves the value of activeConsumer and includes this active consumer in the list of consumers dependent on the signal. When a signal is updated, it subsequently sends a notification to every consumer from its list.

Let’s examine what happens step by step in this example:

    @Component({
      template: `
       Items count: {{ $items().length }}
       Active items count: {{ $activeItemsCount() }}
    `   
    })
    class ExampleComponent {
      protected readonly $items = signal([{id: 1, $isActive: signal(true) }]);

      protected readonly $activeItemsCount = computed(() => {
        return this.getActiveItems().length;
      });

      private getActiveItems() {
        return this.$items().filter(i => i.$isActive());
      }
    }

The template reads the value of activeConsumer and saves it to the prevConsumer variable (this variable is local for the template);
The template sets itself as activeConsumer;
It calls $items() signal to get a value;
$items signal retrieves the value of activeConsumer;
The received value is not empty (it contains a link to the template), so $items signal puts this value (link to our template) into the list of consumers. After that, every time $items is updated, the template will be notified — a new link has been created in the dependency graph;
$items returns a value to the template;
The template reads the value of $activeItemsCount signal. To return a value, $activeItemsCount needs to run its computation function - the function we pass in our code to computed();
Before running the computation function, $activeItemsCount reads the value of activeConsumer and saves it to its local variable prevConsumer. Because $activeItemsCount is also a consumer, it puts a link to itself to the activeConsumer variable;
Computation function calls getActiveItems() function;
Inside this function, we read the value of $items — steps from 3 to 6 are repeated, but because our template is already dependent on $items, Step 5 will not add a new consumer to the list;
When the value (an array of items) is returned, getActiveItems() reads every element of this array and reads the value of $isActive();
$isActive is a signal. So, before it returns a value, it repeats steps 3–6. During step 4, $isActive retrieves the value of activeConsumer. At this moment activeConsumer contains a link to $activeItemsCount, so at step 5 $isActive (each one from the array) will add $activeItemsCount to the list of dependent consumers. Any time $isActive is updated, $activeItemsCount will be notified, $activeItemsCount will notify our template that its value is stale and needs to be recomputed. After that, our template eventually (not right after the notification) will ask $activeItemsCount what is the new value, and steps from 7 to 14 will be repeated;
getActiveItems() returns a value. $activeItemsCount uses this value for computation and before returning it, it puts the value of its local variable prevConsumer to the activeConsumer variable;
$activeItemsCount returns a value;
The template puts the previously saved value of prevConsumer to activeConsumer.

It is not a short list, but please read it thoroughly.

The most important thing here is: that consumers (computed(), effect(), templates) don’t need to worry about adding signals they read to the list of dependencies. Signals will do it themselves, using the activeConsumer variable. This variable is accessible to any reactive node, so it doesn’t matter how deep in the functions chain some signal will be read — any signal will get the value of activeConsumer and add it to the list of consumers.

Remember: if you call a function in a template, computed() or effect() (a consumer), and that function reads another function and that function reads another function…, and finally, at some level, a function reads a signal, and that signal adds that consumer to its list and will notify it about the updates.

Debugging-like reading can be tedious, so let me entertain you with this small app:

Please do the following in that app:

Click button “2” to make it active, then click it again. Notice that the “Active items” text above the buttons reflects the change;
Click the “Add Item” button;
Click button “4”. Notice that “Active items” doesn’t reflect the change;
Click button “2”;
Now click button “4” a few times and notice that the “Active items” text reflects it as expected.

But why? Let’s check the code:

    export type Item = {
      id: number;
      $isActive: WritableSignal<boolean>;
    };

    @Component({
      selector: 'my-app',
      template: `
        <div>Active items: {{ $activeItems() }}</div>
        <div>
          <span>Click to to toggle:</span>
          @for(item of items; track item.id) {
            <button (click)="item.$isActive.set(!item.$isActive())" 
                    [class.active]="item.$isActive()">
              {{ item.id }}
           </button>
          }
        </div>
        <div>
          <button (click)="addItem()">Add Item</button>
        </div>
      `,
    })
    export class App {
      protected readonly items: Item[] = [
        { id: 1, $isActive: signal(true) },
        { id: 2, $isActive: signal(false) },
        { id: 3, $isActive: signal(true) },
      ];

      protected readonly $activeItems = computed(() => {
        const ids = [];
        for (const item of this.items) {
          if (item.$isActive()) {
            ids.push(item.id);
          }
        }
        return ids.join(', ');
      });

      protected addItem() {
        this.items.push({
          id: this.items.length + 1,
          $isActive: signal(false),
        });
      }
    }

Now let’s analyze why the “Active items” line is not updated correctly.

Binding in our template:

    <div>Active items: {{ $activeItems() }}</div>

$activeItems is a signal, provided by computed():

    protected readonly $activeItems = computed(() => {
      const ids = [];
      for (const item of this.items) {
        if (item.$isActive()) {
          ids.push(item.id);
        }
      }
      return ids.join(', ');
    });

The function we pass to computed() will be re-executed every time any of the signals it reads is updated. What signals do we read there?

It’s $isActive signal of every item in the this.items array.

Notice how the $ sign in the name of the variable helps quickly find the sources of reactivity. This principle applies similarly to the effect() function and component templates. That’s why I use it, but it’s simply a matter of personal preference.

So why $activeItems was not updated after steps 2 and 3?

The computation function will only be re-executed when one of the signals it depends on is updated.

When we click “Add Item”, we modify this.items and create a new signal inside the new item. But before this moment, our computed() function had never read that signal, so it does not have it in the list of dependencies.

Before and after clicking “Add Item,” the list of signals that $activeItems depends on remains unchanged: three $isActive signals from the three items in this.items.

Because none of these signals is modified when we click “Add Item”, computed() will not be notified and the computation function will not be re-executed.

We can toggle our new item in the list of buttons as many times as we want, but only the signals of the 3 first items will notify $activeItems and it will re-execute the function we sent.

But if we re-execute our computation function, it will read all the items from this.items again and will read the new signal, finally. The new signal will become the new dependency of the $activeItems node, and it will be notified every time one of them is changed.

To do this, we need to modify one of the existing dependencies: that’s why we click button “2” in step 4.

This example is created to remind you, that functions we pass to computed() and effect() will only be re-executed, when one of the producers they read is updated.

This is why it is always useful to double-check, what dependencies your computed() has and what of them should cause a re-computation. If some of them should not — use untracked().

Some of the functions we pass to computed() or effect() might read signals (or functions they call might read signals).

    this.$petWalkingIsAllowed = computed(() => {
      return this.$isFreeTime() && this.isItGoodWeatherOutside();
    });

    isItGoodWeatherOutside() {
      return $isSunny() && $isWarm() && !$isStormy();
    }

To understand if we should wrap such calls with untracked() to avoid non-desired recomputations, we can use this logic:

If we don’t want our computed() to compute a new result when that function (isItGoodWeatherOutside()) returns a new value, then wrap it with untracked():

    this.$petWalkingIsAllowed = computed(() => {
      return this.$isFreeTime() && untracked(() => this.$isItGoodWeatherOutside());
    });

    isItGoodWeatherOutside() {
      return $isSunny() && $isWarm() && !$isStormy();
    }

If on every new value from that function we do want to re-run our computation, do not wrap it with untracked().

As you can see, untracked() helps us control which dependencies we want to track. It also helps to manage another important aspect:

Reactive Context

Above, in “How automatic dependency tracking works,” I’ve mentioned the variable activeConsumer.

When activeConsumer is not null, signals we read will add that activeConsumer to the list of consumers, to later notify members of this list about modifications of a signal. If a reactive node is read while activeConsumer is empty, it will not create any new link in the reactive nodes dependency graph.

In other words, while activeConsumer is set, we are reading signals within the Reactive Context.

In the majority of cases, the reactive context will be handled automatically, and only the intended links and dependencies will be created and removed.

But sometimes we unintentionally leak the reactive context.

Let’s try out this app:

If you try to use it, you’ll notice that:

clicking “Add Item” leads to a complete reset of all statuses;
clicking to toggle the status changes it randomly, affecting more than just one button.

Can you quickly spot the bug?

    @Component({
      template: `
        <div>Active items: {{ $activeItems() }}</div>
        <div class="flex-row">
          <span>Click to to toggle:</span>
          @for(item of $items(); track item.id) {
          <button (click)="item.$isActive.set(!item.$isActive())" [class.active]="item.$isActive()" [style.transform]="'scale('+item.$scale()+')'">
            {{ item.id }}
          </button>
          }
        </div>
        <div>
          <button (click)="addItem()">Add Item</button>
        </div>
      `,
    })
    export class App {
      private readonly $itemsCount = signal(3);

      protected readonly $items: Signal<Item[]> = computed(() => {
        console.warn('Generating items!');

        const items: Item[] = [];
        for (let id = 0; id < this.$itemsCount(); id++) {
          const $isActive = signal(Math.random() > 0.5);
          const $scale = signal($isActive() ? 1.2 : 1);
          items.push({ id, $isActive, $scale });
        }
        return items;
      });

      protected readonly $activeItems = computed(() => {
        const ids = [];
        for (const item of this.$items()) {
          if (item.$isActive()) {
            ids.push(item.id);
          }
        }
        return ids.join(', ');
      });

      protected addItem() {
        this.$itemsCount.update(c => c + 1);
      }
    }

What can we see here:

We render the list of items from $items, which is computed();
$items generates a new array of items, and their count is controlled by the $itemsCount signal. Every time we modify $itemsCount, items are regenerated;
addItem() simply increments $itemsCount, triggering recomputation of $items.

Now we can see why “Add Item” works this way. Let’s try to figure out why the status toggling behaves strangely.

If we open the console, we’ll notice that every time we click a button, a “Generating items!” warning is logged. But why? We’re not modifying $itemsCount, so why is $items recomputed?

Perhaps you’ve already noticed that the computation function of $items reads one more source of reactivity: the signal $isActive:

    const $scale = signal($isActive() ? 1.2 : 1);

This signal ($isActive) is being read in the reactive context: activeConsumer contains $items, so $isActive will notify $items about every change. Therefore, when we modify $isActive in an attempt to toggle this status, we trigger recomputation of $items.

There are multiple ways to fix this bug, but this approach prevents the leakage of the reactive context:

    const $scale = signal(untracked($isActive) ? 1.2 : 1);

What does untracked() do?

    /** 
     * https://github.com/angular/angular/blob/75a186e321cb417685b2f13e9961906fc0aed36c/packages/core/src/render3/reactivity/untracked.ts#L15
     *
     * packages/core/src/render3/reactivity/untracked.ts
     *
     **/
    export function untracked<T>(nonReactiveReadsFn: () => T): T {
      const prevConsumer = setActiveConsumer(null);
      try {
        return nonReactiveReadsFn();
      } finally {
        setActiveConsumer(prevConsumer);
      }
    }

sets activeConsumer to null and saves the returned value to the local variable prevConsumer;
runs the given function;
restores activeConsumer from prevConsumer.

It temporarily disables the reactive context, executes our function, and then restores the reactive context.

Because of that, while our function is being executed, if any signals are being read, they will read null from activeConsumer and won’t add it to their lists of consumers. In other words, no new dependencies will be created.

In this example, we have some “hints” in the console, and our code is very small and simple. In real apps, signal reading might be buried deep within the function call chain, and the code could be much larger and more complex. Bugs like this can be challenging to debug in real apps, which is why I recommend preventing them by using untracked() whenever you don't want to leak the reactive context.

There are quite interesting and unexpected ways to leak the reactive context:

Creating an instance of a class that reads some signals;
Calling a function that calls another function, which reads a signal;
Emitting a new value to an observable.

When you use computed() and effect(),

Read other signals with caution — they’ll rerun the entire function every time they change, triggered by any other function.
Make these functions easy to read and understand;
Double-check every source of reactivity that your function consumes.

As is often the case, implicit dependency tracking brings not only benefits but also some trade-offs. But when used with skill and caution, you can build wonderful apps with Angular Signals!

I extend my heartfelt gratitude to the reviewers whose insightful comments and constructive feedback greatly contributed to the refinement of this article:

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Angular Signals: Best Practices

Evgeniy OZ — Mon, 01 Apr 2024 10:20:40 +0000

In this article, I share my experience of working with Angular Signals after almost a year of using them.

When to use Signals?

In templates;
When you need to react to changes in a value without a time aspect.

In Angular templates, Signals are better than Observables: they schedule Change Detection without any pipes, they are glitch-free, and you can read the same signal multiple times and it will be “free” in terms of performance (and read values are guaranteed to be the same). There are other reasons that are not so easy to explain briefly, but that’s already enough to make a rule: every variable (that might change) in your new templates should be a Signal.

Outside of templates, Signals also can be used for reactivity, but, as I mentioned, without a time aspect.

I once wrote a post on Twitter about it, and now I’ll post it here, updated and improved:

There are two ways to create reactive variables in Angular: Observables and Signals. If you describe in words, how your variable should express its reactivity, you’ll see what you need to use.

If the role of a variable can be described as conditions, then you need a Signal:

“if this variable has this value, then display this list”
“if this variable has this value, this button is disabled”

If the description of a variable’s role includes words, related to time, you need an Observable:

“when the cursor moves…”
“wait for the file uploading event and then…”
“every time this event happens, do this…”
“until this event…”
“for N seconds ignore…”
“after this request…”

Signals have no time axis, and they can not delay a value — they always have a value, and their consumers should be always able to read it.

Consumers of Signals, computed(), effect(), and templates do not guarantee that they will read every new value written to the Signals they watch. An updated Signal will be eventually read, not instantly after the update as it happens with Observables. Consumers decide when they will read the new value using their scheduling mechanisms. It might be “in the next task,” “during the next Change Detection cycle,” or at some other moment, up to the consumer.

When to use `computed()`?

Whenever you like!

computed() is the best thing in Angular Signals, incredibly handy and safe to use. Using computed(), you’ll make your code more declarative (you can read more about it in this article).

There are just two rules about the usage of computed():

Do not modify things in computed(). It should compute a new result, that’s it. Do not modify the DOM, do not mutate variables using this, and do not call functions that might do that. Do not push values to Observables — it will cause unintentional reactive context propagation (explained below for effect()). computed() should not have side effects, it should be a pure function.
Do not make asynchronous calls in computed(). This function does not allow modification of Signals (and it is amazingly helpful), but it can not track asynchronous code. Moreover, Angular Signals are strictly synchronous, so if you want to use asynchronous code in computed(), you are doing something wrong. So, no setTimeout(), no Promises, no other asynchronous things.

When to use `effect()`?

Angular docs say that you’ll rarely need effect() and discourage you from using it (copy, if docs will be edited).

And that info is correct: you rarely need effect()… if your code is declarative ;)

The more imperative your code, the more often you’ll need effect(). There is no code without imperative parts, but we all should try to make our code as declarative as possible, so we do need to use effect() as rarely as possible.

Besides the dangers, mentioned by Angular docs (infinite loops, change detection errors), there is another thing, that might be quite nasty: effects are executed in a reactive context, and any code you call in effect, will be executed in a reactive context. If that code reads some signals, they will be added as dependencies to your effect. Here Alex Rickabaugh explains the details.

I still don’t want to encourage you to use effect(), but I’ll give you advice on how to use it as safely as possible:

The function you provide to effect() should be as small as possible. This way it will be easier to read and spot erroneous behavior.
Read signals first, then wrap the rest of the effect into untracked():

    effect(() => {
      // reading the signals we need
      const a = this.a();
      const b = this.b();

      untracked(() => {
        // rest of the code is here - this code should not
        // modify the signals we read above!
        if (a > b) {
          document.title = 'Ok';
        }
      });
    });

Mixing Signals and Observables

…is ok!

Your code will have Signals and Observables, at least because Signals can not be used for every kind of reactivity (see detailed explanation above). It is not an issue, it is perfectly fine.

If you need some value from an Observable in your computed(), create a Signal using toSignal() (outside of computed()).

If you need to read a Signal in Observable’s pipe(), there are two ways:

If you need to react to changes in that Signal in your Observable, then you need to convert that Signal into Observable and add it using some join operator.
If you are sure you just need the current value of a Signal and you don’t need to react to its changes — you can read a Signal directly in your operators or subscribe(). Observable is not a reactive context, so you don’t need untracked() here.

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

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

Preparing our Code for Zoneless Angular

Evgeniy OZ — Sat, 16 Mar 2024 15:54:54 +0000

This article explains how to modify your code to make your library or app work without Zone.js.

What is Zoneless Angular?

In the article “Angular Change Detection — Today and Tomorrow”, I’ve explained how different types of change detection work in Angular.

The main benefit of making Angular apps zoneless is performance. No more unnecessary CD cycles and recomputations of values. No more checking every binding on every mousemove event. No more runOutsideAngular() calls to reduce the amount of CD cycles, no more juggling with detach() and detectChanges().

Another benefit: we can safely use async..await syntax because we don’t rely anymore on monkey-patching Promises by Zone.js.

Removing Zone.js dependency also removes the “Angular-compatible” term for JS tools: you don’t need to worry anymore if changes that some JS tool makes will be caught by Angular’s Change Detection and rendered correctly.

Prerequisites

Before your app goes zoneless, it should be “OnPush compatible”. It means, that every binding in your template is reactive.

Reactive bindings will notify Angular that their value has changed, so the DOM might need to be modified.

Examples of non-reactive bindings:

    @Component({
      template: `
       <div> {{ name }} </div>
       <child [value]="value"/>
    `
    })
    export class ExampleComponent {
       name = "Alice";
       value = "Bob";
    }

The bindings {{ name }} and [value]=”value” lack reactivity — they won’t update if the values of name or value are modified because the template cannot know about it.

Reactive bindings:

    @Component({
      template: `
       <div> {{ name() }} </div>
       <child [value]="value | async"/>
    `
    })
    export class ExampleComponent {
       name = signal("Alice");
       value = new BehaviorSubject("Bob");
    }

Here, the template will get a notification when name or value are updated. What happens in the template (what is marked as dirty, what is marked for traversal) — just implementation details, it doesn’t matter. What matters is: when notified about the changes, Angular knows what part of the views tree it should update.

There are only two requirements:

Every binding in your templates should be reactive;
Angular v17.1+.

No other things are required. If all components in your app have changeDetection: ChangeDetectionStrategy.OnPush then your app will work fine in “zoneless” mode. There are many new things in the latest releases of Angular, but they are not required to be used to make your app zoneless.

Preparing your code

NgZone has a few methods that your app or library may use:

onMicrotaskEmpty();
onStable();
onUnstable();
onError();
run(), runOutsideAngular(), runGuarded(), runTask().

run*() methods are not needed in Zoneless Angular: you can just call your function directly.

Was:

    @Injectable()
    export class ExampleService {
      private ngZone = inject(NgZone);

      draw() {
        this.ngZone.runOutsideAngular(() => this.putPointsToCanvas());
      }

      private putPointsToCanvas() {}
    }

Now:

    @Injectable()
    export class ExampleService {
      draw() {
        this.putPointsToCanvas();
      }

      private putPointsToCanvas() {}
    }

To replace onStable() and onMicrotaskEmpty(), you can use afterRender() or afterNextRender().

afterRender() will be called after every rendering of the application (not some component), and afterNextRender() will be called after the next rendering event, once. Notice that both of them have phases (second argument).

Was:

    @Injectable()
    export class ExampleService {
      private ngZone = inject(NgZone);

      draw(): Observable<string> {
        this.ngZone.onStable().pipe(
          tap(() => this.putPointsToCanvas())
        );
      }

      private putPointsToCanvas() {}
    }

Now:

    @Injectable()
    export class ExampleService {
      private readonly afterNextRender$ = new Subject();

      constructor() {
        afterNextRender(() => this.afterNextRender$.next({}));
      }

      draw(): Observable<string> {
        this.afterNextRender$.pipe(
          tap(() => this.putPointsToCanvas())
        );
      }

      private putPointsToCanvas() {}
    }

This code will work both in Zoneless and “regular” Angular.

Notice that you can use afterRender() and afterNextRender() whenever you want; just call them in an injection context. Because, as the documentation says: “The execution of render callbacks is not tied to any specific component instance, but instead an application-wide hook”.

StackBlitz example:

Third-party libraries

The main purpose of this article is to help library maintainers in preparing their code for Zoneless Angular. But sometimes we use a library that is too large to fork, and we need to make it work in our application right now.

For libraries that are not updated yet and use onStable() or onMicrotaskEmpty(), we can emulate the behavior of onStable() and onMicrotaskEmpty(), and later remove all of these emulations when all the libraries we use are ready for Zoneless Angular (or if and when Angular provides its own emulation).

I’ve created a helper with functions that override the NoopNgZone implementation and emulate the onStable() behavior: GitHub link. I don’t publish it as a library because it is a temporary solution.

I’ll repeat this because it is important: please update your apps and libraries to not rely on NgZone interface (see above how to modify your code). Do not make your code rely on emulations made by this code snippet. Only use it to temporarily workaround limitations of the libraries you cannot modify.

Let me explain how this emulation works:

    export class NoopNgZone implements NgZone {
      // ...

      private readonly onStableEmitter = new EventEmitter<any>();
      private readonly schedule = getCallbackScheduler();

      get onStable() {
        this.schedule(() => this.onStableEmitter.emit({}));
        return this.onStableEmitter;
      }

      // ...
    }

When code calls NgZone.onStable(), our getter returns an Observable. Before returning it, we schedule an emission of the new value (which would mean that the zone is “stable”).

For scheduling, I use awesome code I found in the Angular source code.

Sometimes, libraries are so tightly bound to Zone.js that they expect onStable() or onMicrotaskEmpty() to emit quite often. For them, one event that we emit is not enough.

To make them work, you can find an event after which that library wants to do its job and artificially emit onStable() or onMicrotaskEmpty() when this event happens:

    export class ExampleComponent {
      private readonly ngZoneNoop = inject(NgZone) as NoopNgZone;
      private readonly docClickHandler = () => this.ngZoneNoop.emitOnStable();

      constructor() {
        document.addEventListener('click', this.docClickHandler);
      }

      ngOnDestroy() {
        document.removeEventListener('click', this.docClickHandler);
      }
    }

In the example above, we are listening for click events and making our NgZone implementation emit onStable event on every click.

I hope you will never need to use a workaround like this, and all the libraries will quickly adapt to Zoneless Angular.

Converting our Angular app to zoneless

This part is pretty easy:

Provide a custom NgZone implementation and a scheduler:

    bootstrapApplication(AppComponent, {
      providers: [
        ɵprovideZonelessChangeDetection(), // imported from `@angular/core`
      ]
    });

Remove the import of zone.js in your polyfills.ts file, or (if you don’t have this file), remove the “zone.js” line from the polyfills array in the angular.json file.

That’s it!

You can see that it doesn’t require a lot of changes if your app or lib is already “OnPush-compatible”.

Authors of libraries, please consider making your code compatible with Zoneless Angular. It will not take a lot of effort: afterRender() here, afterNextRender() there and that’s it 😉

The Angular Team needs your feedback, they want to know about the cases that don’t work and where afterRender() is not good enough. Let’s start preparing our codebases and provide them feedback!

I extend my heartfelt gratitude to the reviewers whose insightful comments and constructive feedback greatly contributed to the refinement of this article:

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Hacking Angular Signals

Evgeniy OZ — Tue, 20 Feb 2024 09:45:01 +0000

Let’s check out what Angular Signals have under the hood, and how we can use it for extending their functionality and debugging.

What are Angular Signals

Angular Signals are functions with methods:

    const $val = signal(0);

    // function:
    const value = $val();

    // object:
    $val.set(4);
    $val.update((v) => v * 2);

How is this possible? Because in JavaScript, functions are objects:

    // declaring a function
    const double = (val: number) => val * 2;

    // adding a method
    double.isEven = (number: number) => number % 2 === 0;

    // use as object
    double.isEven(15) // false

    // use as function
    double(8) // 16

How can we use it?

We can:

add new methods;
override methods set() and update() to intercept modifications;
read internal state variables and methods of signal;
create a proxy signal that will intercept reads.

Extending our Signals

Sometimes you need a variable to be a Signal, but some parts of your code would like to use it as an Observable instead.

Fortunately, interfaces of Signals and Observables have no collisions in method names. So let’s create a hybrid:

    export function toObservableSignal<T>(
      s: Signal<T>, 
      options?: ToObservableOptions
    ) {
      if (isDevMode() && !options?.injector) {
        assertInInjectionContext(toObservableSignal);
      }

      // create an observable
      const obs = toObservable(s, options);

      // add methods of observable to our signal object
      for (const obsKey in obs) {
        (s as any)[obsKey] = (obs as any)[obsKey];
      }
      return s;
    }

Usage example:

    @Component({
      //...
      template: `
        <h4>Signal A: {{ a() }}</h4>
        <h4>Observable A: {{a|async}}</h4>
        <h4>Signal C (computed() A*3): {{c()}}</h4>

        {{quote()}}
      `,
    })
    export class App {
      a = toObservableSignal(signal<number>(1));

      // use as Observable
      b = this.a.pipe(
        debounceTime(500),
        distinctUntilChanged(),
        switchMap((v) => this.http.get('https://dummyjson.com/quotes/' + v))
      );

      // use as Signal
      c = computed(() => this.a() * 3);

      quote = toSignal(this.b);

      increment() {
        // "a" will not stop being a Signal after 
        // we used it as an Observable
        this.a.update((v) => v + 1);
      }

      decrement() {
        this.a.update((v) => Math.max(1, v - 1));
      }
    }

You can find this function in the NG Extension Platform: documentation.

This function can be improved in multiple ways, so your pull requests are welcomed!

You can extend Signals with any functions you want, your fantasy here has almost no limitations: just don’t use names set, update, and asReadonly.

Overriding existing methods

Let’s say that we want to intercept writes to our Signal to transform input values, duplicate information somewhere else, or just for debugging.

    function skipNonEvenNumbers(s: WritableSignal<number>) {
      const srcSet = s.set; // we need the source method to avoid recursion

      s.set = (value: number) => {
        if (value % 2 !== 0) {
          console.warn('[set] skipping:', value);
          return;
        }
        console.log('[set]:', value);
        srcSet(value);
      };
      s.update = (updateFn: (value: number) => number) => {
        const value = updateFn(s());
        if (value % 2 !== 0) {
          console.warn('[update] skipping:', value);
          return;
        }
        console.log('[update]:', value);
        srcSet(value);
      };
    }

Usage example.

This trick is being used in Reactive Storage: getWritableSignal().

Inside a Signal

Angular Signal is not just a function, it is an object. This object has a hidden field, SIGNAL, which contains some interesting data and functions. I’m glad we have it, and I hope you will not abuse it. Because the tricks above were “a little bit hacky”, and the tricks below are too filthy to use for anything but debugging, creating dev tools, and fun.

Every Angular Signal extends ReactiveNode:

    // packages/core/primitives/signals/src/graph.ts

    export const REACTIVE_NODE: ReactiveNode = {
      version: 0 as Version,
      lastCleanEpoch: 0 as Version,
      dirty: false,
      producerNode: undefined,
      producerLastReadVersion: undefined,
      producerIndexOfThis: undefined,
      nextProducerIndex: 0,
      liveConsumerNode: undefined,
      liveConsumerIndexOfThis: undefined,
      consumerAllowSignalWrites: false,
      consumerIsAlwaysLive: false,
      producerMustRecompute: () => false,
      producerRecomputeValue: () => {},
      consumerMarkedDirty: () => {},
      consumerOnSignalRead: () => {},
    };

this way:

    // packages/core/primitives/signals/src/signal.ts

    export const SIGNAL_NODE = {
      ...REACTIVE_NODE,
      equal: defaultEquals,
      value: undefined,
    }

But an instantiated Signal object does not contain all of this directly. All of them are hidden under the field that uses a Symbol as a name:

    // packages/core/primitives/signals/src/signal.ts

    export function createSignal<T>(initialValue: T): SignalGetter<T> {
      const node: SignalNode<T> = Object.create(SIGNAL_NODE);
      node.value = initialValue;
      const getter = (() => {
                       producerAccessed(node);
                       return node.value;
                     }) as SignalGetter<T>;

      // next line adds a SignalNode to the field SIGNAL:
      (getter as any)[SIGNAL] = node;
      return getter;
    }

So if you have a signal $value and you access SIGNAL field, then you’ll get all of the fields that SIGNAL_NODE has.

How can we use it?

We can read fields and override methods to intercept access and use it for debugging or to create fancy tools that illustrate what is going on inside a Signal and render the Dependency Graph.

We can even convert some fields to accessors:

    function getSignalVersion<T>(s: WritableSignal<T>): Signal<number> {
      const node = s[SIGNAL];
      const $version = signal(0);

      Object.defineProperty(node, 'version', {
        get: () => {
          const v = untracked($version);
          console.log('🟢 reading:', v);
          return v;
        },
        set: (v) => {
          untracked(() => $version.set(v));
          console.log('🔴 writing:', v);
        },
      });

      return $version.asReadonly();
    }

StackBlitz.

Or create a proxy that can watch Signal reads without effect():

    function watchSignalReads<T, M extends Signal<T> | WritableSignal<T>>(s: M): M {
      const node = s[SIGNAL];
      const newGetter = () => {
        const value = s();
        console.log('Read:', value);
        return value;
      };
      (newGetter as any)[SIGNAL] = node;
      if (s.hasOwnProperty('set')) {
        const w = s as WritableSignal<T>;
        newGetter.set = w.set;
        newGetter.update = w.update;
        newGetter.asReadonly = w.asReadonly;
      }

      return newGetter as M;
    }

Usage example.

Again, I hope you won’t even consider using this in “production,” and instead, I hope you’ll utilize it to create some amazing tools, gain recognition, and contribute to enriching the Angular ecosystem 😎

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

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

Creating Angular Components: Template-First Declarative Approach

Evgeniy OZ — Tue, 06 Feb 2024 11:56:19 +0000

This article explains how to build a reactive and reusable Angular component in a declarative way, using a “template-first” approach.

So, we need a component!

We need to display a table of items, with pagination, each column should be sortable in ascending or descending order.

Let’s use ng g c items-table to generate a component, and then add file items-table.store.ts to the folder, generated by Angular CLI. If you don’t know why I call it “store”, this article is for you.

I recommend using stores for non-trivial components and moving most of the logic there. This way it will be much easier to reuse code (not bound to the template anymore) and to communicate from child components.
It is not so significant detail for the approach I’m describing in this article: if you prefer to put it all into the component itself — I don’t mind at all.

An important part of this approach is to start creating the template first, not anything else.

We have an empty template, generated by Angular CLI:

    <p>items-table works!</p>

We need a table, so let’s put a table here:

    <table class="table table-sm table-striped">
      <thead>
      <tr>
        @for (header of store.$headers(); track header.path) {
        }
      </tr>
      </thead>
    </table>

Your IDE will start complaining that you don’t have store.$headers() yet. But let’s ignore it for now and just keep creating our template — it is better to don’t interrupt this process and express what we need in the template first, without thinking about the implementation.

    <table class="table table-sm table-striped">
      <thead>
      <tr>
        @for (header of store.$headers(); track header.path) {
          <th (click)="store.changeSorting(header.path)">
            <span class="d-flex flex-row align-items-center gap-2">
              <span>{{ header.label }}</span>
              @if (store.$sortByHeader() === header.path) {
                @if (store.$sortingOrder() === 'asc') {
                  <ng-container *ngTemplateOutlet="iconSortDown"></ng-container>
                } @else {
                  @if (store.$sortingOrder() === 'desc') {
                    <ng-container *ngTemplateOutlet="iconSortUp"></ng-container>
                  }
                }
              }
            </span>
          </th>
        }
      </tr>
      </thead>

      <tbody>
        @for (item of store.$items(); track item) {
          <tr>
            @for (header of store.$headers(); track header.path) {
              <td>{{ item[header.path] }}</td>
            }
          </tr>
        }
      </tbody>
    </table>

    <!-- Pagination -->
    <div class="d-flex flex-row justify-content-center">
      <div class="btn-group">
        <button type="button" class="btn btn-outline-primary" (click)="store.prevPage()">⬅️</button>
        <button type="button" disabled class="btn btn-primary">{{ store.$page() + 1 }}</button>
        <button type="button" class="btn btn-outline-primary" (click)="store.nextPage()">➡️</button>
      </div>
    </div>

Now we’ve declared in our component what we need to render it.

You can find the code, described in this article, in this repository: 🔗 GitHub.

Now, we can start implementing all the data bindings and events handlers.

Reactive Data Bindings

I recommend using Signals in Angular templates as the reactive containers of data.

The first signal we need to create is store.$headers():

    // items-table.store.ts

    export type ItemsTableHeader = {
      path: keyof Item;
      label: string;
    }

    @Injectable()
    export class ItemsTableStore {
      readonly $headers = signal<ItemsTableHeader[]>([]);
    }

The next highlighted thing is an event handler, but let’s postpone it for now, and take the next signals: $sortByHeader() and $sortingOrder():

    // items-table.store.ts

    readonly $sortByHeader = signal<string | undefined>(undefined);
    readonly $sortingOrder = signal<'asc' | 'desc'>('asc');

And now, the most interesting part, $items()!

We could naively implement it like this:

    readonly $items = signal<Item[]>([]);

But, then for pagination and sorting we would need to overwrite the value of that signal. It is an imperative approach, and it is not good enough for us: this way $items would have multiple sources of truth: component input, pagination side effects, and sorting. They all would write into our signal, and we would have to control in what order they should do this…

The imperative approach is only simpler when the first line is written, later imperative code evolves into a more and more complicated mess.

Let’s use the declarative approach instead.

Derived values

The initial source of items is the component’s inputs — and we should react to the changes in this input too:

    @Component({
      selector: 'items-table',
      // ...
      providers: [ItemsTableStore],
    })
    export class ItemsTableComponent {
      protected readonly store = inject(ItemsTableStore);

      @Input({ required: true }) set items(items: Item[]) {
        if (items) {
          this.store.setItems(items);
        }
      }
    }

When we produce the list of items, the last thing that will decide what items we should render on this page is pagination.

      // items-table.store.ts

      readonly $itemsPerPage = signal<number>(5);
      readonly $page = signal<number>(0);

      private readonly $inputItems = signal<Item[]>([]);

      readonly $items = computed(() => {
        const items = this.$inputItems();
        // pagination:
        const page = this.$page();
        const perPage = this.$itemsPerPage();
        if (page === 0 && items.length <= perPage) {
          return items;
        }
        return items.slice(page * perPage, page * perPage + perPage);
      });

      setItems(items: Item[]) {
        this.$inputItems.set(items.slice());
      }

Items should be sorted, in selected order, and sorting should happen before pagination, otherwise, we’ll only sort items on the selected page.

So let’s create a computed signal that will produce sorted items from $inputItems(), and our paginated $items() will use that produced result as input:

      // items-table.store.ts

      readonly $sortedItems = computed(() => {
        const sortPath = this.$sortByHeader();
        if (!sortPath) {
          return this.$inputItems();
        }
        const items = this.$inputItems().slice();

        items.sort((a, b) => {
          const aVal = a[sortPath];
          const bVal = b[sortPath];
          if (typeof aVal === 'number' && typeof bVal === 'number') {
            return aVal < bVal ? -1 : (aVal > bVal ? 1 : 0);
          } else {
            return a[sortPath].toString().localeCompare(b[sortPath].toString());
          }
        });

        if (this.$sortingOrder() === 'asc') {
          return items;
        } else {
          return items.reverse();
        }
      });

      readonly $items = computed(() => {
        const items = this.$sortedItems();
        // pagination:
        // ...
      }

All the data bindings are implemented, let’s implement event handlers.

Side Effects

The first event handler, changeSorting(), is a function that will return nothing but after its execution, the state of our store will be modified — it is a side effect of that function, and often such functions are called “side effects” (or “effects”) for brevity.

Side effects are the only place where our imperative code should be located. As you might noticed, all the computed() signals just return the result, based on inputs, and don’t have side effects (they don’t write to signals). It makes them pure functions. Writing to signals is not allowed in computed() exactly to make them pure functions. I recommend using computed() because of this — your code will be declarative and clean.

      // items-table.store.ts

      changeSorting(path: keyof Item) {
        if (path === this.$sortByHeader()) {
          if (this.$sortingOrder() === 'asc') {
            this.$sortingOrder.set('desc');
          } else {
            this.$sortByHeader.set(undefined);
          }
        } else {
          this.$sortByHeader.set(path);
          this.$sortingOrder.set('asc');
        }
      }

Handlers prevPage() and nextPage() are simple:

      // items-table.store.ts

      prevPage() {
        const page = this.$page();
        if (page > 0) {
          this.$page.set(page - 1);
        }
      }

      nextPage() {
        const page = this.$page();
        const items = this.$sortedItems();
        if (items.length > ((page + 1) * this.$itemsPerPage())) {
          this.$page.set(page + 1);
        }
      }

I omitted the implementation of headers input of our component in the article, but you can find it in the source code (it is too simple to be illustrative).

That’s it!
Now our component will render a table of items, and the content of this table is reactive — it will be modified in response to user actions.

In the source code, you can check out how the parent component (app.component.ts) uses our component. Also, if you open the resulting app in multiple tabs, and start switching “collections”, you’ll see they all synced across tabs, using just 1 line of code 😎

You can play with the deployed app using this link.

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Globally Shared Instances in Angular — Use with Care

Evgeniy OZ — Tue, 06 Feb 2024 11:52:22 +0000

Why you should use {providedIn: “root”} not always, not by default, but only when you need it and know how to use it.

Why do we need the `Injectable()` decorator?

To let the Angular Dependency Injection mechanism inject it. So by definition, if you decorate your class with the Injectable(), you want to later use it in your components (or other services), and let Angular DI take care of the dependencies of this decorated class.

There is one configurable option: providedIn, which currently has only 2 meaningful values: root and undefined (default).

Services with providedIn: root will be instantiated just once. Without this option — will be instantiated every time, when a component that has them in its providers array is instantiated. That is an important difference.

Why ‘use with care’?

Services, providedIn: root will be shared across your application. It means, that every component, every service that injects such services, will get the same instance. It is not “bad”, or “wrong”, it just means that you should write the code in such services with constant consideration, that multiple components will use it at the same time.

Sometimes it is exactly what you need! For example, HttpClient with its interceptors. You want to configure them once and use the same instance of HttpClient across the whole application.

But quite often developers just add it because tutorials told them to, and they don’t know other ways of injecting a service. And not every time developers are actually aware of the fact that multiple components will share the same instance of the service they create.

Here is a modified example from Angular documentation:

    import {Injectable} from '@angular/core';
    @Injectable({
      providedIn: 'root',
    })
    export class CalculatorService {
      scale = 1;

      add(x: number, y: number) {
        return (x + y) * this.scale;
      }
    }

If some component modifies the scale field, all other components that use this service will be affected. It is a simplified example, in the real code things are more sophisticated.

How to use it correctly?

The main rule of globally shared services: they should either not have an internal state, or their state should not be modifiable after instantiation, or their code should be aware that multiple different consumers will modify this state in a chaotic order (that’s why methods that modify the state should be atomic — only one call should be expected from a consumer, not a set of calls, executed in pre-defined order).

I’m not saying “do not use it”, but: if you want to share the single instance of that service with all the components that use it — do it, and write the code accordingly.

If you want a new instance of this class whenever some component is instantiated, and have it destroyed when a component is destroyed — do not add providedIn: root, just add Injectable() and add this service to the providers array of that component.

If your class has no dependencies and you don’t need it to be shared across multiple components — then you don’t even need the Injectable() decorator, you can just use new.

In my article Advanced Usage of Angular Dependency Injection you can find more examples of using Angular DI in your apps.

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Hidden Reactivity Tricks in Angular Templates

Evgeniy OZ — Tue, 06 Feb 2024 11:45:28 +0000

Let me show you some tricks you can use to add reactivity to your templates, even when it looks impossible.

I’ll show you how to make any field of an object reactive, and you will not even need the async pipe to get the updates.

Let’s start with a simple template:

    <ul>
      @for(item of items; track item.id) {
        <li>{{ item.name() }}: {{ item.id }}</li>
      }
    </ul>

Here is the type of “item” objects:

    type Item = {
      name: () => string;
      id: number;
    }

As you can see, name can be updated synchronously, id can not be updated at all.

But what if I tell you, that both of them can be reactive? And you can update them any way you need: synchronously or asynchronously.

When Angular reads signals in a template, the template becomes a consumer of these signals. And whenever you update these signals, the template will be notified. It is a simple concept to grasp.

But there is more: when a template calls some function to get its value, and this function reads a signal — the template still becomes a consumer of that signal. And the level of nesting doesn’t matter! Only two things can prevent it: if you make an asynchronous call, or if you wrap your call with untracked().

Example:

    {{ name() }}

    $user = signal({name: 'John Doe'});

    name() {
      return [this.firstName(), this.lastName()].join(' ');
    }

    private firstName() {
      return this.getNameParts()[0];
    }

    private lastName() {
      return this.getNameParts()[1];
    }

    private getNameParts() {
      // here we read a signal!
      return this.$user().name.split(' ');
    }

    updateUser() {
      this.$user.set({name: 'Jane Doe'});
    }

Here you can see 3 levels of nested calls before we read the signal. Two levels of function don’t know anything about the signal. And still, because the last one reads the signal, all of them will be called by the template again, after the signal is updated.

Yes, the code of this example is not perfect — it was made intentionally, to illustrate the idea.

Asynchronous reactivity using synchronous function call

    protected readonly items: Item[] = [];

    private readonly repeat$ = timer(0, 2000);
    private readonly $repeat = toSignal(this.repeat$, {
        initialValue: undefined
    });

    constructor() {
        for (let i = 0; i < 10; i++) {
          const item: Item = {
            name: () => 'Item ' + i.toString() + ':'.repeat(this.$repeat() ?? 0),
            id: i,
          };

          this.items.push(item);
        }  
    }

Here we have a source of asynchronous data: observable repeat$.
We convert it into a signal, that can be read synchronously: $repeat.

When we populate the items array, we assign a function to the name field, that reads the $repeat signal every time it is called.

And because it is a signal, our template will become a consumer of this signal when name() is called! After that, whenever $repeat is updated, our template will be notified.

The source of data is asynchronous, but you don’t need async pipe to get the update notifications.

Because Angular Signals match the signature of a callback () => T, you can just use signals to add reactivity when a callback function is accepted as a value for a field.

Replacing fields with getters to make them reactive

Field id also can be reactive — we can replace it with a getter in our object, and this getter will read a signal:

    private readonly $offset = signal<number>(0);

    constructor() {
        for (let i = 0; i < 10; i++) {
          const $id = computed(() => i + this.$offset());

          const item: Item = {
            name: () => 'Item ' + i.toString() + ':'.repeat(this.$repeat() ?? 0),
            get id() {
              return $id();
            },
          };

          this.items.push(item);
        }
    }

Now, when the template reads id, it becomes a consumer of $id — a signal, created using computed(), which reads the signal $offset. Whenever $offset is updated, $id is notified and this signal notifies the template.

This trick might become very useful if you need to add reactivity to some part of an existing template, and migrating it to signals or observables is too expensive or too dangerous.

Combining Signals with Observables

Quite often we need more complicated sources of asynchronous data, than just timer().
The most common source of asynchronous data is HTTP requests. Let me show you how you can easily combine Signals and Observables to get the ultimate power.

Template:

    <p>Current temperature in Barcelona: {{temp()}}</p>

    <button (click)="readTemp()">Check Temperature</button>

Component:

      private readonly reloadTemp$ = new Subject<void>();
      private readonly $tempIsLoading = signal<boolean>(false);
      private readonly http = inject(HttpClient);

      readTemp() {
        this.reloadTemp$.next();
      }

      // observable becomes a signal
      private readonly $weather = toSignal(
        this.reloadTemp$.pipe(
          startWith({}),
          switchMap(() => {
            this.$tempIsLoading.set(true);
            return getWeather(this.http).pipe(
              finalize(() => this.$tempIsLoading.set(false))
            );
          })
        ),
        { initialValue: undefined }
      );

      // consumer of $weather
      private readonly $temp = computed(() => {
        if (this.$tempIsLoading()) {
          return 'Checking...';
        }
        const w: any = this.$weather();
        if (!w) {
          return 'Error';
        }
        return w.current.temperature_2m + '℃';
      });

      private getTemperature() {
        return this.$temp();
      }

      protected temp() {
        // just to illustrate the fact,
        // that this function does not know 
        // anything about the signal it will use.
        return this.getTemperature();
      }

You can find the full code of all these examples and play with this app: StackBlitz.

Using tricks like these, you can add reactivity to the places where it was impossible to start thinking about, and most of the time you will not even need to modify a template.

🪽 Do you like this article? Share it and let it fly! 🛸

💙 If you enjoy my articles, consider following me on Twitter, and/or subscribing to receive my new articles by email.

Forem: Evgeniy OZ

Reactivity in Angular

The Magic

What works

What is the price

Did you just say mousemove?

Is the OnPush Change Detection Strategy Enough?

Pure Reactivity

Reactive bindings

Immutability

Performance

Links:

Examples of linkedSignal() usage in Angular applications

The main use case

With great power…

Starting a Modern Angular Application

Workspace

Angular CLI, without separation by sub-modules/packages/libraries

Angular CLI to create a monorepo, all the code is in libraries

Using Nx to create a monorepo.

Style

SSR

Standalone

Reactivity

State Management

Testing

Strict TypeScript + Linters

Immutability

Nice Little Things

Things to Avoid

Improving Code Reusability in Angular Projects

Pure Functions

Component State Management

Miscellaneous

Angular Inputs and Single Source of Truth

Immutable Inputs

Angular Signals, Reactive Context, and Dynamic Dependency Tracking

Dependency Tracking

Reactive Context

Angular Signals: Best Practices

When to use Signals?

When to use computed()?

When to use effect()?

Mixing Signals and Observables

Preparing our Code for Zoneless Angular

What is Zoneless Angular?

Prerequisites

Preparing your code

Third-party libraries

Converting our Angular app to zoneless

Hacking Angular Signals

What are Angular Signals

Extending our Signals

Overriding existing methods

Inside a Signal

Creating Angular Components: Template-First Declarative Approach

So, we need a component!

Reactive Data Bindings

Derived values

Side Effects

Globally Shared Instances in Angular — Use with Care

Why do we need the Injectable() decorator?

Why ‘use with care’?

How to use it correctly?

Hidden Reactivity Tricks in Angular Templates

Asynchronous reactivity using synchronous function call

Replacing fields with getters to make them reactive

Combining Signals with Observables

When to use `computed()`?

When to use `effect()`?

Why do we need the `Injectable()` decorator?