wheatjs/unison

An express based server written in Typescript with support for basic Dependency Injection

Unison Server is still under development. API's are subject to change and is not guaranteed to be stable.

Table of Contents

• About

• Roadmap

• App

• Components

  • Routes
    • Permissions
    • Required Headers
    • Required Body
    • Required Query
  • Sockets
    • IO
    • Socket

• Injectables (Dependency Injection)

  • Creating Injectables
  • Using Injectables

• Install

• Contributing

• License

About

Unison allows you to easily create RESTful web services. It provides support for routes, sockets, and basic dependency injection. Unison makes use of express and socket.io along with many other libraries and would not be possible without them. Unison server is inspired by Angular.

Roadmap

• Add unit tests, failure is not an option... unless it is.
• Improve Dependency Injection, see Issue #3
• Add permissions for sockets.
• Add permissions to components for routes and sockets.

App

To create a unison app, you will need to create a class and decorate it with the @UnisonApp decorator. You will then need to bootstrap the app using the UnisonServer class. When creating the server you will need to pass in a configuration that includes the port and host. In the future, you will also enable https through this configuration.

In the @UnisonApp decorator you will pass application components into the components array and injectables into the injectables array.

import { UnisonServer, UnisonApp } from 'unison-server';

@UnisonApp({
    
    // Register Components Here
    components: []

    // Register Injectables Here
    injectables: []

})
export class App {}

new UnisonServer({ host: 'localhost', port: 8080 }).bootstrap(App);

Components

Components are a place where you can register routes and sockets. Components can also have injectable classes injected into them. To register components, export the class, then import the class into the main app file and add it to components array in the @UnisonApp decorator.

To create a component, decorate a class with the @Component decorator. In the configuration you can add configuration for the routes and sockets that are children of that component. Currently you can configure the baseUrl and method for routes. All children routes will extend the baseUrl and routes without defined methods will default to the method of the method property. Sockets currently have no configuration, but configuration for sockets may be added in the future.

import { Component, Method } from 'unison-server';

@Component({ 
    routes: {
        baseUrl: '',
        method: Method.GET,
        permissions: []
    }, 
    sockets: {} 
})
export class AppComponent {}

Routes

Routes must be defined inside of a @Component. Inside of a route configuration, you can define the route and method. If a routeUrl is defined on the component, the route will extend the component route. If no method is defined, then the method defined on the component will be used. If no method is defined on the component, then the GET method will be used as a default.

To create a route, decorate a @Component method with the @Route decorator. When doing this, your method will receive two different parameters, request and response. The request and response parameters are from express.

import { Component, Route, Method } from 'unison-server';
import { Request, Response } from 'express';

@Component({ 
    routes: {
        baseUrl: '/api/users',
        method: Method.GET
    }, 
    sockets: {} 
})
export class AppComponent {

    constructor() {}

    @Route({ route: '/create', method: Method.POST })
    public createUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

    @Route({ route: '/get' })
    public getUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

}

Permissions

Using Permissions

Permissions act like guards for routes. You can define as many permissions as you want to a route using the @Permissions decorator or in the route config in the @Component decorator.

import { Component, Route, Method, Permissions } from 'unison-server';
import { Request, Response } from 'express';

import { Authenticated } from '~/permissions/authenticated';

...

    @Permissions([Authenticated])
    @Route({ route: '/create', method: Method.POST })
    public createUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

...

Creating Permissions

To create a permission, you will need to create a class and decorate it with the @Injectable decorator. Then you will need to have it implement the IPermission interface. The check method will be where you will implement your permission. It will receive two different parameters, request and response. The request and response parameters are from express. It should return either a boolean or a promise with a boolean. The reject method will be called when the permissions returns a rejection.

import { Injectable, IPermission } from 'unison-server';
import { Request, Response } from 'express';

@Injectable()
export class Authenticated implements IPermission {

    public check(request: Request, response: Response): boolean || Promise<boolean> {
        if ('some permissions check here')
            return Promise.resolve(true);
        else
            return Promise.reject();
    }

    public reject(request: Request, response: Response): Response {
        return response.send({
            success: false,
            error: 'Failed To Authenticate'
        });
    }

}

Required Headers

The @RequiredHeaders decorator can be applied to routes. It will ensure that routes have certain headers, otherwise, it will reject the request and return an error as a response.

import { Route, RequiredHeaders } from 'unison-server';

...

    @RequiredHeaders(['username', 'password'])
    @Route({ route: '/create', method: Method.POST })
    public createUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

...

Required Body

