Appolo HTTP

Appolo HTTP is an light MVC Framework for Node.js written in Typescript
Build with appolo framework and appolo-inject dependency injection module.
Appolo architecture follows common patten of MVC and dependency injection which makes it easy to build better performance, flexibility and easy maintenance server side in nodejs.

Features

Super fast
MVC Architecture
Full support for express middlewares
Dependency injection system
Simple routing system
Routes validation
Manage easily configurations and environments
Simple folder structures
Easy integrate third party modules
Easy to get started

Installation

npm install appolo-http --save

Typescript

appolo-http requires TypeScript compiler version > 2.1 and the following settings in tsconfig.json:

{
    "experimentalDecorators": true
}

Quick Start

In your app.js file:

var appolo  = require('appolo-http');
appolo.launch();

Benchmarks

node benchmarks/benchmarks

Machine: 2.2 GHz Intel Core i7, 16GiB RAM

Method: autocannon -c 100 -d 10 -p 10 localhost:3000

Name	Average	Min	Max
Req/Sec	32,821.6	23,840	34,463

Examples

Real-time Stocks

live demo: demo.
source code: code.

Chat

source code: source
live demo:demo

Recommended Directory Structure

The config/environments folder is required. Appolo will require all files in the config and server folders, but the environments folder will be loaded first. All other folders are optional and will not influence the way appolo-http works.

|- config
  |- environments
    |- all.ts
    |- development.ts
    |- production.ts
  |- express
    |- all.ts
  |- modules
    |- logger.ts
    |- redis.ts
    |- mongo.ts
    |- modules.ts
    ...
|- server
    |- controllers
    |- managers
    |- middleware
    |- services
    |- bootstrap.ts
    ...
|- app.ts

Configuration

appolo launch configuration options, all options are optional

key	Description	Type	Default
`paths`	folders that will be required and loaded on appolo launch	`array`	`['config', 'server']`
`root`	the root folder of the paths option	`string`	`process.cwd()`
`environment`	environment file name that will override the settinngs in `environments/all.js`	`string`	`(process.env.NODE_ENV
`startMessage`	the message that will be written to console log the the server starts	`string`	`'Appolo Server listening on port: {port} version:{version} environment: {environment}'`
`startServer`	if true the server will start immediately to listen to port else you will have to start in manually.	`boolean`	`true`
`port`	the port that the app will listen to.	`number`	`process.env.PORT
`errorStack`	print route http stack error when env is not development	`boolen`	`false`
`errorMessage`	print route http error.toString()	`boolen`	`true`
`maxRouteCache`	the max size of route lookup lru cache	`number`	`10000`

usage example:

let appolo  = require('appolo-http');

appolo.launcher.launch( {
    paths:['config', 'server'],
    root : process.cwd()+'/app',
    environment : 'testing',
    port:8182,    
});

Environments

With environments you can define different configurations depending on the environment type your app is currently running. It is recommended to have 4 types of environments: development, testing, staging, production. After appolo.launch you can always access the current environment vars via appolo.environment.

//all.ts
export = {
    name:'all',
    someVar:'someVar'
}
//development.ts
export = {
    name:'develpment',
    db:'mongo://development-url'
}
//development.ts
export = {
    name:'testing',
    db:'mongo://testing-url'
}

If we launch our app.js with NODE_ENV = testing

var appolo  = require('appolo-http');
appolo.launcher.launch();
var env = appolo.environment;
console.log(env.name,env.someVar,env.db) // 'testing someVar monog:://testing-url'

Express modules

You can configure express modules or add custom middleware by adding configuration files to the express folder. The express configuration file is called after the environment files were loaded.

//express/all.ts
import favicon = require('static-favicon');
import bodyParser = require("body-parser");

export = function (app: appolo.App) {
    app.use(bodyParser.json());
    
    app.use(function (req: appolo.IRequest, res: appolo.IResponse, next: appolo.NextFn) {
        res.setHeader("Access-Control-Allow-Origin", "*");
        next();
    });
    app.use(favicon());
}

Routes

You can easily bind a route path to a controller method. The routes path are defined in the same way as in expressjs router.

Each route class has the following methods:

path - same as in expressjs.
method - one of get,post,patch,delete,put. default get.
action - the action function the will be invoked to handle the route.
middleware - middleware function the will be invoked before the controller. If the next function is not called or called with an error, the controller won`t be created.
validation - validations object as defined in joi.

import {define,singleton,initMethod,inject,Controller,IRequest,IResponse} from 'appolo-http';

@define()
export class TestController extends Controller{
    @inject() dataManager:DataManager
    
    @path("/test/:userId")
    @method(appolo.Methods.POST)
    public test (req:IRequest, res:IResponse) {
       res.send(this.dataManager.getData(req.params.userId));
    }
}

@define()
export class Test2Controller extends Controller{
    @inject() dataManager:DataManager
    
    @pathPost("/test2/:userId")
    @validations("userId",validator.string().required())
    public test (req:IRequest, res:IResponse) {
       res.send(this.dataManager.getData(req.params.userId));
    }
}

You can also define routes using appolo.route method:

import {define,singleton,initMethod,inject,Controller,IRequest,IResponse} from 'appolo-http';

@define()
export class TestController extends Controller{
    @inject() dataManager:DataManager
    
    public test (req:IRequest, res:IResponse) {
       res.send(this.dataManager.getData());
    }
}

appolo.route<TestController>(TestController)
    .path("/test/")
    .method(appolo.Methods.GET)
    .action(c=>c.test)

Routes Validation

You can add validations to your routes. The action controller will be called only if the route params are valid.
Validations are done using joi module .
The validator takes request params from req.param , req.query and req.body. After validation, all request params will be available on req.model.

import {define,singleton,initMethod,inject,Controller,IRequest,IResponse} from 'appolo-http';
let validator = appolo.validator;

@define()
export class TestController extends Controller{
    
    @inject() dataManager:DataManager
    
    public async search (req:IRequest, res:IResponse) {
       try{
           let model = req.model;
           let result = await this.dataManager.getSearchResults(model.search,model.page,model.pageSize)
            this.sendOk(result)
       }catch(e){
           this.sendError(e)
       } 
    }
}

appolo.route<TestController>(TestController)
    .path('/search/')
    .action(c=>c.search)
    .validations({
        search:validator.string().required(),
        pageSize:validator.number().default(20),
        page:validator.number().default(1)
    })

If the request params are not valid, appolo will return a 400 Bad Request response with detailed validation errors.

{
    status: 400,
    statusText: "Bad Request",
    error: "userId is required"
    
}

Controllers

Controllers are classes that handle routes request. In order for the router to be able to handle the request, a controller class must extend appolo.Controller. Each controller action will be called with request and response objects.

import {define,inject,mehtod,path,validation,Controller,Methods,IRequest,IResponse,IRouteOptions,validator} from 'appolo-http';

@define()
export class LoginController extends Controller{
    
    @inject() authManager:AuthManager;
    
    @path("/login/")
    @mehtod(Methods.POST)
    @validation("username", validator.string())
    @validation("password", validator.string())
    public aynsc loginUser(req:IRequest,res:IResponse,route:IRouteOptions){
        try{
            let result =  await this.authManager.validateUser(req.model.username,req.model.password)
            this.send(result)

        }catch (e){
            this.sendError(e)
        }
    }
}

By default, appolo creates a new controller instance for every request. If you do not need a new controller instance for every request, you can inherit from StaticController which is singleton.

import {define,singleton,inject,lazy,mehtod,path,validation,StaticController,Methods,validator,IRequest,IResponse,IRouteOptions} from 'appolo-http';
@define()
@singleton()
@lazy()
export class LoginController extends StaticController{
    @inject() authManager:AuthManager;
    
    @path("/login/")
    @mehtod(Methods.POST)
    @validation("username", validator.string().required())
    @validation("password", validator.string().required())
    public aynsc loginUser(req:IRequest,res:IResponse,route:IRouteOptions){
        try{
            let result = await this.authManager.validateUser(req.model.username,req.model.password)
            this.send(res,result)
        
        }catch (e){
            this.sendError(e)
        }
    }
}

appolo.Controller

this.req - request object
this.res - response object
this.route - the route object of the current action

json success helper methods

this.send([statusCode?:number?,data?:any]) - send json response with status code
this.sendOk([data?:any]) - send json with statusCode 200
this.sendCreated([data?:any]) - send json with statusCode 201
this.sendNoContent() send empty response with statusCode 204

json server error helper methods

this.sendError([error?:Error,code?:number]) send Error with statusCode 500
this.sendBadRequest([error?:Error,code?:number]) send Error with statusCode 400
this.sendUnauthorized([error?:Error,code?:number]) send Error with statusCode 403
this.sendNotFound([error?:Error,code?:number]) send Error with statusCode 404

send json error response with optional message

error - the error object that will be passed to the response
code - the error code object that will be passed to the response

{
     "status": 500,
     "statusText": "Internal Server Error",
     "error":"something is wrong",
     "code":1001
}

Middleware

A middleware class will run before the action of the controller is invoked. The middleware class must extend must extend appolo.Middleware and implement the run method.

Middleware file:

import {define,inject,Middleware,IRequest,IResponse,NextFn,IRouteOptions} from 'appolo-http';
@define()
export class AuthMiddleware extends Middleware {
    
    @inject() authManager:AuthManager;
    
    public async run(req:appolo.IRequest,res:IResponse,next:NextFn,route:IRouteOptions){
        try{
            let result =  await this.authManager.validateToken(req.headers.authorization)     
            req.user = user;
            next();
            
        }catch(e){
            this.sendUnauthorized();
        } 
    }
    
}

In order to use a middleware in a controller, add it using appolo.route(...).middleware(<middleware-id>):

    appolo.route("someController").path("somePath").middleware(AuthMiddleware)

Dependency Injection System

Appolo has a powerful Dependency Injection system based on appolo-inject. It enables you to write organised, testable code based on the loose coupling idea. You can always access the injector via appolo.injector.

class decorators

define - make the object injectable
singleton - the class will be created only once and the injector will return the same instance every time
lazy - wait for the class to be injected before creating it
alias - add alias name to the object (allows injecting multiple objects which share an alias using injectAlias)
aliasFactory - add alias factory name to the object (allows injecting multiple objects which share an alias using injectAliasFactory)

methods decorators

initMethod - The method will be called after all instances were created and all the properties injected.

property decorators

inject - inject instance reference by id
injectFactoryMethod - factory method is a function that will return the injected object. This is useful to create many instances of the same class.
injectAlias - inject objects by alias name
injectArray - inject array of properties by reference or by value
injectDictionary - inject a dictionary of properties by reference or by value.
injectAliasFactory - inject factory methods by alias name
injectFactory inject object by factory class
injectObjectProperty inject property of another object
injectValue inject property by value

method parameter decorators

injectParam - inject object by parameter

//dataManager.ts
import {define,singleton,initMethod,inject} from 'appolo-http';
@define()
@singleton()
export class DataManager {
    getData(){
        ...
    }
}
//fooController.ts
@define()
export class FooController{
   
    @inject() dataManager:DataManager
    
    constructor() {
        this.data = null
    }
    @initMethod()
    initialize(){
        this.data =  this.dataManager.getData();
        //do something
    }
}
//app.ts
let fooController = appolo.inject.getObject('fooController');
console.log(fooController.data)

you can also use appolo.register

appolo.register('dataManager')
    .type(DataManager)
    .singleton()

class FooController{
    constructor() {
        this.data = null
    }
    initialize(){
        this.data =  this.dataManager.getData();
        //do something
    }
}

appolo.register('fooController')
    .type(FooController)
    .singleton()
    .initMethod('initialize')
    .inject('dataManager');

let fooController = appolo.inject.getObject('fooController');
console.log(fooController.data)

You can also use constructor injection or method parameter injection:

import {define,singleton,injectParam,initMethod,inject} from 'appolo-http';
@define()
@singleton()
export class DataManager {
    getData(){
        ...
    }
}
@define()
class FooController{
    constructor(@injectParam() dataManager:DataManager) {
       this.dataManager = dataManager;
    }
    @initMethod()
    public initialize(){
        this.data =  this.dataManager.getData();
    }
    
    public test(@injectParam() logger:Logger){
        //...
    }
}

Inherited injections

Inherited injections are supported as well. Anything you inject on a base class will be available to child classes. Remember not to use @define on the parent class.

import {define,singleton,injectParam,initMethod,inject} from 'appolo-http';

export class BaseManager {
    @inject() protected env:any
    private getData(){
        ...
    }
}
@define()
class FooManager extends BaseManager{
    
    @initMethod()
    public initialize(){
        //the env object in injected from the base class
        console.log(this.env.test) 
    }
    
}

Event Dispatcher

Appolo has a built-in event dispatcher to enable classes to listen to and fire events. Event Dispatcher has the following methods:

eventDispatcher.on(event,callback,[scope]) add an event listener
- event - event name.
- callback - callback function that will triggered on event name.
- scope - optional, the scope of the callback function default: this.
eventDispatcher.un(event,callback,[scope]) - remove an event listener. All the arguments must be === to the onces used in the on method, or else it won`t be removed.
- event - event name.
- callback - callback function.
- scope - optional, the scope of the callback function.
eventDispatcher.fireEvent(event,[arguments]) fireEvent - triggers the callback functions of a given event name
- eventName - name of the event
- arguments - all other arguments will be passed to the callback function

