DEV Community: Giancarlo Buomprisco

Introduction to Next.js Server Actions

Giancarlo Buomprisco — Thu, 08 Jun 2023 14:48:45 +0000

This article was originally posted on makerkit.dev.

The new App Router released in Next.js 13 brings with it a tons of new features that brought the famous framework by Vercel to a whole new level. We have discussed the new App Router in our article Next.js 13: complete guide to Server Components and the App Directory.

What are Next.js Server Actions?

One of the most exciting features is the introduction of Server Actions or Server Functions. Just like the word says, Server Actions are functions that run on the server, but that we can call from the client, just like a normal function. This is a huge step forward for Next.js, as it allows us to run code on the server without having to create an API endpoint. This is a whole new DX for Next.js developers, and it's going to be a game changer.

To be totally honest, this is actually not a Next.js-specific concept: rather, it's a [React.js built-in functionality, which is still in alpha.

What can I do with Next.js Server Actions?

Server Actions are a very powerful feature, and they can be used for a lot of different use cases. Here are a few examples:

writing to a database: you can write to a database directly from the client, without having to create an API endpoint - just by defining your logic in a server action.
server logic: executing any server-related business logic, such as sending emails, creating files, etc.
calling external APIs: you can call external APIs directly from server actions, without having to create an API endpoint

In summary, you can do anything you would normally do on the server, but without having to create an API endpoint.

Pros to using Next.js Server Actions

There are a few pros to using Next.js Server Actions:

No need to create an API endpoint: you can run server code without having to create an API endpoint.
Jumping to the definition: you can jump to the definition of a server action just by clicking on it in your code editor, without the need of searching for it in your codebase.
Type safety: you can use TypeScript to define the arguments and return value of your server actions, and Next.js will automatically validate them for you.
Less code: you can write less code, as you need a lot less boilerplate to run server code - you can just define a function and its parameters - and then call it from the client.

There's a lot to love about Next.js Server Actions, and I'm sure you'll find a lot of use cases for them.

How to define a Next.js Server Action

Server actions can normally be defined anywhere in your components, but with a few exceptions. Let's take a look at a few scenarios.

Before you start, ensure you have enabled the experimental server actions in your next.config.js file:

module.exports = {
  experimental: {
    serverActions: true,
  }
};

Defining a Server Action in a Server Component

If you are defining a server action in a server component, the only thing you need to do is to define a function with the use server keyword at the top.

For example, the below is a valid server action:

async function myActionFunction() {
  'use server';

  // do something
}

Very important: server actions functions should have serializable arguments and a serializable return value based on the React Server Components protocol. This is because the function's response will be serialized and sent to the client.

Defining multiple Next.js Server Actions

An alternative way to define a server action is to use export multiple functions from a file, adding the use server keyword at the top of the file.

'use server'

export async function myActionFunction() {
  // do something
}

export async function anotherActionFunction() {
  // do something
}

Client Components can only import actions from server actions files: client components cannot define server actions inline from the same file - but you can still import them from a file that defines multiple server actions using the use server keyword.

How to invoke a Next.js Server Action

To invoke a server action, you have numerous options.

Invoking a Server Action from a Form

The simplest way to invoke a server action is to invoke it from a form. To do so, you can use the onSubmit prop of the form element, and call the server action from there.

export function MyFormComponent() {
  function handleFormAction(
    formData: FormData
  ) {
    'use server';

    const name = formData.get('name');
    // do something
  }

  return (
    <form action={handleFormAction}>
      <input type={'name'} />

      <button type="submit">Save</button>
    </form>
  );
}

Invoking a Server Action from a Button

You can also invoke a server action from a button. To do so, you can use the handleAction prop of the button element, and call the server action from there.

export function Form() {
  async function handleSubmit() {
    'use server';
    // ...
  }

  return (
    <form>
      <input type="text" name="name" />
      <button formAction={handleSubmit}>Submit</button>
    </form>
  );
}

Invoking a Server Action imperatively

You can also invoke a server action imperatively, by using the useTransition hook.

First, we define our server action in a separate file that defines multiple server actions:

'use server';

export async function saveData(id) {
  await addItemToDb(id);

  revalidatePath('/product/[id]');
}

Then, we can import it in our client component, and invoke it imperatively using the useTransition hook:

'use client';

import { useTransition } from 'react';
import { saveData } from '../actions';

function ClientComponent({ id }) {
  let [isPending, startTransition] = useTransition();

  return (
    <button onClick={() => startTransition(() => saveData(id))}>
      Save
    </button>
  );
}

Revalidating data after a Server Action

You can use the revalidatePath function to revalidate the data for a specific path. This is useful if you want to revalidate the data for a specific path after the server action has been executed.

Progressive Enhancement

If you use Server Actions from a form component, these will also work if JavaScript is disabled, as the form will be submitted to the server, unlike actions that are invoked imperatively, which will only work if JavaScript is enabled.

If you can, you're encouraged to use Server Actions from forms, as this will ensure your app works even if JavaScript is disabled.

Server Mutations

Next.js defines Server Mutations as Server Actions that mutate your data and calls redirect, revalidatePath, or revalidateTag.

If you are not doing any of these - you are not doing a mutation, and are not required to use useTransition: in such cases, you can just call the server action directly from your client components.

Conclusion

In this article, we've seen how to use Next.js Server Actions, and how to invoke them from client components.

You can use these today, but they are still experimental, so you should use them with caution - since the API might change in the future.

Next.js 13: complete guide to Server Components and the App Directory

Giancarlo Buomprisco — Sat, 03 Jun 2023 19:12:07 +0000

This article was originally published on makerkit.dev

Hi and welcome! In this tutorial, we'll learn how to use Next.js 13 with server components and the app directory.

What does Next.js 13 bring to the table?

Next.js 13 is a major release of the most popular React framework: in fact, it ships with a new routing system, also called App Router. In many ways, this new routing system is a complete rewrite of the previous one, and fundamentally changes the way we will write Next.js applications.

The new app directory brings many improvements to the existing pages directory, and it's the new default way to write Next.js apps, after a period of experimental releases.

Server Components (RSC)

The biggest change in the new App Router is the introduction of Server Components, a new type of React components that run on the server and return compiled JSX that is sent to the client. Server Components are useful for rendering the skeleton of a page, fetching data from the server in parallel, and passing it to the "client components".

Server Components are the default component type in the new app directory.

Layouts

Powered by Server Components, layouts are foundational components that wrap pages. Next.js Layouts are not only useful for displaying a common UI across pages, but also to reuse logic and data fetching across pages.

Layouts also solve the waterfall problem, which is a common issue with the current Next.js routing system. In fact, with the new App Router, we can fetch data in parallel, and pass it to the page component: this is a substantial performance improvement over the current routing system.

Server Actions

Still in alpha, Server Actions are a new way to execute functions on the server, instead of wiring them through an API handler. Server actions are useful for executing server-side logic, such as sending emails, or updating a database. Server actions are useful for submitting forms, execute server-side logic, and redirect the user to a new page.

Additionally, server actions offer us the ability to revalidate data fetched from Server Components, eliminating the need for complex client-side state management as a result of data mutation (such as updating a Redux store).

Enhanced Router

Using conventional filenames, we can add various types of components in the app directory. This is a big improvement over the current routing system, which requires us to use a specific directory structure to define pages, API handlers, and so on.

What does this mean? From now on, we can create various types of components in the app directory using a specific filename convention specific to Next.js:

pages are defined as page.tsx
layouts are defined as layout.tsx
errors are defined as error.tsx
loading states are defined as loading.tsx

What are Server Components?

Server Components are a new type of React components that run on the server and return compiled JSX that is sent to the client. Next.js, with its new app directory released in Next.js 13, fully embraced Server Components by making them the default type components.

This is a big shift from traditional React components that run both on the server and on the client. In fact, as we have specified, React Server components do not execute on the client.

As such, there are some constraints to using Server Components that we need to keep in mind:

Server components cannot use browser-only APIs
Server components cannot use React hooks
Server components cannot use Context

So, what are they for?

React Server Components are useful for rendering the skeleton of a page, while leaving the interactive bits to the so-called "client components".

Despite their name, "client components" (which, IMHO, is unfortunate) are also server-rendered, and they run on both the server and the client.

React Server Components can be useful because they allows us to:

render pages faster
reduce the amount of JavaScript that needs to be sent to the client
improve the routing performance of server-rendered pages

In short, we use Server Components to fetch data from the server and render the skeleton of a page: then, we can pass the data to the "client components".

Server Components vs Client Components

As we have seen, Server Components are useful for rendering the skeleton of a page, while Client Components are the components as we know them today.

This comparison in the Next.js docs is a good way to understand the difference between the two.

Defining Server Components

Server components do not need a notation to be defined as such: server components are the default components when rendered in the app directory.

We cannot use React hooks, Context, or browser-only APIs in Server Components. However, we can use Server Components only APIs, such as headers, cookies, etc.

Server components can import client components.

There is no need to specify a notation to define a Server Component: in fact, Server Components are the default component type in the new app directory.

Assuming the component ServerComponent is not a child of a Client Component, it will be rendered on the server and sent to the client as compiled JSX:

export default function ServerComponent() {
  return <div>Server Component</div>;
}

Defining Client components

On the contrary, in the Next.js app directory, we need to specifically define client components.

We can do this by specifying the use client pragma at the top of the file:

'use client';

export default function ClientComponent() {
  return <div>Client Component</div>;
}

When we use client components, we can use React hooks, Context, and browser-only APIs. However, we cannot use some Server Components only APIs, such as headers, cookies, etc.

NB: Client components cannot import server components, but you can pass a Server Component as a child or prop of a Client Component.

App directory

The new "app" directory released in Next.js 13 is an experimental a new way to build Next.js apps. It coexists with the pages directory, and we can use it to incrementally migrate an existing project to the new directory structure.

This new directory structure is not just a new way to write apps, it's a whole new routing system underneath, much more powerful than the current one.

File Structure

What does the new Next.js 13 file structure look like? Let's take a look at the example app we'll be using in this tutorial.

Below is an example of a Next.js 13 app with the new app directory:

- app
  - layout.tsx
  - (site)
    - page.tsx
    - layout.tsx
  - app
    - dashboard
      - page.tsx
    - layout.tsx

As you can see, the name of the file reflects the type of component it is. For example, layout.tsx is a layout component, while page.tsx is a page component, and so on.

Don't worry, we will go through all the different types of components in the next sections.

Colocation

One important side-effect of the new app directory is that it allows us to colocate our files. Since filenames are conventional, we can define any file in the app directory without these becoming pages components.

For example, we could place our components for a specific page right in the folder where it's defined:

- app
  - (site)
    - components
      - Dashboard.tsx
    - hooks
      - use-fetch-data-hook.ts
    - page.tsx

Why is (site) in parentheses? By using parenthesis, we make the directory site "pathless", which means we can create new layouts, loading files, and pages in the site directory, without adding a new path segment to the routing.

All pages under (site) will be accessed from the root path /: for example, the page app/(site)/page.tsx will be accessible at /.

Layouts

Layouts are one of the biggest new functionality made possible by the new App Router.

Layouts are foundational components that wrap pages: this is not only useful for displaying a common UI across pages, but also to reuse data-fetching and logic.

Next.js needs one root layout component:

export const metadata = {
  title: 'Next.js Tutorial',
  description: 'A Next.js tutorial using the App Router',
};

async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang={'en'}>
      <body>{children}</body>
    </html>
  );
}

export default RootLayout;

Layouts are defined using the convention layout.tsx in the app directory: Next.js will automatically wrap all pages within the folder where the layout is defined.

For example, if we have a layout defined in app/(site)/layout.tsx, Next.js will wrap all pages in the app/(site) directory with this layout:

export default async function SiteLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div>
      <main>
        {children}
      </main>
    </div>
  );
}

As a result - all the pages in the app/(site) directory will be wrapped with the SiteLayout component.

Loading data in Layout Components

Layout components can be extremely useful also in case you need to load some data needed in all pages of a directory: for example, we could load the user's profile in the layout component, and pass it to the page components.

To fetch data in Layout Components in Next.js, we can use the new use hook, an experimental hook in React that uses Suspense to fetch data on the server.

import { use } from "react";

export default function SiteLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const data = use(getData());

  return (
    <div>
      <header>
        { data.user ? <ProfileDropown /> : null }
      </header>

      <main>
        {children}
      </main>
    </div>
  );
}

function getData() {
  return fetch('/api/data').then(res => res.json());
}

In the example above:

we fetch the data in the layout component using the use hook
we conditionally render the ProfileDropdown component based on the data.user property

NB: we used the use hook to fetch the data in a (seemingly) synchronous way. This is because the use hook uses Suspense under the hood, which allows us to write asynchronous code in a synchronous way.

Using Async/Await in Server Components

An alternative way would be to make the component an async component, and use async/await to fetch the data from getData:

export default async function SiteLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const data = await getData()

  return (
    <div>
      <header>
        { data.user ? <ProfileDropown /> : null }
      </header>

      <main>
        {children}
      </main>
    </div>
  );
}

function getData() {
  return fetch('/api/data').then(res => res.json());
}

Reading Cookies and Headers

If you're using a Server Component, you can read cookies and headers using from the next/headers package.

NB: At the time of writing, we can only use these functions to read their values, but not to set or delete them.

import { cookies } from 'next/headers';

export function Layout(
  { children }: { children: React.ReactNode },
) {
  const lang = cookies.get('lang');

  return (
    <html lang={lang}>
      <body>
        {children}
      </body>
    </html>
  );
}

If you feel like something is missing, don't worry, it's not just you. In fact, unlike getServerSideProps, we do not have access to the request object. This is why Next.js is exposing these utilities to read data from the request.

Redirecting from Layouts

In layouts, we can also redirect users to a different page.

For example, if we want to redirect users to the login page if they are not authenticated, we can do it in the layout component:

import { use } from 'react';
import { redirect } from 'next/navigation';

function AuthLayout(
  props: React.PropsWithChildren,
) {
  const session = use(getSession());

  if (session) {
    return redirect('/dashboard');
  }

  return (
    <div className={'auth'}>
      {props.children}
    </div>
  );
}


function getSession() {
  return fetch('/api/session').then(res => res.json());
}

Now, we can use the loadSession function in the layout component:

import { use } from 'react';

function AuthLayout(
  props: React.PropsWithChildren,
) {
  const response = use(loadSession());
  const data = response.data;

  // do something with data

  return (
    <div className={'auth'}>
      {props.children}
    </div>
  );
}

Using the redirect side-effect in Next.js

The new Next.js function redirect will throw an error: in fact, its return type is never. If you catch the error, you need to be careful and ensure to follow the redirect thrown by the error.

To do that, we can use some utilities exported by the Next.js package:

import { use } from 'react';

import {
  isRedirectError,
  getURLFromRedirectError,
} from 'next/dist/client/components/redirect';

import { redirect } from "next/navigation";

async function loadData() {
  try {
    const data = await getData();

    if (!data) {
      return redirect('/login');
    }

    const user = data.user;

    console.log(`User ${user.name} logged in`);

    return user;
  } catch (e) {
    if (isRedirectError(e)) {
      return redirect(getURLFromRedirectError(e));
    }

    throw e;
  }
}

function Layout(
  props: React.PropsWithChildren,
) {
  const data = use(loadData());

  // do something with data

  return (
    <div>
      {props.children}
    </div>
  );
}

Pages

To define pages in the new app directory, we use the special convention page.tsx. That means, if we want to define a page in the app directory, we need to name the file page.tsx.

For example, if we want to define the home page of your website, we can place the page in the app/(site) directory and name it page.tsx:

function SitePage() {
  return <div>Site Page</div>;
}

export default SitePage;

Page Metadata and SEO

To specify the metadata of a page, we can export the constant metadata property in the page.tsx file:

export const metadata = {
  title: 'Site Page',
  description: 'This is the site page',
};

If you need to access dynamic data, you can use the generateMetadata function:

export async function generateMetadata(
  { params, searchParams }
) {
  return { title: '...' };
}

Check out the Next.js documentation for the full list of supported metadata properties.

Generating Static Pages

To generate a list of static pages to be used with dynamic parameters, we can use the generateStaticParams function:

export async function generateStaticParams() {
  const posts = await getPosts();

  return posts.map((post) => ({
    slug: post.slug,
  }));
}

Check out the full documentation for generating static paths.

Loading Indicators

When navigation between pages, we may want to display a loading indicator. To do this, we can use the loading.tsx file which we can define in every directory:

export default function Loading() {
  return <div>Loading...</div>;
}

Here you can add any component you want to display while the page is loading, such as a top bar loader, or a loading spinner, or both.

Error Handling

At the moment, you can define a "not found" page using the convention not-found.tsx:

export default function NotFound() {
  return (
    <>
      <h2>Not Found</h2>
      <p>Could not find requested resource</p>
    </>
  );
}

This file will only be displayed if used in conjunction with the notFound function. This is why it's still recommended to use custom 400 and 500 pages using the old pages directory.

Custom 404 and 500 pages

At the time of writing, we need to stick with the regular pages directory to define custom 404 and 500 pages. This is because Next.js does not support custom 404 and 500 pages in the app directory.

Fonts

We can use the package next/font to load fonts in our application.

To do so, we need to define a client component, and import it in the root layout app/layout.tsx file:

'use client';

import { Inter } from 'next/font/google';
import { useServerInsertedHTML } from 'next/navigation';

const heading = Inter({
  subsets: ['latin'],
  variable: '--font-family-heading',
  fallback: ['--font-family-sans'],
  weight: ['400', '500'],
  display: 'swap',
});

export default function Fonts() {
  useServerInsertedHTML(() => {
    return (
      <style
        dangerouslySetInnerHTML={{
          __html: `
          :root {
            --font-family-sans: '-apple-system', 'BlinkMacSystemFont',
              ${sans.style.fontFamily}, 'system-ui', 'Segoe UI', 'Roboto',
              'Ubuntu', 'sans-serif';

            --font-family-heading: ${heading.style.fontFamily};
          }
        `,
        }}
      />
    );
  });

  return null;
}

After that, we can import the Fonts component in the root layout:

import Fonts from '~/components/Fonts';

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <Fonts />

      <body>{children}</body>
    </html>
  );
}

API Routes

The new app directory also supports API routes. The convention to define an API route is to create a file named route.tsx in the app directory.

API routes now use the standard Request object rather than the express-like req and res objects.

When we define an API route, we can export the handler for the methods we want to support. For example, if we want to support the GET and POST methods, we can export the GET and POST functions:

import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ hello: 'world' });
}

export async function POST(
  request: Request
) {
  const body = await request.json();
  const data = await getData(body);

  return NextResponse.json(data);
}

If we want to manipulate the response, for example by setting cookies, we can use the NextResponse object:

export async function POST(
  request: Request
) {
  const organizationId = getOrganizationId();
  const response = NextResponse.json({ organizationId });

  response.cookies.set('organizationId', organizationId, {
    path: '/',
    httpOnly: true,
    sameSite: 'lax',
  });

  return response;
}

In API routes, just like in Server Components, we can also redirect users using the redirect function imported from next/navigation:

import { redirect } from 'next/navigation';

export async function GET(
  request: Request
) {
  return redirect('/login');
}

Handling Webhooks

Handling webhooks is a common use case for API routes, and getting the raw body request is now much simpler. In fact, we can get the raw body request by using the request.text() method:


export async function POST(
  request: Request
) {
  const rawBody = await request.text();

  // handle webhook here
}

Server Actions

Server Actions are a new concept introduced in Next.js 13. They are a way to define server-side actions that can be called from the client. All you need to do is to define a function and use the use server keyword at the top:

For example, the below is a valid server action:

async function myActionFunction() {
  'use server';

  // do something
}

If you are defining a server action from a client component, this needs to be exported from a separate file, and imported in the client component. The file needs the keyword use server at the top:

 'use server';

async function myActionFunction() {
  // do something
}

To call the server action from the client, you have multiple ways

Defining the action as the action property of a form component
Calling the action from a button component using the formAction property
Calling the action using the useTransition hook (if it mutates data)
Simply calling the action like a normal function (if it does not mutate data)

If you want to know more about Server Actions, I will soon post a whole article dedicated to them soon.

Conclusion

In this article, we learned how to use the new App Router in Next.js 13.

While Next.js App Router is now out of beta, some of the patterns and conventions we learned in this article are new and may be still not production-ready, and may change in the future.

However, they are already very useful, and we can already start using them in our projects.

Angular: Setters vs ngOnChanges - which one is better?

Giancarlo Buomprisco — Fri, 31 Jul 2020 19:23:15 +0000

This post was originally published on Angular Bites

Getting notified about an Angular component's property changes is normally done in 2 ways:

adding a setter to the property
using the ngOnChanges lifecycle hook

But... is there a best practice?

This discussion recently came up with my colleagues while trying to establish a standard practice in our codebase. We tried to find objective arguments to understand which one is better.

As usual, the answer depends on the scenario.

Style

Style is very much a subjective factor, but using a setter is hands-down my favorite approach. Let's take a look at a common scenario:

class MyComponent {
  private subject$ = new Subject<string>();

  @Input()
  set name(name: string) {
    this.subject$.next(name);
  }
}

It's succinct, type-safe, and encourages the usage of Observables. Not much to dislike, imho.

But can you not add a getter?

Yes. It turns out, Angular does not check the previous value by invoking the getter on the property, but stores its value in its component's logical view.

If you're interested in reading the source code where this happens, check this out.

class MyComponent implements OnChanges {
  @Input() name: string;

  private subject$ = new Subject<string>();

  ngOnChanges(changes: SimpleChanges) {
    // changes.name.currentValue is typed as `any`
    this.subject$.next(changes.name.currentValue);
  }
}

The ngOnChanges lifecycle hook, on the contrary, it's not as nice (in my opinion) - and most importantly, is weakly typed.

Also - it's worth to mention that using setters usually takes less code, which is always a good thing.

Performance

Does performance change much? At first, we thought that ngOnChanges would be more efficient as being part of Angular's lifecycle hooks, and therefore being aware of when a property changed.

It turns out, though, that Angular does only change a property when the binding is a new instance. Of course, we're taking into account the change detection being OnPush.

Performance-wise, according to my tests, there isn't a better way, and shouldn't be a factor when deciding which way to go with.

Dealing with multiple Inputs

The situation changes when taking into account changes on multiple inputs:

class MyComponent implements OnChanges {
  @Input() name: string;
  @Input() email: string;

  private username$ = new Subject<string>();

  ngOnChanges({ name, email }: SimpleChanges) {
    const username = name.currentValue || email.currentValue;
    this.username$.next(username);
  }
}

In this case, it's fairly straightforward and simpler to receive all the inputs at once.

But because this situation is pretty uncommon, and sometimes a sign of a code-smell, you'll find yourselves wanting to use the setter the majority of the time.

At the end of the day, remember that this decision is always up to you and your team's preferences.

Hope you enjoyed this post. Ciao!

Angular: Async Rendering with a single Rx Operator

Giancarlo Buomprisco — Sun, 12 Jul 2020 19:26:21 +0000

This post was originally published on Angular Bites

The concept of async rendering, in the way I mean it, is simple: the process of rendering items on screen is scattered so that the browser won't block until all items have been rendered.

So here's how it works: I render item one, then I wait a little bit, then render the next item, and so on. In between, the browser can execute all the other scheduled events in the loop before we let it render again.

When and Why you should use it, sometimes

When does this work (particularly) well?

In case we are rendering particularly long and heavy lists
In case each item of the list takes a lot of space on the page

Why? Your app will "look" faster. It's not going to be actually faster, but your users will perceive it as being so. Good enough.

A single-operator approach

In the past I've solved this in various ways, as I described in How to Render Large Lists in Angular.

This time I thought of a single operator that would sequentially scatter the rendering process of a subset of the array.

We'll call this operator lazyArray. It supports two arguments:

delayMs = how long the browser should wait before it renders the next array
concurrency = how many items to render at once

Just show me the code, Giancarlo!

Alright, here it is:

export function lazyArray<T>(
  delayMs = 0,
  concurrency = 2
) {
  let isFirstEmission = true;

  return (source$: Observable<T[]>) => {
    return source$.pipe(
      mergeMap((items) => {
        if (!isFirstEmission) {
          return of(items);
        }

        const items$ = from(items);

        return items$.pipe(
          bufferCount(concurrency),
          concatMap((value, index) => {
            const delayed = delay(index * delayMs);

            return scheduled(of(value), animationFrameScheduler).pipe(delayed);
          }),
          scan((acc: T[], steps: T[]) => {
            return [ ...acc, ...steps ];
          }, []),
          tap((scannedItems: T[]) => {
            const scanDidComplete = scannedItems.length === items.length;

            if (scanDidComplete) {
              isFirstEmission = false;
            }
          }),
        );
      }),
    );
  };
}

Usage

Using it is pretty simple, use it just like any other operator:

@Component({ ... })
export class MyComponent {
   items$ = this.service.items$.pipe(
     lazyArray()
   );
}

Let's break it down, shall we?

We want to keep track whether it's the first emission, or not. We only want to render lazily the first time:

let isFirstEmission = true;

We transform the array into a stream of items:

const items$ = from(items);

We collect the amount of items into an array based on the concurrency:

bufferCount(concurrency),

We scheduled the rendering based on the delay, and then progressively increase the delay based on the item's index:

concatMap((value, index) => {
  const delayed = delay(index * delayMs);

  return scheduled(of(value), animationFrameScheduler).pipe(delayed);
})

