Forem: Alfi Samudro Mulyo

[React JS] Getting started with react-hook-form and Zod. For better form handling

Alfi Samudro Mulyo — Tue, 06 Feb 2024 01:09:23 +0000

At the beginning of working with React, I had difficulty handling many inputs in a form with validation. I create a different state for every input element, so when there are more and more input elements, the number of states also increases, making it painful to maintain.

But now, all those difficulties are gone since I found React Hook Form and zod.

React Hook Form reduces the amount of code you need to write while removing unnecessary re-renders and it works really well with Zod. Zod is a TypeScript-first schema declaration and validation library.

Preparation

Please take note that the code below is written in typescript.

All we need to do is just install these three packages:

npm install zod
npm install react-hook-form
npm install @hookform/resolvers

to your React project.

Let's dive into the code.

First of all, we need to import the packages mentioned above:



import { useForm, SubmitHandler } from "react-hook-form";
import { z } from "zod";
import { zodResolver } from "@hookform/resolvers/zod";

Create schema and validation rules using Zod:



const schema = z.object({
  name: z.string().min(1, { message: "Name is required." }),
  email: z
    .string()
    .min(1, { message: "Email is required." })
    .email({ message: "Please enter a valid email." }),
  password: z
    .string()
    .min(8, { message: "Password must be at least 8 characters." })
    .regex(
      /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$/,
      {
        message:
          "Password must contain at least one uppercase, one lowercase, one number, one special character",
      }
    ),
});

This is the beauty of Zod as it simplifies schema validation effortlessly. In the provided code, we define three attributes along with their respective validation rules, signifying that our form will encompass three distinct inputs.

Since we're using typescript, let's convert the schema above into type so we have typesafe for every part of our code moving on:



type FormFields = z.infer<typeof schema>;

By assigning FormFields to React Hook Form, we'll have beautiful typesafe

We've done with schema. Now, let's move on to React function component. In the previous steps, we already created schema and FormFields so we can attach them to React Hook Form:



const {
  register,
  handleSubmit,
  setError,
  formState: { errors, isSubmitting },
} = useForm<FormFields>({
  resolver: zodResolver(schema),
});

register: In React Hook Form, the register function is a crucial method that allows you to register your input components with the form. By doing so, you inform the form about the existence of your input fields, enabling the library to manage their state and validation.

handleSubmit: The handleSubmit function in React Hook Form is a utility provided by the library to simplify the form submission process. It handles the form validation, prevents the default form submission behavior, and executes the provided callback function with the validated form data.

setError: A function used to manually set an error for a specific field. This can be useful in scenarios where you want to trigger or display a custom error message based on certain conditions.

formState: An object that provides information about the state of the form. It is typically used to access information such as whether the form is submitting, submitted, or if there are any validation errors, etc.

Here is the code:



function Home() {
  const {
    register,
    handleSubmit,
    setError,
    formState: { errors, isSubmitting },
  } = useForm <
  FormFields >
  {
    resolver: zodResolver(schema),
  };

  // FUNCTION TO HANDLE FORM SUBMISSION
  const onSubmit: SubmitHandler<FormFields> = async (data) => {
    try {
      await new Promise((resolve) => setTimeout(resolve, 1000));

      // throw new Error("Email is already taken.");

      alert(JSON.stringify(data));
    } catch (error) {
      // SET ERROR MESSAGE IF ANY ERROR OCCURS
      setError("email", {
        message: "Email is already taken.",
      });
    }
  };

  return (
    <div className="flex flex-col items-center justify-center h-screen">
      <h1 className="text-2xl mb-4">Register Form</h1>
      <form
        onSubmit={handleSubmit(onSubmit)}
        className="flex flex-col gap-2 w-96"
      >
        <input
          // REGISTER INPUT FIELD
          {...register("name")}
          className="border w-full rounded-md p-4"
          type="text"
          placeholder="Name"
        />
        {/* SHOW ERROR MESSAGE IF OCCURED */}
        {errors.name && (
          <span className="text-xs text-red-600 font-semibold">
            {errors.name.message}
          </span>
        )}
        <input
          // REGISTER INPUT FIELD
          {...register("email")}
          className="border w-full rounded-md p-4"
          type="text"
          placeholder="Email"
        />
        {/* SHOW ERROR MESSAGE IF OCCURED */}
        {errors.email && (
          <span className="text-xs text-red-600 font-semibold">
            {errors.email.message}
          </span>
        )}
        <input
          // REGISTER INPUT FIELD
          {...register("password")}
          className="border w-full rounded-md p-4"
          type="password"
          placeholder="Password"
        />
        {/* SHOW ERROR MESSAGE IF OCCURED */}
        {errors.password && (
          <span className="text-xs text-red-600 font-semibold">
            {errors.password.message}
          </span>
        )}

        <button
          type="submit"
          disabled={isSubmitting} // DISABLE BUTTON IF FORM IS SUBMITTING
          className="bg-blue-500 text-white p-2 rounded disabled:bg-gray-300 disabled:cursor-not-allowed"
        >
          {isSubmitting ? "Loading..." : "Register"}{" "}
          {/* SHOW LOADING TEXT IF FORM IS SUBMITTING */}
        </button>
      </form>
    </div>
  );
}

Full code

That's all. No need to create a bunch of states anymore. If the inputs keep growing, we can just add them to the schema and let the React Hook Form + Zod do the magic.

7 Awesome YouTube Channels that Will Help You to Be a Better Software Engineer 🧑‍💻

Alfi Samudro Mulyo — Thu, 02 Nov 2023 11:00:00 +0000

I believe that most software engineers learn from the internet. It can be from online resources such as blogs, free/paid online courses, interactive coding platforms (like HackerRank and LeetCode), video tutorials, and others.

I usually learn through the sources mentioned above. But in my opinion, the most effective way to learn is through YouTube videos because we can see how other people write their code step by step. And the best thing about it is free.

Here, I will share YouTube channels that I think are good and teach me a lot.

Here is the list:

Josh tried coding

https://www.youtube.com/@joshtriedcoding/featured
The videos on this channel are very well explained. We can find many good tips, tutorials, or even long tutorials that build something from scratch.

Web Dev Simplified

https://www.youtube.com/@WebDevSimplified
This is one of the most my favorite programming channels. The channel's name is not a joke. They are simplified and very well explained. It makes the audience easy to understand.

Cosden Solutions

https://www.youtube.com/@cosdensolutions
If you're a front-end developer, especially in React, this is the best channel I can suggest. All videos are well explained, and it's not only about how to write React code but also how to write React code in a good way.

Sonny Sangha

https://www.youtube.com/@SonnySangha
It's not an ordinary YouTube programming channel, because you'll find super good tutorials here. A lot of long video tutorials and web clones can be found here.

freeCodeCamp.org

https://www.youtube.com/@freecodecamp
If you need a YouTube channel that covers all the programming topics, we can't find anything better than this. From beginner to advanced level, all are covered here.

Fireship

https://www.youtube.com/@Fireship/featured
This one is also a great YouTube channel. If you want to keep up with the most updated programming topics, here is the right place.

CodeAesthetic

https://www.youtube.com/@CodeAesthetic/videos
This channel doesn't have many videos yet, but all the videos here are great. It is animated very well, making it easier to understand.

That's YouTube programming channels I usually learn from. Besides the channels mentioned above, there are tons of other channels also great.

Happy learning, happy coding 🧑‍💻

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 7

Alfi Samudro Mulyo — Wed, 01 Nov 2023 13:31:49 +0000

Scope of discussion:

Create API documentation

This is the last part of this Nest JS series.

Since we already created some endpoints in our API, now it's time for us to write the documentation.

Nest JS itself is compatible with OpenAPI. It's well-documented and super easy to write using Nest JS Swagger.

openAPI doc.

Here, I'll just give a small example of how to build Nest JS API documentation. We'll use register API as a reference. Without any further ado, let's go 🔥🔥🔥

Installation and Config

First of all, let's install the Nest JS Swagger:
$ npm install --save @nestjs/swagger

Once installed, let's continue to update our main.ts, because we need to initialize in the Nest JS bootstrap function:



// src/main.ts

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  ...

  // Check here - Swagger setup
  const config = new DocumentBuilder()
    .setTitle('Superb API')
    .setDescription('The Super API documentation')
    .setVersion('1.0')
    .addTag('superb')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  ...

  await app.listen(3000);
}

Then let's try to run our API using npm run start:dev, and open this URL http://localhost:3000/api. We'll see:

All endpoints that we created will be listed there. If you scroll down, you'll see the empty DTO schemas:

Our API documentation is ready, but it's still messy. So we're going to make it more organized. We'll only touch controller and dto files, and add some decorators.

Add decorators to controller

Let's update our registerUser function in users.controller.ts for an example:



@Post('register')
// 💡 See here. Add this decorator to add operationId to swagger docs
@ApiOperation({
  summary: 'Register a new user',
  operationId: 'create',
})
// 💡 See here. Add this decorator to add API response to swagger docs
@ApiResponse({
  status: 201,
  description: 'Created',
  type: CreateUserDto,
})
async registerUser(@Body() createUserDto: CreateUserDto): Promise<User> {
  // call users service method to register new user
  return this.usersService.registerUser(createUserDto);
}

If you refresh the documentation page, you'll see users endpoints are grouped:

Schema is still empty

And we can see the responses as well:

Add decorators to DTO

Now let's add decorators to our CreateUserDto:



export class CreateUserDto {
  // 💡 See here. Add this decorator
  @ApiProperty({
    example: 'email@email.com',
    description: 'The email of new user.',
    type: String,
  })
  @IsNotEmpty()
  @IsEmail()
  email: string;

  // 💡 See here. Add this decorator
  @ApiProperty({
    example: 'super_secret_password',
    description: 'The password of new user.',
    type: String,
  })
  @IsNotEmpty()
  password: string;

  // 💡 See here. Add this decorator
  @ApiProperty({
    example: 'John Doe',
    description: 'The full name of new user.',
    type: String,
  })
  @IsNotEmpty()
  name: string;
}

Now we can see the DTO schema:

It's super easy, isn't it? 😄

OpenAPI itself has so many attributes. If you want to explore more, just open Nest JS documentation here:

and you'll find tons of features.

I think that's all about this latest part.

The full code of part 7 can be accessed here:
https://github.com/alfism1/nestjs-api/tree/part-seven

Thank you!

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 6

Alfi Samudro Mulyo — Tue, 31 Oct 2023 23:36:01 +0000

Scope of discussion:

Explain about e2e (end-to-end) testing
Handle multiple env files
Write e2e (end-to-end) testing code

In the previous part, we've written code for unit testing. Now, let's move to e2e testing.

What is e2e testing? end-to-end (e2e) testing is a type of software testing that is used to validate the entire system or application from start to finish. E2E testing is designed to simulate real-world scenarios and test the system's functionality, performance, and reliability in a production-like environment.

So, we will hit our real API which will make some updates to the database as well. That's the reason why we need to create .env.test and set a different DATABASE_URL in it, especially for e2e testing. We will use a different database. If we don't do that, our production or development database might be broken.

Pre-configuration

Since we're going to use another env file called .env.test, we need to rename our .env file to something else, for example, I renamed my .env to .env.development. Why? because .env will overwrite other env files. I've tried that before. My .env.test won't work unless I rename my file .env. This will also be useful, we can set any other environment like:

.env.production
.env.development
.env.test based on our needs. Normally, each environment will have a different configuration.

After that, we need to update our scripts inside package.json by adding NODE_ENV as below:



"start": "NODE_ENV=production nest start",
"start:dev": "NODE_ENV=development nest start --watch",
"start:debug": "NODE_ENV=development nest start --debug --watch",
"start:prod": "NODE_ENV=production node dist/main",
...
"test:e2e": "NODE_ENV=test jest --config ./test/jest-e2e.json"

e2e testing configurations

Unlike unit testing, our e2e testing code is written in a separate folder /test. Inside /test folder, we'll find two files; app.e2e-spec.ts and jest-e2e.json. Before diving into the code, let's update jest-e2e.json by adding moduleNameMapper property:



"moduleNameMapper": {
  "^src/(.*)": "<rootDir>/../src/$1"
}

otherwise, we won't be able to import our modules.

Before continuing, let's do some tests by running the e2e test npm run test:e2e and see what will happen:

We got 404 error because, in part 1, we updated the base endpoint (/) to /test, so / is not found. Let's update it, open up app.controller.ts, change @Get('test') to @Get() and run the npm run test:e2e again:

We still got an error, but now is different. Instead of getting 404 error, we got 401 error which means that the endpoint is not public. So, let's set this endpoint as public by adding @Public() decorator, then run the e2e test again:
As you can see, now e2e test success ✅

The next step is creating a new file called .env.test by copy-paste our .env (or .env.development in my case) file, then setting the DATABASE_URL to select another database, for example, I select superb-api-test database:

Then, let's run this command to create tables in our test database npx dotenv -e .env.test prisma db push

We need to install config package from Nest JS:
$ npm i --save @nestjs/config

Once the package is installed, we need to register a configuration in our app.module.ts. Let's just open app.module.ts file and make these updates:



imports: [
  // See here. Add config module
  ConfigModule.forRoot({
    envFilePath: process.env.NODE_ENV
      ? `.env.${process.env.NODE_ENV}`
      : '.env',
    isGlobal: true,
  }),

  ...

  UsersModule,
  PostsModule,

  ...
],

Make sure to put ConfigModule at the top of other module imports

The last configuration will be updating test:e2e script in our package.json. Open up package.json and update test:e2e script by adding NODE_ENV=test. Here is the full snippet:
"test:e2e": "NODE_ENV=test jest --config ./test/jest-e2e.json".

Now let's write our e2e testing code 🔥

Our e2e testing code will be written in test/app.e2e-spec.ts. We'll start with importing some modules; AppModule, UsersModule, PostsModule, PrismaClient, and TRUNCATE all tables as well before running the tests in beforeAll:



beforeAll(async () => {
  const moduleFixture: TestingModule = await Test.createTestingModule({
    imports: [AppModule, UsersModule, PostsModule, PrismaClient],
  }).compile();

  app = moduleFixture.createNestApplication();
  await app.init();

  prismaClient = moduleFixture.get<PrismaClient>(PrismaClient);

  await prismaClient.$executeRaw`TRUNCATE "public"."Post" RESTART IDENTITY CASCADE;`;
  await prismaClient.$executeRaw`TRUNCATE "public"."User" RESTART IDENTITY CASCADE;`;
}, 30000);

Then, after all tests are completed, we need to close the app and disconnect the prismaClient:



afterAll(async () => {
  await app.close();
  await prismaClient.$disconnect();
}, 30000);

Here is the full code:



// test/app.e2e-spec.ts

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from './../src/app.module';
import { UsersModule } from 'src/modules/users/users.module';
import { PostsModule } from 'src/modules/posts/posts.module';
import { PrismaClient } from '@prisma/client';

describe('Superb API (e2e)', () => {
  let app: INestApplication;
  let prismaClient: PrismaClient;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule, UsersModule, PostsModule, PrismaClient],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();

    prismaClient = moduleFixture.get<PrismaClient>(PrismaClient);

    await prismaClient.$executeRaw`TRUNCATE "public"."Post" RESTART IDENTITY CASCADE;`;
    await prismaClient.$executeRaw`TRUNCATE "public"."User" RESTART IDENTITY CASCADE;`;
  }, 30000);

  afterAll(async () => {
    await app.close();
    await prismaClient.$disconnect();
  }, 30000);

  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });
});

Let's start with register and login:



// register

it('should create a user', async () => {
  const user = {
    email: 'newuser@e2e.test',
    name: 'New User',
    password: '12345678',
  };

  const response = await request(app.getHttpServer())
    .post('/users/register')
    .send(user)
    .expect(201);

  expect(response.body).toEqual({
    id: expect.any(Number),
    email: user.email,
    name: user.name,
  });
});



it('should login a user', async () => {
  const user = {
    email: 'newuser@e2e.test',
    password: '12345678',
  };

  const response = await request(app.getHttpServer())
    .post('/users/login')
    .send(user)

    .expect(201);

  expect(response.body).toEqual({
    access_token: expect.any(String),
  });
});

it('should not login a user', async () => {
  const user = {
    email: 'wronguser@e2e.test',
    password: '12345678',
  };

  const response = await request(app.getHttpServer())
    .post('/users/login')
    .send(user)

    .expect(404);

  expect(response.body.message).toEqual('User not found');
  expect(response.body.status).toEqual(404);
});

Okay, we've written e2e test for register and login. Now let's try to run it:

All is good. Now you can try to write e2e tests for Posts endpoints by yourself 😁

Now we're done with this part :)

The full code of part 6 can be accessed here:
https://github.com/alfism1/nestjs-api/tree/part-six

Moving on to part 7
https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-7-6me

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 5

Alfi Samudro Mulyo — Sun, 29 Oct 2023 07:56:50 +0000

Scope of discussion:

Explain about testing
Create unit testing for users

So far, we've created two endpoints; users and posts.

Users endpoints:
POST /users/register,
POST /users/login,
GET /users/me,
PATCH /users/:id,
DELETE /users/:id.

Posts endpoints:
POST /posts,
GET /posts,
GET /posts/:id,
PATCH /posts/:id,
DELETE /posts/:id.

We tested it and everything works as expected. Does it mean our API is ready for production? Technically, we can use it as we already tested it during the development process. But we can do something to minimize the occurrence of bugs because does not rule out the possibility that our API will be grown and will have more features in the future.

What we can do? In the software development world, it's common to write code for testing purposes. We'll have advantages for writing testing code (especially in regression testing) that will save our time to do the automated testing instead of doing manual testing one by one from the very beginning. Not just that, writing testing code will make us more confident to release our code to production.

