Forem: Fernando

Looking out for key actions to propel your organization from the inside

Fernando — Fri, 24 Mar 2023 20:06:35 +0000

My goal with this series is to identify roadblocks that make the process of evolving a company harder. In doing so I wish to kindle discussion and exchange of ideas in the spirit of arriving at a possible solution.

Each article is going to be short. I plan on writing concise ideas, too long for a tweet, and too short for a standalone blog.

Thanks for reading. I hope this series is helpful to you.

The first step: Finding out specifically what is holding your organization back

Being a small and chaotic business is not sustainable at all. Everybody does everything all the time until eternity. Founders and other accountable employees don't stop working. Mistakes are done and fixed again and again. That's why a natural evolution to a well-organized company tends to happen.

So now the whole team plans on making things more organized so that responsibility is distributed and entropy diminishes.

Negative aspects of the company's processes start to pop up. You give them a name. They become real. That is the first step to evolving an organization. Then you can design and implement solutions.

For each roadblock you identify in your journey to improve a company, there is a possibility of improvement. In fact, the mere finding of an obstacle means that it holds the opportunity to set a pillar for the next iteration of your organization. Building a solid process and methodology to surpass that obstacle is the foundation on which you can stand on top and continue identifying and solving problems that lie on the road ahead.

Wrap Up

The thing to take from this article is that identifying a problem with exquisite detail is key. You have to give substance to what you are trying to solve. If not, it will linger on. The simple act of giving entity to what you need to tackle is pushing you closer to its solution.
What I am thinking about right now is processes that get implemented with no sufficient communication to everybody involved. Maybe I will write about that next.

What a potent Email can do: How to evoke the full power of a highly capable team

Fernando — Sat, 28 Jan 2023 14:02:01 +0000

Recently I lived a series of days, and even weeks when confusion and uncertainty filled the air at my company. At least that is how I felt. I didn't know if my peers felt the same. I just knew something was off.

For those who don't know my background, I am a team leader/project manager/tech lead at a mid-sized software company. I work with many teams with different skills and interact with every level of the hierarchy in the company.

The situation I am describing occurs before 2 projects were about to begin. At that time we lacked the team to face these projects. That in itself is a problem. But there was something more.

People seemed not to care. Communication was null. The product owner did not talk to me about the projects. The delivery team did not talk to me about them. The operations manager did not talk to me about them. You guessed it, no one talked to me about them. It seemed I was the only one caring.

In meetings with each of them, every time I brought up concerns about the situation or proposed some action, no one joined to discuss and treat the subject. These debates were postponed, dismissed, or minimized.

That meant that I was alone with these enigmatic projects, by myself, with my head and my thoughts. Me being me, I try to solve problems and move forward with everything I got. But this time, I could not. The data I had was so little, the horizon was deep in a fog of war. I was alone, trying to reverse engineer, trying to plan this project without a clear team, without a concrete specification, and without an estimated delivery roadmap.

Then I summoned a mentor of mine inside the company. He made me realize that what I needed to do was to gather everybody and lead them in the same direction. He told me to write an email...

An email to lead them all.

"Gather everybody - he said - and point out everything you see that is wrong and needs to be addressed. You need their help, not because you are bad at your job, but because they are lacking.".

The thing is that everybody assumed I would take care of everything. Everybody was relaxed. With that email, I sounded the alarm. People thought "Oh! An email gathering all the leaders? Pointing out a problem? This may need my attention".

Something about the written word is powerful. It allows the rational brain to work, you have time to chew ideas and think about what you are reading. When in dialogue, real-time interaction diminishes this capacity of the rational brain.

People are minding their own business and solving problems that are real to them now. They will automatically knock aside everything that may signify another problem. It requires effort and discipline to make time for thinking ahead, working collaboratively, and planning. Sometimes you need to nudge people to wake them. Turn them on and remove the blindfolds.

When you encounter a problem that is too complex. When you find yourself struggling to make sense of a situation. Sound the alarm. Look for help. Teams are there to help and they have enormous power. Your brain is worse than a lot of brains. Use them all if you have some at your disposal. People want to help each other, but sometimes they are narrowly focused on their day-to-day.