We keep collecting the processed items into a single array:

scan((acc: T[], steps: T[]) => {
  return [ ...acc, ...steps ];
}, [])

Finally, we check if the amount of processed items is as long as the initial list. In this way, we can understand if the first emission is complete, and in case we set the flag to false:

tap((scannedItems: T[]) => {
  const scanDidComplete = scannedItems.length === items.length;

  if (scanDidComplete) {
    isFirstEmission = false;
  }
})

Demo

I came up with this because my application, Formtoro, loads quite a bit of data at startup that renders lots of Stencil components at once.

It did not work well, it was laggy. I didn't like it, so I found a way to solve it. I'll show you the differences:

Without lazyArray operator:

With lazyArray operator:

This approach works very well in my case - and may not in yours. Shoot me an email if you want help implementing it.

Ciao!

If you enjoyed this article, follow me on Twitter or check out my new blog Angular Bites

An Opinionated Coding Styleguide for Angular

Giancarlo Buomprisco — Tue, 10 Mar 2020 11:04:31 +0000

An internal style guide for writing code is an important decision that any development team should define and agree on at some point, ideally early on in the project.

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

If you’ve been writing code professionally, you know very well how important style is for many, many developers. Countless hours in my career have been spent arguing about style.

Why is it so important, though? Programmers read code way more than they write: it’s crucial that we simplify this task as much as possible for us but especially for our fellow teammates.

The consensus is to define a style guide before writing the first line of code, but this should not be fixed for the entire project lifecycle: it is a continuous set of learnings deriving from experimentation and experience.

It also doesn’t mean you should change your mind every day: it means you should evaluate, discuss and decide with your team as your project grows.

After writing Angular apps since the alpha days, I’ve developed my style, strongly influenced by people I’ve worked with, reading lots of people’s code, and simply experimenting with my projects.

In this article, I want to show how I style my Angular apps and the rationale behind my decisions. Hopefully, it will inspire you and your team to adopt some of it or to make your own.

Any suggestions would be extremely welcome on how to improve it!

Notice: this style guide is purely stylistic not based on technical details and best practices. This style guide is intended to simply help with code aesthetics and readability, not performance, design patterns or else.

Complementing the right styleguide with the right tools.

In addition to adhering to a certain style guide, it’s important to use tools that make your code simple to understand, maintain and reuse (by others in your organization or even the open-source community). One tool that I love to use it Bit.dev.

HTML Wrapping and Order

Angular templates have quite a few syntax additions on top of normal HTML, and sometimes they’re not very easy to read.

My first suggestion regards the wrapping. I normally do not exceed 80 characters per column for all files: it’s simply much easier to read vertically than horizontally.

This is an element written without any convention:

Messy, isn’t it? Almost every project I’ve worked on while consulting was written in a similar fashion.

We’re going to rewrite the snippet above using a set of simple rules to make it way more readable.

Defining Rules For Writing HTML Tags

When an element has two or more attributes, I normally only write one attribute per line
Attributes have to be written in a specific order
Unless using a single attribute, the closing tag has to be written on the next line

I suggest defining a specific order:

Structural directives
Animations
Static properties
Dynamic properties
Events

Let’s see an example of how I would personally write the previous example:

Even better, I’d always use structural directives exclusively with ng-container:

While I think you can mix up the order of the attributes based on a subjective view, I feel quite strong about displaying structural directives before anything else.

A structural directive tells me (before I need to know anything else it does):

Is this field being shown? And why?
Is this field being repeated?

In my opinion, this can facilitate reading through and understanding the structure of your templates.

Pipes

Pipes are very powerful: they can transform the values in templates and avoid duplication/logic in our components. They can be reused and mixed easily, and are easy to write.

But are they easy to read and to spot? Yes and No.

This is highly subjective and a minor point but I still think it can be valuable to share: whenever I see a pipe in my template, I tend to wrap them within parenthesis. The feeling of division provided by the parenthesis gives me a clue that the value is being transformed and generally is easier on the eye:

When using multiple pipes, it may even be more important:

Lifecycle Hooks

Interfaces

Adding lifecycle hooks interfaces is not mandatory but a suggested practice, which I strongly recommend to follow.

Order

When I look for lifecycle hooks, I usually head to the constructor and expect them to see all of them together and not mixed up with other class methods. Ideally, they should be defined in the same order they execute.

What I recommend is:

always add interfaces
add public and private properties above the constructor
add methods right below the constructor and above the component’s methods
add them all close to each other
add them in the order they execute. Admittedly though, this is a bit harder to follow consistently, so I guess it’s the least important one

Logic

I normally avoid directly writing any logic within the lifecycle hooks: my suggestion is to encapsulate logic within private methods and call them within the lifecycle hooks:

Component Properties and Methods

Angular uses decorators for the component’s methods and properties in order to augment its functionality.

There are so many of them that defining a specific order to follow would be overwhelming, but the important thing I try to follow is to locate the properties and methods with the same decorator close to each other.

The following is what I would consider a bad example:

And below is how I would write it; also, notice there’s an empty line in between groups of properties with the same decorator — I think it helps with readability:

I don’t have a strong opinion on this, but try to locate private and public component properties not marked with any decorator separately from the decorated properties.

In my experience, mixing them up only leads to confusion and a feeling of chaos.

Naming

Oh, naming things is hard, I know.

When it comes to naming, I always have to think it twice or more to come up with a name that is understandable, unambiguous and easy-to-search:

understandable: what does this do, at a glance?
unambiguous: for example, if we have multiple click events on a single component, which one does this event refer to? So yeah, naming it onClick is not the way to go
easy-to-search: I see naming code a bit like SEO: how will my users (teammates or me) search for this particular thing — and how can I write it to make sure they can search for it more easily?

File Names

I like to use hyphen-case for all file names. I would think by now it’s a standard for Typescript projects, but I’ve seen quite a few variations, even in Angular projects, so I feel I have to mention this.

Examples:

sign-up.component.ts
profile-form.component.html

Route Components

I tend to name route components with a suffix page.

For example, the authentication page would normally be called auth-page.component.ts — which tells me it’s a routed component, and I normally use it to wrap and display other components via router-outlet.

Components

Some rules I tend to follow when naming components are:

Try to use no more than 3 words (excluding the prefix). No specific reason why — they just don’t look very pretty. Of course, sometimes it’s simply not very easy to respect this rule
Try to avoid repeating words or contexts already used with other components, as it would slow down while using the search function of my IDE, and also lead to mistakenly open other files, which is ultimately a waste of time and source of frustration
At the same time, also try not to be too generic. For example: if we call a component settings — settings of what!? Help out a little here and give some further context (example: application-settings, profile-settings, organization-settings, etc.).
No biggie for small applications, but at scale, it does make a difference

Events Names

It seems simple and yet it’s not, especially with larger components with many events.

Here are a set of rules I try to follow:

Do not prefix events/outputs names with on. The handler, instead, could be written with such prefix
Don’t make me think: always specify the entity whose action referred, not only the action itself.
If we are describing an event on a component whose value changed, the event change could be valueChange.
In my opinion, this is unambiguous and tells me what changed without having me question if this was the value, the status, or anything else
Use past-sense or not (valueChange vs valueChanged)? This is controversial and I heard valid reasons on opposite sides, so it may be up for discussion for your and your team.
As long as you agree on one single-way, I don’t think it’s that important. What do you think?

ES Imports

Keeping your file imports ordered and neat is challenging, especially when using an IDE to auto-add them as you type. As your files grow, they tend to get quite messy.

This how I order my imports:

Angular imports always go at the top
Rx imports
Third parties (non-core)
Local/Project imports at the end

It’s also a good practice to leave a comment above each group:

Takeaways ⭐

Wrap HTML elements neatly: place 1 single attribute per line, and sort attributes ordered by type
Use parenthesis around values that use pipes
Place lifecycle hooks next to each other and order them by order of execution
When naming things, ask yourself: is this understandable, unambiguous and easy-to-search?
Keep ES imports neat and ordered

Opinionated Angular

I added a Github Repository called Opinionated Angular where I'll be dumping more of my thoughts for writing readable and beautiful Angular code.

Please come and contribute if you wish!

I would love to receive some tips and learn about your conventions and rules you and your team follow. Alternatively, if you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on Medium, Twitter or Dev for more articles about Software Development, Front End, RxJS, Typescript and more!

3 Ways to Render Large Lists in Angular

Giancarlo Buomprisco — Fri, 06 Mar 2020 07:18:20 +0000

An overview of the available techniques to render large lists of items with Angular

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

Frameworks in 2020 got better, more efficient and faster. With that said, rendering large lists of items on the Web without causing the Browser to freeze can still be hard even for the fastest frameworks available.

This is one of the many cases where “the framework is fast, your code is slow”.

There are many different techniques that make rendering a large number of items in a non-blocking way for the users. In this article, I want to explore the current techniques available, and which ones are best to use based on particular use-cases.

Although this article focuses on how to optimize rendering with Angular, these techniques are actually applicable to other frameworks or simply Vanilla Javascript.

The framework is fast, your code is slow

This article goes in detail about an aspect I talked about in one of my previous articles: rendering too much data.
Top Reasons Why Your Angular App Is Slow

We will take a look at the following techniques:

Virtual Scrolling (using the Angular CDK)
Manual Rendering
Progressive Rendering

Whatever implementation you choose for rendering long lists, make sure you share your reusable Angular components to Bit.dev’s component hub. It will save you time otherwise spent on repeating yourself and will make it easier for you and your team to use tested and performance-optimized code across your Angular projects.

1. Virtual Scrolling

Virtual Scrolling is probably the most efficient way of handling large lists, with a catch. Thanks to the Angular CDK and other plugins it is very easy to implement in any component.

The concept is simple, but the implementation is not always the easiest:

given a container and a list of items, an item is only rendered if it’s within the visible boundaries of the container

To use the CDK’s Scrolling module, we first need to install the module:

npm i @angular/cdk

Then, we import the module:

    import { ScrollingModule } from '@angular/cdk/scrolling';

    @NgModule({
     ...
     imports: [ ScrollingModule, ...]
    })
    export class AppModule {}

We can now use the components to use virtual scrolling in our components:

    <cdk-virtual-scroll-viewport itemSize="50">       
     <div *cdkVirtualFor="let item of items">
       {{ item }}
     </div>
    </cdk-virtual-scroll-viewport>

As you can see, this is extremely easy to use and the results are impressive. The component renders thousands and thousands of items without any problem.

If Virtual Scrolling is so good and easy to achieve, why bother exploring other techniques? This is something I’ve been wondering too — and actually there’s more than one reason as to why.

The way it’s going to work is very dependent on implementation: it’s hard to be able to manage all the possible scenarios with one single implementation.
For example, my component depended on the Autocomplete field (built by the same team) and unfortunately, it didn’t work as expected. The more complex your items, the more difficult it’s going to be.
Another module, another big chunk of code added to your app.
Accessibility and Usability: the hidden items are not rendered, and therefore won’t be searchable.

Virtual Scrolling is ideal (when it works) in a number of situations:

an undefined and possibly enormous list of items (approximately greater than 5k, but it’s highly dependent on the complexity of each item)
infinite scrolling of items

2. Manual Rendering

One of the options I’ve tried to speed up a large list of items is manual rendering using Angular’s API rather than relying on *ngFor.

We have a simple ngFor loop template:

    <tr 
        *ngFor="let item of data; trackBy: trackById; let isEven = even; let isOdd = odd"
        class="h-12"
        [class.bg-gray-400]="isEven"
        [class.bg-gray-500]="isOdd"
    >
      <td>
        <span class="py-2 px-4">{{ item.id }}</span>
      </td>

      <td>
        <span>{{ item.label }}</span>
      </td>

      <td>
        <a>
          <button class="py-2 px-4 rounded (click)="remove(item)">x</button>
        </a>
      </td>
    </tr>

I’m using a benchmark inspired by js-frameworks-benchmark to calculate the rendering of 10000 simple items.

The first benchmark run was done with a simple, regular *ngFor. Here are the results: scripting took 1099ms and rendering took 1553ms, 3ms painting.

By using Angular’s API, we can manually render the items.

    <tbody>
      <ng-container #itemsContainer></ng-container>
    </tbody>

    <ng-template #item let-item="item" let-isEven="isEven">
      <tr class="h-12"
          [class.bg-gray-400]="isEven"
          [class.bg-gray-500]="!isEven"
      >
        <td>
          <span class="py-2 px-4">{{ item.id }}</span>
        </td>

        <td>
          <span>{{ item.label }}</span>
        </td>

        <td>
          <a>
            <button class="py-2 px-4 rounded" (click)="remove(item)">x</button>
          </a>
        </td>
      </tr>
    </ng-template>

The controller’s code changes in the following way:

