DEV Community: Mathias Remshardt

Let's build - Autohide tooltip in Angular

Mathias Remshardt — Sat, 05 Aug 2023 11:07:29 +0000

The problem

We want to show/hide a tooltip for some text depending on whether there is enough room for the text.

Solution

A directive that checks the width of the text and compares it against the width of the container. If the latter is smaller than the former the tooltip will be shown.
To focus on the directive implementation we are going to use the tooltips provided by angular material.

Implementation

TooltipIfCollapsedDirective

The directive reads the width of the component it is applied to to check if the tooltip needs to enabled or disabled.

import { Directive, ElementRef, HostListener } from '@angular/core';
import { MatTooltip } from '@angular/material/tooltip';

@Directive({
  selector: '[appTooltipIfCollapsed]',
  standalone: true,
})
export class TooltipIfCollapsedDirective {
  constructor(private element: ElementRef, private tooltip: MatTooltip) {}

  ngAfterViewInit(): void {
    // The requestAnimationFrame gives the browser some time to calculate the scrollWidth which is required
    // to determine if the tooltip should be hidden or not.
    window.requestAnimationFrame(() => {
      this.updateTooltip();
    });
  }

  @HostListener('window:resize', ['$event'])
  onResize() {
    window.requestAnimationFrame(() => {
      this.updateTooltip();
    });
  }

  private updateTooltip() {
    if (
      this.element.nativeElement.getBoundingClientRect().width <
      this.element.nativeElement.scrollWidth
    ) {
      this.tooltip.disabled = false;
    } else {
      this.tooltip.disabled = true;
    }
  }
}

It compares the width of the component against the scrollWidth. If the latter is larger than the former it means that the text does not completely fit into the container.
The first call to updateTooltip is in ngAfterViewInit so that the container width is available. The same call is made whenever the browser window is changed.

As mentioned in the comment, requestAnimationFrame gives the browser some time to recalculate the scrollWidth. Without it I had some instances where the scrollWidth was not up to date leading to the tooltip being shown/hidden when it should not.

Example

The directive is added to the node which also defines the tooltip (matToolbar in the case of Angular Material).

<div [matTooltip]="text" appTooltipIfCollapsed>
  {{ text }}
</div>

:host {
  height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
  container-type: inline-size;
}

div {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}

@container (width < 600px) {
  div {
    width: 100px;
  }
}

For the sake of the example the width of the text container is restricted to 100px when the containing component (AppComponent) width drops below 600px.
Resizing the browser window now shows or hides the tooltip when the width is larger or smaller than 600px.

The code can be found here

Let's build - Feature flags in Angular

Mathias Remshardt — Sat, 24 Jun 2023 15:03:01 +0000

The problem

In one of the projects I'm working on we wanted to show/hide certain elements/features at runtime.
The requirements were pretty simple:

Manually enable and disable the toggle in a configuration file
It should be possible to change the value at runtime

Solution

A well known solution for this are Feature Flags or Feature Toggles. A lot has already been written about this topic e.g. you can find some details here.
There are quite some ready made solutions out there. However most of the available solutions are SaaS offerings and these are not always an option (for technical or financial reasons).
So, as we don't have many (complicated) requirements, it shouldn't be too hard to build our own, local version.

Overview

The following diagram gives an overview of the main elements

As mentioned previously, we are aiming for a rather simple solution so there is not too much going on.

Implementation

Store

All of the configuration is stored in the feature.json file. It has a pretty simple structure with the key being the name of the feature and the value a boolean which indicates if the feature is enabled or not.
This is enough for basic use cases. However if there are a lot flags it could make sense to add bit more structure here e.g. nesting the different flags under a key which represents the pages or components they are associated with.

It is also possible to define different feature.json files as a sort of template for a specific configuration e.g. if the application is deployed for multiple customers.

{
  "newFeature": true
}

FeatureService

Bootstrapping

The root injected service loads the feature.json file and stores it in memory.
The file could be validated and typed after loading (e.g. using something like zod).
I personally did not see any advantage in doing that as the file is only used in the isFeatureEnabled method which checks if the provided key is truthy. Having it typed would not give any benefit and has the drawback that the validation and type definition has to be updated whenever a new property is added to the feature.json file.

  init(): Observable<void> {
    const result = new ReplaySubject<void>(1);
    this.http
      .get<typeof this.featuresFlags>('assets/feature.json')
      .pipe(
        first(),
        catchError(() => of({}))
      )
      .subscribe((featureFlags) => {
        this.featuresFlags = featureFlags;
        result.next();
        result.complete();
      });
    return result;
  }

For the sake of the example the loading mechanismn is kept pretty simple (e.g. it does not include any error handling, it hard codes the path...).

The init method is called by an APP_INITIALIZER at application start up.
It returns an Observable to make sure the first render does not happen before the feature.json file has been loaded.

const initFeatureServiceFactory = (featureService: FeatureService) => {
  return () => featureService.init();
};

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    HttpClientModule,
    WithoutDirectiveComponent,
    WithDirectiveComponent,
  ],
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: initFeatureServiceFactory,
      deps: [FeatureService],
      multi: true,
    },
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

IsFeatureEnabled

The aformentioned isFeatureEnabled method returns if the feature is enabled or not.
The implementation is pretty straight forward at the moment:

  isFeatureEnabled(name: string): boolean {
    return this.featuresFlags[name];
  }

Having a dedicated function hides the storage mechanism and allows for changing to a different approach in the future with minor impact on the using components.

Components

For demonstration purposes two components have been added to the project

WithoutDirectiveComponent

As the name implies the component does the feature check for itself by directly calling the isFeatureEnabled with the feature name.

export class WithoutDirectiveComponent {
  isNewFeatureEnabled = false;

  constructor(public featureService: FeatureService) {
    this.isNewFeatureEnabled = this.featureService.isFeatureEnabled('newFeature');
  }

<p *ngIf="isNewFeatureEnabled; else featureDisabled">
  WithoutDirectiveComponent: Feauture enabled
</p>
<ng-template #featureDisabled>
  <p>WithoutDirectiveComponent: Feature disabled</p>
</ng-template>

FeatureDirective

Repeating the "check and render" is a bit tedious and identical for every using component. Therefore a directive has been added to the project that takes care of this part. It's working similar to ngIf but takes the feature name instead of a boolean.

The directive passes the provided feature name to the FeatureService and leverages the ngIf directive for hiding or showing the feature flagged element.
Similar to ngIf it also allows for displaying an alternative template should the feature be disabled.

@Directive({
  selector: '[appIfFeatureEnabled]',
  standalone: true,
  hostDirectives: [
    {
      directive: NgIf,
      inputs: ['ngIfElse: appIfFeatureEnabledElse'],
    },
  ],
})
export class IfFeatureEnabledDirective {
  @Input() set appIfFeatureEnabled(appIfFeatureEnabled: string) {
    this.ngIf.ngIf = this.featureService.isFeatureEnabled(
      appIfFeatureEnabled ?? false
    );
  }