Communication is key. Writing a good email may be the best choice you have to start or renew a fire in people. You need to lead them in the same direction. That is the way forward, with people, not by yourself.

Learning to build an API in NestJS (Node + Typescript) - Part 05

Fernando — Sat, 17 Dec 2022 19:31:52 +0000

Intro

If you have been following this series, skip the intro!

This is the fifth part of a series about learning NestJs for people who have experience building web applications but in languages other than typescript.

The structure of these articles is not scripted 👮 nor random 😕. My goal is to lay out everything I learn with as much depth as I can understand. I try to build working code that I understand and can replicate in upcoming real projects. That's why I don't write about any foo bar examples.

This is my learning process 📚... hopefully it will serve you as well.

The articles are written at the same time as I code and read the docs for what I am trying to build. After the draft is completed, I revise it, edit it, and reorder stuff to make reading this article easier for you and me in the future.

Recap

Last time we managed to set up a postgres database and generate entities and migrations. Now we can start creating Users! That is what we will be doing next.

Controller

Let's add a Sign-Up endpoint which receives a DTO and invokes the user service's create method.
Now we find ourselves asking questions like where should this DTO be placed. First I thought of placing it in the model module, next to our entities. But then I realized that the model module is used across all the application modules. And no other module needs this DTO (or any other similar DTO), so it makes sense to put this DTO inside a DTO's folder in the Account Module.

To Create a user we just need its email and password.

export default class SignUpReqDTO {
  email: string;
  password: string;
}

Now that we have our DTO, let's code the endpoint. It calls the create method from the user service. passing only the parameters we need to create a user.

  @Post('sign-up')
  async SignUp(@Body() signUpReqDTO: SignUpReqDTO) {
    await this.userService.create(signUpReqDTO.email, signUpReqDTO.password);
    return;
  }

Service

We need a User Service to create our users. For it to work we need access to the user repository. That is imported at the module level.

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [AccountController],
  providers: [
    AccountService,
    JwtService,
    UserService,
    JwtStrategy,
  ],
})
export default class AccountModule {}

Now we can initialize our service and remember to inject the user repository.

@Injectable()
export default class UserService {
  private saltOrRounds: number;
  constructor(
    @InjectRepository(User) private userRepository: Repository<User>,
  ) {}

Now we can start implementing a create method. The first problem we find is that we need to encrypt the user password to save it in the database. This is for security reasons. In this way, we make sure that if anybody gets access to the user's database, they can't find out the real user passwords.

Following the documentation, we use the 'bcrypt' package.

  import * as bcrypt from 'bcrypt';
  //...
  async create(email: string, password: string) {
    const user = new User();
    user.Email = email;
    const saltOrRounds = 10;
    user.PasswordHash = await bcrypt.hash(password, saltOrRounds);
    await this.userRepository.save(user);
  }

Just like that, we are able to create a user. In the future, we will add roles so that we can apply some authorization over the authentication.

What is more useful at this point is to enforce some data validations like "duplicated user".

Validations

The first step to finding out if a user is already created with this unique email is to find if there is one in the database. user repository has a "findOne" method which we can apply filtering by email.

  async getByEmail(email: string): Promise<User> {
    const user = await this.userRepository.findOne({
      where: { Email: email }
    });

    return user;
  }

With that, we add the corresponding if statement and the consequence exception. For this, I found these HTTP exceptions from 'nestjs/common'.

      const dbUser = await this.getByEmail(email);
      if (dbUser)
        throw new HttpException('Email is already taken', HttpStatus.BAD_REQUEST);

Later on, we can apply some constraints to our database so that a user with a taken email can never be created.

Delete

Now we can start to add other crud operations easily. For example a Delete operation.
We just need to specify the user Id of the user we want to delete.

In the controller, we implement our endpoint that requires the id to be passed as a route parameter.

  @Delete(':id')
  async delete(@Param('id') id: string) {
    return await this.userService.delete(id);
  }

The delete method in user service should look something like this

