DEV Community: Sergey Nikitin

Adapting One Old UI Components Library To Work In TypeScript Code

Sergey Nikitin — Sun, 08 Aug 2021 19:48:18 +0000

THE first public version of TypeScript appeared more than 7 years ago. Since that time it grew up and brought many incredible features for developers. Today it slowly becomes a standard in the JavaScript world. Slack, AirBnB, Lyft, and many others add TypeScript into their tech stack. Teams use TypeScript for both browser applications and NodeJS services. There are always pros and cons to this decision. One disadvantage is that many NPM packages are still written as JavaScript modules. We experienced this issue as well when decided to migrate our applications to TypeScript. We had to implement type definitions for our internal UI components library. We wanted to get a tool, that could serve developers as additional documentation. We also wanted to collect everything engineers can use while working with the JS library, in one place. I am going to tell you what steps did we take to achieve the desired solution.

Type definitions

You can describe all data that are being exported by a particular JavaScript module. The TypeScript analyzer will pick it up and will handle the package in a way you defined it in the type definitions file. The approach is close to C/C++ declaration files. Here is a simple example, imagine you have a trivial JS module:

// sample.js

export const pageSize = 25;
export const pageSizes = [25, 50, 100];
export const getOffset = (page, pageSize) => page * pageSize;

one simple `sample.js` module might look like this

You can use the sample.js module in TypeScript code without any problems. But guess what? The analyzer would not be able to run autocomplete and infer types properly. If we want to rely on help from smart tools, we need to manually describe the API provided by our JS module. Usually, it is pretty straightforward to do:

// sample.d.ts

export const pageSize: number;
export const pageSizes: number[];
export const getOffset: (page: number, pageSize: number) => number;

standard way to declare types for TypeScript is to create an appropriate `.d.ts` module

Note that definition files have priority over JavaScript modules. Imagine you removed export const pageSizes = [25, 50, 100] from the sample.js module. TypeScript would still think it exists, and you will get a runtime error. It is a known tradeoff to keep definition files in sync with real JavaScript code. Teams try to update type definitions as soon as possible to provide a smooth experience for other developers. In the meantime, this approach allowed the TypeScript codebase to raise gradually without having to rewrite the whole JavaScript ecosystem.

There are many examples of how to write type definitions. Most of the time you will meet simple cases and thus would be able to find something similar in the repository called DefinitelyTyped, where developers store definitions for NPM packages. You can also learn more about the type definitions feature in the official documentation. It is not a part of this article.

Our JavaScript library

In our company, we develop an internal UI components library. We use it in our products from the beginning, and the current production version is 12. You could only imagine how much effort it would take to rewrite such a big thing. In the meantime, we write new features using the TypeScript language. The problem is, every time one team goes to implement a new code, they write a small copy of the UI library definitions. Well, this does not sound like a good process, and we decided to have a separate package with complete type definitions for our UI components. Key points here are:

We would be able to import this package during the new repository initialization. This will allow controlling the version and simplify the refactoring during the version update.
We would stop copy-pasting the same code again and again.
Type definitions is a great documentation source. I bet developers would prefer to select the method from IntelliSense suggestions rather than go to the web page with all API descriptions and copy the method name.

So what is wrong?

Now you may ask me, what is wrong with our library? The thing is that we inject some global variable to interact with the exposed API. In addition, we want to import some constant pre-defined values (icons, table cell types, tag colors, etc.) that can be used by the UI components. They usually come in form of constant identifiers that help to style components.

For example, we can style a button with one of the types:

// lists/button.ts

export enum ButtonType {
  Primary = "ui-primary",
  Secondary = "ui-secondary",
  Danger = "ui-danger"
}

depending on the value, the button will be rendered in a specific size and color palette

We came to an idea to store all library-specific values in one place. So this project became not just type definitions for the UI library, but a real package! It should represent the exact library state at some specific version. And this is interesting - how can we implement this? Let's state what we want to achieve as the result:

We want the global variable ui to be accessible without having to import anything.
We want our UI components definitions to be available without having to import anything as well.
We want to use predefined constants and objects for UI components by importing them from our types package. There should not be any conflict to assign some type from the library in this case.

Sounds like a small deal, right? Let's write some .d.ts file with type definitions and... Oh, wait, you can't put real code (constants, enumerable lists, and other stuff) in the .d.ts file! Sounds reasonable. Let's create a regular .ts file and put all these enums there. Then we... well, how can we apply globals in the .ts file?! Meh...