The @RequiredBody decorator can be applied to routes. It will ensure that routes have certain body parameters otherwise, it will reject the request and return and error as a response.

import { Route, RequiredBody } from 'unison-server';

...

    @RequiredBody(['username', 'password'])
    @Route({ route: '/create', method: Method.POST })
    public createUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

...

Required Query

The @RequiredQuery decorator can be applied to routes. It will ensure that routes have certain query parameters otherwise, it will reject the request and return and error as a response.

import { Route, RequiredQuery } from 'unison-server';

...

    @RequiredQuery(['username', 'password'])
    @Route({ route: '/create', method: Method.POST })
    public createUser(request: Request, response: Response): Promise<any> {
        return Promise.resolve(request.json({ date: 'Your Data Here' }));
    }

...

Sockets

Sockets in unison use socket.io. Socket support is currently in early stages and many bugs may be present. Sockets must be part of a component.

IO

The IO decorator uses the io.on(event, callback) method. Below is an example of the @IO(event) decorator. It is called whenever a new connection to the socket is created.

import { IO } from 'unison-server';

...

    @IO('connection')
    public onConnection(io: SocketIO.Server, socket: SocketIO.Socket): void {
        // Handle New User Connection
    }

...

Socket

The Socket decorator uses the socket.on method. Below is an example of the @Socket decorator. It is called whenever a message with the name of hello is sent from a connection.

import { Socket } from 'unison-server';

...

    @Socket('hello')
    public onHello(io: SocketIO.Server, socket: SocketIO.Socket, data: any): void {
        // Handle the socket 'hello` message.
    }

...

Injectables

Unison server provides a very basic implementation of dependency injection.

Creating Injectables

To create an injectable, decorator a class with the @Injectable() decorator. Then you will need to register it in the injectables array inside of the @UnisonApp decorator.

import { Injectable } from 'unison-server';

@Injectable()
export class SomeService {

}

Using Injectables

Injectables can be used inside of components or other injectables. To inject an injectable into another injectable or component, create a parameter in the constructor of the target class and add the type of your injectable.

import { Injectable, Component } from 'unison-server';

@Injectable()
export class SomeService {

    constructor(
        private someOtherService: SomeOtherService
    ) {}

}

@Component(...)
export class SomeComponent {

    constructor(
        private someService: SomeService
    ) {}
    
}

Install

npm install --save unison-server

or

yarn add unison-server

Contributing

If you would like to help, feel free to create issues, create pull requests, or suggest future improvements that could be made.

License

MIT, see LICENSE file.

unison's Issues

Improve dependency injection to be more flexible on what can be injected.

Add support for:

• Non-class dependencies,
• Value providers,
• Aliased class providers,
• Alternative class providers

Improve how @RequiredBody handles nested properties.

The @RequiredBody decorator doesn't currently allow you to check for nested properties. It should be able to go down as deep as necessary to check for properties.

Allow "io" from socket.io to be injected into services and components.

Expose express server instance during startup so custom middleware can be added.

Add tests and a way to test code written on top of the framework.

People seem to like tests for some reason.

Create and Expose an injector

Create and expose an injector that will allow one to get the injectable service by calling a method.

Example: this.injector.get(Service)

Fix how class names are retrieved.

Add support for sockets.

Add support for socket.io

Add a rate limiter.

Add "Required" decorators for routes.

Add decorators for routes that will check for different request parameters that are specified.

• @RequiredHeaders(['authorization', 'token']) - Will check for request headers.
• @RequiredBody(['username', 'password']) - Will check for request body parameters.
• @RequiredQuery(['page', 'limit']) - Will check for query parameters.

@View({ base: '/api/home' })
export class HomeView {

    constructor(
        private userService: UserService
    ) { }

    @RequiredQuery(['page', 'limit'])
    @Route({ route: '/list', method: Method.GET })
    public list(req: Request, res: Response): Response {
        return res.send({
            success: true,
            message: this.userService.getUser()
        });
    }

}

Add an option to turn on and off HTTPS

Move permissions checking into its own class.

Permissions checking is currently inside of the views class. It should be moved over into its own class in another folder to make to code more readable.

Add support for async permissions

Class permissions should be able to return a promise or an observable as a response.

@Injectable()
export class Authenticated implements IPermission {

    constructor() { }

    public check(req: Request, res: Response): Promise<boolean> {
        return fetch('some address');
    }
}

or

@Injectable()
export class Authenticated implements IPermission {

    constructor() { }

    public check(req: Request, res: Response): Observable<boolean> {
        return someObservable();
    }
}

Allow for permissions on views.

Allow for permissions to be added to views that would apply to all routes in the view.