  constructor(private ngIf: NgIf, private featureService: FeatureService) {}
}

WithDirectiveComponent

The component just needs to pass to feature name to the FeatureDirective

<p *appIfFeatureEnabled="'newFeature'; else featureDisabled">
  WithDirectiveComponent: Feature enabled
</p>
<ng-template #featureDisabled
  >WithDirectiveComponent: Feature disabled</ng-template
>

Conclusion

This is it, a simple solution for feature flagging templates elements in Angular.
As mentioned in the beginning, the implementation only covers simple hide/show use cases which can often be enough, especially in the beginning.
In our project, it has served us as well so far.
It was easy and fast to build, it's easy to maintain (e.g. adding new feature flags) and avoids adding another dependency to a third party library (or company) and, most importantly, it fulfils all of our current requirements.

The code can be found here

Derive union of string literal types with lookup types in Typescript

Mathias Remshardt — Sat, 04 Sep 2021 07:56:45 +0000

Recently I started playing with unions of string literals as an alternative to enums. I did not experience any issues while using enums. I just prefer the string literals as these, in contrast to enums, do not lead additional code generated during compilation.

One thing that has bothered me so far is that I could not find an easy way to store all strings of a string literal union in an array. This can be useful if you want to e.g. randomly select one of the string literals in the union as part of creating mock/fixture data.

Of course you can define both the unions of string literals and an array with the same strings:

type PostType = 'article' | 'podcast';
const postTypes = ['article', 'podcast'];

This duplication is error prone in case a new option needs to be added, removed and the like. So I was searching for a means to either derive the array from the type or the type from the array.

With lookup types this is exactly possible:

const postTypes = ['article', 'podcast'] as const;
type PostTypes = typeof postTypes[number];

First typeof in combination with as const is used to infer the type of the defined array. as const is important here as Typescript otherwise defines the type as Array<string> instead of an array of string literals.

Using indexed access types/lookup types gives the union of string literals. This is somehow equivalent to using an index in an "normal" Javascript/Typescript to get a specific element like list[0].

Lookup types can be used for more sophisticated use case e.g. like deriving all properties in an object the values of which are e.g. a string:

type Author = {
  firstName: string;
  lastName: string;
};
type Post = {
  title: string;
  description: string;
  views: number;
  author: Author;
};

type PostStringKeys = {
  [P in keyof Post]: Post[P] extends string ? P : never;
}[keyof Post];

Let's quickly break this down:

P keyof Post gives all keys of Post (title and description).
Post[P] extends string ? P : never checks if the value of property P in Post is of type string. If true the property name is set as value otherwise the property is not included in the newly created type.
With the help of lookup types the union of property names/string literals is derived using keyof Post.
- The set of keys in Post is a superset of the keys of the derived type and can therefor be used as an index

This can be made generic like so:

type KeysOfType<T, K> = { [P in keyof T]: T[P] extends K ? P : never }[keyof T];

type PostStringKeys = KeysOfType<Post, string>;
type PostNumberKeys = KeysOfType<Post, number>;

Compare to the previous example T == Post and K == string. This provides the additional possibility to include properties with different value types like string and Author using unions.

type PostStringAndAuthorKeys = KeysOfType<Post, number | Author>;

The code snippets can be found here.

That's it and as always, thanks for reading.

Racing condition in RxJs event order (with multiple subscriptions)

Mathias Remshardt — Tue, 31 Aug 2021 17:03:08 +0000

This is another short article about a "strange issue while working on a project" which took me a while to resolve.
The problem was that the order of events got mixed up in a observable chain, so the first event arrived after the second one (and no there were no http calls or other async operations involved).
As it is hard to explain just in words I created a simplified example application to better show the issue (and help me figure out the root cause).

Example application

Components

The main components and dependencies are:

TasksService
- Stores tasks (a task is a string to keep it simple) in a ReplaySubject which is accessible to other components by the tasks$ property.
- Contains a setTasks method as a means for other components to update the tasks.
TasksFilterService
- Stores a filter pattern (again a simple string) to match against the stored tasks.
- Subscribes to tasks$, filters the received tasks and updates tasks$ in TasksService by calling setTasks$
- An infinite loop is avoided by using distinctUntilChanged --> so tasks$ is only updated in case the filter pattern does lead to a change in the current list of tasks
Component
- Subscribes to tasks$ and tasksFilterPattern$ to derive a areTasksValid$ property. Tasks are considered valid if all of them are matching against the filter pattern. In contrast to what is done in TasksFilterService it only checks the list of tasks but does not perform any update in TasksService.
Template
- Subscribes to areTasksValid$ and renders the boolean value using the async pipe.

When looking at the structure some may spot the circular dependency between TasksService and TasksFilterService.
TasksFilterService filters (based on the set filter pattern) and updates the tasks in TasksService whenever tasks$ emit. To avoid an infinite loop the TasksFilterService should only perform the update in case the filtered list is different to the current one. As mentioned above this can be done using distinctUntilChanged.

Implementation

The Component sets the tasks filter pattern on init and updates the tasks after two seconds using setTimeout.
As both the Component as well as the TasksFilterService subscribe to task$ my initial guess was that there are two routes the application can take when setTimeout is triggered:

Tasks are first received by the Component:
1. The Component checks if tasks are valid which is then displayed in the Template (areTasksValid$).
2. Next TasksFilterService filters and updates the tasks. The second emit of tasks$ does not lead to another update due to distinctUntilChanged.
3. The Component receives the filtered tasks which are again displayed in the Template.
Tasks are first received by the TasksFilterService
1. Same as step 2 in the first option (TasksFilterService updates the task list)
2. Component first receives the unfiltered list of tasks and checks for their validity. Next the filtered tasks are received (set in step 1) and again checked against the current filter pattern.
3. As the complete execution is synchronous the change detection runs once and the result from the last task list processed is displayed in Template.

As it turned out none of these routes are taken. What actually is executed:

Tasks are received by the FiltersService, filtered and updated
Second emit of tasks$ is ignored in FiltersService (due to not having changed)
Component first receives filtered tasks list and then the unfiltered one
Template renders the final value

The actual sequence is pretty close to the second guess. The important difference (marked in bold) is that the tasks received by Component are out of order. As shown in the sequence diagram below, the filtered tasks list comes before the unfiltered one. My assumption was that the order of events is guaranteed, so I expected the Component to receive the task lists in the order these have been set in TasksService (the initial list before the filtered one).

This explained the bug I was facing in my project where one of the Components was rendering outdated/old values.
Basically one cannot assume emissions to be in order in case of multiple subscriptions to the same Observable where one of them is again updating the source stream (tasks$ in the example). Of course, the problem only occurs in case processing and updating the streams happens within the same tick of the event loop.

The sequence diagram below shows what has been described above.

In addition there have been log statements added indicating where and when the task list update is processed (triggered by setTimeout).

The result rendered in the Template is false because the final list received is the unfiltered one and therefor not valid for the applied task filter pattern.

Solutions

I could come up with two options to guarantee the order of the task list received by Component:

Directly perform the filtering in FiltersService so that only the already filtered task list is emitted.
Put the update in TasksFilterService on next tick of the event loop. This can be done by using any of the available asynchronous schedulers (like asapScheduler or requestAnimationFrameScheduler). That way it is guaranteed that the filtered task list is emitted after the initial one. In contrast to the first solution it does lead to both tasks list being emitted and, depending on which async scheduler is chosen, two change detection cycles.

To me the first solution has the advantage it is easier to understand and straight forward. In contrast the second solution has the benefit of clearly separating the concern of storing tasks and filtering.

In my project I opted for the second solution since there was a lot more going on in the services and migrating everything into one would have lead to a huge class and a (more) severe violation of Separation of Concerns.

Both versions are implemented in the example application and can be tested by commenting in the associated component in app.component.html. app-tasks-scheduled represents the scheduled implementation and app-tasks-single-stream the version directly filtering in TasksService.

Thanks for reading.

Optional content projection/injection in Angular

Mathias Remshardt — Sat, 08 May 2021 11:23:10 +0000

Optional content projection/injection in Angular

Recently I had the requirement to make part of a component (the header of a custom table) replaceable with custom content. In case nothing is provided the implementation was supposed to render "default" content. A simple property was not sufficient as the injected/projected content could be anything ranging from simple text to a slider/toggle...

The requirements could be summarized as follows:

Render custom content in case it is provided
Render default content otherwise

I was torn between using ng-content or ng-template to solve the problem. To make an informed decision I created a POC implementing both options to see if one is superior to the other. In contrast to the requirements, the created POC allows for replacing multiple contents (like a header and a footer) to verify that the solution could be extended in the future (if needs arise). The next sections describe the alternatives I could come up with.

ng-content

This is usually the first option as it is simple to implement and use. The custom contents are provided as children using ng-content. By using a select attribute multiple contents can be projected as well:

<ng-content select="[slot='header']"></ng-content>
<ng-content select="[slot='footer']"></ng-content>

This covers the first requirement. The second is more difficult to realize using ng-content alone. The figure out whether to render the custom or default content requires some means to determine if something has been passed as ng-content or not. I was not able to find any build-in feature to query/get that information from the component or template so a custom solution is required.

One option is to create a directive which is put on the content to be projected (appSlot in the example below):

<app-render-slot>
  <div appSlot slot="header">Custom Header</div>
  <div appSlot slot="footer">Custom Footer</div>
</app-render-slot>

The component can search for the directive(s) using a @ContentChildren query. In case something is found for the placeholder the custom content is used, otherwise it falls back to the default content:

@Component({
  selector: 'app-render-slot',
  templateUrl: './component.html',
  styleUrls: ['./component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class RenderSlotComponent {
  @ContentChildren(SlotDirective, { read: ElementRef }) set slotDirectives(
    value: QueryList<ElementRef>
  ) {
    this.nativeSlots.next(Array.from(value));
  }

  private nativeSlots: BehaviorSubject<Array<ElementRef>>;
  readonly slotNames$: Observable<SlotNames>;

  constructor() {
    this.nativeSlots = new BehaviorSubject<Array<ElementRef>>([]);

    this.slotNames$ = this.setSlotsByName(this.nativeSlots.asObservable());
  }

  isSlotSet(slotName: SlotName): Observable<boolean> {
    return this.slotNames$.pipe(
      map((slotNames) => slotNames.includes(slotName))
    );
  }

  private setSlotsByName(
    slots$: Observable<Array<ElementRef>>
  ): Observable<SlotNames> {
    return slots$.pipe(
      map((slots) =>
        slots.map((slot) => slot.nativeElement.getAttribute('slot'))
      )
    );
  }
}

For the example, the "name" of the slot ("header" or "footer") is extracted based on what has been set for the custom "slot" attribute on the projected content. The ElementRef to look for is marked/identified by the SlotDirective and extracted with the @ContentChildren query. The other part of the implementation just maps the list of ElementRefs to the slot names.

With help of the isSlotSet method, the template can either render the custom content (in case the slot is found) or fall back to a default content.

For the sake of the example, the template of the component is kept simple containing only the ng-content placeholders:

<ng-content
  select="[slot='header']"
  *ngIf="isSlotSet('header') | async; else defaultHeader"
></ng-content>
<ng-content
  select="[slot='footer']"
  *ngIf="isSlotSet('footer') | async; else defaultFooter"
></ng-content>

<ng-template #defaultHeader> Default Header </ng-template>
<ng-template #defaultFooter> Default Footer </ng-template>

The alternative described here can be found in the ng-content/render-slot folder in the example repository. When removing either the "Custom Header" or "Custom Footer" div in the AppComponent template for app-render-slot the default fallback will be rendered.

with SlotRenderer

Heads up: This solution does not work, so please skip ahead in case not of interest.

The approach described above has the disadvantage that each component with optional content projection does have to implement the mechanism to find/determine the rendered content.

My idea was to improve the solution by creating a "helper" component called SlotRendererComponent, which would be responsible for rendering the content passed by the using component:

<app-slot-renderer [defaultSlotContent]="defaultHeader"
  ><ng-content select="[slot='header']"></ng-content
></app-slot-renderer>
<app-slot-renderer [defaultSlotContent]="defaultFooter"
  ><ng-content select="[slot='footer']"></ng-content
></app-slot-renderer>

<ng-template #defaultHeader> <div>Default Header</div> </ng-template>
<ng-template #defaultFooter> <div>Default Footer</div> </ng-template>

The custom content gets provided using ng-content and the select attribute (the latter could be omitted in case there is only a single ng-content to project). The default content is passed as TemplateRef using an Input property.

The SlotRendererComponent also uses ng-content to render what has been projected from the using component which would be

<ng-content *ngIf="isSlotSet$ | async; else defaultSlotContent"></ng-content>

The custom content originally passed is therefore projected twice:

First to the outer component (RenderSlotSlotRendererComponent in the example)
Second to the SlotRendererComponent

The flattened hierarchy looks something like this (not the real DOM structure):

<!-- From SlotRendererComponent  -->
<ng-content *ngIf="isSlotSet$ | async; else defaultSlotContent">
  <!-- From RenderSlotSlotRendererComponent  -->
  <ng-content select="[slot='header']">
    <!-- Projected custom content   -->
    <div appSlot slot="header">Custom Header</div>
  </ng-content>
</ng-content>
<!-- Same for the footer -->

By the same mechanism as in the first approach, the custom or default content will be rendered by SlotRendererComponent.
The reason why this solution is not working is due to @ContentChildren not being able to query nested ng-contents. Setting { descendants: true } also did not work for me. I found an issue describing the problem for the AngularDart repository so maybe it is related (or I am doing something wrong here ;) ).

ng-template

with template properties

One option for the ng-template based solutions is to directly pass the custom contents in a property as TemplateRefs.

<app-template-render-props
  [templates]="{ 'header': header, 'footer': footer }"
></app-template-render-props>

<ng-template #header><div>Custom Header</div></ng-template>
<ng-template #footer><div>Custom Footer</div></ng-template>

The provided TemplateRef for each slot is rendered using *ngTemplateOutlet. Same as for the ng-content approach the component falls back to a default content in case nothing has been defined (done by the RenderTemplateComponent helper in the example).

<app-render-template
  [template]="{ customTemplate: templates.header, defaultTemplate: defaultHeader }"
></app-render-template>
<app-render-template
  [template]="{ customTemplate: templates.footer, defaultTemplate: defaultHeader }"
></app-render-template>

<ng-template #defaultHeader> <div>Default Header</div> </ng-template>
<ng-template #defaultFooter> <div>Default Footer</div> </ng-template>

with directive

Having to define a dedicated ng-template wrapper for each custom content is inconvenient to use and clutters the template of the using component. This can be avoided by using a structural directive storing the TemplateRef as well as the slot name:

@Directive({
  selector: '[appTemplateSlot]'
})
export class TemplateSlotDirective {
  @Input() appTemplateSlot: SlotName | null = null;

  constructor(public template: TemplateRef<unknown>) {}
}

The directive takes the slot name ("header" or "footer" in the example) as input property and stores the associated TemplateRef in a public template property (the unknown type of TemplateRef could be replaced by the associated context in case it is known/available).

The rendering component can now query for the TemplateSlotDirectives using @ContentChildren and render the stored template to the associated slot:

@Component({
  selector: 'app-render-props-directive',
  templateUrl: './component.html',
  styleUrls: ['./component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class RenderPropsDirectiveComponent {
  @ContentChildren(TemplateSlotDirective) set templateSlots(
    templateSlots: QueryList<TemplateSlotDirective>
  ) {
    this.templateDirectives.next(
      templateSlots.length > 0 ? Array.from(templateSlots) : []
    );
  }

  private templateDirectives: ReplaySubject<Array<TemplateSlotDirective>>;
  templates$: Observable<Partial<Templates>>;

  constructor() {
    this.templateDirectives = new ReplaySubject(1);

    this.templates$ = this.setupTemplates(
      this.templateDirectives.asObservable()
    );
  }

  private setupTemplates(
    templateDirectives$: Observable<Array<TemplateSlotDirective>>
  ): Observable<Partial<Templates>> {
    return templateDirectives$.pipe(
      map((templateDirectives) =>
        templateDirectives.reduce(
          (partialTemplateDirectives, templateDirective) =>
            templateDirective.appTemplateSlot
              ? {
                  ...partialTemplateDirectives,
                  [templateDirective.appTemplateSlot]:
                    templateDirective.template
                }
              : partialTemplateDirectives,
          {}
        )
      ),
      shareReplay({ bufferSize: 1, refCount: true })
    );
  }
}

As usual the rendering component now either renders the custom or fallback content for each slot:

<app-render-template
  [template]="{ customTemplate: (templates$ | async)?.header, defaultTemplate: defaultHeader }"
></app-render-template>
<app-render-template
  [template]="{ customTemplate: (templates$ | async)?.footer, defaultTemplate: defaultHeader }"
></app-render-template>

<ng-template #defaultHeader> <div>Default Header</div> </ng-template>
<ng-template #defaultFooter> <div>Default Footer</div> </ng-template>

As shown below the ng-template wrapper is now replaced by putting the TemplateSlotDirective selector on the the custom content:

<app-render-props-directive>
  <div *appTemplateSlot="'header'">Custom Header</div>
  <div *appTemplateSlot="'footer'">Custom Footer</div>
</app-render-props-directive>

Conclusion

With both the ng-content as well as the ng-template it was/is possible to fulfill the requirements to either display custom content or fall back to rendering a default.
I prefer the ng-template based solution as:

When used with a structural directive provides the same ease of use as ng-content for the using component (especially within the template).
It allows for extracting all the repetitive rendering related implementations which can be reused for components requiring the same "feature". This is/was not possible for the ng-content based solution due to the issue with querying nested ng-contents using @ContentChildren.

The complete code for the POC can be found here.

Custom build configurations for testing and debugging in iOS/Xcode

Mathias Remshardt — Wed, 28 Apr 2021 17:46:24 +0000

When debugging one of my unit tests I coincidentally noticed that the complete start-up procedure/code was running before the unit tests get executed. With my web development background, this was somehow surprising to me as I expected only the class/method... referenced by the test suite being run. After taking some time to think about it this makes a lot of sense as the tests are run e.g. on a simulator where the application first needs to be installed and started before the tests run.

This means that any side effects at application start e.g. an HTTP call is also triggered when any unit test gets executed. Even though this did not lead to any unwanted side effects in my particular case I felt uneasy about the requests being performed. So I was looking for some means to exchange the "production" implementation with a version suitable for test runs or debugging.

For the unit tests, I already relied on constructor-based dependency injection to pass stubs/mocks to avoid unwanted side effects and/or return test data. However, this only covered the dependencies for the subject under test, but not whatever is executed at application start.
Having dependency injection already in place I just required some means to "determine" at compile and/or runtime if the problematic dependencies should be replaced by e.g. a test- or in-memory version.

The idea was to define a "mode" like test or production which could be derived and set at application start.

Build Configuration based dependency injection

When creating a new project in XCode it also defines build configurations like DEBUG and RELEASE which can be used in combination with preprocessor macros to include different code sections depending on the configuration the build is executed with.

This seems to be often used e.g. to exclude SwiftUI previews from release builds or define a different PersistenceController when working with CoreData.

Schemes can then be used to set unique build configurations e.g. for Run or Test. This seemed to be sufficient to solve my test run dependency issues.

Using the DEBUG flag was one option but would also replace the release dependencies with the test/in-memory versions for debug runs on the simulator/real device (something I did not want). So a dedicated Test configuration would allow for having different dependencies injected during debug- and test runs.

As it turned out creating and using such a custom configuration requires three steps:

Creating a custom build configuration and configuring the Active Compilation Conditions
Injecting dependencies based on the configuration selected
Creating/updating the Xcode scheme for Run and Test

Build configurations and Active Compilation Conditions

First a new custom Build Configuration is required, which can be created in the project settings Info tab by duplicating from the e.g. Debug configuration:

Next a new entry for Active Compilations Conditions needs to be added for Test which can be done in the Build Settings Tab. It made sense to me to set TEST as well as DEBUG for the Test build configuration to make sure everything applied to Debug is also applied for Test (in addition to what is defined for Test).

Having it setup like this the TEST flag is now available (in addition to DEBUG and RELEASE) for usage in preprocessor macros.

Build Configuration based injection

Using macros alone, it is already possible to switch between different dependencies based on the active build configuration:

private static func makeTodosRepository() -> TodosRepository {
  #if TEST
  return InMemoryTodosRepository()
  #else
  return ProductionTodosRepository(host: "https://jsonplaceholder.typicode.com")
  #endif
}

I did not want to use a macro wherever configuration specific code is required. So I next created a swift enum reflecting all application modes. The mode is determined at startup and made available as shared global property (same as it is often done e.g. for the PersistenceController and CoreData):

enum ApplicationMode: String {
  case release
  case test
  case debug
}


#if TEST
let mode = ApplicationMode.test
#elseif DEBUG
let mode = ApplicationMode.debug
#else
let mode = RunningMode.release
#endif

To me, the approach has the advantage that Swift language features can be used when working with the configuration. It also decouples the application running mode from the build configurations (in case necessary for any reason).

The global available application mode property can next be combined with any dependency inject approach (e.g. like the Single-container approach), restricting the configuration dependant implementations to a few dedicated classes:

protocol TodosRepository: ListTodos {}

class AppContainer: ObservableObject {
  private let todosRepository: TodosRepository
  private let todosContainer: TodosContainer

  init() {
    todosRepository = AppContainer.makeTodosRepository()
    todosContainer = AppContainer.makeTodosContainer(listTodos: todosRepository)
    Logger().debug("Application running in mode: \(mode.rawValue)")
  }

  func makeTodosContainer() -> TodosContainer {
    todosContainer
  }

  private static func makeTodosRepository() -> TodosRepository {
    switch mode {
    case .test:
      return InMemoryTodosRepository()
    default:
      return ProductionTodosRepository(host: "https://jsonplaceholder.typicode.com")
    }
  }

  private static func makeTodosContainer(listTodos: ListTodos) -> TodosContainer {
    TodosContainer(listTodos: listTodos)
  }
}

extension ProductionTodosRepository: TodosRepository {}
extension InMemoryTodosRepository: TodosRepository {}

Schemes

To make it all work for test runs the build configuration is set to Test for the Test step:

If everything has been wired up correctly the application should now use the Test dependencies on test startup (at least mine did ;) ).

Conclusion

The short article described how to exchange dependencies based on tags by:

Defining a custom build configuration and Active Compilation Conditions property
Injecting dependencies based on the application running mode derived from the active build configuration
Creating/Updating a scheme to run the tests with the custom build configuration

This now allows for having different dependencies during test and debugging sessions. In case of interest, a small example application using the approach can be found on Github.

Environment Variables

As explained here exchanging dependencies only requires different behavior and not different compilation, so environment variables read at runtime could be a solution as well.

I opted against such an approach as the variables are set for all build configurations and therefore need to be manually switched on/off depending e.g. when running tests or debugging.

Besides the advantage of not having to recompile the application when changing the variable was not relevant for my use case/problem.

Rolling (up) a multi module system (esm, cjs...) compatible npm library with TypeScript and Babel

Mathias Remshardt — Sun, 07 Feb 2021 16:16:18 +0000

In this article we will delve into the build chain and build steps necessary to create the artifacts required to publish a library on npm. Our goal will be to provide our library consumers with a versatile package supporting (modern/legacy) JavaScript/TypeScript as well as the most common module systems.
What has been written is based on my learnings and research when creating packages and is also meant to be documentation for myself. The process is still in flux, so every feedback (ideas for improvements, critics...) is, as always, very welcome.

Overview

The first section lists and explains the requirements for the build process as well as the artifacts it produces. Related to this, we will also answer the question if a bundled version is required for each of the supported module systems.

With the requirements ready, the build chain and, most important, the steps for creating the necessary library artifacts will be laid out.

As demonstration defeats discussion, we will look at the implementation of the sketched out build chain with help of an example "library". In the end there will be a deployment ready package, hopefully fulfilling all listed requirements.

As our focus lies on packing itself, the "features" of the example library are irrelevant and are therefore kept extremely simple.

The explanations provided are based on my current understanding of the topics and may be opinionated or incomplete (hopefully not wrong). In addition, every package is unique and therefor its/your requirements and the resulting process can differ from what has been written here. However, I have tried to keep the information as overall applicable as possible. As mentioned in the beginning, feed back is very welcome.

That being said, let's start with the requirements for our build artifacts.

Requirements

JavaScript/TypeScript

To me, one important goal was to make the modernly written, not transpilled library code available for further processing. This helps e.g. to decrease bundle sizes, as downstream consumers can base their build chain on the most current/common JavaScript version and only transpile the code to the language level required by their browser- or node version needs.

However, for consumers not able to leverage modern JavaScript, an ES5 based version sacrificing the latest features must be provided.

In case TypeScript is used, a transpilled JavaScript version should be supplied as well, so we do not enforce unnecessary restrictions to consumers by our language choice. "Types" will be provided as separate type definition files.

Module system

Next to modern JavaScript, the library must support all current/common module systems. At the time of writing these are "ECMAScript Modul" (esm), "CommonJs" (cjs) and "Asynchronous Module Definition" (AMD).

Especially supporting esm is important to allow tree shaking support for consumers using bundlers like Rollup or webpack. So even when transpilled to legacy JavaScript, leveraging esm is still beneficial (as described here).

To bundle or not to bundle...

Bundling is usually applied when writing JavaScript for the client (e.g. Single Page Applications) as it avoids too many round trips to the server (especially before HTTP/2 arrived) by delivering everything in a single file. However, with multiplexing and server side push now being available in HTTP/2, the questions is a bit more controversial today.

If we take into account that downstream build systems further process and bundle the library code, the npm package should contain an unbundled artifact for all supported module systems with the most modern JavaScript version possible. This gives our consumers the flexibility to shape the library code based on their needs (e.g. supported browser versions) helping them to reduce the amount of shipped code by avoiding e.g. unnecessary transpilling.

So if the library code is further processed by downstream consumers, one may ask the question if we need to create a bundled version at all? I sifted through different (popular and not so popular) npm packages and some of these are bundling, while others are not. Also reading blog posts and tutorials did not give a unambiguous answer, leaving me more confused then before.

Therefor I decided to look at each module system individually combined with whether it is used on the client or server. My hope was that I'd find some enlightenment when narrowing done the question...
Next you find the reasoning I finally came up with.

ECMAScript Modules

Browser

When esm based library artifacts are consumed by e.g. SPAs something like webpack or Rollup should be in place. Further processing, like tree-shaking, bundling, minifying..., is therefor better left to the downstream build process.

So I originally decided not to include a bundled esm version. But, when reading about the reasoning for providing a bundled umd artifact (described in the section below) I thought about doing the same for esm. It does sound counterintuitive at first, I mean what benefit do we get from a modern module system when everything is bundled to a single file. What we do get however, is all the modern JavaScript available for library code written in ES6+ syntax. This means modern browser can choose the bundled esm version instead of umd for direct import, avoiding all the additional code created to make our library code compatible with previous JavaScript versions. One could argue that in such a case the unbundled artifact could be imported. However, there still could be use cases for the bundled alternative e.g. in case HTTP/2 is not available and therefor loading a lots of files is not a performant option.

Node

In case the server application uses a current node version, same reasoning as for the browser applies.

However, the server can directly load the files from disk which should have almost no performance impact compared to the http request the browser has to perform. So I don't see any reason for using the bundled version here, even if no additional build process is in place.

CommonJs

Browser

Same arguments as for esm: Bundling should not be required as the imported library is always further processed by downstream build systems.
The only reason why client applications could/should use the cjs instead of the esm version is in case of an older bundler which does not understand the latter. In all other cases esm is the preferred option as the tree shaking support is superior to cjs.

Node

Again no difference to esm. However, by including a cjs version we ensure older node versions are also supported, so no additional/extra transpilling step is required for library consumers.

UMD

We will discuss the bundling question for umd instead of amd, as the latter supports both amd and cjs in a single artifact.

Browser

For me, the bundling question was a bit harder to answer for umd, as I have most often worked in environments (usually SPAs) where either cjs and/or esm has been used in combination with a dedicated bundler.

The reason for including a bundled umd version is to support direct usage (with no further processing) in (older) browsers e.g. from something like unpkg. Modern browser, as described above, can use the bundled esm version.

However, when a bundling step is performed downstream, it should always either use esm or cjs making an unbundled version superfluous.

Node

Node can always use either esm or cjs. So in case these are included in the npm package there seems to be no reason to provide a special, unbundled umd version for node. It provides no benefit over the bundled variant already considered required in order to cover all use cases.

My final impression regarding umd and server applications is, that it makes sense if one wants to include only a single version of the library. However, since npm packages and bundlers (now) support including multiple versions and creating these is not much effort, there seems to be no reason for restricting library consumers to just umd.

Conclusion

This brings us the conclusion that a bundled version is only required for esm and umd. For all other module system bundling is not a necessity, which finally leads to the following list of library artifacts:

an unbundled esm version
an bundled esm version
an unbundled cjs version
a bundled umd version

These four variants should cover most of our consumers use cases without restricting their build processes and, most importantly, not forcing them to ship unnecessary JavaScript code.

Having the bundle/not bundle question out of the way, we will next define the build chain and its steps to create the listed artifacts.

Build chain

The diagram below gives an overview of the steps required to go from our written source code (TypeScript for the example library) to the artifacts described in the previous section. The image also shows how the created results are referenced in the package.json. This is important as it makes downstream bundlers "aware" of the available versions allowing them to choose the most appropriate one (e.g. esm over cjs for better tree shaking support).

Diagrams often read kind of abstract before knowing the details and this one is no exception. Therefor, when next going through the process and its artifacts, excerpts from the example library (e.g. configuration files) are referenced to provide additional details.

One note regarding the employed build tools mentioned in the diagram: I tried to use the most common ones for this/my build chain fulfilling the requirements listed earlier. These can of course be replaced by your own choice e.g. tsc instead of babel when compiling TypeScript.

Building the library artifacts

The build steps next described need to get us from our source to the four target build artifacts defined in the previous section. For the example application this means going from TypeScript to esm (bundled and unbundled), cjs (unbundled) and umd (bundled).

The two main steps required are transpilling and bundling. The latter is of course only needed when the final build artifact is a bundle.

Transpilling

With the example application written in TypeScript, our first step is to go to the target JavaScript versions. Usually this can either be done by using tsc or, as of late, babel (with help of the @babel/typescript plugin).

I opted for the latter as it, in my opinion, provides more flexibility compared to tsc when configuring the transpilation/compilation step (e.g. tsc requires a specific target JavaScript version where as in babel it can be defined based on browsers market share, versions and the like). In addition, with the support of TypeScript in Babel, we can now use almost the same build chain for JavaScript or TypeScript projects helping to unify/simplify the process.

The exact Babel configuration is somehow specific for each individual library/project and/or requirements. For the example library we only require two babel plugins:

@babel/typescript: To go from TypeScript to JavaScript
@babel/env: To get down to the JavaScript version fulfilling the configuration we opted for (e.g. supported browsers and node versions)

A description of the two plugins and the available configurations is out of scope of the article. Therefor, I only quickly note why a property has been set like that and the reasoning behind it.

Especially the @babel/env plugin provides a lot of flexibility, so in case you are interested in more details the two provided links should make for a good starting point.

Having that said, the configuration for the example library looks like the following:

const sharedPresets = ['@babel/typescript'];
const shared = {
  ignore: ['src/**/*.spec.ts'],
  presets: sharedPresets
}

module.exports = {
  env: {
    esmUnbundled: shared,
    esmBundled: {
      ...shared,
      presets: [['@babel/env', {
        targets: "> 0.25%, not dead"
      }], ...sharedPresets],
    },
    cjs: {
      ...shared,
      presets: [['@babel/env', {
        modules: 'commonjs'
      }], ...sharedPresets],
    }
  }
}

We are using three Babel environments here:

esmUnbundled: The environment only goes from TypeScript to JavaScript and keeps the rest of the code in place. This is on purpose as it makes the most modern version of the library available to our consumers for further processing.
esmBundled: In addition to what is done in unbundled, the bundled environment transpiles to JavaScript supported by the majority of browsers/node versions. I opted against transpilling completely down to ES2015 as older browser can use the umd alternative when directly importing the library.
cjs: Again, the environment is similar to es-unbundled, with the only difference that esm is replaced by commonjs with the help of @babel/env

To execute the Babel transpilation, two scripts have been defined in the package.json:

{
  ...
  "build:esm": "cross-env BABEL_ENV=esmUnbundled babel src --extensions '.ts' --out-dir 'lib/esm' --source-maps",
  "build:cjs": "cross-env BABEL_ENV=cjs babel src --extensions '.ts' --out-dir 'lib/cjs' --source-maps"
  ...
}

At the time of writing, source maps seem not to be generated when configured in .babelrc which is why --source-maps has been added.

Running the scripts gives the following result:

Unsurprisingly, the esm folder contains the unbundled esm and cjs the unbundled cjs artifact.

For the unbundled case we are almost done. What is missing is a reference to our index.js entry files from to package.json to make Bundlers aware of the available versions.

As described in detail here we need to:

Set the main property to our cjs index.js and the module property to the esm index.js
Set the appropriate properties in exports
- require again to the cjs index.js
- import again to the esm index.js

{
  ....
  "main": "lib/cjs/index.js",
  "module": "lib/esm/index.js",
  "exports": {
    "require": "./lib/cjs/index.js",
    "import": "./lib/esm/index.js"
  }
  ....
}

Having the package.json setup like that, Bundlers can now choose whatever alternative is best supported. For example modern ones can take the esm artifact whereas as older ones (not supporting the new module and exports property) fall back to what is referenced in main.

To finalize our package we will next look how to generate the bundled artifacts for esm and umd.

Bundling

To bundle our library we need a ... Bundler. I chose Rollup for the job since it has good support for creating different versions for each module system from a single entry file. Of course it can again be replaced by whatever Bundler you prefer as long as it bundles to the required module systems and also comes with a plugin for the Transpiler, Terser... of your choice.

As shown in the overview from the beginning of this section, there is not much difference between the build steps of the unbundled and bundled versions:

the Bundler takes care of orchestrating the build process and build tools (like the Transpiler), so no need to call these "individually"
an additional bundling step is added to the end of the build chain

For the example library, the Rollup configuration looks like this:

import babel from '@rollup/plugin-babel';
import resolve from '@rollup/plugin-node-resolve';
import { terser } from "rollup-plugin-terser";

const extensions = ['.js', '.ts' ];

export default  {
  input: 'src/index.ts',
  output: [
    {
      file: 'lib/bundles/bundle.esm.js',
      format: 'esm',
      sourcemap: true
    },
    {
      file: 'lib/bundles/bundle.esm.min.js',
      format: 'esm',
      plugins: [terser()],
      sourcemap: true
    },
    {
      file: 'lib/bundles/bundle.umd.js',
      format: 'umd',
      name: 'myLibrary',
      sourcemap: true
    },
    {
      file: 'lib/bundles/bundle.umd.min.js',
      format: 'umd',
      name: 'myLibrary',
      plugins: [terser()],
      sourcemap: true
    }
  ],
  plugins: [
    resolve({ extensions }),
    babel({ babelHelpers: 'bundled', include: ['src/**/*.ts'], extensions, exclude: './node_modules/**'})
  ]
}

There is nothing too fancy going on:

The input property points to the entry index.ts and output defines the configurations for both esm (normal/minified) and umd(normal/minified). Additionally, the sourcemap attribute has been added and set to true to create external source map files. The name property for the umd version defines the namespace for the exported functions (e.g. myLibrary.echo() for the example library).

For the build itself we require three plugins:

@rollup/plugin-node-resolve: The plugin adds support to resolve imports to other node packages. This is not required for the example library (as no other dependency is used) but has been added since it is not unlikely to occur for more complex packages.
@rollup/plugin-babel: Triggers the transpile step through Babel (basically what we have done by means of the babel-cli for the unbundled versions). As we are using babel only for the bundled artifacts babelHelpers are set to bundled, so in case any helpers are needed these are added to the bundle file (you can read more about the property in the documentation). In include and extensions the files and their extensions (ts/js for the example library) to process are defined, whereasexcludes indicates folders/patterns which should be skipped (just the node_modules folder for the example library).
rollup-plugin-terser: Used for minification and therefor only added for the minified outputs. This is optional and can be left out in case not wanted or required.

Executing the Rollup process by using the added package.json script build:bundles produces the following result:

An new folder bundles has been created containing the esm and umd artifacts. In contrast to the unbundled ones, there is no need/means to reference the former from the package.json as these will be directly imported and are not meant for further processing.

We now have all required "code" artifacts available for the package. The last thing missing is creating type definitions, so that clients using TypeScript can easily integrate the library.

Types

Babel currently "only" transpiles our TypeScript code to JavaScript. Therefor, as shown in the overview diagram, a dedicated build step is required for creating the type definition files using tsc.

As we already have the transpiled JavaScript code, our tsconfig.json can be kept pretty simple:

{
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "declarationMap": true,
    "outDir": "lib/types",
  },
  "include": [
    "./src/index.ts"
  ],
}

With the declarations and emitDeclarationOnly set to true, tsc only creates declarations files and skips transpilling to JavaScript. The result is then put into the folder defined by outDir.

We also should not miss to create mappings between the *.d.ts and *.ts files, enabling IDEs like VSCode or IntelliJ to navigate directly to the source instead of the declarations files e.g. on CMD + click/Strg + click on a method or property name. This is simply done by adding the declarationMap to the tsconfig.json and setting it again to true.

The script declarations has been added to the package.json to trigger tsc, which will create the declaration files in the types folder (as defined by outDir):

As a final step we link the index.d.ts file in the package.json by means of the types property, helping IDEs to discover the types:

{
  "types": "lib/types/index.d.ts"
}

With the unbundled-, bundled library versions and type declarations created, we now have a library ready for being published on npm. Since there are numerous posts out there explaining this final step (and the example application is pretty useless) we will not go further into this.

So time for wrapping up...

Conclusion

The goal for this article was to create a versatile build chain to allow creating libraries that:

provide raw, non transpilled artifacts based on modern JavaScript or TypeScript which can be further processed by downstream build chains
provide an unbundled- (for consumers using Bundlers) and bundled (for direct usage/import) version
support all modern and legacy module systems

With the listed requirements ready, we sketched the build steps and setup necessary to create our library artifacts.

To make the theoretical overview more tangible the process has been described based on a simple example library. This included a possible choice of tools required to realize the build chain and creating the artifacts necessary to fulfill our initial goals.

Appendix

Testing locally

To test the example library locally I have created a separate "testing repository". The setup and link procedure is as follows:

Example Library
- Run npm install
- Run npm run build
Testing Repo
- Use npm link to link to the locally available example library e.g. in case both projects are siblings in the folder structure the command is npm link ../node-module-esm (a more detailed description can be found e.g. here)
- Run npm install
- Run npm start (this starts a local http-server)
- Open localhost:8080 in the browser of your choice
- Navigate to src
- The then opened index.html includes imports of umd bundled, esm bundled and esm unbundled from the example library giving the following result:

File replacements when building angular projects

Mathias Remshardt — Sat, 16 Jan 2021 17:11:01 +0000

This short article is about replacing files (e.g. configuration files) for different build configurations/targets (like dev, qa and prod) in Angular. For our projects we used to leverage the Angular file replacements feature to provide different files based on the chosen build target:

{
  "production": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.prod.ts"
      },
      {
        "replace": "src/configurations/configuration.json",
        "with": "src/configurations/configuration.prod.json"
      }
    ]
  },
  "dev": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.dev.ts"
      },
      {
        "replace": "src/configurations/configuration.json",
        "with": "src/configurations/configuration.dev.json"
      }
    ]
  },
  "qa": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.qa.ts"
      },
      {
        "replace": "src/configurations/configuration.json",
        "with": "src/configurations/configuration.qa.json"
      }
    ]
  }
}

