DEV Community: Stephen Cooper

Test that every MutationObserver is disconnected to avoid memory leaks

Stephen Cooper — Thu, 22 Aug 2024 11:30:46 +0000

MutationObserver is a useful mechanism to watch for changes in the DOM and respond to them.

The MutationObserver interface provides the ability to watch for changes being made to the DOM tree.

Here is an example that watches for a theme class change.

    function setUpThemeClassObservers() {
        const observer = new MutationObserver(() => {
            const themeClass = this.getThemeClass();
            this.fireStylesChangedEvent('themeChanged');
        });

        observer.observe(this.eGridDiv, {
            attributes: true,
            attributeFilter: ['class'],
        });

        // we must disconnect otherwise "this" will not be GC'd
        // causing a memory leak
        return () => observer.disconnect();
    }

However, if you forget to disconnect you could be exposing yourself to memory leaks depending on what is accessed from within the MutationObserver functions.

Wouldn't it be great to have a test that can validate that we disconnect our observers?

Automatic Validation for Code

It turns out that it is possible to validate that every MutationObserver that is observing the DOM is also disconnected. (You may need more than one test if you have to exercise different code paths in order to setup the MutationObservers)

The idea is to Mock the global MutationObserver with sub mocks for its observe and disconnect methods. Before the mock is returned we record it in an array so that we can validate all instances at the end of the test run.


describe('Mutation Observers Disconnected', () => {

    let originalMutationObserver: typeof MutationObserver;

    const allMockedObservers: any = [];
    const mutationObserverMock = jest.fn<MutationObserver, [MutationCallback]>().mockImplementation(() => {
        const mock = {
            observe: jest.fn(),
            disconnect: jest.fn(),
            takeRecords: jest.fn(),
        };
        allMockedObservers.push(mock);
        return mock;
    });

    beforeEach(() => {
        // Ensure we can restore the real MutationObserver after the test
        originalMutationObserver = global.MutationObserver;
        global.MutationObserver = mutationObserverMock;
    });

    afterEach(() => {
        global.MutationObserver = originalMutationObserver;
    });

    test('observer always disconnected after destroy', async () => {
        const api = createGrid();
        // Perform some actions if required to exercise the code paths
        api.destroy();

        expect(allMockedObservers.length).toBeGreaterThan(0);
        for (const mock of allMockedObservers) {
            expect(mock.observe).toHaveBeenCalled();
            expect(mock.disconnect).toHaveBeenCalled();
        }
    });
});

In this way we can validate that each MutationObserver, setup during the test, is also disconnected at the end of the test.

Stephen Cooper - Senior Developer at AG Grid
Follow me on X @ScooperDev

Supporting Circularly Referenced Mapped Types in Typescript

Stephen Cooper — Fri, 22 Sep 2023 10:03:27 +0000

Recursive structures are very common across many applications but they can pose a big challenge to Typescript. While in our real data the recursion may only go a few levels, Typescript does not know this which can prose big problems for custom types. Just search for the following error and see all the results!



Type of property circularly references itself in mapped type

In the remainder of this post I will share how I resolved this error for a type called NestedFieldPaths<TData> that is a key part of the AG Grid library.

Context for Error

In AG Grid when configuring the grid that are two main parts, columns and rowData. The most important part of the column is the field property which describes which property from the row data should be displayed. The field property can access deeply nested properties via a dot separated string.

So if the user provides the Person interface to ColDef<Person> the valid field properties will be as follows: name, age, address, address.firstLine and address.city.



interface Person {
    name: string;
    age: number;
    address:  {
        firstLine: string;
        city: string;
    }
}

We achieve this via a generic type helper called NestedFieldPaths<TData> which extracts all the possible paths from the provided interface. This works great and brought a new level of type checking an DX via auto completion for the field property.

Recursive Interface Issue

This works great until you update the Person interface to also include a child: Person property making the interface recursive.



interface Person {
    name: string;
    age: number;
    // interface refers to itself recursively
    child: Person;
}

Pass this to NestedFieldPaths<Person> and instead of getting all the possible paths, i.e value, child.value, child.child.value and so on and you will get the following error.



Type of property 'children' circularly references itself in mapped type

This prevents the use of recursive interfaces with the NestedFieldPaths. Which makes people sad (Github Issue). So what can we do about this?

Potential Solutions

There are a number of unsatisfactory approaches such as not supporting recursive interfaces, or forcing the user to do some trickery to the interface that they provide to make it less recursive.

We cannot get round the fact that Typescript has to bail at some point so that it does not get stuck in an infinite loop. But is there something that we can do to make a type practically useable?

Best of both worlds is:

support a fixed number of recursions
beyond this give the user freedom to do whatever they like

We definitely want to be able to support these interfaces as they correctly explain the data that users want to display with AG Grid. So how can we do it?

Count Recursion Levels and exit at a given depth

The idea is to count how deep we have recursed and at a given level, say 6, bail from the recursion and let the rest of the path match anything. This last part is key because as soon as you set an arbitrary limit someone is going to actually specify a path that goes beyond that limit and we do not want to prevent that.

The first typing tool that we need is to be able to count levels of recursion. We can achieve this with the following type structure.

We first define a union of numbers that are within the depth level that we support. For this type we will go 7 levels deep so have the digits up to 7.



// Union of numbers within our depth limit
type Digit = 1 | 2 | 3 | 4 | 5 | 6 | 7 ;

We then construct an array of those same digits but crucially where their index in the array is one less then their own value. So for example at index 1 we have the value 2 and at index 2 we have 3.



// Array where each value is one greater than its index in the array
type NextDigit = [1, 2, 3, 4, 5, 6, 7, 'STOP'];

You can see how by using our current digit we can index the NextDigit array to get the next value. Putting these together we can setup the Inc<T> type utility which will give us the next digit.



// Type to get the number from the index in the array
type Inc<T> = T extends Digit ? NextDigit[T] : 'STOP';

But how do we stop? Well you can see that the last element in the NextDigit type is the string STOP which clearly is not a Digit. We can use this along with a check in Inc<T> to ensure that we stop changing the value returned from Inc and we will be able to pick a different path based on the return type of STOP.



type ShouldStop = Inc<7> extends 'STOP' ? true : false;

For our use case stopping the recursion means letting the user type any string path after the given path. The key part of our type to achieve this is as follows:



type NestedPath<TValue, Prefix extends string, TDepth> = 
    TValue extends object
        // Return any to allow any further string to be appended
        ? `${Prefix}.${ TDepth extends 'STOP' ? any : NestedFieldPaths<TValue, TDepth>}`
        : never;

This type checks if the current TValue is an object and if it is then it checks if the current TDepth = STOP. If it is then we append any to the string literal type. If we have not reached STOP yet it will recurse on the child properties of TValue.

Note that we are not incrementing TDepth in this type because the recursion happens across two interfaces. The higher level interface of NestedFieldPaths is responsible for calling Inc<TDepth> when it calls NestedPath. In this way each level of the input type will increment depth by one.



type NestedFieldPaths<TData = any, TDepth = 0> = {

    [TKey in StringOrNumKeys<TData>]:

        | </span><span class="p">${</span><span class="nx">TKey</span><span class="p">}</span><span class="s2">

        | NestedPath<TData[TKey], </span><span class="p">${</span><span class="nx">TKey</span><span class="p">}</span><span class="s2">, Inc<TDepth>>;

}[StringOrNumKeys<TData>];

Recursive Support for Nested Field Paths

By introducing this counter and stop logic we can now support recursive interfaces with the desired goals of:

support a fixed number of recursions
beyond this limit give the user freedom to do whatever they like

Autocompletion clearly shows the depth value kicking in and stopping the recursion.

Considerations

One potential downside of this approach is that if you have a nested object with no recursion, that goes beyond our depth limit, then those deeper levels will no longer be autocompleted. This is a trade off that we have decided to accept as we hope that nesting beyond 6 levels should be less common then having recursive interfaces.

The only other consideration is that you cannot increase the depth limit arbitrarily as you can still cause Typescript to bail on you if it thinks the type is getting too complex. This is why we have set a limit of 7, as in testing we found going above this caused the following error.



error TS2589: Type instantiation is excessively deep and possibly infinite.

Playground

If you want to experiment this type yourself you can find it in the following Ts Playground.

Would love to know if you find this useful or if you spot any issues that I have missed!

Generate array of all an interface's keys with Typescript

Stephen Cooper — Mon, 24 Jul 2023 21:09:34 +0000

When working with a large and complex code base like AG Grid it is very easy to miss updating certain parts of the code base.

For example, we have code generators that depend on having accurate lists of interface property names. In other words given a Typescript interface how can you produce an array that contains every property and ensure it stays up to date.

There are three approaches you might take to keeping this array of properties accurate:

1: Add a BIG comment reminding devs to update another part of the codebase.

   // IF YOU UPDATE THE COLDEF INTERFACE REMEMBER TO ALSO UPDATE...

2: Delve deep into the world of ASTs to extract / generate the list based off the code file.

3: Use Typescript to enforce the link between ColDef properties and a manually maintained list.

// See below for an explanation
type ColDefObject = Record<(keyof ColDef), undefined>;

1. Add a BIG COMMENT

The first approach is very simple and works initially. However, as the team grows, or you get forgetful it can still be easily missed. This is true no matter how big and attention grabbing you try to make your comment. So it's probably best not to go for this approach. Secondly, its litters the code base with unsightly comments.

2. Use an AST Parser and code Generator