We did not find an example of how to do that, really. StackOverflow is flooded with the .d.ts vs .ts concept war. We had nothing but digging into TypeScript documentation and finally introduced the code that meets our requirements.

Start from the scratch

First things first. We write interfaces and enums as usual. I am going to provide code examples in a simplified matter, so we would focus on the approach, not the particular code features. Imagine we have a notification dialog, so we write something like this:

// interfaces/notification.ts

import { ButtonType } from "../lists/button";

export interface NotificationButtonConfig {
  text: string;
  type?: ButtonType;
}

export interface Notification {
  info(text: string, buttons?: NotificationButtonConfig[]): void;
  warning(text: string, buttons?: NotificationButtonConfig[]): void;
  error(text: string, buttons?: NotificationButtonConfig[]): void;
}

simple notification API allows assigning a text message and buttons

Where ButtonType values are from enum we saw already:

// lists/button.ts

export enum ButtonType {
  Primary = "ui-primary",
  Secondary = "ui-secondary",
  Danger = "ui-danger"
}

we highlight a button according to the type

Then let's take a look at the simple case. We don't import anything, as the UI components expose the global variable, and we want to call a notification:

// example/application/moduleNoImport.ts

ui.notification.info("Document has been saved!");

we call a global API to show the notification dialog without custom button configuration

What do we need to do to make it available? We are going to enrich the global namespace with the ui variable:

// index.ts

import { UiLib } from "./interfaces/ui";

declare global {
  let ui: UiLib;
}

we simply add a new variable into the global namespace

UiLib here describes everything our UI library exposes into the global scope. In our example, we have a list of methods that show different kinds of notifications:

// interfaces/ui.ts

import { Notification } from "./notification";

export interface UiLib {
  notification: Notification;
}

all the notifications API is collected under the Notification interface

This is almost it. Lastly, we adjust the package configuration. We tell TypeScript to emit type declarations by adjusting the tsconfig.json:

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "dist/",
    "outDir": "dist/es"
  }
}

always emit declaration files

We now control how TypeScript emits the output. We also specify a path to our types in package.json:

{
  "main": "dist/es/index.js",
  "types": "dist/index.d.ts"
}

don't forget to set up a build step for your package to compile TypeScript files

Alright, then we install the package in our project. Finally, we specify the package path in the project's tsconfig.json (since we don't use the default @types folder) to see that it works!

Using the values

Now let's go deeper. What if we want to create a notification with some specific button? We want to be able to write something similar to this example:

// example/application/moduleWithImport.ts

import { UiCore } from "ui-types-package";

const showNotification = (message: string): void =>
  ui.notification.info(message, [
    { text: "Sad!", type: UiCore.ButtonType.Danger }
  ]);

we want to show notifications with the button of Danger type

Note here and below UiCore is a namespace that contains all the enums, configs, interfaces our UI library operates with. I think it is a good idea to collect everything under some namespace, so you would not think of names for each interface. For instance, we have a Notification interface. It sounds quite abstract, and it takes a while to understand the exact object behind the naming. In the meantime UiCore.Notification clearly describes where it comes from. Having a namespace is just an optional but convenient way to handle such things.

Right now we can't import UiCore from the library as we don't export anything. Let's improve our code and form the namespace:

// namespaces/core.ts

import * as notificationInterfaces from "../interfaces/notification";
import * as buttonLists from "../lists/button";

export namespace UiCore {
  export import NotificationButtonConfig = notificationInterfaces.NotificationButtonConfig;

  export import ButtonType = buttonLists.ButtonType;
}

we use composite export to create an alias for objects under the namespace

We basically export all data we have under the namespace with export import alias syntax. And, since the main package module is index.ts in the root, we write a global export to expose the namespace to the public:

// index.ts

import { UiLib } from "./interfaces/ui";

export { UiCore } from "./namespaces/core";

declare global {
  let ui: UiLib;
}

we export UiCore, and now it is available from the outside

Two simple steps to achieve our goal! Now we can import some enum and enjoy writing the code. OR. Or we can think of some other use cases. In the example above, we used the ButtonType.Danger value to create a notification with some pre-defined button. What if we want to use ButtonType as a parameter type?

Covering edge cases

We are not going to use some particular value, so we expect to access the type UiCore.ButtonType without having to import anything. Currently, we don't have UiCore in the global scope and thus the code below does not work:

// example/application/moduleWithType.ts

const showNotificationWithButton = (
  buttonText: string,
  buttonType: UiCore.ButtonType // <-- TS2503: Cannot find namespace 'UiCore'
): void =>
  ui.notification.info("hello world!", [
    { text: buttonText, type: buttonType }
  ]);

TS2503: Cannot find namespace 'UiCore'

Obviously, we are going to add the namespace in the global scope. Unfortunately, we can't just use the namespace created earlier, we need to define a new one. The trick is to create a new namespace with the same name and with almost the same data included. Good news: instead of importing everything again, we can use our existing namespace to clone the data in form of types:

// index.ts

import { UiCore as _UiCore } from "./namespaces/core";
import { UiLib } from "./interfaces/ui";

export { _UiCore as UiCore };

declare global {
  namespace UiCore {
    export type NotificationButtonConfig = _UiCore.NotificationButtonConfig;

    export type ButtonType = _UiCore.ButtonType;
  }

  let ui: UiLib;
}

we create types from the existing namespace using the type alias syntax

We first rename the UiCore import as we want to avoid name conflict. Then we re-export UiCore under the correct name as it was done previously. Finally, we copy the UiCore namespace items under the global scope. Both namespaces (UiCore and global UiCore) export the same data. The only thing I want to draw your attention to is the way how we write export statements:

// UiCore under the global scope
export type ButtonType = buttonLists.ButtonType;

// UiCore that can be used as a value
export import ButtonType = lButton.ButtonType;

different syntax for each case

You can see the global namespace uses type alias syntax to define objects. For import statements, we want to have values (not types) accessible, so we can't use the same approach there. Instead, we import values and re-export them under the namespace using the composite export import operator. Thus, we collect all the constants, models, enums, interfaces under some common name, we can name it whatever we want, and it will be a single entry point for all our UI library-related data. As the result, we collected all data in one place, and the developer experience does not change from using the global object to having to import something.

This part is a tradeoff to get all usage cases working. It adds some copy-paste routine, but then it is a comfortable way to supply developers with type definitions: we can use the global variable exposed by the UI library as we do in JavaScript modules — without having to import anything. Then we can import the package and use constant values. All of them are defined and ready to use. The existing code will remain the same. And yes, we do support the new import type { UiCore } from "ui-types-package" syntax which was introduced in TypeScript v3.8 to define types. There is no conflict with our implementation.

Conclusion

You can find thousands of existing type definitions for JavaScript libraries. In this article, I tried to explain some specific edge case, where along with type definitions, the package needs to contain real values. We use this approach for our UI components library to style table cells, specify icons, and more. You can achieve such capabilities by following these steps:

Create and set up a new NPM package.
Describe the whole interface supported by the JavaScript library you want to write type definitions for.
Declare the global object that is being injected into window.
Create a namespace made of objects you have defined already - you will use it for import statements.
Create a namespace made of types based on the previous namespace. It will be located in the global scope.
Verify that we assigned the same name for both namespaces.

This small guide makes it possible to cover all potential use cases for any available JS library. In the end, you will get a package, that is easy to use, support, and extend.

The name UiCore, the package ui-types-package, and all objects in the article are placeholders to show the approach. You can use whatever names you want for your libraries and follow the idea described here.

Complete code example is located here.

What I Learned From My Contribution to Angular

Sergey Nikitin — Fri, 02 Apr 2021 16:28:37 +0000

ANGULAR 9 has come, and you might notice my name in the commit history. This was the first time I contributed to such a big and widely-used project. The journey appeared to be easy enough and very exciting! Was it so? Let me tell you the story.

In our company, we went through a bunch of technologies and approaches on how to develop frontend code. Initially, our service was written using the Grails framework — Java-based MVC server-side rendering engine. JQuery used to add some interactions with customers on the page which was quite common those days, but you definitely don’t want to see this in 2020.

A few years later, AngularJS showed up and it was like fresh air in frontend development. Services, components, template rendering engine, etc. We were happy to implement AngularJS on our platform and wrote over 700k lines of code.

Time flew and one day Angular (which was expected to be AngularJS v2) was released. The problem was that these two things are not compatible with each other, so our codebase became legacy at one moment. I pushed hard to update the version of the AngularJS and gave up on v1.5.11. What was the solution? We decided to keep existing applications as it is and to select a new way to write frontend inside the company. The thing is that our platform consists of independent applications each of them loads unrelatedly to others. Thus, every application can be written using any library or framework the team decided to use.

First of all, we switched to build js code with Webpack and removed Browserify for goods. This brought us a lot of opportunities like how we split bundles, what JS features are supported, and so forth. Then the time has come and we added Typescript. After all, we implemented React on the platform. Currently, engineers develop new applications using React. But fair to say that our vision remains the same: each team decided what to use on their own. Some teams still use AngularJS because it is too difficult to re-implement existing logic. Others still fix Grails applications (yes, we still have a few of them in production at the moment!).

The idea to tune up the infrastructure for Angular was flying in the air, but it was quite tricky until we started to use Webpack. With Webpack it seemed to be an easy deal: load CSS modules with raw-loader, fix Jest HTML templates loader and we good. Good enough? I thought so until we started to write an application based on the Angular framework…

Something Went Wrong

The problem appeared from a place we did not expect. Let’s make some introduction: we use UI component package which renders a beautiful and strict UI experience for our clients. This library is framework-agnostic and acts quite similar to Material UI components for Angular i.e. developer forms a specific HTML layout to bring particular component into action, populate and style components by applying pre-defined element classes and tags. Also, one can access any element in the JS code and play with it dynamically.

So it was my colleague Irina, who found an interesting issue. She was the first person to try Angular on our platform. Historically, the UI components we use rely on the HTML element attributes. These attributes have the form of data-ts or data-ts.something. For instance, if we want to implement a modal window, we should add the title by setting data-ts.title attribute:

<dialog data-ts="Modal" data-ts.title="some-title">
    <div data-ts="Panel">
        <p>Modal content.</p>
    </div>
</dialog>

Pretty straightforward, right? But what if we want to apply the title dynamically? Let’s say we want the title to contain a user name or something like this. What should we do? Yes, Angular provides a standard way to interpolate the attribute value from the controller property:

<dialog data-ts="Modal" [attr.data-ts.title]="modalTitle">
    <div data-ts="Panel">
        <p>Modal content.</p>
    </div>
</dialog>

Here we go! But wait… what?! This does not look good in the browser:

You may notice here that the Angular compiler went through the HTML template and parsed attributes in the wrong way. For attr.data-ts.title symbol it generates data-ts attribute instead of data-ts.title. This completely breaks the layout and the modal window does not work. UI components even don’t know that I defined a modal window because the attribute was overridden with the result of interpolation. It sounds like a real blocker that prevents us from using Angular.

Trying to Find a Solution

I tried to google the solution but had no luck. I felt like it is meant to be a very specific case nobody noticed really. Fair enough. On the other hand, if HTML standard supports this type of element attributes and browsers render them correctly, so should Angular compiler do. Taking this into account, I decided to ask Angular team directly. I went to Angular GitHub repository and opened an issue. The beginning was promising, they marked my issue with tags that highlight that the bug exists in the Angular compiler and the issue has low priority. What happened next? I started waiting…

…After 2 months nothing really happened. I figured out that since my problem is not something major, then there are low chances to see it fixed any time soon. The team is busy making the Ivy engine into a stable version. Nonetheless, they confirmed the bug exists, so they would not be against me fixing the issue by myself. Okay then, I am doing a fork of the Angular repository.

I am Going to Fix the Bug

First of all, I drew my attention to the CONTRIBUTING.md file and read it carefully (consider making a project fork to be my zero step). This file describes all the rules I should follow so Angular team will proceed with my Pull Request. It explains the responsibility of the parties, code ownership, agreement on the commit message format, test coverage requirements and many other questions.

Next, you need to sign the Contributor License Agreement with Google company which confirms you are okay with all contributing rules and restrictions. The CLA link is located at the end of the CONTRIBUTING.md file so read the whole text until the end. Finally, paperwork comes to an end, let’s dive into the project itself.

Angular is a typical yarn project, just big enough. You can simply run yarn install and it will setup all the environment. Well, okay, simply run yarn install and simply wait for 5–7 more minutes — I told you this is a big one!

I stopped for a second at this point, because I was looking forward to an exciting journey — to go through the source code. It was scary in the beginning to figure out what is going on in such a huge project, tons of modules, different pieces of code interact with each other. But after spending some time I came to the conclusion that big projects mean to be a big advantage.

