node-backend-framework v2.1.5

Node Backend framework

A Node backend framework extending Express written in TypeScript. It introduces the Controller principle known from other various frameworks. It has built-in authorization handling, easy CORS configuration via environment variables and out of the box Sentry support.

Using TypeScript with this framework is highly recommended! All shown examples are in TypeScript. Also, Yarn is used in the examples, but NPM should work fine too.

Initializing a backend project

Initialize a Node project:

yarn init

Install the framework:

yarn add node-backend-framework

Initialize a backend project:

npx be-init # or just `be-init` when globally installed

NOTE: Using Visual Studio Code as IDE is highly recommended!

App class

The App class is the default export of the application and will initialize the controllers, middleware and error handler. It will also check for a .env file and inject its content into process.env when found.

Use it like this:

import App from 'node-backend-framework'; // make sure to import first so .env is injected from the start
import express from 'express';
import HelloWorldController from './controllers/HelloWorldController';

const app = new App(
    [new HelloWorldController()],
    [express.json()] // optional, Express middleware to be used
);

app.start(`Server started at port ${app.port}`); // start with custom start up message

export default app;

To specify a middleware path:

const app = new App(
    [new HelloWorldController()],
    [{ middleware: express.json(), mPath: '/' }]
);

Controllers

A controller will take care of routing and handles requests. The routes can be grouped by the programmer this way. It also contains a default authorization handler which will check for a Bearer JWT in the Authorization header. It will try to verify the JWT with the secret found in the JWT_SECRET environment variable.

A controller can be set up like this:

import {
    Controller,
    Method,
    Route,
    XRequest,
    XResponse
} from 'node-backend-framework';

/**
 * Controller regarding Hello world routes.
 */
export default class HelloWorldController extends Controller {
    readonly path = '/hello'; // obligated override, set the base path for this controller
    readonly routes: readonly Route[] = [
        {
            path: '/world', // the subpath, will result in => /hello/world
            requestHandler: this.helloWorld, // the function which will handle the request
            method: Method.GET // HTTP method
        }
    ]; // obligated override, set the controller's routes

    /**
     * Return JSON with Hello world message.
     * @param _req Express request object.
     * @param res Express response object.
     * @returns Express JSON response with Hello world message.
     */
    private async helloWorld(
        _req: XRequest, // prepended with _ since it remains unused (linter)
        res: XResponse
    ): Promise<XResponse> {
        return res.json({ message: 'Hello world' });
    }
}

Constructor parameters:

* = optional

Overridable properties:

Routes

A route is represented as an instance of the Route interface. A route is part of a Controller instance, read Controller to see it in action.

Route Properties:

* = optional

Method

A method enum has been created so invalid HTTP methods can't be accidentally passed to routes.

export enum Method {
    GET = 'GET',
    HEAD = 'HEAD',
    POST = 'POST',
    PUT = 'PUT',
    DELETE = 'DELETE',
    CONNECT = 'CONNECT',
    OPTIONS = 'OPTIONS',
    TRACE = 'TRACE'
}

Role

A role is a type alias for a string, number or the following interface:

{ value: number | string; allowHigher?: boolean; allowLower?: boolean }

The value will be compared to the allowed roles, after which will be determined if the user is authorised or not. When setting allowHigher it allows values higher than the allowed role value. When setting allowLower it allows values lower than the allowed role value.

RequestHandler

RequestHandler is a type alias for (XRequest, XResponse) => Promise<XResponse>.

A RequestHandler looks like this:

    /**
     * Return JSON with Hello world message.
     * @param _req Express request object.
     * @param res Express response object.
     * @returns Express JSON response with Hello world message.
     */
    private async helloWorld(
        _req: XRequest, // prepended with _ since it isn't used (linter)
        res: XResponse
    ): Promise<XResponse> {
        return res.json({ message: 'Hello world' });
    }

AuthHandler

AuthHandler is a type alias for (XRequest) => Promise<boolean>.

The default AuthHandler is implemented like this:

/**
* The default AuthHandler to run when `auth` of the controller or route is set to true.
* This method may be overridden by the child controllers
* to allow different auth handling between controllers.
* By default, it checks for a Bearer JWT in the Authorization header and tries to verify it.
* If successful, the decodedJwt will be injected into the Request object and the method will return true, else false.
* @param request Express request object.
* @param roleKey The key of the decoded JWT which has a role value.
* @param roles The roles to allow.
* @returns true if authorised, else false.
*/
protected async authHandler(
        request: XRequest,
        roleKey: string,
        roles?: readonly Role[]
    ): Promise<boolean> {
        if (!process.env.JWT_SECRET) {
            throw Error('No JWT_SECRET environment variable set.');
        }
        const authHeader = request.headers.authorization;
        if (authHeader === undefined) return false;
        if (!authHeader.startsWith('Bearer ')) return false;
        const token = authHeader.replace(/^(Bearer )/, '');
        try {
            const decoded: any = jwt.verify(token, process.env.JWT_SECRET);
            if (decoded instanceof String) return false;
            if (
                roles &&
                (decoded[roleKey] === undefined ||
                    !roles.find(role => {
                        if (role instanceof Object) {
                        if (role.allowHigher) {
                            return decoded[roleKey] >= role.value;
                        }
                        if (role.allowLower) {
                            return decoded[roleKey] <= role.value;
                        }
                    }
                    return decoded[roleKey] === role;
                }))
        )
            return false;
        request.decodedJwt = decoded;
        return true;
    } catch {
        // ignored
    }
    return false;
}