we declare our template and our container

    @ViewChild('itemsContainer', { read: ViewContainerRef }) container: ViewContainerRef;
    @ViewChild('item', { read: TemplateRef }) template: TemplateRef<*any*>;

when we build the data, we also render it using the ViewContainerRef createEmbeddedView method

    private buildData(length: number) {
      const start = this.data.length;
      const end = start + length;

      for (let n = start; n <= end; n++) {
        this.container.createEmbeddedView(this.template, {
          item: {
            id: n,
            label: Math.random()
          },
          isEven: n % 2 === 0
        });
      }
    }

Results show a modest improvement:

734ms time spent scripting, 1443 rendering, and 2ms painting

In practical terms, though, it’s still super slow! The browser freezes for a few seconds when the button is clicked, delivering a poor user experience to the user.

This is how it looks like (I’m moving the mouse to simulate a loading indicator 😅):

Let’s now try Progressive Rendering combined with Manual Rendering.

3. Progressive Rendering

The concept of progressive rendering is simply to render a subset of items progressively and postpone the rendering of other items in the event loop. This allows the browser to smoothly and progressively render all the items.

The code below is simply:

we create an interval running every 10ms and render 500 items at once
when all items have been rendered, based on the index, we stop the interval and break the loop

    private buildData(length: number) {
      const ITEMS_RENDERED_AT_ONCE = 500;
      const INTERVAL_IN_MS = 10;

      let currentIndex = 0;

      const interval = setInterval(() => {
        const nextIndex = currentIndex + ITEMS_RENDERED_AT_ONCE;

        for (let n = currentIndex; n <= nextIndex ; n++) {
          if (n >= length) {
            clearInterval(interval);
            break;
          }

          const context = {
            item: {
              id: n,
              label: Math.random()
            },
            isEven: n % 2 === 0
          };

          this.container.createEmbeddedView(this.template, context);
        }

        currentIndex += ITEMS_RENDERED_AT_ONCE;
      }, INTERVAL_IN_MS);

Notice that the number of items rendered and the interval time is totally dependent on your circumstances. For example, if your items are very complex, rendering 500 items at once is certainly going to be very slow.

As you can see below, the stats look certainly worse:

What’s not worse though is the user experience. Even though the time it takes to render the list is longer than before, the user can’t tell. We’re rendering 500 items at once, and the rendering happens outside of the container boundaries.

Some issues may arise with the container changing its size or scroll position while that happens, so these issues need to be mitigated in a few cases.

Let’s see how it looks like:

Final Words

The above techniques are certainly useful in some situations and I’ve used them whenever virtual scrolling was not the best option.

With that said, for the most part, virtual scrolling using a great library like Angular’s CDK is definitely the best way to tackle large lists.

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on Medium, Twitter or Dev for more articles about Software Development, Front End, RxJS, Typescript and more!

Top Reasons Why Your Angular App Is Slow

Giancarlo Buomprisco — Tue, 28 Jan 2020 16:38:01 +0000

Is your app slow? Learn what to watch out when debugging poor performance in your Angular apps!

Introduction

Angular is, by default, a fast and performant framework. While it leaves ample space for improvement by opting out some of its magic, we almost never have to do anything special to write extremely performant code for the average app.

With that said, some difficulties will eventually arise when we are writing either performance-critical apps, apps with large and complex content, or apps updated extremely frequently.

There are loads of resources and popular advice out there about improving performance with Angular apps. While most of it is totally good and valid advice, what I have personally found while mitigating performance issues is not often talked about.

In this article, I want to show some of the most important reasons why Angular apps become slow at scale. What we will see is that it doesn’t really matter the framework used — these tips will be valid for any framework.

Tip: as we all know, rewriting code is a recipe for bad code. Use tools like Bit (Github) to “harvest” reusable components from your codebase and share them on bit.dev. This way you and your team can easily find them, import them to any project and develop them further if needed. It’s a good way to guarantee high quality, scalable and maintainable code.

Micro Optimizations: Do they Matter?

In my experience, this is a very misunderstood topic among developers. Whenever I’ve had to deal with performance issues, many colleagues were pointing out at code that could have been causing these issues, which very often happened to be micro-optimizations that would only save a few milliseconds.

Some examples:

“We’re using too much reduce, map and filter, let’s replace them all with for loops!”
“Let’s use a dictionary for accessing data faster!”
“Bitwise Operators!”

I always thought there was something else going on.

The ones above are all very valid points if you are coding performance-critical applications, frameworks or libraries. The first thing people look at when trying to find the reason why they’re experiencing poor performance is to debug every function call:

“How much did it take to find an item in this list [of maybe 300 items]?
“How long did it take to sort [800 items]”?

But when you’re developing an application, these optimizations may count much less than you think.

This is not to say it can’t happen, but I would start questioning two other possible issues first:

How much is the app actually rendering?
How often is the framework re-rendering components?

As we will see, even when following best practices, sometimes they’re not enough to prevent slow performance. And most often it’s not due to the framework we’re using but to our code or architecture.

Your app is rendering too often

Let’s start with this quite common issue: your application re-renders components unnecessarily, making your application slower than it could be. This is both easy to solve and easy to cause.

Change Detection

Setting the default change detection to OnPush is an almost mandatory step if your application is suffering from slow performance, or if you want to prevent from it happening in the future.

By setting your components to update only “on push”, you prevent re-rendering components that don’t need to be checked. It’s straightforward and its usage is greatly simplified when using Observables and the Async pipe.

Async Pipe

Even if you’re using OnPush and the async pipe in your templates, you may still be re-rendering more than it is actually needed.

For example, in my experience, preventing observables from emitting is a good way to prevent your component from re-rendering. For example, you may use operators such as filter and distinctUntilChanged to skip re-renderings altogether.

Another issue that I’ve experienced even when using Observables and Async pipe was due to selecting items from a store without selectors. If we write and use granular selectors, we only receive updates from the state slice affected.

If we select the whole object from a Redux state tree, the selectors will emit every time the tree-changed, and as a result, we will end up triggering updates on components that are virtually unaffected.

This is a seemingly subtle improvement that ended up making one of my applications from barely usable to decently performant on IE11.

For more information about improving efficiently with RxJS, check out my article below:
RxJS Patterns: Efficiency and Performance

High-Frequency Updates

This is a use-case where Angular doesn’t excel at, and it is probably due to Zone.js, which is also the reason behind Angular’s magical change detection.

Zone.js will monkey-patch all events and will schedule a change detection when any of these happened. That means that if your application is streaming events at a fast rate (Websocket, or even DOM events), for each event received, Zone will trigger a change detection. There’s definitely room for improvements in similar cases.

I have talked in depth about this at the link below:
Quantum Angular: Maximizing Performance by Removing Zone

Of course, you don’t need to remove Zone from your app to solve this issue. Here are a few steps you can take instead:

detach the affected components, then update surgically when your subscriptions get notified
use ngZone.runOutsideAngular(callback) to run the callback outside of Angular’s change detection
last resort: exclude the event from being monkey-patched by Zone

Your app is rendering too much

No matter how fast your framework is, if you are rendering thousands of complex components in one go, the browser is eventually going to show some amount of lag.

Even if maybe on your Macbook Pro it isn’t very noticeable, slower machines will definitely struggle, and you should think that not everyone is using a powerful machine.

It’s extremely important to make sure that components rendered many items (eg. within lists) are optimized in a particular way.

How can you solve this?

Keying

This is the simplest and probably most well-known technique which is baked in most libraries. The concept is simple: we assign a key to each item of a list, and the library will re-render it only if the key has changed.

This works great when adding/removing items or when the amount of items changes is limited but still doesn’t solve a performance issue if we render a vast amount of items at once. For example — if we render a very large list at page load.

Virtual Scrolling

Only render what the user can see.

While this has accessibility/usability implications to be aware of, it is one of the best methods to improve perceived performance and avoid getting the page frozen for an unreasonable amount of time, which is less than you’d think.

It’s pretty easy to implement: the Angular CDK provides a utility for this!

Async/Progressive Rendering

This is an older technique, to which I’d prefer virtual scrolling, but that can still be better than rendering 1000 items at once and it is very easy to implement without having to write much code.

The concept is this: start rendering a limited number of items (ex, 50 out of 500), then schedule a subsequent rendering with the next 50 items using setTimeout(0) until all items are rendered**. **This is a simple technique, so the results are also simple — but the browser won’t get stuck for 250ms while rendering.

Lazy Rendering

Not everything has to be rendered right away, sometimes we can simply render a component when the user needs to interact with it.

Here’s a similar use-case I worked on: I was working on a page that used many instances of Quill, a famous WYSIWYG library.

This is a great tool, but it’s pretty heavy. Instantiating one of its components took 20–30ms, and I had to render hundreds of them on a page. My Macbook pro crashed.

Instantiating it right away was pretty silly: WYSIWYG can be simple HTML when not interacted with. I could simply instantiate the component when the user needed to, e.g. when hovered or clicked on. All performance issues were gone!

Lazy Listeners

This is directly related to the previous points: subscribing and listening to too many events may be quite expensive.

Avoiding subscribing to too many events can be done in different ways:

If you have a large list of items with DOM handlers, make sure you only subscribe to the items that are visible (virtual scrolling help with this)
Sometimes you may want to only create one single global event from within a Service, rather than subscribing to the event in each Directive/Component

Some code… is just slow

If you’ve done your research and figured out that your app doesn’t render that much and doesn’t render that often, then your code may just simply be quite slow. This is probably due to some heavy scripting and not DOM-related.

Cheer up! It’s a good thing, as nowadays we have the tools to resolve this sort of issue.

Use WebWorkers. The Angular CLI also provides a command to generate a WebWorker in a snap. When is this a suitable route? Simple — when your code has nothing to do with rendering and takes a while to execute. This is normally crunching numbers, data-processing, etc. That’s great for Redux, right? Wait, don’t do that yet.
Use WebAssembly, for example using AssemblyScript. Read this case study from Figma for more information.

If the above are not routes you’re comfortable with, or simply don’t solve your use case, then it’s time to try micro-optimizations and see by how much they can improve your runtime performance:

Use a Custom Iterable Differ
Turn everything into for-loops, scrap filter, reduce and map. Use break and continue to reduce the number of iterations
Maintain the shape of your objects. Learn more about how Angular is so fast watching this video from Misko Hevery

Takeaways

Opt-out of the framework’s magic: make sure you use ChangeDetection.OnPush and TrackBy for arrays
Render less often by surgically triggering change detections on your components. Run outside Zone when needed.
Try to render less using a variety of techniques such as virtual scrolling and lazy rendering
Don’t listen to everything: subscribe to only the items that are visible, and subscribe to only one global event listener

Resources

One of the most enlightening talks about Angular-related performance issues: Performance optimizations in Angular | Mert Değirmenci

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on Medium, Twitter or my website for more articles about Software Development, Front End, RxJS, Typescript and more!*

Quantum Angular: Maximizing Performance by Removing Zone

Giancarlo Buomprisco — Tue, 19 Nov 2019 13:29:34 +0000

Experiment: removing Zone from Angular with minimal effort, to boost runtime performance.

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

As Angular developers, we owe Zone a great deal: it’s also thanks to this library that we can use Angular almost magically; in fact, most times we simply need to change a property and it just works, Angular re-renders our components, and the view is always up to date. Pretty cool.

In this article, I want to explore some ways in which the new Angular Ivy compiler (being released in version 9) will be able to make apps work without Zone much simpler than it was in the past.

As a result, I was able to increase the performance of an application under heavy load by a huge amount by adding as little overhead as possible using Typescript’s decorators.

Notice: the approaches explained in this article are only possible thanks to Angular Ivy and AOT enabled by default. This article is educational only and doesn’t aim to advertise the code described.

Tip: Use Bit (Github) to easily and gradually build Angular component libraries. Collaborate on reusable components across projects to speed up development, maintain a consistent UI and write more scalable code.

The case for using Angular without Zone

Wait a moment, though: is it worth disabling Zone as it allows us to effortlessly re-render our templates? Yes, it is incredibly useful, but as always, magic comes at a cost.

If your application needs a special performance target, disabling Zone can help deliver better performance for your application: an example of a case-scenario where performance can actually be game-changing is high-frequency updates, which is an issue I had while working on a real-time trading application, where a WebSocket was continuously sending messages to the client.

Removing Zone from Angular

Running Angular without Zone is pretty simple. The first step is to comment out or remove the import statement in the file polyfills.ts:

The second step is to Bootstrap the root module with the following options:

    platformBrowserDynamic()
      .bootstrapModule(AppModule, {
        ngZone: 'noop'
      })
      .catch(err => console.error(err));

Angular Ivy: Manually Detecting Changes with ɵdetectChanges and ɵmarkDirty

Before we can start building our Typescript decorator, we need to see how Ivy allows us to bypass Zone and DI and trigger a change detection on a component by marking it dirty.

We can now use two more functions exported from @angular/core: ɵdetectChanges and ɵmarkDirty. These two functions are still to be used privately and are not stable, hence they are prefixed with the character ɵ.

Let’s see an example of how they can be used.

ɵmarkDirty

This function will mark a component dirty (e.g. need re-rendering) and will schedule a change detection at some point in the future unless it is already marked dirty.

    import { ɵmarkDirty as markDirty } from '@angular/core';

    @Component({...})
    class MyComponent {
      setTitle(title: string) {
        this.title = title;
        markDirty(this);
      }
    }

ɵdetectChanges

For efficiency reasons, the internal documentation discourages the use of ɵdetectChanges and recommends using ɵmarkDirty instead. This function will synchronously trigger a change detection on the components and subcomponents.

    import { ɵdetectChanges as detectChanges } from '@angular/core';

    @Component({...})
    class MyComponent {
      setTitle(title: string) {
        this.title = title;
        detectChanges(this);
      }
    }

Automatically detecting changes with a Typescript Decorator

While the functions provided by Angular increase the Developer Experience by allowing us to bypass the DI, we may still be unhappy about the fact we need to import and manually call these functions in order to trigger a change detection.

In order to make automatic change detection easier, we can write a Typescript decorator that can do it for us. Of course, we have some limitations, as we will see, but in my case, it did the job.

Introducing the @observed decorator

In order to detect changes with minimal effort, we will build a decorator that can be applied in three ways:

to synchronous methods
to an Observable
to an Object

Let’s see two quick examples. In the image below, we apply the @observed decorator to the state object and to the changeName method.

to check changes on the state object we use a Proxy underneath to intercept changes to the object and trigger a change detection
we override the changeTitle method it with a function that first calls the method, and then it triggers a change detection

Below, we have an example with a BehaviorSubject:

For Observables, it gets a little bit more complicated: we need to subscribe to the observable and mark the component dirty in the subscription, but we also need to clean it up. To do that, we override ngOnInit and ngOnDestroy to subscribe and then clean the subscriptions.

Let’s build it!

Below is the signature of the observed decorator:

    export function observed() {
      return function(
        target: object,
        propertyKey: string,
        descriptor?: PropertyDescriptor
      ) {}
    }

As you can see above, descriptor is optional as we want the decorator to be applied to both methods and properties. If the parameter is defined, then it means the decorator is being applied to a method:

we store the original method’s value
we override the method: we call the original function, and then we call markDirty(this) in order to trigger a change detection

    if (descriptor) {
      const original = descriptor.value; // store original
      descriptor.value = function(...args: any[]) {
        original.apply(this, args); // call original
        markDirty(this);
      };
    } else {
      // check property
    }

Moving on, we now need to check what type of property we’re dealing with: an Observable or an object. We now introduce another private API provided by Angular, which I am surely not supposed to be using (sorry!):

the property ɵcmp gives us access to the post-definition properties processed by Angular, which we can use to override the methods onInit and onDestroy of the component

    const getCmp = type => (type).ɵcmp;
    const cmp = getCmp(target.constructor);
    const onInit = cmp.onInit || noop;
    const onDestroy = cmp.onDestroy || noop;

In order to mark the property as “to be observed”, we use ReflectMetadata and set its value to true so that we know we need to observe the property when the component is initialized:

    Reflect.set(target, propertyKey, true);

It’s time to override the onInit hook and check the properties when it is instantiated:

    cmp.onInit = function() {
      checkComponentProperties(this);
      onInit.call(this);
    };

Let’s define the function checkComponentProperties which will go through the component’s properties, filter them by checking the value we set previously with Reflect.set:

    const checkComponentProperties = (ctx) => {
      const props = Object.getOwnPropertyNames(ctx);

      props.map((prop) => {
        return Reflect.get(target, prop);
      }).filter(Boolean).forEach(() => {
        checkProperty.call(ctx, propertyKey);
      });
    };

The function checkProperty will be responsible for decorating the individual properties. First, we want to check if the property is an Observable or an object. If it is an Observable, then we subscribe to it, and we add the subscription to a list of subscriptions that we store privately on the component.

    const checkProperty = function(name: string) {
      const ctx = this;

      if (ctx[name] instanceof Observable) {
        const subscriptions = getSubscriptions(ctx);
        subscriptions.add(ctx[name].subscribe(() => {
          markDirty(ctx);
        }));
      } else {
        // check object
      }
    };

If instead, the property is an object, we convert it to a Proxy, and we call markDirty in its handler function.

    const handler = {
      set(obj, prop, value) {
        obj[prop] = value;
        ɵmarkDirty(ctx);
        return true;
      }
    };

    ctx[name] = new Proxy(ctx, handler);

Finally, we want to clean up the subscriptions when the component is destroyed:

    cmp.onDestroy = function() {
      const ctx = this;
      if (ctx[subscriptionsSymbol]) {
        ctx[subscriptionsSymbol].unsubscribe();
      }
      onDestroy.call(ctx);
    };

This decorator is not exhaustive and will not cover all cases needed by large applications (ex. template function calls that return Observables, but I’m working on that…).

Though, it was enough to convert my small application. The full source code can be found at the end of this article.

Performance Results and Considerations

Now that we learned a little bit about the internals of Ivy and how to build a decorator that makes use of its API, it’s time to test it on a real application.

I used my guinea-pig project Cryptofolio in order to test the performance changes brought by adding and removing Zone.

I applied the decorator to all the template references needed, and I removed Zone. For example, see the below component:

the two variables used in the template are the price (number) and trend (up, stale, down), and I decorated both of them with @observed

    @Component({...})
    export class AssetPricerComponent {
      @observed() price$: Observable<string>;
      @observed() trend$: Observable<Trend>;

      // ...
    }

Bundle Size

First of all, let’s check by how much the size of the bundle will be reduced by removing Zone.js. In the image below, we can see the build result with Zone:

Build With Zone

Anf the below was taken without Zone:

Build Without Zone

Taking into account the ES2015 bundle, it’s clear that Zone takes almost 35kB of space, while the bundle without Zone is only 130 bytes.

Initial Load

I took some audits with Lighthouse, with no throttling: I wouldn’t take the below results too seriously: in fact, the results varied quite a bit while I was trying to average the results.

It’s possible though that the difference in bundle size is why the version without Zone has a slightly better score. The audit below was taken with Zone:

Audit with Zone

The below, instead, was taken without Zone:

Audit without Zone

Runtime Performance 🚀

And now we get to the fun part: runtime performance under load. We want to check how the CPU behaves when rendering hundreds of prices updated multiple times per second.

In order to put the application under load, I created about 100 pricers emitting mock data, with each price changing every 250ms. Every price will show up green if it increased, or red if it decreased. This can put my MacBook Pro under a fair amount of load.

Working in the financial sector on a number of high-frequency streaming applications, this is a scenario I came across multiple times.

I used the Chrome Dev Tools to analyzed the CPU usage of each version. Let’s start with Angular with Zone:

The below is taken without Zone:

Runtime Performance WIthout Zone

Let’s analyze the above, and take a look ar the CPU usage graph (the yellow one):

As you can see, in the zone version the CPU usage is constantly between 70% and 100%! Keep a tab under this load for enough time, and it will surely crash
In the second one, instead, the usage is stable at between 30% and 40%. Sweet!

Notice: The results above are taken with the DevTools open, which decreases performance

Increasing the load

I went on and tried to update 4 more prices every second for each pricer:

The non-Zone version was still able to manage the load without a problem with 50% CPU usage
I was able to bring the CPU close to the same load as the Zone version only by updating a price every 10ms (x 100 pricers)

Benchmarking with Angular Benchpress

The above is not the most scientific benchmark there is nor it aims to be, so I’d suggest you to check out this benchmark and uncheck all the frameworks but Angular and Zoneless Angular.

I took some inspiration from it, and I created a project that executes some heavy operations which I benchmarked it with Angular Benchpress.

Let’s see the component tested:

    @Component({...})
    export class AppComponent {
      public data = [];

      @observed()
      run(length: number) {
        this.clear();
        this.buildData(length);
      }

      @observed()
      append(length: number) {
        this.buildData(length);
      }

      @observed()
      removeAll() {
        this.clear();
      }

      @observed()
      remove(item) {
        for (let i = 0, l = this.data.length; i < l; i++) {
          if (this.data[i].id === item.id) {
            this.data.splice(i, 1);
            break;
          }
        }
      }

      trackById(item) {
        return item.id;
      }

      private clear() {
        this.data = [];
      }

      private buildData(length: number) {
        const start = this.data.length;
        const end = start + length;

        for (let n = start; n <= end; n++) {
          this.data.push({
            id: n,
            label: Math.random()
          });
        }
      }
    }

I then run a small benchmarking suite with Protractor and Benchpress: it executes the operations for a specified number of times.

Benchpress in Action

Results

Here’s a sample of the output returned by this tool:

Benchpress Output

And here’s an explanation of the metrics returned by the output:

    - gcAmount: gc amount in kbytes
    - gcTime: gc time in ms
    - majorGcTime: time of major gcs in ms
    - pureScriptTime: script execution time in ms, without gc nor render
    - renderTime: render time in ms
    - scriptTime: script execution time in ms, including gc and render

Notice: The graphs below will only show the rendering time. The complete outputs can be found at the following link.

Test: Create 1000 Rows

The first test creates 1000 rows:

Test: Create 10000 Rows

As the load gets heavier, we can see a bigger difference:

Test: Append 1000 Rows

This test appends 1000 rows to a list of 10000:

Test: Remove 10000 Rows

This test creates 10000 rows and removes them:

Final Words

While I do hope you enjoyed the article, I also hope I didn’t just convince you to run to the office and remove Zone from your project: this strategy should be the very last thing you may want to do if you plan on increasing the performance of an Angular application.

Techniques such as OnPush change detection, trackBy, detaching components, running outside of Zone, and blacklisting Zone events (among many others) should always be preferred. The tradeoffs are significant and it's a tax you may not want pay.

In fact, developing without Zone may still be quite daunting, unless you have complete control over the project (e.g. you own the dependencies and have the freedom and time to manage the overhead).

If all else fails, and you think Zone may actually be a bottleneck, then it may be a good idea to try and give Angular a further boost by manually detecting changes.

I hope this article gave you a good idea of what may be coming to Angular, what Ivy makes possible to do, and how you can work around Zone to achieve maximum speed for your applications.

Source Code

The source code for the Typescript decorator can be found at its Github Project page:

Resources

Frontend Frameworks Benchmark
Zoneless Benchmark Project (zone branch contains the code with Zone)
RFC: Component: Proposal for a new package component
Building with Ivy: rethinking reactive Angular

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on Medium, Twitter or my website for more articles about Software Development, Front End, RxJS, Typescript and more!

Composing Angular Components with Typescript Mixins

Giancarlo Buomprisco — Thu, 14 Nov 2019 13:00:25 +0000

Learn how to maximize reusability in your Angular components by using composition instead of inheritance

This is a follow-up from my previous article about Component Composition with Angular where I listed 3 ways of composing Angular components:

Class Inheritance
Class Mixins
Component Composition

TLDR; my favorite way is to compose components in small units and use Inputs and Outputs to communicate between components. In order to share logic pieces between components, I like how Mixins can help us avoid some pitfalls from using class inheritance.

In this article, I want to focus more on the relationship between Class Inheritance and Class Mixins, how they differ, and some pitfalls from using Mixins for building components.

Tip: Use tools like **Bit** (Github) to increase code reuse by sharing and collaborating on Angular components across projects. Share your reusable building blocks to a collection on bit.dev, for future compositions.

Example: Shared Angular components in a Bit collection

The Pitfalls of Class Inheritance

You probably already know why using inheritance is at times very appealing: define some methods and properties once, then use them for every common subclass: wonderful!

On a superficial level, and in some cases, that is actually a good thing. Yet, there are some well-known and documented issues that come with *class inheritance. *The most important ones, from a component architect’s point of view, are the following:

fragile base class — when a change in your base class breaks the derived subclasses
it encourages early choices when designing the base class: it makes the design brittle and fragile
it breaks encapsulation

In fact, you may have heard the legendary quote from the Gang of Four book:

Favor composition over inheritance

There are several types of components where I see inheritance used pretty often:

form fields with common value accessors
route components that extend a base-route
modal, popups, etc. with common methods (show, hide, etc.)

This article focusses more on business logic rather than purely visual attributes (disabled, animated, etc.). I found that sharing logic between components to be a little bit complex and a mostly misunderstood topic, especially when the framework itself does not provide an official stance regarding the topic, as opposite for example to React.

Typescript Mixins

The concept of Mixins is pretty simple: imagine that instead of having a hierarchy of classes, you instead have a number of very small partial classes. These classes can be combined together and build larger classes with great flexibility.

The way Mixins are created with Typescript is simple: we define a function that takes as argument a class and extend the newly created class with the one passed as the argument.

First, we define the mixins pinMixin and closeMixin that define 1 method each:

    function pinMixin(BaseClass) {
      return class extends BaseClass {
         pin() {
            // implementation
         }
      }
    }

    function closeMixin(BaseClass) {
      return class extends BaseClass {
         close() {
           // implementation
         }
      }
    }

We create a Base class that is created by merging the mixins functions, and then we extend the implementation:

    const BaseTabMixin = pinMixin(
      closeMixin(class {})
    );

    class Tab extends BaseTabMixin {}

    // Tab now can use the methods `close` and `pin`

Scenario: A Social Media Aggregator App

As an example, I want to build a prototype of a Social Media aggregator application with a feed of posts from the main social media services.

This is a particular example that I faced many years ago as a Junior developer: Babel was released, and ES6 classes were the fancy new thing until they weren’t.

Junior me, a little naively, started creating base classes, extending left and right, and it was exciting. Look how much code I was able to share thanks to them! In the beginning, it’s something you don’t immediately realize: requirements are not fully fleshed-out, and as we all know, new details emerge continuously.

We’re going to see how to build posts components for social media like Facebook, Twitter, Youtube, and Reddit: first, we’ll be using the good old Inheritance.

Afterward, we’ll be refactoring using Composition.

Building a base post component with Inheritance

Let’s proceed and build a BasePost class that shares properties and methods that the derived subclasses will share. As you may already know, social media posts are fairly similar to each other, with subtle differences: they have an author, some content (be it text, a link, or an image), and allow some actions such as liking, sharing, editing, etc.

Our base class PostComponent will have an input (Post object) and will inject a service PostService to which we delegate our actions.

The only common action shared among all the Social posts is delete and therefore we add it to base class so that all the subclasses can inherit the method.

    class PostComponent {
      @Input() post: Post;

      constructor(protected service: PostService) {}

      delete() {
         this.post.delete(this.post.id);
      }
    }

This is the bare minimum base class we can create. Now, we can proceed and add specific actions.

We know that both Facebook and Twitter allow posts to be liked, but not Twitter nor Youtube; therefore, we create a subclass called LikeablePost:

    class LikeablePost extends PostComponent {
        get likes() { 
          return this.post.likes;
        }

        like() {
          this.service.like(this.post.id);
        }

        unlike() {
          this.service.unlike(this.post.id);
        }
    }

Both Youtube and Reddit allow posts to be upvoted and downvoted; it makes sense to create a subclass that allows performing such actions:

    class VoteablePost extends PostComponent {
        downvote() {
          this.service.downvote(this.post.id);
        }

        upvote() {
          this.service.upvote(this.post.id);
        }
    }

Facebook and Twitter also have another similarity: the concept of “sharing” as key metadata.

    class ShareablePost extends LikeablePost {
        get shares() {
          return this.post.shares;
        }

        share() {
          this.service.share(this.post.id);
        }
    }

A similarity shared among Youtube, Facebook and Reddit are that they all allow posts to be edited, unlike Twitter.

This is the first issue we encounter:

as the method is not shared by all classes, it would be a mistake to add it to the base class
we could implement the method edit for all the subclasses, but that’d be very repetitive

We proceed by implementing TwitterPostComponent

    @Component({...})
    class TwitterPostComponent extends ShareablePost {}

Let’s take a jump into the future, and Jack gives us horrible news: we can no longer delete tweets! Our class now needs to change, but wait: delete is defined in the base class.

if we remove the method from the base class, we will break the other classes
if we remove it only from TwitterBaseComponent we will end up breaking the Liskov substitution principle, that means TwitterBaseComponent and PostComponent should be able to be swapped without breaking anything

If it wasn’t clear enough by now, all this was a bad idea.

Enter Composition

Now, we’re going to rewrite all the previous by composing mini-classes instead and using Typescript mixins to create components made of many separate, small classes.

Let’s create the mixins required to create the component TwitterPostComponent: likeMixin, deleteMixin and shareMixin.

Base Class

First of all, we want the mixins to be generic enough to be applied to a variety of components, with one single dependency being the service injected to the component.

    export interface PostComponent {
      post: Post;
      service: PostService;
    }

likeMixin

    // like
    function likeMixin<IBasePost extends Constructor<PostComponent>>(
      Base: IBasePost
    ) {
      return class extends BasePost implements CanLike {
        get likes() {
          return this.post.likes;
        }

        like() {
          return this.service.like(this.post.id);
        }

        unlike() {
          return this.service.unlike(this.post.id);
        }
      };
    }

deleteMixin

    function deleteMixin<IBasePost extends Constructor<PostComponent>>(
      BasePost: IBasePost
    ) {
      return class extends BasePost implements CanDelete {
        delete() {
          return this.service.delete(this.post.id);
        }
      };
    }

shareMixin

    *export function shareMixin<IBasePost extends Constructor<PostComponent>>(
      BasePost: IBasePost
    ) {
      return class extends BasePost implements CanShare {
        shares: number;

        share() {
          return this.service.share(this.post.id);
        }
      };
    }

Creating the implementation component: TwitterPostComponent

Once created, we can apply them to the newly created TwitterPostComponent:

    const TwitterBase = deleteMixin(
      likeMixin(
        shareMixin(PostComponent)
      )
    );

If you prefer to use the applyMixins function described in Typescript’s own documentation, you can do the following:

    class TwitterBase extends PostComponent {}

    interface TwitterBase extends CanLike, CanDelete, CanShare {}

    applyMixins(TwitterBase, [
      shareMixin, 
      likeMixin, 
      deleteMixin
    ]);

Once created the base component composed with the mixins, we can extend the new component TwitterPostComponent:

    @Component({
      selector: 'twitter-post',
      template: `
        <div class="post">
          <div class="post-header">
            {{ post.author }}
          </div>

          <div class="post-content">
            {{ post.content }}
          </div>

          <div class="post-footer">
            <button (click)="like()">Like</button>
            <button (click)="share()">Share</button>
          </div>
        </div>
      `
    })
    export class TwitterPostComponent extends TwitterBase {}

In order to remove a delete functionality from the Tweets components, we don’t have to do much — we simply remove the deleteMixin mixin from our class:

    const TwitterBase = likeMixin(
        shareMixin(PostComponent)
      )
    );