  async delete(id: string) {
    const user = await this.userRepository.findOneBy({ Id: id });
    await this.userRepository.remove(user);
  }

If you want, we can add a validation here as well. Let's check if the user exists.

  async delete(id: string) {
    const user = await this.userRepository.findOneBy({ Id: id });
    if (!user)
      throw new HttpException('The user does not exist', HttpStatus.BAD_REQUEST);
    await this.userRepository.remove(user);
  }

We can sophisticate this even more. For now, I pretend to keep on building the app.

Wrap up

That's it for now. Now I want to complete the authentication scheme by adding a local authentication strategy for user log-in. With that in place, we can then apply some roles authorization and have a nice platform boilerplate with a log-in and user management. This is our roadmap!
In the next article, I'll focus on that local authentication strategy.

Thanks for reading. Once again I hope this article is useful for you as it is for me. Keep coding!

Learning to build an API in NestJS (Node + Typescript) - Part 04

Fernando — Sun, 04 Dec 2022 14:34:03 +0000

Hello, my friend! 😄
Nice to have some company on this quest to learn NestJS.

Intro

If you have been following this series, skip the intro!

This is the fourth part of a series about learning NestJs for people who have experience building web applications but in languages other than typescript.

This is my learning process 📚... hopefully it will serve you as well.

Recap

Last time we implemented a semi-public authentication scheme. We covered how to create a JWT token and validate it using the Passport library and guarding our endpoints with custom guards extending from the NestJS Passport wrapper.

The aim now is to add users and close the authentication flow. For that, we are going to configure a database. We will leverage documentation and tutorials. Throughout this article, I will reference this YouTube video which is awesome :love:.

Let's go!

Choosing the database

Won't be spending brain power on this 😄. Let's go with PostgreSQL.

Set Up TypeORM

The official NestJs documentation refers to TypeORM for driving the database layer module. Let's take a look at the TypeORM documentation.

If influenced by Entity Framework, I already like this :love:

Classes representing entities are decorated as well as their properties which represent database columns. The data access patterns can DataMapper or ActiveRecord. The ActiveRecord pattern looks nice, but I am used to working with a DataMapper/Repository pattern. So I'll stick with it for now.

Setting up TypeORM looks pretty intuitive.

First, we need to install TypeORM, the NestJS wrapper, and the database driver for Node. In this case, we use "pg" for a PostgreSQL database.

$ npm install --save typeorm @nestjs/typeorm pg

Let's declare a User entity with a unique Id, email, name, last name, and password hash.

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export default class User {
  @PrimaryGeneratedColumn('uuid')
  public Id: string;

  @Column()
  public Email: string;

  @Column()
  public Name: string;

  @Column()
  public LastName: string;

  @Column()
  public PasswordHash: string;
}

TypeORM needs a DataSource configured (database connection info such as host, name, user, etc.). For that, we use the NestJS wrapper. It provides a class that should receive those configuration parameters and be imported to the root module of our application. Once that is done, we can import the repositories we need in other modules.

So, at the root AppModule we declare the TypeOrmModule with basic database configuration parameters:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { AuthenticationModule } from './authentication/authentication.module';
import ExampleModule from './example/example.module';
import User from './model/entities/User';

@Module({
  imports: [
    ExampleModule,
    AuthenticationModule,
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      username: 'sa',
      password: 'sarasa',
      database: 'test',
      entities: [User],
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Then in our ExampleModule, we import TypeOrmModule and register the repositories that we need. Then, at the ExampleService we can inject any of those registered repositories in the current module:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { AuthenticationModule } from 'src/authentication/authentication.module';
import User from 'src/model/entities/User';
import ExampleController from './example.controller';
import ExampleService from './example.service';

@Module({
  controllers: [ExampleController],
  providers: [ExampleService],
  imports: [AuthenticationModule, TypeOrmModule.forFeature([User])],
  exports: [],
})
export default class ExampleModule {}

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import User from 'src/model/entities/User';
import { Repository } from 'typeorm';

@Injectable()
export default class ExampleService {
  constructor(
    @InjectRepository(User) private userRepository: Repository<User>,
  ) {}
  async get(id: string) {
    const user = await this.userRepository.findOneBy({ Id: id });
    return user.Name;
  }

  // All other methods
  // ...
}

Ok, time to get real with the database

Go to the postgreSQL site and download the installer. Create a database with the provided GUI or CLI and fill the data in the database configuration at AppModule.

Migrations are handled by TypeORM (no NestJS sugar here). In this case, the documentation is not very clear and did not work for me. I ended up throwing away all I coded because of that documentation and went back to the YouTube video I mentioned before.

2 key ideas clarified everything for me:

The database configuration should be accessible by the runtime and the database client for managing database changes. For this, the configuration should be defined in a separate file that the CLI and the code can access.
References to entities and the Datasource instance should be to the transpiled JavaScript files generated when NestJs builds the project.

So I wrote a configuration file and a data source file that feeds from it. You could define both things in the same file, but I like to have those things separated for clarity.

For the configuration object, I copy pasted what we defined before and added paths to the entity end migration folders. This is easier because if not we should reference every entity and migration file explicitly.

import { PostgresConnectionOptions } from 'typeorm/driver/postgres/PostgresConnectionOptions';

const ormConfig: PostgresConnectionOptions = {
  type: 'postgres',
  host: 'localhost',
  schema: 'public',
  username: 'your-data-base-user-name',
  password: 'your-data-base-user-password',
  database: 'your-data-base-name',
  entities: ['dist/model/entities/*.entity.js'],
  migrations: ['dist/model/migrations/*.js'],
  synchronize: false,
};

export default ormConfig;

As mentioned before, we need a DataSource instance.

import { DataSource } from 'typeorm';
import ormConfig from './ormconfig';

const dataSource = new DataSource(ormConfig);

export default dataSource;

Done setting up the configuration for our database. Now we can test if everything works by generating some migrations and running them.

Migrations

For generating migrations and running them it is useful to write some npm scripts. I will go with what is suggested in the YouTube video.

So in your package.json file, you can add these scripts. Make sure you reference the transpiled DataSource file for the typeorm script. Remember that the transpiled files get generated inside the dist folder. Also, notice that this script builds the project first so that all the transpiled files are updated.

{
  //...
  "scripts": {
    "typeorm": "npm run build && npx typeorm -d dist/model/DataSource.js",
    "migration:generate": "npm run typeorm -- migration:generate",
    "migration:run": "npm run typeorm -- migration:run",
    "migration:revert": "npm run typeorm -- migration:revert"
  },
  //...
}

For the migration:generate script you should pass the path to the file where the migration should be generated.

npm run migration:generate -- model/migrations/Your-Migration-Name
npm run migration:run

Wrap Up

Today we managed to set up a postgres database and generate entities and migrations. Now we can start creating Users! That is what we will be doing next.

Thanks for reading. Hope this is helpful to you.
Stay tuned!

Learning to build an API in NestJS (Node + Typescript) - Part 03

Fernando — Thu, 17 Nov 2022 01:02:36 +0000

Back again for the third round of NestJS goodness. 😎

If you didn't read the past two articles... you should! This is a process-oriented series, so every article builds on the last one.

Last time we managed to implement a super basic service, inject it into a controller, route endpoints properly, capture params (query parameters, URI embedded parameters, and request body), and import a module to the main module.

Now we are going to apply this new knowledge by building useful stuff. We start by coding a semi-public authentication scheme. No users, for now, just an unguarded endpoint that always returns a valid token. The rest of the endpoints should be guarded.

The first question that comes to my mind is ¿How do we generate a token?...

Generating a Token

NestJS has a JwtModule we can install (docs). ❤️

npm i @nestjs/jwt

It has a service that can sign a user token. This should be used by our AuthenticationService to execute the sign in action.

import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';

@Injectable({})
export class AuthenticationService {
  constructor(private readonly jwtService: JwtService) {
    this.jwtService = jwtService;
  }
  async signIn(user: any): Promise<any> {
    // Here we should map the user entity to a stripped-down object
    const userInfo = { username: 'username', sub: 'sub' };
    return this.jwtService.sign(userInfo);
  }
}

Remember that if we use a service, we need to import the module where it came from. This specific import has a few configuration parameters that need to be provided. These involve the expiration time of the token, the hashing algorithm, the secret key, etc... These parameters come from the underlying library jsonwebtoken.
So at AuthenticationModule, we will import JtwModule with just a fantasy secret:

import { Module } from '@nestjs/common';
import { PassportModule } from '@nestjs/passport';
import { AuthenticationService } from './authentication.service';
import { JwtModule } from '@nestjs/jwt';

@Module({
  imports: [PassportModule, JwtModule.register({ secret: 'secret-key' })],
  providers: [AuthenticationService],
})
export class AuthenticationModule {}

Get the token for future requests

So now we should create a sign in endpoint which will return our token.

// All other imports
// ...
import { AuthenticationService } from 'src/authentication/authentication.service';

@Controller('example')
export default class ExampleController {
  constructor(
    private readonly exampleService: ExampleService,
    private readonly authenticationService: AuthenticationService,
  ) {}

  @Get('sign-in')
  async signIn() {
    return await this.authenticationService.signIn({});
  }

  // All the other endpoints
  //...
}

That is looking good. The next step is to guard the rest of the endpoints by checking if there is a valid bearer token in the authorization header of the request. For that, we need to implement an authentication step in the server pipeline.

Implementing Passport

Looking at the official documentation, there is an authentication section. It introduces the passport library.

Passport gives us the middleware responsible for parsing the request and validating that the jwt token is valid.

We need to install the core Node library (passport), the underlying code to support a jwt strategy (passport-jwt), the NestJS wrapper (@nestjs/passport), and some types for development easiness (@types/passport-jwt).

npm install passport passport-jwt @nestjs/passport
npm install -D @types/passport-jwt

So how does Passport know if the jwt token is valid?

Configuring Passport JWT Strategy

In the same way, we configured NestJS's JwtModule for building our jwt tokens, Passport will need to be configured with the same parameters to be able to parse correctly the token.

To go alongside the convention, this configuration goes in a jwt.strategy.ts file inside the authentication folder. It defines a class that is responsible for extending the base passport strategy class with the configuration needed. This includes implementing a validate function which will consume a user validation callback (we need to code this callback). This class will be available through AuthenticationModule as a provider for the rest of the application to use. This implies that the strategy class should be decorated with @Injectable(). The file should look something like this:

// import the specific strategy from Passport
import { Strategy } from 'passport-jwt';
// import NestJS passport wrapper
import { PassportStrategy } from '@nestjs/passport';
// import the Injectable decorator to allow this class to be imported into the AuthenticationModule
import { Injectable } from '@nestjs/common';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super();
  }
}

For this to work properly we need to add some parameters to the base constructor. We will provide the two most basic ones:

jwtFromRequest: Defines where to find the jwt token (it could be another place than the authorization header...). We will stick with the classic Bearer schema. For that, the value should be ExtractJwt.fromAuthHeaderAsBearerToken(). This seems to map to this and this parts of the passport documentation about extracting the jwt token from the request.
secretOrKey: The key that will sign the tokens provided by our app. For demo purposes, the value will be "secret-key". This seems to map to this part of the passport documentation

The file ends up looking like this:

import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthenticationService } from './authentication.service';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private authenticationService: AuthenticationService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: 'secret-key',
    });
  }

  async validate(userInfo: any): Promise<any> {
    // This method needs to be implemented right now
    const user = await this.authenticationService.validateUser(userInfo);
    if (!user) {
      throw new UnauthorizedException();
    }
    return user;
  }
}

