Forem: Tápai Balázs

Old browser's tale

Tápai Balázs — Wed, 30 Dec 2020 15:43:45 +0000

I have started as a software developer in late 2015. I would say it was a pretty nice time to start because there were popular frameworks out there which were making it easier to be a front-end focused developer. However, there were hardships as well. I think everybody has a story about supporting old browsers. Nowadays, most greenfield projects need to support the so-called evergreen browsers only.

These browsers are not limited to updates that are connected to OS updates. Usually, they automatically update and allow developers to adopt new technology early. However, there are still some areas where old browsers must be supported. I have been working on such a project lately, and it is especially hard to support IE11 when I only have a Mac.

IE11 is not a bad browser, but it is old and no longer supported. In 2015 I needed to support IE9 for various banking and accounting software. I know that some of you could go further telling horror stories about "ancient" times with IE8 or even IE6. The good news is that supporting IE11 is not that hard, you just have to check everything on caniuse.com. But of course, there are some funny stories that I can share with you.

The debugger was the culprit.

So here is the situation: On this project, we have a Back-End developer, a Front-End developer and a Manual Tester. The Manual Tester needed me to add some console logs to the Front-End code, so it would make their job easier to just pop up the devtools, and read the values. So, reluctantly I did that and we to developed for weeks, leaving console.log entries throughout the front-end code and testing it thoroughly in IE11... But with the devtools always open. Our tester went on vacation, and our Business Analyst took over testing the application.

What could possibly go wrong? One morning I opened the project's JIRA board, and I nearly got a small heart attack. This does not work in IE, that does not work in IE, etc. I was nervous. How could that happen? How the hell will I debug it on a Mac? And similar, sometimes more obscene questions raced through my mind. I was convinced that everything should work, so naturally, I asked our BA to please open the devtools in IE11 and let's check the console for errors or something. And everything worked like a charm.

So let's repeat it with the devtools closed. Nothing works. Open it and it works again. A quick search and the answer became pretty obvious: in IE11 the console object is only created when the devtools is open. Therefore, if it is not open it can block javascript execution.

Triggered much?

So there is an IE11 issue with forms and accented characters, which can be especially annoying with Angular reactive forms. This bug is very simple: whenever an input field has an accented character in its placeholder, IE11 fires an input event. Why is that a problem? Well, in an Angular reactive form, an input event marks the form as touched, therefore, every input field's validation error is displayed immediately.

It makes it harder when you have localisation, and you cannot be sure. Would this always occur? This is one problem I refused to hack around. I imagine that it could be done with checking the browser, the placeholder value and if it is the first input event then marking the form as untouched again. But that's just too hacky, and I don't think it would worth investing time to come up with a hacky and hard-to-understand solution.

Tyrannical buttons

I am usually very careful with using third-party libraries and UI components whenever I need to support IE11. The reason is, that most of the third-party libs never supported it or maybe just dropped support. I can't blame them, but it might make my job harder.

I was working on a project that was using a third-party UI component for displaying tabs in an application. My predecessor chose the library, however, it supported tab focusing mechanism using HTML <button> elements. It was usable, looked okay and had acceptable accessibility. The problem started when the so-called 'closable' tabs used small "X" SVG icons with click handlers inside the <button> tags. Those small "X" buttons never got the events in IE, not even the hover events.

So, I needed to remove this UI component lib, and I needed to develop the tabs from zero, using <div> elements and styling them to look exactly like the previous ones. After that, I needed to replace all the existing tab components in the application. It took several hours. I also set the tabindex property to 0 for the divs, so at least keyboard navigation works. I also added role="button" to these divs, so at least the application stayed accessible.

Please, stop using IE11

I have had my share fo cross-browser compatibility issues working as a Front-End developer in the past 5 years. These obsolete and old browsers that we need to support sometimes are huge security risks and they don't get updates anymore. That is scary, knowing, that certain banks and bureaucratic bodies still use insecure browsers and even operating systems (I saw Windows Vista during a screen share in late 2019) in their everyday work.

These projects that I work on nowadays are modernisation projects. Rewriting old software written in a very old programming language to modern web apps. These are usually greenfield projects, however, if we need to support IE11, at a certain point we won't be able to use the latest technology. IE11 support is opt-in since Angular 9 and it is just a matter of time when will it be completely dropped. Many component libraries don't even bother supporting IE11, which makes it hard to find one that will work properly after an update.

These projects also cost you a lot of money. I am confident, that updating your browsers to Microsoft Edge would be much cheaper than Front-End developers spending days investigating and fixing IE11 bugs. In my opinion, refusing to update to an evergreen browser in 2020 is not a sane business decision.

Do you have IE11 support stories? Share it with me on Twitter.

Complex UI logic in Angular - Advanced search functionality with RxJS

Tápai Balázs — Tue, 20 Oct 2020 17:16:28 +0000

In enterprise web applications, usually, there are data-grids with filters. In certain situations, you also need to enable polling in a specified interval. Recently, I have been working on a project that has such a requirement, however, the first implementation is an imperative implementation with manually unsubscribing from observables and using setInterval. Almost every week there was a bug that originated from this polling logic, and I've decided to fully refactor the code into a declarative, RxJS based solution. It was a good opportunity to write marble tests as well.

I decided to create a blog post series about certain scenarios that can be a challenge to implement. This is the first part of the series.

If you would like to jump straight into the implementation, you can check out my ng-reusables git repository.

The Requirements

The user stories look something like the following:

As a user, I'd like to be able to use the filter inputs to provide filter parameters to the search action.

When I click on the search button, and the request takes too long, I'd like to be able to stop the request. In this case, keep the already fetched data in the data-grid.

I would also like to have a select, in which I can choose an interval value. When I trigger a search, it searches by polling at the provided interval. During polling, if I change the filters the next poll will use those filters.

As a user, I'd like the search button to display 'Refresh' when there are no changes to the form.

So let's think it through and gather the problems that we need to solve.

We need a Search button which changes its text and behaviour to Stop and Refresh based on the current state.
We need a polling interval select near the search button. When we change it during polling, the interval should change accordingly.
Searching and Polling should only start when the search button gets interacted with. (clicking or pressing enter)
Whenever we search, and the response takes too long to arrive, we need the ability to stop the request.
We need to be able to cache the previous value in case an error occurs.
After a successful search, the search button should display Refresh. When the filter form changes in any way, display Search.

The action streams and their triggers

First, let's set up our template, so we can visualise it. We have two inputs in this example, a username and an email input. Then we add a select element and bind it to the pollInterval form control. All the inputs are inside a form element, which is bound to the searchForm FormGroup.

We also have a button, which gets displayed when there is a value in the searchState$ observable. This observable is going to have a default value, so the button always gets displayed. We also bind a click handler to the button. It calls triggerSearchAction() with the actual state every time it gets clicked.

<form [formGroup]="searchForm">
  <label for="username">Username</label>
  <input id="username" type="text" name="username" formControlName="username" />
  <br>
  <label for="email">email</label>
  <input id="email" type="text" name="email" formControlName="email" />
  <br>
  <div *ngIf="searchForm.get('email').hasError('email')"> Invalid e-mail address.</div>
  <br>
  <select name="pollInterval" formControlName="pollInterval">
    <option value="0">No polling</option>
    <option value="5000">5 sec</option>
    <option value="10000">10 sec</option>
  </select>

  <button *ngIf="searchState$ | async as state" (click)="triggerSearchAction(state)">
    <ng-container *ngIf="state === 'IDLE' && searchForm.dirty">Search</ng-container>
    <ng-container *ngIf="state === 'IDLE' && !searchForm.dirty">Refresh</ng-container>
    <ng-container *ngIf="state === 'SEARCH'">Stop</ng-container>
  </button>
</form>

<your-data-grid [data]="searchResults$ | async"> </your-data-grid>

We also display the different button texts in separate ng-containers. This way our button stays accessible. Whenever the state changes, only the button's text changes. The button does not get removed from the DOM, therefore, it does not lose the focus. It is rather important for keyboard-only users. Finally, we have a data-grid component, and we bind the searchResults$ observable to it as a data source.

In our component we set up the searchForm with validators to the provided controls. In the class constructor, we also call markAsdirty() on it. This way the searchState$ observable maps to IDLE and our button displays Search. Our searchStateSub is a BehaviorSubject with an initial value of IDLE. When the searchForm is not dirty, it changes the button to display Refresh. The searchAction$ observable sets the search state based on the provided action. The triggerSearchAction() method handles this logic.

type SearchTriggers = 'START' | 'STOP'
type SearchToggleStates = 'IDLE' | 'SEARCH'

interface SearchFormValue {
  username: string
  email: string
  pollInterval: number
}