Pitfalls of using Mixins

Mixins are great, but they’re not an infallible tool. While I would still prefer Mixins to multiple inheritance, it is important to understand the implications of using this technique.

This React blog post provides a great explanation on why Mixins are no longer considered a best practice in React:

Mixins create implicit dependencies: mixins that call methods on components, reference a property from the component, or components that need a mixin to work well, are all dependent on each other
Mixins start small but grow over time
Mixins lead to name clashes

Of course, because of the similarities, these also apply to Typescript mixins used with Angular components.

How to avoid these pitfalls?

Try not to apply too many mixins; if you have too many mixins, maybe you should split the component into several components and use component composition with inputs and outputs to communicate between each other
Strive to keep them as small as possible
Keeps dependencies between mixin/component to a minimum. For example, wherever possible, try not to call a component’s dependencies from the mixin
Combine the mixins technique with component composition. Together with the usage of small mixins, you can leverages both techniques to share code and maintain a healthy codebase

Resources

Typescript Mixins
Angular Material is a library that makes use of mixins, so I would suggest you check out their components to see how they can be used in a variety of situations
Mixins Considered Harmful

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on* Medium, Twitter or my website for more articles about Software Development, Front End, RxJS, Typescript and more!

Component Reusability Techniques with Angular

Giancarlo Buomprisco — Wed, 06 Nov 2019 19:21:26 +0000