However, file replacements outside of bundles were never officially supported by Angular and has ceased to work since the Angular 9 release as described here.
We have migrated to the proposed workaround in the linked Github issue and it is working fine for us so far. In case someone has the same issue/question (and also to document the approach for myself ;) ), I have created a simple example repository showcasing the approach for a single configuration.json file.
The following section shows the required steps.

Configuration Folder

In the example, a dedicated folder holding the different configurations has been created. This is not necessarily required but keeps the files organized. Next, each configuration target has an associated folder containing the configuration.json. The additional folder is indeed required as otherwise it is not possible to select and copy the correct file (described in the next section).
At the end it looks something like the following:

Angular CLI configuration file (angular.json)

As shown in the snippet below, for each of the deployment configurations the associated configuration.json is copied as part of the assets section:

{
  "production": {
    "assets": [
      "src/favicon.ico",
      "src/assets",
      {
        "input": "src/configurations/prod",
        "output": "configuration/",
        "glob": "*.json"
      },
      {
        "input": "src/configurations",
        "output": "configuration/",
        "glob": "README.md"
      }
    ],
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.prod.ts"
      }
    ]
  },
  "dev": {
    "assets": [
      "src/favicon.ico",
      "src/assets",
      {
        "input": "src/configurations/dev",
        "output": "configuration/",
        "glob": "*.json"
      },
      {
        "input": "src/configurations",
        "output": "configuration/",
        "glob": "README.md"
      }
    ],
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.dev.ts"
      }
    ]
  },
  "qa": {
    "assets": [
      "src/favicon.ico",
      "src/assets",
      {
        "input": "src/configurations/qa",
        "output": "configuration/",
        "glob": "*.json"
      },
      {
        "input": "src/configurations",
        "output": "configuration/",
        "glob": "README.md"
      }
    ],
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.qa.ts"
      }
    ]
  }
}