Now we are missing the user validation callback.

User validation

Passport requires a callback from us which will be used to validate a user. That validation callback receives the supposed user information as interpreted by the passport middleware. So with that information, we have to execute the validation process.

For this jwt strategy scenario, as we defined how our tokens are built, Passport already knows if the token is valid before the user validation. So what gets passed to our callback is the decoded jwt token. This is implied in this passage of the passport documentation.

Here we can add some logic if we wanted to. The only constraint is that if the validation es correct, we should return an object with useful user information (this info will be available at a user property of the request object). If not, the return value should be null. In our case, the validation will always succeed because we won't have users. Nonetheless, that validation callback needs to be implemented and should be placed in the AuthenticationService.

import { Injectable } from '@nestjs/common';

@Injectable({})
export class AuthenticationService {
  validateUser(userInfo: any): boolean | null {
    // Passport expects this return value to be a user object when validation is successful.
    // That info will be available at a `user` property in the `request` object
    return true;
  }

  // SignIn method
  // ...
}

For the module to work, we need to import the recently installed PassportModule. Also, the Authentication Service should be exposed as an export. So the file will look like this:

import { Module } from '@nestjs/common';
import { PassportModule } from '@nestjs/passport';
import { AuthenticationService } from './authentication.service';
import { JwtModule } from '@nestjs/jwt';