The second approach requires a lot more work! Yes it will ensure the property list is perfectly accurate, but now you have to maintain a code parser and manage additional build complexity. While this isn't beyond the realms of possibility, (we have a few of these in AG Grid) it is definitely not an easy task. We can safely say that this approach is totally overkill for what we are trying to solve, especially with the next option.

3. Use Typescript to enforce the updates

The third option really is the best of both worlds. There is no need for a big comment because your Typescript build will fail if the property list is out of sync. Secondly, we don't need to write a code generator, we have a perfectly good human developer who can fix the issue in seconds.

What makes this very easy is that they will get autocompletion and a clear description of what property they need to add to the list. This approach is both simple to maintain and also is 100% reliable.

How to use Typescript

So how can we use Typescript to achieve our desired result? As a reminder we want to have a complete array of all the property names defined on the ColDef interface.

It is worth clarifying we want an actual array of property names that we can use in our code as opposed to just having the list of possible properties in Type land. This is why (keyof ColDef)[] alone is not sufficient.

First off lets show a cut down version of the ColDef interface.

interface ColDef {
  headerName: string;
  columnGroupShow: boolean;
  toolPanelClass: {string: string};
  valueGetter: (params: ValueGetterParams) => any;
}

As you can see we have a mixture of different property types including primitive types as well as objects and functions.

Using the ColDef interface we can create a new type that will enable us to type an object from which we can extract all the ColDef keys from. We can do this using the Typescript Record utility type.

type ColDefObject = Record<(keyof ColDef), undefined>;

This type enforces that the object has every property from the ColDef interface defined and set to undefined. As we do not care about the actual values we give all the properties the undefined type.

With this we can produce the following colDefProperties object using autocompletion in our IDE thanks to Typescript.

const colDefProperties: ColDefObject = {
  headerName: undefined,
  columnGroupShow: undefined,
  toolPanelClass: undefined,
  valueGetter: undefined,
};

Then to produce the complete list of ColDef property names we can then pass this to Object.keys. We cast back to (keyof ColDef)[] as otherwise ALL_PROPERTIES will be typed as string[] which is not so helpful to us.

const ALL_PROPERTIES = Object.keys(colDefProperties) as (keyof ColDef)[];

Conclusion

A bit of time spent finding the correct Typescript type can avoid the need to manually maintain code and ensure consistency without the need for complex code generators.

Use AG Grid with Observables as cell values

Stephen Cooper — Thu, 05 Jan 2023 10:23:23 +0000

In this guest post by Nicolas Gehlert, origianlly published here, learn a clean approach to working with Observable data in Angular.

Many thanks again to our user Nicolas for sharing his findings with us!

AG Grid does support observables as data input, but only one dimensional. If you have an observable that contains other observables the values cannot be displayed.

In this post I want to show you scenarios where this might be useful and how you can display those values properly with a loading indicator.

Introduction
Example
Custom cell renderer
Loading overlay
Sorting
Clipboard
CSV export
Excel export
Pitfalls

Introduction

Let me start of by saying, I'm aware that AG Grid is perfectly capable to handle (one dimensional) observables and for all the basic examples out there you probably don't need the approach that is described here.This is useful if you fetch data from different endpoints and they vastly differ in either the purpose or the loading duration.

One real life example where I used this a lot is if you fetch base data of business objects from one endpoint. Those are properties like name and description. But from another endpoint you fetch some reporting information. The latter is drastically slower in performance and usually takes more than 5 seconds.

The idea is to already display the information that is quickly available, while showing a loading indicator for the information that takes longer to fetch.

In this post I will take the very common AG Grid example with car information and simulate a loading for the car costs.

Example

I'm going to reference this in the very beginning. Everything described in this post can be found in action in this
stackblitz or this
GitHub repo.

But it probably still makes sense to check each chapter step by step to follow the thought process.

Base setup

In my example I will use Angular as a framework. But the concept works equally well for others like react or vue. Our base column definition is going to look like this:

class AppComponent {
  public columnDefs: Array<ColDef<ITableEntry>> = [
    {colId: 'car.model', field: 'car.model'},
    {colId: 'car.make', field: 'car.make'},
    {colId: 'price', field: 'pricingData'},
  ];
}

interface ITableEntry {
  car: {
    model: string;
    make: string;
  },
  pricingData?: Observable<number>;
}

Custom cell renderer

When we provide some data to our grid that follows the interface from above we will get the following result.

The result is actually expected, because AG Grid tries to display a string representation of the given object in the DOM and is not actually trying to resolve this observable.

We are going to create a custom cell renderer component that does this for us.

@Component({
    selector: 'grid-text-renderer',
    template: '<span>{{value|async}}</span>',
    changeDetection: ChangeDetectionStrategy.OnPush,
})
class AgGridTextCellRendererComponent implements ICellRendererAngularComp {
    public value: Observable<string> = of('');
    private params!: ICellRendererParams;

    public agInit(params: ICellRendererParams): void {
        this.params = params;
        this.value = params.value;
    }

    public refresh(params: ICellRendererParams): boolean {
        this.agInit(params);

        return true;
    }
}

The interesting part here is the public value property to render the value in the template. The params assignment and the refresh implementation are just my defaults to be consistent and performant for all custom cell renderer components.

The parameter params: ICellRendererParams will get the cell value as defined in our column definition by the field property. You can also use a valueGetter to return an observable. However things like valueFormatter won't work. If you need a custom format you need to implement it in your cell renderer component. You can also use cellRendererParams on the column definition to pass additional properties or values to your component.

As a last step we need to define in our column definition to actually use this component.

{
  colId: 'price', 
  field: 'pricingData', 
  cellRenderer: AgGridTextCellRendererComponent,
}

For more information on custom cell renderers check out the AG Grid docs

Now our result should look something like this:

As you can see the observables are properly resolved and the real number value is being displayed.

Loading overlay

We want to display a loading indicator to show to the user that the value for the cell is currently being loaded and he just needs to wait. There are different approaches how you can do this. You can extend the custom cell renderer we build in the previous step, and add a loading overlay that you trigger with *ngIf and hide it once the observable is resolved. But keep in mind, if you build multiple custom cell renderer for different observable purposes you need to implement this behavior in all of them.

Let me show you another AG Grid feature that is really awesome and pretty much made for cases like this. I'm talking about cellClassRules on the column definition (see docs).

The base idea is that you can add/remove classes to each cell depending on the result of a function. For easier maintainability I've added this to the defaultColDef in my gridOptions so I don't have to redefine it for every column where I need this, but it is just automatically available. You can also add it to the regular column definition if you prefer.

Now let's talk code.

import { first, forkJoin, isObservable, Observable } from 'rxjs';

public getDefaultColumnDefinition(_isServerSideRowModel: boolean = false): ColDef {
  const loadingStateByEntry: Map<unknown, boolean> = new Map<unknown, boolean>();
  const updateTableState: (params: CellClassParams) => void = (params: CellClassParams): void => {
    loadingStateByEntry.set(params.value, false);
    setTimeout(() => {
      params.api.refreshCells({
        suppressFlash: true,
        rowNodes: [params.node],
        columns: [params.column],
      });
    });
  };

  return {
    cellClassRules: {
      'grid-table-cell-loading': (params: CellClassParams): boolean => {
        const mapEntry: boolean | undefined = loadingStateByEntry.get(params.value);
        if (mapEntry !== undefined) {
          return mapEntry;
        }

        // Handle observables
        if (isObservable(params.value)) {
          loadingStateByEntry.set(params.value, true);
          params.value.pipe(first()).subscribe({
            next: (): void => updateTableState(params),
            error: (): void => updateTableState(params),
          });

          return true;
        }

        return false;
      },
    },
  };
}

We create a map loadingStateByEntry that represents the current loading state and whether an observable is already resolved or not. We use the reference of the observable as key and the loading state true|false as value. The benefit of using the reference here, is if multiple rows share the same observable reference it is only added once.

The updateTableState function is used to update the table state and re-trigger the cellClassRules evaluation. Everything from the observable happens outside of any ngZone or grid change detection. The loading state is set to false in our map and with the grid api we refresh our current cell.

The key 'grid-table-cell-loading'in the cellClassRules object is a css class name that will be added to the cell itself whenever the function provided as value is returning true.

First we need to check whether there is already an loading entry for our observable reference. Afterwards an isObservable check to ensure
we only trigger the next code if it is really an observable.

Now we can just subscribe to the observable - we are using the first() pipe to immediately unsubscribe and not create any memory leaks -
and call our updateTableState function.

Last but not least we need to add a global style. In my case I'm just using a simple circle that spins around, but feel free to change it to a bar,
hourglass or something more fancy.

.grid-table-cell-loading::after {
  content: '';
  box-sizing: border-box;
  position: absolute;
  top: 50%;
  left: 50%;
  width: 20px;
  height: 20px;
  margin-top: -10px;
  margin-left: -10px;
  border-radius: 50%;
  border: 2px solid transparent;
  border-top-color: cornflowerblue;
  border-right-color: cornflowerblue;
  animation: spinner 1s linear infinite;
}
.grid-table-cell-loading::before {
  background: transparent;
  content: '';
  position: absolute;
  width: 100%;
  height: 100%;
  left: 0;
}

@keyframes spinner {
  to {transform: rotate(360deg);}
}

And now we should see a beautiful loading indicator while the observable is still loading and as soon as a value is resolved
the loading indicator will disappear.

Tip: If you want to use a different spinner style or want to adjust the styles let the function for the cell class rule return true.

Sorting

Feature wise we can stop after the previous chapter. The next couple of sections are just needed if you use the given feature.

The sorting of AG Grid is not going to work, because the grid has no idea how to sort objects by reference. But AG Grid - like always -
has an awesome option to help us. We can use the postSortRows api for control over the sorted rows (see docs)

The base idea is to resolve all observables for the current sorted column and afterwards trigger the grid sort again to let is sort properly.

postSortRows: (params: PostSortRowsParams): void => {
  if (skipNextPostSort) {
    skipNextPostSort = false;

    return;
  }
  const columnStates: Array<ColumnState> =
    params.columnApi.getColumnState();

  columnStates
    .filter((state: ColumnState) => !!state.sort)
    .forEach((state: ColumnState) => {
      const observables: Array<Observable<unknown>> = [];
      params.api.forEachNode((node: RowNode) => {
        const value: unknown = params.api.getValue(
          state.colId || '',
          node
        );
        if (isObservable(value)) {
          value.subscribe({
            next: (result: unknown) => {
              storeResolvedObservableValue(value, result);
            },
          });
          observables.push(value);
        }
      });
      if (observables.length) {
        forkJoin(observables).subscribe({
          next: () => {
            /**
             * If we re-sort after all observable data for a column sort is resolved we don't want
             * to execute postSort again (infinite loop)
             */
            skipNextPostSort = true;
            params.api.refreshClientSideRowModel('sort');
          },
        });
      }
    });
},

The core logic is in the params.api.forEachNode. We want to iterate each row and see if the current value is an observable. If it is, we want to subscribe and store the given value with a little helper function I will explain in a second.

With the forkJoin we want to wait for all observables to be resolved and then re-sort the grid again. To store the values I'm using a WeakMap (to prevent any memory issues) and store the value by observable reference.

const valueByObservable: WeakMap<Observable<unknown>, unknown> = new WeakMap<Observable<unknown>, unknown>();
export function storeResolvedObservableValue(observable: Observable<unknown>, value: unknown,): void {
  valueByObservable.set(observable, value);
}
export function getStoredResolvedObservableValue(observable: Observable<unknown>): unknown {
  return valueByObservable.get(observable);
}

If we implement everything so far the result would still not work because AG Grid is still trying to sort by the reference.So we actually need a way to tell AG Grid to use our resolved value instead of the reference. On the column definition there is a comparator property that allows us to specify a custom sort comparator function
(see docs).

export function getObservableNumberComparator(): (valueA: any, valueB: any, nodeA: RowNode, nodeB: RowNode, isInverted: boolean) => number {
  return (valueA: any, valueB: any, _nodeA: RowNode, _nodeB: RowNode) => {
    if (isObservable(valueA) || isObservable(valueB)) {
      return (getStoredResolvedObservableValue(valueA) as number || 0) - (getStoredResolvedObservableValue(valueB) as number || 0);
    }

    return valueA - valueB;
  };
}

The comparator function is very simple in this case. We just check if the provided values are actually observables and then fetch the result from our WeakMap from the previous step.

If we update our column definition to include the comparator it looks like this and we can finally sort our price column.

{
  colId: 'price', 
  field: 'pricingData', 
  cellRenderer: AgGridTextCellRendererComponent,
  comparator: getObservableNumberComparator(),
}

Clipboard

Same story as before. If you just try to use the clipboard copy out of the box you will get [object Object] copied into your clipboard. Like for everything else you can imagine there is a neat little property on the gripdOptions called processCellForClipboard that allows us to hook into the process before the value is passed to the clipboard (see docs).

A simple check whether the given value is actually an observable and then checking our WeakMap for the real value and returning this instead of the
reference.

processCellForClipboard: (params: ProcessCellForExportParams) => {
  if (isObservable(params.value)) {
    return getStoredResolvedObservableValue(params.value) || '';
  }

  return params.value;
},

Note: Keep in mind, this will only save your value to the clipboard if the value has already been resolved. If you try this during the loading, the
result will just be an empty string.

CSV export

Very similar as clipboard export. I'm just gonna link the docs and show the proper gridOptions property.

defaultCsvExportParams: {
  processCellCallback(params: ProcessCellForExportParams) {
    if (isObservable(params.value)) {
      return getStoredResolvedObservableValue(params.value) || '';
    }

    return params.value;
  }
},

Excel export

Ok this is almost too easy… see the docs and check out the gridOptions property.

defaultExcelExportParams: {
  processCellCallback(params: ProcessCellForExportParams) {
    if (isObservable(params.value)) {
      return getStoredResolvedObservableValue(params.value) || '';
    }

    return params.value;
  },
},

If this is only logic you have in your export functions and you actually use all three of them you can extract this logic into a separate function and use this to avoid copy paste.

function processCellCallback(params: ProcessCellForExportParams) {
  if (isObservable(params.value)) {
    return getStoredResolvedObservableValue(params.value) || '';
  }

  return params.value;
}

Then your gridOptions are more readable:

processCellForClipboard: processCellCallback,
defaultCsvExportParams: {
  processCellCallback: processCellCallback,
},
defaultExcelExportParams: {
  processCellCallback: processCellCallback,
},

Pitfalls

In this section I just try to document issues I or others had in the past. If you have anything else to add, please let me know.

DOM Virtualisation / observables are not triggered

If we build everything properly, the observables are only resolved if they are visible - only then a .subscribe() is being called. Be aware that all observables will be resolved upfront if you turn off row- or column virtualisation
(see docs)

And on the other hand don't be surprised if some observables are not triggered if they are currently not visible in the viewport.

HTTP requests are executed multiple times

If you are using HTTP requests for your observables you most like will notice that requests are now done multiple times. For most HTTP client implementations every separate .subscribe() call will actually do a separate request. We are now doing this for example the view in the template, the sorting and the export.

You can use the shareReplay pipe (see docs) to prevent this and all
.subscribe() calls will refer to the same HTTP request. Same concept applies if your original observable is very computation heavy. It's better to use the shareReplay pipe.

Huge tables and sorting

If each cell uses a different observable and you have a grid with thousands of rows, be aware that if you sort for an observable column that every observable gets resolved. It might make sense to disable the sorting in such a case.

Row model type

This post was written for the client side row model. Other row models like server side, viewport or infinite (see docs might not work or need additional configuration effort.

Streamed observables

This approach currently works best for observables that are completed after the first result. From my experience that was all the use cases I had. Theoretically this is also possible for observables that emit multiple values, however you probably need to adjust couple of things. Find a better unsubscribe logic in the sort function to replace the first().

Alternatively you can also just create a new observable and re-assign it to the field in your grid data. The big advantage is that you get the loading indicator displayed again if you start a new request/loading time.

Does Angular Support Generic Component Types?

Stephen Cooper — Tue, 20 Dec 2022 16:49:14 +0000

You may be familiar with writing Typescript Generics like Grid<IRowData> but how does this work for Angular components? We can't provide generic types to our template selectors so how does Angular support generic components?

In this article we will explain how Angular does it, but also how you can help the Angular Compiler be more accurate in complex components.

Typescript Generics

Typescript Generics are a very powerful feature. Through generics we are able to customise existing Interfaces to a specific use case. For example, you might have a grid component to display rows of data. By making the grid component generic users can provide their own interface that represents their row data and have that interface used throughout the grid components' properties.

Why do we want a Generic Component?

Before we dive into the technical details of generic components I think it's important that we understand why we want to have generic support for our components.

Let's say we have a grid component that displays items and fires an event when users select a row. Without Generics we have to specify the type of the row data as any because we want to re-use this grid component with different data sets.

@Component({
    selector: 'app-grid',
})
export class GridComponent {

    @Input() rowData?: any[];
    @Output() onSelection: EventEmitter<any> = new EventEmitter<any>();
}

We would use this GridComponent like so in our application.

@Component({
    selector: 'app-car-data',
    template: `<app-grid [rowData]="rowData" (onSelection)="onRowSelected($event)"></app-grid>`
})
export class CarDataComponent {
    // Row data of cars to provide to the grid
    rowData: ICar[];
    // Callback when a row is selected
    function onRowSelected(event: ICar){
    }
}

This all works as expected but what if we made a mistake in our code and defined the selection callback with an event of type IPerson instead of ICar.

function onRowSelected(event: IPerson){
  // ERROR: Function definition expects IPerson but it will be called with ICar!
}

Our component does not complain as there is no link between the type of rowData and onRowSelected. Both IPerson and ICar are assignable to any so there is no error but we have a bug that might only be spotted at runtime.

However, if our component used generic types then Angular could warn us that the two properties do not match and we could fix the issue immediately.

Creating a Generic component

You make a component generic by providing a generic type parameter within angle brackets as part of the class declaration: GridComponent<TData>. You then use the generic type TData throughout your class where ever that type should be used.

For the GridComponent that looks like this.

@Component({...})
export class GridComponent<TData> {

    @Input() rowData?: TData[];
    @Output() onSelection: EventEmitter<TData> = new EventEmitter<TData>();
}

Note how we define TData as our generic type and then use that in place of the any type we previously had for rowData and the selection callback. This has the desired effect of linking the type of rowData with the onSelection EventEmitter.

Using a Generic Component

If we were writing plain Typescript we would create the GridComponent component and apply the generic type of ICar as new GridComponent<ICar>. Then all the generic properties would use the ICar type in place of TData.

const myGrid = new GridComponent<ICar>()

// type is ICar[]
myGrid.rowData;
// type is EventEmitter<ICar>
myGrid.onSelection;

However, this is not how we generally create components in Angular. Instead we place the selector in our template and set the Input and Outputs.

<app-grid 
  [rowData]="carData" 
  (onSelection)="carSelected($event)" >
</app-grid>

The key point is this: unlike JSX, you cannot explicitly provide the generic type to the component selector!

For example, the following is not valid HTML code.

<app-grid<ICar> [rowData]="carData" ></app-grid>

You cannot provide generic types to an Angular component explicitly, but that doesn't stop Angular supporting generic components via another mechanism.

So how do generic components work?

As we cannot specify the generic type explicitly, Angular has to infer it from the types of the Input and Outputs that we bind to the component. Let's step through this to explain how it works.

Firstly, the component author specifies the generic type, TData, and uses it for one or more properties.

@Component({...})
export class GridComponent<TData> {

    @Input() rowData?: TData[];
    @Output() onSelection: EventEmitter<TData> = new EventEmitter<TData>();
}

The user of the component types their properties in the app component.

carData: ICar[];

They then bind these to the component via an Input, in this case rowData.

<app-grid [rowData]="carData">

At this point the Angular compiler knows that the property carData has the type ICar[] and this has been assigned to the Input rowData which has the type TData[]. It then infers that the generic type TData should be set to ICar.

Using this information the compiler then applies the correct type to the onSelection Output. That type then becomes EventEmitter<ICar> and the compiler can validate that the types of rowData and onSelection are consistent.

Now if we make a mistake in the configuration, and provide incompatible types to multiple generic properties, we will get a build error. This is great and just what we wanted!

You may now be wondering why we said that Angular doesn't support generic types fully. It certainly seems like it does from this example.

Impact of Inference

In most cases when working with Generic components in Angular everything will work as expected. However, if the component gets more complex, in its use of the generic type parameter, then you may start to see a breakdown / widening in type inference.

This happens because type inference in Typescript has to ensure it is accurate across every code path. When Typescript cannot narrow the type specified in every code path you may see that the generic type is inferred as any. At this point you will stop getting template type errors because any matches any type.

In our example above this means the error about providing IPerson to the selection event would just disappear.

In these situations we need to start applying new techniques to help improve the developer experience with generics in Angular. We will do this by tweaking how we define our component's generic types.

Example Breakdown of Inference

To give a concrete example of the breakdown in inference we can look at the ag-grid-angular component from AG Grid. This component is generic with respect to row data. It is defined in the following way with many properties omitted for brevity.

@Component({
    selector: 'ag-grid-angular',
})
export class AgGridAngular<TData = any> {

    @Input() rowData?: TData[];
    @Input() columnDefs?: ColDef<TData>[];
    @Input() defaultColDef?: ColDef<TData>;
    @Output() rowSelected: EventEmitter<RowSelectedEvent<TData>> = new EventEmitter<RowSelectedEvent<TData>>();
}

If you write the following code with the ag-grid-angular component you might expect that the generic type would be correctly inferred as ICar.

carData: ICar[];
defaultColDef: ColDef;

<ag-grid-angular
 [rowData]="carData"
 [defaultColDef]="defaultColDef" >
</ag-grid-angular>

However, it is not. Instead you will see that the generic type is any. This means that there will be no template type checking across properties.

After a bit of investigation it is possible to find the cause of the issue. When defining the defaultColDef the type used is ColDef with no generic type instead of ColDef<ICar>. This means that the default generic type of any is used. This any is one of the possible types for the TData generic type in the component preventing further narrowing of the TData type to ICar.

Enforce Generic Parameters

One solution to ensure that generic types are correctly inferred is to enforce that your users supply them to every interface.

This can be enforced by not providing a default type. So instead of:

interface ColDef<TData = any>{}

You would define the interface as:

interface ColDef<TData>{}

There are tradeoffs with this approach though. For AG Grid this would have resulted in a major breaking change for all Typescript users. They suddenly would have been forced to update every type declaration to include a generic property. We did not feel this would be well received.

If you are in the different position of creating a new component from scratch, then maybe you could consider not supplying a default type as this will lead to more accurate and consistent type inference in the long run.

But what if you need to provide a default any type?

Understanding Code Inference in Angular

At this point we need to take a deeper look at how inference for Angular components works. It turns out that it is similar to the following static code structure.

  static typeCtor<TData>(inputs: Partial<Pick<GridComponent<TData>, 'rowData' | 'onSelection'>>): GridComponent<TData> {
    return null!;
  }

This gives us a useful mechanism for experimenting with different generic setups without the need to run the Angular compiler over our component in a template. This means you could validate inference for a component in an easily shareable environment like TS Playground.

You can use this approach to experiment with your generic types to find those that give the best developer experience based on common use cases.

Influencing Type Inference

This next section covers the specific changes made to the AG Grid component to improve its generic type support. We are trying to prevent the use of the ColDef interface with no type parameters from leading to a breakdown in inference of the TData generic type.

The way we do this is to introduce a second generic parameter, TColDef that is derived from the first: TColDef extends ColDef<TData>. This is entirely for the purpose of changing how inference works and has no other implications.

Our component definition changes like this:

- class AgGridAngular<TData = any>
+ class AgGridAngular<TData = any, TColDef extends ColDef<TData> = ColDef<any>>

Then we update our columnDefs Input to use this new derived generic parameter.

- @Input() columnDefs?: ColDef<TData>[];
+ @Input() columnDefs?: TColDef[];

We provide a default value of ColDef<any> to TColDef, so that we do not changed the interface requirements of AgGridAngular in case the component is used in a ViewChild selector.

However, as most users will only define the component in their template with ag-grid-angular this change will likely be invisible to them. They do not have to worry about the extra generic type parameter as they never specified them in the first place.

On the surface you may not expect this to change anything as you are simply redefining the columnDefs type as part of the generic parameters. We haven't actually changed any types here. However, this relocation has the effect of separating which properties Typescript tries to infer to the same type. The result for the AgGridAngular component is that the columnDefs property has a stronger influence on the inferred type of TData.

Now let's show the impact of this change in real application code.

Improved Inference Results

To see the result of this change we will show the exact same code with two different versions of AG Grid. (As this is all about the types I have omitted the actual implementation and just show the typings)

We define our properties and provide the ICar interface as the generic parameter to columnDefs and rowData. We don't provide a generic parameter to defaultColDef.

Finally, we simulate an error by setting the generic parameter to IPerson for the onRowSelected callback.

columnDefs: ColDef<ICar>[];
defaultColDef: ColDef;
rowData$: Observable<ICar[]>;
//This should result in an error as IPerson != ICar
onRowSelected(e: RowSelectedEvent<IPerson>): void {}

We then assign these to the component as follows:

<ag-grid-angular
  [columnDefs]="columnDefs" 
  [defaultColDef]="defaultColDef"
  [rowData]="rowData$ | async"
  (rowSelected)="onRowSelected($event)">
</ag-grid-angular>

If you were to use AG Grid v28.0 this code would compile as the generic parameter fallsback to any as can be seen in this screenshot.

However, with our updated typings in the latest versions of AG Grid, this same code will result in a compile error as expected.

We now also can see how the generic parameter has been correctly inferred along with improved IDE error highlighting.

This is great news because it means we have been able to improve the typing experience for AG Grid users without forcing them to add generic parameters to all their existing code.

Conclusion

While in many cases Angular will correctly infer your component types, when it does not, I hope that by sharing this knowledge you will be in a stronger position to provide hints to the Angular compiler to get it back on track.

Credits

My thanks go to Alex Rickabaugh @synalx from the Angular core team for showing me this approach in the Hallway track at NG Conf. It turns out this is also used to improve the typings for ngFor. See here. Big thanks to Alex!

Stephen Cooper - Senior Developer at AG Grid
Twitter @ScooperDev or Tweet about this post.

Reducing Angular Library Contributions to the Main Bundle

Stephen Cooper — Tue, 06 Dec 2022 09:39:48 +0000

In this guest post by Nicolas Gehlert, origianlly published here, learn the best way to include AG Grid in your own shared Angular library that will not result in AG Grid being included in the main bundle, as long as it is only used in lazy loaded routes.

Many thanks again to our user Nicolas for sharing his findings with us!

Using an Angular workspace with your own library you might've noticed that your main bundle size keeps increasing the more features you are adding - even if you
are not using all features up front. Let me show you how you can build a sustainable and lightweight library structure for your own library.

Introduction
Bundle analyzer
Problem analysis
Solution
Test for yourself

Introduction

Angular libraries are awesome and Angular does a good job giving you a kick start with their documentation.
However this only works for very simple and small libraries. If your library gets bigger and you want to optimize it, I found
there to be very few good resources.

Let me tell you an example. I'm using a big library with dependencies like AG Grid to provide shared components and services
in a multi application Angular workspace. I'm using lazy loading for all my routes but I discovered the main bundle get's increased
for all applications if I add more things to the library. At some point I was just using a simple data service in the main
application and an AG Grid component few lazy loaded modules down the line, but still AG Grid and all components were added to the
main bundle.

In this post I will show you how to analyze your package and how to properly set up your library in order to prevent similar issues.

All examples in this post use a sample project at https://github.com/ngehlert/angular-lazy-load.

Bundle analyzer

A bundle analyzer allows you to get insights in your bundled JavaScript. It shows you what dependencies are included and how much space
each section needs.

The Angular team recommends to use a tool called source-map-explorer. A lot of other post show tools like webpack-bundle-analyzer
or others. To some extend they work as well, but let's stick with the source-map-explorer for now.

First we need to install it with npm or yarn

npm install -g source-map-explorer
yarn global add source-map-explorer

Now build your project with the --source-map=true flag. (If you are using a project with an Angular version prior 12 also add the --prod flag)

ng build app --source-map=true

And now we can have a look at our stats with

source-map-explorer dist/app/main.js

The result looks something like this.

Problem analysis

Let's have a look at our sample application. We are using a small service and a component to display a simple table.

In our app.component.ts we are using the RandomService and in our lazy loaded route the TableComponent.

But if we have a look at our bundle analysis (see screenshot above) we will notice that AG Grid is actually added to the main module, instead of the lazy loaded one.

It turns out by default an Angular library is actually not tree shakeable, and you will always add the entire library to your bundle, even if you are just
importing one service or variable.

Solution - Multiple Entry points

You can create multiple entry points to your library and then you only need to import a specific entry point you are interested in, instead of the entire library.
Angular material is using the same concept, for example import {MatDialog} from '@angular/material/dialog';

Creating separate entry points is actually fairly simple and you only need to create a new directory inside your library and add an ng-package.json file.
Inside the ng-package.json you need to put the following content

{
    "$schema": "../../../../node_modules/ng-packagr/ng-package.schema.json",
    "lib": {
        "entryFile": "public_api.ts"
    }
}

In our example I moved the table directory into a separate grid directory next to the already existing src directory.

If you now run ng build good-lib you will notice that actually two entry points are created

Building Angular Package

------------------------------------------------------------------------------
Building entry point 'good-lib'
------------------------------------------------------------------------------
✔ Compiling with Angular sources in Ivy partial compilation mode.
✔ Writing FESM bundles
✔ Copying assets
✔ Writing package manifest
✔ Built good-lib

------------------------------------------------------------------------------
Building entry point 'good-lib/grid'
------------------------------------------------------------------------------
✔ Compiling with Angular sources in Ivy partial compilation mode.
✔ Writing FESM bundles

Now just one step is missing in order to use the secondary entry points. Go to your tsconfig.json (in your root directory). And extend the path entry for your library with a
placeholder match.

before:

"paths": {
  "good-lib": [
    "dist/good-lib"
  ],
},

after:

"paths": {
  "good-lib/*": [
    "dist/good-lib/*"
  ],
  "good-lib": [
    "dist/good-lib"
  ],
},

Note: You just need to do this once for your first secondary entry point. All future entry points will be resolved as well.

You can now use the TableModule from the secondary entry point like this import { TableModule } from 'good-lib/grid';

How to reference between the different entry points

You can NOT use relative imports between difference entry points. You need to import from the build package like you would from a regular application
as well. In our example this would be import {RandomService} from 'good-lib'; if you want to use it in the grid entry point.

Note: ng-packagr will detect in which order it needs to compile the different entry points so everything can be resolved. You will get an
error if you introduce a circular dependency and two (or more) entry points actually try to import from each other.

Test for yourself

You can clone the https://github.com/ngehlert/angular-lazy-load and just need to change three imports
to switch between the good and the bad library. See what imports to change

In the end with the good library AG Grid gets added to the lazy loaded route instead of the initial bundle. Now our initial bundle is only 200kb instead of 1.3mb!

For further details about minimizing the AG Grid bundle size in your application make sure to also read our other post Minimising Application Bundle Size.

Code Refactoring with Regex Find and Replace

Stephen Cooper — Fri, 14 Oct 2022 13:39:17 +0000

When faced with a major refactoring task across your codebase don't forget you can use Regexes to do the heavy lifting for you, potentially saving you hours of work!

Let me show how I used a Regex to update over 1000 method calls across hundreds of files in about 5 minutes instead of a day's work!

My Refactoring Task

In one section of code, I had many duplicated methods that could be replaced with a single generic getter. All the methods did was coerce a value from a configuration object and return this to the rest of the codebase without exposing the underlying object.

But how do you go about updating hundreds of these method calls when there are many different properties names and call locations?

Fortunately, all the methods follow a naming convention so we can take advantage of this and automate the update via Regex find and replace.

Old Code

We had many methods of this format:

public isMaintainColumnOrder() {
    return isTrue(this.gridOptions.maintainColumnOrder);
}
public isSuppressRowTransform() {
    return isTrue(this.gridOptions.suppressRowTransform);
}
public isSuppressColumnStateEvents() {
    return isTrue(this.gridOptions.suppressColumnEvents);
}

Which were then called like this.

if(this.gridOptionsWrapper.isMaintainColumnOrder()){
    ...
}

New Code

To be replaced with calls to the following method:

public is(property: keyof GridOptions) : boolean {
  return isTrue(this.gridOptions[property])
}

Called like this.

if(this.gridOptionsWrapper.is('maintainColumnOrder'){
    ...
}

The change will result in the following diff:

- if(this.gridOptionsWrapper.isMaintainColumnOrder()){
+ if(this.gridOptionsWrapper.is('maintainColumnOrder'){

Breaking Down the Changes Required

Thanks to the naming convention the changes follow this pattern:

Extract the property name after the is prefix in the original method call
Lowercase the first letter of the matched property name
Place the updated match into single quotes and parenthesis

Required Regexes

When doing a find and replace in VS Code we require two regexes. The first is used to find the code to update and extract the required information. The second regex is used to format the information, via a transformation, to be the new code.

Find Regex

This is the regex we use to match all our method calls.

gridOptionsWrapper.is(\w*)\(\)

Let's break this down.

gridOptionsWrapper.is: first find this string
(\w+): now match one or more word characters for the method name and extract this into the regex group result
: match the parenthesis (). \ is an escape character so we can match a parenthesis.

When the Regex sees the following code we will get a full match and also the extracted group match.

if(this.gridOptionsWrapper.isMaintainColumnOrder()){

Full Match: gridOptionsWrapper.isMaintainColumnOrder()
Group: MaintainColumnOrder

This is enough information for us to make the transformation.

Replacer

This is the regex we use to construct the new method call.

gridOptionsWrapper.is('\l$1')

This replaces the code in the following way:

gridOptionsWrapper.is remains unchanged
(' open parenthesis and single quote
\l lowercase the first letter of the next section
$1 provide the matched group
') close quote and parenthesis

This gives us the required diff for every single one of our is lookup methods no matter what the property name is.

- if(this.gridOptionsWrapper.isMaintainColumnOrder()){
+ if(this.gridOptionsWrapper.is('maintainColumnOrder'){

- if(this.gridOptionsWrapper.isSuppressRowTransform()){
+ if(this.gridOptionsWrapper.is('suppressRowTransform'){

Then it is a matter of running through the changes or just hitting that "Replace All" button and committing! :P

Conclusion

Don't forget about all the tools built into your IDE that can save you time and effort. Using Regexes for Find / Replace is just one example of the tools at your disposal.

Write Typescript in the browser with SystemJs

Stephen Cooper — Tue, 13 Sep 2022 10:49:34 +0000

(This post is just a rough public note about a side effect of some of my work. May or may not be helpful :) )

Do you love Typescript and wish you could use it to power a simple toy HTML sites that you want to play with? Well you can with SystemJs and a bit of on the fly browser compilation.

You don't always need a fancy setup :P

Demo Index.html + Typescript files

Check out this demo on Plunker that shows you how you can write Typescript files and use their methods from your Index.html file.

Yes, this does require you to get your SystemJs config setup right but that is why I am sharing this starter that I used for our AG Grid demos so that you can get started easily.

System.config({
        // DEMO ONLY! REAL CODE SHOULD NOT TRANSPILE IN THE BROWSER
        transpiler: "ts",
        typescriptOptions: {
            // Copy of compiler options in standard tsconfig.json
            target: "es5",
            module: "system", //gets rid of console warning
            moduleResolution: "node",
            sourceMap: false,
            emitDecoratorMetadata: true,
            experimentalDecorators: true,
            lib: ["es2015", "dom"],
            noImplicitAny: true,
            suppressImplicitAnyIndexErrors: true
        },
        meta: {
            typescript: {
                exports: "ts"
            },
            '*.css': { loader: 'css' }
        },

Aside from the systemjs.config.js file the main part of the code are as follows:

<script src="https://unpkg.com/systemjs@0.19.47/dist/system.js">        </script>
<script src="systemjs.config.js"></script>
<script>
  System.import('./main.ts')
        .catch(function(err) { console.error(err); });
</script>

Attaching methods to the window scope so can be called from HTML. (This is done for you when you just use a plain Javascript file)

<button onclick="onBtExcludeMedalColumns()">Exclude Medal Columns</button>

// Attach external event handlers to window so they can be called from index.html
(<any>window).onBtExcludeMedalColumns = onBtExcludeMedalColumns;

That's kind of it!

(This post is just a rough public note about a side effect of some of my work. May or may not be helpful :) )

AG Grid: Typescript Generics

Stephen Cooper — Thu, 14 Jul 2022 10:31:53 +0000

In this article, we will show you how to make the most of Typescript Generics in AG Grid v28. We will demonstrate the great developer experience it unlocks with the help of code examples.

AG Grid Generic Types

There are two generic types that you can pass to AG Grid interfaces. They are: TData and TValue.

TData - Row Data Type

TData is used to represent the shape of row data items. This generic parameter should match the interface used when defining your row data. If an AG Grid interface has a TData generic parameter this will always refer to the row data type.



interface GridOptions<TData = any>{
    rowData: TData[] : null;
}

To maintain backwards compatibility a default type of any is provided. This mimics the behaviour of previous versions of AG Grid that explicitly type the rowData as any[].

TValue - Cell Value Type

TValue is used to represent the type of a specific cell value. This generic type is more limited in scope and can be used within cell renderers/value getters when you want to give a type to the value property.



export interface GetQuickFilterTextParams<TData = any, TValue = any> {
    /** Value for the cell. */
    value: TValue;
}

As with TData, we also default TValue to any to maintain backwards compatibility.

Using Generic Types

In the examples below we use the ICar interface to represent row data.



// Row Data interface
interface ICar {
    make: string;
    model: string;
    price: number;
}

var rowData: ICar[] = [
  { make: "Toyota", model: "Celica", price: 35000 },
  { make: "Porsche", model: "Boxster", price: 72000 }
];

The best place to assign ICar to the TData generic parameter is via the GridOptions interface. This will cascade the generic type down the interface hierarchy.



// Pass ICar to GridOptions as a generic
const gridOptions: GridOptions<ICar> = {
    // rowData is typed as ICar[]
    rowData: [ { make: 'Ford', model: 'Galaxy', price: 200 } ]
}

With the generic parameter set to ICar, the rowData property has the type ICar[] instead of the default any[]. This means that if you mistype one of the properties you will get a compile-time error.

It is worth noting that it is not just rowData where the interface is used. For example, in the getRowId callback, the params.data property is typed as ICar instead of any. This is a result of AG Grid cascading the generic type down from GridOptions.

This also applies to all the grid events that contain a data property. i.e onRowSelected.



const gridOptions: GridOptions<ICar> = {
    // Callback with params type: GetRowIdParams<ICar>
    getRowId: (params) => {
        // params.data : ICar
        return params.data.make + params.data.model;
    },

    // Event with type: RowSelectedEvent<ICar>
    onRowSelected: (event) => {
        // event.data: ICar | undefined
        if (event.data) {
            const price = event.data.price;
        }
    }
}

If you use the grid api via gridOptions.api or callback params.api properties, then the api will be aware of the row data type too. This means that the method api.getSelectedRows() will return rows as ICar[].



// Grid Api methods use ICar interface
function onSelection() {
  const cars: ICar[] = gridOptions.api!.getSelectedRows();  
}

Configure via Individual Interfaces

While it is possible to configure everything inline within a gridOptions object, you may want to split things out for readability / re-usability. To benefit from Typescript generics we can provide our ICar interface to any AG Grid interface that accepts a TData generic parameter.

For example, we could configure our event handler with
RowSelectedEvent<ICar>. This results in the event.data property being typed as ICar | undefined. (See Generic Type or Undefined below for more details on the additional undefined type).



function onRowSelected(event: RowSelectedEvent<ICar>) {
    if (event.data) {
        // event.data: ICar | undefined
        const price = event.data.price;
    }
}

Advantages over any

There are two main reasons to provide generic types to AG Grid:

Compile-time errors
Auto-completion in your IDE

Compile Time Errors

Say we mistyped price as prive. Without generics, your application code would compile but your grid would no longer show prices in the grid. You would then have to track down the source of the bug. It could even be possible that this type of bug escapes into production if it slips past your tests.

However, if you supply generic types your application would not compile and would tell you the exact location of the bug. This enables you to instantly correct the code, instead of having to track down the bug. It will also be underlined with a red squiggle in your IDE!

Auto-Completion

As Typescript knows that our data object conforms to the ICar interface our IDE can suggest properties to us. This speeds up your development process as you do not have to spend time thinking about property names as they are suggested to you automatically.

Framework Specific Demo

React

If you are using AG Grid via the React component then you can pass your row data type to the AgGridReact component via this syntax: <AgGridReact<ICar>.

This will validate that all props conform to the row data type.



<AgGridReact<ICar>
   ref={gridRef}
   rowData={rowData}
   columnDefs={columnDefs}
   onGridReady={onGridReady}
></AgGridReact>

If you provide conflicting types you will get a compile-time error. For example, here we have provided a different generic type, INotCar to the onGridReady event which does not match our rowData of ICar.

Angular

For Angular, providing a type to your rowData property is enough to enable generics for the entire component.



 public rowData: ICar[];



 <ag-grid-angular
      [columnDefs]="columnDefs"
      [rowData]="rowData"
      (gridReady)="onGridReady($event)"
    ></ag-grid-angular>

If you are not using the rowData property, then type any other input/output that takes the generic parameter. For example, setting the following type on the onGridReady event would set the generic type for the entire component.



onGridReady(event: GridReadyEvent<ICar>) { }

Generic Type or Undefined

One thing you may notice when adding generic support to an existing application is that you may get errors relating to the data property potentially being undefined. You will not have seen this previously as the data property was typed as any which silently includes undefined. By specifying the type explicitly, AG Grid has the opportunity to warn you, via typings, that the data property could be undefined under some circumstances.

To demonstrate this we will look at a common pitfall that users have when adding custom cell renderers while supporting row grouping.

Common Pitfall with Cell Renderers

When writing a custom cell renderer you are likely to access the data property from the ICellRendererParams interface. Your first attempt may have code that accesses data properties with no undefined checks.



init(params: ICellRendererParams) => {
   this.total = params.data.gold + params.data.silver + params.data.bronze;
};

This may work in your application but it is not technically correct or future-proof.

If you have row grouping enabled then as soon as the user groups by a column your cell renderer will fail. This is because when grouping the data property is undefined.

However, if you provide a generic type to ICellRendererParams, such as IOlympicData, your code will warn that the data property can be undefined.

With the generic type supplied you are more likely to correctly write the cell renderer to handle this case.



init(params: ICellRendererParams<IOlympicData>) => {
    if(params.data){
        this.total = params.data.gold + params.data.silver + params.data.bronze;
    }else{
        this.total = undefined;
    }
};

While it is possible to silence the "Object is possibly 'undefined'" errors with a non-null operator !. such as params.data!.gold, we would recommend writing your code defensively in line with the AG Grid interfaces.

Conclusion

If you are using Typescript then we would encourage you to take advantage of our generic types to give you:

Compile-time errors
Auto-completion in your IDE
Improved code typings

It is a small change in your type definitions that results in a greatly improved developer experience!

For more details visit our Typescript Generics documentation.

Upcoming changes to AG Grid Angular in v28

Stephen Cooper — Thu, 09 Jun 2022 09:48:17 +0000

In this post, we want to give you notice of the changes that are coming to our Angular wrappers in v28 and actions that you can take now to make the upgrade as smooth as possible.

In v28 of AG Grid, we are enabling the Ivy distribution format which brings numerous benefits. However, this means the minimum Angular dependency will increase to Angular v12.

To maintain support for older versions of Angular, v8-11, we are going to release new legacy versions of our Angular packages. So please read on to understand what to expect when upgrading to AG Grid v28.

Why are we doing this?

Since Angular v12 the recommend distribution format for Angular libraries was changed to Ivy. There are many advantages to this approach, namely no longer requiring ngcc to run and mutate your node_modules.

As Angular v12 is over a year old and there are other features that moving our library to Ivy unblocks we have decided to make this change now. This brings us in line with the rest of the Angular ecosystem in moving towards Ivy everywhere.

We have decided to update our existing Angular libraries, ag-grid-angular and @ag-grid-community/angular, (see Package vs Modules for why we have two Angular libraries) to use Ivy as opposed to creating new packages for the Ivy format. We have decided to minimise the change for users who are up to date with Angular and avoid future breaks when View Engine is no longer supported.

What to expect when migrating to AG Grid v28

Apps using Angular v12+

First off, if your application is built with Angular v12 or above, then you will update as normal. Simply move ag-grid-angular to v28 and notice that ngcc will no longer run against our package. You may see a slight improvement in CI build time as a result of this.

The following warning will disappear from your build log!

Generating browser application bundles (phase: setup)...
Processing legacy "View Engine" libraries:
- ag-grid-angular [es2015/esm2015]
Encourage the library authors to publish an Ivy distribution.

Deprecation of `AgGridModule.withComponents()`.

With our Angular lib now requiring its consuming applications to run with Ivy, we have deprecated and removed the .withComponent() method from the AgGridModule. This has not been required for any applications that were running with Ivy but as we supported Angular v8 we could not remove it.

Simply delete the .withComponents([MyComponent]) if it is present in your code.

That is all you need to do concerning this Angular upgrade as part of AG Grid v28. Do still check the changelog for grid-related breaking changes.

Apps using Angular v8-11

If your application is on an old version of Angular there is going to be more work for you to upgrade to AG Grid v28 to get our latest features. If possible take this opportunity to upgrade your Angular version to at least v12. However, we understand this is not always going to be viable. As a result, we will produce legacy versions of our Angular libraries that will still work in your app.

These will be ag-grid-angular-legacy and @ag-grid-community/angular-legacy respectively for Package / Module setups.

So in your package.json file, you will need to change the AG Grid package to be the legacy version.

"dependencies": {
    ...
-    "ag-grid-angular": "^27.3.0",
+    "ag-grid-angular-legacy": "^28.0.0",
    ...

You will then need to update all the import paths throughout your application to use the legacy package name too.

- import { AgGridModule } from 'ag-grid-angular';
+ import { AgGridModule } from 'ag-grid-angular-legacy';

The only difference between the standard and legacy packages is the Angular distribution format, so aside from standard major version breaking changes, the legacy package should act as a drop-in replacement.

AG Charts v6

The same change will also be applied to our standalone Angular charting library. So from v6 of ag-charts-angular you will need to have a minimum Angular dependency of v12.

If you are on Angular v8-11 then you will need to switch to the ag-charts-angular-legacy package.

"dependencies": {
    ...
-    "ag-charts-angular": "^5.3.0",
+    "ag-charts-angular-legacy": "^6.0.0",
    ...

Then also update your chart import paths too.

- import { AgChartsAngularModule } from 'ag-grid-angular';
+ import { AgChartsAngularModule } from 'ag-grid-angular-legacy';

Conclusion

As Angular continues to move forward we want our users to be able to take advantage of the new features and so we will continue to move forward with Angular upgrades. This means that in future releases please expect that we will continue to drop support for older versions of Angular until we reach v12 and will drop the legacy packages entirely.

VS Code: It's taking a while to configure your breakpoints"

Stephen Cooper — Thu, 12 May 2022 14:12:59 +0000

I love using VS Code to run and debug local scripts. However, I had noticed that starting up the task in debug mode sometimes took a really long time.

I also got the warning pictured here with the text, "It's taking a while to configure your breakpoints. You can speed this up by updating the 'outFiles' in your launch.json."

This is likely because, when working in a mono repo, there are a lot of files that the task runner tries to load into the debugger so that it can configure your breakpoints.

Javascript Task Configuration

This was the task configuration from my launch.json file. This task just ran a Javascript file, meaning for debugging, I did not require any source maps.

 {
    "type": "node",
    "request": "launch",
    "name": "Generate Cypress Config",
    "runtimeExecutable": "npm",
    "cwd": "${workspaceRoot}/grid-packages/ag-grid-docs/documentation",
    "runtimeArgs": [
        "run-script",
        "generate-cypress-config"
    ],
    "port": 9229,
    "skipFiles": [
        "<node_internals>/**"
    ],           
    "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!**/node_modules/**"
    ]
}

Simply setting sourceMaps to false caused the task to startup pretty much immediately saving me a lot of time!

"sourceMaps": false,

Typescript Task

However, if you are running a Typescript task you will need source maps loaded if you want to debug it. This is when we need to follow the instructions of the warning and set the outfiles config property.

I set this to the folder containing all the files that would be included in the given task run. Even if this still included some extra files, restricting to a small subset and ignoring node_modules gave a huge boost in startup speed.

"outFiles": [
    "${workspaceFolder}/grid-packages/ag-grid-docs/**/*.js",
    "!**/node_modules/**"
],

You should match the .js files and not the sourcemap files directly.

Conclusion

Don't ignore warnings when they are giving you a hint that could improve your productivity!

You can read how VS Code does source map discovery from their documentation for a more complete picture.

Understanding async tests in Angular

Stephen Cooper — Mon, 25 Apr 2022 15:58:19 +0000

If you are testing an Angular application, then at some point, you will be required to test asynchronous behaviour. In this article, we will demonstrate how to write an asynchronous test with both fakeAsync and async/await. We will explain each step in detail to give you the understanding and confidence to write your own asynchronous tests.

Full application code along with tests is available at StephenCooper/async-angular-testing

Application for our Test

We will be testing an application that uses AG Grid. Our application displays a table of Olympic medal winners and also provides users with a text box to filter the medal winners by any field. You can try the application out for yourself here.

We are going to test that we can filter our data to a specific country of interest. Our test will validate that:

Our grid shows the full set of 1000 rows and our application displays the row count of 1000.
Upon entering the text "Germany" the grid should filter the rows to only show German athletes
Our application row count should update to 68 (the number of German athletes).

The reason for choosing this application is that it contains asynchronous code making it virtually impossible to test synchronously.

Application Code

In our application we have a text input box that is bound to the quickFilterText property of our component. We display the current number of rows in our template and we pass the quickFilterText to our grid component so that it can filter its rows as required.

<input id="quickFilter" type="text" [(ngModel)]="quickFilterText"/>

<div id="numberOfRows">Number of rows: {{ displayedRows }}</div>

<ag-grid-angular #grid
  [quickFilterText]="quickFilterText"
  (modelUpdated)="onModelUpdated($event)"
></ag-grid-angular>

The number of rows will be kept up to date by using the grid callback (modelUpdated). This is fired every time the grid model is updated, including when filtering is performed.

export class AppComponent implements OnInit {
  public displayedRows: number = 0;
  public quickFilterText: string = '';

  @ViewChild('grid') grid: AgGridAngular;

  onModelUpdated(params: ModelUpdatedEvent) {
    this.displayedRows = params.api.getDisplayedRowCount();
  }
}

Test helpers

Before we get to the tests let me quickly explain the assertion helper function we will be using. This function will give us an insight into the inner workings of our test, especially when we start working with asynchronous callbacks.

The function validates the following:

internal grid state
state of the component variable, i.e displayedRows
rendered HTML output of the {{ displayedRows }} binding

We will see that these values do not update in sync due to asynchronous callbacks and if change detection is required to have run to update the property.

function validateState({ gridRows, displayedRows, templateRows }) {

    // Validate the internal grid model by calling its api method to get the row count
    expect(component.grid.api.getDisplayedRowCount())
      .withContext('api.getDisplayedRowCount')
      .toEqual(gridRows)

    // Validate the component property displayedRows
    expect(component.displayedRows)
      .withContext('component.displayedRows')
      .toEqual(displayedRows)

    // Validate the rendered html content that the user would see 
    expect(rowNumberDE.nativeElement.innerHTML)
      .withContext('<div> {{displayedRows}} </div>')
      .toContain("Number of rows: " + templateRows)
}

The .withContext() is a helpful Jasmine method to give us clearer error messages when values are not equal.

Configuring the Test Module

The first part of the test is to configure the test module. It requires AG Grid's AgGridModule and also Angular's FormModule to provide support for ngModel.

import { DebugElement } from '@angular/core';
import { ComponentFixture, fakeAsync, flush, TestBed } from '@angular/core/testing';
import { FormsModule } from '@angular/forms';
import { By } from '@angular/platform-browser';

import { AgGridModule } from 'ag-grid-angular';
import { AppComponent } from './app.component';

beforeEach(() => {
  TestBed.configureTestingModule({
      declarations: [AppComponent],
      imports: [AgGridModule, FormsModule],
    });
    // Create the test component fixture
    fixture = TestBed.createComponent(AppComponent);
    component = fixture.componentInstance;
    let compDebugElement = fixture.debugElement;

    // Get a reference to the quickFilter input and rendered template
    quickFilterDE = compDebugElement.query(By.css('#quickFilter'))
    rowNumberDE = compDebugElement.query(By.css('#numberOfRows'))
});

An important thing to note here is what is missing from beforeEach. We have purposefully not included fixture.detectChanges() as part of our setup logic. By doing this we ensure that all our tests are as isolated and it enables us to make assertions on our component before it is initialised. Finally, and most importantly, when working with fakeAsync we do not want our component to be created outside of our test's fakeAsync context. If we do this, we can end up with all sorts of test inconsistencies and bugs.

Note that we do not run fixture.detectChanges() inside the beforeEach method! This can lead to numerous issues when testing asynchronous code!

Broken Synchronous Test

To prove that we need to handle this test asynchronously, let's first try to write the test synchronously.

it('should filter rows by quickfilter (sync version)', (() => {

    // When the test starts our test harness component has been created but not our child grid component
    expect(component.grid).toBeUndefined()
    // Our first call to detectChanges, causes the grid to be created
    fixture.detectChanges()
    // Grid has now been created
    expect(component.grid.api).toBeDefined()

    // Run change detection to update template
    fixture.detectChanges()

    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })
  }))

While it looks like this test should pass it does not. We would expect that by the point we call validateState each assertion would correctly show 1000 rows. However, only the internal grid model has 1000 rows and both the component property and rendered output display 0. This results in the following test errors:

Error: component.displayedRows: Expected 0 to equal 1000.
Error: <div> {{displayedRows}} </div>: Expected 'Number of rows: 0 for' to contain 1000.

This happens because the grid setup code runs synchronously and so has completed before our assertion. However, the component property is still 0 because the grid callback is asynchronously and is still in the Javascript event queue when we reach the assertion statement, i.e it has not run yet.

If you are not familiar with the Javascript event queue and how asynchronous tasks are run then you may find it beneficial to read these articles:

As we cannot even validate the starting state of our test synchronously it is clear that we are going to need to update our tests to correctly handle asynchronous callbacks.

Writing an Async Test

We are going to cover two approaches for writing our test that handles the asynchronous grid behaviour:

Using fakeAsync
Using async await

FakeAsync

As asynchronous code is very common, Angular provides us with the fakeAsync test utility. It enables us to control the flow of time and when asynchronous tasks are executed with the methods tick() and flush().

The high-level concept with fakeAsync is that when the test comes to execute an asynchronous task, it is added into a time-based queue instead of being executed. As a developer, we can then choose when the tasks are run. If we want to run all the currently queued async tasks we call flush(). As the name suggests this flushes all the queued tasks executing them as they are removed from the queue.

If we have code that uses a timeout, for example, setTimeout(() => {}, 500), then this will be added to the fake async queue with a time delay of 500. We can use the tick function to advance time by a set amount. This will walk through the queue and execute tasks that are scheduled before this time delay. Tick gives us more control over how many tasks are removed from the queue as compared to flush.

It is worth noting that there is also a flushMicrotasks() function. For an example of when you might use flushMicrotasks instead of flush take a look at this article Angular Testing Flush vs FlushMiscrotasks.

Controlling Change Detection in our test

You will see the following line of code fixture.detectChanges() in a lot of Angular tests. This enables you to control when change detection is run. As part of change detection, Input bindings receive their updated values and Html templates are re-rendered with updated component values. Each of these is important when you want to validate that code is working correctly. In the test code below, we will highlight why we are required to call fixture.detectChanges() at multiple stages.

Quick Filter Test with FakeAsync

We will now walk through the full fakeAsync test to validate that our application correctly filters data and updates the number of displayed rows.

Test setup

The first thing to do is wrap our test body in fakeAsync. This causes all async functions to be patched so that we can control their execution.

import { fakeAsync, flush } from '@angular/core/testing';

it('should filter rows by quickFilterText', fakeAsync(() => {
    ...
}))

At the start of our test, our application component has been created but it has not been initialised. i.e ngOnInit has not run. This means that our <ag-grid-angular> component has not been created yet. To validate this, we can test that the grid is undefined.

The first call to fixture.detectChanges(), will create the grid and pass the component values to the grid via its @Inputs. When working with fakeAsync ensure the first call to fixture.detectChanges() is within the test body and NOT in a beforeEach section. This is vital as it means that during the construction of the grid all async function calls are correctly patched.

// At the start of the test the grid is undefined
expect(component.grid).toBeUndefined()

// Initialise our app component which creates our grid
fixture.detectChanges()

// Validate that the grid has now been created
expect(component.grid.api).toBeDefined()

Next, we validate that the internal grid model is correct. It should have 1000 rows. At this point, the asynchronous grid callbacks have not run. i.e the (modelUpdated) @Output has not fired. This is why the internal grid state has 1000 rows, but the component and template still have 0 values.

// Validate the synchronous grid setup code has been completed but not any async updates
validateState({ gridRows: 1000, displayedRows: 0, templateRows: 0 })

To run the callbacks, that are currently in the fake task queue, we call flush(). This executes all the async tasks that were added during the initialisation of the grid and also any others that are created during the flush itself until the task queue is empty. Async tasks may create new async tasks as they are executed. Be default flush() will attempt to drain the queue of these newly added calls up to a default limit of 20 turns. If for some reason your async tasks trigger other async tasks more than 20 times you can increase this limit by passing it to flush. i.e flush(100).

// Flush all async tasks from the queue
flush();

Now the component has its displayedRows property updated by the (modelUpdated) event handler. However, this is not reflected in the template as change detection has not yet run. For the rendered template to reflect the updated component property we need to trigger change detection.

Our test state is now consistent. The internal grid model, component data and renderer template all correctly show 1000 rows before any filtering is applied.

// Validate that our component property has now been updated by the onModelUpdated callback
validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 0 })
// Force the template to be updated
fixture.detectChanges()
// Component state is stable and consistent
validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

Update Filter Text

Now it's time to enter text into the filter. We set the filter value to 'Germany' and fire the input event which is required for ngModel to react to the filter change.

At this point, the text input has been updated but the grid input binding, [quickFilterText]="quickFilterText", has not been updated as that requires change detection to run. This is why even the internal grid model still reports 1000 rows after the filter change.

// Mimic user entering Germany
quickFilterDE.nativeElement.value = 'Germany'
quickFilterDE.nativeElement.dispatchEvent(new Event('input'));

// Input [quickFilterText]="quickFilterText" has not been updated yet so grid is not filtered
validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

We now run change detection which passes the text 'Germany' to the grid input [quickFilterText]="quickFilterText". We then validate that the internal number of rows has been reduced to 68 as the grid filters asynchronously. However, the displayedRows property has not been updated as grid callbacks are asynchronous and sitting in the task queue.

// Run change detection to push new filter value into the grid component
fixture.detectChanges()
// Grid uses filter value to update its internal model
validateState({ gridRows: 68, displayedRows: 1000, templateRows: 1000 })

We now flush our async task queue which causes the event handler (modelUpdated) to fire and update our component's displayedRows property. We then run change detection to update the template with the new value.

Our component test state is once again stable and we can validate that our quick filter and model update logic is correct.

//flush all the asynchronous callbacks.
flush()
// Component property is updated as the callback has now run
validateState({ gridRows: 68, displayedRows: 68, templateRows: 1000 })

// Run change detection to reflect the changes in our template
fixture.detectChanges()
validateState({ gridRows: 68, displayedRows: 68, templateRows: 68 })

Full Test Code

Here is a more concise version of the test without all the intermediary validation steps. Hopefully it is now clear why we have this repeating pattern of detectChanges -> flush -> detectChanges. In both cases, you can think of it as updating component inputs, running async tasks, and then updating the template with the resulting values.

it('should filter rows by quickFilterText using fakeAsync', fakeAsync(() => {

    // Setup grid, run async tasks, update HTML
    fixture.detectChanges()
    flush();
    fixture.detectChanges()

    // Validate full set of data is displayed
    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

    // Update the filter text input
    quickFilterDE.nativeElement.value = 'Germany'
    quickFilterDE.nativeElement.dispatchEvent(new Event('input'));

    // Push filter text to grid, run async tasks, update HTML
    fixture.detectChanges()
    flush()
    fixture.detectChanges()

    // Validate correct number of rows are shown for our filter text
    validateState({ gridRows: 68, displayedRows: 68, templateRows: 68 })

  }))

Using Auto Detect Changes

Now that we understand the data flow in the test above we can simplify the test by using fixture.autoDetectChanges().

When autodetect is true, the test fixture calls detectChanges immediately after creating the component. Then it listens for pertinent zone events and calls detectChanges accordingly.
The default is false. Testers who prefer fine control over test behaviour tend to keep it false.

it('should filter rows by quickFilterText using fakeAsync auto', fakeAsync(() => {

    // Setup grid and start aut detecting changes, run async tasks and have HTML auto updated 
    fixture.autoDetectChanges()
    flush();

    // Validate full set of data is displayed
    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

    // Update the filter text input, auto detect changes updates the grid input
    quickFilterDE.nativeElement.value = 'Germany'
    quickFilterDE.nativeElement.dispatchEvent(new Event('input'));

    // Run async tasks, with auto detect then updating HTML
    flush()

    // Validate correct number of rows are shown for our filter text
    validateState({ gridRows: 68, displayedRows: 68, templateRows: 68 })
  }))

As you can see, writing the test with auto-detect hides a lot of complexity and so maybe a good starting point for your asynchronous tests. Just be aware you will lose precise control of when change detection is run.

Using async await

Another way that we can test our application is to use the built-in async and await syntax along with the fixture method fixture.whenStable(). This can at times be a simpler way to write async tests as you do not have to worry about manually running async tasks.

It is worth noting that there are cases when it is impossible to write a test with fakeAsync. If any of the executed code has a recursive setTimeout being used as a polling timeout, then the fakeAsync task queue can never empty during a flush. Each time a task is removed and executed it adds a new one to the queue indefinitely. This is why you may run into the following error.

Error: flush failed after reaching the limit of 20 tasks. Does your code use a polling timeout?

If you run into this situation you may have more success with the async and await approach.

Let's now re-write our test to work with async and await.

it('should filter rows by quickFilterText (async version)', (async () => {

    // Grid is created
    expect(component.grid).toBeUndefined()
    fixture.detectChanges()
    expect(component.grid.api).toBeDefined()

    // At this point in the test we see that the async callback onModelUpdated has not run
    validateState({ gridRows: 1000, displayedRows: 0, templateRows: 0 })

    // We wait for the fixture to be stable which allows all the asynchronous code to run.
    await fixture.whenStable()

    // Callbacks have now completed and our component property has been updated
    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 0 })
    // Run change detection to update the template
    fixture.detectChanges()
    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

    // Now let's test that updating the filter text input does filter the grid data.
    // Set the filter to Germany
    quickFilterDE.nativeElement.value = 'Germany'
    quickFilterDE.nativeElement.dispatchEvent(new Event('input'));

    // We force change detection to run which applies the update to our <ag-grid-angular [quickFilterText] Input.
    fixture.detectChanges()

    // Async tasks have not run yet
    validateState({ gridRows: 68, displayedRows: 1000, templateRows: 1000 })

    // Again we wait for the asynchronous code to complete
    await fixture.whenStable()
    validateState({ gridRows: 68, displayedRows: 68, templateRows: 1000 })
    // Force template to update
    fixture.detectChanges()
    // Final test state achieved.
    validateState({ gridRows: 68, displayedRows: 68, templateRows: 68 })
  }))

As you may have noticed the structure of the test is very similar and we have just basically replaced flush with await fixture.whenStable. However, under the hood, these tests are running in very different ways so this will not be a straight swap in many other examples.

Here is a concise version using autoDetectChanges which is our shortest working test so far. It is also conceptually the most simple to understand and hides a lot of the complexity from the tester.

  it('should filter rows by quickFilterText (async version)', (async () => {

    // Run initial change detection and start watching for changes
    fixture.autoDetectChanges()
    // Wait for all the async task to complete before running validation
    await fixture.whenStable()

    validateState({ gridRows: 1000, displayedRows: 1000, templateRows: 1000 })

    // Set the filter to Germany
    quickFilterDE.nativeElement.value = 'Germany'
    quickFilterDE.nativeElement.dispatchEvent(new Event('input'));

    // Wait for callbacks to run
    await fixture.whenStable()

    // Changes automatically applied
    validateState({ gridRows: 68, displayedRows: 68, templateRows: 68 })
  }))

Complete Test Application Code

You can find the full application, complete with tests in the Github repo: StephenCooper/async-angular-testing

Conclusion

We have taken a step by step walkthrough of an asynchronous Angular test. We explained how to write the test with both fakeAsync and async / await, starting with first principles and then showing how to take advantage of autoDetectChanges. I hope that you will have found this breakdown useful and it will enable you to confidently write tests for your applications' asynchronous behaviour.

Stephen Cooper - Senior Developer at AG Grid