By means of the created subfolders in the configuration folder, the correct configuration.json file can be selected and copied. With help of the output property the path within the dist folder is defined. For the example, it is copied to a configuration folder in the root path. In addition a README.md is put next to the configuration.json to describe its properties and their effect on the application. Creating the dedicated folder helps to keep the two files next to each other.

What I don't like about the approach is, that we now have to duplicate the assets properties for all build configurations as otherwise e.g. the assets folder (images, fonts, translations and the like) does not get copied. Also, having to create a dedicated subfolder is also not as convenient as it was with the file replacement (although this is more a nuisance than a major drawback).

In case you have a better idea (or a solution) for solving the duplication, I'd love to hear about it. Otherwise I hope it can be beneficial for someone.

Reactive Angular components with presenters - Part 2

Mathias Remshardt — Sat, 09 Jan 2021 10:04:58 +0000

In the first part of the article we looked at the issue of slow running (component) unit tests in one of our projects. After having discussed different approaches for improving the execution time, moving business logic out of the affected components has been chosen as the preferred solution. Based on the derived requirements for the (new) component structure, the main ideas of a Flutter BLoc and Mode-View-Presenter inspired component structure have been explained.

In contrast to the more theoretical discussion in part one, part two focuses on showing the approach in practice by means of a simple example application. This will then enable us to assess the new found component structure in regard to the requirements formulated in part one.

