DEV Community: Yann L

Typescript enums drawbacks and solutions

Yann L — Wed, 22 Dec 2021 12:12:21 +0000

Typescript has for years an enum feature that is very similar to the C# one. However, when run, Typescript is Javascript and enum have to be transpiled. The result is not so satisfying than what we could expect as it's very verbose. In this article we'll see why it's so verbose and what other solutions can improve our code.

The problem of TS enums

Typescript's enums are very handy because there's nothing like enum yet in Javascript, probably because a JS object is very close from an enum already. But when we write TS code, the enum informs about readonly state, which is something that can't be done easily from the object (well this is not true anymore... read further).

However, at build time, the TS enum has to be transpiled to an object. The result will be a very verbose transpiled output for something that could be simply an object structure. The developer has then to choose between a lighter output by using an object or a better typing comfort by using the enum type...

Here's a concrete example of enum transpilation in TS
(TSConfig's target = es2017)

export enum EHttpStatusCode {
    Ok = 200,
    BadRequest = 400,
    Unauthorized = 401,
    Forbidden = 403,
    NotFound = 404,
    ServerError = 500,
}

will transpile to the following JS

export var EHttpStatusCode;
(function (EHttpStatusCode) {
    EHttpStatusCode[EHttpStatusCode["Ok"] = 200] = "Ok";
    EHttpStatusCode[EHttpStatusCode["BadRequest"] = 400] = "BadRequest";
    EHttpStatusCode[EHttpStatusCode["Unauthorized"] = 401] = "Unauthorized";
    EHttpStatusCode[EHttpStatusCode["Forbidden"] = 403] = "Forbidden";
    EHttpStatusCode[EHttpStatusCode["NotFound"] = 404] = "NotFound";
    EHttpStatusCode[EHttpStatusCode["ServerError"] = 500] = "ServerError";
})(EHttpStatusCode || (EHttpStatusCode = {}));

Pretty verbose isn't it?

Why does Typescript generate all this code?

The reason for that is Reverse Mapping. In short, the reverse mapping allows you to pass the value to the enum to get a literal value.

The good point of this reverse mapping is that if it was not provided, but we would need it, then we would have to write some logic like following:

function getEnumKeyByEnumValue<T extends {[ index: string ]: string}>(myEnum: T, enumValue: string): keyof T |null {
    const keys = Object.keys(myEnum).filter(x => myEnum[x] == enumValue);
    return keys.length > 0 ? keys[0] :null;
}

There's a cavehat tho, and it's that most of the time we don't need this reverse mapping... So we're basically bloating the bundle with useless code more than we should.

String enums have no reverse mapping

Something interesting to know is that string enums are handled differently by the compiler. If you compare a string enum and another type of enum (ex: number), you'll quickly notice that the transpiled code is different for the string value. It's now a simple enum without reverse mapping, but still it's more verbose than a basic javascript object.

So if you were trying to use reverse mapping on a string enum, then now you know why your code is not working as expected.

Alternatives to enums

Verbosity of the transpilation is something that was heard by the TypeScript team and they now offers alternatives:

The const assertion feature

The const assertion feature will help us keep a lighter bundle, but at the same time it will give us the same typing feature than the enum.

This is how to use it:

declare the object like you would in plain JS
add as const after the declaration

export const httpStatusCode = {
    Ok: 200,
    BadRequest: 400,
    Unauthorized: 401,
    Forbidden: 403,
    NotFound: 404,
    ServerError: 500,
} as const;

What this declaration will do, is create the object, but also inform TS that all the properties and the object are readonly.
Talking about the output bundle, the Javascript transpiled result will be exactly the same but without the as const statement for sure.

However we still miss the typing feature

So now yes we have the enum declaration, but we still miss the Type which will be used by TS to type check our code.

For TS check, we will need 1 more declaration (here below it's an example of how you could try to declare an enum property, but...)

class HttpResponse {
 code: HttpStatusCode = 200;
// other stuff here
}

This won't work because our object is a value and we can't directly use it as a type. So we will need to extract the type from it:

type HttpStatusCodeKey = keyof typeof httpStatusCode;
export type HttpStatusCode = typeof httpStatusCode[HttpStatusCodeKey];

Now we have the real type which is representing the union of the httpStatusCode object's values. And the good news is that this type is only used for building TS and is then removed from the transpiled output. So the only thing JS will have is the object.

On TS side it will then be very easy to type the code like

class HttpResponse {
 code: HttpStatusCode = httpStatusCode.Ok;
// other stuff here
}

Also notice the casing convention. The object const is camelCased (httpStatusCode) because it's a value. On the other hand, the type extracted from the object is PascalCased (HttpStatusCode). So it follows usual convention and is then easy to differentiate type from value object.

Const enums

The const enum is exactly the same syntax than a standard enum, but with a const prefix.

export const enum EHttpStatusCode {
    Ok = 200,
    BadRequest = 400,
    Unauthorized = 401,
    Forbidden = 403,
    NotFound = 404,
    ServerError = 500,
}

However this slight difference will become a huge one in the transpiled output. See here what will come out:

You read it correctly, there's nothing... The reason for that is that the whole enum is now virtual. And when you will use its value, the value will directly be printed instead. It's like a swipe of the enum to a value at compile time.

Conclusion

Typescript enum is a C# flavor brought to Typescript. It's an innocent syntax when you're coming from C# code, but it can be harmful to the end user. The typescript authors are also aware of this pitfall and are doing great work to provide alternate solutions. So if you don't know what to use you can follow this logic:

Do you need reverse mapping? (If you don't know, then the answer is probably "No")
If Yes, and your enum is not about strings, then you'll have to use a standard enum
If No, continue to the next point
Do you need to loop over enum members?
If Yes, then use const assertion
If No, continue to the next point
Use const enum and live happy

Feel free to share your thoughts in the comment 💬 or to like 👍 the post if it was interesting for you.

Angular library with demo project

Yann L — Tue, 07 Sep 2021 11:17:01 +0000

Angular, with the help of angular-cli makes it easy to create a library project. But when your library is about components, it's very useful to have a visual rendering of what you're creating, and not only the lib code and tests.
In this article, we'll see how we can easily create in a same project, the library and the demo app, but still keep a coherent structure like we need for a library project.

Generate the Angular workspace

Like for every Angular project, the first step is to generate the workspace for your library:

ng new my-lib --createApplication=false # for Angular < 16
ng new my-lib --no-create-application # for Angular 16+

⚠ Don't forget the createApplication option so that you don't generate the skeleton of an app inside of your workspace. We will see later how to organize the project structure.

Now you should see the base Angular workspace, with a project folder to correctly structurate libraries and demo app.

Generate the library in the project

Angular-cli can generate the library project scaffolding for you with the command

ng generate library myLib

You should now have a my-lib folder inside projects and that's where you will place all components related to the library you're creating.

If you open the ./tsconfig.json file, you should also see the path property that was created with the information about your library. This will be useful later to easily import it from the demo app.

In ./tsconfig.json

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

Generate the demo app

To generate the demo app, Angular-cli again provide you a command for scaffolding generation.

ng generate application demo

As you noticed, this time, we don't use the library keyword, but the application one. The generated project will be different as it can be "started" to be debugged in the browser.

The difference of using generate application command, instead of doing this at the first step with ng new my-lib, is that it allows a workspace name different from the initial app name, and ensures that all applications reside in the /projects subfolder, matching the structure of the configuration file.

More info in the angular-cli documentation.

Import the lib in the demo project

Now that you've created the components you wanted in the lib and also the demo project to see your component in the browser, what you're missing is the glue between both.
This link is done by importing your library module into the demo project. As we have seen, the tsconfig was automatically updated with the new path, so now in your project, you just need to specify the import with the path key, like:

In demo/src/app/app.module.ts

import { MyLibModule } from 'my-lib';

That way, when the build is started, it will detect the my-lib path, and with the help of the config, it will know where to look for to import the module correctly.

Don't forget to build

One last thing to consider, is that in this tsconfig.json file, the path is looking for the dist folder. But this one doesn't exist yet. This mean that if you want your demo project to find your library components, you will need to build the library first.

For that purpose, you can add a script in the package.json file to easily build the lib every time you need it to be updated.

In package.json

  "scripts": {
    "build-lib": "ng build my-lib --watch",
    ...
  }

And then simply build the lib with

npm run build-lib

🧐 If this article helped you in a way, don't hesitate to share it or comment 💬

Credits

Cover image by @samuelwu

Typescript cast is a type breaker

Yann L — Thu, 17 Jun 2021 10:28:51 +0000

Cover image by Pankaj Patel on Unsplash

The Typescript types and "cast"

Everyone is aware that the any type is a bad thing because it would basically be like coming back to Javascript where there's no strong type check and anything is allowed.

But even if we respect this rule, we can fall into another pitfal where we break Typescript's type-check by casting types. Following chapter will describe you why and how to avoid it.

Typing the code

Type creation can be done in several ways in typescript. It can be anonymous, interface/class declarations, type aliases, duck-typings, etc. (See everything in the doc)

But when it comes about typing a variable, there's one syntax only which is with colon :.



const mystring: string = 'hello'; // this example could be duck-typed, but yeah, focus on the colon

By typing a variable, TS will know what type it is, and check that the content of the variable is valid with the given type.

The following example shows exactly this behavior, the compiler will tell you that your definition is not valid according to the type you've defined.

Casting the code

The cast syntax is done either with the as keyword, or with the angle-bracket notation <...>. The former being probably better (opinionated) as it can't be confused with the angle bracket notation for generic types.



const duck = animal as Duck; // 'as' keyword notation
const duck = <Duck>animal; // angle bracket notation

If instead of typing it, you use a cast, TS will know the type of your object, but won't make any type check, because casting the variable is about saying to TS "Trust me, I know what I'm doing!".

The same example casted would then look like following and wouldn't raise any error:

Needless to say that this type check "break" is where it becomes dangerous and that's why we should not confuse types and casts.

In fact it was so confusing that even TS developers have added a new feature (the unknown type described later in this page) to prevent some unwanted casts and force developers to explicitly cast completely different types.

When is a cast ok?

Like in every other strongly typed languages, a cast in the code is mostly only about polymorphism.

Here are some example:

You're precising the type with inheritance

Like in other languages, that's basically the reason for a cast. When you have an object of a certain type group and want to precise the exact type because you now know more about it.

You're precising the type from union types

The same can also be done when you're defining the type from a union type.

You're infering a type from an external input

It can be that a type comes from an external input and you have no idea what type it is. In that case, it's a mix between both previous reason.

As an example, it could be a DOM API like the following where you specify the precise type in a generic syntax



// here TS won't know what element you're accessing. So it will by default use HTMLElement | null
// But we can cast it to what we know it is with the angle-bracket syntax 
const aFieldInTheHTML = document.getElementById<HTMLInputElement>('username-field');

Best practices when doing a cast

Always Guard

One thing to not forget is that the cast is only existing in typescript. Once compiled, it's javascript and there's no mention of the type anymore. For that reason, casting is not enough and you have to first check explicitly (= Guard) the value to ensure it is what you think it is.

Type predicates and guard functions

To help you writing guards and cast in one shot, Typescript developers have created type predicates like the is keyword below (See official documentation).

By using them, simply calling this function will cast the variable automatically and correctly from where the guard is called by refering to the returned boolean.



const possibleFish = { swim: () => console.log('swim') };
if (isFish(possibleFish)) {
   // here the variable is infered as a Fish

The `unknown` type to explicitly force cast

In recent release of TS (v. 3+), they've added a new type: unknown. (See official documentation).

This type is used to define a type that we don't know what it is, but where we don't want to use any to not completely "disable" type check.
New TS version will also force to use this type to prevent you to cast completely different object, as doing so would look like a buggy implementation. And if you really have a good reason to do so, then you're adding an additional cast to unknown to make everyone aware it's intended.

Let's think about a use case where you want to cast an object to another, but you know they've nothing in common. It's not from a union type, it's not from inheritance, it's just completely different, like casting a pizza into a tree: 🍕 ▶ 🌳.

It's something that should probably never happen, and that's why TS doesn't allow it as easily as before. If you try it, here's how it will look like:

with the following error



Conversion of type '{ price: number; size: number; ingredients: string[]; }' to type 'Tree' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
  Type '{ price: number; size: number; ingredients: string[]; }' is missing the following properties from type 'Tree': color, height, age(2352)

Typescript detected that this cast is probably a mistake, and tells it to you. If now for a mysterious reason, you think it's totally ok to cast a 🍕 ▶ 🌳, you can force that cast by casting into unknown first. This will tell the compiler "Trust me, I know it looks wrong, but YOLO!!".

Conclusion

Typescript is about typings, but you always have a way to break the typing for good or bad reasons. So here are some key advices.

Always type (not cast) all your code but forget the any as much as possible.
If you have to cast, it's a polymorphism-like reason, or it's probably a code smell.
If you want to cast for another reason and you're sure it's justified, then use the unknown type, and maybe add a comment about the reason for future readers 🙏.

Last but not least, don't forget one important rule:

Typescript is only about types in your IDE/compiler. Once it's running in the browser/engine there's external factors in the game, and nothing will prevent your code to be of the wrong type! => be defensive.

Tell me in comments 💬 if you see other valid use cases for casts than the one listed above.
Thanks for reading 🤘

DEV Community: Yann L

Typescript enums drawbacks and solutions

The problem of TS enums

Why does Typescript generate all this code?

String enums have no reverse mapping

Alternatives to enums

The const assertion feature

However we still miss the typing feature

Const enums

Conclusion

Angular library with demo project

Generate the Angular workspace

Generate the library in the project

Generate the demo app

Import the lib in the demo project

Don't forget to build

Credits

Typescript cast is a type breaker

The Typescript types and "cast"

Typing the code

Casting the code

When is a cast ok?

You're precising the type with inheritance

You're precising the type from union types

You're infering a type from an external input

Best practices when doing a cast

Always Guard

Type predicates and guard functions

The unknown type to explicitly force cast

Conclusion

The `unknown` type to explicitly force cast