VESAC

Vesac is an enhancement wrapper around Express.Js

I often have common functionalities in my projects, I'm always copy-pasting files from one project to another. Vesac aim to be the central point of these projects, containing code that I often need and re-use.

⛔️ This project will probably not meet your needs or code quality requirements. I mostly develop it for myself. Btw, if you think you could help to improve it, or make it more suitable for people, do not hesitate to get in touch.️

Functionalities goal :

• [x] HTTP result/error handler
• [x] Internationalisation
• [ ] Auth with JWT
• [ ] References data
• [ ] Validations
• [ ] Permissions
• [ ] Helpers for DB model
• [ ] Error loging
• [ ] Error reporting

Table of content

• Install
• Basic Usage
• Vesac API
• Configure vesac
• Routing
• Internationalisation

Install

$ npm i --save vesac

const vesac = require("vesac");

Basic usage

const vesac = require("vesac");

vesac.configure({ hideSensibleErrors: false });

vesac.get("/fail", () => vesac.httpStatus.internalServerError("Error"));

vesac.post("/ok", ctx => vesac.httpStatus.ok(ctx.req.body));

vesac.start(3000);

Vesac API

| Name | Description | Link | | :--------- | :------------------------------ | :---------------------------------- | | configure | Basic vesac configuration | Configure vesac | | start | Start the HTTP server | Configure vesac | | get | Declare a GET route | Routing | | post | Declare a POST route | Routing | | put | Declare a PUT route | Routing | | del | Declare a DELETE route | Routing | | httpStatus | List of available HTTP statuses | Routing |

vesac.configure should always be called before other interactions with the library.

Configure vesac

vesac.configure(options)

Syntax

const vesac = require("vesac");

vesac.configure({
  hideSensibleErrors: false,
  languages: ["EN", "FR"],
  translationsFolder: path.resolve(__dirname, "./translations"),
});

Api

| Name | Type | Mandatory | Default | Description | | ------------------ | ---------- | -------------------------------------------- | ------------ | ---------------------------------------------------------------------------- | | hideSensibleErrors | boolean | ❌ | true | Hide all the 5xx errors message | | languages | string[] | ❌ | [] | Activate the internationalisation and define the list of languages available | | languageHeader | string | ❌ | x-language | Defines the header the client should send to define it's language | | translationsFolder | path | Mandatory if internationalisation is enabled | none | Provides the list of translations files |

Routing

vesac.get(path, callback)

vesac.post(path, callback)

vesac.put(path, callback)

vesac.del(path, callback)

Syntax

const vesac = require("vesac");

vesac.configure({});

vesac.get("/fail", () => vesac.httpStatus.internalServerError("Error"));
vesac.post("/ok", ctx => vesac.httpStatus.created(ctx.req.body));
vesac.put("/ok/:id", ctx => Promise.resolve(httpStatus.ok(ctx.req.params.id)));
vesac.del("/ok", ctx => ctx.req.body);

vesac.start(3000);

get, post, put and del works the same way as in Express.Js: It takes a path and a callback. If the path is fulfilled, the callback is fired.

The great difference at this level between vesac and express is that in vesac, the callback do not receive and manage explicitly the res object. Vesac will handle this object basec on the output of the callback.

The callback can return :

• Simpe data (string, number, ...)
• JS object or arry (they will be JSON-ified)
• An error
• A promise (which can fulfil or not)
• A vesac HTTP status

The recommanded approach is to use promises resolving or throwing vesac HTTP status.

The vesac default approach is to respond with HTTP/200 for anything but errors and HTTP/500 for errors. You can change this behavior by returning a specific vesac.httpStatus.

vesac.httpStatus

Here is the list of currently available httpStatus you can return from your callback.

| Status | HTTP Status | Default Message | | -------------------------------------- | ----------- | --------------------- | | vesac.httpStatus.ok | 200 | Ok | | vesac.httpStatus.created | 201 | Created | | vesac.httpStatus.accepted | 202 | Accepted | | vesac.httpStatus.movedPermanently | 301 | Moved Permanently | | vesac.httpStatus.found | 302 | Found | | vesac.httpStatus.notModified | 304 | Not Modified | | vesac.httpStatus.badRequest | 400 | Bad Request | | vesac.httpStatus.unauthorized | 401 | Unauthorized | | vesac.httpStatus.forbidden | 403 | Forbidden | | vesac.httpStatus.notFound | 404 | Not Found | | vesac.httpStatus.methodNotAllowed | 405 | Method Not Allowed | | vesac.httpStatus.internalServerError | 500 | Internal Server Error | | vesac.httpStatus.notImplemented | 501 | Not Implemented | | vesac.httpStatus.badGateway | 502 | Bad Gateway | | vesac.httpStatus.serviceUnavailable | 503 | Service Unavailable |

All of them take one optional parameter : the payload (any type accepted).

If no payload is provided, the default message is used. If hideSensibleErrors has been defined at configure level, any payload passed to a 5xx error is ignored and the default message is sent to the client.

request context

The callback receive a context, which contains :

| Name | Type | Description | | --------- | ---------- | ----------------------------------------------------------------------- | | req | object | The Express.Js request object | | translate | function | Translation function. See Internationalisation | | i | function | A translate alias |

Internationalisation

Vesac internationalisation works this way :

• You configure it at vesac.configure level
• You provide translations files
• In the context of requests you have a translate function that provides a translation for anything you need
• The language to use is defined by a header sent by the client

Translation files

A translation file should have this form factor :

// landing.js
module.exports = {
  this_is_vesac: {
    EN: "This is vesac",
    FR: "Voici vesac",
  },
  want_see_doc: {
    EN: "Want to see the doc?",
    FR: "Vous avez envie de voir la doc?",
  },
};

You need to place them in a specific folder that DO NOT contain anything else than translation files. The folder location is defined at vesac.configure level with the option translationsFolder.

Config

vesac.configure({
  languages: ["EN", "FR"],
  translationsFolder: path.resolve(__dirname, "./translations"),
  languageHeader: "xxx-language",
});

The list of language should match the languages you define in the translations files. The first one is always the default one.

The language header defines the header vesac should looks for in order to determine the right translation to use. If none is sent, or if it is not in the list of languages, the default one will be used.

request context

translate(file, key)

i(file, key)

In the requests callback you have access to translate and i who provides translations.

vesac.get("/hello", ctx =>
  vesac.httpStatus.ok(ctx.i("landing", "this_is_vesac")),
);

vesac.get("/docs", ctx =>
  vesac.httpStatus.ok(ctx.translate("landing", "want_see_doc")),
);

vesac.get("/admin", ctx =>
  vesac.httpStatus.ok(ctx.i("admin", "welcome_admin")),
);