DEV Community: judehunter

The only API stack (and workflow) you should be using.

judehunter — Sun, 13 Sep 2020 01:09:11 +0000

Over the years, I've tried multiple Node.js back-end technology stacks, and I can finally say I've found a suitable one that will help you rapidly develop your projects (and kickstart your startups!).

The REST framework

Why? I've extensively used both REST and GraphQL back-ends and I believe GraphQL is an overkill in most cases. While it's great for scalability, it is not the fastest way to develop an API for your project.

My REST framework of choice is koa.js.
Why? I believe it's one of the best frameworks when it comes to quick development of your API, since it makes it extremely easy to go from the idea to the implementation.

The middleware stack is also very intuitive and relies on async/await.

I also feel it's a lot better than Express and generally more lightweight.

TypeScript

Why? It is an extremely good and easy way to make your API type safe and develop more rapidly in the long run. It has saved me a lot of headaches and I could not live without its IntelliSense suggestions.

You'll also see that using TypeScript enables us to easily integrate TypeORM into our project.

ESLint

Why? Consistency goes a long way. ESLint makes sure you and your co-workers don't yell at each other over code that - in their opinion - is not properly formatted. It can also track things like unused variables/imports and usages of let instead of const.

The Database

This depends on your use case. However, there are only two database types you should care about - relational and document-based databases.

If you're not sure,
I'd say for smaller projects you'd want to go with a document-based database, like MongoDB.
However, when your project grows, you'll probably have certain relations between your entities. And thus, you should use a relational database, like MySQL or PostgreSQL (which is my database of choice).

TypeORM

For MongoDB, Mongoose may be more suitable.
Why? TypeORM is an Object-Relational Mapping library for typescript (and babel), which basically means you don't have to deal with raw SQL and you can use certain utilities, like automatic relation joining.

The reason why TypeORM is so interesting is the fact that it uses decorators for entity synchronization. What that means is you won't have to use migrations in your development environment.

Instead, you define a class and decorate it:

@Entity()
class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  // automatic type detection thanks to reflection!
  @Column()
  name: string;

  // automatic date columns!
  @CreateDateColumn()
  createdAt: Date;
}

TypeORM then uses that class to migrate the database and to make IntelliSense suggestions based on the fields.

Why not? Frankly, TypeORM is not beginner friendly, largely due to the docs being quite horrible. However, when you get a hang of it and use IntelliSense to your advantage, it becomes an incredibly powerful tool.

Git Flow

