Angular RxJS User interface Reactivity Web

At SketchUp I was running a team of developers making a complex Angular application. One of the features that required lots of fragile code that was hard to test and was developed independently in many different components was locking parts of the interface while data was loading.

We had a mixture of basic HTTP requests to API endpoints and also streaming data from WebSockets, where a loading spinner was necessary until the first value arrived.

The answer was one component that you can wrap around any part of the site, and pipes that fetch data directly inside the template, for instance 'url' | httpGet.

Loading in one component

Here's the usual way for a component to load something and show a spinner while it does:

@Component({
    selector: 'app-project',
    template: `
        <div class="spinner" *ngIf="loading"></div>
        <h1 *ngIf="!loading">{{ project?.name }}</h1>
    `,
})
export class ProjectComponent implements OnInit, OnDestroy {
    @Input() projectId: number;
    project: Project;
    loading = false;
    private subscription: Subscription;

    constructor(private http: HttpClient) {}

    ngOnInit() {
        const url = '/api/projects/' + this.projectId;
        this.loading = true;
        this.subscription = this.http.get<Project>(url).subscribe(
            (project) => {
                this.project = project;
                this.loading = false;
            },
            () => {
                this.loading = false;
            },
        );
    }

    ngOnDestroy() {
        this.subscription.unsubscribe();
    }
}
Loading a project with a flag and a subscription

That's a lot of code for showing one name, and it still isn't right. If projectId changes, ngOnInit doesn't run again, so it carries on showing the old project; fixing that needs ngOnChanges, and cancelling the request that's already on its way. Only the heading is hidden while it loads, so anything else in the component can still be clicked. And every one of those paths needs a test.

Loading in hundreds of components

Now scale that up to hundreds of components, loading things at various different points as people use the interface: opening a panel, choosing a tab, expanding a row.

Every developer wrote it a little differently. Some components locked their buttons while they loaded and some didn't, so you could click twice, or edit something that was about to be replaced. A panel showing three things from three requests needed forkJoin or combineLatest just to know when they'd all arrived. A parent that had to stay locked until its children had loaded, requiring loading flags passed up through outputs and back down through inputs.

The loading code was spread through every component, and that's where the bugs were.

A loader and a pipe

With the loader, the same component is just a template. In practice we wrapped up the endpoints in functions which returned a high level request object to abstract over different types of connections, but this shows the basic principle:

<app-loader>
    <ng-container *ngIf="('/api/projects/' + projectId) | httpGet as project">
        <h1>{{ project.name }}</h1>
        <app-model-list [projectId]="projectId"></app-model-list>
    </ng-container>
</app-loader>
The project component's template
<ul>
    <li *ngFor="let model of ('/api/projects/' + projectId + '/models') | httpGet">
        {{ model.name }}
    </li>
</ul>
The app-model-list component's template

Neither component has a flag, a subscription or a lifecycle method. While the project loads, the loader hides its content and shows a spinner. When the project arrives, the model list appears and starts loading its models, and the loader stays locked until they've arrived too. If projectId changes, both pipes see a new URL and fetch again, and the loader locks while they do. Neither component knows the loader is there.

The pipes find the loader through dependency injection. The loader provides a LoadingManager, and every httpGet pipe inside it, however deep in child components, is given that manager when it's created. Each pipe registers itself, says when it starts and finishes loading, and unregisters when it's destroyed. The loader watches the manager, and hides its content while anything is loading:

Pipes anywhere inside the loader report to its manager
Pipes anywhere inside the loader report to its manager

There are three pieces: the loader component, the manager, and the pipe.

The loader component

import { Component } from '@angular/core';
import { Observable } from 'rxjs';
import { LoadingManager } from './loading-manager';

//  Wrap any part of a page in <app-loader>: while anything inside it is loading, its content is hidden,
//  and so locked, and a spinner shows instead
@Component({
    selector: 'app-loader',
    template: `
        <div [class.hidden]="loading$ | async">
            <ng-content></ng-content>
        </div>
        <div class="spinner" *ngIf="loading$ | async"></div>
    `,
    styles: [`
        :host { display: block; position: relative; min-height: 48px; }
        .hidden { visibility: hidden; }
        .spinner { position: absolute; top: 12px; left: 50%; margin-left: -12px; width: 24px; height: 24px;
                   border: 3px solid #c9d6da; border-top-color: #0e7490; border-radius: 50%;
                   animation: spin 0.8s linear infinite; }
        @keyframes spin { to { transform: rotate(360deg); } }
    `],
    providers: [LoadingManager],
})
export class LoaderComponent {
    loading$: Observable<boolean>;