@Module({
  imports: [PassportModule, JwtModule.register({ secret: 'secret-key' })],
  providers: [AuthenticationService],
  exports: [AuthenticationService],
})
export class AuthenticationModule {}

Guard endpoints

What remains is to guard our endpoints. Last step to finish this one up. 💪

NestJS Passport wrapper provides us with an AuthGuard decorator. You can provide the strategy name for the guard, but it is better to extend the class to a specific one per strategy basis. That way the code is cleaner and easier to maintain. This is evident when you use more than one strategy. For now, we just have de jwt one, but when adding users and logging in, that endpoint should be guarded by the local strategy which is based on username and password.

import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class JwtGuard extends AuthGuard('jwt') {}

Then import the guard in the controller and use it!

@Controller('example')
export default class ExampleController {
  constructor(
    private readonly exampleService: ExampleService,
    private readonly authenticationService: AuthenticationService,
  ) {}

  @Get()
  @UseGuards(JwtGuard)
  index() {
    return this.exampleService.getAll();
  }

  // All other endpoints
  // ...
}

Try your endpoints with curl:

curl http://localhost:3000/example -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InVzZXJuYW1lIiwic3ViIjoic3ViIiwiaWF0IjoxNjY3MDc3NzYxfQ.LX2jeE1bavLOk9x-YvBZdEsfOo2ow4fMJ9DT4CYhXiE