import {define,singleton,injectParam,initMethod,inject,EventDispatcher} from 'appolo-http';
@define()
@singleton()
export class FooManager extends EventDispatcher{
    public notifyUsers(){
        this.fireEvent('someEventName',{someData:'someData'})
    }
}
@define()
export class FooController {
    
    @inject() fooManager:FooManager;
    
    @initMethod()
    public initialize(){
        this.fooManager.on('someEventName',(data)=>{
            this.doSomething(data.someData)
        },this);
    }
    doSomething(data){
        ///    
    }
}

Modules

Third party modules can be easily loaded intto appolo inject and used in the inject container. Each module must call appolo.use before it can be used by appolo launcher. appolo.use accepts a function as anargument. The last argument to that function must be the next function: modules are loaded serially, so each module must call the next function or return a promise in order to continue the launch process. Other arguments to the function are object which you wish to inject into the module (these objects must be injected earlier).

By default, each module can inject:

env - environment object,
inject - injector - to add objects to the injector,

Module example:

import appolo = require('appolo-http');
export = function(){
//my custom module 
    appolo.use(function(env:any,inject:appolo.Injector,next:appolo.NextFn){
        let myModuleObject = {data:'test'};	
        inject.addObject('myModuleObject',myModuleObject);
        next();
    }); 
//or with promise
    appolo.use(async function(env:any,inject:appolo.Injector){
        let myModuleObject = {data:'test'};
        await toSomeThing();
        inject.addObject('myModuleObject',myModuleObject);
    });

}
//or with asyc await and appolo load
export = async function(){
    await appolo.load(function(env:any,inject:appolo.Injector){
        let myModuleObject = {data:'test'};	
        inject.addObject('myModuleObject',myModuleObject);
    });
}

