Steplix Microservice

Steplix Microservice is a Node.js base microservice.

Index

• Download & Install
• How is it used?
  • Getting started
  • Configure
  • Detailed explanation
    • Config
    • Database
    • Routes
    • Errors
    • Validator
    • Logger
• Tests

Download & Install

NPM

    npm i steplix-microserver

Source code

git clone https://gitlab.com/steplix/SteplixMicroservice.git
cd SteplixMicroservice
npm install

How is it used?

NOTE: Based on bluebird promises.

Getting started

const pkg = require('./package.json');
const { app, listen } = require('steplix-microservice/server');
const { errors, health } = require('steplix-microservice/server/routes');

app.get('/', (req, res) => res.send('Hello World!'));

health(app, { pkg /* , router, database, services: ['other-service-name'] */ });
// Handle all errors (400, 404, 500, etc...)
errors(app);

listen(app);
/*
 * Listen routes
 *  + GET  /        Home
 *  + GET  /health  Health check
 *  + ANY  /*       404 error. {code: 404, error: 'Not Found'}
 */

Configure

For app/server.

Environment variable	Values	Type	Default value	Description
SERVER_HOST	host name	string	undefined	Host name where the server listens
SERVER_PORT / PORT	port number	number	8000	Port where the server listens
SERVER_MULTIPART	true/false	boolean	false	Indicate if app use support for multipart middleware

(go to top)

For database

Simple configuration

Environment variable	Values	Type	Default value	Description
DB_ENABLED	true/false	boolean	true	Indicate if need support for database
DB_NAME	database name	string	null
DB_HOST	database host name	string	'db.steplix.com'
DB_PORT	database port	number	3306
DB_USER	database user	string	'admin'
DB_PASS	database password	string	null
DB_TIMEZONE	database timezone	string	'+00:00'

(go to top)

Read/Write replication configuration

Environment variable	Values	Type	Default value	Description
DB_HOST_WRITE	database host name	string	DB_HOST	Database host name for write replication
DB_PORT_WRITE	database port	number	DB_PORT	Database port for write replication
DB_USER_WRITE	database user	string	DB_USER	Database username for write replication
DB_PASS_WRITE	database password	string	DB_PORT	Database password for write replication
DB_HOST_READ	database host name	string	DB_HOST	Database host name for read replication
DB_PORT_READ	database port	number	DB_PORT	Database port for read replication
DB_USER_READ	database user	string	DB_USER	Database username for read replication
DB_PASS_READ	database password	string	DB_PORT	Database password for read replication

(go to top)

Pool configuration

Environment variable	Values	Type	Default value	Description
DB_POOL_ENABLED	true/false	boolean	true	Indicate if need support for db pool connections
DB_POOL_MAX	max pool connections	number	10	Maximum number of connection in pool
DB_POOL_MIN	min pool connections	number	0	Minimum number of connection in pool
DB_POOL_IDLE	max idle time	number	10000	Maximum time, in milliseconds, that a connection can be idle before being released
DB_POOL_ACQUIRE	max time reconnect	number	60000	Maximum time, in milliseconds, that pool will try to get connection before throwing error
DB_POOL_EVICT	interval time	number	1000	Time interval, in milliseconds, after which sequelize-pool will remove idle connections

(go to top)

For services

Environment variable	Values	Type	Default value	Description
SERVICE_AGENT	service agent name	string	''
SERVICE_CONNECTION_TIMEOUT	number in miliseconds	number	21000
SERVICE_REQUEST_TIMEOUT	number in miliseconds	number	20000

(go to top)

For global dependencies

Environment variable	Values	Type	Default value	Description
DEFAULT_LOCALE	locale	string	'es'	Default locale
MOMENT_LOCALE	locale	string	DEFAULT_LOCALE	Default locale for moment module
MOMENT_DEFAULT_FORMAT	date format	string	'YYYY-MM-DD HH:mm:ss'	Default format for moment.format
NUMERAL_LOCALE	locale	string	DEFAULT_LOCALE	Default locale for numeral module
NUMERAL_DEFAULT_INTEGER_FORMAT	number format	string	'0,0'	Example usage numeral(1000).format(numeral.defaultIntegerFormat)
NUMERAL_DEFAULT_DECIMAL_FORMAT	number format	string	'0,0.00'	Example usage numeral(10.01).format(numeral.defaultDecimalFormat)
NUMERAL_DEFAULT_BALANCE_FORMAT	number format	string	'$ 0,0.00'	Example usage numeral(100.2).format(numeral.defaultBalanceFormat)
LODASH_TRUNCATE_LENGTH	length	number	24	Default truncate length use for lodash. Example usage _.truncate('hi-diddly-ho there');
LODASH_TRUNCATE_SEPARATOR	string separator	string	' '	Default truncate separatotr use for lodash. Example usage _.truncate('hi diddly there');

(go to top)

Detailed explanation

Server