curl http://localhost:3000/example

Wrap up

This concludes the third article of this series. Today we covered how to create a JWT token and validate it using the Passport library and guarding our endpoints with custom guards extending from the NestJS Passport wrapper.

Next, we should start including users to make this authentication more realistic. For that, we need to use a database. So that will be the next step. Set up a database, choose a library to interact with it, successfully self-sign up to the app, and then be able to log in (log out will be left for another time...).

That's all for now! thanks for reading. I hope these articles are useful to you. Have fun and keep learning!

Learning to build an API in NestJS (Node + Typescript) - Part 02

Fernando — Sat, 05 Nov 2022 16:11:30 +0000

Intro

If you have been following this series, skip the intro!

This is the second part of a series about learning NestJs for people who have experience building web applications but in languages other than typescript.

The structure of these articles is not scripted 👮 neither random 😕. My goal is to lay out everything I learn with as much depth as I can understand. I try to build working code that I understand and can replicate in upcoming real projects. That's why I don't write about any foo bar examples.

This is my learning process 📚... hopefully it will serve you as well.

Recap

At this point, we managed to code a module composed of a controller which returns a simple string when requesting its path.
Now we could start interacting with our endpoints, maybe adding some POST, PUT and DELETE requests. For that, we should probably know how to manage data. The concepts of imports and providers remain unexplored and seem to be what we need.

Let's dive into the documentation for providers.

Providers

Right off the bat, the analogy with service injection is made. So, we could think of providers as services that will be injected into other parts of the app, such as modules or controllers, or even other services?

Let's make a service for our controller to consume it. The database part will come later. For now, focus on getting a service up and running.

Again, a decorator is needed to make our service an injectable entity.
These four methods seem reasonable to develop:

import { Injectable } from '@nestjs/common';

@Injectable()
export default class ExampleService {
  get(id: string) {
    return 'Hello';
  }