Techniques to share logic between components

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

DRY (Don’t repeat yourself) is one of the fundamental concepts of software engineering; As software engineers, we often strive to build as much as possible using as little code as we can.

That’s indeed a really good thing because it allows us to ship less code, increase productivity, and keep a healthy codebase.

In this article, I want to introduce you to the techniques available with Angular to build components by sharing as much code as possible:

Class inheritance
Class mixins
Component composition

Tip: Use Bit (Github) to easily share and reuse Angular components across your projects, suggest updates, sync changes and build faster as a team.

Angular components with Bit: Easily share across projects as a team

Component Class Inheritance

My least favorite, but also the most used way to share code among Angular components, is ES6 class inheritance *using the extends keyword.*

ES6 class inheritance is seen as hugely controversial in the Javascript community for various reasons, but it is still incredibly used in the Angular world; when used in the right way and is not abused, the technique is a decent solution for sharing code between components.

Let’s see an example of extending a component with inheritance by creating a component ListComponent, extended by two more abstract classes that extend the functionality of the base class, and then we implement these with the actual Angular component.

A common way of using this technique is to create an abstract class and define there the methods shared by all the subclasses. A subclass may have to implement the abstract methods or override the existing ones.

ListComponent Base class

The Base class is very simple: we simply define the Input items.

    export abstract class ListComponent {
      @Input() items: Item[];
    }

Next, we want to extend the functionality of a simple list with pagination and selection. Therefore, we proceed and extend BaseList with two more abstract classes.

PageableListComponent

The component PageableListComponent extends ListComponent and adds pagination functionality.

    export abstract class PageableListComponent extends ListComponent {
        page = 0;
        itemsPerPage = 2;

        get start() {
         return this.page * this.itemsPerPage;
        }

        get end() {
         return this.page * this.itemsPerPage + this.itemsPerPage;
        }

        get pages() {
          return new Array(this.items.length / this.itemsPerPage);
        }

        changePage(page: number) {
          this.page = page;
        }
    }

SelectableListComponent

The component SelectableListComponent extends PageableListComponent and adds selection/unselection functionality.

    export abstract class SelectableListComponent extends PageableListComponent {
      @Output() selected = new EventEmitter<Item>();
      @Output() unselected = new EventEmitter<Item>();

      selectedItems: Item[] = [];

      select(item: Item) {
        this.selected.emit(item);
        this.selectedItems = [...this.selectedItems, item];
      }

      unselect(item: Item) {
        this.unselected.emit(item);
        this.selectedItems = this.selectedItems.filter(({value}) => value !== item.value);
      }

      isItemSelected(item: Item) {
        return this.selectedItems.some(({value}) => item.value === value);
      }
    }

Implementation component: CustomersListComponent

Finally, we create an implementation of the class CustomersListComponent and extend it SelectableListComponent. The template and the component will have access to all the outputs and inputs we specified in the other classes.

    @Component({
      selector: 'customers-list',
      template: `
        <div *ngFor="let item of items | slice: start : end">
         <label>
           <input
             type="checkbox"
             [checked]="isItemSelected(item)"
             (change)="
               $event.target.checked ? select(item) : unselect(item)
             "
           />
          {{ item.display }}
         </label>
        </div>
        <div class='pages'>
        <div *ngFor="let p of pages; let i = index;" 
             class='page' 
             [class.selected]="i === page" 
             (click)="changePage(i)"
         >
         {{ i }}
        </div>
      </div>
    `
    })
    export class CustomersListComponent extends SelectableListComponent {}

    // USAGE
    <customers-list [items]="customers" 
                    (selected)="onSelected($event)"               
                    (unselected)="onUnselected($event)"
    ></customers-list>

We can also create a subclass from CustomersListComponent, although the decorator’s metadata will have to be redefined. That means we will need to assign a new selector, template, styles, etc. to the new component. If you want to reuse them, then you can point the URLs to the parent class’:

    @Component({
      selector: 'new-customers-list',
      templateUrl: '../customers-list/customers-list.component.html'
    })
    export class NewCustomersListComponent extends CustomersListComponent {}

Component Class Mixins

In order to share logic between Angular component classes, we can also leverage a less-known method known as Mixins. Mixins allow us to compose multiple small classes that extend the target class but without having to use multiple inheritance.

An Example of Typescript Mixin

Let’s demonstrate what a mixin is with a simple example. First, we define a base class:

    class BaseButton {
      label: string;
      disabled: boolean;
    }

Next, we define a function that extends the base class with a new mini-class

    function themeMixin(BaseClass) {
        return class extends BaseClass {
          theme: string;
        }
    }

Finally, we extend the BaseButton class with the mixin:

    class PrimaryButton extends themeMixin(BaseButton) {}

Building CustomersListComponent using Mixins