When your project becomes huge, you focus on absolutely different things that might sound meaningless when you have just a few files. Different things, different approaches show up to be the priority. In the Angular, I saw that the project structure is a super important thing. Every module has a meaningful name, every variable document itself, every method shows what it does exactly. It is quite easy to navigate through the framework parts and the understanding of what this or that module is for comes to your mind instantly.

I already knew that my issue lays somewhere in the Angular compiler and it was quite easy to find the exact line:

Well, what is this? We receive an HTML element attribute (stored in the boundProp). Then we split the attribute name by some delimiter to figure out if it contains “attr” prefix. If the first part is the prefix, we consider the attribute name to be equal to the second part. Obviously, this is not correct, we should concatenate all the parts except the prefix instead. Let’s fix it:

Perfect! Now we need to make sure other changes would never break our functionality. I am going to write a test. It is quite easy to do in such huge projects like Angular. There is a requirement to cover any code change by unit tests so you definitely will find a spec file along with each module in the repository.

So I opened that spec file and saw a bunch of tests that cover the module I have changed. I went through the 2000 lines of test cases and found the test which checks the name of the attribute after compiler parsed some HTML element. Made a copy and changed attribute name, so now it contains a dot delimiter and fixed the output expectation. That’s it. Now my changes are covered! I thought it would be tough, but turn out it was super easy:

Well, I fixed the code. Writing a commit message keeping in mind the format team asked to follow and… going to the kitchen to make some tea as the pre-commit hook launches all unit tests in the project. Can you imagine having 37000+ tests in the project? The first launch will take a while, but then test results will be cached and next runs will take much less time. I made a commit, opened a Pull Request, started waiting…

Resolution

…After 2 months I decided waiting is enough for me. The code was the smaller problem, the bigger one was how to proceed with my changes? It was clear to me that I need to find a person who is somehow related to the Angular team and discuss what options I have right now. I applied the social engineering approach and went through the latest contributors to the Angular compiler module. Andrew Kushnir was the first on my mind. I found his Facebook account and wrote him a message. Unfortunately, a week after I did not get a follow back and decided not to be annoying for the person who doesn’t know me. I decided to have another try and found Pete Bacon Darwin. I noticed that his profile has an email address so it might be useful even in 2019. And it actually did work!

I wrote a long email describing all the little things we struggle with. Described our UI library, attached links on the issue and pull-request. I told about myself and my company. And most important I was really thankful as expecting Pete to spend his own time on my problem.

The next day I found a message from Pete. He told me that he is okay to contact via email about my pull request and that he never saw people define attributes with dot notation. He also gave me a piece of advice on how to write an accurate commit message. And then, he approved my code changes. After this, all happened with the speed of light… while I was sleeping. (guess why? 12 hours difference between the US and Novosibirsk — the place where I live)

While I was sleeping, the Angular team moved my pull request into a release state. They ran another set of tests (I guess they were integration tests this time) and figured out that in one test there was an SVG-block with some interesting attribute [attr.height.px]=”16". It used to be rendered as height=”16", but with my changes, it became height.px=”16". After a small discussion, they decided to fix that SVG block and to merge my changes into Angular. This meant that my fix will show up in the upcoming major version of the framework!

My commit was merged, my pull request was closed. I just got up in the morning and saw all these comments, was scared, upset, and glad at the same time.

In the evening I got an email from Pete. He confirmed that my fix will be released with Angular v9 and thanked me for contributing to the project.

From my side, I paid appreciation for the time he spent on me and for all the help. I said that it was quite an important step for me to make things right and to make a success.

You may ask me what’s next?

Next few months I was waiting for the release. I noticed that my changes came with Angular 9.0.0-rc.2. And now, literally, a month ago they have released the stable version of the Angular 9.

The outcome

For me, it was a success story. We finally got Angular based applications working on the platform. But the most important thing here is that I did my best to gain the result. So, go all the way and never give up. Try different ways to achieve what you want. Push the stuff you think is right. Look for people who can help you to find a way to deliver.

If you see a big popular project in front of you, it does not mean you can’t influence it. If you have an idea or you believe something works not as expected — just try. Even if the cost of your changes is a one-line fix. In most cases, the team is open to external contributions and any help from other developers. They might have no time to fix this or that issue. So you are welcome to offer your help.

I have this article posted in Russian as well, so if you want you can read the translated version here.