@jeje-devs/ts-roller NPM

TsRoller

General info
Technologies
Setup
Usage
Contributors
Links

General info

TsRoller is an easy to use tool to create a quick Web API using Node.js and Express.js

Example:

import { Controller, controller, httpGet, TsRoller } from '@jeje-devs/ts-roller';

@controller('api/planets')
export class PlanetController implements Controller
{
    @httpGet(':name')
    public getPlanets(name: string): Array<string>
    {
        return ['Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter', 'Saturne', 'Uranus', 'Neptune']
            .filter(x => x.includes(name));
    }
}

// Starting the server
TsRoller.run(
    8080,
    () => console.log("Startup done"),
    error => console.error(error),
    [new PlanetController()]
);

Technologies

Node.js
Express.js
Typescript

Setup

npm install @jeje-devs/ts-roller

Usage

Create a controller class using the decorator @controller and implementing Controller:

@controller('api/route')
export class MyController implements Controller

Create the different http methods using the decorators:

@httpGet('hello')
public sayHello(): string
{
    return 'Hello World!';
}

The available methods are

httpGet
httpPost
httpPut
httpPatch
httpDelete

Query params

To send query params, just add parameters to the endpoint method. The types must be string, number or boolean

// Endpoint url: /api/controller/cars?model=208&brand=Peugeot
@httpGet('cars')
public getCars(model: string, brand: string): Array<Car>
{
    // ...
}

Route params

To send route params, you need to add the parameter in the route in the decorator like this: '/route/:param'

// Endpoint url: /api/controller/cars/431
@httpGet('cars/:id')
public getCarById(id: number): Car
{
    // ...
}

Body params

For httpPost, httpPut and httpPatch you can pass body parameters to the endpoints using the decorator @fromBody

// Endpoint url: /api/controller/cars.
// A body of type 'Car' is expected, for example { name: '208', brand: 'Peugeot' }
@httpPost('cars')
public createCar(@fromBody car: Car): void
{
    // ...
}

You can use all types of parameters:

// Endpoint url: /api/controller/cars/12?language=FR
// 'id' is a route param
// 'car' is a body param
// 'language' is a query param
@httpPut('cars/id')
public updateCar(id: number, @fromBody car: Car, language: string): void
{
    // ...
}

Also, you can write code asynchronously using Promises:

@httpDelete('cars/id')
public async deleteCar(id: number): Promise<void>
{
    await this._carService.deleteCar(id);
}

Here is an example of what you can achieve:

import { controller, Controller, httpGet, httpPost, httpPut, httpDelete, fromBody } from '@jeje-devs/ts-roller';
import { Car } from 'src/models/car.model';
import { CarService } from 'src/services/car.service';

@controller('api/cars')
export class CarController implements Controller
{
    public constructor(
        private readonly _carService: CarService) { }

    @httpGet()
    public async getCars(name: string, brand: string): Promise<Array<Car>>
    {
        return await this._carService.getCars(name, brand);
    }

    @httpPost()
    public async createCar(@fromBody car: Car): Promise<void>
    {
        await this._carService.createCar(car);
    }

    @httpPut(':id')
    public async updateCar(id: number, @fromBody car: Car): Promise<void>
    {
        await this._carService.updateCar(id, car);
    }

    @httpDelete(':id')
    public async deleteCar(id: number): Promise<void>
    {
        await this._carService.deleteCar(id);
    }
}

Starting server

To start the server you need to run the TsRoller.run method:

import { Controller, TsRoller } from '@jeje-devs/ts-roller';
import { CarController } from 'src/controllers/car.controller';
import { CarService } from 'src/services/car.service';

const port = 8080;

function afterServeCallback(): void
{
    // Controller started
}

function onApiErrors(): void
{
    // An error occurred with an endpoint
}

const carService = new CarService();
const carController = new CarController(carService);

const apiInstances: Array<Controller> = [carController];

TsRoller.run(
    port,
    afterServeCallback,
    onApiErrors,
    apiInstances
);

The parameters of the TsRoller.run method are:

port: The port of the server
afterServeCallback: Called once when the server is ready and listening
onApiErrors: Called every time an error occur with an endpoint that would typically return an error code (500)
apiInstances: The list of all controller instances containing the decorator @controller and extending Controller