@tne/express-app

A library that encapsulates the Web Application framework Express.js and other common middleware tools such as compression, cors, morgan, serve-favicon and also the joi the famous javascript schema validation tool, in order to provide you a base to load easily the resources and services for your web application.

Menu

Installation

Creating a web service with @tne/express-app

ExpressApplication

• construct()
• destruct()
• getInstance()
• getExpressApp()

Foundation Libraries

• Express
• joi

Decorators

• Config
• FinalClass
• Prefix
• Endpoint
• ExpressRouter

Interfaces

• IAppSettings
• ILoggerSettings
• IEndpointConfig

Back to Menu

Installation

You can install through the node package managers:

NPM

$ npm install --save @tne/express-app

Yarn

$ yarn add @tne/express-app

Back to Menu

ExpressApplication

This Object is an interface that provides us with the methods that will allow you to create, destroy or obtain the instance of our web application.

Methods

• construct()
• destruct()
• getInstance()
• getExpressApp()

Example usage

import { ExpressApplication } from '@tne/express-app';
// code here

Back to Menu

construct()

This method will build a singleton instance of class ExpressCoreApplication, start the http service and return a reference to the built instance.

The method has two overloads:

• string
• IAppSettings

String Example

file: src/index.ts

import { ExpressApplication } from '@tne/express-app';

ExpressApplication.construct(__dirname);

IAppSettings Example

file: src/index.ts

import { ExpressApplication, IAppSettings } from '@tne/express-app';

const config: IAppSettings = {
	appPath: __dirname,
	// ... other IAppSettings here
};

ExpressApplication.construct(config);

Back to Menu

destruct()

This method will stop the http service created by Express.js and destroy the singleton instance of the ExpressCoreApplication class (if they existed).

Example

import { ExpressApplication } from '@tne/express-app';

ExpressApplication.destruct();

Back to Menu

getInstance()

This method returns a reference to the singleton instance of class ExpressCoreApplication, if it exists, otherwise it will return null.

Example

import { ExpressApplication } from '@tne/express-app';

const app = ExpressApplication.getInstance();

Back to Menu

getExpressApp()

This method returns a reference to the app property (which is the Express.js application) of the singleton instance of the ExpressCoreApplication class, if it exists, otherwise it will return null.

Example

import { ExpressApplication } from '@tne/express-app';

const expressApp = ExpressApplication.getExpressApp();

Back to Menu

Express

There is not much to add, just the Express.js library on which this library works, free to use it as you wish.

For example, you can use this export to create a mock Server for your unit tests.

Example

import { express } from '@tne/express-app';

const app = express();

Back to Menu

joi

just the joi to create amazing schema-based validations.

Example

import { joi } from '@tne/express-app';

const pager = joi.object().keys({
	page: joi.number().integer().positive().min(1).required(),
	per_page: joi.number().integer().positive().min(1).required(),
});

const { error, value } = joi.validate({ page: 1, per_page: 50 }, pager);
// result.error === null -> valid

Back to Menu

Decorators

This library provides you with some decorators that will help you simplify or extend the functionalities of your web application.

Back to Menu

@Config

The class decorator @config will freeze the decorating class as well as its prototype, so that it can not be modified externally.

Example

import { Config } from '@tne/express-app';

@Config
export class ExampleClass {
	// class that I do not want to modify externally
}

Back to Menu

@FinalClass

This "class decorator" transforms the class into a "Final class", so it can not be extended by any other class.

Example

import { FinalClass } from '@tne/express-app';

@FinalClass
export class SomeFinalClass {
	// class that I do not want to extend
}

export class OtherClass extends SomeFinalClass {
	// code here!
}

The above code will throw an error when loading the "OtherClass" class.

Back to Menu

@Prefix

This "property decorator" prefixes the value of the property of the string or property provided in the argument to the decorated property.

Parameters

| Param | Type | Required? | Description | |-|-|-|-| | propToPrefix | string | true | The property that will be prefixed to the property that is being decorated. |

Constraints

It only works if all the properties of the decorated class are static.

Example

import { Config, Prefix } from '@tne/express-app';

@Config
export class Routes {
	static baseUrl = '/';
	static apiUrl = '/api/v1/';

	@Prefix('apiUrl')
	static users = '/users/';

	@Prefix('apiUrl')
	static user = '/users/:id/';

	@Prefix('apiUrl')
	static users = '/users/';

	@Prefix('baseUrl')
	static view_users = '/users/:id/';

	@Prefix('baseUrl')
	static view_user = '/users/:id/';
}

Example output

import { Routes } from 'config/route';

console.log(Routes.user) // -> /api/v1/users/:id/;
console.log(Routes.view_user) // -> /users/:id/;

Back to Menu

@Endpoint

