Adrian Faciu's Blog RSS Feed

Exploring template literal types in TypeScript

Tue, 25 Jan 2022 13:00:37 GMT

This post will explore my train of thought following a question about how I would type an existing function. This code was not used in any production app, but it was a good exercise in working with TypeScript while trying to solve this particular problem.

We will go a bit deeper by using (recursive) conditional types, template literal types, index accessed types, and a suite of other helper types. Previous knowledge of TypeScript is required in order to be able to follow along. Knowing about these types beforehand will also help, but I’ll try to provide links and examples for further reading.

So grab your favorite hot beverage and get ready for a post that goes towards the ‘heavy to read’ end of the spectrum. Experimenting with the code as we go along is encouraged, for example in the TypeScript playground. There is also a link with the solution at the end.

The problem

Let’s assume we have an existing code base, with a general function that reads data from an API. We can pass it the property names that we want to read for that specific object type, and the URL. Might look something like this:

fetchData(properties, url) {...}

Assuming we have a Car object:

type Car = {
  id: number;
  name: string;
  price: number;
};

We can use our function to fetch a list of available cars, and what properties we need for each:

fetchData('id, name', '/api/cars');

We are specifying that we want the list of cars, but only the id and name properties on them. In our simple example, this is somehow irrelevant. But if you are working with complex objects or large volume of data, this can save a lot of bandwidth and improve the speed of our applications. If we have a large list of complex objects, including just a few properties (vs. all) would make a big difference.

Another possible use case is if you have different clients (web, mobile) that use the same APIs, but they display different data. So this might be useful to fetch what’s needed in each case. There are different ways to implement this on the backend, depending on what technology you are using.

Going back to our function, we can think about this as being used inside an existing code base. Our task at hand would be to create a proper typed version of fetchData, so that it will be easier to use and make our code better.

Return type

This should be straight forward. We want to get a specific type back, so we make the function generic, and specify ourselves what the return type is:

function fetchData<T>(properties: string, url: string): T {...}

Then we can use it as:

const cars = fetchData<Car>('id', '/api/cars');

Now TypeScript will make sure our cars variable has the proper type. It’s a bit tricky that we have to explicitly write this, but there is no easy way out of it. We cannot easily map the type to a string, so this is what we have to settle with. All the popular data fetching libraries have an implementation similar to this.

If we want to make sure developers working in this codebase use the correct type, we could encapsulate this at the API layer in one way or another. For example creating a fetchCars function:

function fetchCars(properties: string) {
  return fetchData<Car>(properties, '/api/cars');
}

This takes care of the basics, now let’s see about that properties type.

One property

It would be nice to be able to specify only existing properties of a Car when we call this! In that way, we’re sure our function is typed.

First thing I would think of is keyof. This will allow us to get all the keys of a specified type. So if we have something like:

type CarKeys = keyof Car;

It will expand into:

type CarKeys = 'id' | 'name' | 'price';

This happens because those are all the properties that we defined on our Car type above. Any time we add or remove one from the Car type, the keyof derived type will be updated. You can see the official docs for more.

So we update our function to fetch data with this knowledge:

function fetchData<T>(properties: keyof T, url: string): T;

This works, we can make calls and get back data with what property we want:

// ✅
fetchData('id', '/api/cars/');

But we can specify only one property at a time, which is not exactly what we want 😅:

// ❌
// Argument of type '"name, id"' is not assignable to parameter of type...
fetchData('id, name', '/api/cars/');

But before we are going to look at how to implement support for multiple properties, we need to get ourselves conformable with some (new) TypeScript features.

Template literal and recursive conditional types

A possible solution to our problem is the use of template literal types and recursive conditional types, introduced in TypeScript 4.1. You can see the release notes for full details, but I’ll try to show some examples so we can better understand them.

Template literal types

Using similar concepts from template literals, we create a type using substitutions:

type Programming = "programming";
type Statement = `love ${Programming}`; // 'love programming'

This is pretty straight forward, but we can explore one additional trick:

type Programming = "programming";
type Reading = "reading";
type Statement = `love ${Programming | Reading}`;

What happens if we use a union operator with a template literal type? It will create all the possible combinations! So this will get expanded to:

type Statement = 'love programming' | 'love reading';

We can use something a bit more complex as an example to better grasp it. Lets compose some CSS properties:

type CssProperty = "margin" | "padding";
type PropertySide = "top" | "right" | "bottom" | "left";

type Prop = `${CssProperty}-${PropertySide}`;

Which will get expanded to all possible combinations:

type Prop =
  | 'margin-top'
  | 'margin-right'
  | 'margin-bottom'
  | 'margin-left'
  | 'padding-top'
  | 'padding-right'
  | 'padding-bottom'
  | 'padding-left';

Conditional types

Since TypeScript 2.8 we have conditional types at our disposal. Let’s explore them a bit.

A simple example of this would be (re)creating the NonNullable type. This will remove null or undefined from types:

type NonNullable<T> = T extends null | undefined ? never : T;

As the name implies, you can think of conditional types like an if statement. If the condition is true, resolve to the first type, if not, the second one. If the expression is not that familiar, you can have a quick look at the conditional operator.

In the example above, we check to see if the generic type matches null or undefined and:

if true -> we return never
if false -> we return the generic type itself

In TypeScript, never is a built-in type representing values that are never observed. In our case, it removes undefined or null:

// string
type OnlyString = NonNullable<string | null>;

// number
type OnlyNumber = NonNullable<number | null | undefined>;

Recursive conditional types

We had conditional types but, up until TypeScript 4.1, we could not recursively reference the type itself. Let’s try to extract the primitive types from an array, also handling the case when we have deeply nested arrays:

type ExtractType<T> = T extends Array<infer U> ? ExtractType<U> : T;

As before, we check to see if the generic type matches something like an Array and:

if true -> we return the same ExtractType, but as a type argument we use the type of the Array itself
if false -> we return the generic type itself

In order to figure out what the type of the arrays is, we used the infer keyword. It’s like saying take whatever type you find there, and place it in this U variable, so that I can use it later on.

And we can test it out:

// 'string'
let one: ExtractType<[string]>;

// 'string' | 'number'
let two: ExtractType<[string, [number]]>;

// 'string' | 'number' | 'boolean'
let three: ExtractType<[string, [number, [boolean]]]>;

These examples are pretty similar to those from the release notes. Added them here for more context or in case you did not open the links :)

And now we know everything we need to continue.

Multiple properties

Back to our problem. We have the Car type, we used the keyof on it, which works, but only with one property at a time, and we would like to expand this to work for all/any combination of them.

Let’s start the other way around. One solution would be something like this:

type KeysOf<T, Key extends keyof T = keyof T> = Key extends string
    ? `${Key}, ${KeysOf<Omit<T, Key>>}` | Key
    : never;

Lets go through it step by step. We created a generic type with two arguments: the type of the object we want to use and an union with property names of that type. By default, this will be a union of all the property names, like we’ve seen before. In most cases we’ll use the generic type by passing in only the first argument, as most of the time we want to go through all of the properties, which is what the default, keyof T, value does.

Then, we use a conditional type to see if the second generic argument, the Key, looks like a string. This will happen most of the time, for all the properties of our type. When there are no more properties, it will be an empty set, so no string, and we return never. This is our way to make sure we don’t get into infinite recursive calls.

Now, if we still have properties to process, we construct our template literal type: ${Key},${KeysOf<Omit<T, Key>>}. We want the properties to be separated by a comma, so we add it there. Then we use the same type to create a recursive call.

The trick here is to use the Omit helper type. Each time we process a property name, we call the same type recursively, but without the processed property. In this way we handle all the properties one by one, until we call the type with an empty set. In that case, the Key will no longer be a string, so we will return never and stop the recursive call.

type CarWithoutName = Omit<Car, 'name'>;

It is equivalent to the initial Car type, but without a name:

type Car = {
  id: number;
  price: number;
};

The last thing to add here is a union with the Key itself. This will generate a union with all the possible combinations.

Then we can update our function with our new type:

function fetchData<T>(properties: KeysOf<T>, url: string): T;

And this will work pretty well. We can specify any combination of properties that we might want to read:

fetchData('name, price');
fetchData('price, name');
fetchData('price');
fetchData('id, name, price');
// and so on

If you want to check this, you can use this yourself (or see the TypeScript playground link at the end):

type CarProps = KeysOf<Car>;

It will get transformed into:

type CarProps =
  | 'id'
  | 'name'
  | 'price'
  | 'name, price'
  | 'price, name'
  | 'id, name'
  | 'id, price'
  | 'id, name, price'
  | 'id, price,name'
  | 'price, id'
  | 'name, id'
  | 'name, id, price'
  | 'name, price,id'
  | 'price, id, name'
  | 'price, name, id';

There are some ways to solve this without using the second generic argument, but I found this way of doing it more straight forward and we get some extra benefits. Notice that we’ve passed only one generic argument so far, but we can also pass the second to explicitly use only specific keys:

KeysOf<Car, "id">
KeysOf<Car, "id" | "name">

Or just maybe this way of solving it might have been the easiest for me 😅.

Complex (nested) objects

We can further improve on our type. So far we had a simple car, with properties that have primitive values. But in real life, we might have some more complex types. Maybe the car also has an engine:

type Engine = {
  power: number;
  id: string;
};

type Car = {
  id: number;
  name: string;
  price: number;
  engine: Engine;
};

And, in case of the engine property, we could do the same thing, specify only what properties we want to read from it. Something like this:

fetchData('name, engine(power)', '/api/cars');

This will mean that we want a list of all the cars, with only the name and engine properties, and on the engine we only need the power property.

In this part we’ll make use of the Record utility type. This helps us check if a type looks like an object, or it is a primitive type. Using Record we create an object-like type, where the first argument will represent all the properties and the second one the type of those properties. So using something like Record<string, any> will create an object that has as properties any string and those can have any value.

As an alternative, we could have used our own Primitive type, or another way to create an object-like type.

Knowing this, we can build on our previous version to include an additional check:

type KeysOf<T, Key extends keyof T = keyof T> = Key extends string
    ? T[Key] extends Record<string, any>
        ? `${Key}(${KeysOf<T[Key]>})`
        : `${Key}, ${KeysOf<Omit<T, Key>>}` | Key
    : never;

We have added even another level to our type. After we check that the Key is a string, we need to see if the type of that property is a Primitive or not. To get that type, we use the T[Key] expression, which is an index accessed type. Then we do a similar thing, depending on the condition:

if it looks like an object, we add round brackets and we do a recursive reference to KeysOf, passing in the just extracted index accessed type
if it’s not an object, we have the previous code, nothing different here

And this solves the problem of a bit more complex types, as we can see if we check it out:

type CarProps = KeysOf<Car>;

It will get transformed into an even more complex thing:

type CarProps = "id" | "name" | "price" | "engine(id)" | "engine(power)" |
                "engine(id,power)" | "engine(power,id)" | "price,engine(id)" |
                "price,engine(power)" | "price,engine(id,power)" |
                ... 68 more ... | "price,name,id,engine(power,id)";

Yes, 68 more options, it indeed has all the possible combinations and we can use any of them to call our function.

Conclusion

This was an interesting experiment, and it allowed me to play around with template literals and recursive conditional types. They are quite powerful and can provide useful types for our code. This post is a first in a series of “learning in public” style of articles. More will follow :)

If you want to experiment live with this type, you can use this TypeScript playground.

Let me know if you would use something like this in production, or what other interesting ways of solving this problem you have.

Handling Observables in a LitElement component

Thu, 06 Aug 2020 20:46:37 GMT

Intro

Since the first time I’ve used RxJs for some Angular projects, I’ve fallen in love with this library. There are a lot of use cases where it’s applicable. And for me, it makes the whole experience of writing and reading code way better.

LitElement is a small and lightweight base class for creating web components. It’s easy to use and understand. You can start writing web components without a lot of setup and it’s a joy to use.

We’re going to have a look at how to use RxJs inside a LitElement web component. Some different approaches we can take to handle and render Observables. Basic knowledge of RxJs, LitElement, and TypeScript is required. If you’re comfortable with any of the big three (React/Angular/Vue) you should be able to follow along.

Problem

Let’s define a basic LitElement component that we are going to use for our examples:

import { LitElement, html, customElement } from 'lit-element';

@customElement('my-element')
class MyElement extends LitElement {
  render() {
    return html`
      <p>This is a sample LitElement</p>
    `;
  }
}

A simple class that extends from LitElement and renders a text. We use the customElement decorator to register the class as a web component.

Our purpose is to have an Observable and render it inside our component. For a sample stream, we are going to use an interval and take the first ten items from it:

import { interval } from 'rxjs';
import { take } from 'rxjs/operators';

values$ = interval(1000).pipe(take(10));

We generate a new value each second, starting from 0 and we take the first 10. We would like to render this inside our component:

import { LitElement, html, customElement } from 'lit-element';

import { interval } from 'rxjs';
import { take } from 'rxjs/operators';

@customElement('my-element')
class MyElement extends LitElement {
  values$ = interval(1000).pipe(take(10));

  render() {
    return html`
      <ul>
        <li>Render all items here</li>
      </ul>
    `;
  }
}

Working with Observables inside a LitElement is easy enough, but it involves a bit of code. We need at least to subscribe and schedule an update for anything to show up:

@customElement('my-element')
class MyElement extends LitElement {
  values$ = interval(1000).pipe(take(10));
  data = [];

  connectedCallback() {
    super.connectedCallback();
    this.values$.subscribe(value => {
      this.data = [value, ...this.data];
      this.requestUpdate();
    });
  }

  render() {
    return html`
      <ul>
        ${this.data.map(
          item =>
            html`
              <li>${item}</li>
            `
        )}
      </ul>
    `;
  }
}

The connected callback life cycle hook is called when the component is added to the document’s DOM. Here, we want to subscribe to our stream and update the property in our class. Since LitElement is not tracking our data property, we need to manually request an update each time the value changes.

In this case, it’s good enough, because our observable will finish after ten items and clean everything up. But what happens if we remove the take method call? We would like to unsubscribe and clean up when our component is removed from the DOM. So we have to add a bit more code to handle that:

@customElement('my-element')
class MyElement extends LitElement {
  unsubscribe$ = new Subject();
  values$ = interval(1000);
  data = [];

  connectedCallback() {
    super.connectedCallback();
    this.values$.pipe(takeUntil(this.unsubscribe$)).subscribe(value => {
      this.data = [value, ...this.data];
      this.requestUpdate();
    });
  }

  disconnectedCallback() {
    super.disconnectedCallback();
    this.unsubscribe$.next();
    this.unsubscribe$.complete();
  }

  render() {
    return html`
      <ul>
        ${this.data.map(
          item =>
            html`
              <li>${item}</li>
            `
        )}
      </ul>
    `;
  }
}

To achieve this, we’ve created a Subject, this is a special type of Observable that also allows us to emit values. We used this inside the disconnected callback to send a new value whenever the life cycle hook is called. Before we subscribe we use the takeUntil operator to emit the values from the source observable, but only until something is emitted on the unsubscribe stream.

This is all good and it works, but if we have multiple streams to handle in our component, the amount of code grows a bit with each new one.

Options

There are a few directions that you can go about if you want to extract this functionality and make it more generic:

a simple function
a directive
a base class
a decorator

This is also the order in which I’ve explored them. First, we are going to rule out the first two.

Using a simple function, you cannot monkey patch life cycle hooks of custom elements. This means we cannot extend the functionality of disconnected callback to know when the element was removed and unsubscribe. We cannot clean up after ourselves, so this is not OK.

While there are a few examples out there with async directives that handle Observables, they have one issue. The directive itself is not aware of the life cycle of the component, so there is no easy way to unsubscribe when needed. The same problem as with a simple function.

Base class

The next option, a base class, is a good, working, option. One advantage is that a lot of projects using LitElement already have a base class, so it’s a matter of extending that one, and having the provided functionality in all the components throughout the app.

We want to provide a subscribe method, that could be used inside a component to subscribe to an Observable and request an update whenever new data comes in. Something like:

connectedCallback() {
  super.connectedCallback();
  this.subscribe('data', this.values$);
}

We start with something simple, the base class and a simple implementation for the subscribe method:

export abstract class RxLitElement extends LitElement {
  subscribe(propertyName, stream) {
    stream.subscribe(value => {
      this[propertyName] = value;
      this.requestUpdate();
    });
  }
}

We get the stream and the property name where we want to place the values. We subscribe to the stream, update the class property with new values, and request an update so that our UI will reflect the new data.

Then we can update our component and use our new base class:

@customElement('my-element')
class MyElement extends RxLitElement {
  values$ = interval(1000);
  data = [];

  connectedCallback() {
    super.connectedCallback();
    this.subscribe('data', this.values$);
  }

  render() {
    return html`
      <ul>
        ${this.data.map(
          item =>
            html`
              <li>${item}</li>
            `
        )}
      </ul>
    `;
  }
}

If you run this, you will see that nothing happens. This is because we expect that data is an array and in this case, it’s only a value. We can slightly update our stream to transform it into an array with all the values so far. We’ll use scan operator to transform it:

values$ = interval(1000).pipe(scan((acc, value) => [value, ...acc], []));

The scan operator is similar to reduce, but it emits each intermediate result. We start with an empty array, for each value we append it to the array and emit the result. Now everything works as before, and all the code that handles the subscribe is abstracted in our base class.

As a possible future improvement, we could pass in a function to our subscribe method. This will handle the update of the property and will allow custom functionality, like adding items to an array, properties to an object, and so on.

Type safety

The first thing that we want to improve is the typing, we want to make sure we send in an Observable and a property name that exists in our class:

    subscribe<Key extends keyof this>(
      propKey: Key,
      stream$: Observable<this[Key]>
    ) { }

Using keyof this we create a subtype of string that can have as values only the property names defined in our class. If we have an interface with some properties:

interface Person {
  name: string;
  age: number;
  location: string;
}

type K1 = keyof Person; // "name" | "age" | "location"

We defined our method with a generic Key type parameter that extends from this sub type Key extends keyof this. In this way, we make sure we can pass in only properties that exist in our class.

Next, we can define the stream as an Observable, but we need a type for that. We have to use lookup types, to make sure that the type of the values emitted by the Observable is the same as the type of the property that will receive them:

interface Person {
  name: string;
  age: number;
  location: string;
}

type P1 = Person['name']; // string

Using lookup types, we can take the defined type of our property, and make an Observable of that specific type.

Now our method is type-safe and it prevents us from making mistakes when using it. You can read more about keyof and lookup types here.

Unsubscribe

The first improvement is to unsubscribe from the Observable when our component is removed from the DOM. For that, we can use the takeUntil operator.

To use this we create a Subject, that will emit a value when the component disconnected callback is called. Then we’ll use it before we subscribe to our stream:

const unsubscribe = Symbol('unsubscribe');

export abstract class RxLitElement extends LitElement {
  [unsubscribe] = new Subject();

  subscribe<Key extends keyof this>(
    propKey: Key,
    stream$: Observable<this[Key]>
  ) {
    stream.pipe(takeUntil(this[unsubscribe])).subscribe(value => {
        this[propertyName] = value;
        this.requestUpdate();
      }
    }

  disconnectedCallback() {
    this[unsubscribe].next();
    this[unsubscribe].complete();
    super.disconnectedCallback();
  }
}

We used a symbol to define the unsubscribe subject to make sure it’s unique, so it does not clash with other user-defined properties, and that by default it’s not accessible from outside our base class.

This is the basic working implementation, but we can add some more features that will help us when using this approach.

Extra features for our base class

For safe programming practices, we can check that the stream we get inside our subscribe method is indeed an Observable. We get all the type checking at runtime. RxJs has a method called isObservable that we can take advantage of:

if (!isObservable(stream$)) throw new Error('Invalid Observable!');

If we want to be extra safe, we can even check the property:

if (!this.hasOwnProperty(propKey)) throw new Error('Invalid property name');

Now to some more useful features, we might want to call the subscribe method several times in our component life cycle, for the same property, with different streams. We want to handle this, meaning unsubscribe from the old observable before subscribing to the new one. And ignoring subscribe calls for the same property and the same Observable.

For this, we need to remember the subscriptions and the stream that was used to create them. What we want to get a hold of:

interface ExistingSubscription {
  stream$?: Observable<unknown>;
  subscription?: Subscription;
}

We can create a map with all this information:

const subscriptions = Symbol('subscriptions');

[subscriptions] = new Map<keyof this, ExistingSubscription>();

And work with it inside our subscribe method:

subscribe<Key extends keyof this>(
    propKey: Key,
    stream$: Observable<this[Key]>
  ) {
    const existingSubscription = this[subscriptions].get(propKey);
    if (existingSubscription) {
      if (existingSubscription?.stream$ === stream$) return;
      else existingSubscription?.subscription?.unsubscribe();
    }
    const subscription = stream$.pipe(...);

    this[subscriptions].set(propKey, { stream$, subscription });
  }

We check to see if we already have a subscription for that property name. If yes, in case it’s the same stream, we ignore the call, no need to do anything. If it’s a different stream, we unsubscribe from the old one before handling it. In the end, we store the new subscription and stream combination using the property name as a key.

This is a more complete implementation of our base class, which besides extracting all this functionality in a central place, provides us with a few advantages:

type safety (we can use only existing property names and Observable objects)
unsubscribes when the component is removed
unsubscribes from old observable if called again on the same property with a different Observable
ignores calls on the same property with the same Observable

Decorator

Now, how about that subscribe call, could we improve it a bit more? Like avoid calling it inside our connected callback manually for each property? It turns out we can! In some specific cases, like when the Observable we want to subscribe to is not a member of our class, we could improve things a bit further.

That is, by creating a decorator that will do this for us. Decorators are an experimental feature, but they are useful in certain situations.

A decorator is a special kind of function that can be attached to classes, methods, properties, or arguments. They are used in the form of @expression where expression is the name of the function. In our case we use subscribe:

export const subscribe = (stream: Observable<any>) => <K extends RxLitElement>(
  targetPrototype: K,
  propertyKey: keyof K
) => {
  if (!stream) throw new Error('Invalid stream!');

  const initial = targetPrototype.connectedCallback;
  targetPrototype.connectedCallback = function() {
    initial?.call(this);
    this.subscribe(propertyKey, stream);
  };
};

Since we want to customize how the decorator is applied to our property we created a decorator factory. That is a function that returns another function. A decorator for a property is always a function that gets the prototype and the property key, but we also want to pass in a stream for each use.

Inside the function, we monkey patch the connected callback method of our class and call the subscribe method inside it. Pretty much what we manually did before.

And we can use it for our components to simplify code even further:

class DemoElement extends RxLitElement {
  @subscribe(interval(1000).pipe(scan((acc, value) => [value, ...acc], [])))
  streamValues: number[];
}

The limitation on what streams we can use here comes from the way decorators work. We don’t have access to the class instance at the moment when the decorator is parsed, so there is no way to access the instance variables there. Hence the limitation.

You can find more information about how to create decorators here.

The end

To help with this, I’ve extracted the functionality into a small lib. Or even better, you can fetch the code from GitHub and use it in your project, if you find it useful.

If you know other solutions to this problem or have a different idea, feel free to let me know. Or why not, open a pull request 🙂.

Typed fake REST APIs

Mon, 30 Mar 2020 13:00:37 GMT

Whenever you start working on a new project, you might need to consume an API. But that API might not be written yet, or you don’t want to hit the real thing while developing the app.

In this post we’re going to have a look at using JSON Server and faker.js to create a fake REST API. You can use it for local development, testing or any other related tasks.

Basic knowledge of TypeScript and npm is required to follow along. Out of habit and personal preference, I’ll use yarn instead of npm for all the examples.

Setup

We’re going to assume you already have a TypeScript project where you want to add and use the fake API. If you do, skip to the next section. If not, and you want to follow along with the code, let’s create a simple project:

mkdir fake-rest-api && cd fake-rest-api
yarn init

Hit enter at any of the inputs to use the defaults, as long as you don’t want to fill in something more useful 🙂.

Install the latest version of TypeScript and generate a new config file:

yarn add typescript -D
yarn tsc --init

The only thing we want to change in the config file is the outDir property, we can set it to dist. By default, TypeScript will place the output in the same place as the input files. We want things to be a bit cleaner, hence using an output folder.

JSON Server

Let’s get started and create our fake API. First, install JSON Server:

yarn add json-server -D

Usually, the server will use JSON files with our data. In our case, we’re going to use TypeScript, because we want to add a bit of type safety to our fake API. Whenever our types change we want to know and make the appropriate changes in the fake data.

Create a new file server.ts, inside a src folder, and add this code to get it up and running:

export = () => ({
  test: { value: 'Hello from our fake API' },
});

The convention is to export a function that returns an object which is the structure of the fake API. The properties of the object are the routes and the values are the data.

Now we want to run the server with this file, but before we can do that we also have to compile it to plain JavaScript. Let’s create a script to do that. Add the following to package.json:

scripts: {
  "fake-api": "tsc && json-server dist/server.js"
}

It would be great if we could run both these commands with the watch flag, which they do support. This would restart the server each time we make a change. Unfortunately, last time I’ve checked, the watch mode for JSON Server was working only with JSON files. So don’t forget to manually restart the server after you make some changes to the data.

If you add this to an existing project, you can have a TypeScript configuration file only for this fake API, and you could compile it with a command like:

tsc --project ./mock-server/tsconfig.mock-server.json

This will allow you to set some project-specific settings, like a different output folder.

Built-in features

JSON Server has some great built-in features that you should be aware of. Among them, two are quite important in our case.

If you make any POST, PUT, PATCH or DELETE requests your data will be affected. You need to be aware of this when testing.

There are some built-in routes. For example, if you have a collection of items and each item has an id, you get individual access to each item without any other configuration. If the base path is */items*, you can go to */items/123*, and get the item that has an id equal to 123. This will greatly simplify your routing config. You also have built-in filter, pagination, and sort.

Custom routes

Sometimes we might want to use some custom routes. Maybe we want to simplify what a route looks like or redirect to the same data without changing the file we use to generate out API from.

To do that we can add a file named routes.json to our project:

{
  "/foo/bar/baz": "/test"
}

In this example we have a resource located at */foo/bar/baz*, which should return the same data as */test*. But we don’t want to create a deeply nested structure within our config object, so we use the routes file to redirect to test.

Also need to update the command used to start the server for this to work:

"fake-api": "tsc && json-server dist/server.js --routes src/routes.json"

Go to *foo/bar/baz* and notice we get the same result as for */test*, but the URL will remain the same.

JSON Server is packed with features and offers way more. We’ve just scratched the surface a bit here. See the official documentation for more information about what you can do with it.

Typed data

All good and nice, but so far we did not take advantage of TypeScript almost at all. Let’s assume we have an Item interface that looks like this:

export interface Item {
  id: number;
  name: string;
}

Go ahead and add this as item.ts to the project, if you did not do it already. This is an example of a type of data that we can get from a real API. Inside a data folder we can create an items file with some test data:

import { Item } from '../types/item';

export const items: { count: number; values: Item[] } = {
  count: 3,
  values: [
    {
      id: 1,
      name: 'foo',
    },
    {
      id: 2,
      name: 'bar',
    },
    {
      id: 3,
      name: 'baz',
    },
  ],
};

Each time a property is added, renamed or any other relevant change is made to the type, we’ll know right away, when compiling our server, and we’ll be able to easily update the data.

I’ve used a similar approach, but without TypeScript and believe me, it was no fun 🙂.

After we add the items object to our server file, we’ll have the new endpoint available:

import { items } from './data/items';

export = () => ({
  test: { value: 'Hello from our fake API' },
  items,
});

Since we have all the fake data inside a folder within TypeScript files, we can use this for more purposes. Like unit or integration tests and reference the same files from all our projects where this test data is required.

Fake data

When creating fake test data, we can write it manually or do a request to a real API and get some data back. But we might want to use some random fake data to test our application. For this, we’re going to use faker.js.

Faker.js is a library for generating random data and has a lot of helpful methods for generating addresses, finance information, names, and many other things. Check the documentation to find out more.

We start by installing faker.js along with types:

yarn add faker.js -D
yarn add @types/faker -D

Then we can use the faker API to generate any kind of data we want. Let’s replace the hardcoded item names with some random ones:

import { Item } from '../types/item';
import * as faker from 'faker';

export const items: { count: number; values: Item[] } = {
  count: 3,
  values: [
    {
      id: 1,
      name: faker.commerce.productName(),
    },
    {
      id: 2,
      name: faker.commerce.productName(),
    },
    {
      id: 3,
      name: faker.commerce.productName(),
    },
  ],
};

Or better yet, let’s generate a completely random number of items:

import { Item } from '../types/item';
import * as faker from 'faker';

const randomItems: Item[] = [];
for (let idx = 0; idx < faker.random.number(50); idx++) {
  randomItems.push({
    id: faker.random.number(),
    name: faker.commerce.productName(),
  });
}
export const items: { count: number; values: Item[] } = {
  count: randomItems.length,
  values: randomItems,
};

Without much hassle, we managed to generate fake data for our API.

Paths issue

I’m a big fan of using absolute paths in a TypeScript project. This allows us to replace imports like:

import { Item } from '../../../../../types/item';

with something much nicer:

import { Item } from 'types/item';

If you want to read more about this you can google ‘TypeScript paths’ or read my short article.

So if you use this, kudos to you, but you’ll have a small problem. You are required to replace all absolute paths with the relative versions after compiling to JavsScript, for this to work in all environments.

One of the most used solutions is the tsconfig-paths package. As usual, we add it using:

yarn add tsconfig-paths -D

If you have multiple projects in the same workspace and use a different TypeScript config for the fake server you can take that into account. Add this to the server file:

import * as tsConfig from '../tsconfig.json';
import * as tsConfigPaths from 'tsconfig-paths';

tsConfigPaths.register({
  baseUrl: 'dist',
  paths: tsConfig.compilerOptions.paths,
});

Here we load the main config file for the workspace and register the tsconfig-paths package using the paths configured from that one. In our sample project we don’t have this setup, so we don’t add this now.

Read-only data

As discussed above, one of the features of JSON server is that it saves any operations we make on our API. So if we make a POST/PUT request the values will be updated.

In some cases, we might not want this and we could use middleware to handle only GET requests. We can create a new file called readonly-middleware.ts in our project and using an express like syntax, handle only these requests:

function handleOnlyGet(req, res, next) {
  if (req.method !== 'GET') {
    res.status(200);
    res.send();
  } else {
    next();
  }
}
export = handleOnlyGet;

For any request that is not a GET return a 200 OK status and don’t do anything. We need to add this to the script used to start the server:

"fake-api": "tsc && json-server dist/server.js --routes src/routes.json --middlewares dist/readonly-middleware.js"

End

Hopefully, you’ve found this useful, and you’ll be able to use it in your projects. The code can be found on GitHub. In a future post we’ll experiment with using JSON Schema Faker to achieve a similar result. Keep hacking!

Custom Angular directives

Fri, 19 Jul 2019 23:46:37 GMT

This is a post written for AgGrid, you can see the original here.

Intro

In this post, we are going to talk about one of the most important building blocks of an Angular application. As we know, an application is like a tree of components. And these components are actually directives with a template.

We’ll focus on Angular directives, both attribute and structural. And we’ll talk a bit about components. What they are and how can we create custom ones. Some basic knowledge of Angular and TypeScript is required to follow along.

Overview

Directives allow us to extend or manipulate the DOM. Angular components, which as we said, are directives with a template, allow us to extend the DOM by creating custom components along with the native ones like button or div. We know they are similar to directives because internally they use the directive API.

Directives can be split into two categories: attribute and structural. As the name suggests, attribute directives will be able to change the characteristics of a single element. While the structural ones are able to add or remove blocks of elements.

Some examples of structural directives are NgIf, used to add/remove an element from the DOM based on a condition:

<p *ngIf="condition">This shows up only if the condition is true</p>

And NgForOf, used to iterate over a collection and render a template for each item:

<li *ngFor="let item of items">
  <p>{{ item.text }}</p>
</li>

As for attribute directives, NgClass is the first that comes to mind. It is used to dynamically add/remove CSS classes associated with an element:

<div [ngClass]="['first', 'second']">...</div>

To declare a directive, we must use the @Directive decorator. This will mark that specific class as an Angular directive.

Selectors

The minimum thing we need to pass to the Directive decorator is the selector property:

@Directive({ selector: '[foo]' })
export class FooDirective {}

This is a CSS selector that will identify the directive inside a template. It will allow Angular to create an instance of the directive whenever needed. These CSS selectors are quite powerful.

A most common scenario is to target attributes of an element [foo]. The brackets ([]) mark it as an attribute selector. Meaning it will look at all the elements in the template that have an attribute called foo. We could also limit this to specific elements by extending the selector: div[foo]. This will locate all the div elements that have an attribute named foo.

Playing around with this we could select all elements of a specific type, an element with a specific class or even using pseudo-classes like :not. However, you should keep in mind that it does not support nesting selectors.

For most cases, a selector for a specific attribute is what we need, but we can also get pretty wild with them.

Export

Another important property for a directive is exportAs. This defines a name that can be used to fetch an instance of our directive in our template. For example in our custom directive:

@Directive({
  selector: '[foo]',
  exportAs: 'appFoo',
})
export class FooDirective {}

We’ve added a value for exportAs and now we could use it in a template:

<div [foo] #dirInstance="appFoo"></div>

This comes in handy when we want to show certain values of the directive, call methods on it, or pass it as a reference to some other method. For a more practical example, suppose we have an input and we want to send the text to a function call from the template:

<input type="text" #myInput />
<button (click)="performAction(myInput.value)">Click me</button>

There are a few other properties that we can set for a directive, the above two being just some examples. You can see all of them in the very good Angular documentation.

Custom attribute directive

Now to some more real-world examples. We’ll start with a simple attribute directive that will set the focus to an element whenever it’s displayed on the screen.

We start with the basics and create the directive class:

@Directive({ selector: [appFocus] })
export class AppFocus {}

Adding the attribute that matches the selector to an element will tell Angular to create an instance of the directive and attach it:

<input type="text" appFocus />

To get an instance of the element that the directive is attached to, we can use Angular dependency injection mechanism. Adding a reference to ElementRef, in the constructor will get us access to what we need:

constructor(private elementRef: ElementRef) {}

Now we have access to the element and bring focus to it when needed. We can implement the OnInit lifecycle hook and focus the element there:

@Directive({ selector: [appFocus] })
export class AppFocus implements OnInit {
  constructor(private elementRef: ElementRef) {}

