DEV Community: Stefan Baumgartner

Tidy TypeScript: Prefer union types over enums

Stefan Baumgartner — Wed, 20 Jan 2021 15:04:05 +0000

This is the first article in a series of articles where I want to highlight ways on how to keep your TypeScript code neat and tidy. This series is heavily opinionated, so don't be angry if I ditch a feature that you learned to like. It's not personal.

Today we look at enums. Enums are a feature that I see used a lot by people who come from languages like Java or C# because they have been so prominent there. Enums are also a feature from "the old days" of TypeScript where the JavaScript landscape was a lot different than it is now. And you can see that, as enums work exceptionally different than any other type in TypeScript.

Enums emit code

My most preferred way of writing TypeScript is to

write regular, modern-day JavaScript.
add types wherever we can strengthen TypeScript's understanding of our code.

This means after a compile step, you end up with the same code as before without the extra type definitions.

Enums, like classes, create both a type and a value. Meaning that e.g. this declaration:

enum Direction {
  Up,
  Down,
  Left,
  Right,
}

emits code in the JavaScript output.

var Direction;
(function (Direction) {
    Direction[Direction["Up"] = 0] = "Up";
    Direction[Direction["Down"] = 1] = "Down";
    Direction[Direction["Left"] = 2] = "Left";
    Direction[Direction["Right"] = 3] = "Right";
})(Direction || (Direction = {}));

You can get rid of the output if you use a const enum, but too often I've seen people using just regular enums everywhere and wondering why their output gets so big. Especially if you put "glue code" between front-end and back-end in enums you can end up with huge files and bundles.

Okay, that's one thing, and we can handle that by enforcing const enums. But there is also this nasty ambiguity.

Numeric enums are not type-safe

Yes, you've heard right. Regular numeric enums -- as in an enum where you don't set string values -- are not type-safe! If we look back at the Direction enum from earlier a function that takes a direction also takes any number value instead.

enum Direction {
  Up,
  Down,
  Left,
  Right,
}

declare function move(direction: Direction): void;

move(30);
// ☝️ This is totally ok! 😱

The reason is that there is a use-case of implementing bitmasks with numeric enums. And people seem to actually do that! Do a quick search for "TypeScript enum bitmask" or "bitwise flags" and see lots of implementations and examples. Enums provide syntactic sugar for this scenario. I'd argue that why this scenario is valid to implement in JavaScript, I'd doubt it's the most common scenario you would use enums for.

Usually, you want to make sure you only can pass values that are actually valid.

So far for numeric enums. But there's always string enums, right? They are type-safe, aren't they? Yes. And they are peculiar!

String enums are named types

In a world of structural typings, enums chose to be a named type. This means that even if values are valid and compatible, you can't pass them to a function or object where you expect a string enum. See this example:

enum Status {
  Admin = "Admin",
  User = "User",
  Moderator = "Moderator",
}

declare function closeThread(threadId: number, status: Status): void;

closeThread(10, "Admin");
//              ^ 💥 This is not allowed!


closeThread(10, Status.Admin);
//              ^ You have to be explicit!

This is something you can leverage, but it's also very different from how number enums and the entire rest of TypeScript's type system work.

Prefer union types

A simple union type gives you something that works similarly and is much more aligned with TypeScript.

type Status = "Admin" | "User" | "Moderator"

declare function closeThread(threadId: number, status: Status): void;

closeThread(10, "Admin");
// All good 😄

You get all the benefits from enums like proper tooling and type-safety without going the extra round and risking to output code that you don't want. It also becomes clearer what you need to pass, and where to get the value from. No need to manually map back-end strings to an enum just for the sake of it. Simple, clear, tidy!

If you want to write your code enum-style, with an object and a named identifier, a const object with a Values helper type might just give you the desired behaviour and is much closer to JavaScript:

const Direction = {
  Up: 0,
  Down: 1,
  Left: 2,
  Right: 3,
} as const;

// Get to the const values of any object
type Values<T> = T[keyof T];

// Values<typeof Direction> yields 0 | 1 | 2 | 3
declare function move(
  direction: Values<typeof Direction>): void;

move(30);
//   ^ 💥 This breaks!

move(0);
//   ^ 👍 This works!

move(Direction.Left);
//   ^ 👍 This also works!

// And now for the Status enum

const Status = {
  Admin: "Admin",
  User: "User",
  Moderator: "Moderator"
} as const;

// Values<typeof Status> yields "Admin" | "User" | "Moderator"
declare function closeThread(
  threadId: number, 
  status: Values<typeof Status>): void;

closeThread(10, "Admin"); // All good!
closeThread(10, Status.User); // enum style

There are also no surprises.

You know what code you end up with within the output.
You don't end up with changed behavior because somebody decides to go from a string enum to a numeric enum.
You have type-safety where you need it.
And you give your colleagues and users the same conveniences that you get with enums.

But to be fair, a simple string union type does just what you need: Type-safety, auto-complete, predictable behavior.

Of course, you can learn and remember all the peculiarities of enums and know quite well how to handle them. But why bother if there is a much clearer and easier way to achieve the same -- if not better -- type safety entirely in the type system? That's why I suggest to prefer union types over enums.

Tidy TypeScript: Avoid traditional OOP patterns

Stefan Baumgartner — Tue, 24 Nov 2020 00:00:00 +0000

This is the third article in a series of articles where I want to highlight ways on how to keep your TypeScript code neat and tidy. This series is heavily opinionated and you might find out things you don't like. Don't take it personally, it's just an opinion.

This time we look at POOP, as in "Patterns of Object-Oriented Programming". With traditional OOP I mostly mean class-based OOP, which I assume the vast majority of developers think of when talking OOP. If you come from Java or C#, you might see a lot of familiar constructs in TypeScript, which might end up as false friends in the end.

Avoid static classes

One thing I see a lot from people who worked a lot with Java is their urge to wrap everything inside a class. In Java, you don't have any other options as classes are the only way to structure code. In JavaScript (and thus: TypeScript) there are plenty of other possibilities that do what you want without any extra steps. One of those things is static classes or classes with static methods, a true Java pattern.

// Environment.ts

export default class Environment {
  private static variableList: string[] = []
  static variables(): string[] { /* ... */ }
  static setVariable(key: string, value: any): void  { /* ... */ }
  static getValue(key: string): unknown  { /* ... */ }
}

// Usage in another file
import * as Environment from "./Environment";

console.log(Environment.variables());

While this works and is even -- sans type annotations -- valid JavaScript, it's way too much ceremony for something that can easily be just plain, boring functions:

// Environment.ts
const variableList: string = []

export function variables(): string[] { /* ... */ }
export function setVariable(key: string, value: any): void  { /* ... */ }
export function getValue(key: string): unknown  { /* ... */ }

// Usage in another file
import * as Environment from "./Environment";

console.log(Environment.variables());

The interface for your users is exactly the same. You can access module scope variables just the way you would access static properties in a class, but you have them module-scoped automatically. You decide what to export and what to make visible, not some TypeScript field modifiers. Also, you don't end up creating an Environment instance that doesn't do anything.

Even the implementation becomes easier. Check out the class version of variables():

export default class Environment {
  private static variableList: string[] = []
  static variables(): string[] { 
    return this.variableList;
   }
}

As opposed to the module version:

const variableList: string = []

export function variables(): string[] {
  return variableList;
}

No this means less to think about. As an added benefit, your bundlers have an easier time doing tree-shaking, so you end up only with the things you actually use:

// Only the variables function and variablesList 
// end up in the bundle
import { variables } from "./Environment";

console.log(variables());

That's why a proper module is always preferred to a class with static fields and methods. That's just an added boilerplate with no extra benefit.

Avoid namespaces

As with static classes, I see people with a Java or C# background clinging on to namespaces. Namespaces are a feature that TypeScript introduced to organize code long before ECMAScript modules were standardized. They allowed you to split things across files, merging them again with reference markers.

// file users/models.ts
namespace Users {
  export interface Person {
    name: string;
    age: number;
  }
}

// file users/controller.ts

/// <reference path="./models.ts" />
namespace Users {
  export function updateUser(p: Person) {
    // do the rest
  }
}

Back then, TypeScript even had a bundling feature. It should still work to this day. But as said, this was before ECMAScript introduced modules. Now with modules, we have a way to organize and structure code that is compatible with the rest of the JavaScript ecosystem. So that's a plus.

So what do we need namespaces for?

Extending declarations

Namespaces are still valid if you want to extend definitions from a third party dependency, e.g. that lives inside node modules. Some of my articles use that heavily. For example if you want to extend the global JSX namespace and make sure img elements feature alt texts:

declare namespace JSX {
  interface IntrinsicElements {
    "img": HTMLAttributes & {
      alt: string,
      src: string,
      loading?: 'lazy' | 'eager' | 'auto';
    }
  }
}

Or if you want to write elaborate type definitions in ambient modules. But other than that? There is not much use for it anymore.

Needless namespaces

Namespaces wrap your definitions into an Object. Writing something like this:

export namespace Users {
  type User = {
    name: string;
    age: number;
  }

  export function createUser(name: string, age: number): User {
    return { name, age }
  }
}

emits something very elaborate:

export var Users;
(function (Users) {
    function createUser(name, age) {
        return {
            name, age
        };
    }
    Users.createUser = createUser;
})(Users || (Users = {}));

This not only adds cruft but also keeps your bundlers from tree-shaking properly! Also using them becomes a bit wordier:

import * as Users from "./users";

Users.Users.createUser("Stefan", "39");

Dropping them makes things a lot easier. Stick to what JavaScript offers you. Not using namespaces outside of declaration files makes your code clear, simple, and tidy.

Avoid abstract classes

Abstract classes are a way to structure a more complex class hierarchy where you pre-define some behavior, but leave the actual implementation of some features to classes that extend from your abstract class.

abstract class Lifeform {
  age: number;
  constructor(age: number) {
    this.age = age;
  }

  abstract move(): string;
}

class Human extends Lifeform {
  move() {
    return "Walking, mostly..."
  }
}

It's for all sub-classes of Lifeform to implement move. This is a concept that exists in basically every class-based programming language. The problem is, JavaScript isn't traditionally class-based. For example, an abstract class like below generates a valid JavaScript class, but is not allowed to be instantiated in TypeScript:

abstract class Lifeform {
  age: number;
  constructor(age: number) {
    this.age = age;
  }
}

const lifeform = new Lifeform(20);
//               ^ 💥 Cannot create an instance of an abstract class.(2511)

This can lead to some unwanted situations if you're writing regular JavaScript but rely on TypeScript to provide you the information in form of implicit documentation. E.g. if a function definition looks like this:

declare function moveLifeform(lifeform: Lifeform);

You or your users might read this as an invitation to pass a Lifeform object to moveLifeform. Internally, it calls lifeform.move().
Lifeform can be instantiated in JavaScript, as it is a valid class
The method move does not exist in Lifeform, thus breaking your application!

This is due to a false sense of security. What you actually want is to put some pre-defined implementation in the prototype chain, and have a contract that definitely tells you what to expect:

interface Lifeform {
  move(): string
}

class BasicLifeForm {
  age: number;
  constructor(age: number) {
    this.age = age
  }
}

class Human extends BasicLifeForm implements Lifeform {
  move() {
    return "Walking"
  }
}

The moment you look up Lifeform, you can see the interface and everything it expects, but you hardly run into a situation where you instantiate the wrong class by accident.

Bottom line

TypeScript included bespoke mechanisms in the early years of the language, where there was a severe lack of structuring in JavaScript. Now that JavaScript reached a different language of maturity, it gives you enough means to structure your code. So it's a really good idea to make use of what's native and idiomatic: Modules, objects, and functions. Occasional classes.

Tidy TypeScript: Prefer type aliases over interfaces

Stefan Baumgartner — Fri, 20 Nov 2020 00:00:00 +0000

This is the second article in a series of articles where I want to highlight ways on how to keep your TypeScript code neat and tidy. By nature, this series is heavily opinionated and is to be taken with grains of salt (that's plural).

There are two different ways in TypeScript to declare object types: Interfaces and type aliases. Both approaches to defining object types have been subject to lots of blog articles over the years. And all of them became outdated as time progressed. Right now, there is little difference between type aliases and interfaces. And everything that was different has been gradually aligned.

Syntactically, their difference is nuanced:

type PersonAsType = {
  name: string;
  age: number;
  address: string[];
  greet(): string;
};

interface PersonAsInterface {
  name: string;
  age: number;
  address: string[];
  greet(): string;
}

It's an equal sign. This nuance can have some effect on the time of type evaluation -- immediate for the type alias, lazy for interfaces -- but that's it. You can use interfaces and type aliases for the same things, in the same scenarios:

In an implements declaration for classes
As a type annotation for object literals
For recursive type structures

You name it! There is however one important difference that can have side effects you usually don't want to deal with:

Declaration merging

Interfaces allow for declaration merging, type aliases don't. Declaration merging allows for adding properties to an interface even after it has been declared.

interface Person {
  name: string;
}

interface Person {
  age: number;
}

// Person is now { name: string; age: number; }

TypeScript itself uses this technique a lot in lib.d.ts files, making it possible to just add deltas of new JavaScript APIs based on ECMAScript versions. This is a great feature if you want to extend e.g. Window, but it can fire back in other scenarios. Take this as an example:

// Some data we collect in a web form
interface FormData {
  name: string;
  age: number;
  address: string[];
}

// A function that sends this data to a back-end
function send(data: FormData) {
  console.log(data.entries()) // this compiles!! 😱
  // but crashes horrendously in runtime 😕
}

Oh, bother, where does the entries() method come from? It's a DOM API! FormData is one of the interfaces provided by browser APIs, and there are a lot of them. They are globally available, and nothing keeps you from extending those interfaces. And you get no notification if you do.

We can of course argue about proper naming, but the problem persists for all interfaces that you make available globally, maybe from some dependency where you don't even know they add an interface like that to the global space.

Changing this interface to a type alias immediately makes you aware of this problem:

type FormData = {
//   ^ 💥 Duplicate identifier 'FormData'.(2300)
  name: string;
  age: number;
  address: string[];
}

It also prevents your types from being extended unknowingly.

Index access types

Declaration merging is also the reason why interfaces won't work as a subset of index access types. Below is an example that sends data to a server. You can pass in any object and a set of HTTP headers that require all keys to be of string and all values to be of string.

declare function 
  send(data: any, headers: Record<string, string>): void;

Record<string, string> is the same as { [key: string]: string }, which shows the flexible index access better.

Let's do two type definitions for required HTTP headers. Once as object type:

type HTTPHeaders = {
  Accept: string,
  Cookie: string
}

And another one as an interface:

interface HTTPHeaderInterface {
  Accept: string,
  Cookie: string,
}

If you call send with an object that has been annotated as HTTPHeaders, everything is wonderful:

const hdrs: HTTPHeaders = {
  Accept: "text/html",
  Cookie: ""
};

send({}, hdrs) // 👍

But the moment you change hdrs to HTTPHeadersInterface, things go boom:

const hdrs: HTTPHeaderInterface = {
  Accept: "text/html",
  Cookie: ""
};

send({}, hdrs) 
//       ^ 💥 Index signature is missing in type 'HTTPHeaderInterface'

TypeScript will complain that the index signature is missing. Only if the type is final, like with HTTPHeaders, TypeScript can correctly check if all properties and values are assignable to the Record<string, string> type we declared in send. Since interfaces are up for declaration merging, and therefore not all properties are known, TypeScript can't tell if the index signature is compatible with Record<string, string>.

That's why I suggest to prefer type aliases over interfaces. Of course, if you are providing a library that has interfaces that should be extendable by others, type aliases won't get you far. But other than that, type aliases are clear, simple, and tidy.

void in JavaScript and TypeScript

Stefan Baumgartner — Tue, 10 Sep 2019 06:20:50 +0000

This article originally appeared on Fettblog

If you come from traditional, strongly typed languages you might be familiar with the concept of void: A type telling you that functions and methods return nothing when called.

void exists in both JavaScript as an operator and in TypeScript as a primitive type. And in both worlds void works a little bit different than most people are used to.

void in JavaScript

void in JavaScript is an operator which evaluates the expression next to it. No matter which expression is evaluated, void always returns undefined.

let i = void 2; // i === undefined

Why would we need something like this? First, in earlier times, people were able to override undefined and giving it an actual value. void always returned the real undefined.

Second, it's a nice way to call immediately invoked functions:

void function() {
  console.log('What')
}()

All without polluting the global namespace:

void function aRecursion(i) {
  if(i > 0) {
    console.log(i--)
    aRecursion(i)
  }
}(3)

console.log(typeof aRecursion) // undefined

Since void always returns undefined, and void always evaluates the expression next to it, you have a very terse way of returning from a function without returning a value, but still calling a callback for example:

// returning something else than undefined would crash the app
function middleware(nextCallback) {
  if(conditionApplies()) {
    return void nextCallback();
  }
}

Which brings me to the most important use case of void: It's a security gate for your app. When your function is always supposed to return undefined, you can make sure that this is always the case.

button.onclick = () => void doSomething();

void in TypeScript

void in TypeScript is a subtype of undefined. Functions in JavaScript always return something.
Either it's a value, or undefined:

function iHaveNoReturnValue(i) {
  console.log(i)
} // returns undefined

Since functions without a return value always return undefined, and void always returns undefined in JavaScript, void in TypeScript is a proper type for telling developers that this function returns undefined:

declare function iHaveNoReturnValue(i: number): void

void as type can also be used for parameters and all other declarations. The only value that can be passed is undefined:

declare function iTakeNoParameters(x: void): void

iTakeNoParameters() // 👍
iTakeNoParameters(undefined) // 👍
iTakeNoParameters(void 2) // 👍

So void and undefined are pretty much the same. There's one little difference though, and this difference is significant: void as a return type can be substituted with different types, to allow for advanced callback patterns:

function doSomething(callback: () => void) {
  let c = callback() // at this position, callback always returns undefined
  //c is also of type undefiend
}

// this function returns a number
function aNumberCallback(): number {
  return 2;
}

// works 👍 type safety is ensured in doSometing
doSomething(aNumberCallback)

This is desired behaviour and often used in JavaScript applications. Read more on this pattern called substitutability in my other articles.

If you want to make sure to pass functions who only return undefined (as in "nothing"), be sure to adapt your callback method signature:

- function doSomething(callback: () => void) {
+ function doSomething(callback: () => undefined) { /* ... */ }

function aNumberCallback(): number { return 2; }

// 💥 types don't match
doSomething(aNumberCallback)

You'll propably be good with void most of the time.

JAMStack vs serverless web apps

Stefan Baumgartner — Thu, 30 May 2019 21:20:33 +0000

JAMStack seems to be one of the most trending topics right now. So are serverless web apps. Hot and loved! I've seen some tweets, articles and even live presentations just this week that talk about JAMStack and serverless web apps as if they are the same. For good reason. In an ideal scenario, serverless web apps and JAMStack sites/apps are indistinguishable.

But, it's in the details where both differ. Let's dig deeper.

JAMStack sites/apps

Let's think back one more time what the "JAM" in JAMStack stands for: JavaScript, APIs, Markup. But how are they interconnected?

We deploy and serve pre-generated, static markup. We enhance this markup dynamically on the client side with JavaScript, and fetch dynamic data via APIs. MJAStack just has not the ring to it, has it?

Let's focus on the "M" in JAMStack. Statically generated markup. Generated by a static site generator. Probably the one thing that tends to be overlooked when talking about JAMStack vs. serverless web apps.

As soon as we deploy and serve statically generated markup, our sites qualify for being a JAMStack site.

The good thing about this pre-generated markup: We are able to serve content in any scenario. Our APIs might malfunction, our JavaScript might break. As long as we send some pure, old HTML over the wire we have something to show! Then we add dynamic features -- if necessary -- via JavaScript.

This is progressive enhancement in its purest form. That's why so many people love it.

What about APIs, though? In an ideal scenario, the only APIs we call are serverless or cloud functions. Because they are cheap. They allow for self-healing. They scale. They might have a lower security attack surface.

But, as long as we call URLs via JavaScript to get dynamic data, we fulfil the "A" part in JAMStack.

Best case: Serverless. A bunch of URLs: Good enough.

Serverless web apps

Compared to JAMStack, a serverless web app by its very name needs to talk to serverless APIs. Most of the time there's a funny sounding JavaScript framework running in your application to show data to your users.

We don't have to serve any markup at all other than some element your JavaScript app can attach to. We don't have to pre-generate content and have a bunch of HTML files if it doesn't serve our purpose.

If we serve actual content, the HTML does not have to be statically stored or pre-generated. It can be generated dynamically through server-side rendering.

The best case scenario? Just like JAMStack: We have our content pre-generated and served statically. Maybe via a CDN to have the cheapest and most effective delivery secured.

Just having an empty HTML file calling some JavaScript and having a blank element to attach your app to? Good enough?

Bottom line

In JAMStack apps, the "A" can be any API to call. Preferably serverless. The "M" though, is statically generated markup. Serverless web apps are much stricter on the "A" part. Markup though is a whole different story.

If you care about performance, security, discoverability and resilience, I recommend architecting both serverless web apps and JAMStack sites the same.

The Unsung Benefits of JAMStack Sites

Stefan Baumgartner — Thu, 09 May 2019 13:22:21 +0000

Traditional websites are usually built on top of a CMS. Drupal, Wordpress, Typo3, you name it. CMS handle everything from content editing, over application programming to front-end generation. So choosing a CMS has a huge impact on how you develop your sites, and what skills and trades you need to get the job done. A CMS has also impact on hosting! Does LAMP-Stack ring a bell? Linux, Apache, MySQL and PHP. The golden standard for lots of popular CMS to this day.

JAMStack sites are different. Instead of putting the CMS into the core of all your decisions, you focus on the Front-End. And for good reason. The browser doesn't care what technology is underneath. It just cares about HTML, CSS and JavaScript. So why shouldn't you?

Putting the Front-End into focus has a lot of impact on every other level of your website. Be it the CMS, your application layer or even where you host it. And this impact comes with a lot of benefits.

Choose your tools

JAMStack sites treat hosting, content management and application as their own entities. With little to no dependency to each other.

The application layer can be anything as long as it produces APIs consumable by the Front-End. And if you go full serverless, you don't even have to care about having a dedicated application server. This is where the server-less comes in, folks.

Same for Content Management Systems. Great deal: A CMS can focus on actually managing content again! No need to serve as a rendering tool or application platform. You even can stick with Wordpress, if you like. Or have something JAMStack optimised like Storyblok. As long as there's an API to fetch content, you're good.

Hosting is as easy as serving files. Put it up on a cloud storage like S3 or Azure Storage. Host it in your dropbox. Or find a cozy place next to your old website. It's your choice.

The best thing: People can choose what they like best, and what they feel most productive with. It all sticks together with APIs.

No technology lock-in

With each part being independent, you not only have lots of choice for getting your website done. You also continue to have this choice as your project evolves. It's mich easier to swap one technology for the other if you don't have to replace your whole website. Want to move from Metalsmith to Gatsby, no need to kill your APIs. No need to kill your hosting strategy. No need to kill your builds or the huge amount of content you store in your CMS.

Does the CMS not serve your purpose anymore? Store the latest output in JSON files to keep builds going, and move silently to another one.

The bulky Java monolith is too slow and costs too much? Some light-weight cloud functions are easy to create and integrate. Only keep API contracts alive.

Moving away from technology and adopting other still isn't easy or without serious effort. But it's a lot easier to grasp if you don't have to take care about complete picture.

Incremental adoption

Every part is independent, and written in the technology you prefer. This means you can start migrating to the JAMStack immediately. Your old app still in place, start getting a few cloud functions up and running and publish a few HTML pages next to your old installation. Any server is ready to serve static files!

Especially in bigger projects I've seen this to be most beneficial. You don't want to migrate 2000 pages to a new stack in a big bang. But having the top-most pages fresh, new and fast can make a huge impact.

Bottom line

Moving to the JAMStack is a commitment to modern cloud architectures and DevOps workflows. This also means that you are able adopt as you go, with the tools you see fit best. Don't be intimidated to redo everything. Start. And see where it takes you.

DEV Community: Stefan Baumgartner

Tidy TypeScript: Prefer union types over enums

Enums emit code

Numeric enums are not type-safe

String enums are named types

Prefer union types

Further reading

Tidy TypeScript: Avoid traditional OOP patterns

Avoid static classes

Avoid namespaces

Extending declarations

Needless namespaces

Avoid abstract classes

Bottom line

Tidy TypeScript: Prefer type aliases over interfaces

Declaration merging

Index access types

void in JavaScript and TypeScript

void in JavaScript

void in TypeScript

JAMStack vs serverless web apps

JAMStack sites/apps

Serverless web apps

Bottom line

The Unsung Benefits of JAMStack Sites

Choose your tools

No technology lock-in

Incremental adoption

Bottom line