This "method decorator" is used in conjunction with @ExpressRouter to transform the methods of a class into usable Route handler of Express.js.

Your must provide an object that implements the IEndpointConfig Interface as argument.

Example

import { Endpoint, ExpressRouter } from '@tne/express-app';
import { middlewareFunc } from 'some/path';

@ExpressRouter
export default class ExampleRouter {
	@Endpoint({
		method: 'GET'
		path: '/users'
	})
	getUsers(req,res){
		// GET Route handler code here!
	}

	@Endpoint({
		method: 'POST'
		path: '/users'
	})
	postUsers(req,res){
		// POST Route handler code here!
	}

	@Endpoint({
		method: 'PUT'
		path: '/users/:id',
		middleware: [middlewareFunc]
	})
	putUsers(req,res){
		// PUT Route handler code here!
	}
}

Back to Menu

@ExpressRouter

This "class decorator" is used in conjunction with @Endpoint to transform the methods of a class into usable Route handlers for 'Express.js'.

Example

import { Endpoint, ExpressRouter } from '@tne/express-app';
import { middlewareFunc } from 'some/path';

@ExpressRouter
export default class ExampleRouter {
	@Endpoint({
		method: 'GET'
		path: '/users'
	})
	getUsers(req,res){
		// GET Route handler code here!
	}

	@Endpoint({
		method: 'POST'
		path: '/users'
	})
	postUsers(req,res){
		// POST Route handler code here!
	}

	@Endpoint({
		method: 'PUT'
		path: '/users/:id',
		middleware: [middlewareFunc]
	})
	putUsers(req,res){
		// PUT Route handler code here!
	}
}

In runtime, above example will behave in the following way:

const { Router } = require('express');
const { middlewareFunc } = require('some/path');
const router = Router();

module.exports.default =  router
.get('/users', (req, res) => { /* GET Route handler code here! */ })
.post('/users', (req, res) => { /* POST Route handler code here! */ })
.put('/users/:id', middlewareFunc, (req, res) => { /* PUT Route handler code here! */ })

Back to Menu

Interfaces

The interfaces that this library provides and that are described here provide help to the developer that will consume this library to build incredible web applications.

Constraints

The interfaces mentioned in this section will be importable only if you are developing your web application with typescript.

Back to Menu

IAppSettings

Used as an argument for the ExpressApplication.construct method, and used to create an instance of the class ExpressCoreApplication with arguments different from those used by default.

Parameters

| Param | Type | Required? | Description | |-|-|-|-| | appPath | string | true | The __dirname when using from src/index.ts file.. | | environment | string | false | When provided your app will use this env instead NODE_ENV. | | appName | string | false | Your application name. | | logger | ILoggerSettings | false | valid ILoggerSettings object. | | locals | any | false | any data that you want push to app.locals. | | port | number | false | The port for tour webApplication; defaults to 3000. | | faviconPath | string | false | Relative path to favicon. | | publicFolder | string | false | Relative path to Public folder. | | defaultPage | number | false | Default Page value for req.pager helper. | | defaultPerPage | number | false | Default Per_Page value for req.pager helper. | | corsOptions | CorsOptions | false | valid CorsOptions object. | | compressionOptions | CompressionOptions | false | valid CompressionOptions object. | | urlEncodedOptions | OptionsUrlencoded | false | valid OptionsUrlencoded object. | | jsonOptions | OptionsJson | false | valid OptionsJson object. | | appMiddleware | RequestHandler[] | false | A valid middleware array that you want to use in your app. | | routesFolder | string OR string[] | false | Relative path to Route(s) Folder. | | errorHandler | ErrorRequestHandler | false | valid ErrorRequestHandler function. |

Back to Menu

ILoggerSettings

Used to config the Application logger

Parameters

| Param | Type | Required? | Description | |-|-|-|-| | format | Format | false | valid winston Format. | | fileCfg | IFileSettings | false | valid IFileSettings object. | | customTransports | Transport[] | false | array of your own additional winston Transports |

Back to Menu

IFileSettings

Used to config the Application file logger with daily rotate function.

Parameters

| Param | Type | Required? | Description | |-|-|-|-| | logsPath | string | true | valid Path where logFiles will be placed. | | logFile | string | false | basename for fileLogs. | | datePattern | string | false | datePattern for fileLogs, defaults to YYYYMMDD.|

Back to Menu

IEndpointConfig

Interface Used to describe arguments for the method decorator "@Endpoint".

It helps us to transform the decorated method into a useful Route handler for Express.js.

Parameters

| Param | Type | Required? | Description | |-|-|-|-| method | string OR string[] | true | Method, list of methods delimited by commas or an array of valid methods for Express.js. path | string | true | Route path valid for Express.js. middleware | RequestHandler[] | false | A valid middleware array that you want to prefix to your Express.js Route handler.