Let’s rewrite the CustomersListComponent example using mixins.

    export function pageableListMixin(BaseClass) {
      return class extends BaseClass {
        page = 0;
        itemsPerPage = 2;

        get pages() {
          return new Array(this.items.length / this.itemsPerPage);
        }

        changePage(page: number) {
          this.page = page;
        }

        get start() {
         return this.page * this.itemsPerPage;
        }

        get end() {
         return this.page * this.itemsPerPage + this.itemsPerPage;
        }
    }

    export function selectableListMixin(BaseClass) {
      class SelectableListMixin extends BaseClass {
        @Output() selected = new EventEmitter<Item>();
        @Output() unselected = new EventEmitter<Item>();

        selectedItems: Item[] = [];

        select(item: Item) {
          this.selected.emit(item);
          this.selectedItems = [...this.selectedItems, item];
        }

        unselect(item: Item) {
          this.unselected.emit(item);
          this.selectedItems = this.selectedItems.filter(({value}) => {
            return value !== item.value;
          });
        }

        isItemSelected(item: Item) {
          return this.selectedItems.some(({value}) => {
            return item.value === value;
          });
        }
      }

      return SelectableListMixin;
    }

Once we define all the mixins we need to compose the component, we import the mixins and pass the Base class as an argument.

Then, we simply extend CustomersListComponent with the mixin CustomersListMixin.

    const CustomersListMixin = 
      selectableListMixin(
        pageableListMixin(ListComponent)
      );

    @Component(...)
    export class CustomersListComponent extends CustomersListMixin {}

While also Mixins have several pitfalls, this is, in my opinion, a more elegant and safer solution to multiple inheritance, at least in the long term.

Component Composition

The component composition is a technique that complements inheritance and mixins: instead of extending a component with more functionality, we can combine multiple smaller components to achieve the same result.

ListComponent: Leveraging the Power of ngTemplateOutlet

The first component we can create is a generic, reusable component ListComponent: its responsibility is to simply render the items based on start and end indexes as provided by the parent component.

As you can see, the component does not dictate how to render each individual item: we let the parent define that by providing ngTemplateOutlet and passing each item as context.

    @Component({
      selector: "list",
      template: `
        <div *ngFor="let item of items | slice : start : end">
          <ng-container 
           *ngTemplateOutlet="template; context: { item: item }"
          >
          </ng-container>
        </div>
    `
    })
    export class ListComponent {
      @Input() items: Item[] = [];
      @Input() itemsPerPage = 2;
      @Input() currentPage: number;

      @ContentChild('item', { static: false }) 
      template: TemplateRef<any>;

      get start() {
        return this.currentPage * this.itemsPerPage;
      }

      get end() {
        return this.currentPage * this.itemsPerPage + this.itemsPerPage;
       }
    }

PaginationComponent

Then, we add a pagination component that takes care of listing the page numbers, and to notify the parent when the user clicks on a page:

    @Component({
      selector: "pagination",
      template: `
        <div class="pages">
          <div
           *ngFor="let p of pages; let i = index"
           class="page"
           [class.selected]="i === currentPage
           (click)="pageChanged.emit(i)"
          >{{ i }}
          </div>
       </div>
    `
    })
    export class PaginationComponent {
      @Input() currentPage: number;
      @Input() itemsPerPage = 2;
      @Input() itemsLength: number;

      @Output() pageChanged = new EventEmitter<number>();

      get pages() {
        return new Array(this.itemsLength / this.itemsPerPage);
      }
    }

CustomerComponent

Next, we define a component to represent each item in the list: it takes care of defining how the item is displayed, and dispatch events when the item is selected or unselected:

    @Component({
      selector: "customer",
      template: ` 
        <label>
          <input
            type="checkbox"
            [checked]="isSelected"
            (change)="$event.target.checked ? selected.emit(item) : unselected.emit(item)"
          />
          {{ item.display }}
       </label>
    `
    })
    export class CustomerComponent {
      @Input() item: Item;
      @Input() isSelected: boolean;

      @Output() selected = new EventEmitter<Item>();
      @Output() unselected = new EventEmitter<Item>();
    }

CustomersListComponent

It’s now time to put things together! We can reuse the previously defined components to compose a list of customers, that is selectable and pageable. These components are all reusable and can be composed with any other list.

    @Component({
      selector: "composition-customers-list",
      template: `
        <list
         [items]="items"
         [itemsPerPage]="2"
         [currentPage]="currentPage"
        >
         <ng-template #item let-item="item">
           <customer
            (selected)="selected($event)"
            (unselected)="unselected($event)"
            [item]="item"
            [isSelected]="isItemSelected(item)"
           ></customer>
         </ng-template>
        </list>

        <pagination
         [currentPage]="currentPage"
         [itemsLength]="items.length"
         [itemsPerPage]="2"
         (pageChanged)="currentPage = $event"
        ></pagination>
    `
    })
    export class CompositionCustomersListComponent {
      @Input() items = [];

      currentPage = 0;
      selectedItems = [];

      selected(item) {
        this.selectedItems = [...this.selectedItems, item];
      }

      unselected(item) {
        this.selectedItems = this.selectedItems.filter(({ value }) => value !== item.value);
      }

      isItemSelected(item) {
        return this.selectedItems.some(({ value }) => item.value === value);
      }
    }

Component composition is the ultimate way to create highly-reusable, clean, and effective components, and is easily my favorite way of thinking about sharing code and reusability.

Instead of writing God components, we can reuse many smaller ones. Getting right the public API of each component is fundamental for them to work well with the rest of your application.

As you can see above, we still have some repeated logic due to some methods being rewritten for each list we create: that’s why using one technique is not exclusive: we can easily combine this with a mixin that takes care of selection, so we do not have to rewrite it for other lists.

Source code

You can find all the examples’ code at this Stackblitz link.

Final Words

In this article, we went through three techniques for sharing code between components.

If it wasn’t clear by now, I am not a fan of inheritance and multiple inheritances, but I think it’s still very important to know and recognize when it’s a good idea to use and when it’s not.

In my next article, I will be focussing more on Typescript Mixins, which in my opinion is the least known and underrated way of building components. I will explore a scenario where inheritance results in brittle, hard to maintain code, and how Mixins can help, including cons and pros, and prior art from the Javascript community.

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on Medium, Twitter or my website for more articles about Software Development, Front End, RxJS, Typescript and more!

Debugging Memory Leaks in Angular

Giancarlo Buomprisco — Wed, 30 Oct 2019 12:08:35 +0000

The situations where memory leaks are most likely to happen, and how you can deal with them using Chrome DevTools.

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

Introduction to Memory Leaks

Building large applications entails writing lots of code, complex pages, long lists, and hundreds (if not more) of components. If you’ve worked at least once in a non-trivial web application, you may have found yourself battling a memory leak for hours and hours.

In this article, I want to introduce you to a number of situations where memory leaks are most likely to happen, and how you can deal with them thanks to the powerful Chrome DevTools.

Preface: Angular is a framework that does a really great job at memory management: in fact, you almost never have to do something specific to avoid memory leaks!
Nonetheless, I’ve found myself in a number of scenarios that led to mistakes resulting in memory leaks and, as a consequence, a crippled user-experience for my company’s clients.

Not good.

What’s a Memory Leak?

In layman’s terms, a memory leak occurs when an application fails to get rid of unused resources.

If the memory of an application is using more and more memory without being populated with new resources (images, text, objects, etc.), then the application is likely affected by this sort of performance degradation.

Tip: **Use **Bit (Github) to easily share and reuse Angular components across your projects, suggest updates, sync changes and build faster as a team.

Don’t waste time rewriting mediocre code — build awesome reusable Angular components, test them in isolation using Bit and share them on bit.dev.

Components with Bit: Easily share across projects as a team

Why Memory Leaks are tricky

The trickiest aspect of memory leaks is that they are pretty hard bugs to spot. Unlike CPU usage issues, where you can see the UI lagging, memory leaks (especially for smaller apps) are much a more subtle sort of problem.

If not also in charge of QA, the way most developers work is to focus on the context of their task, and very rarely they have to switch page dozens of times, create and re-create large lists, or in general perform long-lived actions that are naturally where memory leaks become apparent.

In fact, your applications may have dozens of memory leaks who have not yet been discovered!

Nowadays, users reload pages less and less often. As someone who works in the financial sector, I should know: traders hate reloading! The computers in offices are rarely restarted and so are browser pages.

This is why keeping performance optimal for long-lived sessions is essential: if an application is leaking memory, the user will at some point realize that it is slower, sluggish, and will likely pause very frequently.

And we don’t want our users to get frustrated. Right!?

Debugging Process

In this section, we will explore some real-world scenarios in Angular applications where it’s most likely to encounter potential mistakes that lead to memory leaks.

The irony about this article is that I planned on purposefully add mistakes in my code (using my guinea pig project Cryptofolio) to produce a memory leak.

Cryptofolio shows live crypto prices

As it turns out, it wasn’t needed! A leak was already there. All I did in order to reproduce it was to initialize the app with 101 pricers — back and forth a couple of times between pages, et voilá — the memory went nuts!

Notice: the application I am using is very small, and as a result, the mistakes won’t cause the app to crash, and more importantly, the objects retained in memory won’t be immediately easy to find in the Heap Snapshots.

Monitoring Memory with the Performance Monitor tool

The application I built allows me to display prices in two separates views: list and dashboard; these two are two different pages, so the components contained in each of them are supposed to be destroyed and collected when you navigate to another page.

The first thing to do is to open the Chrome Dev Tools, open the panel on the right and click on More Tools > *Performance Monitor. *The memory of our application is displayed in the blue graph.

As you can see in the image below, whenever I switch page, the memory jumps up almost 20mb!

Js heap size increasing when switching page

I keep switching back and forth, and this is the result below:

Performance Monitor

🔥154MB and 99% CPU? Clearly, something’s wrong🔥

Starting the debugging process: Memory Snapshots

The first thing I do when debugging is to record memory snapshots in two stages:

at initial load, as soon as the app becomes stable and all the elements have been loaded
a second time once the initial data is replaced by other data. It’s quite important to make sure your app is not actually adding additional resources, unless of course if that is a bug. For example, you could be switching page or forcing some elements to show/hide

The above will allow me to compare them with the Dev Tools’ Memory Snapshots.

Tip: Make sure you also tick “Event Listeners”: it will help understand if the number of event listeners is piling up.

In order to take a Memory Snapshot, open the Dev Tools->Memory, select “Heap Snapshot” and then click on the button “Take Snapshot”. The profiles are listed on the left-hand side and you can compare them with each other to visualize which objects have been retained in memory.

Exploring the Snapshot 🧭

As you can see in the image below, I proceeded by taking 2 heap snapshots, listed on the left.

When the initial snapshot is taken, the tools will show you the summary of the current snapshot, but you can compare two snapshots by choosing “Comparison” from the dropdown above the objects.

The list displayed by the snapshot can look pretty alien, low-level and unfamiliar if you have been a Web Developer all your life like me, but don’t let that scare you off. The most important thing is to be patient and understand the clues that will lead you to the memory leak.

As soon as I took the snapshot, I started scrolling through the items looking for clues and familiar pieces of code, and one item immediately caught my attention: MapSubscriber.

That’s kind of familiar, isn’t it? As you can see in the comparison table on the right-hand side, the Delta suggests that there have been more items added than removed.

Heap Snapshot

By clicking on an item in the top panel will immediately redirect the panel below to its “retainers”, or the Object Retaining Tree.

I started digging down the Map destination object until we get to project, which is the function we pass to a map operator and that leads to a line in one of the project’s files, asser-pricer.component.ts.

Let’s take a look at the context around that line: it is a simple selection from the store that returns me a price and maps it to a String.

Also, I used shareReplay(1) to multicast the price observable to the get trend value (e.g. if it went up or down since the previous emission).

    this.price$ = this.pricesFacade
      .getPriceForAsset(this.asset)
      .pipe(
        filter<string>(Boolean),
        map(price => {
          return parseFloat(price).toFixed(2);
        }),
        shareReplay(1)
      );

Rx Subscriptions 🦊

Let’s reflect for a moment about the line we just landed on: the issue is clearly an unsubscribed observable that is retaining the components in the memory.

It doesn’t matter how many times we’ve been told to clean up our Rx subscriptions: in my experience, this is by far the most common cause of memory leaks in Angular applications.

Many developers will probably be thinking: is an open subscription really going to cause havoc in a real-world application?

Yes, it can.

Especially for large applications, if the leak happens within a repeated component (lists, tables, infinite scrolling components, etc.), even only one open subscription can cause your application to retain in memory the components until the subscription gets cleaned up.

You would expect the components to be cleaned up when destroyed, for example:

when the user navigates to another page
when the user replaces/filters the elements with a different selection

While unsubscribing is a fairly simple concept to understand, and unsubscribing itself (especially is using the async pipe) is easy, there are situations when the full knowledge of the operators we’re using is essential, as it happened in my case.

ShareReplay, what are you? 🤔

Let’s get back to the issue.

We found out a possible responsible candidate for our memory leak. The first thing I do is to debug shareReplay to understand why the subscription is not being unsubscribed, which lead me to its source code:

ShareReplay’s source code

The long condition around the unsubscription was pretty suspect — why? It turns out, despite me reading articles and documentation plenty of times about this, I missed a pretty important detail about this operator.

In fact, if we don’t specify the property refCount: true, the subscription will never be unsubscribed. To fully understand why I refer you to this Angular In Depth article: What’s Changed with ShareReplay.

In order to fix this, I made the following change:

    this.price$ = this.pricesFacade.getPriceForAsset(this.asset).pipe(
      filter<string>(Boolean),
      map(price => {
        return parseFloat(price).toFixed(2);
      }),
      shareReplay({
        bufferSize: 1,
        refCount: true
      })
    );

And now the memory leak from my application is gone!

But let’s see some other common scenarios — some of which appear even in some extremely popular libraries for Angular.

Event Listeners

Another common cause of memory leaks is DOM events that are never unregistered. Some folks may think that using Angular’s Renderer may take care of it, but that is only the cause if the events are defined in the template, just as with the async pipe.

Let’s see a quick and common example of a component that registers a scroll listener on the body, without never unregistering the event:

    @Component({...})
    export class ScrollComponent {
      constructor(private renderer: Renderer2) {}

      ngOnInit() {
        this.renderer.listen**(document.body, 'scroll', () => {
          this.updatePosition();
        });
      }

      updatePosition() { /* implementation */ }
    }

This does, indeed, create a memory leak every time we instantiate ScrollComponent — so let’s fix it:

    @Component({...})
    export class ScrollComponent {
      private listeners = [];

      constructor(private renderer: Renderer2) {}

      ngOnInit() {
        const listener = this.renderer.listen(
          document.body, 
          'scroll', 
          () => {
            this.updatePosition();
          });

        this.listeners.push(listener);
      }

      ngOnDestroy() {
        this.listeners.forEach(listener => listener());
      }

      updatePosition() { /* implementation */ }
    }

Unregistering all the events prevents the component ScrollComponent to be retained in memory and will be cleaned up once destroyed, along with its children.

Websocket Connections

Very similarly, WebSocket connections must always be closed when unused. Imagine we have a component PricerComponent that subscribes to a WebSocket and displays incoming cryptocurrency prices.

    @Component({
      selector: 'pricer',
      template: `
        <span>{{ id | titlecase }}:</span>
        <span>{{ ( price$ | async) || 'loading...' }}</span>
      `
    })
    export class PricerComponent  {
      @Input() id: string;

      public price$ = new Subject();
      private static Endpoint = 'wss://ws.coincap.io/prices/';
      private webSocket: WebSocket;

      ngOnInit() {
        this.webSocket = new WebSocket(
          this.getEndpoint(this.id)
        );

        this.webSocket.onmessage = (msg) => {
          const data = JSON.parse(msg.data);
          this.price$.next(data[this.id]);
        };
      }

      private getEndpoint(id: string) {
        return PricerComponent.Endpoint + '?assets=' + id;
      }
    }

Let’s explain the snippet:

we receive an ID as input and we subscribe to it via WebSocket every time the component is initialized
when is the WebSocket connection cleared? Never! Once again, we’re missing the good gold ngOnDestroy hook to take care of it when the component gets destroyed
This creates multiple issues: not only we’re creating multiple WebSocket connections, but we’re also retaining PricerComponent in memory every time it gets re-initialized

Let’s take a snapshot and analyze it!

Heap Snapshot WebSocket example

As per the image above, I start by comparing the initial load (with 1 pricer) with another snapshot taken after a small session.

The Delta reveals me where additional memory has been allocated, so I start digging in the (closure) tree searching for clues back to my code.

After scrolling a little bit, I stumble on this closure, which takes me back exactly to the callback passed to webSocket.onmessage!

Debugging this case was admittedly pretty easy, but in some cases, it can be pretty daunting. There is a way we can help facilitate the debugging process by** naming functions** so that they will appear in the Memory Snapshot.

For example, I could have written:

    const onPriceReceived = (msg: MessageEvent) => {
      const data = JSON.parse(msg.data);
      this.price$.next(data[id]);
    };

    this.webSocket.onmessage = onPriceReceived;

This bug is easily solved by adding the following method:

    ngOnDestroy() {
      this.webSocket.close();
    }

You can see the full example at this Stackblitz link.

Takeaways ⭐

Memory Leaks are quite hard to find and debug — my suggestion is to keep the Performance Monitor open from time to time and see if the memory is stable
Angular does a great job at managing memory; with that said, we need to watch out for open subscriptions (Observables, Subjects, NgRx Store Selections), DOM events, WebSocket connections, etc.
Learn how to use well the Chrome Dev Tools! It is essential for debugging performance and memory leaks. Even if it is intimidating to see so much low-level terminology, try to read and learn as much as possible about it
Name closures! It helps with debuggability and, in my opinion, makes code more readable

Resources

If you need any clarifications, or if you think something is unclear or wrong, do please leave a comment!

I hope you enjoyed this article! If you did, follow me on* Medium, Twitter or my website for more articles about Software Development, Front End, RxJS, Typescript and more!

API-less Prototyping with Angular

Giancarlo Buomprisco — Mon, 28 Oct 2019 10:40:23 +0000

Start prototyping with minimal changes to your application at integration time with Angular Injectables

This article was originally published on Bits and Pieces by Giancarlo Buomprisco

I am one of those developers who is usually fairly impatient when the Product Manager unveils the new product’s features that I can finally start working on.

After the sprint planning, I ask the dreaded question:

… is the API ready yet?

… and the answer is often times negative. Sometimes your backend colleagues are busier with other things, and can’t provide even a mock endpoint. No fear, though!

Provided you have a viable DTO interface your back-end colleague agrees with, you can start prototyping the new features with minimal changes to your application at integration time with the real API endpoints.

In order to minimize the changes needed during the integration, we will leverage the power of Angular’s Injectables and will work on both the API clients at the same time:

one is the mocked version, which we will call MockPriceApiService
the other is the actual service that will be shipped with the application when the API will be ready to be consumed, which we call PriceApiService
the two classes will implement an interface to establish an API contract between the two

A quick tip: Use Bit (Github) to share, reuse and update your Angular components across apps**. Bit track and bundles reusable components in your projects, and exports them encapsulated with their dependencies, compilers and everything else. Components can then be installed with package managers, and even updated right from any new project. Give it a try.

Yet again (!), I will build a minimal live cryptocurrency application that will work with both mocked prices and with an actual service that will pull prices from Coincap.

If you’re impatient or just TLDR; you can see the final result on Stackblitz!

Final Result

The API Interface

First thing, we want to establish which API the two classes will share. So, we build an interface called ApiService

import { Observable } from 'rxjs';

export interface PriceApi {
  getPrice(currency: string): Observable<string>;
  unsubscribe(): void;
}

As you can see, the services that will implement this interface will only need to provide two public methods:

one to subscribe to a stream of prices
the other to unsubscribe the stream.

Mock Service

Let’s start by creating the mock service. As we have said before, we only need to implement two methods to respect the contract. In short, what we want to do is:

get a stream of random numbers (prices), and we will base this off a set of base prices we use as a reference to make the numbers close to the real ones
unsubscribe said stream

The app we will create will only support 3 currencies: Bitcoin, Litecoin and Ethereum.

const BASE_PRICES = {
  bitcoin: 11000,
  litecoin: 130,
  ethereum: 300
};

const randomize = (price: number) => {
  return (Math.random() * 2) + price;
};

@Injectable()
export class MockPriceApiService implements PriceApi {
  static latency = 250;
  private unsubsciptions$ = new Subject();

  public getPrice(currency: string): Observable<string> {
    return timer(0, MockPriceApiService.latency).pipe(
      delay(1000),
      map(() => BASE_PRICES[currency]),
      map((price: number) => randomize(price)),
      map((price: number) => price.toFixed(5)),
      takeUntil(this.unsubsciptions$),
    )
  }

  public unsubscribe() {
    this.unsubsciptions$.next();
  }
}

Let’s explain the method getPrice:

we receive a parameter called currency which represents the name of the asset subscribed
we create a timer that will emit an event every 250ms
we delay the emitted observable by 1 second to mimic a real network latency
we take the BASE_PRICE of the selected currency and return a number that gets randomized at each emission
we unsubscribe the stream when the subject unsubscriptions$ emits

Real Live-Prices Service

As we said before, your team may take a while before a real API is provided to you to implement in your front-end.

If your team already agreed on the interface, though, there is nothing stopping you from implementing the API beforehand and build the real service alongside the mock service.

In order to complete our example, we will build the real service and take prices from Coincap’s Service (thank you again!) and use a WebSocket to stream prices to our client.

The two public methods will:

create a WebSocket connection and stream prices using an Observable, respecting the contract in the interface
close the connection when the method unsubscribe is called. As a result, the prices stream will stop emitting prices.

const WEB_SOCKET_ENDPOINT = 'wss://ws.coincap.io/prices/';

@Injectable()
export class PriceApiService implements PriceApi {
  private webSocket: WebSocket;

  public getPrice(currency: string): Observable<string> {
    return this.connectToPriceStream(currency);
  }

  public unsubscribe() {
    this.webSocket.close();
  }

  private connectToPriceStream(asset: string): Observable<string> {
    this.createConnection(asset);

    return new Observable(observer => {
      const webSocket = this.webSocket;

      webSocket.onmessage = (msg: MessageEvent) => {
        const data = JSON.parse(msg.data);
        observer.next(data[asset]);
      };

      return {
        unsubscribe(): void {
          webSocket.close();
        }
      };
    });
  }

  private createConnection(asset: string) {
    if (this.webSocket) {
      this.webSocket.close();
    }

    this.webSocket = new WebSocket(
      WEB_SOCKET_ENDPOINT + `?assets=${asset}`
    );
  }
}

Consuming the Service’s Data

Now, let’s show how to actually consume the data streamed by any of the two services we created.

Let’s create a component that injects PriceApiService:

we create a property to which we assign the stream, which we call price$
when the user changes cryptocurrency, we call the method unsubscribe, unless the currency has never been selected

@Component({
  selector: 'my-app',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class AppComponent {
  public price$: Observable<string | undefined>;
  public currency$ = new BehaviorSubject<string | undefined>(undefined);

  constructor(private api: PriceApiService) { }

  ngOnInit() {
    this.price$ = this.currency$.pipe(
      mergeMap((currency: string | undefined) => {
        return currency ? this.api.getPrice(currency) : of(undefined);
      })
    );
  }

  onCryptoSelected(currency: string) {
    if (this.currency$.value) {
      this.api.unsubscribe();
    }

    this.currency$.next(currency);
  }
}

And now on to the template:

we display the price
if the price is still undefined, but currency has been selected, it means a subscription is still in progress: as a result, we show to the user a loading message
if the currency hasn’t been selected, we show an empty message

<div class='mt-5'>
  <crypto-selector (selected)="onCryptoSelected($event)"></crypto-selector>

  <div class='price'>
    {{ price$ | async }}
  </div>

  <ng-container *ngIf="(price$ | async) === undefined && (currency$ | async)">
    <div class='alert alert-info mt-2'>
      Awaiting for Price...
    </div>
  </ng-container>

  <ng-container *ngIf="!(currency$ | async)">
    <div class='alert alert-warning mt-2'>
      No Crypto Subscribed Yet
    </div>
  </ng-container>
</div>

Switching Services using Dependency Injection

Here is the magic part. Thanks to Angular’s Dependency Injection, we can provide which service we want to use by passing to it the type and the actual class.

As you can see below, we instruct the DI:

when the user injects PriceApiService
use the following class: if useMocks is truthy, use MockPriceApiService, otherwise, use PriceApiService.

// in a real app could be environment.useMocks ?
const useMocks = true;

@NgModule({
  imports: [BrowserModule, CommonModule],
  declarations: [AppComponent, CryptoSelectorComponent],
  bootstrap: [AppComponent],
  providers: [
    {
      provide: PriceApiService,
      useClass: useMocks ? MockPriceApiService : PriceApiService
    }
  ]
})
export class AppModule { }

Of course, while your real endpoints are still being built, your prototype will continue using MockPriceApiService for as long as it’s needed.

Once your team is ready to switch to the real endpoints, all you’ll have to do is switch the environment variable to false (which could be set in your CI) and your app will automatically work with the real endpoints!

Angular’s DI

Angular’s Dependency Injection is very powerful.

In addition to useClass, you can also use:

useValue: for example, if you want to pass a number, a string, etc.
useFactory: for example, when you want to pass a function and make use of the DI to inject dependencies

And you can also use InjectionToken to pass different values other than classes.

For a complete reference about dependency injection, I’d suggest you read the full documentation at Angular.io.

Result

You can see the final result on Stackblitz!

Final Words

The Dependency Injection is a powerful tool, and can be used in a variety of useful ways:

prototyping
feature flags
mocking services for tests
general configuration

Learning how to master it can improve your Angular projects’ architecture and can allow patterns you didn’t know where even possible.

If you need any clarifications, or if you think something is unclear or wrong, please leave a comment!

If you enjoyed this article, follow me on Medium or Twitter for more articles about Angular, RxJS, Typescript and more!