    constructor(manager: LoadingManager) {
        this.loading$ = manager.loading$;
    }
}
The loader component

Each loader has its own manager, because it's in the component's providers. That's also what makes it visible to the content projected into the loader, and not just to the loader's own template (viewProviders would only reach the template). The loader itself does nothing but watch loading$.

Hiding, not removing

The content is hidden with CSS rather than taken out of the page, and it has to be. The pipes that are loading live in that content. If it were destroyed while it loaded, which is what *ngIf does to whatever it wraps, they'd unregister, the manager would say nothing is loading, the content would come back, the pipes would start loading again, and round it would go.

Hiding it has other advantages too. The page keeps its layout, the components keep their state while the next data loads, and because nothing with visibility: hidden can be clicked or focused, the area is locked. There are no double submits, and no editing something that's about to be replaced.

The loading manager

The manager keeps a list of the pipes inside its loader and whether each one is loading, and turns that into one observable: is anything loading?

import { Injectable } from '@angular/core';
import { BehaviorSubject, asapScheduler } from 'rxjs';
import { distinctUntilChanged, map, observeOn } from 'rxjs/operators';

//  Provided by each <app-loader>, and given to every pipe inside it, however deep
@Injectable()
export class LoadingManager {
    //  Every pipe inside the loader, and whether it's loading right now
    private pipes = new Map<object, boolean>();
    private count = new BehaviorSubject<number>(0);

    //  Is anything inside the loader loading?  Delivered just after change detection, so the loader
    //  can change while its content is being checked
    readonly loading$ = this.count.pipe(
        map((count) => count > 0),
        distinctUntilChanged(),
        observeOn(asapScheduler),
    );

    register(pipe: object) {
        this.pipes.set(pipe, false);
    }

    unregister(pipe: object) {
        this.pipes.delete(pipe);
        this.update();
    }

    setLoading(pipe: object, loading: boolean) {
        this.pipes.set(pipe, loading);
        this.update();
    }

    private update() {
        let count = 0;
        this.pipes.forEach((loading) => {
            if (loading) {
                count++;
            }
        });
        this.count.next(count);
    }
}
The loading manager

The count of pipes that are loading goes into a BehaviorSubject, so the loader gets the current state as soon as it subscribes. distinctUntilChanged means the loader only hears about it when the answer changes, not every time a pipe starts or finishes.

observeOn(asapScheduler) deals with the timing. The pipes report while Angular is in the middle of change detection, working through the templates. A component inside the loader is checked after the loader itself, so when it starts loading, the loader has already been drawn as not loading, and changing that straight away gives an ExpressionChangedAfterItHasBeenCheckedError in development. observeOn(asapScheduler) delivers each change just after change detection has finished instead, and Angular then checks the loader again.

The httpGet pipe

import { ChangeDetectorRef, OnDestroy, Optional, Pipe, PipeTransform } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Subscription } from 'rxjs';
import { LoadingManager } from './loading-manager';

//  'url' | httpGet fetches the URL and returns what it gets back, undefined until then, and tells the
//  nearest loader around it while it's loading
@Pipe({ name: 'httpGet', pure: false })
export class HttpGetPipe implements PipeTransform, OnDestroy {
    private url: string | undefined;
    private value: any;
    private subscription: Subscription | undefined;

    constructor(
        private http: HttpClient,
        private changeDetector: ChangeDetectorRef,
        @Optional() private manager: LoadingManager,
    ) {
        if (this.manager) {
            this.manager.register(this);
        }
    }

    transform(url: string | undefined): any {
        //  Called on every change detection, so only fetch when the URL changes
        if (url !== this.url) {
            this.url = url;
            this.load(url);
        }
        return this.value;
    }

    private load(url: string | undefined) {
        //  Cancel the last request, so an old response can't replace a newer one
        this.stop();
        if (url === undefined) {
            return;
        }
        this.setLoading(true);
        this.subscription = this.http.get(url).subscribe(
            (value) => {
                this.value = value;
                this.setLoading(false);
                this.changeDetector.markForCheck();
            },
            () => {
                this.setLoading(false);
            },
        );
    }