Requests & Responses

A request and response are wrapped into a XRequest and XResponse object respectively.

XRequest extends express.Request with the decodedJwt property.

As of now XResponse is only an alias of express.Response.

Read this for more information.

CORS

CORS is disabled by default and can be enabled using the CORS_WHITELIST environment variable.

Allow all domains CORS_WHITELIST=*.

Allow certain domains CORS_WHITELIST=["https://localhost:8080", "http://localhost:8081"].

NOTE: When using an array, it has to be a JSON array string (so double quotes only!).

Throw an exception when CORS is not allowed: CORS_ERROR=CORS disallowed.

Tasks & CronJobs

Tasks are represented as async functions which return nothing (void).

Tasks can be executed with the command line using the be-task command. Without globally installing this framework, it can be done using NPX. By default, the CLI will look into the dist/tasks folder. This can be overridden by setting the TASK_DIR environment variable. The dist/tasks folder contains the JavaScript files which have been compiled from the tasks source. The files will be auto compiled.

Task CLI options and examples:

Running all tasks:

yarn task -A # or --all

Running a single task:

yarn -T calculate  # (.js), or --task

Running tasks from other directory:

yarn task -A -d ./src/crons # or --dir

To run the tasks without auto-compiling (it has to be compiled earlier), replace yarn task with npx be-task

Cron jobs are represented by instances of the CronJob class. It takes a crontab schedule string or Date object to schedule, a task to run on schedule and optionally a onComplete function which is executed when the cron job is stopped (stop() is called). It must then be passed to the App instance. The timezone can be set using the TIMEZONE environment variable.

NOTE: Don't use this in production, but run your tasks from the CLI using a scheduler since this blocks the I/O stream.

Example:

import App, { CronJob } from 'node-backend-framework';
import express from 'express';
import HelloWorldController from './controllers/HelloWorldController';
import calculateTask from './tasks/calculate';

const app = new App(
    [new HelloWorldController()],
    [express.json()],
    [new CronJob('0 12 * * *', calculateTask)] // everyday at 12:00
);

app.start(`Server started at port ${app.port}`); // start with custom start up message, crons are executed by schedule from here

export default app;

Sentry

This framework has Sentry error monitoring support built-in. Sentry will automatically be enabled when the environment variable SENTRY_URL is set. The value will then be used as the dsn property of the initialization options. To use a advanced config, pass the configs to the App constructor:

import App, { MiddlewareError } from 'node-backend-framework';
import express from 'express';
import { CaptureConsole } from '@sentry/integrations';

import HelloWorldController from './controllers/HelloWorldController';

const app = new App(
    [new HelloWorldController()],
    [express.json()],
    undefined,
    {
        dsn: 'https://example@3mp1e.ingest.sentry.io/0000000', // will use this value instead of the SENTRY_URL environment variable
        integrations: [
            new CaptureConsole({
                levels: ['error']
            })
        ]
    }, // Sentry init config
    { ip: '127.0.0.1' }, // Sentry request handler options
    { shouldHandleError: (error: MiddlewareError) => error.status > 499 } // Sentry error handler options, handle error when status code is 500 or higher
);

app.start(`Server started at port ${app.port}`); // start with custom start up message, crons are executed by schedule from here

export default app;

NOTE: Integrations are required to be installed separately:

yarn add @sentry/integrations

For more documentation about configuring Sentry, read https://docs.sentry.io/platforms/node/express/.

HttpException

Can be thrown to return an error response to the client.

export default class HttpException extends Error {
    readonly status: number; // HTTP status code
    readonly message: string; // message in the JSON response body when status < 500
    constructor(status: number, message: string) {
        super(message);
        this.status = status;
        this.message = message;
    }
}

Environment variables

* = Look here for supported timezones.

Dependencies

This framework uses the following dependencies.

Tests

Tests are written with Jest and Supertest and can be found in the __tests__ folder.

Tests can be run with

yarn test

Contribution

Contribution is welcome via GitLab :), please respect the TypeScript, ESLint and Prettier configurations and use Yarn instead of NPM.

More information

Read the Express documentation for more information about how this framework works and how to extend it.