There are some kinds of testing, but we'll only cover unit testing and e2e (end-to-end) testing. Let's focus on unit testing first (we'll do e2e testing in the next part).

If we take a look at our current codes, we can find an example of unit testing, written in a file named app.controller.spec.ts:



import { Test, TestingModule } from '@nestjs/testing';
import { AppController } from './app.controller';
import { AppService } from './app.service';

describe('AppController', () => {
  let appController: AppController;

  beforeEach(async () => {
    const app: TestingModule = await Test.createTestingModule({
      controllers: [AppController],
      providers: [AppService],
    }).compile();

    appController = app.get<AppController>(AppController);
  });

  describe('root', () => {
    it('should return "Hello World!"', () => {
      expect(appController.getHello()).toBe('Hello World!');
    });
  });
});

We can try to run the code. In the terminal, go to the root folder of the project and run npm run test

For more details about testing, read the official documentation here: https://docs.nestjs.com/fundamentals/testing

Let's get started 🔥

Make sure to install the testing package $ npm i --save-dev @nestjs/testing. By default, it's already installed during the Nest JS project initialization in part 1.

Before diving into the code, we need to do a small configuration. For your information, we'll use jest library (for more information about jest, click here). Open up package.json on the root project folder, and find jest property:



"jest": {
  "moduleFileExtensions": [
    "js",
    "json",
    "ts"
  ],
  "rootDir": "src",
  ...
  any other config goes here...
  ...
}

Let's add two properties (testEnvironment and moduleNameMapper) inside jest object:



"jest": {
  "moduleFileExtensions": [
    "js",
    "json",
    "ts"
  ],
  "rootDir": "src",

  ...

  "testEnvironment": "node",
  "moduleNameMapper": {
    "^src/(.*)": "<rootDir>/$1"
  }
}

If you don't update your jest config, you'll get an error during the import module.

Now, let's write our first unit testing code for users controller. Create a new file called users.controller.spec.ts:



// src/modules/users/users.controller.spec.ts

import { Test, TestingModule } from '@nestjs/testing';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

describe('UsersController', () => {
  let controller: UsersController;

  beforeAll(async () => {
    const app: TestingModule = await Test.createTestingModule({
      controllers: [UsersController],
      providers: [UsersService],
    }).compile();

    controller = app.get<UsersController>(UsersController);
  });

  it('should be defined"', () => {
    expect(controller).toBeDefined();
  });

  describe('users controller', () => {
    // 💡 Test code goes here ...
  });
});

I updated to beforeAll because each test uses the same resource.

then try to run npm run test again

Normally we will get this error because users.service is dependent on PrismaService. So we have to import PrismaService to our test code:



const app: TestingModule = await Test.createTestingModule({
  controllers: [UsersController],
  providers: [
    UsersService,
    PrismaService, // 💡 add prisma service here
  ],
}).compile();

You may wonder why users.service or users.controller doesn't need to import PrismaService but in tests, we need them to be imported? In the Nest JS module, we define the PrismaService globally via CoreModule so it can be used in any other modules. Testing code is not part of Nest JS modules, that's why we have to import PrismaService individually.

Then, try to run npm run test again after we imported PrismaService. And again, we still get an error but it's different.

We need to import JwtService as well to make this work:



const app: TestingModule = await Test.createTestingModule({
  controllers: [UsersController],
  providers: [
    UsersService,
    PrismaService, // 💡 add prisma service here
    {
      provide: JwtService, // 💡 add jwt service here
      useValue: {
        signAsync: jest.fn(), // 💡 mock signAsync method
      },
    },
  ],
}).compile();

In unit testing, we will not execute the actual function instead we will just mock the process or result, that's why we mock the signAsync function using jest.fn() as a replacement for the actual process access_token: await this.jwtService.signAsync(payload), in the users.service.ts.

Now let's try again, it should work ✅

We're ready to write our test codes now 🔥
In the users.controller.ts, we have five functions; registerUser, loginUser, me, updateUser, and deleteUser.

We'll try to cover those five functions in unit testing. All the test scenarios will be written inside:



describe('users controller', () => {
  // 💡 registerUser method

  // 💡 loginUser method

  // 💡 me method

  // 💡 updateUser method

  // 💡 deleteUser method
});

Let's start with registerUser test first:



// 💡 registerUser method
it('should register new user', async () => {
  const newUser = {
    email: 'test@user.com',
    name: 'Test User',
    password: 'password',
  };

  const mockRegisterResponse: User = {
    id: 1,
    email: 'test@user.com',
    name: 'Test User',
    password: 'password',
  };

  // delete password from response
  delete mockRegisterResponse.password;

  // 💡 See here -> we mock registerUser function from users.controller.ts
  // to return mockRegisterResponse
  jest
    .spyOn(controller, 'registerUser')
    .mockResolvedValue(mockRegisterResponse);

  // 💡 See here -> we call registerUser method from users.controller.ts
  // with newUser as parameter
  const result = await controller.registerUser(newUser);

  // 💡 See here -> we expect result to be mockRegisterResponse
  expect(result).toEqual(mockRegisterResponse);
});

In the code above, we've written the success register test and if you run npm run test will be marked as a success.

We can write for the failed register test as well:



// 💡 test register error due to email already registered
it('should throw error if email already registered', async () => {
  const registeredUser = {
    email: 'registered@user.com',
    name: 'Registered User',
    password: 'password',
  };

  jest
    .spyOn(controller, 'registerUser')
    .mockRejectedValue(new ConflictException());

  const register = controller.registerUser(registeredUser);

  await expect(register).rejects.toThrow(ConflictException);
});

// 💡 test register error due to missing some fields
it('should throw error if required fields is missing', async () => {
  jest
    .spyOn(controller, 'registerUser')
    .mockRejectedValue(new BadRequestException());

  const register = controller.registerUser(null);

  await expect(register).rejects.toThrow(BadRequestException);
});

Quick overview. We created three test cases for register:

test register success,

test register error due to email already registered, and

test register error due to missing some fields.

Let's continue to loginUser. First, we'll create the success login test case:



// 💡 test login success
it('should login user', async () => {
  const mockLoginResponse = {
    access_token:
      'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyeyey',
  };

  // 💡 See here -> we mock loginUser function from users.controller.ts
  // to return mockLoginResponse
  jest
    .spyOn(controller, 'loginUser')
    .mockResolvedValue(mockLoginResponse);

  // 💡 See here -> we call loginUser method from users.controller.ts
  // with mockLoginResponse as parameter
  const result = await controller.loginUser({
    email: 'some@user.com',
    password: 'password',
  });

  expect(result).toEqual(mockLoginResponse);
  expect(result.access_token).toBeDefined();
});

and test case for login error with the wrong email:



 // 💡 test login error due to wrong email
it('should throw error if email is wrong', async () => {
  const wrongEmail = {
    email: 'wrong@user.com',
    password: 'password',
  };

  jest
    .spyOn(controller, 'loginUser')
    .mockRejectedValue(new NotFoundException());

  const login = controller.loginUser(wrongEmail);

  await expect(login).rejects.toThrow(NotFoundException);
});

Quick overview. We created two test cases for login:

test login success

test login error due to wrong email

We're done with loginUser and registerUser test cases. There are still three methods remaining; me, updateUser, and deleteUser.

I won't write all the test cases in this article. But don't worry. The full version is in my GitHub repository 🔗

Check the user full test code here: https://github.com/alfism1/nestjs-api/blob/part-four/src/modules/users/users.controller.spec.ts

Now we're done with this part :)

The full code of part 5 can be accessed here:
https://github.com/alfism1/nestjs-api/tree/part-five

Moving on to part 6
https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-6-c51

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 4

Alfi Samudro Mulyo — Sat, 28 Oct 2023 20:52:06 +0000

Scope of discussion:

Update getAllPosts function to have pagination
Create a utility function to handle pagination

In the third part, we've created Post endpoints:

POST /posts: Create a new post,
GET /posts: Get all posts,
GET /posts/:id: Get post by ID,
PATCH /posts/:id: Update post by ID,
DELETE /posts/:id: Delete post by ID.

Let's focus on get all posts endpoint. To get the posts data, we use prisma ORM await this.prisma.post.findMany() and it will return all the posts data. Looks fine, right? but it's not actually fine. Imagine if our posts data is getting bigger, let's say our posts have 100k rows, it will make the API response slow. The more data, the slower it will be.

So, what's the solution?

Fortunately, prisma provide skip and take property in findMany ORM; for example:

await this.prisma.post.findMany({
  skip: 0,
  take: 10,
});

We'll use query parameter in the URL to input the pagination variable GET /posts?page=1&size=2. page represents the selected page, size represents how many data we want to display.

Let's create a new DTO (Data Transfer Object) to validate the query params. Create a new file called query-pagination.dto.ts:

// src/common/dtos/query-pagination.dto.ts

import { IsNumberString, IsOptional } from 'class-validator';

export class QueryPaginationDto {
  @IsOptional()
  @IsNumberString()
  page?: string;

  @IsOptional()
  @IsNumberString()
  size?: string;
}

We'll create a utility code to handle our pagination called pagination.utils.ts:

// src/common/utils/pagination.utils.ts

import { NotFoundException } from '@nestjs/common';
import { QueryPaginationDto } from '../dtos/query-pagination.dto';

const DEFAULT_PAGE_NUMBER = 1;
const DEFAULT_PAGE_SIZE = 10;

export interface PaginateOutput<T> {
  data: T[];
  meta: {
    total: number;
    lastPage: number;
    currentPage: number;
    totalPerPage: number;
    prevPage: number | null;
    nextPage: number | null;
  };
}

export const paginate = (
  query: QueryPaginationDto,
): { skip: number; take: number } => {
  const size = Math.abs(parseInt(query.size)) || DEFAULT_PAGE_SIZE;
  const page = Math.abs(parseInt(query.page)) || DEFAULT_PAGE_NUMBER;
  return {
    skip: size * (page - 1),
    take: size,
  };
};

export const paginateOutput = <T>(
  data: T[],
  total: number,
  query: QueryPaginationDto,
  //   page: number,
  //   limit: number,
): PaginateOutput<T> => {
  const page = Math.abs(parseInt(query.page)) || DEFAULT_PAGE_NUMBER;
  const size = Math.abs(parseInt(query.size)) || DEFAULT_PAGE_SIZE;

  const lastPage = Math.ceil(total / size);

  // if data is empty, return empty array
  if (!data.length) {
    return {
      data,
      meta: {
        total,
        lastPage,
        currentPage: page,
        totalPerPage: size,
        prevPage: null,
        nextPage: null,
      },
    };
  }

  // if page is greater than last page, throw an error
  if (page > lastPage) {
    throw new NotFoundException(
      `Page ${page} not found. Last page is ${lastPage}`,
    );
  }

  return {
    data,
    meta: {
      total,
      lastPage,
      currentPage: page,
      totalPerPage: size,
      prevPage: page > 1 ? page - 1 : null,
      nextPage: page < lastPage ? page + 1 : null,
    },
  };
};

In the code above, we created:

const DEFAULT_PAGE_NUMBER to define the default page number,
const DEFAULT_PAGE_SIZE to define the default page size per page,
interface PaginateOutput to define the response schema we'll receive. The data itself contains an array and it is dynamic since we pass generic type T, for example:

const users: User[] = [/* ... */];
const paginateOutput: PaginateOutput<User> = {
  data: users,
  total: users.length,
  page: 1,
  limit: 10,
};

function paginate to convert query params into prisma property. It returns an object with skip and page properties and we can use it in prisma. We'll use it in posts.service
function paginateOutput to handle the pagination output response. It has a generic type and three parameters (data, total, and query).

All set. Now, we're ready to update our posts.controller and posts.service. Let's start with posts.service by updating getAllPosts function:

async getAllPosts(query?: QueryPaginationDto): Promise<PaginateOutput<Post>> {
  const [posts, total] = await Promise.all([
    await this.prisma.post.findMany({
      ...paginate(query),
    }),
    await this.prisma.post.count(),
  ]);

  return paginateOutput<Post>(posts, total, query);
}

In the getAllPosts function above, we add a QueryPaginationDto as an optional parameter called query. We also updated the function return type to Promise<PaginateOutput<Post>> since we want the response to be a pagination.

The tricky part is on the Promise.all. Besides we need the data, we need the total data or count data as well, that's why also invoke await this.prisma.post.count(). Posts data will be stored in posts variable, and total data will be stored in total using Promise.all.

Then, we return the data using paginateOutput and pass parameters into it paginateOutput<Post>(posts, total, query);.

We're done with posts.service. Now let's move on to posts.controller.

In the posts.controller, we'll only update getAllPosts function:

getAllPosts(
  @Query() query?: QueryPaginationDto,
): Promise<PaginateOutput<CPost>> {
  return this.postsService.getAllPosts(query);
}

It's more simpler compared to posts.service. What we need to do is just add @Query decorator and pass it into the getAllPosts service.

So we're done with the pagination.

Let's test the pagination:

Great! All works as we expect 🔥

The full code of part 4 can be accessed here: https://github.com/alfism1/nestjs-api/tree/part-four

Moving on to part 5:
https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-5-1ggd

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 3

Alfi Samudro Mulyo — Sat, 28 Oct 2023 01:12:59 +0000

Scope of discussion:

Create CRUD for posts endpoints
Protect edit and delete routes access from non-author

In the second part, we've handled route protection by using auth.guard. Some of the endpoints are public (like login and register). By default, the routes will be defined as private that need access_token.

Also, we protect a user from updating/deleting other user's data by using is-mine.guard

So far, we've completed the users routes with basic CRUD, Validation, Authentication, and Route protection. Now let's move on to the Post model.

Post model will have the same basic CRUD, validation, and route protection as we did in User model. Here are the Post endpoints:

POST /posts: Create a new post,
GET /posts: Get all posts,
GET /posts/:id: Get post by ID,
PATCH /posts/:id: Update post by ID,
DELETE /posts/:id: Delete post by ID.

We'll use the same project structure for building Post. Let's recall what are the files inside src/modules/users folder:

Let's start with creating three main files:

src/modules/posts/posts.service.ts
src/modules/posts/posts.module.ts
src/modules/posts/posts.controller.ts

and dto files:

src/modules/posts/dtos/create-post.dto.ts ```typescript

// src/modules/posts/dtos/create-post.dto.ts

import { IsNotEmpty } from 'class-validator';

export class CreatePostDto {
@IsNotEmpty()
title: "string;"

@IsNotEmpty()
content: string;

@IsNotEmpty()
published: boolean = false;

authorId: number;
}

- `src/modules/posts/dtos/update-post.dto.ts`
```typescript


// src/modules/posts/dtos/update-post.dto.ts

import { PartialType } from '@nestjs/mapped-types';
import { CreatePostDto } from './create-post.dto';

export class UpdatePostDto extends PartialType(CreatePostDto) {}

We'll start building Post endpoints from the controller. Here is what the src/modules/posts/posts.controller.ts will look like:



// src/modules/posts/posts.controller.ts

import {
  Body,
  Controller,
  Delete,
  Get,
  Param,
  ParseIntPipe,
  Patch,
  Post,
  Request,
  UseGuards,
} from '@nestjs/common';
import { CreatePostDto } from './dtos/create-post.dto';
import { UpdatePostDto } from './dtos/update-post.dto';
import { PostsService } from './posts.service';
import { Post as CPost } from '@prisma/client';
import { Public } from 'src/common/decorators/public.decorator';
import { IsMineGuard } from 'src/common/guards/is-mine.guard';
import { ExpressRequestWithUser } from '../users/interfaces/express-request-with-user.interface';

@Controller('posts')
export class PostsController {
  // inject posts service
  constructor(private readonly postsService: PostsService) {}

  @Post()
  async createPost(
    @Body() createPostDto: CreatePostDto,
    @Request() req: ExpressRequestWithUser,
  ): Promise<CPost> {
    // 💡 See this. set authorId to current user's id
    createPostDto.authorId = req.user.sub;
    return this.postsService.createPost(createPostDto);
  }

  @Public()
  @Get()
  getAllPosts(): Promise<CPost[]> {
    return this.postsService.getAllPosts();
  }

  @Public()
  @Get(':id')
  getPostById(@Param('id', ParseIntPipe) id: number): Promise<CPost> {
    return this.postsService.getPostById(id);
  }

  @Patch(':id')
  @UseGuards(IsMineGuard) // <--- 💡 Prevent user from updating other user's posts
  async updatePost(
    @Param('id', ParseIntPipe) id: number,
    @Body() updatePostDto: UpdatePostDto,
  ): Promise<CPost> {
    return this.postsService.updatePost(+id, updatePostDto);
  }

  @Delete(':id')
  @UseGuards(IsMineGuard) // <--- 💡 Prevent user from deleting other user's posts
  async deletePost(@Param('id', ParseIntPipe) id: number): Promise<string> {
    return this.postsService.deletePost(+id);
  }
}

Then, let's create posts.service.ts:



// src/modules/posts/posts.service.ts

import {
  ConflictException,
  HttpException,
  Injectable,
  NotFoundException,
} from '@nestjs/common';
import { Post } from '@prisma/client';
import { PrismaService } from 'src/core/services/prisma.service';
import { CreatePostDto } from './dtos/create-post.dto';
import { UpdatePostDto } from './dtos/update-post.dto';

@Injectable()
export class PostsService {
  constructor(private prisma: PrismaService) {}

  async createPost(createPostDto: CreatePostDto): Promise<Post> {
    try {
      // create new post using prisma client
      const newPost = await this.prisma.post.create({
        data: {
          ...createPostDto,
        },
      });

      return newPost;
    } catch (error) {
      // check if email already registered and throw error
      if (error.code === 'P2002') {
        throw new ConflictException('Email already registered');
      }

      if (error.code === 'P2003') {
        throw new NotFoundException('Author not found');
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async getAllPosts(): Promise<Post[]> {
    const posts = await this.prisma.post.findMany();

    return posts;
  }

  async getPostById(id: number): Promise<Post> {
    try {
      // find post by id. If not found, throw error
      const post = await this.prisma.post.findUniqueOrThrow({
        where: { id },
      });

      return post;
    } catch (error) {
      // check if post not found and throw error
      if (error.code === 'P2025') {
        throw new NotFoundException(`Post with id ${id} not found`);
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async updatePost(id: number, updatePostDto: UpdatePostDto): Promise<Post> {
    try {
      // find post by id. If not found, throw error
      await this.prisma.post.findUniqueOrThrow({
        where: { id },
      });

      // update post using prisma client
      const updatedPost = await this.prisma.post.update({
        where: { id },
        data: {
          ...updatePostDto,
        },
      });

      return updatedPost;
    } catch (error) {
      // check if post not found and throw error
      if (error.code === 'P2025') {
        throw new NotFoundException(`Post with id ${id} not found`);
      }

      // check if email already registered and throw error
      if (error.code === 'P2002') {
        throw new ConflictException('Email already registered');
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async deletePost(id: number): Promise<string> {
    try {
      // find post by id. If not found, throw error
      const post = await this.prisma.post.findUniqueOrThrow({
        where: { id },
      });

      // delete post using prisma client
      await this.prisma.post.delete({
        where: { id },
      });

      return `Post with id ${post.id} deleted`;
    } catch (error) {
      // check if post not found and throw error
      if (error.code === 'P2025') {
        throw new NotFoundException(`Post with id ${id} not found`);
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }
}

Then, let's create posts.module.ts:



// src/modules/posts/posts.module.ts

import { Module } from '@nestjs/common';
import { PostsController } from './posts.controller';
import { PostsService } from './posts.service';

@Module({
  imports: [],
  controllers: [PostsController],
  providers: [PostsService],
})
export class PostsModule {}

Now we've completed the three main files:

src/modules/posts/posts.module.ts ✅
src/modules/posts/posts.controller.ts ✅
src/modules/posts/posts.service.ts ✅

We need to update is-mine.guard.ts to handle Post. Let's update the canActivate function:



async canActivate(context: ExecutionContext): Promise<boolean> {
  const request = context.switchToHttp().getRequest();

  // 💡 We can access the user payload from the request object
  // because we assigned it in the AuthGuard

  // 💡 Get instance of the route by splitting the path, e.g. /posts/1
  const route = request.route.path.split('/')[1];
  const paramId = isNaN(parseInt(request.params.id))
    ? 0
    : parseInt(request.params.id);

  switch (route) {
    // 💡 Check if the post belongs to the user
    case 'posts':
      const post = await this.prismaService.post.findFirst({
        where: {
          id: paramId,
          authorId: request.user.sub,
        },
      });

      return paramId === post?.id;
    default:
      // 💡 Check if the user manages its own profile
      return paramId === request.user.sub;
  }
}

Last, we need to import PostsModule to AppModule. Open up app.module.ts file and modify:



import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UsersModule } from './modules/users/users.module';
import { CoreModule } from './core/core.module';
import { JwtModule } from '@nestjs/jwt';
import { APP_GUARD } from '@nestjs/core';
import { AuthGuard } from './common/guards/auth.guard';
import { PostsModule } from './modules/posts/posts.module';

@Module({
  imports: [
    UsersModule,
    PostsModule,
    CoreModule,
    // add jwt module
    JwtModule.register({
      global: true,
      secret: process.env.JWT_SECRET,
      signOptions: { expiresIn: '12h' },
    }),
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
  ],
})
export class AppModule {}

We've completed the Post routes:

POST /posts
GET /posts
GET /posts/:id
PATCH /posts/:id
DELETE /posts/:id

The full code of part 3 can be accessed here: https://github.com/alfism1/nestjs-api/tree/part-three

Moving on to part 4: https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-4-oad

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 2

Alfi Samudro Mulyo — Fri, 27 Oct 2023 05:27:05 +0000

Scope of discussion:

Understanding about Guard in Nest JS
Understanding about Nest JS decorator
How to handle private or public routes

In the first part, we've created some users endpoints:

POST /users/register,
POST /users/login,
GET /users/me,
PATCH /users/:id, and
DELETE /users/:id

but we haven't handled this endpoint GET /users/me yet.

Don't worry, we're going to fix it.

We'll only use access_token obtained from the login response to get the user's data.

First, we must understand a guard in Nest JS. What does guard mean? According to the Nest JS documentation, guard is a class annotated with the @Injectable() decorator, which implements the CanActivate interface

Read more about guard.

And what is the purpose of Guard? Basically Guard is like a layer that is responsible for validating or updating any incoming request before being forwarded to their main process.

So for me endpoint, we're gonna validate the access_token and modify the information. Let's dig into this.

Let's create a new file called auth.guard.ts inside src/common/guards/ folder:



// src/common/guards/auth.guard.ts

import {
  CanActivate,
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { Request } from 'express';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private jwtService: JwtService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractTokenFromHeader(request);
    if (!token) {
      throw new UnauthorizedException();
    }
    try {
      const payload = await this.jwtService.verifyAsync(token, {
        secret: process.env.JWT_SECRET,
      });
      // 💡 We're assigning the payload to the request object here
      // so that we can access it in our route handlers
      request['user'] = payload;
    } catch {
      throw new UnauthorizedException();
    }
    return true;
  }

  private extractTokenFromHeader(request: Request): string | undefined {
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

In the code above, we created a class that implements CanActivate interface. Since we implement CanActivate interface, we need to define canActivate function that will be responsible for validating and updating the incoming request. There is also a function called extractTokenFromHeader for validating the access_token included through the header as a Bearer token.

Moving down, we'll see the jwt verification



const payload = await this.jwtService.verifyAsync(token, {
  secret: process.env.JWT_SECRET,
});

To make this work, we need to add a new variable to our .env file JWT_SECRET="super_secret_key"

We might need to update our app.module.ts as well by updating the jwt secret to use .env file secret: 'super_secret_key',

If all validation is passed, it will modify the incoming request information. In this case, request will receive user data from access_token request['user'] = payload;

After we created auth.guard. The next step is to register auth.guard to our root module (a.k.a app.module.ts). Open up app.module.ts and add the auth.guard to providers array:



providers: [
  AppService,
  {
    provide: APP_GUARD,
    useClass: AuthGuard,
  },
],

Great! Now let's continue to users.controller. Open src/modules/users/users.controller.ts file and move to me() function:



// This is before the changes
@Get('me')
me(): string {
  return 'Get my Profile!';
}

Let's modify that function by adding @Request decorator imported from @nestjs/common:



@Get('me')
me(@Request() req) {
  return req.user;
}

Now we're ready to test GET /users/me endpoint:

You might not be able to access other endpoints (including login) since we registered auth.guard globally. We'll fix this in the section below.

Is that all about GET /users/me endpoint? Nope, we can still make an adjustment. If you take a look at the function, req doesn't have an explicit type @Request() req. Since we're using typescript to write our code, will be better to add explicit type.

Let's do this!
We need to create an interface:
src/modules/users/interfaces/express-request-with-user.interface.ts



import { Request as ExpressRequest } from 'express';
import { UserPayload } from './users-login.interface';

export interface ExpressRequestWithUser extends ExpressRequest {
  user: UserPayload & { iat: number; exp: number };
}

Then we can use new interfaces to our me function



@Get('me')
me(@Request() req: ExpressRequestWithUser): UserPayload {
  return req.user;
}

Finally, we're done with GET /users/me endpoint!

Let's move on to the last part of this section. We already created auth.guard and set it as a global Guard. But now we have a problem. If we access the login or register endpoint, we'll get Unauthorized response



{
  "message": "Unauthorized",
  "statusCode": 401
}

As we will have some public endpoints (No need to pass access_token), this will be troublesome.

How do we fix that?

Now we must provide a mechanism for declaring routes as public. For this, we can create a custom decorator using the SetMetadata decorator factory function.

Create a new file src/common/decorators/public.decorator.ts:



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

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Update our users.controller by adding @Public() decorator in register and login endpoints:



...

@Public() // <--- Set register as public route
@Post('register')
async registerUser(@Body() createUserDto: CreateUserDto): Promise<User> {
  // call users service method to register new user
  return this.usersService.registerUser(createUserDto);
}

@Public() // <--- Set login as public route
@Post('login')
loginUser(@Body() loginUserDto: LoginUserDto): Promise<LoginResponse> {
  // call users service method to login user
  return this.usersService.loginUser(loginUserDto);
}

...

Lastly, open again auth.guard.ts and add some modify:



// src/common/guards/auth.guard.ts

export class AuthGuard implements CanActivate {
  constructor(
    private jwtService: JwtService,

    // 💡 See this line
    private reflector: Reflector,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    // 💡 See this line
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    // 💡 See this condition
    if (isPublic) {
      return true;
    }

    ...

  }
}

Now we're able to access login and register endpoints :)

The final step of this part.

After everything we've done here, let's finalize our users endpoints. So we want to prevent a user from updating or deleting another user's data, for example: in the access_token, it contains user id equal to 2. We don't want user id 2 able to change the name of user id 1.

To achieve that, let's create a new Guard called is-mine.guard



// src/modules/users/users.controller.ts

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';

@Injectable()
export class IsMineGuard implements CanActivate {
  constructor() {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();

    // 💡 We can access the user payload from the request object
    // because we assigned it in the AuthGuard
    return parseInt(request.params.id) === request.user.sub;
  }
}

We won't apply is-mine.guard globally like what we did in auth.guard, but we'll apply to routes manually.

Open up users.controller and add @UseGuards(IsMineGuard) decorator to our updateUser anddeleteUser



@Patch(':id')
  @UseGuards(IsMineGuard) // <--- 💡 Prevent user from updating other user's data
  async updateUser(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateUserDto: UpdateUsertDto,
  ): Promise<User> {
    // call users service method to update user
    return this.usersService.updateUser(+id, updateUserDto);
  }

  @Delete(':id')
  @UseGuards(IsMineGuard) // <--- 💡 Prevent user from deleting other user's data
  async deleteUser(@Param('id', ParseIntPipe) id: number): Promise<string> {
    // call users service method to delete user
    return this.usersService.deleteUser(+id);
  }

The full code of part 2 can be accessed here: https://github.com/alfism1/nestjs-api/tree/part-two

Moving on to part 3:
https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-3-3j34

Build Complete REST API Feature with Nest JS (Using Prisma and Postgresql) from Scratch - Beginner-friendly - PART 1

Alfi Samudro Mulyo — Wed, 25 Oct 2023 23:52:48 +0000

Scope of discussion:

What we want to build
Nest JS installation + new project initialization
Nest JS overview
Prisma configuration
Validation configuration
Create user endpoints (register, login, update, delete)
Password encryption

I have been looking for a great, nice, superb Node JS framework to build an API. After doing some exploration I found Nest JS which is super great. It's a Node JS framework with many built-in features written in Typescript. Check Nest JS documentation for more details Nest JS Doc.

In this article, I'm going to show how to create a REST API with these features:

CRUD (Create Read Update Delete) with Prisma,
Validation,
Authentication,
Route protection,
Handle multiple .env files,
Unit test,
e2e test,
Open API for documentation, etc.

Full code of the entire series can be accessed here: https://github.com/alfism1/nestjs-api

Okay, now let's get started.

First thing first, let's create a new Nest JS project called superb-api.

$ npm i -g @nestjs/cli
$ nest new superb-api

It will prompt a question to choose package manager (npm, yarn, or pnpm). Choose whichever you want.

Once the project initialization is completed, go to the project folder, open the code editor, and run it.

$ cd superb-api
$ npm run start

First App Run

By default, the Nest JS use 3000 as the default port.

If you want to change the port number, just open up src/main.ts and update the port number await app.listen(ANY_AVAILABLE_PORT_NUMBER);.

Nest JS Overview

Now, let's do a quick overview of the project folder structure.

Most of our codes will be written in the src folder. Let's take a look at the src folder. There are 5 files:

app.controller.ts: A basic controller with a single route.
app.controller.spec.ts: The unit tests for the controller.
app.module.ts: The root module of the application.
app.service.ts: A basic service with a single method.
main.ts: The entry file of the application which uses the core function NestFactory to create a Nest application instance.

Controller

Controllers are responsible for handling incoming requests and returning responses. As per the Nest JS rules, controller will be written in a class with @Controller() decorator. We can also add a string as the prefix inside the controller decorator @Controller('some-prefix') then the URL will be domain.com/some-prefix. Inside the controller class, there will be functions with HTTP methods decorator @GET(), @POST(), @PUT(), @PATCH(), @DELETE(). Similar to the controller, HTTP methods decorator can also receive a string, for example @GET('test'), and then the endpoint URL will be domain.com/some-prefix/test.

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

// Import the AppService class, which is defined in the app.service.ts file.
import { AppService } from './app.service';

// Controller decorator, which is used to define a basic route.
@Controller()
export class AppController {

  // Get decorator, which is a method decorator that defines a basic GET route.
  @Get()
  getHello(): string {
    // controller process goes here...
  }
}

For more details about the controller, check controller documentation.

Service/Provider

Services or Providers are responsible for handling the main process. We're gonna write all the endpoint logic here. As per the Nest JS rules, provider will be written in a class with @Injectable() decorator.

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

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

In the code above, we have getHello method which is responsible for returning a string 'Hello World!'. Then we can inject this provider into the controller

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  // inject the AppService into the AppController
  constructor(private readonly appService: AppService) {}

  @Get('test')
  getHello(): string {
    // call the AppService's getHello method
    return this.appService.getHello();
  }
}

For more details about the service or provider, check provider documentation.

Module

In NestJS, a module is a class annotated with the @Module() decorator. It is used to organize code into cohesive blocks of functionality. Modules have a few key responsibilities, such as defining providers (services, factories, repositories, etc.), controllers, and other related stuff. They also allow for defining imports and exports, which are used to manage dependencies between different parts of the application.

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

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

For more details about the service or provider, check module documentation.

Let's build our superb API

Prisma installation

We're gonna use Prisma as the database ORM. Prisma is a great library for working with databases. It supports PostgreSQL, MySQL, SQL Server, SQLite, MongoDB and CockroachDB.

First, let's install Prisma package in our project

$ npm install prisma --save-dev

Once prisma is installed, run the command below

$ npx prisma init

It will create schema.prisma file inside prisma folder

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

and .env file in the root folder

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

If you haven't installed PostgreSQL, just download it.

Make sure to set the correct DATABASE_URL in .env file.

Next, open up the schema.prisma and let's define the model schema

model User {
  id       Int     @id @default(autoincrement())
  email    String  @unique
  password String
  name     String?
  posts    Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean? @default(false)
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

Once the schema is created, sync the schema to the database by executing

npx prisma migrate dev --name init

and check the database. It will create these tables:

Install prisma client

npm install @prisma/client

Note that during installation, Prisma automatically invokes the prisma generate command for you. In the future, you need to run this command after every change to your Prisma models to update your generated Prisma Client.

The prisma generate command reads your Prisma schema and updates the generated Prisma Client library inside node_modules/@prisma/client

Next, let's create a new file called prisma.service.ts inside src/core/services/ directory:

// src/core/services/prisma.service.ts

import { Injectable, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect();
  }
  async onModuleDestroy() {
    await this.$disconnect();
  }
}

For the last configuration of Prisma, let's register PrismaService as a global module so it can be used on any other modules. Create a new file called core.module.ts inside src/core/

// src/core/core.module.ts

import { Global, Module } from '@nestjs/common';
import { PrismaService } from './services/prisma.service';

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class CoreModule {}

then update our app.module.ts by adding CoreModule:

// src/app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UsersModule } from './modules/users/users.module';
import { CoreModule } from './core/core.module';

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

Great! Now we're ready to interact with the database :)

Validation config

Nest JS can do request body and query validation very well (more details check here).
First, install the packages:

$ npm i --save class-validator class-transformer
$ npm install @nestjs/mapped-types

and update our main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Global pipe that will be applied to all routes
  // This will validate the request body against the DTO
  app.useGlobalPipes(new ValidationPipe());

  await app.listen(3000);
}
bootstrap();

We added app.useGlobalPipes(new ValidationPipe()); in main.ts to make it globally applied.

Create users endpoints

Let's move on to the endpoint creation.
In the src folder, create a new folder called modules/users.

Inside modules/users, we'll create endpoints that handle any logic related to user model such as; create user, update user, and delete user.

Before diving into the code, let's install some packages:

bcrypt
We'll encrypt the user's password during the user creation.

$ npm i bcrypt
$ npm install --save @types/bcrypt

Now let's create a new folder src/modules/users/dtos and create these files:

create-user.dto.ts Validation for user creation/registration

import { IsEmail, IsNotEmpty } from 'class-validator';

export class CreateUserDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;

  @IsNotEmpty()
  password: string;

  @IsNotEmpty()
  name: string;
}

update-user.dto.ts Validation for user update

import { PartialType } from '@nestjs/mapped-types';
import { CreateUserDto } from './create-user.dto';

export class UpdateUsertDto extends PartialType(CreateUserDto) {}

import { IsEmail, IsNotEmpty } from 'class-validator';

export class LoginUserDto {
  @IsNotEmpty()
  @IsEmail()
  email: string;

  @IsNotEmpty()
  password: string;
}

Let's start with creating a new controller boilerplate called users.controller.ts

import {
  Body,
  Controller,
  Delete,
  Get,
  Param,
  ParseIntPipe,
  Patch,
  Post,
} from '@nestjs/common';
import { CreateUserDto } from './dtos/create-user.dto';
import { UpdateUsertDto } from './dtos/update-user.dto';
import { LoginUserDto } from './dtos/login-user.dto';

@Controller('users')
export class UsersController {
  @Post('register')
  registerUser(@Body() createUserDto: CreateUserDto): string {
    console.log(createUserDto);
    return 'Post User!';
  }

  @Post('login')
  loginUser(@Body() loginUserDto: LoginUserDto): string {
    console.log(loginUserDto);
    return 'Login User!';
  }

  @Get('me')
  me(): string {
    return 'Get my Profile!';
  }

  @Patch(':id')
  updateUser(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateUserDto: UpdateUsertDto,
  ): string {
    console.log(updateUserDto);
    return `Update User ${id}!`;
  }

  @Delete(':id')
  deleteUser(@Param('id', ParseIntPipe) id: number): string {
    return `Delete User ${id}!`;
  }
}

users.controller.ts has five endpoints:

POST /users/register for user registration process,
POST /users/login for user login process,
GET /users/me to Get the user's profile,
PATCH /users/:id for user updates,
DELETE /users/:id for user delete.

Each endpoint above already implemented validation as well according to the DTO, for example:

Registration input validation (DTO create-user.dto)
Login input validation (DTO login-user.dto)
Update user wrong :id (should be numeric)

Now let's jump to the user service. In the service, we'll create functions to interact with the database via Prisma and they'll represent each endpoint mentioned above.

Here are the users.service boilerplate:

import { ConflictException, HttpException, Injectable } from '@nestjs/common';
import { User } from '@prisma/client';
import { PrismaService } from 'src/core/services/prisma.service';
import { CreateUserDto } from './dtos/create-user.dto';
import { hash } from 'bcrypt';

@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  // async registerUser

  // async loginUser

  // async updateUser

  // async deleteUser
}

Let's start with the register function first:

async registerUser(createUserDto: CreateUserDto): Promise<User> {
  try {
    // create new user using prisma client
    const newUser = await this.prisma.user.create({
      data: {
        email: createUserDto.email,
        password: await hash(createUserDto.password, 10), // hash user's password
        name: createUserDto.name,
      },
    });

    // remove password from response
    delete newUser.password;

    return newUser;
  } catch (error) {
    // check if email already registered and throw error
    if (error.code === 'P2002') {
      throw new ConflictException('Email already registered');
    }

    // throw error if any
    throw new HttpException(error, 500);
  }
}

registerUser will be responsible for handling register logic. We can see that now we interact with database using prisma this.prisma.user.create. We also encrypt the password to make our API secure hash(createUserDto.password, 10) and remove it from the response API delete newUser.password.

We also handle the error using throw new ConflictException if there is a duplicate email or any other error throw new HttpException.

Now let's move on to login function:
Login response will return an object with a single property called access_token (interface LoginResponse) which contains some user data (interface UserPaylod) generated by using jwt, so we need to install @nestjs/jwt first:

$ npm install --save @nestjs/jwt

Once @nestjs/jwt is installed, update UsersService's constructor by adding private jwtService: JwtService,

constructor(
  private prisma: PrismaService,
  private jwtService: JwtService,
) {}

Last but not least, update our app.module.ts by adding jwt module as a global:

// src/app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UsersModule } from './modules/users/users.module';
import { CoreModule } from './core/core.module';
import { JwtModule } from '@nestjs/jwt';

@Module({
  imports: [
    UsersModule,
    CoreModule,
    // add jwt module
    JwtModule.register({
      global: true,
      secret: 'super_secret_key',
      signOptions: { expiresIn: '12h' },
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Please take note that the secret and expiresIn should be stored in a safe place like .env file. We'll cover this in the next section.

Once jwt configuration is completed, let's create a new interface file called src/modules/users/interfaces/users-login.interface.ts:

export interface UserPayload {
  sub: number;
  name: string;
  email: string;
}

export interface LoginResponse {
  access_token: string;
}

Here is the loginUser code:

async loginUser(loginUserDto: LoginUserDto): Promise<LoginResponse> {
    try {
      // find user by email
    const user = await this.prisma.user.findUnique({
      where: { email: loginUserDto.email },
    });

    // check if user exists
    if (!user) {
      throw new NotFoundException('User not found');
    }

    // check if password is correct by comparing it with the hashed password in the database
    if (!(await compare(loginUserDto.password, user.password))) {
      throw new UnauthorizedException('Invalid credentials');
    }

    const payload: UserPayload = {
      // create payload for JWT
      sub: user.id, // sub is short for subject. It is the user id
      email: user.email,
      name: user.name,
    };

    return {
      // return access token
      access_token: await this.jwtService.signAsync(payload),
    };
  } catch (error) {
    // throw error if any
    throw new HttpException(error, 500);
  }
}

So far we already created two functions, registerUser and loginUser. Now let's continue on updateUser and deleteUser.

Here is the updateUser function:

async updateUser(id: number, updateUserDto: UpdateUsertDto): Promise<User> {
  try {
    // find user by id. If not found, throw error
    await this.prisma.user.findUniqueOrThrow({
      where: { id },
    });

    // update user using prisma client
    const updatedUser = await this.prisma.user.update({
      where: { id },
      data: {
        ...updateUserDto,
        // if password is provided, hash it
        ...(updateUserDto.password && {
          password: await hash(updateUserDto.password, 10),
        }),
      },
    });

    // remove password from response
    delete updatedUser.password;

    return updatedUser;
  } catch (error) {
    // check if user not found and throw error
    if (error.code === 'P2025') {
      throw new NotFoundException(`User with id ${id} not found`);
    }

    // check if email already registered and throw error
    if (error.code === 'P2002') {
      throw new ConflictException('Email already registered');
    }

    // throw error if any
    throw new HttpException(error, 500);
  }
}

and last function deleteUser:

async deleteUser(id: number): Promise<string> {
  try {
    // find user by id. If not found, throw error
    const user = await this.prisma.user.findUniqueOrThrow({
      where: { id },
    });

    // delete user using prisma client
    await this.prisma.user.delete({
      where: { id },
    });

    return `User with id ${user.id} deleted`;
  } catch (error) {
    // check if user not found and throw error
    if (error.code === 'P2025') {
      throw new NotFoundException(`User with id ${id} not found`);
    }

    // throw error if any
    throw new HttpException(error, 500);
  }
}

Now the UsersService is completed and here is the final full code:

// src/modules/users/users.service.ts

import {
  ConflictException,
  HttpException,
  Injectable,
  NotFoundException,
  UnauthorizedException,
} from '@nestjs/common';
import { User } from '@prisma/client';
import { PrismaService } from 'src/core/services/prisma.service';
import { CreateUserDto } from './dtos/create-user.dto';
import { compare, hash } from 'bcrypt';
import { LoginUserDto } from './dtos/login-user.dto';
import { JwtService } from '@nestjs/jwt';
import { LoginResponse, UserPayload } from './interfaces/users-login.interface';
import { UpdateUsertDto } from './dtos/update-user.dto';

@Injectable()
export class UsersService {
  constructor(
    private prisma: PrismaService,
    private jwtService: JwtService,
  ) {}

  async registerUser(createUserDto: CreateUserDto): Promise<User> {
    try {
      // create new user using prisma client
      const newUser = await this.prisma.user.create({
        data: {
          email: createUserDto.email,
          password: await hash(createUserDto.password, 10), // hash user's password
          name: createUserDto.name,
        },
      });

      // remove password from response
      delete newUser.password;

      return newUser;
    } catch (error) {
      // check if email already registered and throw error
      if (error.code === 'P2002') {
        throw new ConflictException('Email already registered');
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async loginUser(loginUserDto: LoginUserDto): Promise<LoginResponse> {
    try {
      // find user by email
      const user = await this.prisma.user.findUnique({
        where: { email: loginUserDto.email },
      });

      // check if user exists
      if (!user) {
        throw new NotFoundException('User not found');
      }

      // check if password is correct by comparing it with the hashed password in the database
      if (!(await compare(loginUserDto.password, user.password))) {
        throw new UnauthorizedException('Invalid credentials');
      }

      const payload: UserPayload = {
        // create payload for JWT
        sub: user.id, // sub is short for subject. It is the user id
        email: user.email,
        name: user.name,
      };

      return {
        // return access token
        access_token: await this.jwtService.signAsync(payload),
      };
    } catch (error) {
      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async updateUser(id: number, updateUserDto: UpdateUsertDto): Promise<User> {
    try {
      // find user by id. If not found, throw error
      await this.prisma.user.findUniqueOrThrow({
        where: { id },
      });

      // update user using prisma client
      const updatedUser = await this.prisma.user.update({
        where: { id },
        data: {
          ...updateUserDto,
          // if password is provided, hash it
          ...(updateUserDto.password && {
            password: await hash(updateUserDto.password, 10),
          }),
        },
      });

      // remove password from response
      delete updatedUser.password;

      return updatedUser;
    } catch (error) {
      // check if user not found and throw error
      if (error.code === 'P2025') {
        throw new NotFoundException(`User with id ${id} not found`);
      }

      // check if email already registered and throw error
      if (error.code === 'P2002') {
        throw new ConflictException('Email already registered');
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }

  async deleteUser(id: number): Promise<string> {
    try {
      // find user by id. If not found, throw error
      const user = await this.prisma.user.findUniqueOrThrow({
        where: { id },
      });

      // delete user using prisma client
      await this.prisma.user.delete({
        where: { id },
      });

      return `User with id ${user.id} deleted`;
    } catch (error) {
      // check if user not found and throw error
      if (error.code === 'P2025') {
        throw new NotFoundException(`User with id ${id} not found`);
      }

      // throw error if any
      throw new HttpException(error, 500);
    }
  }
}

The next step is we need to update our UsersController to interact with usersService and here is the full code:

// src/modules/users/users.controller.ts

import {
  Body,
  Controller,
  Delete,
  Get,
  Param,
  ParseIntPipe,
  Patch,
  Post,
} from '@nestjs/common';
import { CreateUserDto } from './dtos/create-user.dto';
import { UpdateUsertDto } from './dtos/update-user.dto';
import { LoginUserDto } from './dtos/login-user.dto';
import { UsersService } from './users.service';
import { User } from '@prisma/client';
import { LoginResponse } from './interfaces/users-login.interface';

@Controller('users')
export class UsersController {
  // inject users service
  constructor(private readonly usersService: UsersService) {}

  @Post('register')
  async registerUser(@Body() createUserDto: CreateUserDto): Promise<User> {
    // call users service method to register new user
    return this.usersService.registerUser(createUserDto);
  }

  @Post('login')
  loginUser(@Body() loginUserDto: LoginUserDto): Promise<LoginResponse> {
    // call users service method to login user
    return this.usersService.loginUser(loginUserDto);
  }

  @Get('me')
  me(): string {
    return 'Get my Profile!';
  }

  @Patch(':id')
  async updateUser(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateUserDto: UpdateUsertDto,
  ): Promise<User> {
    // call users service method to update user
    return this.usersService.updateUser(+id, updateUserDto);
  }

  @Delete(':id')
  async deleteUser(@Param('id', ParseIntPipe) id: number): Promise<string> {
    // call users service method to delete user
    return this.usersService.deleteUser(+id);
  }
}

We haven't updated the me endpoint yet. Will do it later

We're almost done. We need to register UsersController and UsersService to UsersModule:

// src/modules/users/users.module.ts

import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  imports: [],
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

Finally, we've done with users register, login, update, and delete. Now we can test these endpoints:

POST /users/register,
POST /users/login,
PATCH /users/:id,
DELETE /users/:id

We've been doing great so far :)
The full code of part 1 can be accessed here:
https://github.com/alfism1/nestjs-api/tree/part-one.

Moving on to part 2:
https://dev.to/alfism1/build-complete-rest-api-feature-with-nest-js-using-prisma-and-postgresql-from-scratch-beginner-friendly-part-2-1g25