roman-sachenko/boilerplate-express-entity-based

ExpressJS bases server. Includes internal architecture, basic services and functionality such as authentication service, database services, validation, admin dashboard functionality etc.

Express-Lemon: Back-End Boilerplate

1. Description

• Ideology
• Middleware Entities
• Services
• Commands

2. Installation

• Requirements
• Installation Steps
• Running the package

Description

Initial API Architecture. Contains a basic and must-have set of modules, services and configurations.

Ideology

Use Express Middlewares in order to split functionality and have logically separated parts. Each router/endpoint may have a chain of middlewares to validate data, load data from data sources, map data, check permissions and perform the main business logic.

Each Middleware function should have the same name through the whole chain set.

Example: If a new request of user creation process passes multiple middleware functions, all of them should have the same name (createOne(req, res, next))

*Exception: unrelated 'helper' middlewares

Example:

appRoute.get('/:userId',
  authMiddleware.isAuthenticated,
  acl.getOne,
  validator.getOne,
  loader.getOne,
  controller.getOne,
);

Middleware Entities

./app/middlewares/

Chain items to perform own specific functionality.

Access Control (accessControl)

Checks if the current request may reach a business logic. This layer may check if a logged in user has permissions to perform this request.

Example:

async getOne(req, res, next) {
    if (mainAcl.isAdmin(req.user)) {
      return next();
    }

    const userIdRequested   = req.params.userId;
    const userIdCurrent     = req.user._id.toString();

    if (userIdRequested === userIdCurrent) {
      return next();
    }

    return next(new Forbidden());
},

Data Mappers (dataMappers)

Maps Outgoing/Incoming data for further processing by another function.

Example:

updateOne(req, res, next) {
    delete req.body.password;
    delete req.body.confirm_password;
    return next();
},

Data Validators (dataValidators)

Validates incoming data according to installed rules to prevent invalid data from handling.

Example:

deleteOne(req, res, next) {
    req.assert('userId', 'Valid user id should be provided').notEmpty().isMongoId();
    mainValidator.handleValidationResult(mainValidator.validateErrorsSync(req), res, next);
},

Entity Loaders (entityLoaders)

Loads/Gets required by business logic entities/objects from available data sources. The system may retrieve users or related entities from a database or process a data.

Stores and passes loaded entities in a special object inside the req (request) object. The Entity Loader Service should be used to sed all of the entities and pass within the request object.

Example:

async getOne(req, res, next) {
    try {
      const userFound = await UserService.findOne({ query: { _id: req.params.userId }, options: { lean: true } });
      if (!mainHelper.isObjectValid(userFound)) {
        throw new NotFound('user not found');
      }

      MainLoader.setEntities(req, { user: userFound });
      return next();

    } catch (err) {
      return next(err);
    }
},

Services

./app/services/

Services perform single-minded focus functionality to be invoked inside the application for handling business logic.

• Authentication Service (access/refresh token flow)
• Crypto Service
• Database Service
• Email Service
• Entity Loader Service
• Log Service
• Response Service
• User Service

Commands

./commands

• Admin User creation script

Installation

Requirements

Node

Visit https://nodejs.org for installation details.

npm

Node Package Manager, should come bundled with node.

MongoDB

Install MongoDB https://docs.mongodb.com/manual/installation/

Installation Steps

Clone the package

1. Create a folder with the chosen name
2. Run $ git clone <package url> .

install dependencies

1. Go to the package root folder
2. Run $ npm install

App Settings

1. Create config/env/env.local file and copy data from config/env/env.local_example
2. Update settings according to your needs and environment specifications

Test Environment Settings

1. Create config/env/.env.test file and copy data from config/env/.env.test_example
2. Update settings according to your needs and environment specifications

Running the package

$ npm run start:[environment]

Example: $ npm run start:local

boilerplate-express-entity-based's Issues

Middlewares and controller methods convert to ES6 object declaration

App Init: Remove Model require from the main app file

System Logs - fix format

Update logger:

• add timestamps for all the logs
• log only uncaught exceptions and errors 500

Initiate Test Env

Auth Controller: Sign Up - return response before throwing exception

Main Service - get config function

return full config instead mail service config

Question - how to handle entity relationships?

Say, I have User and Task models. Task has only one User but User can have many Tasks. Following the example here, I should create TaskService. But how to manage relationships? Let's say, I want to add a new Task to the existing User. Should I inject UserService in the TaskService? How to handle this situation?

Common: Add Releases

To view changes

Resolve deep nesting in Controllers (entity folder: remove)

Remove deep nesting in middlewares (Remove: entities folder)

Auth: Add Change password

Tests: Write tests to cover basic functionality

Make app.js startable

It should be able to run the application without a clustered file.

Auth: Add Multiple Devices with tokens support

Auth: add refresh token

Add Exact fields validation

Update current incoming request validation to check an exact list of fields/. We may switch to JOI validator:
https://github.com/hapijs/joi

Config flag to enable/disable logs

Create a flag somewhere in a config file to be able to enable or disable logging.

Auth: Add Sign Out

Config flag to control amount of NodeJS instances

Control Clustered instances in the server.js file using config file flag.

Resolve deep nesting in Services

Too deep nesting in services should be resolved. Remove parent 'entity' folder

Auth Controller: Sign Up - remove parameters passing into userService.create function

Add eslint

User Delete - switch to soft delete

Leave Users in DB, but mark as delete for Undo process.

Main Service: Set Max Listeners - fix

Currently, max listeners value is set to 0, so it means an infinite amount of listeners. Fix this and set a suitable value.

Add Social Network Authentication Suppor

Delete Session Declaration

We don't use session - remove session declaration from the app.js file.

Remove console.log()'s

.env file reader

Install module to read .env file

Add Git hooks handler

User Role Update - should be allowed for Admin only

Fix User Update functionality to it's possible to update role by Admin only.

• we may change validator to check for extra fields and reject them
• we may write mapped to remove a role from req.body

DB Service: Create DB Wrapper to handle multiple ORM/ODM

User Update/Delete not formatted response

Server responses with invalid response format.

Create one single PM2 start up file.

At this moment we have multiple startup files in order to suit multiple environments. Since we've changed the config file, we need just one. Fix the ./bin folder and leave just one startup file for PM2.

Remove --harmony key from start up script

Resolve deep nesting in Routes (entity folder: remove)

Users::Get All - remove 'not found' checker in Entity Loader

Update boilerplate documentation

Update boilerplate documentation:

• provide more configuration info
• describe rule elements (entityLoaders, dataMappers, accessControl, dataValidators)
• provide with 'commands' infromation
• provide steps of admin creation process

Update User - duplicate Email validation

The system responses with error, but from DB. We have to validate this in the middle of the process. Update validator or check it somewhere else.

Add API Documentation

Add API documentation to describe routes. Swagger or similar.

Security: add strong password validation

Resolve deep nesting in Models (entity folder: remove)