  getAll() {
    return ['Hello'];
  }

  create(entity: string) {
    return 'Hello';
  }

  delete(id: string) {
    return 'Hello';
  }

  update(entity: string) {
    return 'Hello';
  }
}

Now inject it into the module! 😎
After this step, the service should be accessible at runtime by our controller.

import { Module } from '@nestjs/common';
import ExampleController from './example.controller';
import ExampleService from './example.service';

@Module({
  controllers: [ExampleController],
  providers: [ExampleService],
  imports: [],
  exports: [],
})
export default class ExampleModule {}

In the controller, let's make up some endpoints and call our newly created service. The injection is realized by adding the service as a parameter to the controller constructor.

import {
  Body,
  Controller,
  Delete,
  Get,
  Param,
  Post,
  Put,
} from '@nestjs/common';
import ExampleService from './example.service';

@Controller('example')
export default class ExampleController {
  constructor(private readonly exampleService: ExampleService) {}

  @Get()
  index() {
    return this.exampleService.getAll();
  }

  @Get(':id')
  details(@Param('id') id: string) {
    return this.exampleService.get(id);
  }

  @Post()
  create(@Body() dto: string) {
    return this.exampleService.create(dto);
  }

  @Put()
  update(@Body() dto: string) {
    return this.exampleService.update(dto);
  }

  @Delete(':id')
  delete(@Param('id') id: string) {
    return this.exampleService.delete(id);
  }
}

When running the app in watch mode, our changes seem to go unnoticed... Where are the routes we just defined!? 😮

Imports

It so happens that this is what imports are for. Following the NestJS architecture, we need to import the Module into the main AppModule.

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import ExampleModule from './example/example.module';