const {
    // Base express application instance
    //  Example usage:
    //   app.get('/', (req, res) => res.send('Hello World!'));
    app,

    // Listen express application instance.
    // If the `config('server.https.enabled')` is false, listen from the express application instance will be executed.
    // If the `config('server.https.enabled')` is true, listen from the instance of https.createServer({ key, cert }) will be executed.
    //  Example usage:
    //   listen(app);
    //
    // NOTE: Listen does nothing when NODE_ENV=test
    listen
} = require('steplix-microservice/server');

(go to top)

Routes

const {
    // Routes for error handling. Handle all responses errors (400, 404, 500, etc...)
    //  Example usage:
    //   errors(app);
    errors,

    // Route for health check.
    //  Example usage:
    //   // Simple usage
    //   health(app);
    //
    //   // With options
    //   health(app, {
    //     // To be able to import package.json and tag.json if they exist. Default null
    //     rootDir: require('./package.json'),
    //
    //     // For add package information details on health response. (name, description and version)
    //     pkg: require('./package.json'),
    //
    //     // For add tag details on health response. (commit, version, name, etc)
    //     tag: require('./tag.json'),
    //
    //     // In order to run the health check on a specific router.
    //     router: express.Router(),
    //
    //     // To be able to change the url of health check. Default '/health'
    //     url: '/my/custom/url/for/healthcheck',
    //
    //     // IDEM url. Default null
    //     path: '/my/custom/url/for/healthcheck,
    //
    //     // For add database information details on health response. (is alive, error)
    //     database: <database instance require('steplix-sequelize')>,
    //
    //     // For add required services information details on health response. (is alive, error)
    //     service: <string list of services added to steplix-microservice/helpers/service>
    //   });
    health
} = require('steplix-microservice/server/routes');

(go to top)

Get by ID

Get model by id

const Route = require('steplix-microservice/server/routes/getById');

const route = new Route('YourModel', {
    // Indicates the name of the parameter to search in `req.params`. Default 'id'
    paramNameId: 'id',

    // Indicates the validation that will be applied to the parameter. Default 'isInteger'
    // Possible values:
    //  Function
    //    Example:
    //      function (id, req) { return id > 10; }
    //  String (https://www.gitlab.com/steplix/steplix-microservice#validator)
    validatorIdType: 'isInteger'
});

module.exports = route.handlerize();

(go to top)

Destroy

Delete model. (**WARNING** - Physical erasure! If req.query.force = true)

const Route = require('steplix-microservice/server/routes/destroy');

const route = new Route('YourModel', {
    // Indicates the name of the parameter to search in `req.params`. Default 'id'
    paramNameId: 'id',

    // Indicates the validation that will be applied to the parameter. Default 'isInteger'
    // Possible values:
    //  Function
    //    Example:
    //      function (id, req) { return id > 10; }
    //  String (https://www.gitlab.com/steplix/steplix-microservice#validator)
    validatorIdType: 'isInteger'
});

module.exports = route.handlerize();

(go to top)

List

DEPRECATED List (pagination, filter, order and group) from database model

const Route = require('steplix-microservice/server/routes/list');

const route = new Route('YourModel', {
    // Indicates the page size. Default 10
    defaultPageSize: 10,

    // Indicates the validation that will be applied to the parameter. Default null
    // Possible values:
    //  Object with key-value, where the key is the name of the parameter in the filter, and the value is the name of the column in the database
    //    Example:
    //      { idType: 'id_yourmodel_type' }
    mapKeyParse: null
});

module.exports = route.handlerize();

(go to top)

List by query

List (pagination, filter, order and group) from database model

const Route = require('steplix-microservice/server/routes/listByQuery');

const route = new Route('User', {
    // Relationship with others tables or services. Default value is null
    relationships: [
        // Example for related table
        {
            // relationship name
            name: 'attributes',
            // related table name
            table: 'job_candidates',
            // field needed from related table for join relationship
            fieldSource: 'candidates.id_job',
            // field needed from model for match join relationship
            fieldTarget: 'jobs.id'
        },

        // Example for related with remote service
        {
            // relationship name
            name: 'person',
            // indicate that relationship is with a remote service
            remote: 'true',
            // service name. helpers/service[<service name>]
            service: 'people',
            // url of remote endpoint
            uri: '/people',
            // field needed from remote service for join relationship
            fieldSource: 'id',
            // field needed from model for match join relationship
            fieldTarget: 'users.id_person'
        }
    ],

    // Indicates the page size. Default 10
    defaultPageSize: 10,

    // Indicates the validation that will be applied to the parameter. Default null
    // Possible values:
    //  Object with key-value, where the key is the name of the parameter in the filter, and the value is the name of the column in the database
    //    Example:
    //      { idType: 'id_yourmodel_type' }
    mapKeyParse: null
});

module.exports = route.handlerize();

(go to top)

Proxy

Handrails between microservices

const Route = require('steplix-microservice/server/routes/proxy');