  ngOnInit() {
    this.elementRef.nativeElement.focus();
  }
}

This will work, but there are a few things we can improve.

We might want to disable this functionality dynamically sometimes. So we can add an input to our directive to control this:

@Input() appFocus: boolean = false;

Notice how we used the same name for the input as the selector. This a common practice and will simplify usage:

<input type="text" [appFocus]="shouldFocus" />

Now we have to check when the appFocus input will get a new value, and if it’s true, focus the element. We can achieve this using the OnChanges lifecycle hook:

ngOnChanges(changes: SimpleChanges) {
  if (changes.appFocus) {
    this.elementRef.nativeElement.focus();
  }
}

A better real world example would be to place the directive on an element without any property binding:

<input type="text" appFocus />

This adds a subtle problem. The value for our input becomes an empty string and this will evaluate to false. So our directive will no longer work. We have to update the if condition to properly transform a string value to boolean. This is called coercion, and if we’re using Component Dev Kit from Angular Material, we have this utility (coerceBooleanProperty) built in.

Lastly, we can see that we’re using the nativeElement property to focus. This might be tricky and is not something usually recommended. This will fail in an environment where the DOM is not available and some other custom rendering is used. One way to fix this, is to disable our functionality for such environments.

One way to achieve this is by using the isPlatformBrowser function from angular common:

import { isPlatformBrowser } from '@angular/common';

This function takes as argument a platform ID that we can also fetch from Angular core:

import { PLATFORM_ID } from '@angular/core';

Now we can construct an isBrowser property and use it in our directive:

readonly isBrowser: boolean;
constructor(
  private elementRef: ElementRef,
  @Inject(PLATFORM_ID) platformId: string,
) {
  this.isBrowser = isPlatformBrowser(platformId);
}

Applying this inside our ngOnChanges method will fix the problem:

if (changes.appFocus && this.isBrowser) {
  this.elementRef.nativeElement.focus();
}

We can use this, and our code will only work inside a browser, since we’re using a browser API. Or, as an alternative, we could extend Renderer2 and implement the focus method. Using this, we’ll be sure it works on any platform.

This is a sample on how the directive will work:

You can see all the code on StackBitz.

Custom structural directive

Now, to a more complex example, we can have a look at how we could implement a clone of the NgIf directive. This will demonstrate how to create a directive that changes the DOM by adding or removing an element.

We start as before with a class and the directive selector:

@Directive({ selector: '[appIf]' })
export class IfDirective {}

After we also add it to the app module, we can use it in our template:

<p appIf>
  Start editing to see some magic happen :)
</p>

We’ll see later on why we need to make a small change to this.

Since we want to control when to show and hide the element in a dynamic way we’ll add an Input for this. We use the same name as the directive for ease of use:

@Directive({ selector: '[appIf]' })
export class IfDirective {
  @Input() appIf: boolean;
}

And the template becomes:

<p [appIf]="show">
  Start editing to see some magic happen :)
</p>

In our directive, we can implement the OnChanges lifecycle hook so we can react whenever the input is changed. Now we need to think about how we could add or remove the element.

For this purpose, Angular provides us with a View Container. This is a special container where one or several views can be attached to a component. If you want to know more about this, go on and read this great article about working with DOM in Angular. The views can be created by getting a new instance of a component with createComponent() or by using a template reference with the createEmbeddedView() method.

We’ll use the last one, to create an embedded view from our existing HTML. We first need to import the View Container:

import { ViewContainerRef } from '@angular/core';

And then inject it in the constructor:

constructor(private container: ViewContainerRef) {}

Now we have an instance of this class in our directive. It represents a container linked to the Html paragraph element from our template. And it allows us to add or remove siblings of this element.

To be able to add or remove our content whenever we need, we have to make some changes to our directive. Right now it’s attached to the paragraph element, and this one will be rendered right away.

To tell angular that our directive is a structural one, we can use the * notation. Whenever you see this in front of a directive it means it will manipulate the DOM. So we update our template as so:

<p *appIf="show">
  Start editing to see some magic happen :)
</p>

This is syntactic sugar, it allows us to write less code. This will actually be transformed to:

<ng-template [appIf]="show">
  <p>
    Start editing to see some magic happen :)
  </p>
  <ng-template></ng-template
></ng-template>

We can see that everything is wrapped inside an ng-template, and that our directive, which looks like a normal one now, was moved to this new element. Ng-template is an Angular element for displaying content. Similar to the HTML template element, the content is not rendered right away. Angular will replace it with a debug comment and each directive can do something different with the HTML elements wrapped by this.

In order to get a reference to this template, we can use the TemplateRef class. If we import it from @angular/core we can add it to the constructor and an instance will be provided to us:

constructor(private container: ViewContainerRef,
            private template: TemplateRef<any>,
) {}

Now we have an instance of the view container, which is bound to a host element where we can add or remove elements. An important point to note here is that the view container reference points to a template element (rendered as HTML comment), not the paragraph. We also have a reference to the template that we want to show or hide. Inside our ngOnChanges method we can update the view as needed:

ngOnChanges() {
  if (this.appIf) {
    this.container.createEmbeddedView(this.template);
  }
  else {
    this.container.clear();
  }
}

All the code is available on StackBlitz. Don’t hesitate to check it out and play with it to better understand the example.

A nice caveat here is that if you forget to use the * notation to mark the directive as structural, things will not work. You can quickly sort this our from the error message. If you get one saying that it cannot inject a TemplateRef, this is what it’s trying to say. There is no ng-template, so no template to get a reference to.

Combining both types

Now, we’ve seen these two types of directives, we can also use a directive to programmatically add components to our application. For example, we can have an icon component and we want to create a directive that will show or hide it when the element is hovered.

Let’s create a simple component that shows an icon based on some input string. A simple implementation would be something like this:

@Component({
  selector: 'app-icon',
  template: `
    <i class="fa" [ngClass]="iconName"></i>
  `,
})
export class AppIconComponent {
  iconType: 'home' | 'bars' | 'trash' | 'close' | 'folder' = 'folder';
  get iconName() {
    return 'fa-' + this.iconType;
  }
}

We have all the basic things here. A simple selector, a template and an icon property to hold the type of icon that we want. We make use of the NgClass directive to add the desired icon class to the element.

This is how it would look when used:

<span [appIcon]="'home'">My Home</span>

For this, to work, we also need to import font awesome. In the StackBlitz example I’ve added an import inside the main styles.css file:

@import url('https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css')

As before, we add our component to the declarations array of the application module. But we need to do one more thing here. We also need to add it to the entryComponents array. This is used for any component that Angular loads dynamically. Which means this component is not used statically in any other static angular component’s template, as in our case. If we omit this, Angular will remove the component from the application bundle, believing that it’s not used. This will, of course, crash our app when we want to programmatically instantiate and add the component.

We can create our directive, that will look and behave like an attribute directive:

@Directive({ selector: '[appIcon]' })
export class AppIconDirective {
  @Input() appIcon: 'home' | 'bars' | 'trash' | 'close' | 'folder';
}

Selector and input with the same name are present.

The same as for our structural directive, we leverage the View Container to be able to add elements. This is still available even though it’s not a structural directive.

One last thing we need is to create an instance of our icon component. In Angular, this is done by a so-called component factory, and in order to get an instance of it for our component, we need to make use of a component factory resolver. Our constructor will look like this:

constructor(private container: ViewContainerRef,
            private resolver: ComponentFactoryResolver) {}

To create an instance of the component we:

get an instance of our component factory
create the component and attach it to the view
set the icon type property on the component

It looks like this:

const factory = this.resolver.resolveComponentFactory(AppIconComponent);
const componentRef = this.container.createComponent(factory);
componentRef.instance.iconType = this.appIcon;

Now, since we want to show this when the host element is hovered we add a HostListener for the mouseenter event:

@HostListener('mouseenter')
showIcon() {
  const factory = this.resolver.resolveComponentFactory(AppIconComponent);
  const componentRef = this.container.createComponent(factory);
  componentRef.instance.iconType = this.appIcon;
}

This will show the icon, we also need to handle mouseleave event to hide it:

@HostListener('mouseleave')
hideIcon() {
  this.container.clear();
}

One important thing to remember here, is that the icon element, will be a sibling of the element where the directive is used, and not a child.

As with the other examples, all the code is available on StackBlitz.

Conclusion

Directives are the building blocks of Angular. Hopefully, now you have a better understanding of what they are and how they work. Let me know what you think and what other interesting ways of using directives you’ve found.

Creating a toast service with Angular CDK

Wed, 21 Nov 2018 23:46:37 GMT

OK, not that kind of toast message, but something close 😃. Prepare yourself, this will be a long read, starting from scratch up to a full-blown, almost, production-ready toast service.

Angular Material is a great material UI design components library for your Angular applications. All the common parts needed to create components, things like layout, accessibility, common components like grid or tree have been isolated inside the CDK (Component Development Kit).

You can use the CDK to develop custom components. In this post, we will explore how to leverage this to create a toast service that can be used to show toast messages throughout your application.

Setup

First, we need to add CDK as a dependency to our project:

yarn add @angular/cdk

or if you prefer npm:

npm install @angular/cdk

Now we can use what we need from the CDK. We’ll mainly use the Overlay package that will allow us to open floating panels around the screen which is exactly what we need to show toast messages. Internally this package is using the Portal package that allows us to render dynamic content throughout the application.

Toast component

We can start with the basic thing that we need, meaning a toast component:

	import { Component } from '@angular/core';

	@Component({
	selector: 'app-toast',
	template: `
	<div>This is a toast message</div>
	`
	})
	export class ToastComponent { }

view raw toast_v1.ts hosted with ❤ by GitHub

This is the simplest component possible, a selector and a <div> with some text. Further down, we’ll extend it to suit our needs. But for now we’ll focus on displaying it on the screen.

First thing after we have a component is to add it to an NgModule. In this case since we’ll not use the component directly in a template we’ll have to also add it to the entryComponents list, otherwise, the compiler will notice it’s not used and will remove it from the final bundle.

Since we’re good citizens and we can think like we’re creating a library we can create a module file just for this toast component:

	import { NgModule } from '@angular/core'

	import { ToastComponent } from './toast.component';

	@NgModule({
	declarations: [ToastComponent],
	entryComponents: [ToastComponent]
	})
	export class ToastModule { }

view raw toast.module_v1.ts hosted with ❤ by GitHub

The only thing left to do with this module is add it in the imports array of our main application module.

Toast service

Now that we have a component and a module for our toast, we can start thinking about what we need next. From our application, we want to programmatically show toast messages whenever it’s needed. So the best option for this would be a toast service:

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

	@Injectable({
	providedIn: 'root'
	})
	export class ToastService {
	show() { }
	}

view raw toast.service_v1.ts hosted with ❤ by GitHub

We have a simple service with an empty (for now) method show. The only notable thing is that we use the new providedIn attribute of the Injectable decorator that’s available since Angular 6, specifying ‘root’ as a value. This means that this service will be registered as a singleton in our application, and that we don’t need to add it to the providers array anymore.

This actually means that our services are now tree-shakeable. If we have a service defined in our application, but it’s not referenced in any other place, it will be removed from the final bundle. This was not the case when we had to add them to the providers array of a module. Angular itself is starting to move its built-in services to this way of registering them and I suggest you start doing it as well.

And now to our show toast method: we’ll need to get an instance of the Overlay service, create an instance of our toast component, and display it somewhere on the screen.

We can achieve this with three lines of code:

const overlayRef = this.overlay.create();
const toastPortal = new ComponentPortal(ToastComponent);
overlayRef.attach(toastPortal);

First, we create an overlay using the create method on the overlay service. This will create a container in our application that will host our toast message. We get back a reference to this container that we can use to control it.

Secondly, we have to create an instance of our toast component. Since we’re trying to dynamically render a component, we can use the portal package to achieve this. We import the ComponentPortal class from @angular/cdk/portal and we create a new instance passing our toast component class as an argument. This will create an instance of our component and give us back a wrapper that we can use to handle it.

The last thing we need to do in order to show our toast is to get our toast portal and attach it to the overlay container that we previously created.

Now, if we call the show method on our toast service in our app we’ll see a div with a text added to our application. But it does not look like a floating container or a toast. Let’s quickly fix this.

The default positioning classes used by the overlay container are exported from CDK so that we can use them. Either we import them or create some custom ones. Since I’m always in favor of reusing functionality, we’ll import the existing ones.

We can go to our main styles.css file and import the prebuilt overlay css there:

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

If we use scss we can import it too, but we’ll also have to call the mixin. Otherwise, nothing will happen:

@import '~@angular/cdk/overlay';

@include cdk-overlay();

If we call our method, we’ll see that the message is floating in our top left corner. If we call the method multiple times, we’ll notice that we can see only one message, while previously they would stack one beneath the other. We can see only one because by default now they are placed on top of each other.

In order to make it look more like a toast, we’ll add some basic styling (similar to what Bootstrap has) and use some of the icons that Angular Material provides.

Our toast component will look a bit more complex now:

	<div class="toast">
	<mat-icon>done</mat-icon>
	<div>This is a toast message</div>
	<mat-icon (click)="close()">close</mat-icon>
	</div>

view raw toast.component_v2.html hosted with ❤ by GitHub

Now we have defined the toast CSS class to make it look a bit more like a toast message:

	.toast {
	position: relative;
	display: flex;
	justify-content: space-around;
	margin-bottom: 20px;
	padding: 10px 15px 10px 48px;
	width: 290px;
	background: #fff;
	border-width: 1px;
	border-style: solid;
	border-color: #dddddd #d6d6d6 #cfcfcf;
	box-shadow: 0 2px 4px rgba(0, 0, 0, 0.11);
	}

view raw toast.component_v1.css hosted with ❤ by GitHub

I assume we don’t always want to show the text “This is a toast” when displaying the message. We’ll make this configurable so that each time we call the show method we can pass in what text we want to show.

Since we’ll extend this further on, let’s create an interface to represent the data we might send:

export interface ToastData {
  text: string;
}

For now, it’s OK if we just have the text there. We also update the calls to our service with something like:

toastService.show({ text: 'Everything is ok!' });

Next, we have to pass this data to our component, somehow. We’re going to achieve this using Angular’s dependency injection system. In the toast component class we’ll add it to the constructor:

export class ToastComponent {
  constructor(readonly data: ToastData) {}
}

Then we’ll use it in the component’s template:

<div>{{ data.text }}</div>

We also have to make sure we add this data to the component injector so we have to update our toast service a bit. Thankfully, when we create the component portal (for the toast) we can pass in an injector that will be attached to it. Angular CDK provides a PortalInjector class which extends the basic Injector one from Angular so we’ll use it.

First, we create a map with the custom tokens we want to add in the injector and then instantiate the PortalInjector:

const tokens = new WeakMap();
tokens.set(ToastData, data);

const injector = new PortalInjector(parentInjector, tokens);

The first parameter of the portal injector constructor is a *parent injector, *and we can get an instance of it using dependency injection. This is used to retrieve any dependencies that we don’t add to the custom tokens and we use in the toast component.

Then we can create our component portal with our injector attached:

const toastPortal = new ComponentPortal(ToastComponent, null, injector);

But if we try it, we’ll notice it won’t work yet. ToastData is an interface which is not a valid object for our map. There are two options here, one would be to make it a class, and everything will work. Or, we can create a custom InjectionToken and use that one when we create the map and require the data.

If we want to go for the injection token, we’ll have to create it:

const TOAST_DATA = new InjectionToken<ToastData>('TOAST_DATA');

Use it in our map:

tokens.set(TOAST_DATA, data);

And we also update the constructor for the Toast component to use the inject decorator:

constructor(@Inject(TOAST_DATA) readonly data: ToastData) { }

Now our toast is configurable and we can pass in whatever text we want.

As a bonus to this, it would be easy enough to configure the type of toast we’re showing and maybe display a different image based on that.

We can define our toast type as one of success, info or warning. We left error out because it’s not a good UX practice to show errors in the form of a toast.

We can create a TypeScript union type to represent this information:

export type ToastType = 'warning' | 'info' | 'success';

And extend our ToastData to include it:

export class ToastData {
  text: string;
  type: ToastType;
}

When we want to show a toast message we also specify the type:

toastService.show({ text: 'Everything is ok!', type: 'success' });

You can use any icons you want but, in our case, we’ll go with the ones provided by the Material library. If we don’t have it already we need to make sure we have the material module added as a dependency:

yarn add @angular/material

Then we have to add the icon font to our HTML file by including this line:

<link
  href="https://fonts.googleapis.com/icon?family=Material+Icons"
  rel="stylesheet"
/>

Add the Material icon module to our imports:

	import { NgModule } from '@angular/core'
	import { OverlayModule } from '@angular/cdk/overlay';
	import { MatIconModule } from '@angular/material/icon';

	import { ToastComponent } from './toast.component';

	@NgModule({
	imports: [OverlayModule, MatIconModule],
	declarations: [ToastComponent],
	entryComponents: [ToastComponent]
	})
	export class ToastModule { }

view raw toast.module_v2.ts hosted with ❤ by GitHub

And finally, we’re able to display an icon:

<mat-icon>info</mat-icon>

The names of the icons we want to show are identical for two of our toast types (warning and info), but when we have a success toast type we want to show a done icon. We can easily fix this by creating a local property in the component and initializing it in the constructor:

this.iconType = data.type === 'success' ? 'done' : data.type;

Updated image usage:

<mat-icon> {{ iconType }} </mat-icon>

OK, we have a toast message. Now how do we get rid of it? We have to implement some self-closing logic and allow it to be closed both from the UI and programmatically.

In order to make sure we can close the toast from the UI we have to add a close icon/button. We can do that by adding it in the template:

<mat-icon (click)="close()">close</mat-icon>

Now really, how do we close the toast? It looks like it’s not that complicated at all. We show the toast using an overlay, and when we create the overlay we get an instance of an overlay reference back. We can use this to do several things, including destroying it by calling the dispose method:

this.overlayRef.dispose();

Similar to how we got an overlay reference instance when creating one, we also want to create a toast reference that we can use and return using our service. The only thing we need in it now is the close method:

	import { OverlayRef } from '@angular/cdk/overlay';

	export class ToastRef {
	constructor(readonly overlay: OverlayRef) { }

	close() {
	this.overlay.dispose();
	}
	}

view raw overlay-ref_v1.ts hosted with ❤ by GitHub

We pass in the overlay reference and only expose the close method that will call dispose. We’ll use it in two places from the start. We’ll return it to the user from the show method of the toast service. And, we’ll pass it to the toast component so it can close itself:

	import { Injectable, Injector } from '@angular/core';
	import { Overlay } from '@angular/cdk/overlay';
	import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';

	import { ToastComponent } from './toast.component';
	import { ToastData } from './toast-config';
	import { ToastRef } from './toast-ref';

	@Injectable({
	providedIn: 'root'
	})
	export class ToastService {
	constructor(private overlay: Overlay, private parentInjector: Injector) { }

	showToast(data: ToastData) {
	const overlayRef = this.overlay.create();

	const toastRef = new ToastRef(overlayRef);
	const injector = this.getInjector(data, toastRef, this.parentInjector);
	const toastPortal = new ComponentPortal(ToastComponent, null, injector);

	overlayRef.attach(toastPortal);

	return toastRef;
	}

	getInjector(data: ToastData, toastRef: ToastRef, parentInjector: Injector) {
	const tokens = new WeakMap();

	tokens.set(ToastData, data);
	tokens.set(ToastRef, toastRef);

	return new PortalInjector(parentInjector, tokens);
	}
	}

view raw toast.service_v2.ts hosted with ❤ by GitHub

Instantiate it by passing the overlay reference, return it from the method and add it to the tokens when we create the injector.

In the toast component, we implement the close method. When the user clicks the close icon we actually do something and use a setTimeout to automatically hide the toast after an interval:

	import { Component, OnInit, OnDestroy } from '@angular/core';

	import { ToastData } from './toast-config';
	import { ToastRef } from './toast-ref';

	@Component({
	selector: 'app-toast',
	templateUrl: './toast.component.html',
	})
	export class ToastComponent implements OnInit, OnDestroy {
	iconType: string;

	private intervalId: number;

	constructor(readonly data: ToastData, readonly ref: ToastRef) {
	this.iconType = data.type === 'success' ? 'done' : data.type;
	}

	ngOnInit() {
	this.intervalId = setTimeout(() => this.close(), 5000);
	}

	ngOnDestroy() {
	clearTimeout(this.intervalId);
	}

	close() {
	this.ref.close();
	}
	}

view raw toast.component_v1.ts hosted with ❤ by GitHub

Awesome! Let’s make some changes to correctly show toasts one beneath the other.

Multiple toast messages

Since we want to show the next toast relative to the last one that was shown, it will be useful to remember the last one created. So let’s create a private variable *lastToast *and store the reference to the last toast created.

And now that we have this reference we need to add another method on it that will allow us to get the position of the toast message on the screen:

getPosition() {
    return this.overlay.overlayElement.getBoundingClientRect();
}

We have an instance of the overlay class and it has the overlayElement property that is the actual HTML element. From that, we can use the getBoundingClientRect method to get the actual size and position of the element. We will use this to know where the last element is displayed on the screen and show the next one in the correct position.

Let’s configure the toast service to show toasts where we want. When calling the create method on the overlay service we can also pass in a config object.

Conveniently the overlay service has a position method for us to use that will expose in a fluent API style all the options that we can set. For example, if we want to show our toasts on the right side of the screen, relative to the global window we can do something like:

const positionStrategy = this.overlay
  .position()
  .global()
  .right();