@Module({
  imports: [ExampleModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

And just like that... 💥

Right now, there is not much more to say about imports. Maybe we will return to this topic in the future.

Where to go now? 😕

I would like to implement something useful. Authentication comes to mind given that almost every application needs it. But I don't want to mess with database access or data encryption for the time being. So I will code a semi-public scheme. No users, for now, just an unguarded endpoint that always returns a valid token and a bunch of real authenticated endpoints properly guarded.

Wrap up

Congratulations if you made it this far! 😄🙌

In this article, we managed to implement a super basic service, inject it into a controller, route endpoints properly, capture params (query parameters, URI embedded parameters, and request body), and import a module to the main module.

That's all for now. I would like to make the next article completely about coding this authentication structure and not mix it up with this one.

Learning to build an API in NestJS (Node + Typescript)

Fernando — Sat, 29 Oct 2022 12:40:07 +0000

This is the first article of a series I'll be posting as an exercise for learning and digesting knowledge. Not just for me, but for other people that already have some coding experience on MVC projects but never built an API in Typescript.

If you want to dive into the "tutorial", skip the "My approach" section. However, I highly recommend you read it, to find out if my approach is what you are looking for and to get a sense of the prerequisites to follow along.

What this article will dive into

Scaffolding a NestJS App, Modules, and Controllers. If you don't know what those are, you will find out throughout this article.

My approach (given my context and background)

First, the premises which resulted in this (and the following posts), then I'll tell you my full background.

INITIAL DESIRE: Learn Typescript and use it to build an API

THE RESULTING GOAL: Build an API with NestJS understanding its modules, controllers, and services architecture.

My Background

I learned Web development working in a "Software Factory". The main programming language was C# in .Net Core and Entity Framework. I still work there and still code, but since I managed to get a grip on the coding part and the company's methodologies and architectures, my role changed to be more of a tech/team leader helping other new developers and noodling with the project management tasks. I am closing on three years of working here.

I still love coding and I would like to work on side projects with friends and colleagues. I love .Net Core. But I feel like I should know to build apps with other technologies. Not just to know more and get more coding skills. But to have a better understanding of other technologies so that I can better lead my teams and, last but not least, embark yet again on a learning journey that stimulates my brain cells.

Research building up to this story/tutorial.

First of all, I needed to learn typescript. So I looked at some youtube tutorials. If you know Javascript (like in my case), you need a quick tutorial teaching you the basics. Free Code Camp has great tutorials. I watched this one.

I found that NestJs is a mainstream framework for building APIs with typescript... So that seemed to be the no-brainer. It builds on top of Express, which is a framework I noodled on a bit at some point when I touched the surface of Node. I like to get the big picture of what I am going to do, so I worked along yet another YouTube video to build my first ever NestJs API. Now I want to really understand what is happening so that I can leverage this tool with my previously gained knowledge of building apps in .Net Core.

Enough about me. Let's dive into this story...

Ready, set, go be a noob... 😘

Startup

Begin with the official NestJs documentation which really talks about basic stuff: docs.

Go to the folder where you save all your projects and open a terminal there. Then run these commands to scaffold the NestJS project:

$ npm i -g @nestjs/cli
$ nest new project-name

The main.ts file is the one that holds the code for starting up the server. To keep things as familiar as possible, configure what Nest uses under the hood to be Express. That is done by importing the corresponding class and passing it to the create method of Nest.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { NestExpressApplication } from '@nestjs/platform-express';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  await app.listen(3000);
}
bootstrap();

You can run this basic app and access it on your browser at port 3000: $ npm run start

Taking a look at this main.ts file, we see there is a reference to an AppModule. So, what is it?

What are Modules?

Reading the docs, it seems like a Module is a structure that encapsulates and isolates functionality from another. It flirts with the microservice concept. If you are used to building classic layered applications, you usually scaffold an application layer, a business logic layer, a services layer, and a data access layer for example. The NestJs approach may be a little weird when you try to do some things the way you are used to. I will give you two examples:

If you try to replicate a typical application layer where you group all your controllers in a "Controllers" folder. This NestJs Module concept kind of throws that away. Obviously, you can do whatever you want... You could have just an AppModule with a hundred controllers and that's it...
If you try to implement a data access layer which is common for all the apps. That layer can be thought of as a module in itself. Clearly, not every module has to have controllers in it and you can place them in whatever folder you choose. Just decide which folder structure that soothes your mind.

Sticking with the NestJs way, let's leave that AppModule in peace and use it to bring together every other module that hopefully will be created by the end of this journey.

A Module is declared by decorating the Module's main class.

import { Module } from '@nestjs/common';
@Module({})
export class YourModule{}

The naming convention for this file is [module name].module.ts

Now that we declared the module, we should specify the things that this module provides to the app and also what it needs to work properly. This is defined on the object passed to the @Module decorator: controllers, providers, imports, and exports.

import { Module } from '@nestjs/common';
@Module({
  imports: [],
  controllers: [],
  providers: [],
  exports: []
})
export class YourModule{}

Of those 4 concepts, the only one that looks familiar is the controller. Let's start with that.

Controllers

A Controller is a class responsible for defining endpoints (path + handler method) that will process the incoming requests when the routing is set up. As with Modules, we need to decorate the class.

import { Controller, Get } from '@nestjs/common';

@Controller('your-controller')
export class YourController {
  constructor() {}

  @Get('say-hello')
  getHello(): string {
    return "Hello";
  }
}

Also, the controller endpoints should be decorated with the HTTP verb. The path is the result of combining what you define in the controller decorator and the HTTP verb decorator. This example defines an endpoint that routes to the path GET /your-controller/say-hello and returns a string "Hello".

You can access request properties by adding decorators to the method parameters. You need this to populate your parameters correctly, whether they come from the query parameters, the request body, or some URL-embedded parameter.

This way of deserializing the request is a bit lengthy for me, compared to my beloved .Net Core ❤️.

When you finish setting up your controller and endpoint, it should be included as a controller of some module. If not, NestJs does not know that this controller exists and the routing can not be done.

Wrap Up

These are the real basics for launching a local API with NestJs. We covered Controllers, Modules, and Providers. My brain is burning right now, so I think this is a good time to stop.

In the next article, we will try to interact with our API through GET, POST, PUT and DELETE endpoints. This will require parsing incoming requests, fetching data, and more. Surely we will need some service...

Here is me coding literally after I wrote this article. All the mistakes, errors, and distractions. No edit: