Documentation 🤟

This page will guide you through the different steps to start with TeanJS

Description ✍️

TeanJS is a starter that provides you all the keys to be able to start writing your code as quickly as possible 🚀

Built with 🔨

• NestJS 6 - The server framework used

• ng-universal - Nestjs module to work with Angular universal (SSR)

• Angular 8 - The client framework used

• TypeORM (in association with @nestjs-typeorm) - Database management

• Passport (in association with @nestjs-passport and @nestjs-jwt) - Authentication management

• Jest - A test framework for the client/server units tests

• Jasmine - A test framework for client side E2E

Prerequisites 🤖

To be able to start the project right a way, the only thing you will have to do is update the server environments of your database in the file ./server/environments/local/database.ts.

Then, your next action will be to run the following command npm run migration:run. This will result in the creation of your first users table base on the migration file located in the migrations directory ./server/migrations.

Features

Often, when you start a new project, you will have a look on the existing start. But the major problem is that there is too many features that you don't need or not enough. So you have to deal with something you don't really want.

That's why, the amount of features in that starter stay limited (to avoid forcing you to use something you don't want) but enough to be ready to code.

Server

For start, let see the modules available

Users

The Users module provide you some basic features such as

• Create a new user

• Find a user by Id

UserController

To achieve that, you have in your possession a users.service.ts file that encapsulate the logic to manage the users.

You will find also a user.entity.ts that describe your users and along it, a custom user.repository.ts (will see that later) and a user.subscriber-entity.ts that separate the entity behavior logic from the entity itself. The subscriber as one purpose which is to hash/Salt the user password during the creation process.

Authentication

The Authentication module provide you a uniq feature

• Login into your api

AuthController

It's a simple module which enforce the login through a email/password credentials which will be validated by the localStrategy. Then, after the credentials validation, a token will be set in a cookie a return to the client.

To enforce the security, the JwtStrategy will protect all the routes that needs to be protected. So, the auth.service.ts will have only two goal, validateUser and login which create a token and return it.

Beside these modules, the common directory comes with some useful features

Decorators

EntityNotFoundExceptionHandler

These decorator only wrap a method that use TypeORM to make some action. If that action result in an error of type EntityNotFound it will catch it and redirect that error as an EntityNotFoundException which will be handle by a custom filter. It's an example that show how to handle error and unified them to get a common error output.

EntityNotFoundExceptionHandler example

LoggedInUser

When a user has been logged in your api, you will have it ready on your Request object. This decorator is made to be able to grab it into your controller method as an argument.

LoggedInUser example

It's the perfect example of usage of customDecorator in NestJS.

Exceptions

As describe in the decorator tab, we have a EntityNotFoundExceptionHandler which handle and throw a EntityNotFoundException. The purpose of that exception is to be filtered in a custom filter (see next tab).

Custom exception

Filters

BadRequestExceptionFilter

These filter is in charge to handle badRequestException and unified the output as well as the log

BadRequestionExceptionFilter

EntityNotFoundExceptionFilter

This filter has the same role as the previous one, but for the EntityNotFoundException. of course the output is unified and is the same as the previous filter.

EntityNotFoundExceptionFilter

TypeORM

This common utilities will bring two features.

First it will add the SoftDeletable concept to the table. To achieve that, you will be able to extends the SoftDeletableEntity that will add the deletedAt column to your entity.

SoftDeletableEntity

But since it's not a feature of TypeORM, the user.respository.ts (located in the users module) extends the TransactionalSoftDeletableRepository which extends it self the TransactionalRepository (that we will see later).

The only purpose of theTransactionalSoftDeletableRepository is to bring two more methods which are

• softDelete

• softRemove

These methods act the same as delete and remove except that they will update the entities by updating the deletedAt column of our softDeletableEntity. Also, the usual method to find an entity will take in count by default, to only find the entity non deleted. To include the deleted entities, you can pass the force parameter in the options.

Find deleted entities

But why a TransactionalRepository ?

Because when it comes to use transaction, you often have to pass the transaction to another method else where. Except that it's a manager in typeORM. In other words, theTransactionalRepository only override the usual method of typeORM but let you be able to pass or not the EntityManager in charge of your transaction. That way, you will not be afraid anymore to use transaction and pass them through your layers.

Environments ⚙️

Server

All the environments for the server are stored in the ./server/environments. In that directory there is the root files used in the application (e. g. to setup the database connection) and the local directory where you will be able to set the default values of all the environment configurations. That way, you can have a generic configuration file that will use the env variables if possible or the default values provided by the files situated in the local directory.

In the .gitignore file, there is the following statement: # /server/environments/local/

Please remove the # to avoid pushing your password and other sensitive environment configurations anywhere. You must never push your ./server/environments/local directory at any point.

Scripts 🛰️

Here is a non exhaustive list of the main commands available:

Scripts	Descriptions
npm run lint	To lint and format code (used in pre-commit hook as well)
npm run test:unit:server	Run the server side unit tests
npm run test:e2e:server	Run the server side e2e tests
npm run test:server	Run all the server side tests
npm run test:unit:client	Run the client side unit tests
npm run test:e2e:client	Run the client side unit tests
npm run test:client	Run all the client side tests
npm run migration:create {migration name}	Create a new migration file (./server/migrations)
npm run migration:run	Apply migrations
npm run migration:revert	Revert migrations
npm run build:client	Build client side
npm run build:server	Build server side
npm run build:ssr	Build client and server
npm run start:client	Start client only
npm run start:prod	Start all the project using SSR
npm run start:dev	Start SSR using ng-universal LiveReloadCompiler