And then pass this in when creating the overlay:

const overlayRef = this.overlay.create({
  positionStrategy,
});

In order to stack the toast messages below each other, we have to add a top position and compute it. We’ll use the getPosition method we’ve added in the toast reference class for this:

getPosition() {
    const position = this.lastToast ?
        this.lastToast.getPosition().bottom : 0;

    return position + 'px';
}

If there is a last toast, we get the bottom position from that one. If not, we use 0 or a default value. Since the position API expects a CSS style value we have to add ‘px’ and convert the whole result to a string.

Adding this to the initial position creation strategy:

const position = this.overlay
  .position()
  .global()
  .right()
  .top(this.getPosition());

Cool! All the toast messages show up nicely and in order. 👍

Dynamic content

For sure there will be some cases where a simple text message is not enough. Maybe we want to show an anchor tag or even a button, or something more complex in our toast. For this, we’ll add support for templates.

First, we extend the ToastData object that we passed into our show method inside the toast service so that we can either pass in a text that we want to show or a template reference, optionally with a context object:

	export class ToastData {
	type: ToastType;
	text?: string;
	template?: TemplateRef<any>;
	templateContext?: {};
	}

view raw toast_data.ts hosted with ❤ by GitHub

We marked all three of text, template, and templateContext as options so we can pass in either of them. One might want to treat the case when nothing is passed in though. 😄

With this in place, we have to update the template of our toast message to account for this new template reference that might be used. In order to obtain this, we’ll use the ng-template component provided by Angular:

	<ng-container *ngIf="data.text; else templateRef">
	{{ data.message }}
	</ng-container>

	<ng-template #templateRef>
	<ng-container *ngTemplateOutlet="data.template; context: data.templateContext">
	</ng-container>
	</ng-template>

view raw toast.component_v3.html hosted with ❤ by GitHub

We have a container that we show only if we have a text property. If not, we just show the template also providing the context.

And that’s it. Now we can also pass template references to our toast service.

Animations

That’s all good and nice, but we can make our toast message even more awesome. How? By adding animations! 😃

The Angular animations API is easy to use and you can quickly create nice effects with it. For a detailed introduction check out the official docs.

In our case, we’ll add two simple fade in and fade out animations for our toast messages.

In order for this to work you need to import the BrowserAnimationsModule and use it in your application:

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';

@NgModule({
    imports: [ BrowserAnimationsModule ]
)}
export class CoreModule {}

Then, we can go on and create some animations. I find it best to isolate different things in different files so we can create a file where we specify our animations:

	import {
	AnimationTriggerMetadata,
	trigger,
	state,
	transition,
	style,
	animate,
	} from '@angular/animations';

	export const toastAnimations: {
	readonly fadeToast: AnimationTriggerMetadata;
	} = {
	fadeToast: trigger('fadeAnimation', [
	state('in', style({ opacity: 1 })),
	transition('void => *', [style({ opacity: 0 }), animate('{{ fadeIn }}ms')]),
	transition(
	'default => closing',
	animate('{{ fadeOut }}ms', style({ opacity: 0 })),
	),
	]),
	};

	export type ToastAnimationState = 'default' \| 'closing';

view raw toast-animation.ts hosted with ❤ by GitHub

If we ignore the imports, which are almost half of the code, the rest is not that complicated.

We have a toastAnimations object with a fadeToast property. We use the trigger method to specify the name of this animation and some metadata about it.

Firstly, we specify the style that we want to have in the default state, mainly that we want opacity to be 1. Then we specify the two transitions that we care about. Basically, when the element will be shown which can be represented with the void => ** *expression. And, one when the state will change from default to *closing. _Now we could have tried to use the reverse and express the transition as _ => void* *which is also perfectly valid. Although, it would not have helped us much since the element would have already been removed, so there would not be anything to animate.

Inside the animate methods we specify the duration of the animation, but since we want to make this configurable we use something similar to interpolation to specify a value:

animate('{{ fadeIn }}ms');

Lastly, we have defined a union type to specify the state in which our animation can be: default or closing.

Inside our toast component we have to add the animation to the animations array of the component decorator and declare an animationState property to hold the current value:

import { toastAnimations, ToastAnimationState } from './toast-animation';

// ...

animations: [toastAnimations.fadeToast],

// ...

animationState: ToastAnimationState = 'default';

With this in place, we can update the template with the animation:

	<div class="toast"
	[@fadeAnimation]="{value: animationState, params:
	{ fadeIn: 1000, fadeOut: 1000 }}">
	<mat-icon>{{ iconType }}</mat-icon>
	<div>{{ data.text }}</div>
	<mat-icon (click)="close()">close</mat-icon>
	</div>

view raw toast.component_v3.html hosted with ❤ by GitHub

We have to use the trigger name that we defined for our animation, in our case *fadeAnimation *and bind an object to it, similar to property binding. Inside the object we specify two properties: the value that is bound to our component property that holds the animations state, and a params property where we specify configurable values that we use inside the animation.

The only thing left to do is to update our code so that the fade out animation is also visible. Right now we just remove the element from the screen, we’ll have to manually update the state property for this.

When our component was initialized we created a timer that will dispose the toast. What we want to do is start the animation instead, something like:

ngOnInit() {
    this.intervalId =
        setTimeout(() => this.animationState = 'closing', 5000);
}

And now we handle the animation done event to actually close the toast. Add the event handler inside the HTML template:

(@fadeAnimation.done)="onFadeFinished($event)"

Create the function that will take care of this:

	onFadeFinished(event: AnimationEvent) {
	const { toState } = event;
	const isFadeOut = (toState as ToastAnimationState) === 'closing';
	const itFinished = this.animationState === 'closing';

	if (isFadeOut && itFinished) {
	this.close();
	}
	}

view raw fade_out_handler.ts hosted with ❤ by GitHub

As a bonus, you could reset the time whenever the user moves the mouse on a toast message. 😉

Global configuration

Maybe we want to configure the margin from the top/right where we show the toast message, or the fade in fade out animations time. We should do this in a simple and consistent way throughout our application.

A perfect place to set a global config would be the NgModule we created for our toast. We create a forRoot method and we allow the consumers to specify a config object.

Firstly we should define an interface for this toast config object, something like:

	export interface ToastConfig {
	position?: {
	top: number;
	right: number;
	};
	animation?: {
	fadeOut: number;
	fadeIn: number;
	};
	}

view raw toast_config.ts hosted with ❤ by GitHub

Also we should provide some default values that we can use when setting things up in case nothing is specified:

	export const defaultToastConfig: ToastConfig = {
	position: {
	top: 20,
	right: 20,
	},
	animation: {
	fadeOut: 2500,
	fadeIn: 300,
	},
	};

view raw toast_config_default.ts hosted with ❤ by GitHub

Now back to our module file, we can implement the forRoot method that will accept an argument of type ToastConfig and add it to the providers array so we can use it in our service:

	public static forRoot(config = defaultToastConfig): ModuleWithProviders {
	return {
	ngModule: ToastModule,
	providers: [
	{
	provide: TOAST_CONFIG_TOKEN,
	useValue: { ...defaultToastConfig, ...config },
	},
	],
	};
	}

view raw toast_for_root.ts hosted with ❤ by GitHub

If we don’t pass anything, we have the default value for the config. If we pass something, it might be just a part of the config that we want to overwrite, for example the positioning. So when we provide the value we destructure the default config and then overwrite any properties that were specified by the user.

Once we have this in the providers, we can inject it in the toast service constructor and inside the toast component constructor so we can use the values:

@Inject(TOAST_CONFIG_TOKEN) readonly *toastConfig*: ToastConfig

Then we can update the position methods to use the top and right properties from the config, and the animation inside the toast component template:

[@fadeAnimation]="{value: animationState,
    params: {
        fadeIn: toastConfig.animation.fadeIn,
        fadeOut: toastConfig.animation.fadeOut
    }
}"

This way we have a nicely setup global configuration for our toast service. This can easily be extended to add any other properties we want and will allow this service to be used inside different projects that might have slightly different needs.

As a different and probably cleaner alternative, one can created a single overlay and a container component that will be displayed in the overlay. All the toast messages can be added inside this container component and the template will be an ngIf directive going over them. This can make working with positioning and animations easier. Thanks to Alex Okrushko for the feedback and suggestion.

Hope this helped and that you managed to read all the way to here 😉

This is how our simple toast messages look and behave:

You can see the code on StackBlitz.

NgRx: tips & tricks

Wed, 09 May 2018 23:46:37 GMT

Update 2020: NgRx has several new releases. Not everything written here is still up to date. I’ll try to update the article as I have time.

NgRx is one of the good options that developers choose to use in their Angular applications whenever the application grows a bit and something is needed to manage the state.

While working with NgRx I’ve found out a series of tips that I would have loved to know beforehand. Some of them I’ve discovered looking at different ways people were handling things and some I’ve found while constantly refactoring the code to make it cleaner and easier to understand.

This series of tips is split into four categories, according to each part of NgRx that they apply to:

Actions
Effects
Reducers
General

Actions

Use classes for all actions

This will grant you awesome benefits like type safety in all the places where you use the action: components, reducers, effects, etc.

This might feel a bit weird when you start using it, as one would prefer the less clutter way of factory methods, but using classes will pay off on the long run:

import { Action } from '[@ngrx/store](http://twitter.com/ngrx/store)';

export const LOG_ERROR = '[Logger] Log Error';

export class LogError implements Action {
  readonly type = LOG_ERROR;
  constructor(readonly payload: { message: string }) { }
}

Once we have this in place we can benefit in the reducer:

export function reducer(
    state = INITIAL_STATE,
    action: LogError | LogWarning,
){
    switch (action.type) {
        case LOG_ERROR:
            return {
                error: action.payload,
            };
        default:
            return state;
    }
}

In this case we are telling the reducer what kind of actions we expect and we use those in the switch statement below (read on to see how to group them together).

One important thing there is that for TypeScript to be able to infer the type and allow us to benefit from this type of guards we must use readonly on the type property in the class. Normally it’s a property of type string, that can be changed as needed, but adding readonly will make it a string literal, restricting the type to our specific string value and enabling the type guards.

If you export the type declarations, beside readonly you also have to write the properties with an extra typeof:

readonly type: typeof LOG_ERROR = LOG_ERROR;

Otherwise the type will be widen to string and that’s not what you want.

We can also have the type guard in NgRx Effects, where it really helps:

@Effect()
logError$: Observable<Action> = this.actions$.pipe(
    ofType<LogError>(LOG_ERROR),
    tap(action => console.log(action.payload))
)

We used ofType to specify the action that this effect will handle and from that point on we can be sure that the payload object is what we expect, meaning an object with the string property named message. This is really useful when you write or refactor the code because the compiler will show an error each time you make a mistake.

Always name the property of the action payload

The Action interface from NgRx states that our class needs to have only a property type of type string. For consistency and some extra benefits, whenever a payload is needed in the action, we should name the property simply payload.

Also, I always prefer to have the payload an object that has other properties even if just one. So for example, in the LogError case one can easily defined it like:

constructor(readonly payload:string ) { }

I find it more understandable to have an object and state what that value represents:

constructor(readonly payload: { message: string }) { }

Inside a larger app one will have for sure actions that have objects as a payload. Using it like that all the time makes it consistent and easier to read and understand the intent.

Given our logger actions example we can assume we have multiple actions. Even though generally it’s good to have a class per file, in the case of NgRx Actions I find it better to have all the related actions in the same file.

	import { Action } from '@ngrx/store';

	export const LOG_ERROR = '[Logger] Log Error';
	export const LOG_WARNING = '[Logger] Log Warning';
	export const LOG_INFO = '[Logger] Log Info';

	export class LogError implements Action {
	readonly type = LOG_ERROR;
	constructor(readonly payload: { message: string }) { }
	}

	export class LogWarning implements Action {
	readonly type = LOG_WARNING;
	constructor(readonly payload: { message: string }) { }
	}

	export class LogInfo implements Action {
	readonly type = LOG_INFO;
	constructor(readonly payload: { message: string }) { }
	}

view raw logger.actions.ts hosted with ❤ by GitHub

Group actions in a union type

Following the previous tip, we can group all the classes in a TypeScript union type:

export type LoggerActions = LogError | LogWarning | LogInfo;

This will be helpful when we work with them and we want to state that some specific type can be any of the Logger actions without having to write all of them each time.

Use short names for constants and classes

In order to show better the intent we usually go for descriptive names. But in some cases this can get out of hand quickly and it could mess up the discoverability when we use code completion to find something.

Suppose we have a Documents entity. We could create actions like DocumentsFetch, DocumentsFetchSuccess, DocumentsSortChanged with the corresponding constants named in the same way. However this will make most of our names quite long and when we want to use an action from here, everything will start with Documents which is not that great.

Since all of the actions are in separate files we can simply use shorter names for them. For constants:

export const FETCH = '[Documents] Fetch';
export const FETCH_SUCCESS = '[Documents] Fetch Success';
export const SORT_CHANGED = '[Documents] Sort Changed';

We have ‘[Documents]’ in front for all of the strings though. This string is actually the type of the action and we really want to have them different.

Then we can name our actions in the same way: Fetch, FetchSuccess and SortChanged. Since they are all in the same file we can import everything at once:

import * as documentActions from './document.actions';

In this way we sort of namespaced our actions and we always know which action from what type are we using.

Effects

Implement toPayload method

This was actually a part of NgRx but was removed in newer versions. Since most of our actions have a payload property and usually in the transformations that are needed we care only about this, we can create a helper method that will map the action object to the payload:

const toPayload = <T>(action: { payload: T }) => action.payload;

Then we can use it in our effects:

@Effect()
public errors$: Observable<Action> = this.actions$
    .pipe(
        ofType(LOG_ERROR),
        map(toPayload),
        ...
     )

After the map we can use the payload data without having to refer to it as action.payload.foo each time we want something from there.

As a cleaner alternative we can use destructuring to fetch the payload property:

@Effect()
  public errors$: Observable<Action> = this.actions$
    .pipe(
        ofType(LOG_ERROR),
        tap(({ payload }) => console.log(payload)),
        ...
     )

Not all effects have to emit something

Usually we create an effect to catch a specific action, do some processing and then emit one or more different actions. But we don’t have to do this all the time.

We can specify that we don’t want to do this and just do some side effect whenever a certain action takes place:

@Effect({ dispatch: false })
userLogout$ = this.actions$.pipe(
   ofType<userActions.Logout>(userActions.LOGOUT),
   tap(action => console.log('User is logging out', action))
)

As you can see above this is handled by setting the dispatch property to false.

Load data with effects

The purpose of an NgRx effect is to handle any side effects that we have in our application and one of this type of side effect is making AJAX calls to load data from an API. This is done by most developers using this library but I’m adding it here for completion.

So instead of loading data directly we do this with an effect. Assuming the user has a button that can be pressed to load some documents, when this happens we simply trigger an action to notify that we want to do this: documentActions.Fetch.

Inside an effect we catch this action, make the request and map the outcome to a success action:

loadDocuments$ = this.actions$.pipe(
   ofType<documentActions.Fetch>(documentActions.FETCH)
   switchMap(() =>
       this.documentsService
           .getDocuments().pipe(
              map(docs => new documentActions.FetchSuccess(docs))
            )
    )
)

And then we have a reducer that listens for this FetchSuccess action and puts the new documents in the state.

In this way all the requests are isolated from our application and we have a central place to do each of them. We might have multiple places from which we can trigger a documents fetch and all we have to do is send the fetch action.

Always handle errors

The actions stream is an Observable, this means that once an error occurs it’s done, that’s it, no more events will occur and we really don’t want this since it will block our application.

So we always need to make sure we handle things. This means making requests on a different stream that we then merge with operators like switchMap and always handle errors there.

So a more complete example of fetching the documents would be:

loadDocuments$ = this.actions$.pipe(
   ofType<documentActions.Fetch>(documentActions.FETCH)
   switchMap(() =>
       this.documentsService
         .getDocuments().pipe(
            map(docs => new documentActions.FetchSuccess(docs)),
            catchError(err => of(new documentActions.FetchFailed()))
          )
    )
)

The actions stream is the main one that all our actions are emitted onto, so when we want to make a request to load the document, that might fail, we do it inside a switchMap operator where we catch the error and return a different action.

Effects are services

This is an easy thing to forget, but Effect are services in Angular world and we might use Dependency Injection to get instances of other services in them.

For this to work we need to add the Injectable decorator to the class.

Reducers

Keep them simple

Here I have only one tip, keep reducers as simple as possible. They should be clean and don’t have any logic inside. A reducer should only take the data from the action and update the corresponding part in the state with it, it should not make any decisions or any kind of logic that will be hidden there.

The official sample app exemplifies this in a good way, this is how a reducer should look:

	export function reducer(state = initialState, action: AuthActionsUnion): State {
	switch (action.type) {
	case AuthActionTypes.LoginSuccess: {
	return {
	...state,
	loggedIn: true,
	user: action.payload.user,
	};
	}

	case AuthActionTypes.Logout: {
	return initialState;
	}

	default: {
	return state;
	}
	}
	}

view raw reducer-example.ts hosted with ❤ by GitHub

If you have something that looks more complicated than this there is place to refactor and make it slightly better.

General

Use selectors

On the store class we have the select method, and there also is a pipeable select function. We can use both of them to fetch a part from the state in places where it’s needed.

While you can pass the keys/path to what you want to fetch as a string argument to these functions I recommend using the createSelector function provided by NgRx which, as the name suggests, allows us to create a callback function that knows how to fetch a part of the state.

For example something like:

export const getLoggerErrors =
  createSelector(getLoggerState, (state) => state.errors);

Where getLoggerState is a generic way to get the part of the state responsible for the router:

export const getLoggerState = (state: AppState) => state.logger;

And then whenever we want to select something we use these kind of functions as an argument to select.

This has several benefits:

we can change the way our state looks behind the scenes without actually changing the app code, since the selector will be the same one
we can group together different parts of the state and get what we need
the selectors use a technique called memoization which basically means that once we call one with some arguments it will store that result and whenever we call it again it will return the cached result without executing the function

There is a lot of good info about selectors in the official docs.

Normalize data

We should think of the state like a local, in memory database. One important thing we should not do is duplicate the same information all over the place.

So for example if we have a list of items we can keep it in one place and if we need a list of selected items we just hold a list of ids, those that are selected. Whenever we need them we create a selector that gets the list of items and the selected ids and map them together to get the result.

This is important because we don’t want to update multiple parts in the state when one single action occurs.

Also there should not be that many nested levels of data, as this will get tricky to manage and select when needed. A common approach here is that instead of keeping items in arrays, we keep them in objects and use the id as an identifier. This needs a bit of time to get used to but it pays of in the long run.

If normalizing the state in this way gets too complicated to do by hand there is an awesome library called normalizr that can help a lot with this.

{
  result: "123",
  entities: {
    "articles": {
      "123": {
        id: "123",
        author: "1",
        title: "My awesome blog post",
        comments: [ "324" ]
      }
    },
    "users": {
      "1": { "id": "1", "name": "Paul" },
      "2": { "id": "2", "name": "Nicole" }
    },
    "comments": {
      "324": { id: "324", "commenter": "2" }
    }
  }
}

This is how a normalized state would look if we have a blog post containing articles, users and comments. Have a look at the normalizr documentation for more info.

Another benefit of keeping the state like this is that it will allow us, more easily, to add a caching layer to our application. Only loading data when we don’t have it, or what we have is outdated.

Don’t use the store all over the place

This is more about ‘dumb components’ than anything else. Most of our UI components should be small and dumb, meaning they should not know that there is a state, how we fetch data and so on.

Generally we have containers, meaning a parent component that fetches from the state all the required data and triggers all the required actions and all the small components inside only have a few Inputs and Outputs to handle what they need to display.

Generic error action

When we load data using NgRx Effects we’ll end up having lots of actions that trigger the load, those that mark the load success and those that show when an error occured.

We can make some of them generic, for example the error ones. In my experience we tend to use the other ones in more places and need them explicitly, but if this is not the case you can make those generic as well.

For example this is how a generic error action would look:

	export class ErrorOccurred implements Action {
	readonly type = ERROR_OCCURRED;
	constructor(
	readonly payload: {
	action?: Action;
	error?: ErrorData;
	},
	) {}
	}

view raw generic-error-action.ts hosted with ❤ by GitHub

It has a payload with an action property, this will specify which action triggered the error. For example if an error occurs while we were doing a FETCH_USERS action, this will be used here. We have it as an action with the type property inside for consistency and ease of usage, we could have just as easily have this as string and store the action type only.

The error property is of type ErrorData and will hold more information about what went wrong. You can model this as need, for example I generally use something like:

interface ErrorData {
  type?: string;
  error?: any;
}

Then when we can use this in Effects where we handle the error case:

	loadDocuments$ = this.actions$.pipe(
	ofType<documentActions.Fetch>(documentActions.FETCH)
	switchMap((action) =>
	this.documentsService
	.getDocuments().pipe(
	map(docs => new documentActions.FetchSuccess(docs)),
	catchError(error => of(
	new ErrorOccurred({
	action,
	error,
	})
	))
	)
	)
	)

view raw load-doc-err.ts hosted with ❤ by GitHub

Property initialization

Initialize directly all selector properties when defining them instead of constructor or other places. One can have code like:

	export class DocumentContainer {

	companyName$: Observable<string>;
	documentStatus$: Observable<number>;

	constructor(
	private store: Store<AppStore.AppState>,
	) {
	this.companyName$ = this.store.select(detailsSelector.getDocumentCompanyName);
	this.documentStatus$ = this.store.select(detailsSelector.getDocumentStatus);
	}
	}

view raw prop-initialization-long.ts hosted with ❤ by GitHub

Where we first define the properties and then we initialize them in the constructor. Ideally we can do it in one place while having less code that is also easier to read. This would have the same effect:

	export class DocumentContainer {

	companyName$ = this.store.select(detailsSelector.getDocumentCompanyName);
	documentStatus$ = this.store.select(detailsSelector.getDocumentStatus);

	constructor(private store: Store<AppStore.AppState>) { }
	}

view raw prop-initialization-short.ts hosted with ❤ by GitHub

Hopefully you’ve found some good tips about using NgRx above 😃.

Barrel files: to use or not to use?

Sun, 04 Mar 2018 23:46:37 GMT

First of all, what are these barrel files? Using ES2015 modules, we have files from which we export one or more things. Barrel files are a way to re-export all or some of these from one, single, convenient place.

You can understand better what they are and how they are used by looking at this short example from the aswesome TypeScript deep dive book.

Barrel files are named index, as convention, because most module loaders will look for this by default when resolving absolute paths and this will allow us to omit the filename from the path and just point to a folder. Assuming we have a barrel file in a services folder we’ll import things like:

import { LoggerService, UserService } from 'app/core/services'

We can use this anywhere in our app if we’re using an absolute path when importing, if you want to know more about this you can check my short post 😉

There are people arguing that one does not need to use barrel files, at least inside Angular applications since we have NgModule. Even the official documentation hints towards this.

While we can organize a lot of things with the help of Angular modules, I still prefer to also use a few barrel files throughout the application. They greatly simplify the imports and make them look clearer. We just don’t want to have too many barrel files since that is counter productive and usually leads to circular dependency issues which sometimes can be quite tricky to resolve.

So a bad practice would be to create a barrel file inside each folder we have, this is something I would really not recommend. Tried it once to see how it goes, and let’s just say it did not end well 😃

What I found to work is to have one level of barrel files throughout the application structure. In some rare cases maybe a few more in some subfolders but that is a matter of preference.

A good way to structure the application is to place files into folders based on features, and inside these folders create subfolders based on the type.

In the example above we have a core module, usually found inside Angular applications. Inside we have folders for each Angular specific types along with an Angular module.

Similar structure for a feature module:

Pretty much the same, with some more folders based on types.

If we have this kind of structure we would want our barrel files inside these type folders. So each of them will have an index file where we re-export what is inside those folders. Then when we import we’ll have:

import { DocumentModel, CommentModel } from 'app/+documents/models'

This is short, we can import all the similar things from one place and we see pretty clear what they are. So if we need models from a specific feature we go feature folder name and models folder. If we need services to the same feature folder name and services and so on.

Everything should be clear and easy to find. If it’s not, the structure and/or barrel files are wrong and should be changed.

If you look at an import and you don’t immediately understand what you are importing and from where it’s usually a smell that the structure is not that ok. Similar, if you want to import something and don’t know where to get it from.

You should experiment with the structure and using barrel files until you find something that works, usually this is constantly needed as the application grows and evolves. Never be afraid to change things in order to make them better 😃.

Using the Angular Router to navigate to external links

Wed, 14 Feb 2018 23:46:37 GMT

Navigating to an external url from an Angular application is something quite easy. Using window.location or an anchor tag is straight forward, but it has a big disadvantage, it bypasses the Angular Router.

This means that if we have something like route guards, they will not be called. For example we might have a guard that notifies the user of any unsaved changes and can stop the navigation if the user wishes. If you want to know more about route guards, Thoughtram blog has a nice article about this.

So we need a nice and generic way of navigating to an external url but using the Router so that our guards will get called.

We’re going to do this using a route resolver and a custom route. Resolve is used to fetch any required data before activating the route but we’ll hijack it a bit to navigate where we want.

First, we need to define a new custom route in our routes config:

{
    path: 'externalRedirect',
    resolve: {
        url: externalUrlProvider,
    },
    // We need a component here because we cannot define the route otherwise
    component: NotFoundComponent,
},

We have a new route with the externalRedirect path, you can use here whatever string you want, as long as it’s not used by another route within the application.

As an alternative to resolve we can also use the route guards for the same purpose. For example we hookup to the can activate route guard:

canActivate: [externalUrlProvider]

We have a fictional url property that we’re supposed to provide before activating this route with a value set to *externalUrlProvider, *we’ll have a look at this in a second. And last a component, in this case one for a not found page, but it can really be anything, it’s there only because we cannot declare a route without it.

The value of url, external url provider, is an injection token, we’ll use it in the Providers array to define our functionality:

const externalUrlProvider = new InjectionToken('externalUrlRedirectResolver');

And this is how our routing module might look:

@NgModule({
    providers: [
        {
            provide: externalUrlProvider,
            useValue: (route: ActivatedRouteSnapshot) => {
                const externalUrl = route.paramMap.get('externalUrl');
                window.open(externalUrl, '_self');
            },
        },
    ],
    imports: [
        RouterModule.forRoot(routes),
    ],
    exports: [RouterModule],
})
export class AppRoutingModule {}

We create a function that gets as parameter the activated route, read a route parameter called externalUrl and then use window.open to navigate to the provided link.

Now we also have to use our new route when we want to navigate to an external url. While we can do this using directly the router:

this.router.navigate(['/externalRedirect', { externalUrl: url }]);

We might also want a more generic way. Maybe attach to all the anchor elements that have a href pointing to an external resource.

We can create a directive with a selector ‘a[appExternalUrl]’ which means that it will work on all the anchor elements where we add the directive name as attribute.

Then we’ll read the value of href and use the router to navigate to it. The complete version looks something like this:

import { Directive, HostListener, ElementRef } from '@angular/core';
import { Router } from '@angular/router';
import { isNil } from 'ramda';

@Directive({
    selector: 'a[appExternalUrl]',
})
export class ExternalUrlDirective {
    constructor(private el: ElementRef, private router: Router) {}

    @HostListener('click', ['$event'])
    clicked(event: Event) {
        const url = this.el.nativeElement.href;
        if (isNil(url)) {
            return;
        }

        this.router.navigate(['/externalRedirect', { externalUrl: url }], {
            skipLocationChange: true,
        });

        event.preventDefault();
    }
}

We have a constructor where we get an instance of the element and one for the router.

Then we listen for the click event and read the href property of the element passing it along to the navigate method of the router to actually perform the navigation. We also specify ‘skipLocationChange’ as *true *when navigating since we don’t want the user to actually see our intermediary route, we use it just to trigger any router specific logic we might have in our app like the deactivation guards.

