tnc Blog

Using root-provided Injectables in non-DI places

Sun, 03 May 2020 00:00:00 GMT

Hi guys, welcome back to my blog 👋. Today, I want to share with you all about a trick that I’ve been using to access providedIn: 'root' Injectables in places where Dependency Injection (DI) does not make sense in an Angular application.

Non-DI Places

What do I mean by non-DI places? In an Angular application, there are many different building blocks like: Component, Directives, Services, and Modules etc. These building blocks are managed by Angular itself and can be accessed by a built-in Inversion of Control (IoC) container aka Dependency Injection. Beside those, there are different places that are not managed by Angular’s IoC. Namely, there are Custom Reactive Form Validators and Custom RxJS Operators

and more, but I’ll only touch on validators and operators.

Why? Validators and Operators are usually pure functions or static functions because they will be invoked by Reactive Form and RxJS respectively. Because of that, we do not want to write these custom validators and operators with dependence to an instance, aka this. However without this, DI becomes tricky because you cannot use the common DI pattern anymore, or DI via constructor.

export class SomeService {
  constructor(private readonly otherService: OtherService) {}

  static someStaticFn() {
    // you can't access this.otherService in here
  }
}

providedIn: ‘root’

As some of you might have known, providedIn: 'root' is an extra option that you can pass in @Injectable decorator to let Angular knows that you want to provide this Injectable in the root injector. Using providedIn: 'root' will allow you to have lazy-loaded singleton services.

Use-case

Imagine you have a LogService that will handle API errors and log the errors to a 3rd-party logging service, like ApplicationInsight. Let’s take a look at the following pseudo-code

@Injectable({ providedIn: "root" })
export class LogService {
  constructor(private readonly appInsight: ApplicationInsight) {}

  log(error: any) {
    this.appInsight.trackError(error);
  }
}

To use LogService:

// somewhere in the codebase
this.httpClient.get(someUrl).pipe(
  catchError((err) => {
    console.log(err);
    this.logService.log(err);
    return throwError(err);
  })
);

The above works perfectly fine. But, you do not have ONE API call in the whole application. It is going to get very verbose to apply that catchError() to every single API calls.

Then you remember you can create Custom Operator to encapsulate reusable logic. You go ahead and start putting together the following operator:

export function logAndRethrowError<TInput = any>(): MonoTypeOperatorFunction<
  TInput
> {
  return catchError((err) => {
    console.log(err);
    // this.logService.log(err);
    return throwError(err);
  });
}

Now you realize that you need a LogService instance, you start refactoring the operator as follow:

@Injectable({ providedIn: 'root' })
export class OperatorUtil {
    constructor(private readonly logService: LogService) {}

    logAndRethrowError<TInput = any>()L MonoTypeOperatorFunction<TInput> {
        return catchError(err => {
            console.log(err);
            this.logService.log(err);
            return throwError(err);
        });
    }
}

Everything looks good now and you can start using your custom operator:

this.httpClient.get(someUrl).pipe(this.operatorUtil.logAndRethrowError());

Of course, you would need to inject OperatorUtil in wherever you’re calling this.httpClient.get(...)

The above approach works fine but there are a couple of things:

You would not want every new custom operators now need to be in OperatorUtil as instance methods
You would not like that You need to start injecting OperatorUtil everywhere you want to use those custom operators
You would want to stick with Pure Functions for custom operators.

Solution

As you can see, without custom operators being instance methods, there is no way you can access the this.logService inside of your custom operators. Is there a solution? Yes, there is.

This solution applies to Custom Validators as Custom Operators. And this solution only works with providedIn: 'root' injectables.

The solution is to create a class called RootInjector (in fact, you can call it whatever you want) with some static properties and methods to keep track of the root Injector that gets all the providedIn: 'root' providers.

export class RootInjector {
  private static rootInjector: Injector;
  private static readonly $injectorReady = new BehaviorSubject(false);
  readonly injectorReady$ = this.$injectorReady.asObservable();

  static setInjector(injector: Injector) {
    if (this.rootInjector) {
      return;
    }

    this.rootInjector = injector;
    this.$injectorReady.next(true);
  }

  static get<T>(
    token: Type<T> | InjectionToken<T>,
    notFoundValue?: T,
    flags?: InjectFlags
  ): T {
    try {
      return this.rootInjector.get(token, notFoundValue, flags);
    } catch (e) {
      console.error(
        `Error getting ${token} from RootInjector. This is likely due to RootInjector is undefined. Please check RootInjector.rootInjector value.`
      );
      return null;
    }
  }
}

The above is RootInjector implementation. Now the question is “where to use it?” The answer is “main.ts”. In main.ts (or your entry file), you’ll always call bootstrapModule() to start bootstraping your Angular application. bootstrapModule() returns a Promise with the ModuleRef as the resolved value. And there is a property called injector on the ModuleRef that is exactly the root injector that we’re interested in. To be more accurate, the injector on ModuleRef is whatever module’s injector we use to bootstrap. In most cases, it is AppModule. So you can guarantee that the Injectables which are provided in this injector will be singletons throughout your application.

platformBrowserDynamic.bootstrapModule(AppModule).then((ngModuleRef) => {
  RootInjector.setInjector(ngModuleRef.injector);
});

Now back to our logAndRethrowError() operator, we can leverage RootInjector to get the LogService singleton (since LogService is providedIn: 'root')

export function logAndRethrowError<TInput = any>(
  beforeRethrow?: (err?: any) => void
): MonoTypeOperatorFunction<TInput> {
  const logService = RootInjector.get(LogService);
  return catchError((err) => {
    console.log(err);
    logService.log(err);
    beforeRethrow?.(err);
    return throwError(err);
  });
}

I added a beforeRethrow callback in case you want to execute additional logic before rethrow happens.

Then, we can change our httpClient.get() implementation a little bit to use logAndRethrowError()

this.httpClient.get(someUrl).pipe(logAndRethrowError());

// with callback
this.httpClient.get(someUrl).pipe(
  logAndRethrowError((err) => {
    this.toastService.error(err);
  })
);

Summary

RootInjector is a nice and elegant way of keeping track of the root injector so that you can access the Injectables anywhere throughout your application. Although, there are gotchas. RootInjector depends on the actual bootstrap process of AppModule and if you try to access RootInjector before AppModule has been bootstrapped, exceptions will be thrown. What are such occasions? APP_INITIALIZER and Guards/Resolvers/ErrorHandler that might halt the bootstrap process.

RootInjector.injectorReady$ is a workaround for some cases where you want to use RootInjector in AppComponent to initialize some data.

Hopefully, you learn something new today. Thanks for reading and I’ll see you soon 🤞

What's new in AutoMapper v6?

Fri, 20 Mar 2020 00:00:00 GMT

Hi everyone, long time no see 👋. Today, I am very excited to talk to you guys about AutoMapper (@nartc/automapper) version 6. This is a release with an almost complete rewritten core and some small changes to the public API, for the better.

If you do not know about AutoMapper, you can find out more about it via this blog post Introduction to AutoMapper TypeScript or Github

Update 03/24/2020

I have updated the benchmark code and have ran all benchmarks 100 times instead of 10 times. You can check out the benchmark repo here

What’s new?

This v6 release does not contain many changes regarding the public API but performance, bundle-size, critical bug fixes, and a stab at JavaScript support were the main targets of this release. Let’s explore 💪

Performance

For libraries that deal with transforming data like AutoMapper, performance is not to take lightly. However before we dive into the performance of AutoMapper, I want to emphasize the initial purpose of me creating this library which is to transform Domain Model (database) to View Model (client/frontend) via API calls. This is to point out that the number of items going back and forth Network Calls should not be too many like hundreds of thousands or millions of objects going through a single network call. With that in mind, mapping such big amount of objects at once is not realistic in my opinion. Although, I would love for AutoMapper to have better performance than not. Let’s take a look at some simple statistics, shall we?

First, let’s look at the models I am going to use for this benchmark:

class Bio {
  job: string;
  age: number;
  birthday: Date;
}

class User {
  firstName: string;
  lastName: string;
  bio: Bio;
}

and the correspond view models UserVm:

class BioVm {
  job: string;
  isAdult: boolean;
  birthday: string;
}

class UserVm {
  first: string;
  last: string;
  full: string;
  bio: BioVm;
}

along with the following configuration:

Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    mapFrom((s) => s.firstName + " " + s.lastName)
  );
Mapper.createMap(Bio, BioVm)
  .forMember(
    (d) => d.isAdult,
    mapFrom((s) => s.age > 18)
  )
  .forMember(
    (d) => d.birthday,
    mapFrom((s) => s.birthday.toDateString())
  );

Executing map from User to UserVm with the above configuration for 1K, 10K, and 100K items yields the following result:

	1K items	10K items	100K items
`@nartc/automapper` v5	~9ms	~88ms	~959ms
`@nartc/automapper` v6	~8ms	~81ms	~785ms

Each benchmark was ran ~10~ 100 times for each category 1K, 10K, and 100K then the average was taken

As you can see, AutoMapper v6 is slightly faster than v5, about 10-25% faster. And what really changed in v6? AutoMapper v6 does have some optimizations applied to it, as follow:

Loops Optimization: v6 uses while loops that for let (the original for loop with index variable) was used in important places like: map and initializing mapping properties. In areas where for let is still used, v6 has the property length cached to avoid additional property lookup for every iterations.
Accessing Array Index: v6 moves a large part of the core’s data structures from Object to Array to also avoid property lookup. About this technique, there are still areas in the code base where this can be applied further.

You can learn more about Accessing Array Index from the talk How we make Angular fast by Misko Hevery

With the permission from Yann Renaudin, morphism author, I would like to share morphism benchmark with the same mapping configuration as above:

const morphismSchema = {
  first: "firstName",
  last: "lastName",
  full: ({ firstName, lastName }) => firstName + " " + lastName,
  bio: {
    job: "bio.job",
    isAdult: ({ bio }) => bio.age > 18,
    birthday: ({ bio }) => bio.birthday.toDateString(),
  },
};

Each benchmark was ran ~10~ 100 times for each category 1K, 10K, and 100K then the average was taken

	1K items	10K items	100K items
`morphism`	~15ms	~144ms	~1436ms
`morphism` with `create-mapper`	~15ms	~145ms	~1464ms
`@nartc/automapper` v6	~8ms	~81ms	~785ms

This is just a simple comparison solely on the mapping part of the two libraries. Utility wise, morphism is a fantastic library that supports mapping with schema configuration and this suits perfectly with Vanilla JavaScript projects, which do not have classes to model the data in the projects. You can also store the schema configuration elsewhere (database, CDN) and reuse the schema configuration without having the schema inside of your source code. If you find morphism interesting, please check it out at Github. Thank you Yann for allowing me to take morphism to do a simple benchmark for AutoMapper.

Small Bundle

Overall, the bundle-size of v6 is sightly smaller than v5. All of the utility functions and some of the core parts were cleaned up pretty heavily. AutoMapper v5 bundle-size AutoMapper v6 bundle-size

Bundle-size is provided by Bundlephobia

On other note, let’s take another look at the above mapping configuration with the difference between v5 and v6:

// v5
Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    (opts) => opts.mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    (opts) => opts.mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    (opts) => opts.mapFrom((s) => s.firstName + " " + s.lastName)
  );

// v6
Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    mapFrom((s) => s.firstName + " " + s.lastName)
  );

Did you spot the difference? In v6, the second parameter of forMember() is no longer ForMemberOptions. ForMemberOptions is an interface that contains all mapping operations like: mapFrom(), mapWith(), ignore(), condition(), fromValue(), and some others. In v6, these mapping operations are separated into their own Pure Functions. This allows for tree-shaking tools to do their job.

tree-shaking is a step during Build/Bundle. It means to eliminating dead-code (unused code). Dead code, like Functions that are declared but are not used, will be removed from the final bundle which results in a much smaller bundle-size. Only pay for what you use kind of thing.

Critical Bug

In the previous versions of AutoMapper, all of the Mappings and Profiles were stored in a form of Object (or Dictionary) with their prototype.name as key. And whatever comes will come, these Object uses prototype.name as their keys so when a consumer uses the library in Production environment, plugins like Uglify or Terser will minify the source code, resulting in these Mapping and Profile class name are also “uglified” which ultimately leads to duplicate keys forcing AutoMapper to throw exceptions left and right.

v6 changes how it stores these classes with the use of some Singleton Storages. These singletons use WeakMap to store the classes themselves as key instead of using prototype.name. This guarantees the uniqueness of the keys even after the minification process.

// To demonstrate my point about prototype.name
class Foo {}

console.log(Foo.name); // logs Foo
console.log(Foo.prototype.constructor.name); // logs Foo

JavaScript Support

Before v6, support for JavaScript is essentially non-existent. AutoMapper has been working only with TypeScript projects. From v6, this will change as AutoMapper will provide a new API to work with JavaScript. Before introducing this API, I would like to skim through how AutoMapper works so you guys can understand how it has only been supporting TypeScript

AutoMapper works on the concept of Metadata (data about data) of the Models. For example, the above User model has the following information: firstName is a string, lastName is a string, and bio is a Bio. These are so-called Metadata. To get a hold of these information at runtime, AutoMapper uses a decorator @AutoMap(). Afterwards, MetadataStorage will step in and store these metadata, that @AutoMap() provides, for each unique Model. In Vanilla JavaScript projects, it is quite complicated to setup your project to use decorators, and AutoMapper itself did not have any API to support JavaScript.

The API that v6 will provide is: createMapMetadata(). This API will simulate how @AutoMap() works so metadata can be stored. However, this early-versioned API will still require the consumers to provide some amount of boiler-plate code

class User {}
class UserVm {}

class Bio {}
class BioVm {}

JavaScript does not have Type Declaration so fields do not have to be declared. But these empty classes are required to ensure the uniqueness of the Models.

createMapMetadata(Bio, {
  job: String,
  age: Number,
  birthday: Date,
});
createMapMetadata(User, {
  firstName: String,
  lastName: String,
  bio: Bio,
});
createMapMetadata(BioVm, {
  job: String,
  isAdult: Boolean,
  birthday: String,
});
createMapMetadata(UserVm, {
  first: String,
  last: String,
  full: String,
  bio: BioVm,
});

Too boiler-platey right? Well, consumers do not have to provide information for each and every fields like above. Only fields that ARE NOT configured manually by .forMember() are required to be provided. So with the configuration in the beginning of the blog, isAdult and birthday from BioVm do not have to be provided in createMapMetadata. Likewise, first, last, and full do not have to be provided for UserVm.

createMapMetadata(Bio, {
  job: String,
  age: Number,
  birthday: Date,
});
createMapMetadata(User, {
  firstName: String,
  lastName: String,
  bio: Bio,
});

createMapMetadata(BioVm, {
  job: String,
});
createMapMetadata(UserVm, {
  bio: BioVm,
});

The similar is applied for when consumers configure reverse mapping for UserVm -> User (or BioVm -> Bio). Fields that ARE configured manually by .forPath() (if reverseMap() is used) and/or .forMember() are not required to be provided in createMapMetadata.

Can I try?

You can try out AutoMapper v6 by installing the next version of the library

npm i @nartc/automapper@next

Migrate from v5

Like mentioned above, the mapping operations are separate functions in v6. So you configuration needs to be changed:

// before
Mapper.createMap(User, UserVm)
    .forMember(d => d.full, opts => opts.mapFrom(s => s.first + ' ' + s.last)
    .forMember(d => d.foo, opts => opts.ignore());

// after
Mapper.createMap(User, UserVm)
    .forMember(d => d.full, mapFrom(s => s.first + ' ' + s.last)
    .forMember(d => d.foo, ignore())

Mapper.initialize() has been deprecated. Please use Mapper.createMap(), Mapper.addProfile(), and Mapper.withGlobalSettings() directly.
All functions that receive Profile and NamingConvention as arguments are now expecting the Class instead of the instance.

// before
Mapper.createMap(User, UserVm, {
  sourceMemberNamingConvention: new PascalCaseNamingConvention(),
});

// after
Mapper.createMap(User, UserVm, {
  sourceMemberNamingConvention: PascalCaseNamingConvention,
});

You can learn more from the documentation for the next version.

Conclusion

Again, I am very excited to share these changes with you in AutoMapper v6. Same as my previous blog posts about AutoMapper, I hope people will give AutoMapper a try should the library fits their use-cases. Thank you for reading and I will see you in the next one. 👋

Có gì mới với AutoMapper v6?

Fri, 20 Mar 2020 00:00:00 GMT

Xin chào mọi người, đã lâu không gặp 👋. Hôm nay, mình rất phấn khởi khi được giới thiệu về AutoMapper (@nartc/automapper) v6 đến với mọi người. Đây là bản release với phần core gần như được rewrite lại toàn bộ và public API có phần thay đổi chút ít, theo chiều hướng tích cực hơn.

Nếu như các bạn chưa biết về AutoMapper thì có thể tìm hiểu bài blog này của mình Introduction to AutoMapper TypeScript hoặc Github

Cập nhật ngày 24-03-2020

Mình cập nhật lại benchmark và chạy lại tất cả benchmark 100 lần thay vì 10 lần. Các bạn có thể tìm hiểu repo benchmark tại đây

Có gì mới

Bản release v6 lần này không có quá nhiều sự thay đổi về mặt public API nhưng tối ưu hơn, nhỏ gọn hơn, một số bản sửa lỗi, và cung cấp một API mới để support JavaScript. Nghe thật thú vị hen, khám phá cùng mình thôi 💪

Hiệu năng

Với những thư viện thiên về thay đổi hoặc biến hoá data như AutoMapper thì vấn đề về hiệu năng đều khá quan trọng. Tuy nhiên trước khi đi quá sâu về vấn đề Hiệu năng, mình muốn nhấn mạnh mục đích của AutoMapper khi mình quyết định viết thư viện này chính là để transform Data Model (database) sang View Model (client/frontend) nên số lượng phần tử không nhất thiết phải lên đến hàng trăm ngàn phần tử thông qua Network Call. Với điều đó thì việc map một tập lên đến hàng triệu phần tử thì khá là không thực tế 😊. Bây giờ thì chúng ta nhìn vào 1 chút thông số nhé.

Đầu tiên, đây là model User mà mình làm mẫu cho benchmark này:

class Bio {
  job: string;
  age: number;
  birthday: Date;
}

class User {
  firstName: string;
  lastName: string;
  bio: Bio;
}

và view model UserVm tương ứng:

class BioVm {
  job: string;
  isAdult: boolean;
  birthday: string;
}

class UserVm {
  first: string;
  last: string;
  full: string;
  bio: BioVm;
}

với cấu hình như sau:

Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    mapFrom((s) => s.firstName + " " + s.lastName)
  );
Mapper.createMap(Bio, BioVm)
  .forMember(
    (d) => d.isAdult,
    mapFrom((s) => s.age > 18)
  )
  .forMember(
    (d) => d.birthday,
    mapFrom((s) => s.birthday.toDateString())
  );

Thực thi map từ User sang UserVm với cấu hình trên lên 1K, 10K và 100K phần tử cho mình kết quả như sau:

	1K items	10K items	100K items
`@nartc/automapper` v5	~9ms	~88ms	~959ms
`@nartc/automapper` v6	~8ms	~81ms	~785ms

Mỗi benchmark được chạy ~10~ 100 lần cho mỗi 1K, 10K, và 100K phần tử rồi lấy trung bình 10 lần chạy.

Các bạn có thể thấy rằng v6 nhanh hơn v5 khoảng 15-25%. Và cái gì thực sự thay đổi ở v6? AutoMapper v6 đã áp dụng một số phương pháp sau để tăng hiệu năng:

Loops Optimization: v6 sử dụng while thay thế cho for let (original for loop với biến index) ở một số chỗ quan trọng như: map và initialize mapping properties. Ở những khu vực for loop vẫn sử dụng thì biến length đã được cached để giảm thiểu property lookup ở mỗi vòng loop.
Accessing Array Index: v6 chuyển phần lớn cấu trúc data mà phần core sử dụng từ dạng Object sang Array để giảm thiểu property lookup. Và vẫn còn nhiều chỗ để cải thiện ở vấn đề này trong AutoMapper v6.

Tìm hiểu thêm về Accessing Array Index từ talk How we make Angular fast của Misko Hevery

Với sự cho phép của Yann Renaudin, là tác giả của thư viện morphism, mình xin chia sẻ benchmark của morphism với cấu hình tương tự như trên:

const morphismSchema = {
  first: "firstName",
  last: "lastName",
  full: ({ firstName, lastName }) => firstName + " " + lastName,
  bio: {
    job: "bio.job",
    isAdult: ({ bio }) => bio.age > 18,
    birthday: ({ bio }) => bio.birthday.toDateString(),
  },
};

Mỗi benchmark được chạy ~10~ 100 lần cho mỗi 1K, 10K, và 100K phần tử rồi lấy trung bình 10 lần chạy.

	1K items	10K items	100K items
`morphism`	~15ms	~144ms	~1436ms
`morphism` with `create-mapper`	~15ms	~145ms	~1464ms
`@nartc/automapper` v6	~8ms	~81ms	~785ms

Đây chỉ là sự so sánh với 1 benchmark cực kỳ đơn giản và chỉ so sánh về khoản map từ một model sang một model khác mà thôi. Về tiện ích, morphism là một thư viện cực kỳ tuyệt vời nếu các bạn có nhu cầu. morphism hỗ trợ map với schema configuration và điều này thì cực kỳ thích hợp với những dự án thuần JavaScript, không có nhiều classes để tượng trưng cho cấu trúc dữ liệu ở trong code. Nếu bạn có hứng thú thì có thể tìm hiểu thêm về morphism tại đây. Cám ơn Yann đã cho phép mình lấy morphism làm benchmark cho AutoMapper.

Nhỏ gọn

Nhìn chung, kích thước thư viện của v6 nhỏ hơn v5. Các hàm tiện ích (Utility Function) và phần core của thư viện đã được “dọn dẹp” khá nhiều. Kích thước của AutoMapper v5 Kích thước của AutoMapper v6

Kích thước bundle được cung cấp bởi Bundlephobia

Mặt khác, hãy nhìn qua lại cấu hình mapping khi nãy với sự khác nhau giữa v5 và v6:

// v5
Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    (opts) => opts.mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    (opts) => opts.mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    (opts) => opts.mapFrom((s) => s.firstName + " " + s.lastName)
  );

// v6
Mapper.createMap(User, UserVm)
  .forMember(
    (d) => d.first,
    mapFrom((s) => s.firstName)
  )
  .forMember(
    (d) => d.last,
    mapFrom((s) => s.lastName)
  )
  .forMember(
    (d) => d.full,
    mapFrom((s) => s.firstName + " " + s.lastName)
  );

Các bạn có thấy sự khác biệt không? Ở v6, tham số thứ 2 của hàm forMember() không còn lại ForMemberOptions nữa. ForMemberOptions là 1 Function Interface chứa tất cả các hàm mapping operations như: mapFrom(), mapWith(), ignore(), condition(), fromValue(), và một số hàm khác nữa. Ở v6, tất cả các hàm mapping operations này đều được tách riêng ra thành những Pure Function riêng biệt. Điều này giúp cho AutoMapper v6 có thể tree-shakable được.

tree-shake là thuật ngữ ở bước Bundle/Build code, dùng để chỉ đến việc những code không sử dụng đến (ví dụ như hàm được khai báo, nhưng không sử dụng đến trong code) thì sẽ được Builder/Bundler xoá sổ khỏi bundle cuối cùng. Kết quả là kích thước bundle cuối cùng có thể sẽ rất nhỏ, nhờ giảm đi được những code không dùng đến.

Lỗi this lỗi that

Ở những version trước của AutoMapper, các Mapping và Profile được lưu trữ dưới dạng là Object và dùng biến name ở trên các Class này để làm key cho các item này. Và chuyện gì đến sẽ đến, cái gì cũng đúng cho đến khi nó sai🤦‍, những Object này vì dùng Class.name nên khi người sử dụng thư viện (consumer) chạy code cho môi trường production, các plugins làm gọn code như Uglify hoặc Terser sẽ làm cho các Class.name này bị trùng.

AutoMapper v6 đã thay đổi cách lưu trữ những dữ liệu này với các Storages. Những storages này dùng WeakMap để lưu trữ chính Class làm key thay vì dùng Class.name. Điều này đảm bảo các Class sẽ không bị trùng nhau cho dù đã được minified.

// Để thấy được vấn đề với Class.name
class Foo {}

console.log(Foo.name); // logs Foo
console.log(Foo.prototype.constructor.name); // logs Foo

Hỗ trợ JavaScript

Trước v6, hỗ trợ cho JavaScript hầu như là không tồn tại. AutoMapper chỉ hoạt động với những dự án TypeScript mà thôi. Ở v6, AutoMapper sẽ cung cấp một API để hỗ trợ cho JavaScript. Trước khi giới thiệu qua API này, mình xin nói sơ qua về cách hoạt động của AutoMapper để mọi người hiểu rõ hơn về việc “chỉ hỗ trợ TypeScript”.

AutoMapper hoạt động theo nguyên lý lưu trữ Metadata (data về data) của các Models. Ví dụ model User ở trên có: firstName là string, lastName là string, và bio là model Bio. Đây được gọi là Metadata của class User. Để có được thông tin của những metadata này tại runtime, AutoMapper dùng decorator @AutoMap(). Sau đó, MetadataStorage sẽ đảm nhiệm việc lưu trữ metadata mà @AutoMap() cung cấp. Ở những dự án JavaScript thì việc sử dụng decorator là khá phức tạp, và bản thân AutoMapper cũng không cung cấp một API nào để làm việc với JavaScript. Nhưng điều này sẽ thay đổi ở AutoMapper v6.

AutoMapper v6 sẽ cung cấp API có tên là: createMapMetadata. API này sẽ “giả lập” cách hoạt động của @AutoMap() để có thể lưu trữ được metadata. Tuy nhiên, API này vẫn yêu cầu consumers cung cấp một số boiler-plate nhất định.

class User {}
class UserVm {}

class Bio {}
class BioVm {}

JavaScript không có khai báo fields và types nên có thể để trống. Nhưng những class trống này bắt buộc phải có, vì lý do lưu trữ Mapping mình đề cập tới ở mục trên.

createMapMetadata(Bio, {
  job: String,
  age: Number,
  birthday: Date,
});
createMapMetadata(User, {
  firstName: String,
  lastName: String,
  bio: Bio,
});
createMapMetadata(BioVm, {
  job: String,
  isAdult: Boolean,
  birthday: String,
});
createMapMetadata(UserVm, {
  first: String,
  last: String,
  full: String,
  bio: BioVm,
});

Khá dài dòng đúng không? Thực sự ra thì consumer không cần phải khai báo toàn bộ các fields như trên, mà chỉ cần khai báo các fields nào mà SẼ KHÔNG được cấu hình bằng .forMember(). Theo như cấu hình mapping ở đầu bài blog, thì isAdult và birthday ở BioVm là không cần khai báo. Tương tự, first, last, và full ở UserVm cũng không cần khai báo. Code sẽ như thế này:

createMapMetadata(Bio, {
  job: String,
  age: Number,
  birthday: Date,
});
createMapMetadata(User, {
  firstName: String,
  lastName: String,
  bio: Bio,
});

createMapMetadata(BioVm, {
  job: String,
});
createMapMetadata(UserVm, {
  bio: BioVm,
});

Điều tương tự sẽ được áp dụng khi consumer cấu hình từ UserVm -> User (BioVm -> Bio) thì những fields nào SẼ ĐƯỢC cấu hình bằng .forPath() (nếu dùng reverseMap()) hoặc .forMember() thì không cần khai báo ở createMapMetadata()

Cài đặt

Các bạn có thể sử dụng qua bản next của AutoMapper bằng cách sau:

npm i @nartc/automapper@next

Thay đổi từ v5

Như mình đã đề cập ở trên, các hàm mapping operations đã được tách ra thành hàm riêng, cấu hình mapping có thay đổi như sau:

// before
Mapper.createMap(User, UserVm)
    .forMember(d => d.full, opts => opts.mapFrom(s => s.first + ' ' + s.last)
    .forMember(d => d.foo, opts => opts.ignore());

// after
Mapper.createMap(User, UserVm)
    .forMember(d => d.full, mapFrom(s => s.first + ' ' + s.last)
    .forMember(d => d.foo, ignore())

Mapper.initialize() đã được khai tử. Các bạn nên dùng thẳng: Mapper.createMap(), Mapper.addProfile(), và Mapper.withGlobalSettings()
Tất cả các tham số nhận Profile và NamingConvention đều sẽ nhận vào Class của Profile và NamingConvention đó thay vì 1 instance.

// before
Mapper.createMap(User, UserVm, {
  sourceMemberNamingConvention: new PascalCaseNamingConvention(),
});

// after
Mapper.createMap(User, UserVm, {
  sourceMemberNamingConvention: PascalCaseNamingConvention,
});

Các bạn có thể tìm hiểu thêm tại đây

Kết bài

Một lần nữa, mình cảm thấy rất phấn khởi khi được giới thiệu với các bạn về những thay đổi của AutoMapper v6. Cũng như những bài blog về AutoMapper mình từng viết, hy vọng mọi người sẽ tham khảo qua và sử dụng thử nếu cảm thấy thích hợp với các use-cases của dự án của các bạn. Cám ơn mọi người đã đọc bài blog và hẹn gặp lại trong bài blog kế tiếp 👋

Build Dynamic Dialog with Angular CDK

Wed, 08 Jan 2020 00:00:00 GMT

Angular CDK is short for Angular Component Dev Kit (CDK). As the name suggests, the CDK provides you a set of tools to build feature-packed and high-quality Angular components without having to adhere to Material Design that Google embraces. The goal of the CDK is to allow developers to easier implement Common Patterns and Behaviors in our Angular applications. There are many different packages, patterns, and behaviors that you can explore by checking out the CDK documentation.

Lately, I have been involving in an Angular project where we have multiple UI Component Suite installed like NgBootstrap and PrimeNG, and couple other miscellaneous packages. Though these packages get the job done (and quick), we are at the point of having too many different moving parts to maintain and keep up-to-date. In other words, tech debts are building up and inconsistency is haunting our project. One prime example is Dynamic Dialog usage where you can a Dialog and pass in a custom Component as the content of the Dialog with extra data. Sounds neat right? At the moment we needed the feature, PrimeNG didn’t have support for DynamicDialog (they do now, check it out at PrimeNG DynamicDialog). One of our developers turned to NgBootstrap for their NgbModal (NgBootstrap NgbModal). That’s when we ended up with both NgBootstrap and PrimeNG in our project.

Now, we have turned ourselves to these different libraries for just a usage of a Dialog. There has to be a better way which is already available to you right? Luckily, yes. Angular CDK does provide an “easy” way to implement your own Dynamic Dialog with ANY stylings you want to go with. I have been looking into the Angular CDK, namely the Overlay module, to explore a way to build Dynamic Dialog without any dependency to those UI Component Suite so we will not have to rely on those Suite for future projects. This blog post is a mean to share my findings with you all and we are going to utilize Angular CDK OverlayModule along with BulmaCSS to build a Dynamic Dialog that adheres to Angular convention and not look like Material Design. Let’s jump it.

Preparations

Go ahead and initialize a new Angular application using the Angular CLI

ng new cdk-bulma-dialog

If you haven’t installed Angular CLI, let’s do so with npm i -g @angular/cli

Angular CLI generating new Angular application

We are not going to need routing and let’s also pick SCSS for our stylings. Next, let’s install Angular CDK

ng add @angular/cdk

Open styles.scss and add this line:

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

Open app.module.ts and add BrowserAnimationsModule import:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // <-- add this import
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, BrowserAnimationsModule], // <-- add BrowserAnimationsModule
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Open index.html and edit as following:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>CdkBulmaDialog</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
    <!-- Add BulmaCSS CDN -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css">
</head>
<body>
  <app-root></app-root>
</body>
</html>

Now we are ready to move on to the main content of this blog.

More Files

We are going to start off by generating and creating all of the files we are going to need.

Using Angular CLI

Generate DynamicDialogModule

ng generate module dynamic-dialog

Generate DynamicDialogService

ng generate service dynamic-dialog/dynamic-dialog --skipTests

For brevity of this blog post, I am going to include skipTests flag in all ng generate commands.

Generate DynamicDialogContentDirective

ng generate directive dynamic-dialog/dynamic-dialog-content --skipTests

Generate DynamicDialogRootComponent

ng generate component dynamic-dialog/dynamic-dialog-root --flat --skipTests --inlineTemplate --inlineStyle

We are going to use inlineTemplate and inlineStyle here so we keep everything that’s happening in our component in one *.component.ts file.

Creating directories and files

We are going to need some Models so go ahead and create a models directory under dynamic-dialog.

# assuming you are currently at the root of the project which is cdk-bulma-dialog
cd src/app/dynamic-dialog
mkdir models
cd models

Now, let’s create couple files

touch animation-state.enum.ts
touch dynamic-dialog-config.model.ts

and let’s also fill out these two new files. Open up animation-state.enum.ts

export enum AnimationState {
  Void = 'void',
  Enter = 'enter',
  Leave = 'leave'
}

then dynamic-dialog-config.model.ts

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

export class DynamicDialogConfig<TData = any> {
  header: string;
  closable: boolean;
  containerAnimationTiming: number;
  contentAnimationTiming: number;
  animationChildDelay: number;
  data?: TData;
  overlayConfig?: OverlayConfig;

  constructor() {
    this.header = '';
    this.closable = true;
    this.containerAnimationTiming = 0.3;
    this.contentAnimationTiming = 0.2;
    this.animationChildDelay = 0;
  }
}

Let’s go through each config:

header: Very self-explanatory. We are going to configure our dialog to have a header title. We will allow the Dialog consumers to be able to configure the header through DynamicDialogConfig.
closable: Whether to allow the Dialog to be closed via: clicking on backdrop and clicking a close icon. By default, we would like to have a close icon on the right-hand side of the header.
containerAnimationTiming: How long the animation of the Dialog Container runs. Visually, this is a fullscreen container underneath the Dialog Content.
contentAnimationTiming: How long the actual Dialog Content animation needs to run.
animationChildDelay: How long the delay is between the containerAnimation and contentAnimation
data: Extra data that we want to pass to the Dialog. Most of the times, it could be some metadata like productId or something like that that we need to fetch required data to display in the Dialog. The type is a Generic Type which we can specify when we construct our DynamicDialogConfig for a specific Dialog.
overlayConfig: OverlayConfig pass-through. The Dialog that we are building will dictate some default OverlayConfig (from OverlayModule) but we will also allow the consumers to configure the OverlayConfig and merge it with our default setup should they desire to.

Next, the last thing we are going to need is DynamicDialogRef. I will explain the significant of this ref when we get to fill it out. For now, let’s create the file

# assume you are in src/app/dynamic-dialog/models
cd ..
touch dynamic-dialog-ref.ts

Let’s start building

First, we are going to take care of DynamicDialogContentDirective as it is very short and straightforward. Open up dynamic-dialog-content.directive.ts

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

@Directive({
  selector: '[appDynamicDialogContent]'
})
export class DynamicDialogContentDirective {

  constructor(public readonly viewContainerRef: ViewContainerRef) { } // <-- inject ViewContainerRef

}

The directive will play as the insertion point. This is where we want to render our content (as a Component) dynamically. Hence, we are going to inject ViewContainerRef to the directive and as the directive is mounted, it will have access to the ViewContainerRef of the element that the directive is used on (Read more about Angular Directive) Don’t worry, we will piece everything together soon enough.

And that’s all we needed for DynamicDialogContentDirective. Let’s open up dynamic-dialog-ref.ts and add this piece of code

export class DynamicDialogRef<TReturnType = any> {

}

That’s it for now. Open dynamic-dialog-root.component.ts now

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

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush // <-- also use OnPush strategy.
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy { // <-- implements AfterViewInit and OnDestrou

  constructor() {
  }

  ngAfterViewInit(): void { // <-- ngAfterViewInit implementation
  }

  ngOnDestroy(): void { // <-- ngOnDestroy implementation
  }
}

We are going to need a couple of fields:

animationState and animationStateChanged: To keep track of animations of the container and content part of the Dialog. We will base on the animationState and AnimationEvent from @angular/animations to make meaningful decision about when the Dialog is actually closed.
contentComponentType: Type of the Component that is used for the content of the Dialog
componentRef: This is to hold the current reference to the Dialog Content so that we can destroy it in ngOnDestroy hook.

Let’s fill the fields out

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum'; // <-- import AnimationState

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    animationState: AnimationState = AnimationState.Enter;
    // Make sure you import AnimationEvent from @angular/animations
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

  constructor() {
  }

  ngAfterViewInit(): void {
  }

  ngOnDestroy(): void {
  }
}

We are also going to have a couple of things injected to DynamicDialogRootComponent using Dependency Injection (DI)

DynamicDialogConfig: Our custom-made configuration
DynamicDialogRef: Our custom-made dialogRef
ComponentFactoryResolver: When you define and use a regular Component in Angular, Angular will take the metadata from @Component() decorator and create a factory out of those metadata for your Component. Our Dialog will be rendered dynamically on the screen. Hence, we are going to need ComponentFactoryResolver to create the factory ourselves.
ChangeDetectorRef: The idea is we will start constructing our Dialog Content Component in ngAfterViewInit hook after the initial DOM has been loaded. And we are also leveraging OnPush strategy so after we create our Dialog Content Component, we want to call changeDetectorRef.markForCheck() so Angular Change Detection Mechanism will check this Dialog Root Component for update and we only do it once. The later change detection should be happening inside of the Dialog Content Component.

Again, let’s fill these out

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

  constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
  }

  ngAfterViewInit(): void {
  }

  ngOnDestroy(): void {
  }
}

Let’s fill out the template next

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    // Grab the Directive to use in the TypeScript portion
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
    }

    ngOnDestroy(): void {
    }
}

I grab the HTML directly from Bulma Modal and change the title to use dialogConfig.header. I also replace everything in between <section class="modal-card-body"></section> with <ng-template></ng-template> and use our DynamicDialogContentDirective on the ng-template. If you know how Dynamic Component works in Angular, you’ll kind of see what is going on here already. We use ng-template, bind DynamicDialogContentDirective and if you recall, we inject ViewContainerRef in our DynamicDialogContentDirective. This all essentially means we’re grabbing the ng-template as our ViewContainerRef and we can use that as the Insertion Point for our Dialog Content Component.

Now, let’s fill out ngAfterViewInit() and ngOnDestroy() shall we

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }
}

As mention before, in ngAfterViewInit(), we will loadContentComponent() using ComponentFactoryResolver and then mark the Dialog Root for Change Detection Check with ChangeDetectorRef.markForCheck(). In loadContentComponent(), we also grab the viewContainerRef from our DynamicDialogContentDirective to act as the Insertion Point for our Dialog Content Component. If you notice, you will see that we haven’t set our contentComponentType anywhere in this DynamicDialogRootComponent and you are absolutely right. We will assign contentComponentType at an earlier point, in a different place. In ngOnDestroy(), we just do some cleaning up with componentRef. Pretty self-explanatory 😊. Let’s add one more method to DynamicDialogRootComponent before moving on

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    // Add this method
    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }
}

Remember I said we are going to use animationState to make meaningful decision about closing the Dialog? startExitAnimation() will allow us to start that decision making process. There is still more work to be done in DynamicDialogRootComponent, but we will need to come back to it later. Next stop will be our DynamicDialogRef

DynamicDialogRef

DynamicDialogRef is the reference to the current instance Overlay that is being opened (and managed by Angular CDK). We will need a couple of fields and methods in DynamicDialogRef

beforeClosed$: This will be a Subject that will emit when the Dialog is about to close. We will keep the Subject private and expose the Observable counterpart via a getter
afterClosed$: Same concept as beforeClosed$ but this is for when the Dialog has already been closed. We will also pass some optional data back to the consumers with afterClosed$ as well.
componentInstance: The instance of DynamicDialogRootComponent which is being used by the Overlay to render the Dialog. We will hook onto the animationStateChanged on DynamicDialogRootComponent so we can determine when beforeClosed$ and afterClosed$ should emit.
close(data?: TReturnType): void: We are going to make the DynamicDialogRef available in Dependency Injection Context so that the Dialog Content Component can have access to the current DynamicDialogRef and will be able to call close() and pass in some data . Eg: when you close a Confirmation Dialog and upon close, you will want to pass true or false back to the Dialog Invoker so you can make a decision whether the user confirms the action or not. Again, data has a Generic Type TReturnType that we can pass in upon injecting DynamicDialogRef in a Dialog Content Component.

Beside these 4 things, we also need to inject OverlayRef so we can do some clean-up for the Overlay itself. Now, let’s fill this bad boy up

import { OverlayRef } from '@angular/cdk/overlay';
import { Observable, Subject } from 'rxjs';
import { filter, take } from 'rxjs/operators';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { AnimationState } from './models/animation-state.enum';

// A local constant.
const AnimationPhase = {
  START: 'start',
  DONE: 'done'
};

export class DynamicDialogRef<TReturnType = any> {
  private beforeClosed$: Subject<void> = new Subject<void>();
  private afterClosed$: Subject<TReturnType> = new Subject<TReturnType>();

  componentInstance: DynamicDialogRootComponent;

  constructor(private readonly overlayRef: OverlayRef) {
        overlayRef.backdropClick().pipe(take(1)).subscribe(this.close.bind(this));
  }

  get beforeClosed(): Observable<void> {
    return this.beforeClosed$.asObservable();
  }

  get afterClosed(): Observable<TReturnType> {
    return this.afterClosed$.asObservable();
  }

  close(data?: TReturnType): void {
    this.componentInstance.animationStateChanged.pipe(
      filter(event => event.phaseName === AnimationPhase.START),
      take(1)
    ).subscribe(() => {
      this.beforeClosed$.next();
      this.beforeClosed$.complete();
      this.overlayRef.detachBackdrop();
    });

    this.componentInstance.animationStateChanged.pipe(
      filter(event => event.phaseName === AnimationPhase.DONE && event.toState === AnimationState.Leave),
      take(1)
    ).subscribe(() => {
      this.overlayRef.dispose();
      this.afterClosed$.next(data);
      this.afterClosed$.complete();
      this.componentInstance = null;
    });

    this.componentInstance.startExitAnimation();
  }
}

Quite a lot is happening here. Let’s go through it

AnimationPhase is just a local constant that has START and DONE properties on it. You can extract this out to its own file or some other place where you keep track of all of your constants. To me, this would work fine.
In the constructor, we subscribe to backdropClick() on the overlayRef and call close() method.
Declare all of our fields beforeClosed$ , beforeClosed getter, afterClosed$, afterClosed getter, componentInstance, injected OverlayRef, and close() method.
beforeClosed and afterClosed getters will allow us to provide the underline Observable from their Subject without exposing the Subject. Subject has the ability to emit new values and we do not want the consumers to be able to do that.
close(data?: TReturnType): The meat of DynamicDialogRef. We setup two Subscription to animationStateChanged: one is for when AnimationPhase.START and another is for when AnimationPhase.DONE. When we first invoke close(), the animations will actually start first and @angular/animations allows us to hook into these AnimationEvent . So during AnimationPhase.START, we will have the Subscription to filter by the phaseName, and we are only interested in ONE and ONLY ONE emitted value so we take(1). Then, we have beforeClosed$ emit and complete right away so it cleans itself up. Finally, we will have the overlayRef to detachBackdrop(). The other Subscription works in a similar manner. filter by phaseName, take(1) and have afterClosed$ emit new value with data then complete itself. We also call overlayRef.dispose() to finally dispose the Overlay and nullify componentInstance. After setting up the Subscriptions, we actually invoke startExitAnimation() so the Subscriptions are ready when the animation starts.

That’s it for DynamicDialogRef. Now, let’s go back to DynamicDialogRootComponent since we have DynamicDialogRef.close() ready.

Finish up DynamicDialogRootComponent

Let’s first setup some methods that will invoke DynamicDialogRef.close() by default.

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

We added 2 methods

closeDialog(): Handle closing the Dialog upon clicking the Close Icon on the header or clicking on the backdrop.
handleEscapeKey(): A HostListener that listens to document:keydown event and will check if it’s the Escape key to close the Dialog.

Now, we are going to add animations to this DynamicDialogRootComponent

I’m going to utilize an npm package called ng-animate to help with my animation skills. If you want to follow along, please run npm i ng-animate

import { animateChild, AnimationEvent, group, query, transition, trigger, useAnimation } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { fadeIn, fadeOut, zoomIn, zoomOut } from 'ng-animate';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  animations: [
    trigger('zoom', [
      transition(
        '* => in',
        useAnimation(zoomIn, { params: { timing: '{{timing}}' } })
      ),
      transition(
        '* => out',
        useAnimation(zoomOut, { params: { timing: '{{timing}}' } })
      )
    ]),
    trigger('animation', [
      transition(
        `* => ${ AnimationState.Enter }`,
        group([
          useAnimation(fadeIn, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      ),
      transition(
        `* => ${ AnimationState.Leave }`,
        group([
          useAnimation(fadeOut, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      )
    ])
  ]
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

Ok, this is going to be painful. I would suggest reading more about Angular Animations. Basically, we setup two triggers : zoom and animation. zoom will be responsible for animating the Dialog Content while animation will be responsible for animating the Dialog Container. In animation trigger, we setup fadeIn and fadeOut animation (from ng-animate, if you’re comfortable with Animations in general, feel free to setup your own animations) based on the state , we also leverage Animation Params (eg: {{timing}}) to pass in configurable Animation Configuration to our animations. Remember containerAnimationTiming and contentAnimationTiming and such? Those will come into play here. Last but not least, we also setup query for zoom trigger inside of animation trigger so we are able to run animateChild with delay, again, remember animateChildDelay 😅?! Again, I would encourage reading more about Angular Animations.

Finally, let’s finish up the template and hook everything together

import { animateChild, AnimationEvent, group, query, transition, trigger, useAnimation } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { fadeIn, fadeOut, zoomIn, zoomOut } from 'ng-animate';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
      [@animation]="{
        value: animationState,
        params: {
          timing: dialogConfig.containerAnimationTiming,
          delayChild: dialogConfig.animationChildDelay
        }
      }"
      (@animation.start)="animationStateChanged.emit($event)"
      (@animation.done)="animationStateChanged.emit($event)"
    >
      <div class="modal-background" (click)="closeDialog()"></div>
      <div
        class="modal-card"
        [@zoom]="{
          value: animationState == 'enter' ? 'in' : 'out',
          params: { timing: dialogConfig.contentAnimationTiming }
        }">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
            (click)="closeDialog()"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
`,
  changeDetection: ChangeDetectionStrategy.OnPush,
  animations: [
    trigger('zoom', [
      transition(
        '* => in',
        useAnimation(zoomIn, { params: { timing: '{{timing}}' } })
      ),
      transition(
        '* => out',
        useAnimation(zoomOut, { params: { timing: '{{timing}}' } })
      )
    ]),
    trigger('animation', [
      transition(
        `* => ${ AnimationState.Enter }`,
        group([
          useAnimation(fadeIn, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      ),
      transition(
        `* => ${ AnimationState.Leave }`,
        group([
          useAnimation(fadeOut, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      )
    ])
  ]
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

We hook up animation trigger to the top DOM element which is the modal and zoom trigger to modal-card. We also use dialogConfig to pass in the configurable Animation Params. Next, we set @animation.start and @animation.done event then have animationStateChanged emit accordingly. You see how startExitAnimation, DynamicDialogRef.close() and animationStateChanged all play together now? Finally, we hook up closeDialog() to modal-background and button.delete (close icon) on the header.

Woohoo 🔥, we are 60% done now 😅. Let’s finish up the last 40% with DynamicDialogService

DynamicDialogService

Beside DynamicDialogRef, DynamicDialogService is the last piece that will allow the consumers to interact with our whole Dynamic Dialog. So open up dynamic-dialog.service.ts and jump right in. DynamicDialogService only exposes one method which is open<TReturnType = any>() so the consumers can use this method to open the Dialog.

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
  }
}

Let’s import and inject everything we need first. After that, we declare a private readonly defaultDialogConfig which will hold our default configuration of the Dialog. We did setup some default configurations inside of DynamicDialogConfig upon instantiation. Here in the constructor, we are going to be defaulting some OverlayConfig as well

disposeOnNavigation: Self-explanatory. We want to close the dialog if we navigate away from the current page so we clean up and prevent potential memory-leak.
hasBackdrop: This can be set default or not. I set it to true. If it’s true, then Overlay will also render a cdk-backdrop element along side the cdk-overlay on our DOM Tree.
panelClass: Customizable HTML class so we can customize the Overlay element should we desire.
scrollStrategy: Self-explanatory. Set the scrolling behavior when the Overlay is opened. We default it to BlockScrollStrategy here. Read more about ScrollStrategies
positionStrategy: Set the position of the Overlay when it’s opened. Default to center. Read more about PositionStrategies

Next, we declare open() method. open() takes in an optional Generic Type TReturnType . We will have the open() method to return an DynamicDialogRef<TReturnType> so the DynamicDialogRef.afterClosed will have the correct type when the consumers subscribe to it. open() will expect a Component for the Dialog Content (remember contentComponentType, here’s the earlier point that we set the contentComponentType) and a DynamicDialogConfig to be merged with defaultDialogConfig. Afterward, we create our OverlayRef. Let’s implement createOverlay() now.

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }
}

Very simple. We call overlay.create() and pass in the OverlayConfig from DynamicDialogConfig.overlayConfig. Now that we have OverlayRef, we can start creating our custom DynamicDialogRef

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
    const dialogRef = new DynamicDialogRef<TReturnType>(overlayRef);
    dialogRef.componentInstance = this.attachDialogContainer(overlayRef, component, dialogRef, mergeConfig);
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }
}

Remember componentInstance on DynamicDialogRef that has the type of DynamicDialogRootComponent. DynamicDialogRootComponent will still be created dynamically and this is really where Overlay and Portal from Angular CDK come into play. OverlayRef is a PortalOutlet which can attach a ComponentPortal to render that Component dynamically on the screen. Normally, you can leverage Dynamic Component Loader to create the Component dynamically. However, Overlay and Portal from Angular CDK provide better APIs to work with, and to clean up. With that in mind, let’s work on attachDialogContainer method

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
    const dialogRef = new DynamicDialogRef<TReturnType>(overlayRef);
    dialogRef.componentInstance = this.attachDialogContainer(overlayRef, component, dialogRef, mergeConfig);
    return dialogRef;
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }

  private attachDialogContainer(overlayRef: OverlayRef, component: Type<any>, dialogRef: DynamicDialogRef, dialogConfig: DynamicDialogConfig): DynamicDialogRootComponent {
    const injector = this.createInjector(dialogRef, dialogConfig);
    const portal = new ComponentPortal(DynamicDialogRootComponent, null, injector);
    const ref = overlayRef.attach(portal);
    ref.instance.contentComponentType = component;
    return ref.instance;
  }

  private createInjector(ref: DynamicDialogRef, config: DynamicDialogConfig): PortalInjector {
    const injectorTokenMap = new WeakMap();
    injectorTokenMap.set(DynamicDialogRef, ref);
    injectorTokenMap.set(DynamicDialogConfig, config);
    return new PortalInjector(this.injector, injectorTokenMap);
  }
}

First thing is we want to createInjector() for the Dialog because we want DynamicDialogRef and DynamicDialogConfig to be available via Dependency Injection in the Overlay instance which ultimately manages DynamicDialogRootComponent and custom Dialog Content Component which will also have access to the same Injector which provides the same DynamicDialogRef and DynamicDialogConfig instances used when the Dialog is opened with open(). PortalInjector will just merge a token map (WeakMap here) with the parentInjector so it can provide our custom tokens to the Injector. With the PortalInjector ready, we can then create an instance of ComponentPortal with the PortalInjector and our own DynamicDialogRootComponent. All that’s left to do is to attach this ComponentPortal to the OverlayRef. Call overlayRef.attach() to do so. Returned value is the reference to the underline Component used to instantiate ComponentPortal, which in this case is our DynamicDialogRootComponent and this is where we will assign the passed-in component that contentComponentType field. Finally, we return the ref.instance which is the instance of DynamicDialogRootComponent which is being managed by the current Overlay. Ultimately, we return the dialogRef for open() so the consumers have a hold of the dialogRef so they can subscribe to its events when it’s closed.

DynamicDialogModule

Every pieces of the Dynamic Dialog has been completed. However, we need to put everything in DynamicDialogModule before we can use it. Open dynamic-dialog.module.ts

import { OverlayModule } from '@angular/cdk/overlay';
import { CommonModule } from '@angular/common';
import { NgModule } from '@angular/core';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogService } from './dynamic-dialog.service';


@NgModule({
  declarations: [DynamicDialogContentDirective, DynamicDialogRootComponent],
  imports: [CommonModule, OverlayModule], // <-- import OverlayModule
  entryComponents: [DynamicDialogRootComponent], // <-- add DynamicDialogRootComponent to entryComponents. Make sure to put it under declarations as well if you haven't already
  providers: [DynamicDialogService] // provide DynamicDialogService
})
export class DynamicDialogModule {
}

Simple Usage

Before we use our Dialog, let’s create a simple Component to be our Dialog Content. Run the following command

# assume you are at the root level of the project (cdk-bulma-dialog)
ng generate component test-dialog 
--skipTests 
--inlineTemplate 
--inlineStyle 
--changeDetection=OnPush
--entryComponent

We use the CLI to generate a Component with inlineTemplate, inlineStyle, skipTests, changeDetection=OnPush, and entryComponent flags. This component will be really simple so we will have everything inline. entryComponent flag will put this component in entryComponents array automatically for us. Now, let’s open test-dialog.component.ts

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

@Component({
  selector: 'app-test-dialog',
    template: `
        <p>test-dialog works!</p>
        <button class="button" (click)="close()">Close</button>
    `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class TestDialogComponent implements OnInit {

  constructor(
        private readonly dialogConfig: DynamicDialogConfig, 
        private readonly dialogRef: DynamicDialogRef<string>
    ) {}

  ngOnInit() {
  }

  close() {
    this.dialogRef.close('closed from inside content dialog');
  }
}

We only add a button with (click) bound to close() method. We also inject DynamicDialogConfig and DynamicDialogRef<string> to check if our PortalInjector works or not. In close(), we call dialogRef.close() and pass in a string 'closed from inside content dialog'. Now, open app.component.html

<button class="button" (click)="showOverlay()">Show Overlay</button>

then open app.component.ts

import { Component } from '@angular/core';
import { DynamicDialogService } from './dynamic-dialog/dynamic-dialog.service';
import { DynamicDialogConfig } from './dynamic-dialog/models/dynamic-dialog-config.model';
import { TestDialogComponent } from './test-dialog/test-dialog.component';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  constructor(private readonly dynamicDialogService: DynamicDialogService) {
  }

  showOverlay() {
    const config = new DynamicDialogConfig();
    config.header = TestDialogComponent.name;
    const ref = this.dynamicDialogService.open<string>(TestDialogComponent, config);
    ref.afterClosed.subscribe(data => {
      console.log('closed with data', data);
    });
  }
}

We inject DynamicDialogService and implement showOverlay() method:

Instantiate a new DynamicDialogConfig, set the header to the name of TestDialogComponent.
Call dynamicDialogService.open() , with TestDialogComponent and config as the arguments, then assign the returned DynamicDialogRef back to local variable ref
Subscribe to ref.afterClosed and log the data passed from within TestDialogComponent.close() method.

Open app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // <-- add this import
import { AppComponent } from './app.component';
import { DynamicDialogModule } from './dynamic-dialog/dynamic-dialog.module';
import { TestDialogComponent } from './test-dialog/test-dialog.component';

@NgModule({
  declarations: [AppComponent, TestDialogComponent],
  imports: [BrowserModule, BrowserAnimationsModule, DynamicDialogModule],
  bootstrap: [AppComponent],
  entryComponents: [TestDialogComponent]
})
export class AppModule {
}

Make sure you have TestDialogComponent in entryComponents and DynamicDialogModule in imports. Now, everything is ready. Moment of truth! Run your Angular application

ng serve -o

You should see the following on the screen

Lonely Show Overlay button

Clicking on the Show Overlay button will bring up our TestDialogComponent as a Dialog

Tada!

Open your Console, and click on Close button, you’ll see

closed with data closed from inside content dialog

logged to the Console. 👍

Recap

To recap, I have a little ugly diagram

…😢

Here is the encapsulation of what’s happening under the hood when you call dynamicDialogService.open(). Overlay instance is created to manage the current OverlayRef that is being used to handle the current PortalOutlet which renders the DynamicDialogRootComponent as its ComponentPortal. Then, we have the PortalInjector to inject the current instances of DynamicDialogRef and DynamicDialogConfig so we can have access to those in the Dialog Content Component (TestDialogComponent). That’s all there is to it. Overlay and Portal are two very powerful tools that Angular CDK provides with robust APIs which allows developers like us build high quality components like the DynamicDialog. With the same concept, you can apply Overlay and Portal to build many different common overlay behaviors like: Tooltip, Drawer, Toast etc… 💪

To conclude, I hope that I was able to share something and you learn something new after this long blog post 🚀. Have fun and good luck. I’ll see you all in the next blog 👋

Reference

Xây dựng Dynamic Dialog với Angular CDK

Wed, 08 Jan 2020 00:00:00 GMT

Angular CDK là tên viết ngắn gọn cho Angular Component Dev Kit (CDK). Theo như tên gọi, CDK cung cấp cho các bạn một bộ các công cụ dùng để build những Angular Components giàu tính năng và chất lừ mà không cần phải tuân theo tiêu chuẩn của Material Design của Google. Mục đích của CDK là cho phép developers có thể triển khai những patterns và behaviors phổ biến trong ứng dụng Angular của mình. Có khá nhiều những gói thư viện, patterns, và behaviors khác nhau mà các bạn có thể khám phá bằng việc nghiên cứu documentation của CDK.

Gần đây, mình đang làm một dự án Angular mà trong dự án này, bọn mình có dùng cùng một lúc các Bộ UI Component như NgBootstrap và PrimeNG, cũng như một số thư viện lẻ tẻ khác. Mặc dù là việc dùng các thư viện này giúp bọn mình làm xong việc (và nhanh nữa), nhưng việc dùng vô tội vạ đã đẩy dự án đến một vấn đề là có quá nhiều các bộ phận khác nhau mà cần phải maintain, hoặc update. Nói cách khác, tech debts đang bị dồn từng ngày và sự không thống nhất đang ám ảnh toàn bộ dự án. Một ví dụ điển hình nhât là Dynamic Dialog khi mà cần phải hiển thị một Dialog và có thể truyền vào một Component để hiển thị nội dung của Dialog này. Nghe phê phê he? Tại thời điểm mà bọn mình cần tính năng này, PrimeNG chưa có hỗ trợ DynamicDialog (bây giờ thì họ có hỗ trợ rồi, nghiên cứu thêm tại PrimeNG DynamicDialog). Một dev trong team mình đã tìm đến NgBootstrap vì NgbModal (đọc thêm về NgBootstrap NgbModal). Đó là lý do và cũng là lúc mà dự án có cả NgBootstrap lẫn PrimeNG.

Nhưng phải có cách nào tốt hơn chứ đúng không? Phải có cái nào mà có thể dùng những cái sẵn có chứ! May mắn cho các bạn là có. Angular CDK có cung cấp một cách khá “dễ” để triển khai DynamicDialog của riêng bạn, có thể kết hợp với BẤT CỨ bộ giao diện mà các bạn đang hoặc muốn sử dụng. Từ đó, mình đã và đang tìm hiểu thêm về Angular CDK, đặc biệt là Overlay module, để khám phá một cách để xây dựng DynamicDialog mà không phải phụ thuộc vào bất cứ Bộ UI Component nào để trong các dự án tương lai, bọn mình không phải lặp lại sai lầm nữa. Bài blog này là chia sẻ của mình về những gì mình tìm hiểu được và thông qua bài này, chúng ta sẽ sử dụng Angular CDK OverlayModule cùng với Bulma CSS để xây dựng một DynamicDialog theo phong cách Angular. Bắt đầu thôi.

Chuẩn bị

Chúng ta sẽ bắt đầu bằng việc tạo mới một ứng dụng Angular với Angular CLI

ng new cdk-bulma-dialog

Nếu như chưa cài đặt Angular CLI, các bạn cài bằng lệnh npm i -g @angular/cli

Angular CLI khởi tạo một ứng dụng Angular mới

Chúng ta sẽ không cần routing và sẽ chọn SCSS cho phần giao diện. Kế tiếp, chúng ta sẽ cài Angular CDK

ng add @angular/cdk

Mở file styles.scss và thêm vào dòng code này:

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

Mở file app.module.ts và thêm BrowserAnimationsModule:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // <-- thêm import này 
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, BrowserAnimationsModule], // <-- thêm BrowserAnimationsModule
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Mở index.html và sửa lại như sau:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>CdkBulmaDialog</title>
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
    <!-- Thêm BulmaCSS CDN -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css">
</head>
<body>
  <app-root></app-root>
</body>
</html>

Và bây giờ thì chúng ta đã sẵn sàng để tiếp tục vào phần chính của bài blog này.

Nhiều Files khác nữa

Chúng ta sẽ bắt đầu phần này với việc khởi tạo một số files cần thiết bằng Angular CLI lẫn bằng tay

Dùng Angular CLI

Khởi tạo DynamicDialogModule

ng generate module dynamic-dialog

Khởi tạo DynamicDialogService

ng generate service dynamic-dialog/dynamic-dialog --skipTests

Để bài viết này đơn giản, mình sẽ thêm skipTests vào tất cả các lệnh ng generate

Khởi tạo DynamicDialogContentDirective

ng generate directive dynamic-dialog/dynamic-dialog-content --skipTests

Khởi tạo DynamicDialogRootComponent

ng generate component dynamic-dialog/dynamic-dialog-root --flat --skipTests --inlineTemplate --inlineStyle

Chúng ta sẽ dùng inlineTemplate và inlineStyle để có thể thấy được những gì xảy ra trong DynamicDialogRootComponent trong một file *.component.ts mà thôi.

Tạo thư mục và files bằng tay

Chúng ta sẽ phải cần một số Models nên các bạn hãy tự tạo một thư mục mới tên là models. Thư mục này nên nằm dưới dynamic-dialog 1 bậc.

# mặc định là các bạn đang ở root của cdk-bulma-dialog
cd src/app/dynamic-dialog
mkdir models
cd models

Bây giờ thì hãy tạo 1 số files sau

touch animation-state.enum.ts
touch dynamic-dialog-config.model.ts

và cũng viết nốt code cho các files này luôn. Mở file animation-state.enum.ts

export enum AnimationState {
  Void = 'void',
  Enter = 'enter',
  Leave = 'leave'
}

sau đó là dynamic-dialog-config.model.ts

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

export class DynamicDialogConfig<TData = any> {
  header: string;
  closable: boolean;
  containerAnimationTiming: number;
  contentAnimationTiming: number;
  animationChildDelay: number;
  data?: TData;
  overlayConfig?: OverlayConfig;

  constructor() {
    this.header = '';
    this.closable = true;
    this.containerAnimationTiming = 0.3;
    this.contentAnimationTiming = 0.2;
    this.animationChildDelay = 0;
  }
}

Hãy điểm qua từng config:

header: Khá dễ hiểu. Chúng ta sẽ cấu hình dialog của mình để có một title. Mình sẽ cho phép người dùng Dialog tuỳ chỉnh biến header thông qua DynamicDialogConfig.
closable: Cho phép Dialog được đóng lại bằng cách: click vào backdrop và click vào close icon. Mặc định, chúng ta sẽ muốn có một close icon ở bên phải của header.
containerAnimationTiming: Thời gian để chạy animation của Dialog Container. Nhìn trên màn hình, thì Dialog Container sẽ là một khoảng có màu mờ, toàn màn hình và sẽ nằm bên dưới của Dialog Content.
contentAnimationTiming: Thời gian để chạy animation của Dialog Content.
animationChildDelay: Thời giản cách khoảng giữ animation của Dialog Conatiner` và **Dialog Content.
data: Dữ liệu thêm để truyền vào cho Dialog khi mở Dialog. Phần lớn thì data sẽ chứa một số thông tin như productId chẳng hạn, để khi mở Dialog, mình có thể dùng productId để fetch dữ liệu Product.
overlayConfig: OverlayConfig của Overlay từ Angular CDK. Dialog mà chúng ta đang dựng sẽ cấu hình một số giá trị mặc định cho OverlayConfig nhưng chúng ta cũng sẽ cung cấp người dùng Dialog khả năng cấu hình OverlayConfig này thông qua biến overlayConfig. overlayConfig truyền vào sẽ được gộp (merge) với config đã được cấu hình sẵn.

Kế đến, file cuối cùng mà chúng ta cần là DynamicDialogRef. Mình sẽ giải thích tầm quan trọng của ref khi chúng ta bắt đầu viết code cho nó. Bây giờ thì cứ tạo file đó đi đã.

# mặc định là các bạn đang ở bên trong src/app/dynamic-dialog/models
cd ..
touch dynamic-dialog-ref.ts

Bắt đầu chiến thôi

Đầu tiên, chúng ta sẽ xử lý thằng DynamicDialogContentDirective trước vì nó rất ngắn và dễ hiểu. Mở file dynamic-dialog-content.directive.ts lên thôi

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

@Directive({
  selector: '[appDynamicDialogContent]'
})
export class DynamicDialogContentDirective {

  constructor(public readonly viewContainerRef: ViewContainerRef) { } // <-- inject ViewContainerRef

}

Thằng directive này sẽ giữ vai trò như một cột mốc để thêm vào. Đây là nơi mà chúng ta muốn hiển thị động nội dung (bằng một Component) của Dialog. Vì vậy, chúng ta cần inject ViewContainerRef vào thằng directive này để khi nó được mount, nó sẽ có quyền truy xuất đến cái element gốc mà directive này được sử dụng trên element gốc đó dưới dạng là ViewContainerRef. (Đọc thêm về Angular Directive). Đừng lo lắng nếu nghe như sét đánh ngang tai, chúng ta sẽ gỡ các nút thắt sớm thôi.

và đó là tất cả code mà chúng ta cần cho DynamicDialogContentDirective. Giờ thì mở file dynamic-dialog-ref.ts và thêm 1 đoạn code nhỏ này

export class DynamicDialogRef<TReturnType = any> {

}

Hiện tại thì chỉ cần nhiêu đó thôi. Giờ hãy mở file dynamic-dialog-root.component.ts

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

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush // <-- dùng OnPush strategy.
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy { // <-- implements AfterViewInit and OnDestroy

  constructor() {
  }

  ngAfterViewInit(): void { // <-- ngAfterViewInit
  }

  ngOnDestroy(): void { // <-- ngOnDestroy
  }
}

Chúng ta sẽ cần một số fields sau:

animationState và animationStateChanged: Dùng để theo dõi các bước animations của container và content của Dialog. Chúng ta sẽ dựa vào animationState và AnimationEvent từ gói @angular/animations để xác định được thời điểm mà Dialog bị đóng lại.
contentComponentType: Component được truyền vào và được dùng để hiển thị phần content của Dialog.
componentRef: Biến này chỉ dùng để giữ con trỏ hiện tại đến Dialog Content Component, được dùng để “dọn dẹp”, tiêu huỷ đi khi hook ngOnDestroy chạy.

Quẩy code cho mấy fields này thôi

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum'; // <-- import AnimationState

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    animationState: AnimationState = AnimationState.Enter;
    // Bảo đảm là các bạn import AnimationEvent từ @angular/animations
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

  constructor() {
  }

  ngAfterViewInit(): void {
  }

  ngOnDestroy(): void {
  }
}

Ngoài những fields trên, chúng ta cũng sẽ cần một số thứ được injected vào cho DynamicDialogRootComponent này thông qua Dependency Injection (DI)

DynamicDialogConfig: Hàng configuration hand-made của mình
DynamicDialogRef: Hàng dialogRef hand-made của mình
ComponentFactoryResolver: Một chút kiến thức chung. Khi các bạn khởi tạo và sử dụng một Component thông thường bên trong Angular (nghĩa là dùng selector của Component trên template. Ví dụ: <app-todo-item></app-todo-item>), Angular sẽ lấy thông tin metadata từ decorator @Component() và sẽ tạo một factory cho Component đó. Factory sau đó sẽ được Angular Compiler dùng để biết được thông tin về Component, từ đó sẽ hiển thị cũng như cung cấp những thứ cần thiết cho Component đó sử dụng. Dialog của mình sẽ được hiển thị động trên màn hình vào bất cứ thời điểm nào. Vì thế, chúng ta sẽ cần phải dùng đến ComponentFactoryResolver để có thể tạo được factory cho Dialog bằng tay.
ChangeDetectorRef: Ý tưởng ở đây là chúng ta sẽ bắt đầu việc khởi tạo Dialog Content Component trong hook ngAfterViewInit sau khi DOM ban đầu đã được load xong. Bên cạnh đó, chúng ta cũng sử dụng OnPush vì thế sau khi khởi tạo Dialog Content Component, chúng ta sẽ muốn gọi changeDetectorRef.markForCheck() để thông báo cho Cơ chế Change Detection của Angular biến được có sự thay đổi trong DynamicDialogRootComponent và việc thông báo này chỉ xảy ra một lần duy nhất thôi. Các thay đổi khác trong tương lai sẽ xảy ra bên trong Dialog Content Component.

Một lần nữa, quẩy code thôi

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <p>
      dynamic-dialog-root works!
    </p>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

  constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
  }

  ngAfterViewInit(): void {
  }

  ngOnDestroy(): void {
  }
}

Quẩy template nào

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    // Giữ lấy con trỏ tới Directive để dùng trong TypeScript
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
    }

    ngOnDestroy(): void {
    }
}

Mình lấy HTML trực tiếp từ Bulma Modal luôn và chỉ thay đổi Modal Title sang dialogConfig.header. Mình cũng bỏ tất cả những thứ râu ria ở giữa <section class="modal-card-body"></section> với <ng-template></ng-template> và quăng thằng DynamicDialogContentDirective lên ng-tempalte. Nếu bạn nào đã biết các Dynamic Component hoạt động trong Angular, bạn có thể thấy được cái gì đang xảy ra ở đây rồi. Chúng ta dùng ng-template, bind DynamicDialogContentDirective lên ng-template, và nếu nhớ lại, thì chúng ta cũng inject ViewContainerRef trong DynamicDialogContentDirective. Tất cả mấy thứ này sẽ giúp chúng ta lấy được con trỏ tới ng-template dưới dạng ViewContainerRef và chuyển ng-template này thành cột mốc để có thể hiển thị động Dialog Content Component.

Bây giờ thì triển code cho ngAfterViewInit() và ngOnDestroy() thôi

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }
}

Như đã nhắc ở trên, trong ngAfterViewInit(), chúng ta sẽ khởi tạo Dialog Content Component bằng việc gọi hàm loadContentComponent(), dùng ComponentFactoryResolver và sẽ thông báo cho Change Detection để có thể update DialogRootComponent sau khi khởi tạo xong. Trong hàm loadContentComponent(), chúng ta cũng sẽ lấy viewContainerRef từ thằng DynamicDialogContentDirective. Nếu để ý, các bạn sẽ thấy là mình chưa bao giờ gán giá trị cho contentComponentType ở đâu trong DynamicDialogRootComponent hết, và các bạn hoàn toàn đúng. Chúng ta sẽ gán giá trị cho contentComponentType vào một thời điểm “sớm” hơn, và ở một vị trí khác. Trong ngOnDestroy(), chúng ta chỉ triển khai một số công việc dọn dẹp với componentRef thôi. Khá là dễ hiểu 😊. Trước khi chuyển sang file khác, hãy triển thêm 1 hàm cho DynamicDialogRootComponent nữa.

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    // Thêm hàm này
    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }
}

Các bạn có nhớ mình nói là chúng ta sẽ dùng đến animationState để quyết định việc đóng Dialog không? Hàm startExitAnimation() sẽ giúp chúng ta bắt đầu được quy trình đóng Dialog này. Phù, vẫn có một số việc cần phải làm trong DynamicDialogRootComponent nữa, nhưng chúng ta sẽ phải quay lại file này sau. Điểm đến kế tiếp sẽ là DynamicDialogRef, con hàng quan trọng không kém 💪

DynamicDialogRef

DynamicDialogRef là một con trỏ đến instance hiện tại của Overlay đang được mở (và được quản lý bởi Angular CDK). Chúng ta sẽ cần một số fields và hàm trong DynamicDialogRef sau:

beforeClosed$: Đây là một Subject và Subject này sẽ emit khi Dialog chuẩn bị được đóng. Chúng ta sẽ giữ cho Subject này private và sẽ chỉ cung cấp cho người dùng phần Observable thông qua một getter mà thôi.
afterClosed$: Tương tự như beforeClosed$. Khi Dialog đã được đóng lại, thì chúng ta sẽ truyền kèm theo một số data (nếu có) mà người dùng muốn truyền.
componentInstance: Instane của DynamicDialogRootComponent đang được sử dụng bởi Overlay để hiển thị Dialog. Chúng ta sẽ cần tới DynamicDialogRootComponent và hàm animationStateChanged của hắn để có thể xác định được đúng thời điểm mà beforeClosed$ và afterClosed$ cần emit.
close(data?: TReturnType): DynamicDialogRef sẽ được đưa vào Dependency Injection bằng Injector để người dùng có thể inject DynamicDialogRef vào Dialog Content Component mà họ tạo và sẽ gọi được hàm dialogRef.close() này. Ví dụ: khi người dùng đóng một Dialog Xác Nhận, chúng ta sẽ muốn biết được là người dùng chọn Xác Nhận hay Huỷ bỏ khi Dialog được đóng, vì thế tuỳ thuộc vào lựa chọn của người dùng mà chúng ta có thể truyền data vào cho hàm close() để nơi mở Dialog (Dialog Invoker) có thể nhận được data này và thực thi thao tác tiếp theo sau khi người dùng Xác Nhận.

Ngoài 4 thứ trên, chúng ta cũng sẽ cần inject OverlayRef từ Angular CDK để có thể thực hiện một số tác vụ dọn dẹp trên thằng Overlay. Giờ thì quẩy code thôi.

import { OverlayRef } from '@angular/cdk/overlay';
import { Observable, Subject } from 'rxjs';
import { filter, take } from 'rxjs/operators';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { AnimationState } from './models/animation-state.enum';

// Hằng số local.
const AnimationPhase = {
  START: 'start',
  DONE: 'done'
};

export class DynamicDialogRef<TReturnType = any> {
  private beforeClosed$: Subject<void> = new Subject<void>();
  private afterClosed$: Subject<TReturnType> = new Subject<TReturnType>();

  componentInstance: DynamicDialogRootComponent;

  constructor(private readonly overlayRef: OverlayRef) {
        overlayRef.backdropClick().pipe(take(1)).subscribe(this.close.bind(this));
  }

  get beforeClosed(): Observable<void> {
    return this.beforeClosed$.asObservable();
  }

  get afterClosed(): Observable<TReturnType> {
    return this.afterClosed$.asObservable();
  }

  close(data?: TReturnType): void {
    this.componentInstance.animationStateChanged.pipe(
      filter(event => event.phaseName === AnimationPhase.START),
      take(1)
    ).subscribe(() => {
      this.beforeClosed$.next();
      this.beforeClosed$.complete();
      this.overlayRef.detachBackdrop();
    });

    this.componentInstance.animationStateChanged.pipe(
      filter(event => event.phaseName === AnimationPhase.DONE && event.toState === AnimationState.Leave),
      take(1)
    ).subscribe(() => {
      this.overlayRef.dispose();
      this.afterClosed$.next(data);
      this.afterClosed$.complete();
      this.componentInstance = null;
    });

    this.componentInstance.startExitAnimation();
  }
}

Quá trời thứ xảy ra ở đây. Hãy đi qua từng cái một nhé.

AnimationPhase chỉ là một hằng số local thôi. Thay vì dùng magic-string 'start' với 'done' thì mình dùng AnimationPhase. Nếu muốn, bạn có thể đem AnimationPhase ra một file riêng cũng được.
Trong constructor, chúng ta sẽ lắng nghe thằng backdropClick() trên overlayRef và sẽ gọi hàm close() khi backdrop được click.
Khai báo tất cả các fields được nhắc đến ở trên: beforeClosed$, afterClosed$, mấy cái getters, componentInstance, OverlayRef được inject, và hàm close()
Hàm close(): con hàng quan trọng của DynamicDialogRef. Trong đây, chúng ta xác lập 2 Subscriptions đến animationStateChanged: Một cái là sẽ lắng nghe AnimationPhase.START và cái còn lại là lắng nghe AnimationPhase.DONE. Khi chúng ta bắt đầu gọi hàm closse(), thì thực tế các animations của Dialog sẽ bắt đầu chạy trước và @angular/animations cho phép chúng ta lắng nghe những AnimationEvent này. Trong quá trình AnimationPhase.START (animations bắt đầu) chạy, chúng ta filter các sự kiện Animation này theo phaseName và chúng ta cũng chỉ cần nhận giá trị của MỘT sự kiện duy nhât mà thôi nên chúng ta dùng take(1). Ở thời điểm này, beforeClosed$ sẽ emit và cũng sẽ tự hoàn thành để tự dọn dẹp luôn. Cuối cùng ở chuỗi sự kiến AnimationPhase.START, chúng ta sẽ gọi hàm overlayRef.detachBackdrop() để dọn dẹp thằng backdrop. Subscription còn lại thì chúng ta cũng dùng các bước tương tự, filter bằng phaseName, take(1) và cho afterClosed$ emit. Khác biệt ở đây là chúng ta sẽ gọi overlayRef.dispose() để dọn dẹp thằng Overlay trước, sau đó sẽ cho afterClosed$ emit data mà người dùng cần rồi hoàn tất. Ở cuối chuỗi sự kiện, chúng ta sẽ dọn dẹp luôn thằng componentInstance bằng cách gán null cho nó, vì chúng ta không cần nó nữa.

Các bạn lưu ý ở đây là RxJS là asynchronous (bất đồng bộ). Chúng ta chỉ mới thiết lập 2 Subscriptions mà thôi, code ở trong 2 Subscriptions này sẽ không được thực thi ngay lập tức khi hàm close() được gọi. Đây chỉ gọi là “khâu chuẩn bị” mà thôi.

Sau khi chuẩn bị xong các Subscriptions, thì chúng ta gọi componentInstance.startExitAnimation() để bắt đầu chuỗi sự kiện đóng Dialog. DynamicDialogRef đã hoàn tất. Bây giờ chúng ta sẽ quay lại DynamicDialogRootComponent để hoàn tất nó luôn.

Hoàn tất DynamicDialogRootComponent

Đầu tiên thì hãy thiết lập một số hàm mà sẽ gọi dynamicDialogRef.close() mặc định.

import { AnimationEvent } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { AnimationState } from './models/animation-state.enum'; // <-- import AnimationState
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

Chúng ta thêm vào 2 hàm mới

closeDialog(): Xử lý việc đóng Dialog khi backdrop hoặc close icon được click.
handleEscapeKey(): Xử lý đóng Dialog khi phím Escape được bấm bằng việc dùng HostListener lắng nghe sự kiện document:keydown.

Giờ thì chúng ta sẽ thêm animations vào cho DynamicDialogRootComponent

Mình sẽ dùng một gói npm tên là ng-animate để hỗ trợ khả năng animations dở ẹc của mình. Nếu các bạn muốn thì hãy cài ng-animate bằng lệnh npm i ng-animate

import { animateChild, AnimationEvent, group, query, transition, trigger, useAnimation } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { fadeIn, fadeOut, zoomIn, zoomOut } from 'ng-animate';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
    >
      <div class="modal-background"></div>
      <div class="modal-card">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
  animations: [
    trigger('zoom', [
      transition(
        '* => in',
        useAnimation(zoomIn, { params: { timing: '{{timing}}' } })
      ),
      transition(
        '* => out',
        useAnimation(zoomOut, { params: { timing: '{{timing}}' } })
      )
    ]),
    trigger('animation', [
      transition(
        `* => ${ AnimationState.Enter }`,
        group([
          useAnimation(fadeIn, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      ),
      transition(
        `* => ${ AnimationState.Leave }`,
        group([
          useAnimation(fadeOut, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      )
    ])
  ]
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

Ok, giờ giải thích mới dã man đây. Trước tiên thì mình xin gợi ý các bạn đọc thêm về Angular Animations để không hoang mang, vì mình giải thích animations không được tốt. Về căn bản, chúng ta thiết lập 2 animations: animation và zoom. zoom sẽ chịu trách nhiệm animating thằng Dialog Content trong khi animation sẽ chịu trách nhiệm cho thằng Dialog Container. Ở trong animation, chúng ta thiết lập fadeIn và fadeOut được dựng sẵn (từ ng-animate, nếu các bạn tự viết Animations thoải mái, thì cứ việc tự viết nhé) dựa vào state, chúng ta cũng sẽ dùng đến Animation Params (ví dụ: {{timing}}) để có thể truyền các tham số liên quan đến Animation vào trong các animations này. Các bạn có nhớ containerAnimationTiming với contentAnimationTiming không? Được dùng ở đây nè. Cuối cùng, chúng ta cũng thiết lập query cho zoom bên trong animation để chúng ta có thể chạy được animationChild với delay. Ví dụ muốn chạy animation cho container xong, đợi một chút rồi mới chạy animation của content?! Một lần nữa, mình tha thiết mong các bạn đọc qua Angular Animations.

Giờ thì hoàn tất thằng template để kết nối các hàm và animations vừa thiết lập xong

import { animateChild, AnimationEvent, group, query, transition, trigger, useAnimation } from '@angular/animations';
import { 
    AfterViewInit, 
    ChangeDetectionStrategy, 
    Component, 
    OnDestroy, 
    EventEmitter,
    Type,
    ComponentRef,
    ComponentFactoryResolver,
    ChangeDetectorRef,
    ViewChild,
    HostListener
} from '@angular/core';
import { fadeIn, fadeOut, zoomIn, zoomOut } from 'ng-animate';
import { AnimationState } from './models/animation-state.enum';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';

@Component({
  selector: 'app-dynamic-dialog-root',
  template: `
    <div
      class="modal is-active"
      style="padding-left: 1rem; padding-right: 1rem"
      [@animation]="{
        value: animationState,
        params: {
          timing: dialogConfig.containerAnimationTiming,
          delayChild: dialogConfig.animationChildDelay
        }
      }"
      (@animation.start)="animationStateChanged.emit($event)"
      (@animation.done)="animationStateChanged.emit($event)"
    >
      <div class="modal-background" (click)="closeDialog()"></div>
      <div
        class="modal-card"
        [@zoom]="{
          value: animationState == 'enter' ? 'in' : 'out',
          params: { timing: dialogConfig.contentAnimationTiming }
        }">
        <header class="modal-card-head">
          <p class="modal-card-title">{{ dialogConfig.header }}</p>
          <button
            class="delete"
            aria-label="close"
            *ngIf="dialogConfig.closable"
            (click)="closeDialog()"
          ></button>
        </header>
        <section class="modal-card-body">
          <ng-template appDynamicDialogContent></ng-template>
        </section>
      </div>
    </div>
`,
  changeDetection: ChangeDetectionStrategy.OnPush,
  animations: [
    trigger('zoom', [
      transition(
        '* => in',
        useAnimation(zoomIn, { params: { timing: '{{timing}}' } })
      ),
      transition(
        '* => out',
        useAnimation(zoomOut, { params: { timing: '{{timing}}' } })
      )
    ]),
    trigger('animation', [
      transition(
        `* => ${ AnimationState.Enter }`,
        group([
          useAnimation(fadeIn, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      ),
      transition(
        `* => ${ AnimationState.Leave }`,
        group([
          useAnimation(fadeOut, { params: { timing: '{{timing}}' } }),
          query('@zoom', [animateChild({ delay: '{{delayChild}}' })], { optional: true })
        ])
      )
    ])
  ]
})
export class DynamicDialogRootComponent implements AfterViewInit, OnDestroy {
    @ViewChild(DynamicDialogContentDirective, { static: false }) contentInsertionPoint: DynamicDialogContentDirective;

    animationState: AnimationState = AnimationState.Enter;
    animationStateChanged: EventEmitter<AnimationEvent> = new EventEmitter<AnimationEvent>();
    contentComponentType: Type<any>;
    
    private componentRef: ComponentRef<any>;

    constructor(
        public readonly dialogConfig: DynamicDialogConfig,
        private readonly dialogRef: DynamicDialogRef,
        private readonly cfr: ComponentFactoryResolver,
        private readonly cdr: ChangeDetectorRef
    ) {
    }

    ngAfterViewInit(): void {
        this.loadContentComponent();
        this.cdr.markForCheck();
    }

    ngOnDestroy(): void {
        if (this.componentRef) {
          this.componentRef.destroy();
        }
    }

    startExitAnimation(): void {
        this.animationState = AnimationState.Leave;
    }

    private loadContentComponent(): void {
        const factory = this.cfr.resolveComponentFactory(this.contentComponentType);
        const vcr = this.contentInsertionPoint.viewContainerRef;
        vcr.clear();
        this.componentRef = vcr.createComponent(factory);
    }

    closeDialog() {
        this.dialogRef.close();
    }

    @HostListener("document:keydown", ["$event.key"])
    private handleEscapeKey(key: string) {
        if (key === 'Escape') {
          this.closeDialog();
        }
    }
}

Chúng ta dùng animation trên phần tử DOM trên cùng, là cái modal. Và dùng zoom trên modal-card. Chúng ta cũng dùng đến dialogConfig để truyền tham số vào cho animations. Kế đến, chúng ta cài đặt hai sự kiện @animation.start và @animation.done rồi cho animationStateChanged emit. Giờ ngẫm một chút thì các bạn có thấy: startExitAnimation(), dynamicDialogRef.close() và animationStateChanged chạy theo một chuỗi như thế nào chưa? Cuối cùng thì chúng ta dùng closeDialog() trên modal-background và button.delete (close icon) là xong 🔥.

Đến đây thì xong khoản 60% rồi 😅. Hoàn tất 40% còn lại với DynamicDialogService thôi.

DynamicDialogService

Ngoài DynamicDialogRef, DynamicDialogService là mảng cuối cùng giúp cho người dùng có thể tương tác được với Dynamic Dialog. Mở file dynamic-dialog.service.ts rồi quẩy thôi. DynamicDialogService chỉ cung cấp một hàm duy nhất cho người dùng, đó là open<TReturnType = any>(), để người dùng có thể dùng hàm này để thực thi việc mở Dialog.

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
  }
}

Hãy import và inject mấy thứ mình cần trước. Sau đó, chúng ta sẽ khai báo private readonly defaultDialogConfig. Biến này sẽ giữ một số cấu hình mặc định cho Dialog. Chúng ta đã thiết lập một số cấu hình mặc định bên trong DynamicDialogConfig rồi. Ở đây, chúng ta sẽ thiết lập cấu hình mặc định cho OverlayConfig.

disposeOnNavigation: Đọc phát hiểu luôn. Chúng ta muốn đóng Dialog khi chúng ta chuyển sang một trang khác. Việc này giúp cho Dialog được dọn dẹp, phòng ngừa tràn bộ nhớ không cần thiết.
hasBackdrop: Cái này có thể thiết lập hoặc không. Ở đây thì mình sẽ thiết lập nó thành true. Nếu là true, thì Overlay sẽ cho hiển thị một element có class là cdk-backdrop cùng với cdk-overlay trên cây DOM.
panelClass: Class các bạn muốn Overlay có, để tinh chỉnh bằng CSS nếu muốn.
scrollStrategy: Dễ hiểu. Thiết lập tác vụ Scrolling khi Overlay được mở. Chúng ta sẽ mặc định nó về BlockScrollStrategy. Đọc thêm về ScrollStrategies
positionStrategy: Thiết lập vị trí của Overlay khi được mở. Mặc định về center. Đọc thêm về PositionStrategies

Kế tiếp, chúng ta khai báo hàm open(). open() nhận vào một Generic Type TReturnType. Chúng ta sẽ cần hàm open() trả về DynamicDialogRef<TReturnType> để dynamicDialogRef.afterClosed sẽ có được type chuẩn xác khi người dùng đăng ký vào nó. open() sẽ cần 2 tham số: Component để dùng cho Dialog Content (nhớ contentComponentType trên DynamicDialogRootComponent không?) và DynamicDialogConfig. Nếu cấu hình DynamicDialogConfig được truyền vào, thì cấu hình truyền vào này sẽ được gộp chung với defaultDialogConfig. Sau đó, chúng ta sẽ tạo OverlayRef nên quẩy hàm createOverlay() thôi

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }
}

Cực kỳ đơn giản luôn. Chỉ cần gọi overlay.create() và truyền vào OverlayConfig từ DynamicDialogConfig.overlayConfig thôi. Giờ có OverlayRef rồi, chúng ta có thể bắt đầu khởi tạo DynamicDialogRef

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
    const dialogRef = new DynamicDialogRef<TReturnType>(overlayRef);
    dialogRef.componentInstance = this.attachDialogContainer(overlayRef, component, dialogRef, mergeConfig);
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }
}

Các bạn nhớ componentInstance trên DynamicDialogRef có type là DynamicDialogRootComponent chứ? DynamicDialogRootComponent vẫn sẽ được khởi tạo động và đây chính là nới mà Overlay với Portal từ Angular CDK toả sáng. OverlayRef là một PortalOutlet mà bạn có thể dùng để attach một ComponentPortal để hiển thị động Component đó trên màn hình. Thông thường, các bạn có thể dùng tới Dynamic Component Loader để tạo động Component. Tuy nhiên, Overlay và Portal từ Angular CDK cung cấp APIs tốt hơn, dễ sử dụng hơn, dễ dọn dẹp hơn. Giờ thì chiến hàm attachDialogContainer thôi.

import { Overlay, OverlayConfig, OverlayRef } from '@angular/cdk/overlay';
import { ComponentPortal, PortalInjector } from '@angular/cdk/portal';
import { Injectable, Injector, Type } from '@angular/core';
import { DynamicDialogRef } from './dynamic-dialog-ref';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogConfig } from './models/dynamic-dialog-config.model';

@Injectable()
export class DynamicDialogService {

  private readonly defaultDialogConfig: DynamicDialogConfig;

  constructor(private readonly overlay: Overlay, private readonly injector: Injector) {
    this.defaultDialogConfig = new DynamicDialogConfig();
    this.defaultDialogConfig.overlayConfig = new OverlayConfig({
      disposeOnNavigation: true,
      hasBackdrop: true,
      panelClass: 'dynamic-dialog-panel',
      scrollStrategy: overlay.scrollStrategies.block(),
      positionStrategy: overlay.position().global().centerHorizontally().centerVertically()
    });
  }

  open<TReturnType = any>(component: Type<any>, config?: DynamicDialogConfig): DynamicDialogRef<TReturnType> {
    const mergeConfig = {
      ...this.defaultDialogConfig,
      ...config,
      overlayConfig: {
        ...this.defaultDialogConfig.overlayConfig,
        ...(config && config.overlayConfig ? config.overlayConfig : {})
      }
    };

    const overlayRef = this.createOverlay(mergeConfig);
    const dialogRef = new DynamicDialogRef<TReturnType>(overlayRef);
    dialogRef.componentInstance = this.attachDialogContainer(overlayRef, component, dialogRef, mergeConfig);
    return dialogRef;
  }

  private createOverlay(config: DynamicDialogConfig): OverlayRef {
    return this.overlay.create(config.overlayConfig);
  }

  private attachDialogContainer(overlayRef: OverlayRef, component: Type<any>, dialogRef: DynamicDialogRef, dialogConfig: DynamicDialogConfig): DynamicDialogRootComponent {
    const injector = this.createInjector(dialogRef, dialogConfig);
    const portal = new ComponentPortal(DynamicDialogRootComponent, null, injector);
    const ref = overlayRef.attach(portal);
    ref.instance.contentComponentType = component;
    return ref.instance;
  }

  private createInjector(ref: DynamicDialogRef, config: DynamicDialogConfig): PortalInjector {
    const injectorTokenMap = new WeakMap();
    injectorTokenMap.set(DynamicDialogRef, ref);
    injectorTokenMap.set(DynamicDialogConfig, config);
    return new PortalInjector(this.injector, injectorTokenMap);
  }
}

Điều đầu tiên cần làm là createInjector() cho Dialog vì chúng ta cần đem DynamicDialogRef và DynamicDialogConfig vào Dependency Injection trong instance của Overlay. Overlay instance này sẽ quản lý DynamicDialogRootComponent và Dialog Content Component cho nên nếu Overlay có truy xuất đến được DynamicDialogRef và DynamicDialogConfig, thì trong DynamicDialogRootComponent và Dialog Content Component cũng sẽ truy xuất được đến cùng ref và config này. Chúng ta sẽ dùng đến PortalInjector. PortalInjector sẽ nhập các InjectionToken trong WeakMap vào với parentInjector (là Injector mà chúng ta đã inject bên trong DynamicDialogService bên trên). Với PortalInjector sẵn sàng rồi, chúng ta có thể bắt đầu khởi tạo tiếp ComponentPortal với PortalInjector và DynamicDialogRootComponent. Giờ thì chỉ cần attach thằng ComponentPortal này lên OverlayRef thôi. Gọi hàm overlayRef.attach() để làm điều đó. Giá trị được trả về là một con trỏ dẫn đến DynamicDialogRootComponent. Đây chính là nơi mà mình gán giá trị cho contentComponentType bằng tham số component được truyền vào cho hàm open(). Cuối cùng, chúng ta sẽ trả về giá trị ref.instance, chính là con trỏ đến DynamicDialogRootComponent đang được quản lý bởi Overlay. Sau đó, mình sẽ trả về giá trị dialogRef cho hàm open(). Khi người dùng dùng hàm open() để mở một Dialog nào đó, họ sẽ được trả về con trỏ của DynamicDialogRef đó. Với DynamicDialogRef, họ có thể lắng nghe vào sự kiện afterClosed và nhận data để thực hiện tiếp logic của ứng dụng.

DynamicDialogModule

Tất cả các mảnh ghép của Dynamic Dialog đã hoàn tất rồi. Tuy nhiên, chúng ta cần phải quăng tất cả vào DynamicDialogModule thì mới dùng được. Mở file dynamic-dialog.module.ts

import { OverlayModule } from '@angular/cdk/overlay';
import { CommonModule } from '@angular/common';
import { NgModule } from '@angular/core';
import { DynamicDialogContentDirective } from './dynamic-dialog-content.directive';
import { DynamicDialogRootComponent } from './dynamic-dialog-root.component';
import { DynamicDialogService } from './dynamic-dialog.service';


@NgModule({
  declarations: [DynamicDialogContentDirective, DynamicDialogRootComponent],
  imports: [CommonModule, OverlayModule], // <-- import OverlayModule
  entryComponents: [DynamicDialogRootComponent], // <-- thêm DynamicDialogRootComponent vào entryComponents. Chắc chắn rằng DynamicDialogRootComponent cũng được đặt vào declarations nhé.
  providers: [DynamicDialogService] // provide DynamicDialogService
})
export class DynamicDialogModule {
}

Cách dùng

Trước khi dùng được Dialog, hãy tạo một Component đơn giản để làm Dialog Content. Chạy lệnh sau

# assume you are at the root level of the project (cdk-bulma-dialog)
# mặc định là bạn đang ở root của dự án (cdk-bulma-dialog)
ng generate component test-dialog 
--skipTests 
--inlineTemplate 
--inlineStyle 
--changeDetection=OnPush
--entryComponent

Chúng ta dùng CLI để khởi tạo Component với inlineTemplate, inlineStyle, skipTests, changeDetection=OnPush, và entryComponent. Component này sẽ cực kì đơn giản nên mình sẽ gom tất cả vào 1 file *.component.ts. entryComponent sẽ đặt Component này vào entryComponents trên AppModule luôn. Giờ thì mở file test-dialog.component.ts và quẩy thôi

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

@Component({
  selector: 'app-test-dialog',
    template: `
        <p>test-dialog works!</p>
        <button class="button" (click)="close()">Close</button>
    `,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class TestDialogComponent implements OnInit {

  constructor(
        private readonly dialogConfig: DynamicDialogConfig, 
        private readonly dialogRef: DynamicDialogRef<string>
    ) {}

  ngOnInit() {
  }

  close() {
    this.dialogRef.close('closed from inside content dialog');
  }
}

Chúng ta chỉ thêm một button với (click) được gán cho hàm close(). Chúng ta cũng inject DynamicDialogConfig và DynamicDialogRef<string> để kiểm tra xem PortalInjector có hoạt động hay không. Ở trong hàm close(), chúng ta gọi dialogRef.close() và truyền vào một chuỗi 'closed from inside content dialog'. Giờ thì mở app.component.html và thêm vào dòng code sau

<button class="button" (click)="showOverlay()">Show Overlay</button>

rồi mở file app.component.ts

import { Component } from '@angular/core';
import { DynamicDialogService } from './dynamic-dialog/dynamic-dialog.service';
import { DynamicDialogConfig } from './dynamic-dialog/models/dynamic-dialog-config.model';
import { TestDialogComponent } from './test-dialog/test-dialog.component';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  constructor(private readonly dynamicDialogService: DynamicDialogService) {
  }

  showOverlay() {
    const config = new DynamicDialogConfig();
    config.header = TestDialogComponent.name;
    const ref = this.dynamicDialogService.open<string>(TestDialogComponent, config);
    ref.afterClosed.subscribe(data => {
      console.log('closed with data', data);
    });
  }
}

Inject DynamicDialogService và triển hàm showOverlay():

Khởi tạo một instance DynamicDialogConfig mới, gán chuối 'TestDialogComponent' vào header.
Gọi hàm dynamicDialogService.open(), với TestDialogComponent và config là tham số, sau đó gán giá trị được trả về cho biến nội bộ ref.
Lắng nghe vào sự kiện ref.afterClosed và log data được truyền ra từ bên trong hàm TestDialogComponent.close().

Mở file app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations'; // <-- add this import
import { AppComponent } from './app.component';
import { DynamicDialogModule } from './dynamic-dialog/dynamic-dialog.module';
import { TestDialogComponent } from './test-dialog/test-dialog.component';

@NgModule({
  declarations: [AppComponent, TestDialogComponent],
  imports: [BrowserModule, BrowserAnimationsModule, DynamicDialogModule],
  bootstrap: [AppComponent],
  entryComponents: [TestDialogComponent]
})
export class AppModule {
}

Bảo đảm là bạn có TestDialogComponent trong entryComponents và DynamicDialogModule trong imports. Ok, giờ thì mọi thứ sẵn sàng rồi. Khoảnh khắc sự thật là đây! Chạy ứng dụng thôi

ng serve -o

Bạn sẽ thấy được cái nút như sau trên màn hình

Lonely Show Overlay button

Click vào Show Overlay sẽ mở TestDialogComponent với backdrop màu xám đậm.

Tada!

Mở Console lên, rồi click vào Close, các bạn sẽ thấy

closed with data closed from inside content dialog

được log ra Console. 👍

Recap

Để điểm lại, mình có vẽ một cái diagram gớm ghiếc này

…😢

Ở một góc nhìn toàn diện, sau đây là mọi thứ diễn ra khi bạn gọi hàm dynamicDialogService.open(). Overlay instance sẽ được khởi tạo để quản lý OverlayRef. OverlayRef xử lý PortalOutlet và trên PortalOutlet, chúng ta hiển thị DynamicDialogRootComponent thông qua ComponentPortal. Sau đó, chúng ta có thiết lập PortalInjector để inject những instances hiện tại của DynamicDialogRef và DynamicDialogConfig. 2 thằng này sau khi được PortalInjector inject thì sẽ có thể được truy xuất tới trong Dialog Content Component (là TestDialogComponent trong ví dụ). Tất cả mọi thứ chỉ có vậy thôi. Overlay và Portal là hai công cụ cực kỳ ngon mà Angular CDK cung cấp cho các bạn tạo điều kiện cho developers có thể xây dựng những components chất lượng như Dynamic Dialog. Với kiến thức tương tự, các bạn có thể áp dụng Overlay và Portal để xây dựng những components tương tự khác như: Tooltip, Drawer, Toast etc… 💪

Kết bài, mình hy vọng là đã chia sẻ được cái gì đó và các bạn đã học thêm được cái gì đó qua bài blog dài ngoằng này 🚀. Have fun và good luck nhé. Hẹn gặp lại các bạn trong bài blog kế tiếp 👋

Reference

Customize UI Library in Angular

Wed, 01 Jan 2020 00:00:00 GMT

Happy New Year everyone 🎇! I hope everyone will have a prosperous new year ahead of you all. As for me, I want to kick off 2020 with a new blog post, to stay productive you know 💪. So what are we going to do today? We are going to look at how we can customize 3rd party library (if applicable 🤞) in an Angular application.

The Problem

As Web Technologies improve, there are a lot of 3rd-party UI libraries out there that we, Web Developers, can utilize without reinventing the wheels from scratch (Sometimes, building from scratch makes sense for your case/company/team 😊). However, these 3rd-party libraries are most of the times, opinionated, and a particular one library will never be able to fulfill all of your project’s needs. That’s why “sometimes, building from scratch makes sense”.

Inexperienced developers or teams will tend to pull in many different libraries to have coverage of their usages. For example, they might pull in library-A for DataTable usage but library-A’s Tooltip does not cut it so they pull in library-B for library-B’s Tooltip. Although, this will make your team get a feature out quickly enough and make customers happy but overall, this is a bad practice. Not only that you have increased the application’s bundle-size with multiple libraries but you also increase the tech-debt with two external libraries to keep track off and keep up-to-date.

Now, I am talking about Open Source Software (OSS) that are free to use provided to developers by other developers. Usually, paid counterpart provides supports that might be able to help you with your missing feature. However, that is not always the case with OSS. Normally, you would probably follow these steps:

Google a solution regarding the usage you want with the library you use. Sometimes, this will lead you to the library’s Github Issues where it’s most likely that someone else has already had the same issue as yours
File an issue/feature request on the library’s Github
Wait for something to happen to your issue/feature request.

Some people will just stop there, and wait ⏱. But, there is a couple of additional steps that you might want to look at:

Look at the library’s source code
Customize it

Most UI libraries are just JavaScript so most likely, you’ll be able to customize it no problem. The hard part is to conform with whatever framework you’re using for your project. In this blog, I will be going over a use-case with PrimeNG’s TooltipModule.

Use-case

What is PrimeNG? PrimeNG is a 3rd-party UI Component Suite for Angular. It is pretty complete in my opinion. But of course, nothing is perfect. One particular case that we run into for our project is their TooltipModule is not mobile-friendly. In other words, the Tooltip does not play well with mobile viewports as it does not support click triggering.

TooltipModule is not mobile friendly

What can you do? Well, NgBootstrap TooltipModule does have click triggering which you can always pull in your project and use NgBootstrap just for their Tooltip. Or, you can go to PrimeNG Github and submit a feature request for TooltipModule to support click triggering, which I think that’s the way it should be.

While you wait

Your feature request probably takes a while for it to be looked at, let alone worked on. In the mean time, we can utilize step 4 and step 5 above.

Let’s get started with reading PrimeNG source code on how they implement their Tooltip at tooltip.ts. Let’s walk over the Tooltip:

@Directive({
    selector: '[pTooltip]'
})
export class Tooltip implements AfterViewInit, OnDestroy {
  // ...
}

We can tell right away that Tooltip is a Directive. It implements AfterViewInit and OnDestroy. Let’s see what PrimeNG does in ngAfterViewInit and let me highlight the important pieces for you

ngAfterViewInit() {
    this.zone.runOutsideAngular(() => {        if (this.tooltipEvent === 'hover') {            this.mouseEnterListener = this.onMouseEnter.bind(this);            this.mouseLeaveListener = this.onMouseLeave.bind(this);            this.clickListener = this.onClick.bind(this);            this.el.nativeElement.addEventListener('mouseenter', this.mouseEnterListener);            this.el.nativeElement.addEventListener('mouseleave', this.mouseLeaveListener);            this.el.nativeElement.addEventListener('click', this.clickListener);        }        else if (this.tooltipEvent === 'focus') {
            this.focusListener = this.onFocus.bind(this);
            this.blurListener = this.onBlur.bind(this);
            this.el.nativeElement.addEventListener('focus', this.focusListener);
            this.el.nativeElement.addEventListener('blur', this.blurListener);
        }
    });
}

Let’s see:

They run some code outside of Angular Change Detection with runOutsideAngular() provided by NgZone. NgZone is another complex topic that you can read more about at Do You Still Think That Ngzone Zone Js Is Required For Change Detection In Angular? and/or Boosting Performance Of Angular Applications With Manual Change Detection.
If the tooltipEvent is hover, then they bind some mouseEnter and mouseLeave events which makes total sense.

Next, let’s look at onMouseEnter, onMouseLeave and onClick that PrimeNG uses to bind to the events.

onMouseEnter(e: Event) {
    if (!this.container && !this.showTimeout) {
        this.activate();
    }
}

onMouseLeave(e: Event) {
    this.deactivate();
}

onClick(e: Event) {
    this.deactivate();
}

this.container and this.showTimeout are just extra information. What we need to focus on is: activate() and deactivate() methods. We can kind of tell that activate() will show the tooltip and vice versa for deactivate(). Let’s take a look

activate() {
    this.active = true;
    this.clearHideTimeout();

    if (this.showDelay)
        this.showTimeout = setTimeout(() => { this.show() }, this.showDelay);
    else
        this.show();

    if (this.life) {
        let duration = this.showDelay ? this.life + this.showDelay : this.life;
        this.hideTimeout = setTimeout(() => { this.hide() }, duration);
    }
}

deactivate() {
    this.active = false;
    this.clearShowTimeout();

    if (this.hideDelay) {
        this.clearHideTimeout();
        this.hideTimeout = setTimeout(() => { this.hide() }, this.hideDelay);
    }
    else {
        this.hide();
    }
}

It’s clear to see that upon calling activate(), PrimeNG sets active flag to true and have extra logic around its properties to determine how to display the tooltip, vice versa with deactivate(). Up to now, we probably have enough background of how TooltipModule works in PrimeNG. Now on to customizing it.

The Solution

The first step is to run through what we need to do: (rationale)

We still want to have the Tooltip behave with the default hover trigger so we’ll leave: tooltipEvent, onMouseEnter and onMouseLeave as is.
We need to attach an event that we can use on mobile viewports.
We will need to leverage activate() and deactivate() methods for step 2 to work.
We will also need to handle some kind of click outside so we can deactivate() the Tooltip on mobile viewports.

Let’s start, shall we?

First step is to just initialize yourself an Angular application with PrimeNG setup. For the purpose of this demo, let’s use ButtonModule and TooltipModule from PrimeNG

After all that, let’s open up app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ButtonModule } from 'primeng/button';import { TooltipModule } from 'primeng/tooltip';
import { AppComponent } from './app.component';

@NgModule({
  imports: [BrowserModule, ButtonModule, TooltipModule],  declarations: [AppComponent],
  bootstrap: [AppComponent]
})
export class AppModule {}

In app.component.html, let’s remove everything and add the following:

<p-button label="PrimeNG Button" pTooltip="I am a not so mobile friendly tooltip"></p-button>

Run the application with ng serve, you should see a PrimeNG Button on the screen, and the tooltip when you hover over the button as well (just like the demo up there). Now, let’s create a Directive. I am going to create it manually, although you can use Angular CLI to generate a Directive with the following command.

ng g directive tooltip-click --skipTests

Open up tooltip-click.directive.ts

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

@Directive({
  selector: '[pTooltip][clickTrigger]' // change the selector})
export class TooltipClickDirective {}

First thing to do is to change the selector to [pTooltip][clickTrigger]. [pTooltip] part lets us patch TooltipClickDirective on top of PrimeNG’s one. [clickTrigger] is arbitrary but you need to make sure you pick an attribute name that is unique enough. So, with [pTooltip][clickTrigger], our TooltipClickDirective will be initialized with:

<p-button label="PrimeNG Button" pTooltip="..." clickTrigger></p-button>

Remember what PrimeNG’s Tooltip implements? AfterViewInit and OnDestroy right? And we’re going to do the same for TooltipClickDirective

import { Directive, AfterViewInit, OnDestroy } from '@angular/core';

@Directive({
  selector: '[pTooltip][clickTrigger]'
})
export class TooltipClickDirective implements AfterViewInit, OnDestroy {
  
  ngAfterViewInit() {
    
  }
  
  ngOnDestroy() {
    
  }
}

We didn’t really go over PrimeNG’s Tooltip ngOnDestroy but essentially, they unbind the events that they bind in ngAfterViewInit.

We’re going to inject a couple of things in our Directive constructor

import { Directive, AfterViewInit, OnDestroy, NgZone } from '@angular/core';import { Tooltip } from 'primeng/tooltip';
@Directive({
  selector: '[pTooltip][clickTrigger]'
})
export class TooltipClickDirective implements AfterViewInit, OnDestroy {
 
  constructor(private readonly tooltip: Tooltip, private readonly ngZone: NgZone) {}  
  ngAfterViewInit() {
    
  }
  
  ngOnDestroy() {
    
  }
}

Again, remember PrimeNG uses NgZone to run some event bindings outside of Angular with runOutsideAngular. We are going to do the same here. And Tooltip will give us the instance of the PrimeNG’s Tooltip in our Directive.

In your Directive, you can use Dependency Injection (DI) to inject a couple of very useful things like ElementRef (the actual DOM element), NgControl (the FormControl that the Directive is used on) etc… and also the Component Instance (like Tooltip instance that we’re utilizing here)

We are going to take care of a couple of low-hanging fruits next, namely: toggleTooltip() method, click-outside event and a small setup in ngAfterViewInit()

import { Directive, AfterViewInit, OnDestroy, NgZone } from '@angular/core';
import { Tooltip } from 'primeng/tooltip';

@Directive({
  selector: '[pTooltip][clickTrigger]'
})
export class TooltipClickDirective implements AfterViewInit, OnDestroy {
 
  constructor(private readonly tooltip: Tooltip, private readonly ngZone: NgZone) {}
  
  ngAfterViewInit() {
    this.ngZone.runOutsideAngular(() => {      if (this.tooltip.clickListener) {        this.tooltip.el.nativeElement.removeEventListener('click', this.tooltip.clickListener);      }    });  }
  
  ngOnDestroy() {
    
  }
  
  @HostListener('document:click', ['$event.target'])  onClickOutside(target: Node) {    if (!this.tooltip.el.nativeElement.contains(target) && this.tooltip.active) {      this.tooltip.deactivate();    }  }  
  private toggleTooltip() {    if (this.tooltip.active) {      this.tooltip.deactivate();    } else {      this.tooltip.activate();    }  }}

Let’s go through each block, from bottom to top

toggleTooltip(): This is very straight-forward. We check if the Tooltip instance is active, if yes, we deactivate() it, else, we activate() it.
HostListener(): This is our click-outside piece. It listens to click on the Document and will check if the EventTarget is the Tooltip’s nativeElement which is whatever element we use our Directive on, if yes and if the Tooltip is active, we deactivate() it, else, we do nothing. This HostListener will get unbound when the Directive is destroyed.
runOutsideAngular(): You might be wondering why do we need to check for the instance’s clickListener and remove it. Remember what onClick does in PrimeNG’s Tooltip? It calls deactivate() but we really need a click event to toggleTooltip() instead of just deactivate() it. That’s why we’re removing the clickListener and attaching a new event of our own.

Now, you might be jumping to conclusion that “We’re going to use HostListener to listen to the click event then handle it”. Well, you might be right but you’ll soon find out that it’s not going to work. A click event will also trigger mouseenter event which in our case, we still need the hover effect on large viewports so the mouseenter event is still there in the original Tooltip instance. You should be curious to try but to save time, I’m going to let you know what happen: It will take two clicks to display the tooltip instead of one. Why? Because the original Tooltip.onMouseEnter() will call activate() and remember what activate() does? It sets Tooltip.active to true which will conflict with out toggleTooltip() method which we check for Tooltip.active to display the Tooltip. Right? So we need to find another way.

One thing that comes to my mind, for my use-case, is the following question: “What really is a click on mobile devices?” And you know, a click on mobile devices is actually a press, or more accurately, a tap. I bet most of you have heard of hammerjs if you have ever used Angular Material. HammerJS is a JavaScript library that adds Touch gestures to your webapp and that sounds exactly like what we need, a tap gesture. Let’s go ahead and install hammerjs if you haven’t already.

yarn add hammerjs
yarn add -D @types/hammerjs

I know I lied about pulling libraries. At the time, our project has hammerjs installed as well as most of our other web projects. hammerjs is always there. So, let’s move on.

HammerJS has an event that we’re interested in: singletap so let’s start wiring it up

import 'hammerjs';import { Directive, AfterViewInit, OnDestroy, NgZone } from '@angular/core';
import { Tooltip } from 'primeng/tooltip';

@Directive({
  selector: '[pTooltip][clickTrigger]'
})
export class TooltipClickDirective implements AfterViewInit, OnDestroy {
  
  private hammerManager: HammerManager; 
  constructor(private readonly tooltip: Tooltip, private readonly ngZone: NgZone) {}
  
  ngAfterViewInit() {
    this.ngZone.runOutsideAngular(() => {
      if (this.tooltip.clickListener) {
        this.tooltip.el.nativeElement.removeEventListener('click', this.tooltip.clickListener);
      }
      this.hammerManager = new Hammer.Manager(this.tooltip.el.nativeElement);      this.hammerManager.add(new Hammer.Tap({ event: 'singletap' }));      this.hammerManager.on('singletap', this.toggleTooltip.bind(this));    });
  }
  
  ngOnDestroy() {
    this.ngZone.runOutsideAngular(() => {      if (this.hammerManager.get('singletap')) {        this.hammerManager.off('singletap', this.toggleTooltip.bind(this));      }    });  }
  
  @HostListener('document:click', ['$event.target'])
  onClickOutside(target: Node) {
    if (!this.tooltip.el.nativeElement.contains(target) && this.tooltip.active) {
      this.tooltip.deactivate();
    }
  }
  
  private toggleTooltip() {
    if (this.tooltip.active) {
      this.tooltip.deactivate();
    } else {
      this.tooltip.activate();
    }
  }
}

import 'hammerjs'; at the top of our tooltip-click.directive.ts
HammerJS needs a HammerManager instance to start managing touch gestures. We create our Hammer.Manager and pass in the DOM element, add a singletap event and listen to that event with toggleTooltip() bound to singletap event.
We clean up our singletap in ngOnDestroy

Now, we no longer trigger onMouseEnter with our singletap which makes it work pretty well on mobile friendly. Let’s go ahead and try it on our p-button in app.component.html:

<p-button label="PrimeNG Button" pTooltip="I am a mobile friendly tooltip. Try on mobile screen and click me" clickTrigger></p-button>

Go ahead and have your application refreshed, turn on responsive mode and check the Tooltip is working perfectly on mobile viewports.

Tooltip now works on mobile viewports

Recap

I hope you can learn something from this blog post. We’ve done hell of a lot of things in this post. We read the source code of a 3rd party library, learn about HammerJS, and most importantly, learn about how to use Directive to override/customize functionalities of a 3rd-party Component. I also hope you can pick up a couple of tricks here and there from the blog post. Even though in my use-case, I only demonstrate on PrimeNG ’s TooltipModule but the same concept can be applied to any 3rd-party UI Library which is open-source. Oh come on, hammerjs does not count 😢. Again, I wish you a Happy New Year. Thank you for reading 🚀. You can find the full code at Stackblitz

NestJS + Typegoose

Tue, 10 Dec 2019 00:00:00 GMT

Today, I am going to share with you a workflow/technique (whatever you want to call it 🗿) that I’ve been using when I work with NestJS and MongoDB. This workflow leverages the power of TypeScript and an npm package called Typegoose. This blog will be a quick one so let’s jump in.

I’d assume you’re already familiar with NestJS and MongoDB (Mongoose ODM to be exact)

Start off by initializing a new NestJS application with @nestjs/cli

nest new nest-typegoose
cd nest-typegoose

Then, delete app.controller.ts and app.service.ts. Modify your app.module.ts:

import { Module } from '@nestjs/common';
- import { AppController } from './app.controller';
- import { AppService } from './app.service';

@Module({
  imports: [],
-  controllers: [AppController],
-  providers: [AppService],
})
export class AppModule {}

Next, let’s install our dependencies

yarn add @nestjs/mongoose mongoose @typegoose/typegoose
yarn add --dev @types/mongoose

Alright, let’s get started. First thing first, let’s wire up our Mongo connection using nestjs/mongoose. Open up app.module.ts

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';

@Module({
  imports: [
    MongooseModule.forRoot('mongodb://localhost:27017/nestjs-typegoose', {      useNewUrlParser: true,      useUnifiedTopology: true,    }),
  ],
})
export class AppModule {}

Again, I assume you’re familiar with MongoDB and are able to spin up an instance of MongoDB running locally either installing MongoDB on your machine or using Docker. I’d recommend the latter.

Now, you can try running your server:

yarn start:dev

you should see the following:

10:14:05 PM - File change detected. Starting incremental compilation...


10:14:05 PM - Found 0 errors. Watching for file changes.
[Nest] 16093   - 12/10/2019, 10:14:05 PM   [NestFactory] Starting Nest application...
[Nest] 16093   - 12/10/2019, 10:14:06 PM   [InstanceLoader] AppModule dependencies initialized +23ms
[Nest] 16093   - 12/10/2019, 10:14:06 PM   [InstanceLoader] MongooseModule dependencies initialized +0ms
[Nest] 16093   - 12/10/2019, 10:14:06 PM   [InstanceLoader] MongooseCoreModule dependencies initialized +15ms
[Nest] 16093   - 12/10/2019, 10:14:06 PM   [NestApplication] Nest application successfully started +7ms

Let’s create a couple of files:

mkdir src/shared # I like to have a "shared" directory. You can name it whatever you like
touch src/shared/base.model.ts # a base model file
touch src/shared/base.service.ts # a base service file. I'll explain more about this in a bit

Open up the base.model.ts then put in the following:

import { Schema } from 'mongoose';
import { buildSchema, prop } from '@typegoose/typegoose';

export abstract class BaseModel {
  @prop()
  createdDate?: Date; // provided by timestamps
  @prop()
  updatedDate?: Date; // provided by timestamps
  id?: string; // is actually model._id getter
  // add more to a base model if you want.

  static get schema(): Schema {
    return buildSchema(this as any, {
      timestamps: true,
      toJSON: {
        getters: true,
        virtuals: true,
      },
    });
  }

  static get modelName(): string {
    return this.name;
  }
}

Let’s go through the code to understand it:

Create an abstract class so it cannot be initialized (new() up) accidentally. abstract also annotates that this class is only meant to be extended.
createdDate, updatedDate and id are the three fields that ALL of my Domain Models (or Data Model or Mongo Model, it’s up to you) will have. createdDate and updatedDate are provided automatically if you turn timestamps to true. id is actually a getter of _id so it’s always there, but to be able to grab id when paired with .lean() or .toJSON(), you need to set the toJSON: {...} option as shown.
@prop() annotates the field that it’s part of the schema. Learn more at typegoose
static get schema(). The magic is here. With the latest release, typegoose actually makes their API more Functional in a way that they expose functions like getModelForClass() and buildSchema() separately instead of having them as static functions on the Typegoose class which makes this technique/pattern/workflow possible. Why do we need buildSchema()? Well, MongooseModule from nestjs/mongoose requires two things to create a certain MongooseModel for you: Schema and name. buildSchema() will help us get the Schema, the name can be anything. How it works is we call buildSchema() and pass in this. this in this case, inside of a static method, is the actual class itself which invokes schema getter, making it possible to put get schema() on the abstract class so we can DRY up a bit here. Before, we need to write methods to grab schema and modelName for each Domain Model class which is kinda boiler-platey
static get modelName(). Pretty simple here. We just return this.name and this, again in the context of a static method, points to the actual class so this.name returns the class name. However, if you’re skeptical, you might want to return something else or just have a function that will do some magic to return some meaningful name for your MongooseModel. I tend to return this.name here because I use this.name on couple more places like Swagger UI to annotate the Tags.

Now we have our BaseModel, let’s take care of BaseService. Open base.service.ts and paste in the following code (or you can type if you like). But before showing the code, I’d like to explain a bit.

Why BaseService? I used to be a fan of Repository Pattern and base.service.ts would have been base.repository.ts if I was still a fan. Don’t get me wrong, I still like the pattern. However, working with an ODM like mongoose, I feel like the MongooseModel kind of acts like a Repository already. Hence, I tend to get rid of the Repository Layer to decrease the amount of abstractions I have throughout the application. Again, it depends on the characteristics of the application’s requirements. I just want to get my point across and want to explain why I do things the way I do things. Now that we’re clear on this, let’s move on:

import { InternalServerErrorException } from '@nestjs/common';
import { DocumentType, ReturnModelType } from '@typegoose/typegoose';
import { AnyParamConstructor } from '@typegoose/typegoose/lib/types';
import { MongoError } from 'mongodb';
import { DocumentQuery, Types, Query } from 'mongoose';
import { BaseModel } from './base.model';

type QueryList<T extends BaseModel> = DocumentQuery<
  Array<DocumentType<T>>,
  DocumentType<T>
>;
type QueryItem<T extends BaseModel> = DocumentQuery<
  DocumentType<T>,
  DocumentType<T>
>;

export abstract class BaseService<T extends BaseModel> {
  protected model: ReturnModelType<AnyParamConstructor<T>>;

  protected constructor(model: ReturnModelType<AnyParamConstructor<T>>) {
    this.model = model;
  }

  protected static throwMongoError(err: MongoError): void {
    throw new InternalServerErrorException(err, err.errmsg);
  }

  protected static toObjectId(id: string): Types.ObjectId {
    try {
      return Types.ObjectId(id);
    } catch (e) {
      this.throwMongoError(e);
    }
  }

  createModel(doc?: Partial<T>): T {
    return new this.model(doc);
  }

  findAll(filter = {}): QueryList<T> {
    return this.model.find(filter);
  }

  async findAllAsync(filter = {}): Promise<Array<DocumentType<T>>> {
    try {
      return await this.findAll(filter).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  findOne(filter = {}): QueryItem<T> {
    return this.model.findOne(filter);
  }

  async findOneAsync(filter = {}): Promise<DocumentType<T>> {
    try {
      return await this.findOne(filter).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  findById(id: string): QueryItem<T> {
    return this.model.findById(BaseService.toObjectId(id));
  }

  async findByIdAsync(id: string): Promise<DocumentType<T>> {
    try {
      return await this.findById(id).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  async create(item: T): Promise<DocumentType<T>> {
    try {
      return await this.model.create(item);
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  delete(filter = {}): QueryItem<T> {
    return this.model.findOneAndDelete(filter);
  }

  async deleteAsync(filter = {}): Promise<DocumentType<T>> {
    try {
      return await this.delete(filter).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  deleteById(id: string): QueryItem<T> {
    return this.model.findByIdAndDelete(BaseService.toObjectId(id));
  }

  async deleteByIdAsync(id: string): Promise<DocumentType<T>> {
    try {
      return await this.deleteById(id).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  update(item: T): QueryItem<T> {
    return this.model.findByIdAndUpdate(BaseService.toObjectId(item.id), item, {
      new: true,
    });
  }

  async updateAsync(item: T): Promise<DocumentType<T>> {
    try {
      return await this.update(item).exec();
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }

  count(filter = {}): Query<number> {
    return this.model.count(filter);
  }

  async countAsync(filter = {}): Promise<number> {
    try {
      return await this.count(filter);
    } catch (e) {
      BaseService.throwMongoError(e);
    }
  }
}

Whew, I know it’s a lot of code. But what did we do here?

Again, another abstract class to make sure we do not new() this one up accidentally. This takes in a Type Parameter T extends BaseModel. This is where TypeScript comes in with its Advanced Types. Here, we explicitly say T extends BaseModel so that we can only pass actual Domain Model classes to this BaseService, just another safety thing that you could get with TypeScript to prevent passing ANY as the Type Parameter.
Declare a protected field called model with the type of ReturnModelType<AnyParamConstructor<T>>. Wow, such a mouthful. What ReturnModelType<AnyParamConstructor<T>> really is is just the type that mongoose.model() will return. Wait, isn’t there Model<T>?, yes there is. But Model<T> expects T to be an interface that extends mongoose.Document. With typegoose, everything is class here so we can’t really utilize the simpler way with Model<T>. Another notion is making the model protected means only the sub-class can have access to this field so we don’t expose someService.model in any other layers of the application (like the Controller Layer)
Setup a protected constructor. Pretty straight forward here.
Setup a plethora of methods that wrap around mongoose.Model’s methods and return appropriate types. You’ve probably already noticed that we have two versions for each method. The first version returns a DocumentQuery which allows you to chain methods to further: filter, project, and some other stuffs like populate or lean. The 2nd version (async version) helps with situations where you don’t care about any other chainable methods and just want to grab the data quickly. The async version will also have error handler where we throw an InternalServerErrorException with the MongoError. I will go back to this in the bonus section.

You can abstract more methods if you want to but for me, these work for most cases.

Now that we have a BaseModel and a BaseService both of which we can use to extend our Domain Model classes and respective Services. Let’s try creating one real quick here:

nest generate module product
nest generate service product --no-spec
nest generate controller product --no-spec

touch src/product/product.model.ts

Open product.model.ts and paste/type in the following:

import { prop } from '@typegoose/typegoose';
import { BaseModel } from '../shared/base.model';

export class Product extends BaseModel {
  @prop()
  name: string;
  @prop()
  description: string;
  @prop()
  price: number;
}

We extend BaseModel and define 3 fields on our Product. These are arbitrary. Next, open product.module.ts:

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { ProductController } from './product.controller';
import { Product } from './product.model';
import { ProductService } from './product.service';

@Module({
  imports: [    MongooseModule.forFeature([      { name: Product.modelName, schema: Product.schema },    ]),  ],  providers: [ProductService],
  controllers: [ProductController],
})
export class ProductModule {}

The important piece here is we call MongooseModule.forFeature and pass in an array of models. MongooseModule.forFeature will grab the current mongoose.Connection and add the models passed in then provide those models in NestJS’s IoC Container (for Dependency Injection). Now you can see that the schema and modelName are important and the BaseModel helps quite a bit here.

Next, let’s open product.service.ts and type the following:

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { ReturnModelType } from '@typegoose/typegoose/lib/types';
import { BaseService } from '../shared/base.service';
import { Product } from './product.model';

@Injectable()
export class ProductService extends BaseService<Product> {
  constructor(
    @InjectModel(Product.modelName)
    private readonly productModel: ReturnModelType<typeof Product>,
  ) {
    super(productModel);
  }
}

And that’s it. See why I bolded type. With the BaseService all setup, your ProductService now has all the methods available to use. However, most of the cases you would need to add additional methods that are a bit more specialized for specific business logic.

Finally, let’s just inject ProductService in product.controller.ts and start hacking:

import { Controller } from '@nestjs/common';
import { ProductService } from './product.service';

@Controller('product')
export class ProductController {
  constructor(private readonly productService: ProductService) {}
}

Even though this is a really minimal example but I hope it shows you how to utilize TypeScript and Typegoose to abstract some base to speed up your development processes. Moreover, you can even have a BaseController that will have a protected baseService that will cover your basic CRUD functionalities. That’s it for me today, guys. Have fun and good luck 🍀

Bonus

Remember the throwMongoError piece? Now I will show you how you can have a more uniformed way of handling HttpException (InternalServerErrorException is an instance of HttpException) using NestJS Exception Filters. Let’s get started, shall we?

mkdir src/shared/filters
touch src/shared/filters/http-exception.filter.ts
touch src/shared/api-exception.model.ts

Open api-exception.model.ts:

import { HttpStatus } from '@nestjs/common';

export class ApiException {
  statusCode?: number;
  message?: string;
  status?: string;
  error?: string;
  errors?: any;
  timestamp?: string;
  path?: string;
  stack?: string;

  constructor(
    message: string,
    error: string,
    stack: string,
    errors: any,
    path: string,
    statusCode: number,
  ) {
    this.message = message;
    this.error = error;
    this.stack = stack;
    this.errors = errors;
    this.path = path;
    this.timestamp = new Date().toISOString();
    this.statusCode = statusCode;
    this.status = HttpStatus[statusCode];
  }
}

We create an ApiException class (you can call it whatever you want) to model our API Error. Self-explanatory, right?

Then open http-exception.filter.ts:

import {
  ArgumentsHost,
  Catch,
  ExceptionFilter,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { Response } from 'express';
import { ApiException } from '../api-exception.model';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(error: any, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse() as Response;
    const req = ctx.getRequest();
    const statusCode = error.getStatus();
    const stacktrace = error.stack;
    const errorName = error.response.name || error.response.error || error.name;
    const errors = error.response.errors || null;
    const path = req ? req.url : null;

    if (statusCode === HttpStatus.UNAUTHORIZED) {
      if (typeof error.response !== 'string') {
        error.response.message =
          error.response.message ||
          'You do not have permission to access this resource';
      }
    }

    const exception = new ApiException(
      error.response.message,
      errorName,
      stacktrace,
      errors,
      path,
      statusCode,
    );
    res.status(statusCode).json(exception);
  }
}

So if you recall, we throw an InternalServerErrorException for throwMongoError which will be caught by this HttpExceptionFilter because we decorate it with @Catch(HttpException). That’s how Exception Filter works. You can @Catch() some very specific error classes if you desire to. Exception Filter allows you to have access to the ExecutionContext which lets you know that your application is a HttpServer which has access to Request and Response (from express). Then from those information, you can construct an uniformed error and call res.status(Status).json() to return a meaningful, uniformed error to the client. The client will always get the same shape of error which allows them to handle the error more efficiently and consistently.

To activate the HttpExceptionFilter, open main.ts and add the following line:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './shared/filters/http-exception.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());  await app.listen(3000);
}
bootstrap();

Now, all of your HttpException thrown from ANYWHERE in the application will be filtered by HttpExceptionFilter and will be returned with an instance of ApiException 👍

A brief introduction to AutoMapper in TypeScript

Sat, 16 Nov 2019 00:00:00 GMT

Hi everyone, it’s been exactly a month (again) since my last blog 😄 and you’re probably getting bored of me saying that. Last month, I published a blog explaining why I wanted to create an AutoMapper library in TypeScript. In today’s blog, I am going to dive deeper into how it works in TypeScript by officially introducing my library for the first time: @nartc/automapper

Check it out on:

Github
npm

The Problem

With NodeJS getting more and more popular, we start seeing a lot more Server-Side projects written in NodeJS and problems with exposing the proper data slowly concerns many developers who are working on those projects. The concern shows clearer in particular with building APIs using DDD (Domain Driven Design) with a lot of DTOs / VMs (Data Transfer Object or View Model, these two terms can be used interchangeably). In other words, you do not want to expose your Domain Model outside of the Persistence Layer just in case the Application Layer in Multitier Architecture.

And in JavaScript, being a Dynamic Programming Language, the above problem ”can be done” quite easily because there is nothing stopping you from assigning values to your heart content. However, doing so blindly or mindlessly can cost you your maintainability to your code-base which is extremely dangerous and well, costly. On the other hand, doing so repeatedly will be prone to errors and eventually all of these ”manual mappings” will become tech debts that are really hard to repay, especially Complex Mappings.

Use-case

Let’s assume you are building a minimal AirBnB clone and you plan to have the following Domain Models:

Person
Listing
Booking

Real scenario will have many more Domain Models like: Notification, Message, Transaction etc… to accommodate such platform. Here, I take out all the transaction-related to simplify this blog post.

and you want to your platform able to do the following:

Anyone can register to become a Person in your application.
- A Person has two main Role: User and Host
- Signed up Person will have their Role default to User
A Person with User role can:
- Look at all Listing
- Create a Booking
- Save Booking to pastBookings
- Save a Listing to wishlist
- Save a Listing to lastViews list
A Person will become a Host after they create their first Listing and can:
- Create more Listing
- Respond to Booking request

From the above requirements, you can see that our Domain Models are having quite a complex relationship and circular dependencies

Person can have a list of Listing on lastViews and wishlist
Person can have a list of Booking on pastBookings
Listing must have a Person as host
Booking must have both Person as user and host, and also Listing as listing

Let us all assume that we don’t have to worry about Domain Models relationships like One-One, One-Many and Many-Many. We only focus on exposing our Models to the consumers.

Let’s look at our models in code:

// Person.ts

class Address {
  street: string;
  city: string;
  state: string;
  zip: string;
}

class Profile {
  firstName: string;
  lastName: string;
  bio: string;
  phone: string;
  address: Address;
}

enum Role {
  User = "user",
  Host = "host",
}

class Person {
  email: string;
  password: string;
  profile: Profile;
  role: Role;
  lastViews: Listing[];
  wishlist: Listing[];
  pastBookings: Booking[];
}

// Listing.ts

class GeoLocation {
  lat: number;
  lng: number;
}

class Listing {
  name: string;
  description: string;
  price: number;
  location: GeoLocation;
  host: Person;
}

// Booking.ts

class Booking {
  startDate: Date;
  endDate: Date;
  user: Person;
  host: Person;
  listing: Listing;
  total: number;
}

Take note that even though we wrote out Models with Nested Schemas but in reality, those relationships should be managed by reference (aka foreign key, aka IDs). To illustrate the point that data the consumers would get, we wrote it as nested.

As you can see, if we do not transform our Domain Models before returning to the consumers, we will then introduce circular dependencies in the data shape that the consumers would get. And the response could get substantially large with all the deep circular nesting. Moreover, we also create some “security issue” (like password) by exposing the Domain Models as they are: Person -> Booking -> Person -> Booking etc… To address this issue without any tools, we might come up with something like this:

// DTOs.ts

class ProfileDto {
  name: string;
  bio: string;
  phone: string;
  formattedAddress: string; // street + city + state + zip

  constructor(profile: Profile) {
    this.name = profile.name;
    this.bio = profile.bio;
    this.phone = profile.phone;
    this.formattedAddress = profile.address.street + profile.address.city + ...;/
  }
}

class PersonDto {
  email: string;
  role: Role;
  profile: ProfileDto;
  lastViews: ListingDto[];
  wishlist: ListingDto[];
  pastBookings: BookingDto[];

  constructor(person: Person) {
    this.email = person.email;
    this.role = person.role;
    this.profile = new ProfileDto(person.profile);
    this.lastViews = person.lastViews.map(lv => new ListingDto(lv));
    this.wishlist = person.wishlist.map(wl => new ListingDto(wl));
    this.pastBookings = person.pastBookings.map(pb => new BookingDto(pb));
  }
}

// to break the circular dependency here, we will then need to introduce another smaller Dto for Person

class PersonInfoDto {
  email: string;
  profile: ProfileDto;

  constructor(person: Person) {
    this.email = person.email;
    this.profile = new ProfileDto(person.profile);
  }
}

class ListingDto {
  name: string;
  description: string;
  host: PersonInfoDto;

  constructor(listing: Listing) {
    this.name = listing.name;
    this.description = listing.description;
    this.host = new PersonInfoDto(listing.host);
  }
}

class BookingDto {
  host: PersonInfoDto;
  listing: ListingDto;
  startDate: Date;
  endDate: Date;
  total: number;

  constructor(booking: Booking) {
    this.host = new PersonInfoDto(booking.host);
    this.listing = new ListingDto(booking.listing);
    this.startDate = booking.startDate;
    this.endDate = booking.endDate;
    this.total = booking.total;
  }
}

DTOs are very specific and will differ from project to project. Decision making process for this dumbed-down version of this particular use-case:

For Profile.address, we only want to display a formattedAddress string.
For Person.lastViews and Person.wishlist, we would normally display like a list of cards with some minimal information. That’s why ListingDto contains those information.

Next, you might have noticed the constructor() in each DTOs, we are essentially “map” the Domain Models to these DTOs manually by passing in the appropriate Domain Model in the constructor() of a matching DTO. This approach is safe and it works well. In fact, our company uses this hand-written approach in one of our NestJS backend. However, this approach is not a good solution because:

Violates DRY. In a real scenario, you’d end up with many DTOs matching against a single Domain Model. The mapping is almost never one-model-one-view-model and you probably have to re-type a lot of mapping, both simple and complex ones.
Error-prone. Because of the amount of re-typing, your code is more prone to human-errors.
One-way mapping. Without introducing even more code, you cannot have two-ways mapping Domain <=> DTO
Separation of Concern. Now this is a debatable one. One could argue that the mapping logic can (and should) stay within the DTO because that is where the transformation should occur. But, I’d try to make my DTO as clean and slim as possible by separating the Mapping logic out of the DTO itself.

AutoMapper can help

Let me recap, @nartc/automapper implementation of AutoMapper is an Object to Object mapping solution by convention. Before we get to how @nartc/automapper can help us, allow me to introduce to all of you that are not familiar with AutoMapper some terminologies so you can follow better:

Mapper: This is the main object that will help with the mapping. Usually in an AutoMapper implementation, Mapper is exposed as a singleton. In @nartc/automapper, there’s a singleton Mapper. However, you can always instantiate another Mapper if you wish to manage your Mapper instance.
Profile: A Domain Model can have at least 1 Profile. A Profile is a class that extends MappingProfileBase and it represents a profile of ONE Domain Models and its matching DTOs.
Mapping: A Mapping is a blueprint between two Models, usually a Domain Model and a DTO. The Mapper can only proceed with the map operation if the Mapping exists.

Now, let’s start with the issues one by one, not in any particular order:

Separation of Concern As the definition of Profile has stated, a Profile can house all the mapping logics for a specific Domain Model. We have 3 Domain Models so we’ll have 3 Profiles

class PersonProfile extends MappingProfileBase {
  constructor() {
    super(); // needed for this.profileName
  }

  configure(mapper: AutoMapper): void {
    throw new Error("Method not implemented.");
  }
}

class ListingProfile extends MappingProfileBase {
  constructor() {
    super();
  }

  configure(mapper: AutoMapper): void {
    throw new Error("Method not implemented.");
  }
}

class BookingProfile extends MappingProfileBase {
  constructor() {
    super();
  }

  configure(mapper: AutoMapper): void {
    throw new Error("Method not implemented.");
  }
}

Let’s implement our PersonProfile.configure():

class PersonProfile extends MappingProfileBase {
  constructor() {
    super(); // needed for this.profileName
  }

  configure(mapper: AutoMapper): void {
    mapper
      .createMap(Profile, ProfileDto) // create the Mapping for Profile -> ProfileDto
      .forMember(
        d => d.name,
        opts => opts.mapFrom(s => s.firstName + " " + s.lastName)
      ) // map from Profile.firstName and Profile.lastName to ProfileDto.name. TypeScript will help out here
      .forMember(
        d => d.formattedAddress,
        opts =>
          opts.mapFrom(
            s => s.address.street + " " + s.address.city + " " + s.address.state
          )
      ) // d stands for destination, s stands for source
      .reverseMap(); // create the Mapping for ProfileDto -> Profile

    mapper.createMap(Person, PersonDto).reverseMap(); // create the Mapping for Person -> PersonDto and PersonDto -> Person
  }
}

Here, we say PersonProfile extends MappingProfileBase to initiate our contract between PersonProfile and MappingProfileBase which is used internally by @nartc/automapper. The constructor is needed to grab PersonProfile string and assign it to this.profileName. Each instance of Mapper will keep track of its profiles by profileName. Then we implement configure() method which receives the Mapper instance. Next, we proceed to start creating our first mappings by calling createMap() method which follows Fluent Interface:

createMap(Profile, ProfileDto): this creates the Mapping for Profile -> ProfileDto. This method also establishes mapping configurations for properties that are on both Profile and ProfileDto. Remember, by convention? So, Profile.bio will be mapped to ProfileDto.bio without you having to configure that.
What if we need to configure a property on the Destination (ProfileDto in this case)? forMember() is created for that purpose. Pass in a Selector Function to let Mapper know which property you want to configure explicitly and another function that receives the ForMemberOptions object which exposes different methods for you to configure the property being selected. Here, we want to configure ProfileDto.name explicitly and we want to take Profile.firstName value and Profile.lastName value to assign to ProfileDto.name. Therefore, we use mapFrom() which takes in yet another Selector Function to get the value for ProfileDto.name. TypeScript will help out here with safe-typings. You will actually get an error if you’re trying to map a value that is different than a string to ProfileDto.name (which is a string).

TypeError when trying to map unmatched value type

@nartc/automapper follows as close to the original .NET AutoMapper API as possible.

We repeat the process for formattedAddress.
Call reverseMap() to create another Mapping for ProfileDto -> Profile.
Create another Mapping for Person -> PersonDto
Call reverseMap() to create another Mapping for PersonDto -> Person

Why is createMap(Person, PersonDto) so short/empty? Again, remember by convention? This is one of the strong point of an AutoMapper. @nartc/automapper will try to map matching properties on both Person and PersonDto for primitives, nested models and list. Here, we set PersonDto.profile to ProfileDto and we have already setup a Mapping for Profile -> ProfileDto, @nartc/automapper will be able to map from Person.profile to PersonDto.profile without any configuration because @nartc/automapper will get the existing Mapping for Profile -> ProfileDto to map profile since a Mapping for any pair of Models is unique.

The same goes for Listing and Booking so to simplify, I will not be putting code for those in this blog. You can find a full example here: CodeSandbox

@nartc/automapper currently supports a wide range of features:

Basic Mapping between two classes
Basic Mapping for nested classes
Array/List Mapping
Flattening
ReverseMap
Value Converters
Value Resolvers
Async
Before/After Callback
Naming Conventions

so please check out Github to learn more.

Flaws

Just want to get it out there, I work on this library knowing the limitations of TypeScript on its reflection capabilities. Hence, there are some flaws that are worth mentioning:

Selector Function: Currently, the way I grab the properties from these Selector Function is kind of flaky. I expect bugs in different scenarios when the library is used more. Even though I am pretty confident since I have unit test for @nartc/automapper.
Reflection: @nartc/automapper has a peer dependency on reflect-metadata and two dependencies which are class-transformer and lodash.set. lodash.set is pretty self-explanatory. So I will explain the other two:
- reflect-metadata: This is used to be able to get metadata from decorators.
- class-transformer: This library exposes a couple of nifty stuffs that @nartc/automapper can make use of. Namely, plainToClass(), @Expose() and @Type().

I have written about this in the previous blog on Why I (want to) build an AutoMapper in TypeScript?

And to fix and/or improve flaws, I need more trials and more flaws. Please, if it fits your use-case, give @nartc/automapper a try.

Integration

Beside the core library @nartc/automapper, I have also written a wrapper to be used in NestJS which goes by nestjsx-automapper on npm. It is a part of NestJSX opinionated set of modules written specifically for NestJS. Check it out on Github

Future

Currently, @nartc/automapper is waiting for more feedbacks and issues so it can be improved upon. Tutorial wise, I plan to record a video tutorial beside this blog post so stay tune for that. It feels much nicer on video, I promise. That said, if you decide to give the library a try, keep the feedbacks/issues coming. TIA!

Credits

.NET AutoMapper for the inspiration
automapper-ts for the starting point
Cleancode blog for the cover and for some ideas behind putting this blog together.

Thank you for reading. I’m looking forward to seeing you in the next blog 🚀

Why I (want to) build an AutoMapper in TypeScript?

Wed, 16 Oct 2019 00:00:00 GMT

Hey, it’s been around a month since my last blog post 😢. Work has been pretty busy lately for me. Talk about work, this week marks my 2 years as a Developer at ArchitectNow. Over the course of 2 years, I’ve learned so many cool technologies like: .NET Core, Swagger/OpenAPI and especially AutoMapper.

Original .NET AutoMapper

AutoMapper is “A convention-based object-object mapper. 100% organic and gluten-free. Takes out all of the fuss of mapping one object to another.” created by Jimmy Bogard (Github). It’s a pretty simple description of what AutoMapper is, ain’t it? Well, it does a lot for you. And it’s an awesome tool given the very high capability of Reflection in C#.

But why AutoMapper?

tldr; AutoMapper is a tool that provides Object Mapping by convention. If you construct your View Models consistently with your Domain Models, then you have established a convention and AutoMapper is a great tool for situations like this. It will take away all the boring mapping. You can read the whole blog post here: Automappers Design Philosophy. I’ll quote the last part of the blog here:

AutoMapper works because it enforces a convention. It assumes that your destination types are a subset of the source type. It assumes that everything on your destination type is meant to be mapped. It assumes that the destination member names follow the exact name of the source type. It assumes that you want to flatten complex models into simple ones.

All of these assumptions come from our original use case - view models for MVC, where all of those assumptions are in line with our view model design. With AutoMapper, we could enforce our view model design philosophy. This is the true power of conventions - laying down a set of enforceable design rules that help you streamline development along the way.

By enforcing conventions, we let our developers focus on the value add activities, and less on the activities that provided zero or negative value, like designing bespoke view models or writing a thousand dumb unit tests.

And this is why our usage of AutoMapper has stayed so steady over the years - because our design philosophy for view models hasn’t changed. If you find yourself hating a tool, it’s important to ask - for what problems was this tool designed to solve? And if those problems are different than yours, perhaps that tool isn’t a good fit.

AutoMapper is not that well-known, and hated

I know of AutoMapper through work and I was (still am) very impressed with how convenient AutoMapper is. But I’m a tad surprised when no one really knows what AutoMapper is when I ask around. If people don’t really know what AutoMapper is, it kind of defeats my purpose of creating it in TypeScript and will be really hard to promote it 😅. This Reddit post also discusses about whether you want to use AutoMapper in your project. There is also a plethora of blog posts about “Why No AutoMapper?” (I was googling for Why AutoMapper? 😅). Here’s one of them (and it’s a good blog post to be honest with you) Why I Don’t Use AutoMapper.

But I still want to use AutoMapper in TypeScript

Like I mentioned above (and also in some of the blog posts), AutoMapper in the TypeScript world isn’t really a thing because of how limited the Reflection Capability in TypeScript is. It is not as good as C# because in the end, TS is compiled down to a dynamic language, JS, anyway.

Let me dial back to why we use AutoMapper at work in the first place. At ArchitectNow, we utilize Swagger/OpenAPI heavily to document our APIs, and combined with tools like NSwag or swagger-codegen, we have an automation pipeline to generate HTTP calls for client-side applications: a web app or a mobile app. Basically, we have our Domain Models which are the shape of data that will go in the Persistence Layer (Database) of the application. On one hand, we also have conventionally matching View Models that will be exposed to be used by the Clients via Controllers (API Endpoints). Without AutoMapper, we would have to “manually” map a lot of data back and forth on every single API calls. Everything’s good on the C# side of things, because we have AutoMapper.

On the NodeJS side, we take a big interest in NestJS. If you don’t know what NestJS is, you can learn about it here. tldr; NestJS is a NodeJS framework that takes on Angular-like architecture which helps with building maintainable and scalable server-side applications. When building NestJS applications, we use the same approach as we build a .NET Core application. Domain Models <=> View Models. Unfortunately, there isn’t a “good enough” AutoMapper library in the TypeScript world. There are some worth mentioning:

automapper-ts by Bert Loedeman - This is the closest, in terms of syntax, to the original AutoMapper.
@wufe/mapper by Simone Bembi - This is also a very nice library.
morphism by Yann RENAUDIN - This is an interesting library. Not really AutoMapper but it might do the job.

…but all of them have some problems, for me. automapper-ts is a bit outdated and doesn’t seem to be actively maintained. @wufe/mapper is also great but doesn’t support as much as I like it to and it might be hard/long for features that I might want/look for in an AutoMapper tool to be supported. Last but not least, morphism is something that comes up in my search and it looks super interesting, its syntax does not adhere to AutoMapper syntax however.

With all of these in mind, I’ve decided to take a stab at creating my own AutoMapper in TypeScript, mainly inspired by automapper-ts.

Problems with TypeScript

Again, Reflection is a big part in trying to solve the auto part of AutoMapper. Let’s look at one example:

class User {
  firstName: string;
  lastName: string;
}

the above .ts block will be compiled to .js:

class User {}

// or in older ES
function User() {}

So now when you try to instantiate a new User() by writing the following:

const user = new User();
console.log(user);

// User { firstName: undefined, lastName: undefined }; at least this was my expectation

// but in reality, you'll get: User {}

Uh…where’s my firstName and lastName? Let’s look at another code block before I explain why firstName and lastName are important:

// SomeFileName.cs

// Same Domain model as in TypeScript
class User {
    public string FirstName {get; set;}
    public string LastName {get; set;}
    // ... some additional properties ...
}

// Some ViewModel class
class UserVm {
    public string FirstName {get; set;}
    public string LastName {get; set;}
    // ... some additional properties ...
}

...
// Create the Mapping between User and UserVm
CreateMap<User, UserVm>();
...

...
// Actual map from User to UserVm
var userVm = Mapper.Map<UserVm>(user);
...

In the C# world, AutoMapper will be able to map User.FirstName to UserVm.FirstName because of Convention. They share the same property name FirstName. On the contrary in TS, you cannot do that without having to do a bit more work. The User instance in TS doesn’t contain any properties because we never actually declared them in our User class. Remember what I said about Typings will NOT be persisted earlier, this is exactly that problem.

You can kinda fix the problem by writing the following:

class User {
  constructor(public firstName: string, public lastName: string) {}
}

Now, the compiled JS code will look something like:

class User {
  constructor(firstName, lastName) {
    this.firstName = firstName;
    this.lastName = lastName;
  }
}

You can see that we now actually declared firstName and lastName on this instance when we new() up one. Hence, when you do the following:

const user = new User();
console.log(user);
// logs User {firstName: undefined, lastName: undefined};

Great! I have firstName and lastName in my User instance. But why are those important? Because we have to auto-map them. Technically with AutoMapper, you never really do a map manually by: userVm.firstName = user.firstName, AutoMapper is supposed to do that for you. What we can do to help AutoMapper (actually, we need to) is to create a Mapping between a Source and a Destination (User as Source and UserVm as Destination in this case).

I expect my automapper to do the following when it starts mapping User -> UserVm:

Create a new instance of UserVm (1)
Loop through the keys on (1)
Grab the value for the same key on User object passed in.
Assign the “found” value on (1)

Something like this in code:

const destination = new UserVm();

for (const key in Object.keys(destination)) {
  // do some null check for source[key]
  // if key exists on source, then
  destination[key] = source[key]
}

return destination;

Without firstName and lastName being “visible” on a new instance of UserVm, it is impossible to map in this case because Object.keys(destination) will return an empty []. There was no key on destination. The short-hand syntax to declare class properties inside of constructor was my first iteration of the library. Shortly after, I tried to utilize reflect-metadata to declare the properties on the class “automatically”. However, I kinda ran into the same problem which was no properties was there in the first place to grab. Class Decorator does not provide any information about its property and Property Decorator is kind of verbose but Property Decorator is like my only answer to this at the moment. Talk about Property Decorator, I suddenly remembered a library that kind of has that already, which is class-transformer. I turn to class-transformer for not having to reinvent the wheel (well, for being lazy 😅). This library provides three things that I need:

@Expose and @Type decorators. @Expose solves the problem with a property being visible on a new instance. @Type solves the same problem, but with nested model.
plainToClass() method. plainToClass works in sync with Expose and Type to give you an instance with all of its properties “exposed” to be able to map.

Hence, I’ve decided to include class-transformer as one of my library’s dependency. Well, before you judge me, I did try to build Expose, Type and plainToClass by myself using reflect-metadata. However, the difference in bundle size between including class-transformer vs a half-baked internal implementation is 0.3kb. Not really worth it NOT to include class-transformer. Plus, class-transformer provides a lot more than my implementation.

Conclusion

There are a lot more problems that I’ve faced and am still facing while trying to build this first library. Namely, they are features that the original AutoMapper supports like: Reverse Mapping, Type Converters etc… which I will go through each one in more detail in the next blog. I also face problem with getting a value on an object with a path which I turn to lodash.get (because I’m lazy to implement it and I probably won’t implement it to cover enough cases like Lodash does aka best excuse ever!). Keeping the syntax as close to AutoMapper as possible is also a pain point, Fluent API 💪. In the end, I am proud of myself for doing what I’m doing. Trust me, you’re going to learn so much when you try to build a library, or a solution to your problem in general. Sharing my thoughts and my work with others is such a great way to reflect on what I’ve been doing and it brings me such joy to share my findings and knowledge with everybody out there. Thank you for reading and I’ll see you in the next one which is going to be: AutoMapper TypeScript in Action (Link coming up). Finally, my library is actually live and is on npm, you can check the Github repo out here. Please feel free to try it out, look through the source and leave me ANY feedbacks in the Issues section, I am happy to receive feedbacks, good or bad 💪. Thanks again and I’ll see you soon. 👋

MacOS Dev Environment Setup

Thu, 19 Sep 2019 00:00:00 GMT

Today, I am going to share with you guys my development environment which has been serving me really well for the past year. By all means, mine is not that special or anything but I want to share because there might be people out there who might find this interesting, and for me to have a source that I could come back to every time I install Parallels 😂

Parallels is a piece of software that lets you run Windows on a Mac. They’re doing a very good job but I just don’t like installing VMs on my machine. We have Dockers now you know?! tldr; I’ve had not so good experiences with Parallels

Now, if you’re a developer, or developer-to-be and wants to setup your Macbook for development, I’ll pick you up right here after you’re finishing Setup your Mac for first use.

I use https://sourabhbajaj.com/mac-setup/ as my reference but mine is more concentrated on JavaScript Dev. Please check out this guide for System Preferences related setup.

1. Install Xcode

Quick tip: you can start setting up your System Preferences when you’re waiting for Xcode to finish installed.

Open AppStore and install Xcode
After Xcode finishes, open your Terminal and run the following command which will install Xcode Command Line Tools which is required for many other tools, especially Homebrew

 
xcode-select --install

2. Homebrew

Next, we’ll install Homebrew. Homebrew is like npm but for your systems rather than your JS applications. With Homebrew, you can install all kind of tools/applications and manages them in one place. Open your Terminal and run the following command:

 
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After the process is finished, you can run brew doctor in the same terminal to check if “your system is ready to brew”. Once you’re “ready”, let’s run:

 
brew tap caskroom/cask

Following are some most used Homebrew commands that you’ll probably use:

To search for a package (or Formulae or Cask in Homebrew vocabulary):

 
brew search search_phrase

To install a formulae:

 
brew install formulae_name

To install a cask:

 
brew cask install cask_name

using Homebrew to search for VS Code

the little ✅ next to the cask annotates that this cask is already installed on my machine.

3. iTerm2 & Alfred

With Homebrew installed, you should start installing two things: iTerm2 and Alfred 4

 
brew cask install iterm2
brew cask install alfred

Run iTerm2 and start setting a couple of things up. The following items are all optional

Go to Preferences -> Profiles -> Keys, and add new 4 shortcuts:

shortcut	action	esc+
⌘←	Send Escape Sequence	OH
⌘→	Send Escape Sequence	OF
⌥←	Send Escape Sequence	b
⌥→	Send Escape Sequence	f

Go to Preferences -> Profiles -> Session, and check Status bar enabled and configure them how you want. I personally have: Current Directory, CPU Utilization and Memory Utilization

Status Bar Components

If you want to change your typography, go to Preferences -> Profiles -> Text. I use Menlo 14pt.
Finally, browse to iTerm2-Color-Schemes to pick a theme that you like. Then go to Preferences -> Profiles -> Colors, import the preset that you picked and select it. I personally use Dracula

Next up is Alfred 4. Alfred is Spotlight replacement and if you’re willing to pay (which you should) for the Power Pack, you’ll never live your life normally without Alfred. First of all, we need to disable Spotlight.

Run Spotlight and uncheck everything that you don’t want. I uncheck Fonts, Images and such.
Click on Keyboard Shortcuts and uncheck Show Spotlight Search. While you’re here, click on Services, look for Search man Page Index in Terminal and uncheck that as well. I will explain later.
Run Alfred. Check Launch Alfred at login and change your Alfred Hotkey to ⌘ Space. Then you’re all set.

4. zsh and oh-my-zsh

One of the reasons why iTerm2 is so much more powerful than Terminal is that you can customize it. There are many different frameworks that can make your iTerm2 experience up another level. Personally, I always go with zsh and oh-my-zsh because of how well-known it is, easy to look for answers you know 😋. To install zsh, we’ll use Homebrew.

 
brew install zsh

After that’s done, run the following command to install oh-my-zsh:

 
sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

Now you have the power of oh-my-zsh in your iTerm2. Your main configuration file will be ~/.zshrc instead of ~/.bash_profile or ~/.bashrc. We’ll start setting up oh-my-zsh with some productivity stuffs.

By default, zsh provides an alias to quickly open ~/.zshrc from the terminal. However, you might want to install your favorite text editor before doing so. I usually install nvim and vscode at this point.

 
brew install nvim
brew cask install visual-studio-code

nvim feels easier to me and VSCode has that code command that you can open VSCode from the terminal. Go ahead and execute:

 
nvim ~/.zshrc

You can use code if you want to. If code is not available, run Visual Studio Code -> Open the Command Palette -> Shell Command: install 'code' command in PATH

alias is your shortcut to any shell/combinations of shell -

Let’s setup some aliases to make your life easier. The following list is my current aliases which I find super helpful.

 
# change to code if you use vscode
alias zshconfig="nvim ~/.zshrc"
# you need to source zshrc after you make change like adding plugins
alias zshsource="source ~/.zshrc"
# quickly open oh-my-zsh config
alias ohmyzsh="code ~/.oh-my-zsh"
# best alias ever
alias c="clear"

alias rm="rm -rf"
alias ls="ls -lah"
alias cd..="cd .."

# find node_modules recursively from the current dir
alias findnode="find . -name "node_modules" -type d -prune -print | xargs du -chs"
# remove those node_modules
alias rmnode="find . -name 'node_modules' -type d -prune -print -exec rm -rf '{}' \;"

# if you develop iOS app, this will list all available simulators
alias listios="xcrun simctl list devices"

# CLI Alias
alias cra="create-react-app"
alias crl="create-react-library"
alias rn="react-native"

If you’re from ~/.bash_profile or ~/.bashrc, you’ll need to add the next line to your ~/.zshrc

 
# If you come from bash you might have to change your $PATH.
export PATH=$HOME/bin:/usr/local/bin:$PATH

 
# extraneous stuffs
export CLICOLOR=1
export LC_ALL=en_US.UTF-8

Theming: You can go to Themes and pick a theme you like. Then edit the following line

 
ZSH_THEME="theme_name"

Plugins. By default, zsh comes with various plugins and will enable git plugin by default. git plugin provides you with all kinds of git shortcuts. Check this link out. I have the following plugins enabled.
- colored-man-pages: comes with zsh
- colorize: comes with zsh
- zsh-syntax-highlighting: INSTALL.md
- zsh-autosuggestions: INSTALL.md
- zsh-completions: INSTALL.md

Now that we have setup our terminal, it’s time to start installing some applications. Use brew search to search for an app that you want.

 
brew cask install google-chrome
brew cask install appcleaner
brew cask install postman

5. NodeJS

There are many ways to install NodeJS but I’d recommend using nvm to manage NodeJS on your machine. nvm stands for Node Version Manager and it allows you to install and switch between versions very easily.

Install nvm

 
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.1/install.sh | bash

Run zshsource
Run command -v nvm to check if nvm is available. If you have issue, it’s most likely that nvm is missing in your PATH. Fix by adding the following block to your ~/.zshrc

 
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Run nvm install node. This will install the latest version of NodeJS on your machine.
Run nvm ls to list installed Node versions.
Run nvm ls-remote to list Node versions that you can install

6. Python

Even though I don’t use Python as a programming language, but some tools are built with Python. So I’d also recommend installing Python using pyenv (just like nvm for NodeJS).

Install pyenv

 
brew install pyenv

Update PATH

 
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

Run pyenv install --list. If you have issue here, restart your terminal.
Run pyenv install version_here to install Python. I usually install latest 2.x and latest 3.x

7, Database

Again, consult https://sourabhbajaj.com/mac-setup/ and pick the ones that are relevant to you.

8. Docker

Docker can be installed by visiting this link. If you like GUI, I’d recommend Kitematic which is awesome.

 
brew cask install kitematic

Kitematic

9. MongoDB

I use Docker for my local MongoDB instance. However, I recently had to install Mongo client on my machine due to some work that requires some CLIs from Mongo. Visit this link and follow the manual to install Mongo locally.

Again, I like GUI because it saves a lot of times and there are many Mongo GUI Client out there for you to choose: Studio 3T 💰, NoSQL Booster 💰 or Mongo Compass 🆓 and Robo 3T 🆓. I personally like NoSQL Booster (they also have free version) because of their focus on Shell commands and provides extremely good intellisense.

10. Jetbrains

I am a Jetbrains fan. Jetbrains is a suite of well-known IDEs like IntelliJ, Webstorm, PyCharm, PHPStorm, Android Studio ..etc… Only thing to note here is if you use Jetbrains, consider installing their toolbox Jetbrains Toolbox and it’s available via Homebrew

 
brew cask install jetbrains-toolbox

Jetbrains Toolbox allows you to manage your IDEs installation and versions. It also allows you to install certain shell commands so you can open your IDEs from the terminal.

That is all I have to share for Development Environment Setup. I hope you find the information helpful. My next blob will probably be on Jetbrains specific so I can share my productivity tips with you through the tools that we use everyday. Go and be productive, and make sure to always install things with Homebrew whenever possible. Thanks for reading 😀.

Slalom Health Equity Hackathon - Part 2

Thu, 12 Sep 2019 00:00:00 GMT

Welcome back to part 2 (and probably final part) of my journey through Slalom Health Equity Hackathon. As mentioned towards the end of Part 1, this part will start getting into the weed of fine-tuning the data after we have tried fetching and consolidating everything we’re provided by the organizers.

The agenda for this part will be as follow:

Web Scraping
AWS Comprehend
Presentation

It’s worth noting that the organizers did provide an API Endpoint for participants to make a request by sending their data and the endpoint will return a set of scores so participants could see how they’re doing and what they should be improving on.

Web Scraping

Before our team resorted to Web Scraping, we were actually thinking about two different APIs:

Google Places API: This is a Google’s service that provides information about businesses.
Bing Entity Search API: This is pretty much the same service as above but provided by Bing.
Google Custom Search API: This API will allow you to build your custom search.

With the amount of data we had, there’s no way to utilize these two APIs without paying or taking turns creating multiple free accounts (which was totally valid) but I’d rather do something simple, quick, and less bothering, especially to my teammates.

My teammates was working with Python, namely jupyter and boto3 to get familiar and adapt to AWS Comprehend.

For projects that are not in Hackathon format, I would totally suggest going for a well-known and fully supported API like Google Places. What I am about to do is fun, somewhat effective, and pretty inaccurate 😅

After every consideration for not wanting to pay 3rd-party services, we decided to go with Puppeteer

Google Chrome Puppeteer

Puppeteer is a Google Chrome Headless API that allows you to basically use Chrome programmatically and automatically. For what Puppeteer has to offer, I’d refer you to Puppeteer README

Google Chrome Puppeteer README

The plan was to have Puppeteer running on the dataset, perform a Google Search with the organization name, and fetch the first URL that Google Search returns. This approach is easy and quick but facing these issues: inaccurate data and advertisement. Given our time constraint and hackathon format, we decided to go with it anyway. First, I needed to run a query to query for all the Organizations that DO NOT HAVE a WEBSITE yet.

Same ol’ setup to start working MongoDB and JavaScript.

const mongo = require('mongodb');

let result = 0;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

client.connect((err) => {
    if (err) {
        console.log(err);
        return;
    }

    const db = client.db('stl-health-hack');
    const col = db.collection('queriedbmfs');
})

npm install puppeteer and start with importing puppeteer

const puppeteer = require('puppeteer');const mongo = require('mongodb');

let result = 0;

Add a query to find all Organizations that do not have WEBSITE or have invalid WEBSITE

const puppeteer = require('puppeteer');
const mongo = require('mongodb');

let result = 0;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

client.connect((err) => {
    if (err) {
        console.log(err);
        return;
    }

    const db = client.db('stl-health-hack');
    const col = db.collection('queriedbmfs');

    col.find({$or: [        {WEBSITE: {$exists: false}},        {WEBSITE: {$eq: "N/A"}},        {WEBSITE: {$eq: "NONE"}},        {WEBSITE:  {$eq: "None"}}    ]}).toArray(async (err, bmfs) => {            });})

Loop through the result and call getFirstUrl() and pass in the organization name

const puppeteer = require('puppeteer');
const mongo = require('mongodb');

let result = 0;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

client.connect((err) => {
    if (err) {
        console.log(err);
        return;
    }

    const db = client.db('stl-health-hack');
    const col = db.collection('queriedbmfs');

    col.find({$or: [
        {WEBSITE: {$exists: false}},
        {WEBSITE: {$eq: "N/A"}},
        {WEBSITE: {$eq: "NONE"}},
        {WEBSITE:  {$eq: "None"}}
    ]}).toArray(async (err, bmfs) => {
        for (let i = 0; i < bmfs.length; i++) {            const bmf = bmfs[i];            const href = await getFirstUrl(bmf.NAME);        }    });
})

I’ll get to getFirstUrl() in a bit

If href (the URL we want) is found, then I want to update the same organization with the newly found URL

const puppeteer = require('puppeteer');
const mongo = require('mongodb');

let result = 0;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

client.connect((err) => {
    if (err) {
        console.log(err);
        return;
    }

    const db = client.db('stl-health-hack');
    const col = db.collection('queriedbmfs');

    col.find({$or: [
        {WEBSITE: {$exists: false}},
        {WEBSITE: {$eq: "N/A"}},
        {WEBSITE: {$eq: "NONE"}},
        {WEBSITE:  {$eq: "None"}}
    ]}).toArray(async (err, bmfs) => {
        for (let i = 0; i < bmfs.length; i++) {
            const bmf = bmfs[i];
            const href = await getFirstUrl(bmf.NAME);
            if (href) {
                await col.updateOne({_id: bmf._id}, {$set: {WEBSITE: href}});            }
        }
    });
})

Implement getFirstUrl(). Everything that happens with puppeteer is asynchronous operations so I utilize async/await here.

const getFirstUrl = async (query) => {
    // Just a log for knowing which organization puppeteer is trying to fetch
    console.log(`Getting URL for ${query}`);
    
    // Initialize a browser instance. Default value for "headless" is true which means
    // puppeteer will open up a Chrome/Chromium window
    // I set it to "true" explicitly so you can see there's an option.
    const browser = await puppeteer.launch({headless: true});
    
    // Initialize a new page
    const page = await browser.newPage();
    
    // Go to this URL
    await page.goto('https://google.com');

    // Type in the search box the Organization name. 
    // What you pass in .type() is the input selector. 
    // You can find out about the selectors for all elements in the webpage by using Chrome Dev Tools.
    await page.type("input.gLFyf", query);
    
    // Hit Enter
    await page.keyboard.press(String.fromCharCode(13))
    
    // Wait for the next page's done loading
    await page.waitForNavigation();
    
    // Wait additional 2 seconds for no reason at all
    await page.waitFor(2000);
    
    // Try to get the first URL
    let href = await page.$eval("div.g", el => el.firstElementChild.href);
    if (!href) {
        href = await page.$eval("div.r", el => el.firstElementChild.href);
    }

    // the next two lines are for "reporting" purposes
    result++;
    console.log(`Found URL: ${href}. Already ran ${result}`);
    
    // Close the page
    await page.close();
    
    // Close the browser
    await browser.close();
    
    // return the URL if found, return null if not found
    return href;
}

Next thing to do is to run the script with Node and watch Puppeteer does its thing. With this approach, our team was able to come down to only 5 organizations that DO NOT have a WEBSITE. Well, the websites weren’t really accurate because we didn’t take “Ads” into account when we did “first URL”. At this point, we were also ready to start getting into AWS Comprehend. Our plan was:

Train AWS Comprehend to recognize Service Codes by Descriptions: MISSION_DESC, ORG_DESC and the actual CODE_DESC
Use fuzzywuzzy string matching to compare the trained descriptions with the organization’s description.

The goal is to find out which services an organization might provide. And we did just that. With all the information we’ve gotten so far, I was able to whip up quickly an input file in format of a CSV so we could feed that into AWS Comprehend via AWS S3

db.categories.find({}).forEach((it)=> { 
    let concatDesc = "";
    if (it.keywords && it.keywords.length) {
        concatDesc = concatDesc.concat(it.keywords.join(" "));
    }
    
    if (it.description) {
        concatDesc = concatDesc.concat(" ", it.description);
    }
    
    if (concatDesc) {
        db.codedescs.insertOne({code: it.code, description: concatDesc})
    }
});

Basic query, ain’t it? I concat all the keywords associated with a category and the description of the category, then insert each one in a codedescs collection which later allows me to export that collection to CSV.

About AWS Comprehend, you’d have to utilize many different components of the AWS Suite like S3, Permissions Management, and couple more that I don’t really recall. Basically, you need to setup in a way that AWS Comprehend can read and write from/to your S3 bucket on the same account and region because Comprehend will read the input from S3 as well as writing the resutlt to S3.

Once our model has been trained, the comparison starts. We utilized an NPM package called: fuzzball . This package is the JavaScript implementation of fuzzywuzzy methods from Python. At a high level, this library contains a set of methods to compare two strings and return a ratio of how close the two strings match.

First, as usual, bring in your libraries. I’ll skip Mongo initialization part because it’s identical to previous snippet.

const fuzz = require('fuzzball');const mongo = require('mongodb');

Setup our team’s thresholds. These thresholds determine the results. As mentioned above, fuzzball returns a ratio and if the ratio is greater than or equal to both thresholds, we accept the result. However, the data was so bad that for a high threshold, we didn’t get anything back. That’s why we iterated through couple of different thresholds to find that “sweet spot”.

const fuzz = require('fuzzball');
const mongo = require('mongodb');

// ...

/* * First set of threshold: 55 - 70 * Second set of threshold: 30 - 40 * Third set of threshold: 40 - 55 * Fourth set of threshold: 35 - 50 * Fifth set of threshold: 37.5 - 52.5 */const fuzzRatio = 37.5;const fuzzPartialRatio = 52.5;

Next is to connect to our MongoDB client and starts doing some actual string comparisons. The actual code is pretty self-explanatory. All I did was to go through all the keyPhrases, compare it to the description on category using fuzzball. If it’s above the thresholds, return the code of the category then update the collection.

const fuzz = require('fuzzball');
const mongo = require('mongodb');

/**
 * First set of threshold: 55 - 70
 * Second set of threshold: 30 - 40
 * Third set of threshold: 40 - 55
 * Fourth set of threshold: 35 - 50
 * Fifth set of threshold: 37.5 - 52.5
 */
const fuzzRatio = 37.5;
const fuzzPartialRatio = 52.5;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

const colName = 'eindescs_with_key_phrases';

client.connect(async err => {
  if (err) {
    console.log('error connecting to db', err);
    return;
  }

  const db = client.db('stl-health-hack');
  const keyPhrasesCol = db.collection(colName);
  const keyPhrases = await keyPhrasesCol.find({}).toArray();
  const categories = await db
    .collection('categories')
    .find({})
    .toArray();

  for (let i = 0; i < keyPhrases.length; i++) {
    const keyPhrase = keyPhrases[i];

    const codes = categories
      .map(cat => {
        const originalString = keyPhrase.phrase_keys
          ? keyPhrase.phrase_keys.split(',').join(' ')
          : '';
        const comparedString = cat.keywords.length
          ? cat.keywords.join(' ')
          : cat.description;

        const ratio = fuzz.ratio(
          originalString.toLowerCase(),
          comparedString.toLowerCase()
        );
        const partialRatio = fuzz.token_set_ratio(
          originalString.toLowerCase(),
          comparedString.toLowerCase(),
          { trySimple: true }
        );

        console.log(`${keyPhrase.EIN}`, ratio, partialRatio);

        if (ratio >= fuzzRatio && partialRatio >= fuzzPartialRatio) {
          return cat.code;
        }

        return '';
      })
      .filter(c => !!c);

    await keyPhrasesCol.updateOne(
      { _id: keyPhrase._id },
      { $set: { SERVICES: codes } }
    );
    console.log(`Updated: ${keyPhrase._id}`);
  }

  console.log('finished');
});

After this, we had pretty complete dataset, in our opinion. We’ve got WEBSITE and SERVICES at a pretty good point. But we’re still missing two key information: HOURS_OF_OPERATION and PHONE_NUM. We got “some” of the PHONE_NUM from the XMLs but there were a lot more organizations that DO NOT have their PHONE_NUM listed on their Tax Filing. Once again, we’re going to utilize Puppeteer for this task. The approach is pretty much the same as before, we’re just targeting different DOM Element to get what we want. The full script can be viewed below:

const puppeteer = require('puppeteer');
const mongo = require('mongodb');
const { getHour } = require('./utils');

let result = 0;

const client = new mongo.MongoClient('mongodb://localhost:27017', {
  useNewUrlParser: true,
  useUnifiedTopology: true
});

client.connect(err => {
  if (err) {
    console.log(err);
    return;
  }

  const db = client.db('stl-health-hack');
  const col = db.collection('queriedbmfs');

  col.find({}).toArray(async (err, bmfs) => {
    for (let i = 0; i < bmfs.length; i++) {
      const bmf = bmfs[i];
      const { hours, phoneNum } = await getPhoneNumAndHours(bmf.NAME);

      const update = { $set: {} };

      if (phoneNum) {
        update.$set['PHONE_NUM'] = phoneNum;
      }

      if (hours && hours.length) {
        update.$set['HOURS'] = hours;
      }

      if (Object.keys(update.$set).length) {
        await col.updateOne({ _id: bmf._id }, update);
        console.log('Done updated: ', bmf._id);
        console.log('----------------------------------------');
      }
    }
  });
});

const getPhoneNumAndHours = async query => {
  console.log('----------------------------------------');
  console.log(`Getting PhoneNumber and Hours for ${query}`);
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto('https://google.com');

  await page.type('input.gLFyf', query);
  await page.keyboard.press(String.fromCharCode(13));
  await page.waitForNavigation();
  //   await page.waitForSelector('span[data-local-attribute="d3ph"] > span');
  await page.waitFor(2000);
  let phoneNum;
  let hours;

  const hasPhoneNode = await page.$('span[data-local-attribute="d3ph"] > span');
  if (hasPhoneNode) {
    const phoneNumberNode = await page.$eval(
      'span[data-local-attribute="d3ph"] > span',
      el => el.textContent
    );
    console.log(`Found PhoneNumber: ${phoneNumberNode}`);
    phoneNum = phoneNumberNode
      .replace('(', '')
      .replace(')', '')
      .replace(/\s/, '')
      .replace('-', '');
  }

  const hoursNode = await page.$(
    'div[data-local-attribute="d3oh"] div.h-n[jsaction="oh.handleHoursAction"]'
  );

  if (hoursNode) {
    hours = [];
    console.log(`Found Hours`);
    await page.click(
      'div[data-local-attribute="d3oh"] div.h-n[jsaction="oh.handleHoursAction"]'
    );
    const allHoursNodes = await page.$$(
      'div[data-local-attribute="d3oh"] div.a-h > table > tbody tr'
    );

    for (let i = 0; i < allHoursNodes.length; i++) {
      const node = allHoursNodes[i];
      const day = await node.$eval('td.SKNSIb', el => el.textContent);
      const hour = await node.$eval('td:last-of-type', el => el.textContent);
      hours.push({ day: day.toLowerCase(), hour: getHour(hour) });
    }
  }

  result++;
  console.log(`Already ran ${result}`);
  await page.close();
  await browser.close();
  return { phoneNum, hours };
};

I had this script ran overnight as it’s running through all 2800+ organizations and it took about 4 hours to complete. Upon completion, we were able to get ~1400 more PHONE_NUM and ~700 more HOURS_OF_OPERATION. We’re happy with the amount of data we have gathered so far. Without further ado, we’ve started constructing the required data structure and send a test request to check out our scores.

/**
* The structure
* {
*   "team_id": "our team id",
*   "data": {
*     [EIN]: {
*       name: {string} Organization name
*       hours: {
*         [sunday | monday | tuesday | wednesday | thursday | friday | saturday]: {
*           opens_at: {string} 24HR format - if closed, use 00:00
*           closes_at: {string} 24HR format - if opened 24hrs, use 24:00
*         }
*       }
*       url: {string} Organization URL
*       phone: {string} Organization Phone Number - US 10 digits
*       services: {Array<string>} A list of Service Codes
*     }
*   }
* }
*/

// Initialize a request JSON object
const reqJson = { team_id: '<our_team_id>', data: {} };

// Connect to Mongo
client.connect(err => {
  if (err) return;
  console.log('connected');

  // Reference all needed database and collections
  const db = client.db('stl-health-hack');
  const col = db.collection('queriedbmfs');
  const einsWithCodes = db.collection('eindescs_with_key_phrases');

  einsWithCodes.find({}).toArray((err, einsWithCodes) => {
    col.find({}).toArray((err, docs) => {
      if (err) {
        console.log(err);
        return;
      }

      docs.forEach(doc => {
        // Grab the EIN
        reqJson.data[doc.EIN] = {
          name: doc.NAME
        };

        // If there's HOURS, grab the HOURS. getHours() is a function to clean-up hours gotten from Puppeteer Scraping
        if (doc.HOURS && doc.HOURS.length) {
          console.log(doc.NAME, doc.HOURS);
          reqJson.data[doc.EIN]['hours'] = {
            sunday: getHours('sunday', doc.HOURS),
            monday: getHours('monday', doc.HOURS),
            tuesday: getHours('tuesday', doc.HOURS),
            wednesday: getHours('wednesday', doc.HOURS),
            thursday: getHours('thursday', doc.HOURS),
            friday: getHours('friday', doc.HOURS),
            saturday: getHours('saturday', doc.HOURS)
          };
        }

        // If there's WEBSITE, grab it
        if (
          doc.WEBSITE &&
          doc.WEBSITE !== 'N/A' &&
          doc.WEBSITE !== 'NONE' &&
          doc.WEBSITE !== 'None'
        ) {
          reqJson.data[doc.EIN]['url'] = doc.WEBSITE;
        }

        // PHONE_NUM
        if (
          !!doc.PHONE_NUM &&
          doc.PHONE_NUM !== 'undefined' &&
          doc.PHONE_NUM !== '0'
        ) {
          reqJson.data[doc.EIN]['phone'] = doc.PHONE_NUM;
        }

        // and Service Codes
        const foundCodes = einsWithCodes.find(ewc => ewc.EIN === doc.EIN)
          .SERVICES;
        if (foundCodes.length && foundCodes.some(fc => fc.length >= 3)) {
          reqJson.data[doc.EIN]['services'] = foundCodes.filter(
            fc => fc.length >= 3
          );
        } else if (!!doc.NTEE_CD) {
          reqJson.data[doc.EIN]['services'] = [doc.NTEE_CD.substr(0, 3)];
        }

        eins.push(doc.EIN);
      });

      // Write the result to a file called request.json
      fs.writeFileSync('request.json', JSON.stringify(reqJson), {
        encoding: 'utf8'
      });
      console.log('Finished');
    });
  });
});

After we got our request.json, we sent that in a request right away. Our scores was, well, negative 🙀. However, the organizers did mention that the scores during the test runs are nothing but a mere measurement for teams to try to improve, but ultimately they do not contribute to final judging, which was a really good thing for us. It’s already day 3 when we’ve got to this time of the Hackathon. We felt like we’ve done everything we could in the amount of time we had so we “called it”. Personally, I was pretty pissed about how my AWS account needed 24-hour to verify to be able to use AWS Comprehend. That’s one of the reasons that kind of set our team back on the Comprehend part of the Hack. However, on the last day, I’ve tried using Comprehend with a different approach:

Still use categories for its code and keywords. But, I flatten the code and keywords so that each code will have multiple records, each record will be correspond to a single keyword

something like this

Feed the CSV to Comprehend to start training it. My hope was when I input a keyword, Comprehend might be able to suggest a list of services that are close to the input keyword
Put the result back in Mongo and work on some aggregations to get more meaningful, and hopefully more accurate data on what services an organization provides.

I was able to get to this but ran out of time and couldn’t work on any aggregation

Presentation

Our team was 7th on the list of teams to present. It was nerve wrecking, even more so after listening to other teams. There were so many good approaches that we could have taken. Most of the teams struggled with the same problems:

Data is messy or not able to understand the data fully
AWS Comprehend comprehension?!
Consolidating/Centralizing the data
Other 3rd party APIs limitation, like Google Places API

Our team came up to present. We talked about what we did, what problems we faced. We discussed what we could have done earlier and answered judges’ questions. I think we did pretty good but I honestly think we wouldn’t place at all because there were so many good teams. There were even some really good one-man team. But against all odds, our team places 2nd for utilizing fuzzywuzzy. As soon as I heard that, I jumped out of my seat, started approaching my teammates and celebrating 🎉. Through this Hackathon, I’ve learned so much more about both on personal level and social level. I learned that there are so many people out there that are lacking accesses to the essentials like Medical and Health Services and I did feel like what all participants have done over the weekend was tremendously meaningful to the society as a whole. Personally, I learned a couple more technologies and earned myself a couple more friends. And I’d say that’s a win-win-win-win-win-win 🎊.

Thank you all for going along this far. I know it’s all technical stuffs, code stuffs but it’s literally what we did, we code. And I loved explaining the meanings behind all those lines of code to all of you who’re interested. I’ve also pushed our project on Github. Please feel free to reach out to me if you have further questions or discussions. You can always get in touch with me on my social medias. Until next time 👋

Slalom Health Equity Hackathon - Part 1

Sun, 08 Sep 2019 00:00:00 GMT

This is Part One of a two-part series about my journey through Slalom Health Equity Hackathon. You can read about Part Two here.

Over the past weekend, I was participating in Health Equity Hackathon which was hosted and organized by Slalom, partnered with Covo and Johego, and sponsored by AWS. And it was a blast 🚀 !

Personally, I wasn’t planning on take part in the Hackathon at first. But I changed my mind immediately when I read the more about the Hack, which I’ll elaborate more down below. One of the reasons that I was hesitant to join in the beginning was because my ”usual hack-mates” were busy (At least, that’s what I thought through our daily chat). When I decided to participate, I joined by myself and hoped to get in a team during Team Formation session of the Hack. Here’s how it went.

The Challenge

The Hack started off by an organizer from Slalom, Tara Nesbitt, giving her presentation about the Hack’s guidelines and purposes. Next up was Johego Founder and CEO, Michael Kehoe. Michael was introducing Johego and explaining why he does what he’s doing and the positive impact of the work that his team at Johego is doing, as well as all the Hack’s participants were willing to sign their weekends up to contribute to the same positivity.

The problem statement sounds simple enough, at least to me: Medical and Health Services Accessibility for everyone. Sounds simple right? Medical and Health services are essential things that everyone should have access to, easily. Well, unfortunately that’s not the case. According to Michael, the average amount of time that a person gets connected to the right resource for their medical and health need is 43 minutes/resource. Michael also gave a clear example on how we could access to movie tickets via Fandango in a matter of minute. Why can’t we do the same for Medical? The reason, mainly, is how scattered the data is and how expensive it is to validate data on Medical.

Michael founded Johego with the purpose of closing the gap of Medical Accessibility and by participating in this Hackathon, I feel like everyone wants to contribute to the same purpose.

This Hackathon was a little bit different than the ones that I’ve done before. When I think about Hackathons, I think about making an Application that has an impact on one or more aspects of the Problem Statement. The deliverable has been always something visible, and, for lack of better words, presentable. In contrast, participants were given raw datasets and were asked to analyze, filter, and augment the raw provided datasets by using different tools and especially, with the power of Natual Language Processing by utilizing AWS Comprehend. This was also the main reason that changed my mind about joining the Hack. I was both surprised and excited for being able to finally learn something about data and Machine Learning. Problem statement’s provided. Next, I needed a team.

The Team

behind the scene

I was able to join a team that was consisted of 3 amazing people: Mar, Vanessa and Alex. A friend of mine introduced me to Mar and I’ve decided to join with Mar because I liked his personality when he approached me. Mar and Vanessa were very energetic and welcoming which made me feel really nice about the team. Alex didn’t show up on the first day but we ”communicated” briefly during the first night through Slack and I thought this guy was smart and knew what he’s doing, and I was excited to meet him.

Next morning, I got to meet Alex and the guy was like I thought he was, a smart guy. We immediately started working on the project and discussed about how we interpreted the data along the way. It was such a fun experience working with these guys. And it was rewarding, as we finished the Hack with the 2nd place

The check though 🤑

What We Did

The main purpose of this blog was to brag. No, not really 😛. I’m writing this blog post to share with all of you how our team contributed to the goal of the Hackathon’s organizers, partners, and sponsors.

A fast rundown of all the technologies/tools we used in the Hack:

After we get the data from the organizers, the first thing we did was to figure out how to store this data in a place where we can work and continue working on it for the next 2 days. That’s why I suggested that we should store the data in MongoDB. The main reason is because MongoDB is a NoSQL database and a schema-less database solution is great for situations like the challenge of this Hackathon. We only need a place to jot all the data down without worrying about what shape the data is. With that in mind, I quickly got all the CSV and JSON files that were provided and imported them in my local MongoDB instance using NoSQL Booster.

All data provided was in CSV format or JSON format. It was funny because I didn’t have any tools on my machine that read CSV 🤧 so I had to use Postman to fetch the data.

my final local MongoDB instance

Out of all 5 datasets that were provided, the biggest one has 450k rows of data which was a pain in the butt to work with. We didn’t really bother indexing any of the imported data due to time constraint of a hackathon format. Once all the data was imported, I started to run through the Documentation that Johego put together as to how to filter the data and came up with the following fundamental criteria:

I only want the Organizations that have matching EIN (a unique ID to Organization in IRS data) with the ones in Tax Filings 2018
Each organization provides activities/services to the community and this information is captured by annotating the services by Activity Codes and/or NTEE Codes (based on when the organization was established. To my understanding, Activity Codes are old format). Johego only cares about a specific subset of Services Codes and also provides the participants all the Whitelisted Codes so I only want the Organizations that have Services code in the range of the Whitelisted Codes
The Organizations dataset do not come with the Filings XML file that will provide us more information about the Organization: Phone Number and Website. So I also need to make sure to add the Filings XML URL to my enhanced Organizations dataset.

With all 3 above things in mind, I started writing my queries against all the provided datasets.

The first query is pretty simple. All I did was read two collections: bmfs (36K rows) and filings (450k rows) and match all the EINs between the two.

const filings = db.filings.find({});

db.bmfs.find({}).forEach((doc) => {
  const found = filings.find(f => f.EIN === doc.EIN);
  if (found) {
    // if have matching EIN, grab the XML URL from Filings Index and save that onto the document.
    db.bmfs.updateOne({_id: doc._id}, {$set: {URL: found.URL}});
  } else {
    // if not match, remove the document from the collection.
    db.bmfs.deleteOne({_id: doc._id});
  }
});

After this query is ran, I got the bmfs from 36K rows down to 8k rows, which means we have 8k organizations that have matching EINs with the Filings Index, and at the same time, I could update the bmfs with matching XML URL as well. This is a beauty of MongoDB. (1) and (3) were taken care of.

Next query is a bit more complicated and composed of multiple steps. The requirement is straightforward but the provided data is a bit messup. Again, I’ll run down what happens:
- Each Organization has a field called ACTIVITY and/or NTEE_CD.
- The whitelisted Activities is a collection of 3-digit codes.
- ACTIVITY fields among all Organizations were not consistent. The max-length is 9 characters (which is 3 Activities at the most) but some ACTIVITY fields were missing 0s because of the way data is handled from one medium to another, 0s are missing.
- If an Organization has EITHER matching ACTIVITY with the Whitelisted OR matching NTEE_CD with the Whitelisted codes, then it should be included.

With all of these information, my first step was to clean up the bmfs collection.

Get all bmfs that have ACTIVITY field and its value is not "0". If the ACTIVITY length is less than 9, then prepend 0s to it to make it 9 characters.

db.bmfs.find({ACTIVITY: {$ne: "0"}}).forEach((doc) => {
  if (doc.ACTIVITY.length < 9) {
    // If ACTIVITY length is less than 9, then make an array of length: 9 - length 
    // fill that array with 0, 
    // join the array of 0s 
    // concat the current ACTIVITY

    // Eg: ACTIVITY.length is 2. Then an array of ["0", "0"] is needed.
    // ["0", "0"].join("") => "00"
    // "00".concat("1234567") => "001234567"
    doc.ACTIVITY = Array.from({length: 9 - doc.ACTIVITY.length}).fill("0").join("").concat(doc.ACTIVITY);
    
    // Then update the document with the prepended ACTIVITY
    db.bmfs.updateOne({_id: doc._id}, {$set: {ACTIVITY: doc.ACTIVITY}});
  }
})

Now that I’ve got the ACTIVITY cleaned up, I thought that it might be easier to compare if the ACTIVITY were in a form of Array of 3 3-digit code. Eg: ["123", "456", "789"] instead of "123456789". So I did exactly that, make ACTIVITY into an array of 3-digit codes.

db.bmfs.find({ACTIVITY: {$ne: 0}}).forEach((doc) => {
  // initialize an empty array
  const codes = [];
  
  // create a loop that will loop 3 times
  for (let i = 0; i < 3; i++) {
    // each time, get a substring of the ACTIVITY in length of 3 and push that to codes array
    // eg: first iteration, i = 0, get the substring from index 0 (i * 3) and take 3 characters. So 123456789.substr(0, 3) gives me 123
    // second iteration, i = 1, continue getting the substring from index 3 and take 3 chars. So 123456789.substr(3, 3) gives me 456
    // same for last iteration.  
    codes.push(doc.ACTIVITY.substr(i * 3, 3));
  }
  // Update the document with the codes array.
  db.bmfs.updateOne({_id: it._id}, {$set: {ACTIVITY_CODES: codes}});
})

You can see that I could have combined the two previous queries but because I didn’t realize I needed the CODES until later.

Now I have ACTIVITY, ACTIVITY_CODES and NTEE_CD all good to go. Time to actually filter the Organizations.

// Initialize an empty array
const result = [];

// This is just to be safe, I drop the collection before running this script.
db.queriedbmfs.deleteMany({});

// Grab all the Whitelisted Codes
const codes = db.activitycodes.find({});

// Grab all the whitelisted NTEEs
const ntees = db.ntees.find({});

// Since my whitelisted codes are both MongoDB Collection
// so they come back with a form of Array of Object with _id and the actual code.
// I only want the Array of codes so I run them both through .map() method to grab the code.
const codesArr = codes.map(c => c.code);
const nteesArr = ntees.map(n => n.code);

// Filter the bmfs collection for EITHER:
// 1. If an Organization has both NTEE_CD and ACTIVITY
// 2. If an Organization does not have NTEE_CD (which means it only has ACTIVITY)
// 3. If an Organization does not have ACTIVITY (which mean it only has NTEE_CD)
db.bmfs.find({
    $or: [
        { $and: [{ NTEE_CD: { $exists: true }, ACTIVITY: { $ne: "0" } }] },
        { NTEE_CD: { $exists: false } },
        { ACTIVITY: { $eq: "0" } }
    ]
}).forEach((it) => {
    
    // Determine if this Organization should be included.
    // 1. If it only has NTEE_CD and its NTEE_CD startsWith at least one of the whitelisted NTEEs. It's good
    // 2. If it only has ACTIVITY and its ACTIVITY_CODES array (the one I made from the previous query)
    //    exists and its ACTIVITY_CODES array includes at least one of the whitelisted Activity Codes.
    // 3. If it has both NTEE_CD and ACTIVITY 
    //    then either its NTEE_CD startsWith at least one the whitelisted NTEEs
    //    or its ACTIVITY_CODES exists and includes at least one of the whitelisted Activity Codes.
    const shouldPush = (it.NTEE_CD && !it.ACTIVITY && nteesArr.some(n => it.NTEE_CD.startsWith(n)))
        || (it.ACTIVITY && !it.NTEE_CD && codesArr.some(c => it.ACTIVITY_CODES && it.ACTIVITY_CODES.includes(c)))
        || (it.ACTIVITY && it.NTEE_CD && (nteesArr.some(n => it.NTEE_CD.startsWith(n)) || codesArr.some(c => it.ACTIVITY_CODES && it.ACTIVITY_CODES.includes(c))));

    // If an Organization should be included, push it to the array.
    if (shouldPush) {
        result.push(it);
    }
});

// After the looping, insert the result array into a new collection 
// (which I intentionally drop at the beginning of this script)
db.queriedbmfs.insert(result);

After this query’s ran, I got the dataset down to 2.8K rows and queriedbmfs becomes the main collection that our team works with. And this concludes our first day.

The first task of the second day was to start parsing the XMLs to get the organizations’ WEBSITE and PHONE_NUM. Since I have the queriedbmfs with all the URLs I need on my local MongoDB, I took on the task. Meanwhile, my teammates started cramping up on AWS Comprehend. Back to my XML Parsing task, I needed a parser package which I went with fast-xml-parser and he. I also needed a HTTP Client which I went with good ol’ node-fetch.

Just FYI, all the previous code snippets were Mongo Shell scripts. You can write some JavaScript within the Mongo Shell but because it’s Mongo Shell so variable like db works. The below script is written in JS, specifically with NodeJS Runtime, so we need to approach MongoDB a little differently.

// Just bringing in the 3rd party libraries
const fetch = require('node-fetch');
const mongo = require('mongodb');
const parser = require('fast-xml-parser');
const he = require('he');

// Initialize MongoDB client at localhost:27017, default port of MongoDB
const client = new mongo.MongoClient("mongodb://localhost:27017", {
  // some recommended options to work with newer version of MongoDB
  useNewUrlParser: true,
  useUnifiedTopology: true
});

// XML parser options. I don't have a lot of experience
// working with XML so I don't really know what the options entail.
// This is from fast-xml-parser documentations
const options = {
  attributeNamePrefix: '@_',
  attrNodeName: 'attr', //default is 'false'
  textNodeName: '#text',
  ignoreAttributes: true,
  ignoreNameSpace: false,
  allowBooleanAttributes: false,
  parseNodeValue: true,
  parseAttributeValue: false,
  trimValues: true,
  cdataTagName: '__cdata', //default is 'false'
  cdataPositionChar: '\\c',
  localeRange: '', //To support non english character in tag/attribute values.
  parseTrueNumberOnly: false,
  attrValueProcessor: a => he.decode(a, { isAttributeValue: true }), //default is a=>a
  tagValueProcessor: a => he.decode(a) //default is a=>a
}

// Connect to MongoClient
// Note: I won't get into Async/Await or Promises in JS
client.connect(async err => {
  if (err) {
    // if the connection has error
    console.log('Error connecting: ', err);
    return; // stop executing
  }
  
  // initialize db instance
  const db = client.db('stl-health-hack'); // connect to stl-health-hack Database
  const xmls = db.collection('xmls'); // connect (create if not existed, and connect) to xmls collection
  
  const queriedBmfsCursor = db.collection('queriedbmfs').find({URL: {$exists: true}});
  const bmfs = await queriedBmfsCursor.toArray();
  
  // grab all XML URls from BMFs, and construct a GET request for the XML
  // as a form of a Promise (Asynchronous Operation)
  const xmlUrls = bmfs.map(bmf => fetch(bmf.URL).then(res => res.text()));
  
  // xmlUrls is an Array of Promises.
  // I intentionally did so so I could utilize Promise.all
  // to execute all the XMLs requests in parallel
  const xmlsResponses = await Promise.all(xmlUrls);
  
  // Loop through the responses
  // parse them into JSON
  // save JSON into the xmls collection
  xmlsResponses.forEach(xml => {
    if (parser.validate(xml) === true) {
      xmls.insertOne(parser.parse(xml, options));
    }
  })
})

So I only grabbed all the XMLs and pushed them into the database. There’s no actual XML Parsing happening yet which it will in the next query. Now that I have the XML content in the database, I can start running queries on it.

Back to Mongo Shell

// Get all XMLs
const xmls = db.xmls.find({}).toArray();

db.queriedbmfs.find({}).forEach((it)=> {
    // Match EINs
    const found = xmls.find(xml => xml.Return.ReturnHeader.Filer.EIN === it.EIN);
    
    // Initialize update object
    const update = {$set: {}};
    
    if (found) {
        // if has PhoneNum, set PHONE_NUM on the update object
        if (found.Return.ReturnHeader.Filer.PhoneNum) {
            update.$set["PHONE_NUM"] = found.Return.ReturnHeader.Filer.PhoneNum;
        }
        
        // if has IRS990EZ
        if (found.Return.ReturnData["IRS990EZ"]) {
          
            // if has Website, add WEBSITE to update object
            if (found.Return.ReturnData["IRS990EZ"]["WebsiteAddressTxt"]) {
                update.$set["WEBSITE"] = found.Return.ReturnData["IRS990EZ"]["WebsiteAddressTxt"];
            }
            
            // if has MissionDesc, add MISSION_DESC to update object
            if (found.Return.ReturnData["IRS990EZ"]["MissionDesc"]) {
                update.$set["MISSION_DESC"] = found.Return.ReturnData["IRS990EZ"]["MissionDesc"];
            }
            
            // if has Desc, add XML_DESC to update object
            if (found.Return.ReturnData["IRS990EZ"]["Desc"]) {
                update.$set["XML_DESC"] = found.Return.ReturnData["IRS990EZ"]["Desc"];
            }
        } else if (found.Return.ReturnData["IRS990"]) {
            // same process as above
            if (found.Return.ReturnData["IRS990"]["WebsiteAddressTxt"]) {
                update.$set["WEBSITE"] = found.Return.ReturnData["IRS990"]["WebsiteAddressTxt"];
            }
            
            if (found.Return.ReturnData["IRS990"]["MissionDesc"]) {
                update.$set["MISSION_DESC"] = found.Return.ReturnData["IRS990"]["MissionDesc"];
            }
            
            if (found.Return.ReturnData["IRS990"]["Desc"]) {
                update.$set["XML_DESC"] = found.Return.ReturnData["IRS990"]["Desc"];
            }
        }
        
        // if update object is not an empty object, then update
        if (Object.keys(update.$set).length) {
            db.queriedbmfs.updateOne({_id: it._id},update)    
        }
    }
});

The reason why I constructed an update object was because one of the requirements was do not include the field if it does not have data/value.

At this point, my queriedbmfs collection should have quite a bit more data with WEBSITE and PHONE_NUM from the XMLs. But little did we know that the data from the XMLs (IRS) was missing a bunch of data and also contains inconsistent data. For example:

The WEBSITE field has inconsistent values for “No Website”:
- No WEBSITE field
- WEBSITE has value of "N/A"
- WEBSITE has value of "NONE"
- WEBSITE has value of "None"
A lot of organizations do not provide PHONE_NUM

So we’re missing quite a few PHONE_NUM and WEBSITE information which are crucial in terms of Accessibility. After this query-run, it’s starting to get heavily into more JavaScript with web scrapping and stuffs. My teammates were also ready to start playing with AWS Comprehend. All of this will have to wait to Part 2 of the blog because this one is getting quite lengthy. Thank you for getting this far and hopefully you will continue to follow me through this journey in Part 2.

How I Get Started

Mon, 02 Sep 2019 00:00:00 GMT

2019 marks my 2 years of working professionally as a Software Developer. Everyday, I enjoy what I do (that’s a lie 😜). Of course, there are frustrations with the job: difficult clients, hard-to-solve programming problems, or indecisive management.

Programming was not my first career choice but it was my first career and programming has also become a huge part of my life. In today’s blog, I want to share with you all about:

Before programming?
When programming?
How programming?
Why programming?
The Present

Before Programming

In 2010, I moved to the USA at the age of 19 and literally started over 🙀. I went to college for Computer Science (CS) at first without knowing what CS really was. I was just going with it because there’s the word “computer” in it. However in 2012, I decided to drop CS because I couldn’t understand a single word in Engineering Physics class. Had I tried better with my English, I might have had a chance to stay with CS. After dropping physics class, I switched to Information Systems (IS) major and started preparing to transfer to a 4-year institution. 🏫

After the transfer, I started working at this warehouse which deals with Medical Supplies. The young me realized then I liked the way products are organized and distributed. Basically, I was almost tricking myself into thinking I liked Operational stuffs. Then, I decided to lean towards Business side of IS instead of Technical side. How wrong I was!! Last semester came, I had to pass this Capstone class where students have to get in teams, go out to look for our own clients, and solve their business pains using Technology. I was like “I am a Documentations guy” but then I slowly took a role of a Programmer because our team lacked technical people. I wasn’t really sure about my skill at all but little did I know, that decision literally changed my career path. That’s truly when I started Programming. 💻

Disclaimer: I did take programming courses in the previous semesters but I really didn’t pay attention because I truly thought I was going to be a business man. 📈📉

When Programming

For this Capstone class project, our team picked the MEAN Stack. For those of you who have no clues, MEAN stands for:

MongoDB: The most popular NoSQL database
ExpressJS: The most popular NodeJS framework used to build Web Server
Angular (Angular 2+): One of the most popular JS Frontend frameworks developed by Google
NodeJS: JavaScript Runtime that enables running JavaScript outside of the Browser (eg: on the server)

Sounds super cool to me, to be honest. Well, I didn’t really know anything about any of these 4 technologies. Eventually, I was tasked with working on the HTML portion of the Angular side then I closely learned Angular (Yeah, I know. Scary, right?! Angular before JavaScript 😲). Long story short, the following list was my “achievements”:

Spent 150+ hours in the lab learning the MEAN stack with my friend
Quit my warehouse job about a week after midterm. My friend was like “WT…?!”
Got the project finished and graduated with a Bachelor Degree in IS
And most importantly, I realized my passion - Programming

I thought it was super cool and super rewarding when something that didn’t exist came to life through our hard work + technologies and that something actually helped a business grow. Next thing I know, I was determined to teach myself how to be a better programmer. Here’s how.

How Programming

After graduation, I was … jobless and broke. Honestly, I could have just gone back to my old warehouse job and applied for a higher position in the company but I WANTED TO CODE. In addition, it was extremely frustrated at the time because my wife just came to live with me, a broke husband ☹️. On positive note, my wife was very understanding and she was the one who pushed me towards my passion. For 3 months straight after graduation, I coded for 14-16 hours a day for 3 months. My Udemy account was growing like crazy (I know I know, I was tricked by those 9.99 too 😅). Below was a shorten list of the courses I took:

…and a couple more from different sites. During the 3 months of practicing, I also started rebuilding my Capstone’s project (Again, I know, no creativity 😅). But, the good thing was I wrote much better code in this rebuild over what we did in the Capstone class and the time it took was much shorter as well. I’m talking about 2 weeks versus 4 months 🤯.

Next, I started applying for Developer jobs. And it was hard. I had no previous experience, no internship under my belt, and had not gone over any official CS courses. I applied for tons of positions, maybe got one call or two back. Long story short, I was still jobless and broke 3 months after graduation. My wife was frustrated, I was desperate. Then, I contacted my friend from the old team in the Capstone class and learned that he was working for a Dev Shop (basically, a consultant company but we like to call it Dev Shop). That friend introduced me to his boss, Kevin, which is my current boss and I did land an interview with them. I was nervous and happy at the same time thinking: “I cannot screw this up”. Show up for the interview, my interviewer, Chris, made the interview super casual. We talked about how I learned, what I already knew and I got to show my Capstone-project-rebuild and talked about how I did it, what I could have done better. Long story short, somehow they gave me a shot for a Contractor position. That’s OK. I will do my best - I said. To me, I was, and still am, extremely truly grateful towards my bosses and my friend who literally trusted and gave me an opportunity in a life time. On 11th Oct 2017, I started my first job as a Developer. That’s how I programming.

Why Programming

As I mentioned earlier, I found it’s rewarding to be creating impacting products that will either realize one’s dream or make the dream better. It also makes my passion becomes a reality. I just love programming, man. For the past year, I’ve learned so much from people around me and I’ve also made many friends along the way. Programming have been opening so many different doors for me where I feel joy doing what I love. I go to meetups to see, hear, and talk to like-minded people. I join online programming communities to share my experience and knowledge. The whole thing has been rewarding both mentally and financially. It makes my marriage less stressful, my wife less doubtful about her leaving her family, friends, and job in Vietnam to come to me.

All of these things will always remind me about how I get started and the people that were there in the beginning of my career for which they helped launched. Because of that, I will still keep learning about programming, and keep sharing what I’ve learned with others. That brings uttermost joy to me whenever I can use my knowledge to help others, to enlighten others, and to inspire others.

The Present

Currently, I am still a Software Developer at ArchitectNow. However, I give myself a title of: TypeScript Enthusiast. I love TypeScript and have done so many things with it:

I continue to get better at Angular which uses TypeScript as its main programming language
I discovered NestJS, a progressive NodeJS framework, which uses TypeScript
I get to learn ReactJS and apply TypeScript with it. And it is AWESOME
I created a library called automapper-nartc to learn even more about TypeScript. (the library is actually working, just FYI 😛)
I created a NestJS tutorial series on Youtube
- Repository: nest-mean
- Youtube: MEAN Stack with NestJS Part 1
I just built my blog with React, Gatsby and TypeScript. You can check out how I built this blog here
…and more. If you catch me on social media, I’ll tell more.

I can’t believe that it has been almost 2 years since I started on this path and I do not regret any of it. I have many plans in the near future that I will keep updated through this blog. So stay tuned. Check out my socials if you want to reach out. Thanks for reading and I will see you around.

How I Build This Blog

Sun, 01 Sep 2019 00:00:00 GMT

It’s been a while since I first init a “personal blog” project but I haven’t found the time to actually complete one until now. When I first started with the project, I went with Angular and Angular Universal. At the time, I was working on a React project at work so I couldn’t switch context between Angular and React to finish the blog. Then, I discovered GatsbyJS and it changed my mind on how I wanted to build my blog. After a long time (since Gatsby v1), I finally put this blog together and here’s how I did it with: Gatsby, React and TypeScript.

Of course, I haven’t included many other functionality like Newsletter and such. Those are going to be included and will have their own written blog as well. Stay tuned!

React + TypeScript

Since this blog is powered by Gatsby so I will save Gatsby for last. For React, I learned (still learning) React the same way as everybody does, mostly.

React and TypeScript 😍

I am an Angular developer. When I was learning React, I was trying to find similarities between the two frameworks. For instance:

Component Declaration

// Angular
@Component({...})
export class SomeComponent {}

// React
export class SomeComponent extends Component<Props, State> {}

Input

// Angular
@Input() someInput: string;

// React
type Props = {
  someInput: string;
}
export class SomeComponent extends Component<Props> {}

Output

// Angular
@Output() event: EventEmitter;

// React
type Props = {
  event: () => void;
}
export class SomeComponent extends Component<Props> {}

Content Projection

// Angular
<ng-content></ng-content>

// React
{this.props.children}

Fragment

// Angular
<ng-container></ng-container>

// React
<Fragment></Fragment>

Above notes were some of the similarities I was trying to point out when I was learning React as an Angular developer. However, I soon realized that I should have tripped most of my knowledge about Angular specific to learn React better. I was completely lost and confused when I came to learn some React Advanced Concepts like Render Props and then there’s also Redux 🤯. Reusability differs greatly between the two frameworks as well. Although I am comfortable with React now, I wish I would have spent less time getting familiar with it.

As for TypeScript, it’s just a natural and personal choice for me. I love TypeScript and writing React with TypeScript feels really nice to me 🥳. I don’t have any personal note about integrating TypeScript with React but to share my ultimate resources about the two technologies:

GatsbyJS

Gastby is an awesome technology. Though quick to get started, but it’s not quite easy to get used to and start building something for yourself. When I started learning Gatsby months ago, all I did was to pull Gatsby Starters and play with them without the full understanding to actual build something. And I was frustrated 😨.

Up until about a month ago, I returned to start learning Gatsby from scratch. I followed the Gatsby Tutorial from start to finish. Along the way, I was also trying to integrate TypeScript and MaterialUI.

For my personal blog, I want to go with something minimalistic. I’m not the greatest UX/UI person in the world so I rely on a couple of third parties like:

For Theme, I utilize Context in combination with MaterialUI Theming to achieve a simple switch between light 🏙 and dark 🌃 theme. Here’s my ThemeChangerContext:

import React, {
  createContext,
  Dispatch,
  FC,
  SetStateAction,
  useCallback,
  useContext,
  useState,
} from "react";

export type BlogTheme = "light" | "dark";

export type ThemeChangerContext = {
  theme: BlogTheme;
  setTheme: Dispatch<SetStateAction<BlogTheme>>;
};

const context = createContext<ThemeChangerContext | null>(null);

export const ThemeChangerProvider: FC = ({ children }) => {
  const [theme, setTheme] = useState<BlogTheme>("light");

  return (
    <context.Provider value={{ theme, setTheme: useCallback(setTheme, []) }}>
      {children}
    </context.Provider>
  );
};

export const useThemeChangerContext = () => {
  const ctx = useContext(context) as ThemeChangerContext;

  if (ctx === undefined) {
    throw new Error(
      "useThemeChangerContext must be used within ThemeChangerProvider"
    );
  }

  return ctx;
};

And use it on my Layout:

const Layout: FC = ({ children }) => {
  const { theme } = useThemeChangerContext();
  const muiTheme = useMemo(() => buildTheme(theme), [theme]);

  return (
    <ThemeProvider theme={muiTheme}>
      <CssBaseline />
      <ThemeToggler />
      {children}
    </ThemeProvider>
  );
};

const LayoutWithThemeChanger: FC = ({ children }) => {
  return (
    <ThemeChangerProvider>
      <Layout>{children}</Layout>
    </ThemeChangerProvider>
  );
};

export default LayoutWithThemeChanger;

Notice how I use useMemo to cache so when my Layout is rendered and the theme hasn’t changed, I don’t have to execute buildTheme() again.

For overall feels and looks, I just utilize MaterialUI Components where I see fit. MaterialUI Styles is a very important concept that you might want to pick up if you want to use MaterialUI efficiently.

For the content, I will not go over Gatsby API but I want to highlight a couple points:

createPages

I want to have a Pagination on my Blogs page. Here’s what I came up with:

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;

  const result = await graphql(`
    {
      allMarkdownRemark {
        edges {
          node {
            fields {
              slug
            }
            frontmatter {
              title
              tags
            }
          }
        }
      }
      site {
        siteMetadata {
          blogsPerPage
        }
      }
    }
  `);

  if (result.errors) {
    console.error(result.errors);
    throw new Error(result.errors);
  }

  // Templates
  const blogsTemplate = path.resolve("./src/templates/blogs.tsx");

  const blogs = result.data.allMarkdownRemark.edges;
  const blogsPerPage = result.data.site.siteMetadata.blogsPerPage;
  const numPages = Math.ceil(blogs.length / blogsPerPage);

  Array.from({ length: numPages }).forEach((_, index) => {
    createPage({
      path: index === 0 ? "/blogs" : `/blogs/${index + 1}`,
      component: blogsTemplate,
      context: {
        limit: blogsPerPage,
        skip: index * blogsPerPage,
        numPages,
        currentPage: index + 1,
        total: blogs.length,
      },
    });
  });
}

The above will give me each blogs/{pageNumber} for every 10 blog post that I have which is pretty sweet.

graphql

I am a hard-fan on typings so working with graphql in the beginning wasn’t really a pleasant. Luckily, I found Webstorm GraphQL plugin and it literally saved my life (well not really, but it did save my interest in GraphQL). Setup is easy as well:

Install GraphQL plugin
Setup a .graphqlconfig file like following:

{
  "projects": {
    "blog": { // notice of this "blog" name
      "name": "Untitled GraphQL Schema",
      "schemaPath": "schema.graphql",
      "extensions": {
        "endpoints": {
          "Default GraphQL Endpoint": {
            "url": "http://localhost:8000/___graphql",
            "headers": {
              "user-agent": "JS GraphQL"
            },
            "introspect": false
          }
        }
      }
    }
  }
}

Install graphql-cli npm package.
Setup a script (or not): graph: graphql get-schema --project blog. The --project points to the project name you set up in the config.
Run npm run graph against a running Gatsby instance.

The graphql-cli will output a schema.graphql file and this file is all the GraphQL plugin needs to provide intellisense in your GraphQL queries. Awesome 🥳!

You can also generate TypeScript types from scheme.graphql but the types aren’t really helpful since they’re all of type Maybe<T> and it requires a lot of null checking in your code.

End

Rather than the points that I mentioned above, it all comes down to your own Customization and how you want your blog to look, act, and feel like. Gatsby is a great tool that will allow you to build a full SEO-supported personal blog (or even more). Utilizing React allows you to build your components in a more concise and performant way. Overall, putting this blog together was a joy to me and I will definitely keep working on it to include more features in the future. Thanks for reading!