Why? This is a certain philosophy/workflow/strategy that works particularly well when working with git in teams (not particularly needed if you're not in a team).
It defines what branches should be used for certain things, like features, releases, hotfixes.

.env

Why? Using .env files for defining your environmental variables is pretty much a standard now. It lets you define different variables for your local machine and for the machine you're hosting your project on.

Do not forget to add .env to .gitignore!.

File structure

I came up with a file structure that works well with this particular technology stack:

src
├── entities
│   └── User.ts
├── modules
│   └── module-name
│       ├── module-name.router.ts
│       ├── module-name.service.ts
│       └── module-name.spec.ts
├── mw
├── utils
└── app.ts

e2e
└── test-name.e2e.ts

Going from the top:

The entities folder is where you should store your TypeORM entities
The modules folder holds the different modules of your application (inspired by NestJS). For instance, an auth module may have a router that has a /auth/facebook route which in turn calls the authorizeWithFacebook() function in the service file. It's important the router handles the HTTP stuff, and the service deals with pure data. This way, your unit tests (.spec.ts) can call the service directly. Additionally, your routes should - most of the time - be prefixed with the module name.
The mw folder is where you should store your custom middleware. You could also use the utils folder for this.
The utils folder is pretty much every other function that doesn't fit anywhere else.
The e2e folder stores the end-to-end tests.

This workflow has proven most successful for my projects and is great for rapid development.

Don't agree with me? Start a discussion in the comments!

Happy coding! 🎉

The caveats (and solutions) to generic type guards in TypeScript.

judehunter — Tue, 08 Sep 2020 23:49:54 +0000

When dealing with user data - especially in APIs - and inheritance, it's often difficult to generalize your code and follow the DRY principle.

The TypeScript language uses a concept called type guards 🛡️ - a clever compiler feature that will help you write safer code and deal with that angry and complaining compiler.

The compiler uses guards to narrow down the type of your value and provide IntelliSense suggestions.

Say we have a given inheritance model:

class Vehicle {
  brand: string;
}

class Aircraft extends Vehicle {
  usage: 'civil' | 'military';
}

class Car extends Vehicle {
  drive: 'AWD' | 'FWD' | 'RWD';
}

We are given a secretVehicle object that we know extends Vehicle in terms of properties it has. However, the object is not an instance of any of these classes.

Thus, the instanceof approach won't work, since it requires the left operand to be an instance:

if (secretVehicle instanceof Car) {
  console.log(`This is a car with ${secretVehicle.drive} drive`);
  // TypeScript doesn't complain, but this will never print!
}

What we can do instead, is check if our secretVehicle has all the properties of our subclasses.

We do that by either using reflection or by creating an actual instance of that class and looking up its keys with Object.keys():

export const hasAllKeys =
  <T>(obj: Record<string, any>, cls: new () => T): obj is T => {
    const properties = Object.keys(new cls());
    for (const p of properties) {
      if (!(p in obj)) return false;
    }
    return true;
  };

We can then use the guard to assure TypeScript that the secretVehicle is actually of a given type.

if (hasAllKeys(secretVehicle, Car)) {
  console.log(`This is a car with ${secretVehicle.drive} drive`);
}
if (hasAllKeys(secretVehicle, Aircraft)) {
  console.log(`This is a ${secretVehicle.usage} aircraft`);
}

However, in some edge cases this solution is problematic. It may incorrectly check the properties when used with a class that has a custom constructor.

Moreover, sometimes it's simply not what we need. The input data we get is often just a Partial<T> instead of a T, meaning some properties might be missing (e.g. the id).

To counter that, let's use a guard that checks for specific properties instead of all of them.

export const hasKeys =
  <T>(
    obj: Record<string, any>,
    properties: (keyof T)[]
  ): obj is T =>
    properties.filter(p => p in obj).length == properties.length;
    // functional approach

The TypeScript compiler is clever enough to figure out T by itself, if we don't want to specify it.

For instance, hasKeys(secretVehicle, ['usage']) will infer T to be of type {usage: any} and thus, we will be able to use the usage key inside of our if statement.

if (hasKeys(secretVehicle, ['usage'])) {
  console.log(`
    Not sure what this is,
    but it has a ${secretVehicle.usage} usage!
  `);
}

Alas, this forces us to operate on values of type any.
We can either pass the the type for that key:

hasKeys<{usage: 'civil' | 'military'}>(secretVehicle, ['usage']);

Or just simply pass the entire class:

hasKeys<Aircraft>(secretVehicle, ['usage']);

This will also give us IntelliSense suggestions when defining the keys!

Still, what if both our subclasses have the same fields, but of different types? The issue gets more complicated and may require the usage of reflection.
However, we can overcome this problem by specifying a type field in our base class to easily differentiate between types.

class Vehicle {
  brand: string;
  type: 'Car' | 'Aircraft';
}

const ofType =
  <T>(
    obj: Record<string, any> & {type?: string},
    cls: new () => T
  ): obj is T =>
    obj.type == (new cls()).constructor.name;
    // or use another argument for the type field

if (ofType(secretVehicle, Car)) {
  console.log(`This is a car with ${secretVehicle.drive} drive`);
}

TypeScript is a powerful language and using these constructs can help you use it to its full potential.

Thank you for reading my first contribution to the dev.to community.

Happy coding! 🎉