Lastly, since we handled the click ourselves we call the preventDefault method on the event.

We can use our new directive wherever it’s needed:

<a [href]="[https://www.google.com/](https://www.google.com/)"
    appExternalUrl
>Click Me</a>

While this might feel a bit like a hack, it does provide a good and generic way of navigating to external resources while also involving the Angular Router.

You can find a sample implementation on StackBlitz.

Update on testing NgRx Effects

Mon, 04 Dec 2017 23:46:37 GMT

A while ago I’ve written a post on how to test NgRx effects. If you did not read that one I encourage you to go and have a look.

Since then, both NgRx and RxJs have released some new versions and there are some things we need to update in our tests.

Store mock

Up to now we were creating the data for the store mock with one simple line of code:

const initialAppState = reducer(undefined, { type: 'INIT_ACTION' });

We were fetching the root reducer, the result of calling combineReducers on all our reducers, and calling it with an unknown action so we would get the initial state in all the cases.

The 4.x release of NgRx added, among others, the awesome option of placing reducers, effects and actions inside the modules where they were used and lazy load them when needed. So, as with other libraries, we use forRoot method in the app module and forFeature in all the rest.

You can have a look at the migration guide here.

This means that now we have to compose the reducers object from all our feature modules. We have to create a reducers map that looks something like this:

const reducersMap = {

    ...coreReducers,

    items: fromItems.Reducer,

    itemDetails: fromItemDetails.Reducer,

};

Another change is that the forRoot method now takes this map of reducers as an argument, it will call internally combineReducers method. So we need to create the root reducer by calling this ourselves:

const rootReducer = combineReducers(reducersMap, initialState);

The second argument, *initialState, *is an object that we can create in our tests, when a state different than the default is needed.

After we have all this, we can create the state as we did before:

const appState = rootReducer(undefined, { type: 'INIT_ACTION' });

RxJs and lettable operators

From RxJs 5.5 we have lettable operators, which means we import them as standalone functions and need the pipe method in order to use. You can read more about this in the official documentation.

Since they are functions, and no longer patch the Observable prototype when imported, it means we also cannot do this anymore in order to specify a scheduler, so we need to find an alternative.

And this alternative it’s not that easy to find at the moment, there is no easy and clean way to do this without changing the code of the effect class.

Rebinding schedule

By default, RxJs operators use the async scheduler internally, if no other is specified. So a workaround to the problem is to change the behaviour of this scheduler. We can import it in our tests and overwrite the schedule method to that of our test scheduler:

import { async } from 'rxjs/scheduler/async';
import { getTestScheduler } from 'jasmine-marbles';

const testScheduler = getTestScheduler();

async.schedule = (*work*, *delay*, *state*) =>
          testScheduler.schedule(work, delay, state);

By running this in a before block, we’ll make sure that our tests will still pass, and we can get rid of the code where we were patching individual operators.

Passing scheduler in constructor

A similar approach to how the tests are done inside the sample app from NgRx repository is to add a scheduler to the effect constructor. Either mark it with the optional decorator and if we don’t get anything we initialize it to the async scheduler or we can use a default value for it:

export class AppTimeEffect {
     constructor(private *actions$*: Actions,
                 private *scheduler* = async,
      ) { }
}

After we have it here we also need to pass it as argument to all the operators where it’s required, so our effect will become something like:

@Effect()
fetchDataWithDebounce$ = this.actions$
   .ofType(actions.DATA_WITH_DEBOUNCE_FETCH)
   .debounceTime(100, this.scheduler)
   *// Call API service or some other processing
   *.map(() => ({ type: actions.DATA_WITH_DEBOUNCE_FETCH_SUCCESS }));

Once that is done, we can pass the test scheduler when we create an instance of the effect inside the tests:

const scheduler = getTestScheduler();
const effect = new AppTimeEffect(new Actions(source), scheduler);

In this case we edited the effect code so we can test it, but our intent is more clear. On the good side, we still avoided using Angular specific constructs like the TestBed.

If you want to know more about the future of schedulers in RxJs have a look at this thread.

Custom preloading strategy for Angular modules

Thu, 30 Nov 2017 23:46:37 GMT

Lets say we have a medium sized Angular application and each large feature split into a lazy loaded module.

When the application starts, we load only the main modules and all the routes are lazy loaded, including the first one that we navigate to:

	export const routes: Routes = [
	{ path: '', redirectTo: 'items', pathMatch: 'full' },
	{
	path: 'items',
	loadChildren: 'app/+items/items.module#ItemsModule',
	},
	{
	path: 'item',
	loadChildren: 'app/+item-details/item-details.module#ItemDetailsModule',
	},
	{
	path: 'admin',
	loadChildren: 'app/+admin/admin.module#AdminModule',
	},
	];

view raw example_lazy_routes.ts hosted with ❤ by GitHub

So what happens is that the app, core and shared modules are loaded, right away we navigate to a feature page and the coresponding module is loaded. When we go to item details page, since the module is lazy loaded, before we do something we have to wait for it to get loaded.

This is already an awesome setup and thumbs up if you use it 👍

We can improve things a bit by using a preloading strategy that Angular provides for us. When we provide the routes to the router module we have a second argument where we can specify a strategy.

RouterModule.forRoot(routes, { preloadingStrategy: NoPreloading })

Out of the box Angular provides two strategies already implemented for us, pretty explanatory from the name:

NoPreloading — no modules are preloaded, this is the default behaviour
PreloadAllModules — all modules are preloaded as fast as possible

While this will work in some scenarios, we might want to create something a bit more complex here. All we have to do is create a class that implements PreloadingStrategy class.

A good strategy here would be to load quickly just what is required and load some of the other modules with a small delay. We might know that after the initial load most of the users will go to a specific feature module, then after everything is loaded we can preload that feature module where we think users might go, or maybe preload all the other modules if we don’t have that many.

We start by adding a data object to the routes config, so we can leverage this in our custom preloading strategy:

	export const routes: Routes = [
	{ path: '', redirectTo: 'items', pathMatch: 'full' },
	{
	path: 'items',
	loadChildren: 'app/+items/items.module#ItemsModule',
	data: { preload: true, delay: false },
	},
	{
	path: 'item',
	loadChildren: 'app/+item-details/item-details.module#ItemDetailsModule',
	data: { preload: true, delay: true },
	},
	{
	path: 'admin',
	loadChildren: 'app/+admin/admin.module#AdminModule',
	data: { preload: false, delay: true },
	},
	];

view raw example_lazy_routes_data.ts hosted with ❤ by GitHub

Inside the data object I’ve added two properties, both boolean:

preload — if we want to preload that module or not
delay — if we want to load it right away or with a delay

Then we implement the preload method and decide which modules we preload right away and which we load with a small delay:

	export class AppPreloadingStrategy implements PreloadingStrategy {
	preload(route: Route, load: Function): Observable<any> {
	const loadRoute = (delay) => delay
	? timer(150).pipe(flatMap(_ => load()))
	: load();
	return route.data && route.data.preload
	? loadRoute(route.data.delay)
	: of(null);
	}
	}

view raw app_preloading_strategy.ts hosted with ❤ by GitHub

Normally we would just check to see if the route has the preload property set to true and then we would call the load function, if not we would return an observable with null value (this will indicate that we don’t want any preloading):

return route.data && route.data.preload ? load() : of(null);

This can be improved by creating a loadRoute function that takes an argument, the delay property. If delay is false we call the load function right away. If *delay is true *an observable that emits a value after an interval is created, with the timer method, and the result is flat mapped to calling the load method.

The only thing left is to use this new strategy:

RouterModule.forRoot(routes, {
   preloadingStrategy: AppPreloadingStrategy
})

Using this our module is already loaded when we need it and the user has an improved experience.

Use absolute paths for module imports

Sat, 04 Nov 2017 23:46:37 GMT

Handling imports is a bit more trickier to manage due to paths and constant refactoring that one will do inside a more complex application.

When importing modules they are usually separated in two:

importing libraries modules, which is quite nice, since we use only the name and they are resolved from node_modules folder
importing modules from our own application

When doing the second the web is, unfortunately, full of examples that use relative paths to get the needed file:

import { foo } from ‘../bar’;

Which is quite ok, but it goes quickly wrong when the file we need is several levels up or down. Then we get something like:

import { foo } from ‘../../../../bar’;

Which is hard to write/read and will break as soon as we move the file somewere else.

Since TypeScript 2.0, we have an awesome compiler setting called baseUrl, and we can configure it in the tsconfig.json file like:

{
  "compilerOptions": {
    "baseUrl": "./src"
  }
}

If you are using Angular CLI this will be already setup for you. In the tsconfig file for the app it’s set as above.

Once this is done we can use a path starting from that base url, so most of our imports will be transformed to something like:

import { foo } from ‘app/bar’

I would use this for almost all of the imports throughout an application. Those that import from the same folder might be left as they are though.

All our imports will be shorter to write, easy to understand and most important: will not break as we refactor and move files around.

With a few barrel files strategically placed we will have a very nice structure with imports that look like:

import { UserService } from ‘app/core/services’;
import { SearchComponent } from ‘app/shared/components’;

If you want to go a bit further there is also a setting for creating path mappings, but as of now, most editors and IDEs have some issues with correctly resolving this and in my opinion it is a bit harder to understand what is happening.

It should be clear enough why this way of importing modules is a bit better and more error proof. We should all use this more when working on large application codebases.

Angular location service

Tue, 19 Sep 2017 23:46:37 GMT

There is a small and well hidden service inside Angular: the location service. As the name and documentation suggests, this is a class that is used to interact with the browser URL.

I’ve seen people using this, probably by mistake, trying to navigate inside an application, this is not working because it’s not related to the router at all. We can use it to update/change the browser address, basically interacting with the URL outside of routing.

Use case

A nice place that I’ve found for this to use is to update the current location after we finish an operation that would normally change it, but we don’t want to involve the router (for example, to avoid any side effects and navigation triggers generated by a reload of the page).

Lets say we have a route that goes to an item details, something like: ‘item/{itemId}’ and a very similar one that is used to create a new item: ‘item/new’.

When we create a new item we navigate to the last one and the browser address is set to item/new. After we add all the details when we send this to the API we get back the saved entity from the database, including the item id.

Since the item was saved, we’re no longer in the new state, we’re in edit mode and we want to show this in the URL by changing new with ***id **value*.

We could reload the page, but this will most probably fetch again the item from the API. And this in the most simple scenario, in more complex ones we can have multiple effects that are triggered when the page is loaded and we want to avoid all that extra stuff.

Solution

Here comes to the rescue the location service. We can use the **go** method to update the address and to add it to the history, making sure that if we go to a different route and hit back button, we’ll end up with the item id in the address bar and not with new.

Using the method is as simple as calling it with a string argument representing the new address:

Code

A sample, and very small, application that shows this can be found on StackBlitz. If you want to edit the sample you can use this link.

What other use cases did you find for the Location service ?

Testing NgRx effects

Wed, 30 Aug 2017 23:46:37 GMT

Update: Since I’ve wrote this, both NgRx and RxJs released some new versions that require some small changes in how we can write the tests. You can see all those in this follow up.

If you decide to use a state management library in your Angular application (and for most of them you should :) ) a good choice is one of the Redux inspired libraries. You’ll most likely have actions, reducers and pretty soon something to handle all the side effects. In case of ngrx, these side effects are handled with the help of the ngrx/effects module.

This post will show an approach on how to test ngrx effects and show some samples. It will not go into state management and why to use this library for managing side effects.

An Effect is a stream that filters the actions object (all the actions going through the application) and filters them based on the action type we want to react to. An action is handled by a reducer function which updates the application state. In cases where we want to have some side effects (eg. xhr call) as a result of that action, we do it in an Effect.

Testing reducers is pretty straight forward since they are pure functions and should not be that complex. The interesting part comes when we want to test the effects that we’ve built.

There is some documentation and some samples on how to test them, but the samples don’t have that much information provided and they are using the TestBed provided by Angular. I liked better the approach that Victor Savkin took in his repo on how to test effects. We instantiate everything ourselves, there is no TestBed, no subscribe calls and generally the tests look and feel more clean.

As a bonus this approach works with both old (2.x) and new (4.x) version of ngrx so you can easily have the tests up and running and then migrate with confidence, and without having to rewrite the tests afterwards.

I’ve added some samples, including a bit more complex scenarios that I’ve encountered while writing tests for effects, and tried to explain each of them.

We use jasmine-marbles for easier testing and a better visualisation of Observables. While it’s not wildly popular, it’s being used trough several open source projects (including ngrx itself) and quite a few presentations. The code base is quite small so you could look at it and implement it yourself if needed.

Assuming we have the most simple effect possible that just listens for an action, might do some processing, and triggers another action as a result. The most basic approach would look something like:

We listen to the increment action, perform any processing we might want to and generate a new action.

Inside a test we would want to trigger the increment action and make sure we always get back the update text resulting action:

Using jasmine-marbles library we can create observables using marble diagrams which generally helps a lot when reading the tests. So if we have an observable that emits two values we can describe it as: ‘ -a-b-|’.

When using marble diagrams we represent them as a string using:

- to represent passing of time (10 frames)
| to mark the completion event
to emit an error
most other characters to represent an emitted value

The library has two useful methods hot/cold that allow us to create an observable from a string representation. If you want to read about the difference between a cold and a hot observable, Ben Lesh has a great article about this.

When we create an observable using hot/cold method, the second parameter that we can pass to the method is an object that maps values for each emitted item. In our case we only pass the action object that we want to handle:

Another nice thing that jasmine-marbles adds is the toBeObservable matcher so we can directly compare our input with the expected result:

This is the basic setup for testing a simple effect that we might use.

We can move on to our second testing scenario where we use a service in the effect and we want to mock it:

Similar to our first example just that in this case we’re using a service to fetch some data. We get this service through dependency injection so we’ll need to mock it in our test to make sure we don’t hit an API or some other costly operation.

An important thing we should notice is that we don’t want to throw an exception directly on an effect stream, remember this is the main actions stream and an Observable is done after an error occured, so if we do that, no more actions will flow through the application. This is why we use the switchMap/catch combination and we make sure we create a test that checks this case.