    private setLoading(loading: boolean) {
        if (this.manager) {
            this.manager.setLoading(this, loading);
        }
    }

    private stop() {
        if (this.subscription !== undefined) {
            this.subscription.unsubscribe();
            this.subscription = undefined;
            this.setLoading(false);
        }
    }

    ngOnDestroy() {
        this.stop();
        if (this.manager) {
            this.manager.unregister(this);
        }
    }
}
The httpGet pipe

The pipe uses its constructor to register with the manager it's been given, and ngOnDestroy to unregister. In between it tells the manager whenever it starts or finishes loading.

It's an impure pipe (pure: false), so Angular calls transform on every change detection, not just when the URL changes. That's what lets it return the value once it arrives. transform stays cheap: it compares the URL with the last one, and only fetches when it's different. If the URL changes while a request is still on its way, that request is unsubscribed, which cancels it, so an old response can never replace a newer one.

While the next URL loads, the pipe keeps returning the last value, so the content doesn't collapse behind the loader. markForCheck makes it work inside OnPush components too. And the manager is @Optional, so outside any loader the pipe still fetches, it just has nobody to tell.

Live streams

A stream from a WebSocket fits the same pattern. Until its first value arrives, it's loading; after that, each new value just updates the screen. A second pipe does this for any observable. It's the httpGet pipe with the observable passed in, in place of the URL, and it stays subscribed:

@Pipe({ name: 'live', pure: false })
export class LivePipe implements PipeTransform, OnDestroy {
    private source: Observable<any> | undefined;
...
    transform(source: Observable<any> | undefined): any {
        //  Called on every change detection, so only subscribe when the observable changes
        if (source !== this.source) {
            this.source = source;
            this.listen(source);
        }
        return this.value;
    }

    private listen(source: Observable<any> | undefined) {
        //  Stop listening to the last observable
        this.stop();
        if (source === undefined) {
            return;
        }
        this.setLoading(true);
        this.subscription = source.subscribe(
            (value) => {
                this.value = value;
                this.setLoading(false);
                this.changeDetector.markForCheck();
            },
            () => {
                this.setLoading(false);
            },
        );
    }
...
}
The live pipe, where it differs from httpGet (trimmed)
@Component({
    selector: 'app-status',
    template: `
        <app-loader>
            <p>{{ (status$ | live)?.message }}</p>
        </app-loader>
    `,
})
export class StatusComponent {
    status$ = webSocket('wss://example.com/status');
}
Showing a WebSocket stream, locked until its first message

Things to know

  • Each | httpGet in a template is its own pipe, with its own request. Use the same URL twice and it's fetched twice, so fetch it once and give it a name with as. To deal with the same request across multiple different components we actually ended up deduping requests across the application, and this had other benefits like always being able to pass just the IDs of entities into components instead of deciding where in the tree to fetch data and which components take full records vs IDs.
  • Loaders nest. A pipe reports to the nearest loader above it, so a loader around one panel locks just that panel, and the page's loader doesn't wait for it.
  • The pipe finds its manager from the element it's used on, which is how pipes get their dependencies with Ivy, the renderer Angular has used by default since version 9. That's what lets a pipe in the page's own template, inside <app-loader>, find the loader's manager. With Ivy turned off, the older View Engine gives a pipe the dependencies of the component it's in, so it only finds a loader outside that component.
  • On an error the pipe simply stops loading. The manager is the natural place to collect errors as well, so that the loader can show a message instead of the content.

Source code

The whole feature, as one Angular module. Import LoaderModule into any module that uses the loader or the pipes, and HttpClientModule once, in the application's root module. It needs Ivy, Angular's default renderer since version 9.

The loader

  • loader.module.ts TypeScript · 14 lines · the module that declares and exports the loader and the pipes
  • loader.component.ts TypeScript · 31 lines · the loader component, which hides its content and shows a spinner
  • loading-manager.ts TypeScript · 43 lines · the manager each loader provides, which counts the pipes loading

The pipes

  • http-get.pipe.ts TypeScript · 72 lines · fetches a URL from the template
  • live.pipe.ts TypeScript · 70 lines · shows the latest value from any observable, such as a WebSocket

See also