@Component({
  selector: 'search-polling-example',
  template: 'search-polling-example.component.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class SearchPollingExampleComponent {
  readonly searchForm = this.formBuilder.group({
    username: ['', []],
    email: ['', [Validators.email]],
    pollInterval: [0, []],
  })

  private searchActionSub = new Subject<SearchTriggers>();
  private searchStateSub = new BehaviorSubject<SearchToggleStates>('IDLE');

  readonly searchState$: Observable<SearchToggleStates> = this.searchStateSub.asObservable();

  private readonly searchAction$: Observable<SearchTriggers> = this.searchActionSub.asObservable().pipe(
    tap((action: SearchTriggers) => {
      this.searchStateSub.next(action === 'START' ? 'SEARCH' : 'IDLE');
    })
  );

  readonly searchResults$: Observable<User[]> = this.searchAction$
    // We need to implement the search and polling mechanism here using the 'fetchData' method.
    .pipe()

  constructor(private formBuilder: FormBuilder, private userService: UserService) {
    this.searchForm.markAsDirty()
  }

  triggerSearchAction(state: SearchToggleStates): void {
    this.searchActionSub.next(state === 'IDLE' ? 'START' : 'STOP')
  }

  fetchData(formValue: SearchFormValue): Observable<User[] | null> {
    return this.userService.fetchUsers(formValue)
    .pipe(
      catchError((error) => {
        console.error(error)
        return of(null)
      })
    )
  }
}

We also implemented the fetchData method. It accepts our searchForm's values and fetches the data using the UserService. If the service returns with an error, we catch it, and we return a null value. This becomes important later when we need to fall back to a previously emitted value.

Planning the logic

With the initial logic set up, we need to implement the polling, and the circuit breaking logic. We do this in our searchResults$ observable pipe with some operator chaining. Since this logic is going to surface in other parts of the application as well, it is best to create a custom RxJS operator for it. Before we jump right into coding, let's summarise our needs and think ahead.
This is going to be a higher-order operator, and it needs our searchForm and the data-fetching method. It also needs to be able to set the search state. So our function needs at least 3 input parameters, and it needs to return a function.

type SearchTriggers = 'START' | 'STOP'
type SearchToggleStates = 'IDLE' | 'SEARCH'

export function searchPolling<T, F extends { pollInterval: number }>(
  searchForm: FormGroup,
  searchStateSub: Subject<SearchToggleStates> | ReplaySubject<SearchToggleStates> | BehaviorSubject<SearchToggleStates>,
  fetchData: (formValue: F) => Observable<T[] | null>
): (source$: Observable<SearchTriggers>) => Observable<T[]> {
  return (source$: Observable<SearchTriggers>) =>
    source$
      // Logic implementation comes here
      .pipe()
}

Our custom observable operator method should:

emit an empty array as a default value.
trigger search when the event emitted by the source is START and set the search state.
trigger polling search when the provided FromGroup's pollInterval property is not 0.
stop a running polling search when the FromGroup's pollInterval property gets set to 0.
unsubscribe from fetching the data if it takes too long to arrive.
emit the previously emitted value if a null value gets emitted. Either from the data retrieval function or when stopping a long request.
throw an error if it is used in a not intended way.

The implementation

Default value and handling misuse

These are solid test cases. Since we are creating an operator method, we can write our tests using rxjs-marbles. Let's start with writing the two easy tests. Namely, that our operator method does not get misused and that it emits an empty array as a default value. We use a hot observable stream as our source because the source observable emits values outside from it. It is an action-stream which we trigger with passing START and STOP into it. The expectation is a cold observable because the value comes from our operator.

describe(`SearchPolling Operator`, () => {
  let MOCK_FORM: FormGroup
  let MOCK_SUBJECT: ReplaySubject<any>

  beforeEach(() => {
    MOCK_FORM = new FormGroup({
      pollInterval: new FormControl(0),
    })
    MOCK_SUBJECT = new ReplaySubject(1)
  })

  it(`emits an empty array as a default value`, marbles((m) => {
      const source$ =   m.hot( '----')
      const expected$ = m.cold('x---', { x: [] })

      m.expect(
        source$.pipe(searchPolling(MOCK_FORM, MOCK_SUBJECT, (formValue: any) => of(['test'])))
      ).toBeObservable(expected$)
  }));

  it(`should throw an error if it is misused`, marbles((m) => {
    const expectedError = new Error(
      `Search Polling can only accept 'START' and 'STOP' events, but you provided 'WHATEVER'`
    )
    const source$ =   m.hot( '-a--', { a: 'WHATEVER' })
    const expected$ = m.cold('x#--', { x: [] }, expectedError)

    m.expect(
      source$.pipe(searchPolling(MOCK_FORM, MOCK_SUBJECT, (formValue: any) => of(['test'])))
    ).toBeObservable(expected$)
  }));
});

In our first test we can see, that if the action source never emits a value, the result still has an empty array as a value. In the second test, we start by emitting a WHATEVER value and in our output, we expect an error. So let's update our operator to make these tests pass.

export function searchPolling<T, F extends { pollInterval: number }>(/* ... */) {

  return (source$: Observable<SearchTriggers>) =>
    source$.pipe(
      switchMap<SearchTriggers, Observable<T[]>>((event: SearchTriggers) => {
        if (event === 'STOP') {
          // stop logic comes here
        } else if (event === 'START') {
          // search and search polling logic comes here
        } else {
          return throwError(
            new Error(`Search Polling can only accept 'START' and 'STOP' events, but you provided: '${event}'`)
          )
        }
      }),
      startWith<T[], T[]>([])
    )
}

So we use a switchMap operator to convert our event stream into a data stream. This is important because the switchMap operator unsubscribes from the previous stream. We set up the context for the STOP and START events. Inside the else branch, we throw an error. This way we make sure that other developers who use this pipe won't have to deal with errors coming from SOTP typos. Then we add the startWith operator with an empty array. This does exactly what we need, it starts the data stream with an empty array.

Simple search

Let's implement the single search and the stop mechanism now. We need to display the previous values in our data-grid when we stop a search. When the service returns with an error, our data-fetch method will catch it and return null. We also need to set the search state back to IDLE. Updating our button text requires us to call markAsPristine() on our search form as well.

// in our test file
it(`should trigger search when the event emitted by the source is 'START' and set the search state to 'IDLE'.`, marbles(m => {
  const source$ =      m.hot( '--a-', { a: 'START' });
  const searchState$ = m.hot( '--s-', { s: 'IDLE' });
  const expected$ =    m.cold('x-y-', { x: [], y: ['test'] });

  m.expect(
    source$.pipe(searchPolling(MOCK_FORM, MOCK_SUBJECT, (formValue: any) => of(['test'])))
  ).toBeObservable(expected$);
  m.expect(
    MOCK_SUBJECT.asObservable()
      .pipe(tap(_ => expect(MOCK_FORM.dirty).toBe(false)))
  ).toBeObservable(searchState$);
}));

This tests our simple search logic, so let's implement the necessary code to make the test pass. In our else if block, we call the fetchData method with the search form's value. We also pipe through it, setting the search state to IDLE. The tap operator's callback called before our startWith operator calls the markAsPristine() method. It sets the search form to pristine or 'not dirty'.

export function searchPolling<T, F extends { pollInterval: number }>(/* ... */) {
  return (source$: Observable<SearchTriggers>) =>
    source$.pipe(
      switchMap<SearchTriggers, Observable<T[]>>((event: SearchTriggers) => {
        if (event === 'STOP') {
          // stop logic comes here
        } else if (event === 'START') {
          const formData: F = searchForm.getRawValue();

          if (formData.pollInterval === 0) {
            return fetchData(formData).pipe(tap((_) => searchStateSub.next('IDLE'))
          } else {
            // polling logic implementation comes here.
          }

        } else {
          return throwError(
            new Error(`Search Polling can only accept 'START' and 'STOP' events, but you provided: '${event}'`)
          )
        }
      }),
      tap(_ => searchForm.markAsPristine()),
      startWith<T[], T[]>([])
    )
}

Fetching the data and setting the state and search states were pretty straightforward. However, we still need to implement our circuit break and caching logic. Let's write our tests first.

Stop search and cache the previous value

In the first test, we simulate a slow internet connection. For that, we use the delay operator on our mocked fetchData method. In the second test, we need a more complex method for fetching the data. The mockFetchData method uses the test's scope to increase a counter. When the counter reaches 2, it returns a null value. This simulates a network error on the third search request. The value that should get emitted must be the previous value.

// in our test file
it(`should unsubscribe from fetching the data if it takes too long to arrive and return the previously emitted value.`, marbles(m => {
  const source$ =   m.hot( '--ab', { a: 'START', b: 'STOP' });
  const expected$ = m.cold('x--x', { x: [] });

  m.expect(
    source$.pipe(
      searchPolling(
        MOCK_FORM,
        MOCK_SUBJECT,
        (formValue: any) => of(['test']).pipe(delay(200))  // simulate slow response.
      )
    )
  ).toBeObservable(expected$);
}));

it(`should emit the previous successful value, when the data fetch encounters an error and a null value is emitted`, marbles(m => {
  let counter = 0;
  const mockData = ['firstEmmit', 'secondEmmit', 'thirdEmmit']
  const mockFetchData = (formValue: any) => {
    if (counter === 2) {
      return of(null); // simulate caught error
    } else {
      const returnValue = mockData[counter]
      counter++
      return of([returnValue])
    }
  };

  const source$ =   m.hot( '--a-a-a', { a: 'START' });
  const expected$ = m.cold('x-y-z-z', { x: [], y: ['firstEmmit'], z: ['secondEmmit'] });

  m.expect(
    source$.pipe(searchPolling((MOCK_FORM, MOCK_SUBJECT, mockFetchData))
  ).toBeObservable(expected$);

}));

We've set the search state to IDLE in a tap operator, however, we do need to set it whenever we stop a search. Also, it is going to be needed when we search with polling. First, we extract it into a function scoped inside our operator method. Then emit a simple null value when a STOP event triggers the function. Since we are inside a switchMap operator, whenever a previous request takes too long, emitting a null value will unsubscribe from the previous stream.

export function searchPolling<T, F extends { pollInterval: number }>(/* ... */) {

  function setSearchStateToIdle<V>(): (s$: Observable<V>) => Observable<V> {
    return (s$) => s$.pipe(tap((_) => searchStateSub.next('IDLE')))
  }

  return (source$: Observable<SearchTriggers>) =>
    source$.pipe(
      switchMap<SearchTriggers, Observable<T[]>>((event: SearchTriggers) => {
        if (event === 'STOP') {
          return of<T[]>(null).pipe(setSearchStateToIdle())
        } else if (event === 'START') {
          const formData: F = searchForm.getRawValue()

          if (formData.pollInterval === 0) {
            return fetchData(formData).pipe(setSearchStateToIdle())
          } else {
            // polling logic implementation comes here.
          }
        } else {
          return throwError(
            new Error(`Search Polling can only accept 'START' and 'STOP' events, but you provided: '${event}'`)
          )
        }
      }),
      tap((_) => searchForm.markAsPristine()),
      startWith<T[], T[]>([]),
      scan((previous, next) => next || previous)
    )
}

The first emit always going to be an empty array. When we use the scan operator we simply check the latest emitted value. The scan operator caches previous values. If the latest value emitted is a null value, we give back the previous value. In the worst-case scenario, the previous value will always be an empty array. It also keeps the previous search results in memory.

Polling

Now we only need to implement the polling mechanism. When polling, changes in the search form should be taken into account. Whenever the pollInterval is set to zero, the polling should stop with the last request. When this occurs, the operator should unsubscribe from the search form's valueChanges observable. After emitting the last search results, the search state is set to IDLE upon the last emission.

// in our test file
it(`should trigger polling search when the provided FromGroups pollInterval property is not 0`, marbles((m) => {
  MOCK_FORM.setValue({
    pollInterval: 2,
  });
  const source$ =   m.hot( '--a------b', { a: 'START', b: 'STOP' })
  const expected$ = m.cold('x-y-y-y-yy', { x: [], y: ['test'] })

  m.expect(
    source$.pipe(
      searchPolling(MOCK_FORM, MOCK_SUBJECT, (formValue: any) => of(['test']))
    )
  ).toBeObservable(expected$)
}));

it(`should stop a running polling search when the FromGroup's pollInterval property gets set to 0`, marbles((m) => {
  MOCK_FORM.setValue({
    pollInterval: 2,
  });
  const source$ =      m.hot( '--a-------', { a: 'START' })
  const searchState$ = m.hot( '------s--', { s: 'IDLE' })
  const expected$ =    m.cold('x-y-y-y---', { x: [], y: ['test'] })

  m.expect(
    source$.pipe(
      searchPolling(MOCK_FORM, MOCK_SUBJECT, (formValue: any) => of(['test'])),
      // simulate setting the formControl on the third emmit.
      scan((previous, current, index) => {
        if (index === 2) {
          MOCK_FORM.setValue({ pollInterval: 0 })
          MOCK_FORM.updateValueAndValidity()
        }
        return current
      })
    )
  ).toBeObservable(expected$)

  m.expect(MOCK_SUBJECT.asObservable()).toBeObservable(searchState$)
}));

We finally finish the implementation with the polling logic. To make the code readable, we implement it in a separate function. In this function we subscribe to searchForm.valueChanges. We use the startWith pipe again, to emit the initialFormValue parameter. Then we use the switchMap operator to implement the polling logic. If the pollInterval is 0 we must switch to a simple observable which emits once. We can imagine how problematic it would be, if 0 was passed to a timer as the time between intervals. This can only occur when a polling search is already in progress. We stop the polling here and we set the search state to IDLE.

export function searchPolling<T, F extends { pollInterval: number }>(/* ... */) {
  // ...
  function usePolling(initialFormValue: F): Observable<T[]> {
    return searchForm.valueChanges.pipe(
      startWith<F, F>(initialFormValue),
      switchMap((formValue: F) => {
        const pollSource$: Observable<number> =
          formValue.pollInterval === 0
            ? of(0).pipe(setSearchStateToIdle())
            : timer(0, formValue.pollInterval)
        return pollSource$.pipe(map<number, F>((_) => formValue))
      }),
      switchMap(fetchData),
      takeWhile((_) => searchForm.getRawValue().pollInterval !== 0)
    )
  }
  // ...
}

When the pollInterval is greater than 0, we set a timer. Our pollSource$ observable would emit only numbers, so we map it back to the formValue. We use this to fetch the data in the next switchMap operator. Notice, that we don't set the search state to IDLE here because we need to display the text Stop on our button. And last, we unsubscribe from the valueChanges observable using the takeWhile operator. The takeWhile operator completes a stream when the provided method returns a falsy value. This enables us to prevent triggering simple searches with changing form values. This would occur after stopping the polling by setting the pollInterval to 0.

type SearchTriggers = 'START' | 'STOP'
type SearchToggleStates = 'IDLE' | 'SEARCH'

export function searchPolling<T, F extends { pollInterval: number }>(
  searchForm: FormGroup,
  searchStateSub: Subject<SearchToggleStates> | ReplaySubject<SearchToggleStates> | BehaviorSubject<SearchToggleStates>,
  fetchData: (formValue: F) => Observable<T[] | null>
): (source$: Observable<SearchTriggers>) => Observable<T[]> {
  function setSearchStateToIdle<V>(): (s$: Observable<V>) => Observable<V> {
    return (s$) => s$.pipe(tap((_) => searchStateSub.next('IDLE')))
  }

  function usePolling(initialFormValue: F): Observable<T[]> {
    return searchForm.valueChanges.pipe(
      startWith<F, F>(initialFormValue),
      switchMap((formValue: F) => {
        const pollSource$: Observable<number> =
          formValue.pollInterval === 0
            ? of(0).pipe(setSearchStateToIdle())
            : timer(0, formValue.pollInterval)
        return pollSource$.pipe(map<number, F>((_) => formValue))
      }),
      switchMap(fetchData),
      takeWhile((_) => searchForm.getRawValue().pollInterval !== 0)
    )
  }

  return (source$: Observable<SearchTriggers>) =>
    source$.pipe(
      switchMap<SearchTriggers, Observable<T[]>>((event: SearchTriggers) => {
        if (event === 'STOP') {
          return of<T[]>(null).pipe(setSearchStateToIdle())
        } else if (event === 'START') {
          const formData: F = searchForm.getRawValue()

          return formData.pollInterval === 0
            ? fetchData(formData).pipe(setSearchStateToIdle())
            : usePolling(formData)
        } else {
          return throwError(
            new Error(`Search Polling can only accept 'START' and 'STOP' events, but you provided: '${event}'`)
          )
        }
      }),
      tap((_) => searchForm.markAsPristine()),
      startWith<T[], T[]>([]),
      scan((previous, next) => next || previous)
    )
}

And inside our component, we can update the searchResults$ observable.

export class SearchPollingExampleComponent {
  //...
  readonly searchResults$: Observable<User[]> = this.searchAction$.pipe(
    searchPolling<User, SearchFormValue>(this.searchForm, this.searchStateSub, this.fetchData.bind(this))
  )
  //...
}

Conclusion

We have implemented a rather complex logic declaratively, using RxJS. I hope this coding walkthrough will help you understand how to use some RxJS operators. If this article helped you in any way, please shout out to me on Twitter or share it.

Pressing the big red button - Authorisation handling with Angular

Tápai Balázs — Tue, 29 Sep 2020 18:45:20 +0000

Although you should never leave authorisation handling to be dealt with only by the Front-End, customers usually require us to hide or disable UI elements based on roles and/or permissions. This makes up for better user experience and can make the developer's life a little monotone.

If you'd like to jump right into the code, you can check out my ng-reusables git repository. I hope you have fun!

Let's just use dependency injection

I have had the chance to work with several enterprise application Front-Ends and when it came to authorisation, usually a role-based approach got implemented. The user's roles were either provided in the JWT, which was then stored in localStorage, or sent back in the login response, and stored in indexedDb. For this blog post, it is not important how the user roles get to the Front-End, but let's state that there is an AuthorisationService, which handles this upon application startup.

@Injectable({ providedIn: "root" })
export class AuthorisationService {
  private USER_ROLES: Set<string> = new Set()

  // ...

  setRoles(roles: string[]): void {
    this.USER_ROLES = new Set(roles)
  }

  hasReadAccess(role: string): boolean {
    return this.USER_ROLES.has(`${role}_READ`)
  }

  hasWriteAccess(role: string): boolean {
    return this.USER_ROLES.has(`${role}_WRITE`)
  }
}

We intentionally store the roles in a Set, because, as opposed to an array, it is more performant to check if the user has a given access right or not.
In this particular case, the application differentiates between read and write access. Read access displays the UI element, write access allows the user to interact with it. Usually, one feature has one role, let's have a feature for pressing the big red button. This feature would have two roles for the user: BIG_RED_BUTTON_READ and BIG_RED_BUTTON_WRITE. Let's create a component for this feature.

<!-- big-red-button.component.html -->
<section *ngIf=authorisationService.hasReadAccess('BIG_RED_BUTTON')
         class="big-red-button-container">
  <button [disabled]="!authorisationService.hasWriteAccess('BIG_RED_BUTTON') || isButtonDisabled()"
          class="big-red-button">
    DO NOT PRESS
  </button>
</section>

@Component({
  selector: `big-red-button`,
  templateUrl: "./big-red-button.component.html",
  styles: [
    `
      /* styles */
    `,
  ],
})
export class BigRedButtonComponent {
  constructor(public authorisationService: AuthorisationService) {}

  isButtonDisabled(): boolean {
    let isButtonDisabled = false
    // Imagine complex boolean logic here.
    return isButtonDisabled
  }
}

Scaling problems

This approach works perfectly for such a small component, and let's be fair if our whole application is one big red button we can call it a day.
However, this method gets rather tedious and tiresome for a larger application. This approach is not scalable, because you have to inject the service into each and every one of your components. That means stubbing it in every component unit test, setting it up with mock data, and mocking the user rights as well. This also goes against the DRY (Don't Repeat Yourself) principle. How can we move the necessary logic into our component templates? The answer lies in structural directives.

@Directive({ selector: "[authorisation]" })
export class AuthorisationDirective implements OnDestroy {
  private userSubscription: Subscription
  private role: string

  constructor(
    private userService: UserService,
    private authorisationService: AuthorisationService
  ) {
    this.userSubscription = this.userService.currentUser$.subscribe(
      this.updateView.bind(this)
    )
  }

  @Input()
  set authorisation(role: string) {
    this.role = role
    this.updateView()
  }

  ngOnDestroy(): void {
    this.userSubscription?.unsubscribe()
  }

  updateView(): void {
    // TODO view update logic based on access rights.
  }
}

This is our starting directive, which we are going to expand upon. I inject two services, the UserService handles the user data. When the current user changes, we need to update our views, that is why we subscribe to the user changes. Whenever a change occurs, every active directive instance
will update their view. We implement the OnDestroy lifecycle hook because directives use those as well. We handle the teardown logic inside it.
The authorisation setter gets decorated with the @Input decorator. This way we can use this structural directive on any HTML element in our templates as the following: <div *authorisation="BIG_RED_BUTTON"></div>.

With this setup, we can start implementing the view handling logic. We are going to need two important Angular template handler tools, the ViewContainerRef and the TemplateRef. Let's inject these to our constructor and implement the display/hide logic for read access rights and provide a solution for disabling UI elements when the user does not have write access right.

interface AuthorisationContext {
  $implicit: (b: boolean) => boolean
}

@Directive({ selector: "[authorisation]" })
export class AuthorisationDirective implements OnDestroy {
  // ...
  private viewRef: EmbeddedViewRef<AuthorisationContext> = null

  constructor(
    private userService: UserService,
    private authorisationService: AuthorisationService,
    @Inject(ViewContainerRef) private viewContainer: ViewContainerRef,
    @Inject(TemplateRef) private templateRef: TemplateRef<AuthorisationContext>
  ) {
    //..
  }

  // ..

  private updateView(): void {
    const hasReadRight = this.authService.hasReadAccess(this.role)
    if (hasReadRight) {
      const hasWriteRight = this.authService.hasWriteAccess(this.role)
      this.viewContainer.clear()
      this.viewRef = this.viewContainer.createEmbeddedView(
        this.templateRef,
        this.createContext(hasWriteRight)
      )
    } else {
      this.viewContainer.clear()
      this.viewRef = null
    }
  }

  private createContext(hasWriteRight: boolean): AuthorisationContext {
    return {
      $implicit: (booleanValue: boolean) => !hasWriteRight || booleanValue,
    }
  }
}

First, we declare the AuthorisationContext interface. It has an $implicit property, which comes in handy when we want to use it as a template variable. We also prepare the viewRef member property, which stores our EmbeddedViewRef or null if the user does not have read access.
Then, we call the clear() method on our ViewContainerRef instance. When the user has read access, we call clear() again. This comes in handy when the authorisation setter gets called with a different role for which we need to update the previous view. After that, we create our EmbeddedViewRef using the template reference that we inject into our constructor, and we create our context. Now let's update our component, so it uses our directive.

<!-- big-red-button.component.html -->
<section
  *authorisation="'BIG_RED_BUTTON'; let checkWriteAccess"
  class="big-red-button-container"
>
  <button
    [disabled]="checkWriteAccess(isButtonDisabled())"
    class="big-red-button"
  >
    DO NOT PRESS
  </button>
</section>

@Component({
  selector: `big-red-button`,
  templateUrl: "./big-red-button.component.html",
  styles: [
    `
      /* styles */
    `,
  ],
})
export class BigRedButtonComponent {
  constructor() {}

  isButtonDisabled(): boolean {
    let isButtonDisabled = false
    // IMAGINE COMPLEX BOOLEAN LOGIC HERE
    return isButtonDisabled
  }
}

Our directive deals with the DOM, it manipulates it. This is the reason why we use the asterisk(*) prefix. It means that this directive is a structural directive and as such, Angular internally translates the *authorisation attribute into an <ng-template> element, wrapped around the host element. Finally, our rendered <section> element looks like the following:

<!--bindings={
  "ng-reflect-authorisation": "BIG_RED_BUTTON"
}-->
<section _ngcontent-c0 class="big-red-button-container">
  <!-- ommited -->
</section>

With this solution, we successfully reduced the complexity of our component, and we created a scalable and reusable solution. It is important to mention, that the directive should be declared on the application root level, and it needs to be exported. I suggest putting this into a shared
module. Also, it is important to emphasize, that this is only a Front-End solution, this does not protect your API endpoints from unauthorised access.

What about reactive forms?

An excellent question! While the [disabled]="checkWriteAccess(isButtonDisabled())" works well on buttons, and on template-driven forms, it
can cause problems with reactive form inputs. Namely, binding to the [disabled] attribute can cause 'changed after checked' errors. Angular itself warns about this, and recommends using the .disable() and .enable() methods on form controls. Luckily, we can enhance our directive with the capability to store a FormControl if passed, and disable it when updateView is called.

@Directive({ selector: "[authorisation]" })
export class AuthorisationDirective implements OnDestroy {
  private formControl: AbstractControl = null

  // ...

  @Input()
  set authorisationControl(ctrl: AbstractControl) {
    this.formControl = ctrl
    this.updateView()
  }

  // ...

  private updateView(): void {
    const hasReadRight = this.authService.hasReadAccess(this.role)
    if (hasReadRight) {
      const hasWriteRight = this.authService.hasWriteAccess(this.role)
      this.viewContainer.clear()
      this.viewRef = this.viewContainer.createEmbeddedView(
        this.templateRef,
        this.createContext(hasWriteRight)
      )
      if (!hasWriteRight) {
        this.formControl?.disable()
      }
    } else {
      this.viewContainer.clear()
      this.viewRef = null
    }
  }
}

We have added a new @Input() property to our directive. This allows us to pass any control that implements the AbstractControl, such as FormControl, FormGroup and FormArray. We can leverage this using the following directive binding:

<!-- launch-codes.component.html -->
<form
  *authorisation="'LAUNCH_CODE_INPUTS'; control launchCodesForm"
  [formGroup]="launchCodesForm"
>
  <label for="primary-high-ranking-officer">First officer access code:</label>
  <input
    id="primary-high-ranking-officer"
    formControlName="firstOfficerAccessCode"
  />

  <label for="secondary-high-ranking-officer"
    >Second officer access code:</label
  >
  <input
    id="secondary-high-ranking-officer"
    formControlName="secondOfficerAccessCode"
  />
</form>

@Component({
  selector: "launch-codes",
  templateUrl: "./launch-codes.component.html",
})
export class LaunchCodesComponent {
  readonly launchCodesForm: FormGroup = this.fb.group({
    firstOfficerAccessCode: ["", Validators.required],
    secondOfficerAccessCode: ["", Validators.required],
  })

  constructor(private fb: FormBuilder) {}
}

This way when the launchCodesForm is disabled if the user does not have write access.

We need more fancy

So the authorisation logic works, the button gets disabled when the user does not have write right, however, our customer wants something extra.
The goal is to make read-only components differ from full-access components. For the sake of simplicity, in this example we are going to add some opacity to these elements, so they can still be read, but they differ visibly. Let's create the CSS class first.

/* styles.css file */
.app-unauthorised {
  opacity: 0.5 !important;
}

Now, we could easily add [class.app-unauthorised]="checkWriteAccess(false) to our template, but then again, we would need to do this to every element, which has our directive on it. We don't want that, it would not be DRY... Instead, we could use a little DOM manipulation with the help of the ElementRef. Since we want to manipulate the DOM, we inject the Renderer2 as well. Let's update our directive.

@Directive({ selector: "[authorisation]" })
export class AuthorisationDirective implements OnDestroy {
  // ...

  constructor(
    private userService: UserService,
    private authorisationService: AuthorisationService,
    @Inject(ViewContainerRef) private viewContainer: ViewContainerRef,
    @Inject(TemplateRef) private templateRef: TemplateRef<AuthorisationContext>,
    @Inject(ElementRef) private el: ElementRef,
    private renderer: Renderer2,
  ) {
    //..
  }

  // ..

  private updateView(): void {
    const hasReadRight = this.authService.hasReadAccess(this.role)
    if (hasReadRight) {
      const hasWriteRight = this.authService.hasWriteAccess(this.role)
      this.viewContainer.clear()
      this.viewRef = this.viewContainer.createEmbeddedView(
        this.templateRef,
        this.createContext(hasWriteRight)
      )
      if (!hasWriteRight) {
        this.formControl?.disable()
        this.setUnauthorised()
      }
    } else {
      this.viewContainer.clear()
      this.viewRef = null
    }
  }

  // ...

  private setUnauthorised(): void {
    this.renderer.addClass(this.el.nativeElement.previousSibling, 'app-unauthorised');
  }
}

First, we inject the ElementRef into our directive. When the user has only read rights, the app-unauthorised class gets added to our nativeElement's previousSibling. The reason for this is that this kind of directive binding gets converted into an HTML comment in the template as mentioned before. The previous sibling is the element that you apply the structural directive to. Note, that if you use structural directives, like *ngIf, you can see  in production built
Angular applications. This is the reason why we cannot bind more than one structural directive to an element, therefore, if we'd like to use this authorisation directive with an *ngIf structural directive as well, we should wrap the element inside an <ng-container> and apply one of the structural directives onto that container element.

Conclusion

Authorisation handling on the UI can be a tedious job, especially when it is one of the last things to implement in an application. I hope this article has shed some light on how you can use the power of directives in your app to make your job easier.

Angular's async pipe and performance - a code walk-through

Tápai Balázs — Thu, 27 Aug 2020 17:04:07 +0000

The Angular async pipe is the cornerstone of making applications performant. How exactly does it work? Let's walk through the code together to understand it.

If you have ever searched for articles about Angular applications and performance, you have read about OnPush change detection. A lot of people jump right into using it, however, I see a tendency of using object mutation for manipulating data and relying on the Default change detection strategy. Usually, when an application is built on object mutation, changing to OnPush change detection breaks the application. There are usually two solutions, one is to revert to using the Default change detection strategy, the other one is injecting the ChangeDetectorRef to every component where a subscription occurs and call its markForCheck() method at the end of the callback function.

Using the Default change detection strategy in these cases won't increase performance, injecting the ChangeDetectorRef into every component can be rather cumbersome and obnoxious. However, you can avoid it with RxJS, and the async pipe.

Data composition is important

I have met with the phenomena of subscribing to an Observable inside a component and saving the result into a class member property. You might be familiar with this structure as well:

// ...
data: Data[] = [];

constructor(private http: HttpClient) {}

ngOnInit(): void {
  this.http.get(`some/url`).subscribe(result => {
    this.data = result;
  })
}

Instead of assigning to the data property of your component class, you could (and in my humble opinion should) use the async pipe in your template, to subscribe to the observable, and it would handle unsubscribing for you.

{{ data$ | async }}
// ts

data$ = this.http.get(`some/url`);

How does the async pipe work?

@Pipe({name: 'async', pure: false})
export class AsyncPipe implements OnDestroy, PipeTransform {
// ...
}

The Angular async pipe is not pure. Whenever a pipe has an internal state the pure property of the @Pipe() decorator config should be set to false. This means, that the transform() method of the pipe gets invoked on every change-detection cycle. Since the async pipe usually deals with Observable or Promise inputs, the pipe itself has an internal state for storing the last value. However, to properly handle the teardown logic and to avoid memory leaks, the Subscription, the source (_obj) and the SubscriptionStrategy are stored in memory as well.

// ...
  private _latestValue: any = null;

  private _subscription: SubscriptionLike|Promise<any>|null = null;
  private _obj: Observable<any>|Promise<any>|EventEmitter<any>|null = null;
  private _strategy: SubscriptionStrategy = null!;

  constructor(private _ref: ChangeDetectorRef) {}

//...

As you can see, the ChangeDetectorRef is injected into every async pipe instance, but more on that later. First, let's check the SubscriptionStrategy interface. The classes that implement this interface must have the following methods: createSubscription, dispose and onDestroy. The first creates the subscription, dispose and onDestroy are responsible for handling the teardown logic, so memory leaks can be avoided.

interface SubscriptionStrategy {
  createSubscription(async: Observable<any>|Promise<any>, updateLatestValue: any): SubscriptionLike | Promise<any>;
  dispose(subscription: SubscriptionLike|Promise<any>): void;
  onDestroy(subscription: SubscriptionLike|Promise<any>): void;
}

class ObservableStrategy implements SubscriptionStrategy {
  createSubscription(async: Observable<any>, updateLatestValue: any): SubscriptionLike {
    return async.subscribe({
      next: updateLatestValue,
      error: (e: any) => {
        throw e;
      }
    });
  }

  dispose(subscription: SubscriptionLike): void {
    subscription.unsubscribe();
  }

  onDestroy(subscription: SubscriptionLike): void {
    subscription.unsubscribe();
  }
}

class PromiseStrategy implements SubscriptionStrategy {
  createSubscription(async: Promise<any>, updateLatestValue: (v: any) => any): Promise<any> {
    return async.then(updateLatestValue, e => {
      throw e;
    });
  }

  dispose(subscription: Promise<any>): void {}

  onDestroy(subscription: Promise<any>): void {}
}

const _promiseStrategy = new PromiseStrategy();
const _observableStrategy = new ObservableStrategy();

// ... Pipe class declaration

The ObservableStartegy and the PromiseStrategy classes are wrappers around the logic that needs to be handled. While the dispose and onDestroy methods for Promise handling are void methods, the Observable strategy calls .unsubscribe() in both of those methods. Although, the onDestroy method never gets called in the async_pipe.ts file the dispose method handles unsubscribing.

@Pipe({name: 'async', pure: false})
export class AsyncPipe implements OnDestroy, PipeTransform {

// ...

  ngOnDestroy(): void {
    if (this._subscription) {
      this._dispose();
    }
  }

// ...

  private _dispose(): void {
    this._strategy.dispose(this._subscription!);
    this._latestValue = null;
    this._subscription = null;
    this._obj = null;
  }

// ...
}

As it shows, the async pipe implements the OnDestroy lifecycle hook, and if there is a subscription stored in the instance, it calls the internal _dispose() method. This method calls dispose on the internally stored _strategy, and sets everything to null. When this occurs, the JS engine's garbage collector will deal with the rest.

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

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

    return this._latestValue;
  }

// ...

The transform() method always returns the internally stored _latestValue, therefore whenever an async pipe is used, the first value is always null. The first time the method gets called, and the provided parameter is neither null nor undefined, a subscription occurs. This internal _subscribe method handles a couple of things. It saves the reference of the pipe's target, then selects the proper strategy for it via the Angular internal ɵisPromise and ɵisObservable helper functions.

  private _subscribe(obj: Observable<any>|Promise<any>|EventEmitter<any>): void {
    this._obj = obj;
    this._strategy = this._selectStrategy(obj);
    this._subscription = this._strategy.createSubscription(
        obj, (value: Object) => this._updateLatestValue(obj, value));
  }

  private _selectStrategy(obj: Observable<any>|Promise<any>|EventEmitter<any>): any {
    if (ɵisPromise(obj)) {
      return _promiseStrategy;
    }

    if (ɵisObservable(obj)) {
      return _observableStrategy;
    }

    throw invalidPipeArgumentError(AsyncPipe, obj);
  }

Finally, it saves the subscription by creating it with the createSubscription method, providing the internal _updateLatestValue callback method. This method checks if the internally stored Observable and the passed Observable are the same and have the same reference. If they are, the _latestValue is updated, and the ChangeDetectorRef's markForCheck() method gets called, triggering a change detection when the subscribed Observable emits a new value. This is the part, where using RxJS and the async pipe handles using the OnPush change detection strategy.

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

That is not all, since the pipe's target can be a new Observable instance as well. Since Observables are objects, they are passed by reference. Therefore, whenever you assign a new observable to a member property, the transform method runs recursively.

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

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

    return this._latestValue;
  }

// ...

You'll notice, when there is an existing subscription, the internally stored and target Observables are checked against each other, and if they differ by reference, the old (internally stored) Observable gets disposed, and the transform method gets called recursively to create a new subscription.

Example in action

Let's create a component with two timers. One timer should emit every 2 seconds, and it should use the async pipe, the other one should emit every second, but it should use object mutation. For now, let's use the default change detection strategy.

@Component({
  selector: 'app-test',
  template: `
  <div> Timer 1: {{ timer1$ | async }} </div>
  <div> Timer 2: {{ timer2 }} </div>
  `
})
export class TestComponent {
  timer1$ = timer(0, 2000);

  timer2 = 0

  constructor() {
    timer(0, 1000).subscribe((count) => {
      timer2 = count;
    })
  }
}

When using the Default change detection strategy, you can see that timer2 gets increased by 1 every second, and timer1$ with the async pipe gets increased by 1 every two seconds. Now let's switch to OnPush change detection, by adding changeDetection: ChangeDetectionStrategy.OnPush to the component decorator.

Now the timer2 binding gets increased by 2 every 2 seconds, and the timer1$ behaves the same way as before, namely, it gets increased by 1 every 2 seconds. Why does timer2 get increased when timer1$ emits? Because the async pipe triggers change detection. If you comment out the {{ timer$1 | async }} part from the template, you can observe that nothing gets updated.

Conclusion

Using the async pipe and understanding how it works allows us to write better-performing applications. When you use OnPush change detection, Angular can work more efficiently, because it does not have to watch for object mutation. In these cases, RxJS and data composition can help you in making reactive and performant applications.

Small mistakes, huge lessons

Tápai Balázs — Wed, 03 Jun 2020 09:38:53 +0000

Everybody makes mistakes because we are human. However, making a mistake is not necessarily a bad thing. The best kind of mistake is the kind which enables you to learn something. When that happens, usually an A-HA moment occurs. Some of these moments come from small mistakes which cause trouble. I have recently had the chance to make some mistakes, and even though they were small they caused quite a scare. But, I have learnt from them and I'd like to share them, so others might learn from it.

Photo by Kevin Ku on Unsplash

process.env.SURPRISE

One of my recent projects required me to develop a full-stack application using Angular on the front-end and Node on the back-end. I chose NestJS as my back-end framework, and I loved every moment of using it. The application used PostgreSQL as its database and we've decided to use typeOrm for speeding up the process.

Everything worked fine, the typeOrm configuration came from environment variables, but to make local development easier, the environment.ts file was populated with the sync parameter set to false. However, after some time, when there were some changes in the DB schemas, suddenly the deployed application did not start.

We restarted the deploy process a couple of times, and we added more and more debug logs to the application. We realised that our API could not start because typeOrm tried to do changes in the DB but it failed. So everything pointed to mistakes made in the dev.env file. The file contained the following:

// ...
TYPEORM_SYNC=false

Boy, I was confused! Then I put a debug log into the application to log the configuration. That is when I saw that the typeOrm configuration had the sync property equal 'false'. Yes, as you can see it was a string, which was truthy. After a huge facepalm and a proper parsing of the environment variables, the deploy worked again.

Lesson learned: Log the non-sensitive configurations in debug mode in a development environment, so you can understand parse errors from the logs and process.env parses values as strings. Since this issue, I always double-check these variables.

It works in Chrome

I don't mean to sound old, but some of you will never know the struggle of hardcore cross-browser compatibility issues. I had the "luck" to work on projects which needed to support IE9, but not for long. It wasn't easy, but we've managed. Several years (and projects) later I am lucky to live in a world of evergreen browsers. Which is good, because caniuse.com is a great source of information, and the ever-changing browsers usually support the cool stuff which makes our jobs easy.

Maybe that is why this mistake I made took a toll on me. I am a huge fan of testing. I do my best to write automated unit tests and test my apps at least on a functional level using Cypress. But I develop mostly on Chrome, and since most of my projects were enterprise applications for back-office users, browser compatibility did not matter that much. I always knew that what I do in Chrome will work in Firefox. I knew this because in the previous years I have checked every edge case that indicated, that something works differently in Firefox. Also, the requirements always state that Chrome is a must.

So here's what happened. I have worked on a public-facing application with my colleagues. We did extensive unit testing and Cypress functional testing. A lot. I'm not kidding, we have even thought about introducing screenshot comparator tests. Then we've released it. And the customer sent us an angry e-mail telling us that it looks extremely ugly...

On Safari. Some parts of our code used flex: 1 1 0 and those parts were broken on Safari. I have a Macbook pro, and I made the mistake of not opening our application even once in one of the evergreen browsers.

You can imagine, our customer was quite angry. It was pure luck that it was an easy fix, but I have decided that never again should this mistake occur. Every time a change has been made on the UI, I manually open it in Safari. I even plan to buy myself an iPhone just to be able to test it natively.

Check the tooling

I have recently been asked to consult on a project with an Angular Front-End. Before the NDA I was told that the app is in Angular 9. So when I was able to check out the project I noticed that something was off. The project itself was not in good shape, and all the tests were missing. Well, not all, there were 15 unit tests generated with components, and they were all failing.

So naturally, my first task was to plug in the linter, so formatting the code would at least give me some perspective of the type of errors I might face in the future. At that point I saw in the package.json that the angular version was indeed 9.0.0, however, all the tooling was still on 8.x.x... So what could go wrong, right? I updated the tooling to leverage it, and I saw that everything works. The project starts up in serve mode, so after carefully double-checking everything I committed and pushed.

Then the build pipeline broke and the console filled with ngcc errors. So after the initial scare, and thinking about reverting immediately I took a deep breath, carefully read the error description and started googling. The angular documentation helped me out again. At the 'Opting out of Ivy in version 9' section I found the flag that fixed all my problems:

{
  "angularCompilerOptions": {
    "enableIvy": false
  }
}

I am glad Angular comes with fallback for projects that don't have their workflows set up to follow standards. So I have learned an important lesson. Whenever I play around with the package.json (or anything really) in a new project, first I must run everything according to the project's build setup.

Thinking in the fourth dimension, or at least with timezones

"Marty! You're not thinking fourth-dimensionally!"

While I love movies with time travel, I am usually terrified of date/time issues in production. Recently we have developed a food ordering web application for a client. The rule was to display next week's schedule after Friday 14:00. Not a hard thing, it could be done with a few lines of code and since on the back-end, I didn't have to care about bundle size that much, I even used momentjs to make my job easier.

So the logic got implemented, with lots of unit tests and Cypress tests. Using cy.clock() was fun, so we could even test scenarios involving the first week of next year, and the same with a leap year, etc. So everything worked, and the tests ran on the CI pipeline as well.

Then came the production release on a Monday. We've eagerly waited until Friday 14:00, and we've checked if the menu would change properly. At Friday 14:00 nothing happened, it did not change. Boy, we got scared, because that meant that people can still order food items that should not be available. It worked on our development environment properly, and the tests were running still. So what went wrong?

At Friday 16:00 the next schedule appeared. We've started checking the logs. It took some time putting 2 and 2 together and noticing that the production logs are 2 hours before the actual time. Well, my local time to be precise. The production server was in GMT timezone, and everything else was in CEST.

My big take-away is that I should always check the server time, and when the server starts up, log it properly, but most importantly:

Keep an environment as close to the production environment as possible. Make it a shadow environment, it could be useful to use a database with similar data to production. You can make a backup and anonymise the data if you work with sensitive information. But keep a prod-like environment, so you can catch errors before you deploy.

I hope you like my stories, and if you face a similar problem, learn from my mistakes. Do you have similar stories? Let me know!

I'm in a Pickle - Configuring Gherkin with NX Workspaces

Tápai Balázs — Sat, 18 Apr 2020 09:59:37 +0000

Why NX?

I believe, that every project should start with a proper development environment setup. NX does that or at least gives us a head-start. When you generate a project in a monorepo structure, it provides you with very good tools already set up. I encourage you to try it out, it has helped me deliver well tested and stable code for short deadlines. By default, it sets up Jest as the unit test framework, and it also generates a well set up cypress test environment for every front-end project.

However, there comes a time, when you encounter a project, where the client has been using Selenium driven e2e tests with Gherkin
as their test language. There is a good reason for that because Gherkin is the format for cucumber specifications. It is a language abstraction which helps you to describe business behaviour without the need to go into details of the implementation. This text acts as documentation, and a skeleton for your automated tests. Although, setting it up inside an NX workspace might require some effort.

Set up Gherkin

Cypress uses JavaScript for writing the test cases, but NX ships it with nice TypeScript support. We would like to support Gherkin, therefore, we need to install cypress-cucumber-preprocessor as a dev dependency.

npm install cypress-cucumber-preprocessor cucumber-html-reporter --save-dev

With the packages installed, let's set up a configuration file in our root folder, so let's add the cypress-cucumber-preprocessor.config.js file to our root folder. We set up our universe config, so each of our cypress tests will look for their step definitions in their respective folders.

const path = require("path")

const stepDefinitionsPath = path.resolve(process.cwd(), "./src/integration")
const outputFolder = path.resolve(process.cwd(), "../../cyreport/cucumber-json")

module.exports = {
  nonGlobalStepDefinitions: true,
  stepDefinitions: stepDefinitionsPath,
  cucumberJson: {
    generate: true,
    outputFolder: outputFolder,
    filePrefix: "",
    fileSuffix: ".cucumber",
  },
}

It is important that this file had the .config.js ending, otherwise, your step definitions will not be found. Notice, that we have configured the stepDefinitionPath variable, so it looks for the feature files from the current working directory. This is important because that is going to be the folder from where cypress is going to run. We created an outputFolder variable as well because we are going to need it to generate our cucumber-json file for our reports, but more on that later. Finally, we export our universe config, with setting the nonGlobalStepDefinitions property to true. We do this because we want our step definitions to be under the {your_e2e_folder}/integration/common folder.

Migrate our tests

A freshly generated NX e2e project uses the following folder structure:

project-e2e
|_src
| |_fixtures
| | |_example.json
| |_integration
| | |_app.spec.ts
| |_plugins
| | |_index.js
| |_support
| | |_app.po.ts
| | |_commands.ts
| | |_index.ts
|_cypress.json
|_tsconfig.e2e.json
|_tsconfig.json
|_tslint.json

The default test looks like the following:

// app.po.ts
export const getGreeting = () => cy.get("h1")

// app.spec.ts
import { getGreeting } from "../support/app.po"

describe("sandbox", () => {
  beforeEach(() => cy.visit("/"))

  it("should display welcome message", () => {
    // Custom command example, see `../support/commands.ts` file
    cy.login("my-email@something.com", "myPassword")

    // Function helper example, see `../support/app.po.ts` file
    getGreeting().contains("Welcome to app!")
  })
})

What does this test do? Before every test, the application is opened at the / url. The cy.login() method is a custom command added in the commands.ts file. It simulates a login step. Then finally, checks if the page displays Welcome to app! inside an h1 HTML tag. Let's implement the same in Gherkin. We can delete the app.spec.ts and the app.po.ts files and create a Landing.feature file with the following content:

Feature: Landing page

Scenario: The application displays the welcome message.
  Given the user is logged in
  Then the "Welcome to app!" message is displayed

We create two folders near our feature file, the Landing and the common. The common folder contains our shared steps, the Landing folder deals with the feature-specific steps. Make sure that you use the same name for these steps as you use for your .feature file. In the common/common.steps.ts, add the following:

import { Before } from "cypress-cucumber-preprocessor/steps"

Before(() => {
  cy.server()
})

This will make sure, that we can stub requests in steps. Be careful though, the order of the steps matters. In our Landing/landing.steps.ts file, we add our Given and Then steps.

import { Before, Given, Then } from "cypress-cucumber-preprocessor/steps"

Before(() => {
  cy.visit("/")
})

Given("the user is logged in", () => {
  cy.login("my-email@something.com", "myPassword")
})

Then("the {string} message is displayed", (message: string) => {
  cy.get("h1").contains(message)
})

Preprocessed Pickles

Our roughly-the-same test case is ready, however, we still cannot run our tests. Our cypress runner is not-yet set up for processing .feature files, and it still expects only typescript files as test sources. We need to update our cypress configuration. Let's update our cypress.json first:

{
  "fileServerFolder": ".",
  "fixturesFolder": "./src/fixtures",
  "integrationFolder": "./src/integration",
  "modifyObstructiveCode": false,
  "pluginsFile": "./src/plugins/index",
  "supportFile": "./src/support/index.ts",
  "video": true,
  "videosFolder": "../../dist/cypress/apps/sandbox-e2e/videos",
  "screenshotsFolder": "../../dist/cypress/apps/sandbox-e2e/screenshots",
  "chromeWebSecurity": false,
  "testFiles": "**/*.{feature,features}"
}

We also need to update our cypress plugins file. Let's open the plugins/index.js file and replace its contents with the following:

Update (2021.02.02.)
_As of Cypress v4.4.0, TypeScript is supported out-of-the-box.

const browserify = require('@cypress/browserify-preprocessor');
const cucumber = require('cypress-cucumber-preprocessor').default;
const resolve = require('resolve');

module.exports = (on, config) => {
  const options = {
    ...browserify.defaultOptions,
    typescript: resolve.sync('typescript', { baseDir: config.projectRoot }),
  };

  on('file:preprocessor', cucumber(options));
};

We don't want to override the existing typescript compilation solution provided by our NX workspace, we just want to extend it. We add two loaders, one for .feature files and one for .features files. In the cypress plugin setup method that we export we need to make some changes. Our webpackConfig needs to set the node options to 'empty', so compilation does not throw node-specific errors. We push our feature configurations into the rules, and we set the preprocessor to use our new config.

Now if you run your cypress tests with npm run e2e it uses Gherkin. One note though, if you are used to tag-based test running with CucumberJS that does not work well in an NX workspace. At least I have not found a proper way to pass the TAGS environment variables in the command line. That said, all the debugging capabilities are present if you open cypress in their application, you can select your tests, and you can debug them easily.

However, If anybody can provide a good solution for tags, I'm open to suggestions.

Lt. Pickle reports for duty

One of the reasons to use cucumber is human-readable test cases. When your Product Owner wants to validate properly how a feature set works you can present them with cool Cucumber test run reports. In our initial config setup, we have already added configuration to generate a cypress report with a cucumber.json file. We just need to add a tool to generate a nice report. Let's create a generate-cucumber-report.js file in our tools folder:

const path = require("path")
const reporter = require("cucumber-html-reporter")
const chalk = require("chalk")

const options = {
  theme: "bootstrap",
  jsonDir: path.join(process.cwd(), "cyreport/cucumber-json"),
  output: path.join(process.cwd(), "cyreport/cucumber_report.html"),
  reportSuiteAsScenarios: true,
  scenarioTimestamp: true,
  launchReport: false,
  storeScreenshots: true,
  noInlineScreenshots: false,
}

try {
  reporter.generate(options)
} catch (e) {
  console.log(chalk.red(`Could not generate cypress reports`))
  console.log(chalk.red(`${e}`))
}

We put the whole report generator method into a try-catch, because if we run our e2e tests in the affected mode, sometimes they won't run, and report generation would break our build pipeline. Let's update our package.json to run this generator script.

{
  "scripts": {
    "devtools:cucumber:report": "node ./tools/generate-cucumber-report.js"
  }
}

After running your e2e tests, running npm run devtools:cucumber:report in the terminal would generate a report. We can find it in the cyreport folder.

This guide could not have been written without several hours of reading GitHub issues. I'd like to thank the open-source community for creating these awesome tools, and for documenting them properly. Huge thanks for the people who found solutions and workarounds and comment them on GitHub issues. I wanted to document my final solution, so it might help others in the future.

You can read the original article here

The Butler did it! Jenkins/JIRA tricks and tips

Tápai Balázs — Mon, 23 Mar 2020 19:09:19 +0000

1. Automatic fixVersions in JIRA

We use Bitbucket and Jira. Pretty much awesome Atlassian products, rather common at companies.

Our process requires developers to move JIRA tickets from the To Do column to the Ready for demo column and eventually move them to the Done column. The development process is pretty much straightforward. When you start working on a story you can create a branch from your terminal. If you make sure that the branch name contains the issue ID, when you push that branch up to the remote repository, even without changes, JIRA can automatically move it to the In Progress column. When we open a pull-request, JIRA automatically moves the ticket to the Code Review column, and after merging it moves to the Exploratory column where another developer or a tester checks the functionality, confirms that the acceptance criteria are met and everything is fine.
From there we move it to the Ready for demo column, and at the end of the iteration, we demo the changes. If they are accepted by the Product Owner they are moved to the done column and we can trigger a release build.

Now the only thing not automated in that process is that we do our releases using the JIRA versions feature. When the release build runs successfully it tags the actual commit with that version registered in JIRA. The problem is that we are developers and we are lazy. We always forgot to add the last unreleased version to the stories that we worked on.

And in rare cases when we didn't forget it, it happened that the unreleased version of in-progress tickets was released and we needed to change that manually to add the new fixVersion. This was unacceptable, and since I happen to be a developer who can do something about it, I took it upon myself to automate this task, using the Jira Steps Plugin and tweak our Jenkinsfile for pull requests. So let's check how to do it.

At the top of the Jenkinsfile, we need to set up some methods and variables. We work on the front-end of our application, therefore, our release versions always start with FE, such as FE-2.3.12. So first we get the project versions, and then we use some groovy magic to get the only unreleased version which contains FE in its name. Finally, we apply the result to a variable.

def getFrontEndReleaseVersions() {
  def versions = jiraGetProjectVersions idOrKey: 'YOUR-PROJECT-KEY', site: 'YOUR-CONFIGURED-JIRA-SITE'
  return versions.data.findAll { it.released == false && it.name.contains('FE') }
}

FE_RELEASE_VERSIONS = getFrontEndReleaseVersions()

So the FE_RELEASE_VERSIONS variable now contains a list of version objects. Well, a list of exactly one version object. Then, when we start our build, before checkout we run a script in a try-catch block. The reason why it is inside a try-catch block is that if whenever the JIRA site goes down but the build runs, the build won't fail.

pipeline {
  // ...
  stages {
    steps {
      script {
        try {
          def issuekey = (GIT_BRANCH.toUpperCase() =~ /JIRAPROJECTID-\d*/)[0]

          def editedIssue = [fields: [fixVersions: [FE_RELEASE_VERSIONS.first()]]]

          def response = jiraEditIssue idOrKey: issuekey, issue: editedIssue, site: 'YOUR-CONFIGURED-JIRA-SITE'

          echo response.successful.toString()
          echo response.data.toString()
        } catch (Exception e) {
          echo "Could not update fixVersions. Please do it manually"
        }
      }
    }

    // ...
  }
}

First we call .toUpperCase() on the GIT_BRANCH variable. This is because some of our developers like to create their branches from the terminal. They are usually too lazy to press shift when writing the JIRA issue number into the branch name. After that, we use the =~ operator to extract a substring using the following regex: /JIRAPROJECTID-\d*/. Use your own project's letters and it should work for you. The operator returns an array of matches and we get the first one using bracket notation. After that, we define a variable with the fields that we want to change in our JIRA issue. And finally, we use the jiraEditIssue to update it in our JIRA.

2. Affected pipeline for PR builds

Another project that I work on is a rare delicacy. The back-end part consists of several JAVA SpringBoot microservices. With multiple front-ends. One back-office front-end, one customer-facing, with the chance of changing requirements there might be a third front-end as well in the future.

Our problem is, that because of our limited resources we cannot run the front-end and back-end builds in parallel. Now, the good thing is that everything is tested thoroughly. Which makes the back-end build run for 17 minutes and the front-end builds would run for another 14 minutes. That is simply too much for a pull-request build.

The first step for reducing this build time is that we implemented our two front-end applications using the NX workspace. That has reduced the front-end build time radically, however, installing node and npm, then running npm ci still takes a lot when there are only back-end changes. Similarly building three SpringBoot microservices with all their unit and functional tests take some time.

So, in order to deal with this problem we came up with the idea to make the front-end and back-end pull-request builds conditional. Yes, we are mimicking the affected builds of the NX workspace, but in our pull-request pipelines. After a small research, I have run into this blog post. (Thank you, Mr Becker!) The command that would allow us to condition our build steps is:

git diff --quiet HEAD origin/master -- web-ui || echo changed

This command consists of two parts. The first part before the OR operator returns with an exit code. If the output fails (nonzero exit-code) then the echo will run. We need two variables in our Jenkinsfile. FE_IS_DIRTY and BE_IS_DIRTY. We need to define them at the top of the Jenkinsfile, outside of our pipeline declaration.

def FE_IS_DIRTY
def BE_IS_DIRTY

pipeline { //...

Then, we need to assign the values to these empty variables. We need to run checkout scm first, so we have the actual changes that we can run our commands against. The variable assignment should run inside a script scope.

stage('Init build') {
  steps {
    // ...
    checkout scm
    script {
      FE_IS_DIRTY = sh (
        script: "git diff --quiet HEAD origin/master -- web-ui || echo changed",
        returnStdout: true
      )
      echo "Frontend isDirty: ${FE_IS_DIRTY}"
      BE_IS_DIRTY = sh (
        script: "git diff --quiet HEAD origin/master -- server || echo changed",
        returnStdout: true
      )
      echo "Backend isDirty: ${BE_IS_DIRTY}"
    }
  }
}

Now we just have to decorate our build steps with an appropriate when block:

stage('FE init') {
  when {
    expression { return FE_IS_DIRTY }
  }
  steps {
    sh './gradlew npmInstall'
    sh './gradlew generateGitHash'
  }
}
// ...
stage('BE Unit tests') {
  when {
    expression { return BE_IS_DIRTY  }
  }
  steps {
    echo 'Execute SpringBoot Application unit tets'
    sh './gradlew server:test'
  }
}

This way when there are only changes on the back-end the front-end tests won't run. Similarly, when the changes only involve the front-end, the back-end build steps are not executed unnecessarily.

3. Notify DevOps

In our process, deploying to the dev and the test environment is automatic. New changes are immediately pushed to the dev environment whenever a master merge occurs. Every night at 21:00 the nightly build runs all the tests, builds the artefacts and publishes to the test (staging) environment. Deploying to production is a protected part of this process. Only the DevOps team can (and should) deploy to production.

The process is that whenever a release should be made, we run the release Jenkins job, which runs every test and builds the artefacts. The same version should be on the test environment, and the manual tests should run against it. After that, we need to create an issue for the DevOps team and send a notification e-mail to the DevOps team coordinator. As you have guessed already, the Jira Steps Plugin comes to the rescue. Creating looks like the following:

    stage('Notify DevOps') {
      steps {
        script {
          try {
            def devopsTicket = [fields: [
                project: [key: 'YOUR_PROJECT_KEY'],
                summary: "Release PROJECT ${params.RELEASE_VERSION} to production",
                description: "See Jenkins job: '${env.JOB_NAME} [${env.BUILD_NUMBER}]' (${env.BUILD_URL})"
              ]
            ]
            response = jiraNewIssue site: 'https://your.jira.com/' issue: devopsTicket

            echo response.successful.toString()
            echo response.data.toString()

            mail bcc: '', body: "<b>Release</b><br> Project: ${env.JOB_NAME} <br>Build Number: ${env.BUILD_NUMBER} <br> Build URL: ${env.BUILD_URL} <br> New version: ${params.RELEASE_VERSION}", cc: '', charset: 'UTF-8', from: 'jenkins@yourcompany.com', mimeType: 'text/html', replyTo: '', subject: "Deploy new release ${params.RELEASE_VERSION}", to: 'devops@devops.com';
          } catch (Exception e) {
            // if for some reason the JIRA ticket could not be created, send a notification to slack or an e-mail
            // or something that could benefit your process
          }
        }
      }
    }

We put the whole step into a try-catch block, so if something fails during issue creation, a fallback notification could be sent. We don't want to fail the build on a technicality. Since this is the last step of the build if a flaky connection to the JIRA server fails the release build that is a false alarm. In the try block, we define the issue that needs to be created and populate it with the available data. Then we can also send out an e-mail to the DevOps team, so they can see that this task has priority.

Jira with its plugins can be a powerful tool to automate your builds and processes. I hope you enjoyed this article, and maybe these small tricks and tips could help you in the long run.

You can read the original artile here.

Do you have some tricks up your sleeves as well? You can tweet it to me on Twitter

If you like it, you should have put some lint on it...

Tápai Balázs — Tue, 18 Feb 2020 17:23:44 +0000

I once overheard a manager talking to a developer about the speed of development. He asked why the developer lints his code, that only slows him down.
Another story comes from another company where a lead developer made a statement, that linters make developers lazy.

My opinion is that if you spend several hours of your day doing code reviews, and you only point out space vs tab errors or argue about where to put curly braces, or where does the question mark go in a ternary expression... Well, then you really like to slack off.

Of course, a team should always have a coding style. Even guidelines defined as early as possible. In my experience, these guidelines are set by lead developers or architects who have their reasons. My problem is that too often these coding styles and guidelines get lost in a lonely confluence/wiki page after an unhealthy amount of arguing and bikeshedding.

Some of the rules are memorised by the development team, and they work on the codebase for some time, but developers come and go.
You can even make that confluence (or wiki) page part of the new-hire process, but you must accept the fact, that certain people come from different places with different preferences which won't change by reading a wiki page. So when somebody says that linters make developers lazy he is essentially not wrong, but not right either.

Let the linter deal with it

First and foremost, some things are essential to remember. Coding style rules are not in that category, because most of them can be perfectly automated.
I'd rather remember my wife's birthday than the proper place of curly braces preferred by the project's architect (or whoever made the decision). So if you want to enforce it, automate it and when developers stop fighting the linter they become more productive.

One fine example id leaving multiple empty lines between methods or function calls. I personally didn't care about multiple empty lines, but I had a colleague who pointed out every unnecessary empty line in the codebase.
Eventually, I got tired, because that colleague always put a needs work flag on my pull-requests and often because of these empty lines. While the changes were good, I had to fix the empty lines and wait for another two approvers to be able to finally merge it.
Tslint came to the rescue with the no-consecutive-empty-lines rule and suddenly we were shipping features faster. Nobody got hurt in the process.

Now, the linter setup should not be something that blocks you. For example, it would be crazy to block typescript compilation because the code you write is not properly formatted (and cannot be fixed automatically).
Linting should not be part of hot module replacement, however, there are 3 stages where you can lint your code.

1. Your IDE
2. Pre-commit hooks
3. CI/CD pipeline

I always recommend putting a lint check at the beginning of a CI/CD pipeline, that way no change could go in, which does not meet the preferred coding style. Running the linter manually every time before pushing is still something that you have to remember, that is why I prefer using pre-commit hooks. You can easily set them up. I am working with JavaScript/TypeScript most of the time and recently I have been using NX Workspace for my projects which comes with some out-of-the-box setup.

npm install husky lint-staged --save-dev

I usually start with installing Husky and Lint-Staged, then I set it up in my package.json file:

 "husky": { "hooks": { "pre-commit": "lint-staged" } }

I used to set up the lint-staged commands to run the nx formatter and the linter on the whole project before commit, but that took a long time.
Luckily, my friend Tamás helped me out with a lint-staged.config.js file:

const path = require("path")

module.exports = {
  "*.{html,js,ts,json,md,css,scss}": files => {
    if (
      files.length > 0 &&
      files[0] !== "[filename]" &&
      files[0] !== "[file]"
    ) {
      const cwd = process.cwd()
      const relativePaths = files.map(f => path.relative(cwd, f))
      return [
        `nx format:write --files="${relativePaths.join(",")}"`, //
        `nx affected:lint --files="${relativePaths.join(
          ","
        )}" --fix --parallel`, //
        `git add ${relativePaths.join(" ")}`,
      ]
    } else {
      return []
    }
  }
}

This way only the staged and changed files are linted and formatted. As you can see, NX uses prettier for its format script.

Here is my prettier config which gets used:

{
  "arrowParens": "always",
  "singleQuote": true,
  "trailingComma": "es5",
  "endOfLine": "lf",
  "printWidth": 140
}

Setting the end of line with prettier can prevent issues during code reviews, namely that somebody joins the team on a windows machine, and they have autoclrf = true set. That makes pretty hard to find the actual changes.

A .editorconfig file is important as well. Most IDEs accept it by default, some of them need plugins, but it is a worthy cause.

With a .editorconfig file you can set the line endings, the indent style, the indent size and most basic code styling problems that can come up in a code review.

The most wonderful thing about aesthetic linting is that it saves so much time, and helps to focus the developers' attention towards code readability and architecture instead of arguing about 2 spaces or 4 spaces or tabs.

Why are some of the stricter code formatting rules useful?

Diverging from an agreed-upon coding style is usually automatically fixable using linters. This means that the new-hire can write whatever he/she wants, however, he/she wants, without interruption. Then the pre-commit hook will format his/her code and everybody is happy.

The developer now can focus on what to write instead of how to write it.

Of course, there are stricter rules for linters as well. I for one like SonarQube, but that is not always accessible for budget reasons.

However, we have sonar-js and sonar-ts lint rulesets installed as packages, which can help tremendously. One of my favourites is the cognitive-complexity linting rule.

That has certainly made my life easier because extremely complex methods stopped appearing in the codebase. Readable code is more maintainable,

and when functions are separated in small understandable chunks that is a benefit for everybody.

Cognitive complexity is an extremely important measurement. If you use VSCode you can find a very useful plugin here.

These conventions and configurations should live near the code itself. That is why you have .eslintrc and tsconfig.json and .stylelintrc in your project's root folder.

That way if somebody new joins the team they don't have to fiddle around with setting up everything the way it is declared on a confluence or wiki page somewhere. That is why I don't like to put these rules in .vscode or .idea or whatever folders. In my opinion, enforcing IDE

settings on developers is a serious intrusion into their personal spaces.

Can you control your developer's IDE?

I once worked with somebody who insisted that everybody should use the same IDE settings that he/she used and the .vscode folder should be committed to the repository.

Whenever I use VSCode for certain projects, I love to use peacock so I can differentiate between windows.

However, peacock colour settings saved into the .vscode folder and pushed to the remote repository would force other developers to use the same colours that I like. Not a friendly way to work in a team and it would cause unnecessary merge conflicts as well.

Of course, you and your team should decide upon the ruleset which you want to apply. However, I recommend setting rules for brackets, member-ordering and everything that is automatically fixable. For example, setting up the arrowparens rule would make it easier to search for arrow functions.
For example, you might vaguely remember using an arrow function with a specific variable. Searching for it using specificVariable) => { will find it for you.

I'd like to end this post with a story of how linting could have prevented huge errors in production. I was working with a good friend of mine, who was a rookie developer under my hands at the time. He was excellent! He was eager to learn, and he immediately accepted the fact that writing unit tests is really important. So he did, but one time he encountered an issue where he needed to fix something in one breaking unit test.
He focused that test (fit in Jasmine) while tackling the problem, and forgot to un-focus it. The change was pushed, and another branch was rebased to his changes.

That other branch, however, broke lots of unit tests, but since in the CI pipeline only one focused test ran, we didn't notice the issue first. It was a lucky catch, because one developer noticed, that the CI/CD pipeline was faster.
We've looked at the test reports and found only the focused test. That saved us that time, but obviously one little fit is very easy to miss when the whole file is marked as a change.

After that incident, we integrated the tslint-jasmine-rules ruleset to our linting process. The no-focused-tests and no-disabled-tests rules help a lot.
There are packages for jest and mocha, and other frameworks as well.

What are your favourite lint rules? Have you ever had situations where linting saved you? Or situations, where linting could have, saved you?

You Rang, M'Lord? Docker in Docker with Jenkins declarative pipelines

Tápai Balázs — Fri, 17 Jan 2020 00:00:00 +0000

Resources. When unlimited they are not important, but when limited, boy you have challenges! Recently we've faced such a challenge ourselves when
we realised that we need to upgrade the node version on one of our Jenkins agent so we could build and properly test our Angular 7 app. However, we would also lose
the ability to build our legacy AngularJS apps which require Node 8. What to do?

Apart from eliminating the famous "It works on my machine" problem, docker comes in handy when such a problem arises. However,
there are certain challenges that need to be addressed, such as docker in docker. For this purpose, after a long period of trial and error, we have
built and published a docker file for my team's necessities,
which can help running our builds, which looks like the following:

1. Install dependencies
2. Lint the code
3. Run unit tests
4. Run SonarQube analysis
5. Build the application
6. Build a docker image which would be deployed
7. Run the docker container
8. Run cypress tests
9. Push docker image to the repository
10. Run another Jenkins job to deploy it to the environment
11. Generate unit and functional test reports and publish them
12. Stop any running containers
13. Notify chat/email about the build

The docker image of our needs

Our project is an Angular 7 project, which was generated using the angular-cli. We also have some dependencies that need node 10.x.x. We lint our code with tslint, and run our unit tests
with Karma and Jasmine. For the unit tests we need a Chrome browser installed, so they can run with headless chrome.
This is why we decided to use the cypress/browsers:node10.16.0-chrome77 image. After we install the dependencies, lint our code and run our unit tests, we run the SonarQube analysis.
This requires us to have Openjdk 8 as well.

FROM cypress/browsers:node10.16.0-chrome77

# Install OpenJDK-8
RUN apt-get update && \
    apt-get install -y openjdk-8-jdk && \
    apt-get install -y ant && \
    apt-get clean;

# Fix certificate issues
RUN apt-get update && \
    apt-get install ca-certificates-java && \
    apt-get clean && \
    update-ca-certificates -f;

# Setup JAVA_HOME -- useful for docker commandline
ENV JAVA_HOME /usr/lib/jvm/java-8-openjdk-amd64/
RUN export JAVA_HOME

The sonar scan is ready, therefore, we build the application. One of the strongest principles in testing is that one should test the thing that will be used by the users.
That is the reason that we want to test the built code in exactly the same docker container as it would be in production. we could, of course serve the front-end from a very simple nodejs static server,
but that would mean that everything that an Apache HTTP server or an NGINX server do would be missing. For example all the proxies, gzip or brotli would be missing.

Now while it is a strong principle, the biggest problem of this is that we are already running inside a docker container. That is why we need DIND (Docker in Docker). After spending a whole day
with my colleague researching, we found a solution which works like a charm now. The first and most important thing is that our build container needs the docker executable.

# Install Docker executable
RUN apt-get update && apt-get install -y \
        apt-transport-https \
        ca-certificates \
        curl \
        gnupg2 \
        software-properties-common \
    && curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add - \
    && add-apt-repository \
        "deb [arch=amd64] https://download.docker.com/linux/debian \
        $(lsb_release -cs) \
        stable" \
    && apt-get update \
    && apt-get install -y \
        docker-ce

RUN usermod -u 1002 node && groupmod -g 1002 node && gpasswd -a node docker

As you can see we install the docker executable and the necessary certificates, but we also add the rights and groups for our user. The latter one is necessary because the host machine, our Jenkins agent, starts the container with -u 1002:1002. That is the user ID of our Jenkins agent which runs the container unprivileged.

This is of course not everything. When the container starts, the docker daemon of the host machine must be mounted. This requires us to start the build container
with some extra parameters. It looks like the following in a Jenkinsfile:

pipeline {
  agent {
    docker {
     image 'btapai/pipelines:node-10.16.0-chrome77-openjdk8-CETtime-dind'
     label 'frontend'
     args '-v /var/run/docker.sock:/var/run/docker.sock -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket -e HOME=${workspace} --group-add docker'
    }
  }

// ...
}

As you can see, we mount two Unix sockets. /var/run/docker.sock mounts the docker daemon to the build container.

/var/run/dbus/system_bus_socket is a socket that is needed for cypress to be able to run inside our container.

-e HOME=${workspace} is needed for avoiding access right issues during the build.

--group-add docker passes the host machines docker group down, so, inside the container, our user can use the docker daemon.

With these proper arguments, we can build our image, start it up and run our cypress tests against it. But let's take a deep breath here. In Jenkins, we want to use multi-branch pipelines.
Multibranch pipelines in Jenkins will create a Jenkins job for each branch that contains a Jenkinsfile. This means that when we develop multiple branches they are going to have their own views.

There are some problems with this. The first problem is that if we build our image with the same name in all the branches, it will conflict, since our docker daemon is technically not inside our build container.
The second problem will arise when the docker run command uses the same port in every build because you can't start the second container on a port that is already taken.
The third issue is getting the proper URL for the running application, because Dorothy, you are not in Localhost anymore.

Let's start with the naming. Getting a unique name is pretty easy with git, because commit hashes are unique. However, getting a unique port we might need to use a little trick when we declare our environment variables:

pipeline {

// ..

  environment {
    BUILD_PORT = sh(
        script: 'shuf -i 2000-65000 -n 1',
        returnStdout: true
    ).trim()
  }

// ...

    stage('Functional Tests') {
      steps {
        sh "docker run -d -p ${BUILD_PORT}:80 --name ${GIT_COMMIT} application"
        // be patient, we are going to get the url as well. :)
      }
    }

// ...

}

With the shuf -i 2000-65000 -n 1 command on certain Linux distributions you can generate a random number. Our base image uses Debian so we were lucky here.
the GIT_COMMIT environment variable is provided in Jenkins via the SCM plugin.

Now comes the hard part, namely, we are inside a docker container and there is no localhost and the network inside docker containers can change.
It is also a funny thing that when we start our container, it runs on the host machine's docker daemon, so technically it is not running inside our container. We have to reach it from the inside.
After several hours of investigation my colleague found a possible solution:
docker inspect --format "{{ .NetworkSettings.IPAddress }}"

Which did not work, because that IP address is not an IP address inside the container but outside. Then we tried the NetworkSettings.Gateway property, which worked like a charm.
So our Functional testing stage looks like the following:

stage('Functional Tests') {
  steps {
    sh "docker run -d -p ${BUILD_PORT}:80 --name ${GIT_COMMIT} application"
    sh 'npm run cypress:run -- --config baseUrl=http://`docker inspect --format "{{ .NetworkSettings.Gateway }}" "${GIT_COMMIT}"`:${BUILD_PORT}'
  }
}

It was a wonderful feeling to see our cypress tests running inside a docker container. Then some of them failed miserably.
The reason was, that the failing cypress tests expected to see some dates.

cy.get("created-date-cell")
  .should("be.visible")
  .and("contain", "2019.12.24 12:33:17")

But because of our build container was set to a different timezone, the displayed date on our front-end was different. It is an easy fix, my colleague has seen it before. We install the necessary time zones and locales. In our case we set the build container's timezone to Europe/Budapest, because our tests were written in this timezone.

# SETUP-LOCALE
RUN apt-get update \
    && apt-get install --assume-yes --no-install-recommends locales \
    && apt-get clean \
    && sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen \
    && sed -i -e 's/# hu_HU.UTF-8 UTF-8/hu_HU.UTF-8 UTF-8/' /etc/locale.gen \
    && locale-gen

ENV LANG="en_US.UTF-8" \
    LANGUAGE= \
    LC_CTYPE="en_US.UTF-8" \
    LC_NUMERIC="hu_HU.UTF-8" \
    LC_TIME="hu_HU.UTF-8" \
    LC_COLLATE="en_US.UTF-8" \
    LC_MONETARY="hu_HU.UTF-8" \
    LC_MESSAGES="en_US.UTF-8" \
    LC_PAPER="hu_HU.UTF-8" \
    LC_NAME="hu_HU.UTF-8" \
    LC_ADDRESS="hu_HU.UTF-8" \
    LC_TELEPHONE="hu_HU.UTF-8" \
    LC_MEASUREMENT="hu_HU.UTF-8" \
    LC_IDENTIFICATION="hu_HU.UTF-8" \
    LC_ALL=

# SETUP-TIMEZONE
RUN apt-get update \
    && apt-get install --assume-yes --no-install-recommends tzdata \
    && apt-get clean \
    && echo 'Europe/Budapest' > /etc/timezone && rm /etc/localtime \
    && ln -snf /usr/share/zoneinfo/'Europe/Budapest' /etc/localtime \
    && dpkg-reconfigure -f noninteractive tzdata

Since every crucial part of the build is now resolved, pushing the built image to the registry is just a docker push command. You can check the whole dockerfile here.
One thing remains, which is to stop running containers when the cypress tests fail. This can be done easily using the always post step.

post {
  always {
    script {
      try {
        sh "docker stop ${GIT_COMMIT} && docker rm ${GIT_COMMIT}"
      } catch (Exception e) {
        echo 'No docker containers were running'
      }
    }
  }
}

Thank you very much for reading this blog post. I hope it helps you.

The original article can be read on my blog:
https://tapaibalazs.netlify.com/jenkins-and-docker-in-docker/

What could go wrong? How to handle errors in Angular

Tápai Balázs — Mon, 01 Jul 2019 15:04:09 +0000

Approximately a year ago, I have implemented the first e2e tests on a project. It was a rather big application using JAVA SpringBoot on the back-end and Angular on the front-end. We used Protractor as a testing tool, which uses Selenium. In the front-end code there was a service, which had an error handler method. When that method was called, a modal dialog popped up and the user could see the details of the errors and the stacktrace.

The problem was that while it has tracked every error that happened on the back-end, the front-end failed silently. TypeErrors, ReferenceErrors and other uncaught exceptions were logged only to the console. When something went wrong during e2e test runs the screenshot, which was taken when the test step has failed, has shown absolutely nothing. Have fun debugging that!

Luckily Angular has a built-in way of handling errors and it is extremely easy to use. We just have to create our own service, which implements Angular's ErrorHandler interface:

import { ErrorHandler, Injectable } from '@angular/core';

@Injectable({
    providedIn: 'root'
})
export class ErrorHandlerService implements ErrorHandler{
    constructor() {}

    handleError(error: any) {
        // Implement your own way of handling errors
    }
}

While we could easily provide our service in our AppModule, it might be a good idea to provide this service in a separate module. This way we could create our own library and use it in our future projects as well:

// ERROR HANDLER MODULE
import {ErrorHandler, ModuleWithProviders, NgModule} from '@angular/core';
import {ErrorHandlerComponent} from './components/error-handler.component';
import {FullscreenOverlayContainer, OverlayContainer, OverlayModule} from '@angular/cdk/overlay';
import {ErrorHandlerService} from './error-handler.service';
import {A11yModule} from '@angular/cdk/a11y';

@NgModule({
  declarations: [ErrorHandlerComponent],
  imports: [CommonModule, OverlayModule, A11yModule],
  entryComponents: [ErrorHandlerComponent]
})
export class ErrorHandlerModule {
  public static forRoot(): ModuleWithProviders {
    return {
      ngModule: ErrorHandlerModule,
      providers: [
        {provide: ErrorHandler, useClass: ErrorHandlerService},
        {provide: OverlayContainer, useClass: FullscreenOverlayContainer},
      ]
    };
  }
}

We used the Angular CLI for generating the ErrorHandlerModule, so we already have a component generated which can be our modal dialog's content. In order for us to be able to put it inside an Angular CDK overlay, it needs to be an entryComponent. That is why we have put it into the ErrorHandlerModule's entryComponents array.

We also added some imports. OverlayModule and A11yModule comes from the CDK module. They are needed for creating our overlay and to trap focus when our error dialog is opened. As you can see, we provide OverlayContainer using the FullscreenOverlayContainer class because if an error occurs, we want to restrict our users' interactions to our error modal. If we don't have a fullscreen backdrop, the users might be able to interact with the application and cause further errors. Let's add our newly created module to our AppModule:

// APP MODULE
import {BrowserModule} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

import {AppRoutingModule} from './app-routing.module';
import {AppComponent} from './app.component';
import {MainComponent} from './main/main.component';
import {ErrorHandlerModule} from '@btapai/ng-error-handler';
import {HttpClientModule} from '@angular/common/http';

@NgModule({
  declarations: [ AppComponent, MainComponent ],
  imports: [
    BrowserModule,
    HttpClientModule,
    ErrorHandlerModule.forRoot(),
    AppRoutingModule,
  ],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Now that we have our ErrorHandlerService in place, we can start implementing the logic. We are going to create a modal dialog, which displays the error in a clean, readable way. This dialog will have an overlay/backdrop and it will be dynamically placed into the DOM with the help of the Angular CDK. Let's install it:

npm install @angular/cdk --save

According to the documentation, the Overlay component needs some pre-built css files. Now if we would use Angular Material in our project it wouldn't be necessary, but that is not always the case. Let's import the overlay css in our styles.css file. Note, that if you already use Angular Material in your app, you don't need to import this css.

@import '~@angular/cdk/overlay-prebuilt.css';

Let's use our handleError method to create our modal dialog. It is important to know, that the ErrorHandler service is part of the application initialisation phase of Angular. In order to avoid a rather nasty cyclic dependency error, we use the injector as its only constructor parameter. We use Angular's dependency injection system when the actual method is called. Let's import the overlay from the CDK and attach our ErrorHandlerComponent into the DOM:

// ... imports

@Injectable({
    providedIn: 'root'
})
export class ErrorHandlerService implements ErrorHandler {
    constructor(private injector: Injector) {}

    handleError(error: any) {
        const overlay: Overlay = this.injector.get(Overlay);
        const overlayRef: OverlayRef = overlay.create();
        const ErrorHandlerPortal: ComponentPortal<ErrorHandlerComponent> = new ComponentPortal(ErrorHandlerComponent);
        const compRef: ComponentRef<ErrorHandlerComponent> = overlayRef.attach(ErrorHandlerPortal);
    }
}

Let's turn our attention towards our error handler modal. A pretty simple working solution would be displaying the error message and the stacktrace. Let's also add a 'dismiss' button to the bottom.

// imports
export const ERROR_INJECTOR_TOKEN: InjectionToken<any> = new InjectionToken('ErrorInjectorToken');

@Component({
  selector: 'btp-error-handler',
  // TODO: template will be implemented later
  template: `${error.message}<br><button (click)="dismiss()">DISMISS</button>`
  styleUrls: ['./error-handler.component.css'],
})
export class ErrorHandlerComponent {
  private isVisible = new Subject();
  dismiss$: Observable<{}> = this.isVisible.asObservable();

  constructor(@Inject(ERROR_INJECTOR_TOKEN) public error) {
  }

  dismiss() {
    this.isVisible.next();
    this.isVisible.complete();
  }
}

As you can see, the component itself is pretty simple. We are going to use two rather important directives in the template, to make the dialog accessible. The first one is the cdkTrapFocus which will trap the focus when the dialog is rendered. This means that the user cannot focus elements behind our modal dialog. The second directive is the cdkTrapFocusAutoCapture which will automatically focus the first focusable element inside our focus trap. Also, it will automatically restore the focus to the previously focused element, when our dialog is closed.

In order to be able to display the error's properties, we need to inject it using the constructor. For that we need our own injectionToken. We also created a rather simple logic for emitting a dismiss event using a subject and the dismiss$ property. Let's connect this with our handleError method in our service and do some refactoring.

// imports
export const DEFAULT_OVERLAY_CONFIG: OverlayConfig = {
  hasBackdrop: true,
};

@Injectable({
  providedIn: 'root'
})
export class ErrorHandlerService implements ErrorHandler {

  private overlay: Overlay;

  constructor(private injector: Injector) {
    this.overlay = this.injector.get(Overlay);
  }

  handleError(error: any): void {
    const overlayRef = this.overlay.create(DEFAULT_OVERLAY_CONFIG);
    this.attachPortal(overlayRef, error).subscribe(() => {
      overlayRef.dispose();
    });
  }

  private attachPortal(overlayRef: OverlayRef, error: any): Observable<{}> {
    const ErrorHandlerPortal: ComponentPortal<ErrorHandlerComponent> = new ComponentPortal(
      ErrorHandlerComponent,
      null,
      this.createInjector(error)
    );
    const compRef: ComponentRef<ErrorHandlerComponent> = overlayRef.attach(ErrorHandlerPortal);
    return compRef.instance.dismiss$;
  }

  private createInjector(error: any): PortalInjector {
    const injectorTokens = new WeakMap<any, any>([
      [ERROR_INJECTOR_TOKEN, error]
    ]);

    return new PortalInjector(this.injector, injectorTokens);
  }
}

Let's focus on providing the error as an injected parameter first. As you can see, the ComponentPortal class expects one must-have parameter, which is the component itself. The second parameter is a ViewContainerRef which would have an effect of the component's logical place of the component tree. The third parameter is our createInejctor method. As you can see it returns a new PortalInjector instance. Let's take a quick look at its underlying implementation:

export class PortalInjector implements Injector {
 constructor(
   private _parentInjector: Injector,
   private _customTokens: WeakMap<any, any>) { }

 get(token: any, notFoundValue?: any): any {
   const value = this._customTokens.get(token);

   if (typeof value !== 'undefined') {
     return value;
   }

   return this._parentInjector.get<any>(token, notFoundValue);
 }
}

As you can see, it expects an Injector as a first parameter and a WeakMap for custom tokens. We did exactly that using our ERROR_INJECTOR_TOKEN which is associated with our error itself. The created PortalInjector is used for the proper instantiation of our ErrorHandlerComponent, it will make sure that the error itself will be present in the component.

At last, our attachPortal method returns the recently instantiated component's dismiss$ property. We subscribe to it, and when it changes we call the .dispose() on our overlayRef. And our error modal dialog is dismissed. Note, that we also call complete on our subject inside the component, therefore, we don't need to unsubscribe from it.

Now, this is excellent for errors that are thrown when there's an issue in the clinet side code. But we are creating web applications and we use API endpoints. So what happens when a REST endpint gives back an error?

We can handle every error in its own service, but do we really want to? If everything is alright errors won't be thrown. If there are specific requirements, for example to handle 418 status code with a flying unicorn you could implement its handler in its service. But when we face rather common errors, like 404 or 503 we might want to display that in this same error dialog.

Let's just quickly gather what happens when an HttpErrorResponse is thrown. It is going to happen async, so probably we are going to face some change detection issues. This error type has different properties than a simple error, therefore, we might need a sanitiser method. Now let's get into it by creating a rather simple interface for the SanitisedError:

export interface SanitizedError {
  message: string;
  details: string[];
}

Let's create a template for our ErrorHandlerComponent:

// Imports

@Component({
  selector: 'btp-error-handler',
  template: `
    <section cdkTrapFocus [cdkTrapFocusAutoCapture]="true" class="btp-error-handler__container">
      <h2>Error</h2>
      <p>{{error.message}}</p>
      <div class="btp-error-handler__scrollable">
        <ng-container *ngFor="let detail of error.details">
          <div>{{detail}}</div>
        </ng-container>
      </div>
      <button class="btp-error-handler__dismiss button red" (click)="dismiss()">DISMISS</button>
    </section>`,
  styleUrls: ['./error-handler.component.css'],
})
export class ErrorHandlerComponent implements OnInit {
 // ...
}

We wrapped the whole modal into a <section> and we added the cdkTrapFocus directive to it. This directive will prevent the user from navigating in the DOM behind our overlay/modal. The [cdkTrapFocusAutoCapture]="true" makes sure that the dismiss button is focused immediately. When the modal is closed the previously focused element will get back the focus. We simply display the error message and the details using *ngFor. Let's jump back into our ErrorHandlerService:

// Imports

@Injectable({
  providedIn: 'root'
})
export class ErrorHandlerService implements ErrorHandler {
  // Constructor

  handleError(error: any): void {
    const sanitised = this.sanitiseError(error);
    const ngZone = this.injector.get(NgZone);
    const overlayRef = this.overlay.create(DEFAULT_OVERLAY_CONFIG);

    ngZone.run(() => {
      this.attachPortal(overlayRef, sanitised).subscribe(() => {
        overlayRef.dispose();
      });
    });
  }

  // ...

  private sanitiseError(error: Error | HttpErrorResponse): SanitizedError {
    const sanitisedError: SanitizedError = {
      message: error.message,
      details: []
    };
    if (error instanceof Error) {
      sanitisedError.details.push(error.stack);
    } else if (error instanceof HttpErrorResponse) {
      sanitisedError.details = Object.keys(error)
        .map((key: string) => `${key}: ${error[key]}`);
    } else {
      sanitisedError.details.push(JSON.stringify(error));
    }
    return sanitisedError;
  }
  // ...
}

With a rather simple sanitiseError method we create an object which is based on our previously defined interface. We check for error types and populate the data accordingly. The more interesting part is using the injector to get ngZone. When an error happens asynchronously, it usually happens outside change detection. We wrap our attachPortal with ngZone.run(/* ... */), so when an HttpErrorResponse is caught, it is rendered properly in our modal.

While the current state works nicely, it still lacks customisation. We use the Overlay from the CDK module, so exposing an injection token for custom configurations would be nice. Another important shortcoming of this module is that when this module is used, another module can't be used for error handling. For example, integrating Sentry would require you to implement a similar, but lightweight ErrorHandler module. In order to be able to use both, we should implement the possibility of using hooks inside our error handler. First, let's create our InjectionToken and our default configuration:

import {InjectionToken} from '@angular/core';
import {DEFAULT_OVERLAY_CONFIG} from './constants/error-handler.constants';
import {ErrorHandlerConfig} from './interfaces/error-handler.interfaces';

export const DEFAULT_ERROR_HANDLER_CONFIG: ErrorHandlerConfig = {
  overlayConfig: DEFAULT_OVERLAY_CONFIG,
  errorHandlerHooks: []
};

export const ERROR_HANDLER_CONFIG: InjectionToken<ErrorHandlerConfig> = new InjectionToken('btp-eh-conf');

Then provide it with our module, using our existing forRoot method:

@NgModule({
  declarations: [ErrorHandlerComponent],
  imports: [CommonModule, OverlayModule, A11yModule],
  entryComponents: [ErrorHandlerComponent]
})
export class ErrorHandlerModule {

  public static forRoot(): ModuleWithProviders {
    return {
      ngModule: ErrorHandlerModule,
      providers: [
        {provide: ErrorHandler, useClass: ErrorHandlerService},
        {provide: OverlayContainer, useClass: FullscreenOverlayContainer},
        {provide: ERROR_HANDLER_CONFIG, useValue: DEFAULT_ERROR_HANDLER_CONFIG}
      ]
    };
  }
}

Then integrate this config handling into our ErrorHandlerService as well:

// Imports
@Injectable({
  providedIn: 'root'
})
export class ErrorHandlerService implements ErrorHandler {
  // ...

  handleError(error: any): void {
    const sanitised = this.sanitiseError(error);
    const {overlayConfig, errorHandlerHooks} = this.injector.get(ERROR_HANDLER_CONFIG);
    const ngZone = this.injector.get(NgZone);

    this.runHooks(errorHandlerHooks, error);
    const overlayRef = this.createOverlayReference(overlayConfig);
    ngZone.run(() => {
      this.attachPortal(overlayRef, sanitised).subscribe(() => {
        overlayRef.dispose();
      });
    });
  }
  // ...
  private runHooks(errorHandlerHooks: Array<(error: any) => void> = [], error): void {
    errorHandlerHooks.forEach((hook) => hook(error));
  }

  private createOverlayReference(overlayConfig: OverlayConfig): OverlayRef {
    const overlaySettings: OverlayConfig = {...DEFAULT_OVERLAY_CONFIG, ...overlayConfig};
    return this.overlay.create(overlaySettings);
  }
  // ...
}

And we are almost ready. Let's integrate a third-party error handler hook into our application:

// Imports
const CustomErrorHandlerConfig: ErrorHandlerConfig = {
  errorHandlerHooks: [
    ThirdPartyErrorLogger.logErrorMessage,
    LoadingIndicatorControl.stopLoadingIndicator,
  ]
};

@NgModule({
  declarations: [
    AppComponent,
    MainComponent
  ],
  imports: [
    BrowserModule,
    HttpClientModule,
    ErrorHandlerModule.forRoot(),
    AppRoutingModule,
  ],
  providers: [
    {provide: ERROR_HANDLER_CONFIG, useValue: CustomErrorHandlerConfig}
  ],
  bootstrap: [AppComponent]
})
export class AppModule {
}

As you can see, handling errors is an extremely important part of software development, but it can also be fun.

Thank you very much for reading this blog post. If you prefer reading code, please check out my ng-reusables git repository. You can also try out the implementation as well using this npm package.

You can also follow me on Twitter or GitHub.