How to create an Angular wrapper around an existing Javascript library?

Question

I have a pure javascript library that users can install via npm. I want to add/create an Angular "wrapper" to this library so that it can be used seamlessly within Angular projects but I am not sure how to do this. I am using Angular-cli v6.

This is very similar to How does one go about creating an Angular library wrapper for an existing Javascript library?, however the only response is a link to ng-packagr. I have done a few tutorials on creating a library with ng-packagr, however they don't describe (and I can't find examples elsewhere) of how to create a wrapper around a non-Angular JS library.

Any help is greatly appreciated! :)

Answer 1

An old question but I love it. There's no one simple answer to it, so here's how I did it:

Short version

Read about the internals and how I wrapped the Google Maps Javascript API library

Long version

The following is very abstract, but this is an abstract question, so here goes...

The basic things you probably need to implement are:

1. Detecting changes in your Angular library and delegating them to the native library.
2. Detecting native events and bubbling them into your Angular library.
3. Switching execution in and out of Angular using NgZone.

Other considerations might be performance, scalability, adding new tools over the existing ones, etc. No matter what library you're dealing with, you'll probably end up wrapping a function with a function, a class with a class, a module with a module, etc.

The question arises: "Am I supposed to manually write all that code? Am I seriously going to write a method for each native method?? What happens when the native library changes implementation? I would have to change my code everywhere... 🤔"

To simplify and make your wrapping library scalable, you could automate the wrapping mechanism (one way is using a Javascript Proxy) object. Combine it with TypeScript's utility types and extension interfaces, and you can create a class that automatically delegates calls to the relevant native object/function, AND you'll get intellisense (for methods that you didn't need to manually implement in your wrapper!).

Here's a more detailed explanation with examples

For events delegation, you could create a mechanism that generates observables (or EventEmitters) for your native events.

In some cases you should consider using NgZone.runOutsideAngular() to prevent unnecessary change detection runs for code that is executed in the native library. On the other hand, you should consider using NgZone.run() to bring execution into Angular's zone when running native code that should enter and affect change detection cycles.

My Angular Google Maps library is open source and you can have a look. I have implemented some very interesting architectural mechanisms in it. Anyone running into this post and wants more details or help is welcome to contact me.

Cheers 🥂