NodeJS Express Base App

Summary

Welcome to NodeJS Express Base App project, thanks for reading in advance!

This project is a proposal for the base structure of an express application, it has integrated the (in my opinion and experience) mandatory implementations that each express project must have, from documentation to test suite it already is a boiler plate for you to start building your own services of any kind.

Table of Content:

• NodeJS Express Base App
  • Summary
  • Table of Content:
  • Project Description:
  • Project Structure
  • Proposed Standards
    • Logging
  • Error Handling
    • Tests
    • Responses
    • Code Documentation
    • API Documentation
• • Execution
    • Environment Variables
    • Pre-requisites
    • Installing
    • Scripts
  • Contributing
  • License
  • Credits

Project Description:

The project is a proposal of the base structure for an express RESTful API for all the possible adaptations, it has the following integrations to help the developer to start the developing journey with the less possible technical debt covering all the requirements for a high quality development.

| Integration | Description | Web Page | | ------------------ | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Express | Fundamental web framework which all this project is based on | Express | | TypeScript | Build on Javascript engine to type the development of JS making developments more reliable and high quality | TypeScript | | Mocha | Testing frameworks that integrates a whole test suite for us to develop our unit and integration tests | Mocha | | Isntanbul/nyc | Test tool that integrates with Mocha to provide us metrics about our unit/integration tests KPIs (CodeCoverage) | Instanbul | | Pino | Application logs framework with support for many configurations and custom logs | Pino | | TypeDoc | Documentation tool that converts Typescript TSDoc comments into HTML Documentation for your project | TypeDoc | | SwaggerUIExpress | Swagger Documentation library that helps express to serve a defined swagger.json file into an static file | SwaggerUIExpress |

There are more libraries implemented in this base project but since they don't cover standard quality points for an application there will be covered when needed along the readme.

To integrate the table information about the implemented frameworks and libraries, this project base app holds an Express RESTful API build in TypeScript, documented with TSDoc standards using the TypeDoc engine and SwaggerUI for the endpoints , it generates standard logs defined with Pino, the test suite runs over Mocha with Chai assertions and mocks generated with Sinon, nyc complements with mocha to generate coverage reports.

Project Structure

The folder structure of this app is explained below, not tracked folders are generated during the execution of the application.

| Name | Description | Git Tracked | Reason | | ----------------- | ------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------ | | .nyc_output | Output of the execution of coverage report result | No | Generated when coverage script is executed | | coverage | Result files of coverage report run of nyc | No | Generated when coverage script is executed | | dist | Contains the distributable (or output) from your TypeScript build. | No | Generated when app builds | | documentation | Contains the documentation files generated by TypeDoc | No | Generated when doc command is executed | | node_modules | Contains all npm dependencies | No | Generated when app installs | | public | Contains the definition of the swagger documentation file | Yes | Required | | src | Contains source code that will be compiled to the dist dir | Yes | Required | | src/controllers | Controllers define functions to serve various express routes then used as handlers for Endpoints definitions | Yes | Required | | src/enums | Contains the TypeScript enums defined to be used in application modules | Yes | Required | | src/handlers | Contains handlers for specific functionalities common for many modules | Yes | Required | | src/helpers | Contains helpers with simpler functionalities to abstract the process from the module that uses it | Yes | Required | | src/interfaces | Contains the TypeScript interfaces defined to be used in application modules | Yes | Required | | src/services | Contains the services processes logic itselfs | Yes | Required | | src/index.ts | Entry point to express app, here is where initialization is done | Yes | Required | | test | Contains the definition of unit and integration tests for the source code of the application | Yes | Required | | .env.example | Example of .env file, should be renamed to .env after repository cloning | Yes | Required | | .gitignore | Contains the rules of git to ignore some unecessary files and folders | Yes | Required | | package.json | Contains the definition of the npm package with its dependencies, configurations and scripts | Yes | Required | | readme.md | This file itself | Yes | Required | | tsconfig.json | Contains the configuration of the TypeScript compiler to correctly work with all the project dependencies | Yes | Required |

Proposed Standards

Logging

For the application logs we use Pino library, it provides a well structured standard for logs and personalization over the different log levels. The standard is over the INCOMING_REQUEST, OUTCOMING_REQUEST and FAILED_HTTP_REQUEST logs that are implemented as middlewares in the application for every request.

Every incoming request will trigger the INCOMING_REQUEST logger defined in src/handlers/LogsHandlers.ts, if the response is success then OUTCOMING_REQUEST will log the response, if there is any error then FAILED_HTTP_REQUEST will log the error given with the following error handling standard

For custom logs for any need the suggestion is to use the factory function for Pino Logger createLogger defined in src/handlers/LogsHandlers.ts to generate the logger, the reason is because we want the loggers to have a common base structure, you can configure one defined by you in this function, one example is the logger defined in src/index.ts that we use to generate logs of the app initialization process.

Error Handling

For the error handling the proposal is to use the defined in src/handlers/CustomError.ts CustomError class as the unique error format for the application and to sorround every service own process in try/catch clauses that in case of any error first validate if the error is already a CustomError, if it is then just throw the CustomError exception until controllers that pass the Cu