We create a mock for our service using *createSpyObject *method from jasmine and we handle both cases where we want to return a value or an error:

If we pass in a value, we return an observable that will emit that value and if we pass in an error object, we return an observable that will throw that error.

Having this in place we can create our first test to check that we can retrieve data:

This looks pretty much as our first simple test, we instantiate a new service instance with our mock method and pass it in the effect constructor. Checking the expected value is pretty much as before. For simplicity we’re checking just the action type, but in a more real world application we would also check that the payload from the action contains the data that we want.

As mentioned above, we need to make sure we handle an exception on the stream, so we also test that our catch method works as it should:

In this case we create our service and pass an error so when we call *getDummyData *it will emit the error and it should be caught and transformed in a data fetch failed action.

Another type of effect that we can have is where we might need some other data from our application state in order to process the action or to generate a new one. This would be simple if the data would be in the same part, handled by the same reducer, but imagine that we have a more complex state object and we need to fetch something from different places. An option is to inject the store in the effect class and select what we need:

Notice that we’re creating two streams *numberStream *and *textStream *that read some data from the state and then use these values in the effect, in the *withLatestFrom *operator.

In order to test this effect we need to mock the store and make sure we select whatever data we want from it. If we would have only one stream we could have easily mocked the store and return whatever we want:

But if we have multiple streams for which we use different selector it will be more tricky. One nice way to handle this is to actually initialize the state with the default value by calling the root reducer with an unknown ‘INIT’ action. Then we can call the selector on the state object and return the result in a stream:

The whole test looks like this:

The last type of test that I’ve encountered is that where we need to control time :) If we use different kind of operators like timer, *interval *or debounceTime on our effects we need some special handling in our tests.

Suppose we have an effect that looks like this:

We can see that we use debounceTime operator to emit only the last value from a period of time and ignore the rest. Since we do this our normal way to test this will not work, since when we check the expected value the initial one will not have emitted anything.

One dirty way to hack around this is to spy on the operator and make it do nothing:

Basically we just return the stream itself without anything applied to it, and then we can write the test as we would normally do, just make sure to spy on the observable operator before we create the effect:

A second approach is to use the Scheduler that is provided by the jasmine marbles library. If you look in the ngrx repository at the sample app you can see that an optional injected scheduler is used inside the effects class. If it’s provided it’s used, if not, the default one from rxjs is used.

While this approach works just fine, it makes you add some code in all the effect classes that is not used for anything else beside testing. Another thing is that you’ll have to instantiate the effect using the TestBed provided by Angular to make sure that everything is in place.

A different approach, using the same scheduler that you can fetch using *getTestScheduler *method, is to override all the required Observable operators to use it:

A similar approach to what we used in the first try, here we just save the original operator and call it with our scheduler.

This will make sure our test passes again, as long as we spy on the operator before we instantiate the effect class:

So far these have been the most common scenarios that I’ve encountered while writing tests for ngrx effects.

You can find the complete working code on GitHub. Have fun writing tests ;)

Creating a Mobile App for a Smart Light Bulb with NativeScript & Angular

Thu, 06 Oct 2016 23:46:37 GMT

Since one of the awesome things I got from AngularConnect was a Magic Blue smart light bulb and NativeScript looks like an interesting framework, I’ve decided to create a small mobile app to interact with it.

NativeScript is an open source framework for building native mobile applications, using web technologies, and it works with the latest version of Angular.

I’ll go through setting up the environment, creating a new template application, a basic component and interacting with the light bulb.

Environment

First you need to setup everything, before we actually get to write any code. You start with Node.js, which if you don’t have already you can go to nodejs.org and grab it.

Second you need to install the NativeScript CLI:

npm install -g nativescript

Since it will build native Android or iOS apps you also need to setup the platform for each of them, things like Android SDK, Xcode, etc. I suggest you manually set them up, or you can go to the quick setup part in the NativeScript docs which have some ready made scripts that should do everything.

Finally you can check that everything works using the NativeScript CLI doctor:

tns doctor

If you run into trouble or want more information about the setup, the official docs are quite helpful.

New application

Creating a new application is easy enough, with the help of NativeScript CLI. Create a new application template with:

tns create NativeScriptLightBulb --ng

The first parameter is the application name, and with the second one you’re specifying that we want to use Angular. You can also create applications without Angular, and they will use JavaScript/TypeScript only with the provided SDK.

Second you need to add a new platform to the application, iOS or Android:

tns platform add ios

tns platform add android

At this point you can build and start the application in the emulator or on a real connected device:

tns run android --emulator

Or, if you want to have a live sync kind of flow:

tns livesync android --emulator --watch

This will watch all the files in the solution, build and redeploy the application on each change. Similar to modern web development workflows.

Creating the first component

You can start by creating a simple Angular component, with the accompanying template and style files. For a better project structure add all of them into a components/bulb-control folder.

The project structure should look similar to this:

Then create a class and add the component decorator:

	import { Component } from '@angular/core';

	@Component({
	moduleId: module.id,
	selector: 'ns-bulb-control',
	templateUrl: 'bulb-control.component.html',
	styleUrls: ['bulb-control.component.css']
	})
	export class BulbControlComponent {
	maxValue = 255;
	minValue = 0;

	redValue = 128;
	greenValue = 0;
	blueValue = 0;
	whiteValue = 0;

	updateLightBulb() {
	console.log('Update color');
	}

	connectToMagicBlue() {
	console.log('Connecting to device');
	}
	}

view raw bulb-control.component.ts hosted with ❤ by GitHub

Beside the boilerplate code, there is one method that will eventually update the light bulb color, a method to connect to the light bulb, a set of properties that will be used to bind the color model (red, green, blue, warm white) and some minimum and maximum values for a color. I’ll create the template for this model shortly.

NativeScript uses Angular, but it doesn’t work with a browser, so you won’t be able to use elements like *div *or *h1. *Instead NativeScript provides us a custom made collection of elements that one can use, and each of these elements will be translated into a native Android or iOS UI component.

Adding some basic controls for a simple UI, that can be used to control the color of the light bulb, is all that’s needed.

	<StackLayout>
	<Label text="Magic Blue"></Label>
	<Button (tap)="connectToMagicBlue()"
	text="Connect">
	</Button>
	<Slider [minValue]="minValue"
	[maxValue]="maxValue"
	[(ngModel)]="redValue">
	</Slider>
	<Slider [minValue]="minValue"
	[maxValue]="maxValue"
	[(ngModel)]="greenValue">
	</Slider>
	<Slider [minValue]="minValue"
	[maxValue]="maxValue"
	[(ngModel)]="blueValue">
	</Slider>
	<Slider [minValue]="minValue"
	[maxValue]="maxValue"
	[(ngModel)]="whiteValue">
	</Slider>
	<Button (tap)="updateLightBulb()"
	text="Apply">
	</Button>
	<StackLayout>

view raw bulb-control.component.html hosted with ❤ by GitHub

First you specify the stack layout, and then added two buttons, one for each of our actions, four sliders for the color model and a title so you know what the application does :)

The Angular binding syntax work here also, so you can add event handlers with *(tap)=”updateLightBulb()”, *bind to element properties with *[minValue]=”minValue” *and use two way binding with [(ngModel)]=”blueValue”. Angular documentation offers more insights about this if needed.

With some basic styling (can be grabbed from GitHub) the application should look like this:

Interacting with the light bulb

Even though NativeScript offers the option to access all native APIs directly from TypeScript, which is pretty neat, I’ll use a ready made plugin that will interact with bluetooth connectivity.

NativeScript-Bluetooth can be found on GitHub and you can add it to the project using the CLI:

tns plugin add nativescript-bluetooth

Next, you can move on, to create some services to help interact with the bluetooth plugin. You can create one as a wrapper for the bluetooth plugin and one to hold the logic related to the light bulb.

A class to hold a bluetooth device properties might come in handy also.

	export class BleDevice {
	constructor(public UUID: string,
	public name: string,
	public state: string) { }
	}

view raw ble-device.model.ts hosted with ❤ by GitHub

First thing that you need to do is handle the application permissions. For Android this means that inside the AndroidManifest.xml file you’ll add these extra three permissions:

<uses-permission android:name=”android.permission.BLUETOOTH”/>
<uses-permission android:name=”android.permission.BLUETOOTH_ADMIN”/><uses-permission android:name=”android.permission.ACCESS_COARSE_LOCATION”/>

The first two will allow to discover and connect to bluetooth devices, and the last one is needed to access the device location. This is needed for devices running Android 6, where you need the location permission in order to scan for nearby BLE enabled devices.

Moreover, even if they are added, you need an extra step to request for permission at run time in order to be able to scan for devices. You can do this with *requestCoarseLocationPermission *method from the bluetooth plugin:

	fixPermission(): void {
	bluetooth.hasCoarseLocationPermission()
	.then((granted) => {
	if (!granted) {
	bluetooth.requestCoarseLocationPermission()
	.then(() => console.log("Location permission requested"));
	}
	});
	}

view raw fix-permission.ts hosted with ❤ by GitHub

You can call this method when the application initialises, to be sure we have the permission from that point on. For example in the OnInit hook of our light bulb component.

Other methods like write, *connect *or *disconnect *from the bluetooth service are just wrappers around the ones from the bluetooth plugin so I could add callbacks with some log messages. You could have, just as easily, used directly methods from the plugin. As a bonus you get an abstraction, the application does not know directly of this plugin, and you could switch it with something else, or with my own implementation by changing only this service.

The last interesting method here is *scan, *where you try to fetch all the devices available and store them:

	scan(): Promise<any> {
	return bluetooth.startScanning({
	serviceUUIDs: [],
	seconds: 3,
	onDiscovered: (device) => {
	const bleDevice = new BleDevice(device.UUID, device.name, device.state);
	this.bleDevicesAround.push(bleDevice);
	}
	});
	}

view raw scan-devices.ts hosted with ❤ by GitHub

You’ll use the devices list further on when you’ll try to figure out which one is a smart light bulb.

Hooking up the UI and the light bulb

Use the light bulb command service to interact with the device from the UI components. There will be two essential methods in here, one to figure out which of the devices is magic blue and one to write a message to the light bulb in order to change its color.

A naive approach for detecting the device and just fetch the fist one that has ‘LEDBLE’ in its name works great. After that you need to connect to it, so it will be ready for receiving messages:

	getMagicBlue(): BleDevice {
	return this.bluetoothService.bleDevicesAround
	.filter(d => d.name && d.name.indexOf('LEDBLE') > -1)[0];
	}

	connectToMagicBlue() {
	this.bluetoothService.scan().then(() => {
	this.magicBlue = this.getMagicBlue();
	if (this.magicBlue) {
	this.bluetoothService.connect(this.magicBlue.UUID)
	.then((device) => console.log('Connected: ' + JSON.stringify(device)));
	}
	});
	}

view raw connect-magic-blue.ts hosted with ❤ by GitHub

The second important part here is actually sending a message to the device. Nothing to complicated here, you need to create a message with the correct structure and add data with the correct encoding. Had quite a lot of fun trying to figure out what the light bulb expects but managed to figure it out in the end:

	update(red: number, green: number, blue: number, white: number) {
	const color = [86, red, green, blue, white, 240, 170].map(param => {
	return this.convertToHexString(param);
	}).join(",");

	const updateMessage = this.getMessage(this.magicBlue.UUID, color);
	this.bluetoothService.write(updateMessage);
	}

	getMessage(UUID: string, value: string): any {
	return {
	peripheralUUID: UUID,
	serviceUUID: 'ffe5',
	characteristicUUID: 'ffe9',
	value: value
	};
	}

view raw send-message-to-magic.ts hosted with ❤ by GitHub

The message structure is composed from the device identifier and value to be written along with the service and characteristic ids of the device. This is device specific and is retrieved in the *connect method. *Each device can have multiple services with multiple characteristics. Each of them has a set of properties, and if write is specified as true, it means you can write values to it.

The data that you need to write to the light bulb is formed from the RGB colors, along with some (in this case) hard coded values that control other properties of the light bulb. The bluetooth plugin expects data in hexadecimal so we map all elements of the array to that and join them.

Having this done, you can go back to the component and wire up the connect and update methods in there:

	connectToMagicBlue() {
	this.lightBulbCommandService.connectToMagicBlue();
	}

	updateLightBulb() {
	this.lightBulbCommandService.update(this.redValue,
	this.greenValue,
	this.blueValue,
	this.whiteValue);
	}

view raw light-bulb-component-updated.ts hosted with ❤ by GitHub

And voilà, you’re controlling the light color :)

Source code

The complete source code can be found in this GitHub repository. It contains a full working solution and some small updates beside what was described above. Have fun coding!

Adrian Faciu's Blog RSS Feed

Exploring template literal types in TypeScript

The problem

Return type

One property

Template literal and recursive conditional types

Template literal types

Conditional types

Recursive conditional types

Multiple properties

Complex (nested) objects

Conclusion

Handling Observables in a LitElement component

Intro

Problem

Options

Base class

Type safety

Unsubscribe

Extra features for our base class

Decorator

The end

Typed fake REST APIs

Setup

JSON Server

Built-in features

Custom routes

Typed data

Fake data

Paths issue

Read-only data

End

Custom Angular directives

Intro

Overview

Selectors

Export

Custom attribute directive

Custom structural directive

Combining both types

Conclusion

Creating a toast service with Angular CDK

Setup

Toast component

Toast service

Multiple toast messages

Dynamic content

Animations

Global configuration

NgRx: tips & tricks

Actions

Use classes for all actions

Always name the property of the action payload

Keep all related actions in the same file

Group actions in a union type

Use short names for constants and classes

Effects

Implement toPayload method

Not all effects have to emit something

Load data with effects

Always handle errors

Effects are services

Reducers

Keep them simple

General

Use selectors

Normalize data

Don’t use the store all over the place

Generic error action

Property initialization

Barrel files: to use or not to use?

Using the Angular Router to navigate to external links

Update on testing NgRx Effects

Store mock

RxJs and lettable operators

Rebinding schedule

Passing scheduler in constructor

Custom preloading strategy for Angular modules

Use absolute paths for module imports

Angular location service