Now we can inject myModuleObject to any class:

import {define,singleton,injectParam,initMethod,inject} from 'appolo-http';
@define()
export  class AuthMiddleware{
	
    @inject('myModuleObject') testObject:any
    
    public doSomeThing() {
        return this.testObject.data; //return 'test'
    }
}

Logger module example

A logger module example with winston

loggerModule.js file:

import winston = require('winston');
import appolo = require('appolo');

appolo.use(async function(env:any,inject:appolo.Injector){
    
    transports.push(new (winston.transports.Console)({
        json: false,
        timestamp: true,
        handleExceptions: true
    }));

    let logger = new (winston.Logger)({
        transports: transports,
        exitOnError: false
    });

    inject.addObject('logger', logger);
});

Now we you inject logger anywhere we need it:

import {define,singleton,initMethod,inject} from 'appolo-http';
@define()
export class DataManager{
    @inject() logger:Logger
    public initialize(){
        this.logger.info("dataManager initialized",{someData:'someData'})
    }
}

Appolo Bootstrap

Once it launched, appolo will try to find an appolo bootstrap class and call it's run method. Only when the bootstrap is finished, the server will start

import {define,singleton,injectParam,initMethod,inject,bootstrap,IBootstrap} from 'appolo-http';
@define()
@bootstrap()
export class Bootstrap implements IBootstrap{
    
    @inject() someManager1:SomeManager1
    public async run(){
        //start your application logic here
        await this.someManager1.doSomeThing();
    }
}

Appolo Reset

You can reset appolo sever by calling appolo.reset(). This will clean all environments, config, injector and close the server.

Tests

    grunt test

License

The appolo library is released under the MIT license. So feel free to modify and distribute it as you wish.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
benchmarks		benchmarks
lib		lib
test		test
.gitignore		.gitignore
.npmignore		.npmignore
.travis.yml		.travis.yml
Gruntfile.js		Gruntfile.js
LICENSE		LICENSE
README.md		README.md
decorators.js		decorators.js
decorators.ts		decorators.ts
index.js		index.js
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

shmoop207/appolo-http

Folders and files

Latest commit

History

Repository files navigation

Appolo HTTP

Features

Installation

Typescript

Quick Start

Benchmarks

Examples

Real-time Stocks

Chat

Recommended Directory Structure

Configuration

usage example:

Environments

Express modules

Routes

Routes Validation

Controllers

appolo.Controller

json success helper methods

json server error helper methods

Middleware

Dependency Injection System

class decorators

methods decorators

property decorators

method parameter decorators

Inherited injections

Event Dispatcher

Modules

Logger module example

Appolo Bootstrap

Appolo Reset

Tests

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Languages

Packages