Example application

As it is often the case with these (simpler) applications it cannot showcase all elements and subtleties found in real projects without loosing focus on the main idea. However it should serve a good overview for how a presenter based component implementation can look like.

The main feature of the example application is to show a list of user names. In case of interest, a running version can be seen here The component has been implemented twice which allows for a direct comparison of two variants:

The first variant contains all the "logic" in the component controller, reflecting our "old" approach
For the second variant the logic is taken care of by a presenter, reflecting the "new" approach

Next, a quick overview and explanation of the relevant parts is given. In case you prefer reading code to text you can find it here and directly jump to the results section.

The rest of us will start with the "Architecture" overview.

Architecture

UsersRestAdapter: Interface for requesting the user list from the server.
ProductionUserRestAdapter: Service implementation of UserRestAdapter.
- Using an interface has been done on purpose as it allows for "mocking" the adapter for depending services/components like UsersService.
UsersService: Manages/encapsulates the global user state as an Angular service.
- list all users
- refresh the list of users
UsersComponent: Shows the list of usernames.
UsersPresenter: Service managing the state of the UsersWithPresenterComponent.
UsersWithPresenterComponent: Shows the list of usernames using an presenter for component logic and state management.
UsersCounterComponent: Shows the number of users.
- This has been put into a dedicated component on purpose as it shows how a presenter can be used for sharing overarching state and thus avoiding prop drilling
Other files not relevant for the discussion itself.

