Muchas-toolkit NPM

Muchas Toolkit

Muchas Toolkit is a typescript/javascript toolkit that helps creating amazing applications for distributed system, or even monolithic, in a standardize way of development. Is aimed to use a restricted set of services and technologies. Muchas Toolkit can be used with vanilla javascript, but we prefer typescript and thats how all the examples will be.

npm i --save muchas-toolkit

// file: src/index.ts
import { start } from "muchas-toolkit";

start();

Concept

The idea of this toolkit is to work with a concept of components, that can be easily migrated to other projects if needed. It has built-in capacities to work with messages, rest and routines. The goal is to make each component as independent as possible, following a domain driven design so if your application gets large and you need to make each component a independent project, you can do it easily.

Getting Started

The easiest way to get started is to use the muchas-toolkit-cli, it will help you to build your scaffolding without any problem.

Folder Structure

Muchas is opinionated when it come to folders, that way we can ensure consistency between projects and enforce some development patterns.

- src/
-- components/
-- models/
-- index.ts

Everything starts with the index.ts, this is where we call the start() function to initiate the application.

The folder components is where all the components will be, the child component folder name defines the base route for that component, we will explain these later. all the folders inside will be loaded automatically.

The folder models is where all the models (Mongoose Models), all files inside will be loaded automatically.

Configuration

The toolkit looks for a config.ts file inside the src folder. This where you will setup all the features that you want enabled and the configuration, such as database (mongo), messages (rabbitmq), etc. The following configurations are available:

export default {
  logger: {
      console: {
        level: "debug",
        enabled: "true",
      },
      elastic: {
        enable: "false",
        host: "http://elasticsearch.com",
        level: "debug",
      }
  },
  database: {
    enabled: "false",
    uri: "mongodb://mongodb-uri",
    poolSize: 10,
  },
  broker: {
    enabled: true,
    prefix: true,
    host: "http://rabbitmq:5672",
  },
  web: {
    port: 8080,
    headers: [],
    secret: "",
  },
  swagger: {
      enabled: false,
  },
  routines: {
    enabled: false,
    prefix: true,
    timezone: "",
    ui: false;,
  },
}

You can use a .env file in the root of your folder to provide environment variables, this file is going to be automatically imported and can be use accessing the global process.env

You can add custom properties to this file to centralize any configuration of your application, that is extremely recommended. For example:

export default {
  // ... Default configurations
  custom: {
    apiKey: process.env.API_KEY,
  },
};

Than you can use it in any where of your code by importing the config from the muchas-toolkit:

import { config } from "muchas-toolkit":

console.log(config.custom.apiKey);

We also provide custom function to help knowing in which environment you are working with, so you can dynamically enable features and properties:

import { isDev, isPrd } from "muchas-toolkit":

console.log(isDev); // Returns true if in development environment or false if not

console.log(isPrd); // Returns true if in production environment or false if not

Models

The src/models folders is where you can define your Mongoose Schemas to use across your application, the name of the file will be use as the name of the model/collection. The file must exports a valid mongoose schema, such as bellow:

/** file: src/models/ModelExample.ts
 *
 * ModelExample Model
 *
 */

/* eslint-disable func-names */
import { mongoose } from "muchas-toolkit";

const { Types } = mongoose.Schema;

/**
 *  ModelExample Mongoose Scheme
 */
const schema = new mongoose.Schema(
  {
    name: {
      type: Types.String,
      required: true,
    },
  },
  {
    timestamps: true,
  },
);

/**
 * ModelExample Type
 *
 * @export
 * @interface ModelExample
 */
export interface ModelExample {
  name?: string;
}

/**
 * ModelExampleModel
 *
 * @export
 * @interface ModelExampleModel
 * @extends {ModelExample}
 * @extends {mongoose.Document}
 */
export interface ModelExampleModel extends ModelExample, mongoose.Document {}

export default schema;

Component

As we already spoken, the toolkit enforces the concept of components, they need to be created inside the src/components folders, the component name is going to be the folder name and this is going to be used as the base url for all routes and prefix for routines and messages/queues.

Lets see the structure inside a example component located at src/components/example:

Everything starts with a index.ts file that exports a component class:

import { Component } from "muchas-toolkit";

export default new Component({
  routes: [],
  routines: [],
  messages: [],
  beforeLoad: () => {}, // Function executed before the component is loaded to the application
  afterLoad: () => {}, // Function executed after the component is loaded to the application
});

Root Component

If you want to develope a single component application you can create a folder called root. This component will not have a base url for routes and will be treated as the root for everything. Caution if you use a root component with others components, you can have problems with overlapping routes.

Routes - ExpressJS

The under the hood framework for the routes is the ExpressJS

Routines - Agenda and Agendash

The under the hood framework for the routines is the Agenda and for a graphic interface when developing the routines we use Agendash

Messages - AMQPBLIB

The under the hood framework for the messages is the AMQPBLIB

APM - Elastic APM Node

The muchas-toolkit supports the usage of the elastic-apm-node module, you must create a file named elastic-apm-node.js at the root of your application folder with the configurations as the elastic-apm-node explains. The APM will monitor all the supported technologies that the elastic-apm-node has and also creates custom metrics for the routines and messages actions.

Graceful Shutdown

If you send a SIGTERM or SIGINT to your application, muchas will perform a graceful shutdown, wait any on going route response, routine or message to be processed and then stops the application, if you wish to shutdown immediately you need to sen a SIGKILL signal. These is intended to help green/blue deploys, to avoid down time and package losses.

Healthz

Muchas has a built-in health endpoint that can be used to check the health of the application, useful if you are running in Kubernetes. Just go to http://localhost:8080/healthz, change the port according to your configuration.