const route = new Route({
    // Indicates the service name defined on steplix-microservice/helpers/service.
    serviceName: 'myService',

    // Indicates the function use on service instance. Default `req.method`
    serviceMethod: req.method,

    // Indicates the path use when calling service. Default `req.path`
    serviceUrl: req.path,

    // Extra service request options. Default `{}`
    serviceOptions: {
      responseType: 'json'
    },

    // Indicate if response with the same service response content type.
    sameContentType: true

    // TODO :: Send in service request, the same header from original request
    // headers: [
    //   'authorization'
    // ]
});

module.exports = route.handlerize();

Base route

const _ = require('lodash');
const Base = require('steplix-microservice/server/routes');
const { validator } = require('steplix-microservice/helpers');
const { errors, database } = require('steplix-microservice');
// ...
class Route extends Base {
    /**
     * Validate request
     */
    validate (req) {
        if (_.isEmpty(req.params)) {
            throw new errors.BadRequest('Bad request. Please set "id" parameter');
        }
        if (!validator.isInteger(req.params.id)) {
            throw new errors.BadRequest('Bad request. Please use "id" on parameters');
        }
        return req;
    }

    /**
     * Handle request
     */
    handler (req) {
        return database.models.YourModel.getById(req.params.id).then(model => {
            if (!model) {
                throw new errors.NotFound(`Not found model ${context.id}`);
            }
            return model;
        });
    }
}

module.exports = (new Route()).handlerize();

(go to top)

Config

In order to see all config documentation click here

const { config } = require('steplix-microservice');
// ...
// Read configuration
config('server.port'); // 8000

// Extend current configuration.
config.extend({ server: { port: 8001 } });
config('server.port'); // 8001

// Use default value.
config('server.port2', 8001); // 8001

(go to top)

Database

In order to see all database documentation click here

const { errors, database } = require('steplix-microservice');
// ...
return database.models.YourModel.getById(id).then(yourModel => {
    if (!yourModel) {
        throw new errors.NotFound(`Model not found ${id}`);
    }
    return yourModel;
});

Example use raw database, function query

In order to see all operators click here

const { database } = require('steplix-microservice');
// ...
return database.models.YourModel.find({
    where: {
        deleted_at: {
            [database.Op.is]: null
        }
    },
    order: [['id', 'DESC']],
    limit: 100,
    offset: 0
});

Example use raw database, function query

In order to see all query types click here

const { database } = require('steplix-microservice');
// ...
return database.query('UPDATE users SET active = 0 WHERE id = 1', { type: database.QueryTypes.UPDATE }).spread((results, metadata) => {
    // ...
    return metadata;
});

(go to top)

Errors

const { errors } = require('steplix-microservice');
// ...
throw new errors.NotFound();

// All HTTP Status Code are an Exception
const e = new errors.NotFound('My custom message', {hello: 'world'});
// ...
console.log(e.toJson());
// { "error": 'My custom message', "code": 404, "extra": { "hello": "world" } }

(go to top)

Validator

In order to see all validation functions click here

const validator = require('steplix-microservice/helpers/validator');

validator.isEmail('[e-mail]'); // true

Custom validations.

Integer

validator.isInteger(); // false
validator.isInteger(null); // false
validator.isInteger('a'); // false
validator.isInteger('6'); // true
validator.isInteger('6.1'); // false
validator.isInteger('-6'); // true
validator.isInteger(6); // true
validator.isInteger(6.1); // false
validator.isInteger(-6); // true

Number

validator.isNumber(); // false
validator.isNumber(null); // false
validator.isNumber('a'); // false
validator.isNumber('6'); // true
validator.isNumber('6.1'); // true
validator.isNumber('-6'); // true
validator.isNumber(6); // true
validator.isNumber(6.1); // true
validator.isNumber(-6); // true

(go to top)

Logger

const logger = require('steplix-microservice/helpers/logger');

logger.error(new Error('Not Found')); // [2020-01-28T17:16:50.379Z] - ERROR - ✘ Ooops... Error: Not Found
logger.error('This is an error');     // [2020-01-28T17:16:50.379Z] - ERROR - ✘ Ooops... This is an error
logger.warn('This is a warning');     // [2020-01-28T17:16:50.381Z] - WARN - ⚠ This is a warning
logger.info('Hello World!');          // [2020-01-28T17:16:50.381Z] - INFO - Hello World!
logger.title('Hello World!');         // [2020-01-28T17:16:50.382Z] - INFO - ==========   Hello World!   ==========
logger.success('Hello World!');       // [2020-01-28T17:16:50.383Z] - INFO - ✔ Hello World!
logger.arrow('Hello World!');         // [2020-01-28T17:16:50.384Z] - INFO - • Hello World!
logger.step('Hello World!');          // [2020-01-28T17:16:50.384Z] - INFO - ✦ Hello World!
logger.lap('Hello World!');           // [2020-01-28T17:16:50.384Z] - INFO - ➜ Hello World!

(go to top)

Tests

In order to see more concrete examples, I INVITE YOU TO LOOK AT THE TESTS :)

Run the unit tests

npm test

(go to top)