As described UsersComponent and UsersWithPresenterComponent, both implement the same user interface and features to enable a direct comparison.

Elements

The section will give some implementation details for the elements relevant for the discussion in this article.

Classes/files not important for the approach are not covered.

We will also define the required test categories for each discussed component/service, as testing, especially test performance, plays an important role in this article.
As a quick reminder the two categories are:

Tests targeted at the ui (template required) --> slower
Test targeted at business logic in the component (no template required) --> faster

UsersComponent

The UsersComponent uses the Angular Material UI library to display a simple list of users:

@Component({
  selector: 'app-users',
  templateUrl: './component.html',
  styleUrls: ['./component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UsersComponent implements OnInit {
  readonly userNames$: Observable<ReadonlyArray<string>>;
  readonly userCount$: Observable<number>;

  constructor(private usersService: UsersService) {
    this.userNames$ = this.setupUsers();
    this.userCount$ = this.setupUserCount();
  }

  ngOnInit(): void {
    this.usersService.refreshUsers();
  }

  private setupUsers(): Observable<ReadonlyArray<string>> {
    return this.usersService.users$.pipe(extractUserNames());
  }

  private setupUserCount(): Observable<number> {
    return this.usersService.users$.pipe(extractNumberOfUsers());
  }
}

As mentioned in Architecture the main functionality of the component is to display a list of usernames.

The list is created by subscribing to the users$ Observable in the global UsersService. As the component is only interested in the list of names, it creates a new Observable by mapping over the global users$ list to extract the usernames from the User objects (done by the setupUsers method called in the constructor).

The userCount$ property uses the same approach for extracting the number of users.
For the sake of simplicity, a refresh of the global users list is triggered once the component gets initialized. This ensures that users are available in the UsersService.

The associated component template subscribes to the list by employing the build-in async pipe. Subsequently, it iterates over the usernames and displays each in a material-list/material-list-item.

The user count is displayed by simply subscribing to the userCount$ property.

<ng-container *ngIf="userNames$ | async as userNames">
  <mat-list>
    <h3 mat-subheader>List</h3>
    <mat-list-item class="userNames__element" *ngFor="let userName of userNames"
      >{{userName}}</mat-list-item
    >
    <h3 mat-subheader>Count</h3>
    <mat-list-item class="userNames__count"
      >Number of Users: {{userCount$ | async}}</mat-list-item
    >
  </mat-list>
</ng-container>

Tests

As ui and business logic concerns are mixed in the component, both test categories are represented. This is exactly the type of component which has been deemed problematic for our project as it performs template compilation for both test categories.

UsersWithPresenterComponent

@Component({
  selector: 'app-users-presenter',
  templateUrl: './component.html',
  styleUrls: ['./component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush,
  providers: [UsersPresenter],
})
export class UsersWithPresenterComponent {
  constructor(public presenter: UsersPresenter) {}
}

The functionality is equivalent to the one in UserComponent. The main difference is that all the implementation required for loading and converting the list of users has been moved to the UsersPresenter. By adding the latter to the list of component providers and making it part of the constructor, the template can directly subscribe to the public userNames$ property in the presenter.

As mentioned in the beginning, a dedicated component UserCount is leveraged to display the number of users. Although this would not necessarily be required in a "real" application (due to the low complexity), it shows how prop drilling can be avoided by injecting the presenter in deeper levels of the component tree.

<ng-container *ngIf="presenter.userNames$ | async as userNames">
  <mat-list>
    <h3 mat-subheader>List</h3>
    <mat-list-item class="userNames__element" *ngFor="let userName of userNames"
      >{{userName}}</mat-list-item
    >
    <h3 mat-subheader>Count</h3>
    <mat-list-item> <app-user-counter></app-user-counter></mat-list-item>
  </mat-list>
</ng-container>

Tests

Having most of the logic now extracted to the UsersPresenter leaves only template related functionalities in the component itself. As a consequence, all category two tests can be covered in the presenter tests and template compilation is only performed for ui tests (category one) where it is indeed required.

This is exactly what we wanted to achieve with the new structure in regard to testing.

UsersPresenter

@Injectable()
export class UsersPresenter {
  readonly userNames$: Observable<ReadonlyArray<string>>;
  readonly userCount$: Observable<number>;

  constructor(private usersService: UsersService) {
    this.userNames$ = this.setupUserNames();
    this.userCount$ = this.setupUserCount();

    this.onInit();
  }

  private setupUserNames(): Observable<ReadonlyArray<string>> {
    return this.usersService.users$.pipe(extractUserNames());
  }

  private setupUserCount(): Observable<number> {
    return this.usersService.users$.pipe(extractNumberOfUsers());
  }

  private onInit(): void {
    this.usersService.refreshUsers();
  }
}

The UsersPresenter encapsulates the implementation logic that has been extracted from UsersWithPresenterComponent. It makes the list of users accessible to the component via the public userNames$ property (in the same way as UsersComponent where it is located in the component controller itself).

The UsersPresenter already gives an impression how global state (users list) can be declaratively processes/combined with local state when both use the same underlaying, reactive foundation (RxJs in our case). With NgRx, as another example, a selector would be used instead of directly accessing the users$ property in UsersService.

Tests

As the presenter is a service it only contains category two tests.

UserCountComponent

@Component({
  selector: 'app-user-counter',
  templateUrl: './component.html',
  styleUrls: ['./component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class UserCounterComponent {
  constructor(public presenter: UsersPresenter) {}
}

The UserCountComponent can leverage the UsersPresenter to display the number of users. This showcases how presenters, injected deeper in the component tree, can be an alternative to using @Input properties for passing data.

The UserPresenter is available here, as UserCounterComponent is a child node in the template of UsersComponent. Worth mentioning may be, that it does not have to be a direct child.

Tests

The component contains no business logic and therefor only category one tests are applicable.

Results

With the example application implemented it is now possible to see if component presenters can actually help to:

decrease unit test time for components and component related business logic
improve components and components structure
share common logic/state in case appropriate

Unit test time

All implementations that have been located in the component and factored out can now be tested in isolation. This reduces the number of tests performing template compilation leading to a reduced test time.
At first glance it does look like a lot of effort for a few ms e.g. for the should emit list of user names test in the captured test run. However, these small improvements in run time do add up when the test suite size increases.

So the decreased test run time looks (even if only a few ms) promising. It should be mentioned though, that the effect may be lower when the complexity of the test itself increases, reducing the "impact" of template compilation.

The complete html report of the test run can be found in the test-reports folder.

For our (real) project we could not make a direct before/after comparison as the migration is still ongoing. We are doing a kind of "on-touch" refactoring (instead of a big bang) to strike the balance between new features and code improvements. Nevertheless, we did make some measurements for our more complex components and saw improvements in test time.
For the project (in contrast to the example application) the component tests have been removed all together, so only the ones for the presenters are left. After maintaining the former for some time we did not see any additional benefits as the template part is tested by e2e tests. This is/was just our experience so your mileage may vary here.

Lightweight, modularized and encapsulated components

Even though the UsersComponent and UsersWithPresenterComponent are of low complexity, the simple example already shows the improvements of separating the "behind-the-scenes" implementation to a dedicated presenter. Not only does this lead to a component with almost no additional code (besides what is required for the Angular framework). It also separates the ui/template related implementations from the more involved state handling/orchestration concerns.

Based on our experience so far, we formulated three structural elements for our projects:

Implementations e.g. global services, RxJs... for global state
Presenters for component state and/or business logic (implemented as services provided by the component)
Components concerned with the user interface

These three building blocks not only help us to make our components simpler (in case required multiple component presenters are used). We also made good experiences when introducing new team members as the three categories are a guideline where an implementation should be located.

Sharing business logic and state

Although somehow artificial (as hard to do otherwise in a simple example) the added UsersCount component shows how a presenter provided at a higher level in the component tree can be shared/reused at a lower level. One can probably imagine how this can be applied to avoid e.g. prop drilling when the tree height increases.

For our project, prop drilling and duplicated component state/business logic was/is not really an issue as:

we heavily make us of generic components which take configurations as @Input properties and therefor manage state independently
shared business logic was and is factored into pure and shared plain old JavaScript functions
global state and business logic is covered by NgRx

Bonus - Change Detection

In the beginning of the article it has been mentioned, that presenters can be beneficial for change detection when completely based on Observables.

This is not necessarily required but opens up the possibility to enable the onPush change detection strategy for additional performance benefits.

Conclusion

...for the pattern

Time for a recap:

We started the journey with the problem of slow running unit tests and looking for solutions potentially reducing the execution time. Moving non template related functionalities out of the component came out as our favorite option. It also opened up an opportunity to improve our component structure leading to additional requirements.

After some theory about the patterns inspiring the new found approach, we looked at a simple example application implementing the same component feature (displaying a list of users) twice. This allowed a before/after comparison not possible in our real project for practical reasons.

As a final result the newly employed pattern could be shown as beneficial for our requirements:

lightweight, modularized and encapsulated components
sharing of local state and business logic
unit test time

At the end one could state that our initial problem (unit test times) was more solved as a side effect of the newly imposed presenter based structure.

for the Project

In our project we have (up to this point) made good experiences, both for new and refactored components.

We are using NgRx for global state- and (now) presenters for local state management. As both NgRx as well as our implementations of presenters are completely based on Observables, the global and local state can be combined or piped pretty easily.

What we really like about it is the clear structure it provides in combination with simplified components and testing. It does require some learning and "getting used to" due to being completely based on Observables.

However, we do not consider this a drawback. The Angular framework and libraries are already heavily relying on Observables (e.g. when looking at the HttpClient, the RoutingModule or libraries like NgRx), so learning their usage is kind of a requirement. And almost every framework, library... needs some time and effort to become proficient in it.

NgRx component

Why has @ngrx/component not been considered?.

The simple reason is, that it was not yet ready/available.
Otherwise, as we are using NgRx, it would have been a compelling alternative as it gives similar advantages in regard to testing and component/application structure with additional benefits like component based selectors.

We will definitely consider it for future projects where NgRx is employed.

The availability of @ngrx/component does, in my opinion, not make the here described approach superfluous. Not all projects use NgRx so in case an approach only based on Angular primitives (Providers, Services and Observables) is needed, the MVP pattern and especially presenters can be an option with similar benefits (depending on how it is implemented).

Reactive Angular components with presenters - Part 1

Mathias Remshardt — Sat, 09 Jan 2021 10:04:53 +0000

This two part article focuses on implementing lightweight, reactive Angular components with MVP like presenters.

In the first part we will look how slow running unit tests has lead to new requirements for our component structure in one of our projects. We will next see how and why the solution, described in theory and practice, has been chosen.

In the second part, a simple example application shows the new structure in action and helps to highlight the most relevant parts. This will then enable us to assess, if our solution could fulfill the requirements and expectations set at the outset.

Before getting started, in case not already clear from the description/title, it should be mentioned that the article is more focused on the details of structuring/implementing a single Angular component. Therefor, it will probably not provide much benefit when looking for solutions on how to structure multiple components from a global/application point of view.

The pain - Slow running unit tests

As one of our last project grew larger, we faced the issue of an increasingly slow running unit test suite. Further investigations revealed our Angular component unit tests as one of the major reasons for the increasing unit test time. These seemed to be slow due to the required compile step triggered by compileComponents
This is fine for testing template related functionalities like the state a certain html element is in but not for e.g. state related tests.
For a loading spinner, as an example, there are (at least) two categories that tests could be written for:

A test validating that the spinner shows/hides when e.g. a loading flag is set to true/false (template/ui)
A unit test validating that the loading flag is in the right state e.g. when a backend call is pending or not (business logic)

The first test category requires the compilation step. For the second test it only adds delay which, in case there are a lot of these tests, can lead to a slow down of the complete test suite.

In our project we had a high ratio of component state related (category two) to template (category one) tests, even though core business logic has already been factored out to "helper" classes/services and the like. So for most test cases the template compilation was not required, making the problem even worse.

The ideas

Based on the problem description from above we'd like to perform the compilation process only for tests requiring a template. This could be achieved by:

only writing Integration Tests for these functionalities (e.g. using Cypress)
having Dedicated Tests skipping the compilation process
Moving the functionality (and therefore the tests) out of the component

Integration Tests

Completely relying on integration tests can work. However, there is a possibility for these tests to quickly grow large/complex in case the tested functionality is more involved than a loading spinner.

In addition, multiple test scenarios could lead to the same result(s) e.g. the loading spinner being hidden. The test would need to perform additional checks like e.g. a side effect (could be a backend call) or another element being displayed (e.g. an error message). As we like to treat our integration tests as black box tests the latter was not really an option for us.

With all this additional complexity and, especially effort, comes an inherent risk, that not all use cases/code branches will be covered (things happen when the going gets tough...)

More importantly all integration tests suffer from the same issue of not being as fast as unit tests (probably even slower than Angular component tests) rendering these invalid for solving our problem.

Dedicated test suite/test file

Why triggering compilation for tests not querying the template?

An option would be to move the compilation step out of the beforeEach block into a dedicated method which is only called when the template is required for testing.
Another alternative could be to have these tests in a separate test file which does not compile the template and directly calls the component constructor (similar how Services or Pipes are tested).

The proposed solution avoids the overhead created by the compilation process. In case needed the customized test file generation could be simplified by writing a schematic.

Moving functionalities

The approach is similar to moving the tests into a dedicated file. It takes the idea even further by „separating“ the complete functionality from the component itself and moving it to a dedicated Service or JavaScript Module.
As this new service/module would not have any template, the issue of compilation would be gone.

As an additional benefit, moving the implementation out of the component makes it more lightweight. In case free of core business logic by means of state management solutions (being it „simple“ Servicesor a dedicated library like NgRx) the component only contains view related properties (like the isLoading flag for the described loading spinner example).

For that additional benefit the option looked most appealing and was chosen for our project. We not only figured that it can solve our initial problem (slow running unit tests) but also be an opportunity to bring more structure to the components and application.

The new structure

Components should already be lightweight/free of business logic in case a proper state management solution is in use. Nevertheless, we have experienced that, despite using NgRx for dealing with global state, the orchestration as well as the required component related implementations can grow quite substantial for some components. Also, not every state (at least for us) is supposed to be global state and putting all that (transient) state into the component lead to our testing and structure issues in the first place.

For that reason we were looking for a solution filling the gap between managing global state and more complex local state/business logic (maybe even shared between multiple components).

So we were looking for an approach that:

reduces our unit test time for Angular components
creates more lightweight components
improves encapsulation and modularization for components
enables sharing parts of the logic between component siblings and/or descendant if and only if it makes sense

Having settled on the idea of factoring out logic and state from our components (as described in the previous part) we iterated a few times until we reached our current structure. In hindsight, our final solution was inspired by a combination of the Flutter BLoc- and MVP pattern.

The Flutter BLoc pattern

At the time I had been investigating Flutter as an option/replacement for our non native mobile solutions (in case requested by clients). The BLoc pattern is one of the available (and popular) options for managing (global) state in Flutter. As it is not required for this article to deeply go into the implementation details here is my short summary (no claim to completeness):

Business logic components are a lightweight approach for managing state in a reactive/-event driven fashion. The reactivity within the bloc pattern is achieved by using Streams or Observables. Some implementations introduce the notion of Events/Actions (similar to Redux) triggering effects and/or state changes. (more details can be found e.g. here).

In my Flutter applications I used it for global state management. However, I had (some) of the same issues with Flutter widgets (widgets are similar to components) as discussed in the previous section:

testing widgets is more involved and slower (although faster then Angular component tests)
widgets can grow complex in regard to state and business logic

For the Flutter applications, I somehow solved it by using "BLocs" for local state as well. So each widget, with enough complexity justifying it, is associated with its own BLoc containing the state and business logic (provided either by prop passing or InheritedWidgets).

I should mention however that I have always kept my BLocs simple instead of implementing these "by the book": So plain old classes which expose state as streams and updates are trigger by simple functions calls on these BLocs (so no notion of events and the like), keeping the overhead pretty low.

It served me well in regard to solving the issues for my Flutter applications. What I particularly liked about the approach was the reactivity it provided for the presentational layer in regard to state updates, similar to what we get from NgRx for global state in Angular.

So inspired by that we moved all the component related business logic into an associated service. As we are using NgRx, core business logic was already been taken care of. In hindsight, what we came up with in the end is pretty close to presenters from the MVP pattern.

The MVP pattern

Initially we named the new services classes ComponentBlocs. However, I wasn't really satisfied with this term because:

our component "BLocs" never implemented the interface described by most BLoc related articles/libraries (e.g. we had no notion of Events)
we are not managing global state or core business logic in these classes
it somehow "felt" wrong ;)

Later, when (coincidentally) watching the introductory talk by Lars Gyrup Brink Nielsen about Model-View-Presenter in Angular, I saw a similar structure and idea in there (at least I think so). It is not exactly the same to what we came up with e.g. we do not always have presentational components. However, it is close enough so that MVP and especially Presenter seems to be a good fit for our component associated services.

What is/was important to us (brought over by the BLoc pattern) is, that it should enable our components to react to state and state updates managed by the presenters. This is especially the case when used in combination with NgRx as it then, due to both being based on reactive principles, allows for a seamless integration of global and local state.

Today I like to use the term Reactive Presenter although this may not be exactly true since it is not only the presenter being reactive but also it's clients (usually Angular components).

As reactive is a somehow loaded term and can mean different things for different people, I will stick with just Presenter for the remainder of the article. The important point I want to pass here is, that our presenters should enable reactivity, both for itself and its clients.

As we now figured that our new component structure closely leans on the ideas of presenters in MVP, we need to answer the questions:

What is a presenter
How can it be made reactive in Angular

What it is

The are already lots of resources out there describing the MVP pattern in general e.g. the Wikipedia, including presenters. However, it does not seem to be too popular in the Angular realm (at least this was/is my impression).
As mentioned, the talk and article by Lars Gyrup Brink Nielsen make for a good starting point.

How it is used

Presenters are implemented as Angular services/injectables and associated with the component using component providers. This keeps the services and their states scoped to the instance of the component instead of being globally available like Services e.g. provided in root. Limiting the scope of presenters also binds their lifecycles to the providing component, coming in handy when having to perform e.g. clean up logic onDestroy. It also nicely separates the states (in case there is any), so that multiple instances of the same component cannot interfere with one another.

A component can have multiple presenters allowing state and state related logic being separated into different presenters, enforcing encapsulation.

On the contrary, a single presenter can be injected into multiple components, either for reusing business logic or sharing state. The latter can avoid prop drilling by injecting the top level presenter into a "leaf" component (similar e.g. React Context can be used).

To add support for reactive state updates (not a requirement in general) our presenters are completely based on Observables. This not only allows for declarative state orchestration (global and/or local) but also a seamless integration with other reactive Angular features like the RoutingModule or state management solutions like NgRx. As an additional benefit, it can give us some advantage in regard to change detection, which we will discuss later.

To make the described setup more tangible we will now look at an example implementation in the second part of the article.