iron-express v0.0.1

Iron-express

This project is based on Express framework. It exposes versioned Webservices used by the user watches, use ORM for PostgreSQL DBMS and build to exposes independent modules with the same data model and web modules architecture.

Webmodules design pattern

This project is design to have isolated modules in src directory, with the same code convention and architecture. For example, here a standard architecture for a module :

- commands/
- controller/
- services/
- validator/
- middleware/
- migrations/
- routes.json
- middleware.json

Routing

Each routes should be declared in routes.json in a module, here a classic structure of this file :

[{
  "prefix": "/module-prefix",
  "/travels" : [{
    "method": "GET",
    "validators": ["TestValidator"],
    "middlewares": ["security.TestMiddleware"],
    "version": 1,
    "action": "action"
  }]
}]

• version: default value: 1 . possible values: 1 , 1.x , 2, 2.x,3, 3.x .etc.
• controller: default file path: module/controller/Controller.js
• action: default value: V{version}(), for example, if version = 1, action = V1()
• method: default value: GET

Validators

Description: validators are used to check body/query parameters validation

How to create Validator:

• Add field "validators" in route.json of module.
• Create src/moduleName/validators/DemoValidator.js and fill your validator function.

[{
  "prefix": "/module-prefix",
  "/travels" : [{
    "method": "GET",
    "validators": ["DemoValidator"],
  }]
}]

Validator examples

xxValidator.js

case 1 of validator.js: object with query and body field

module.exports = {
  query: {
    airline: {
      schema: Joi.string().regex(/[A-Z\d]{2}/).required(),
      description: 'airline',
    },
    flightNr: {
      valueToValidate: req => req.query.flightNr || req.otherthings,
      schema: Joi.string().regex(/[A-Z\d]+/).required(),
      description: 'flight number',
    },
    departureDate: {
      schema: Joi.string().regex(/([2]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))/).required(),
      description: 'departureDate',
    },
  },
  body: {
      description: 'body desc',
      schema: Joi.array().items(Joi.object().keys({
        airline: Joi.string().regex(/[A-Z\d]{2}/).required(),
        flightNr: Joi.string().regex(/[A-Z\d]+/).required(),
      })),
      examples: [
          [
              { airline: 'AF', flightNr: '888' },
          ],
      ],
  },
};

• valueToValidate is a function that return the value you want to test in req, by default, if not set, value to validate will be req.query or req.body (depends on parent node)

case 2 of validator.js: a middleware funtion

module.exports = (req, res, next) => {}

case 3 of validator.js: Object with doc field and validator function field

module.exports = {
  doc: {
    title: "",
    description: "",
    schemaFormat: "",
    examples: []
  },
  validator: (req, res, next) => {}
}

Middleware

How to create Middleware:

• create src/moduleName/middleware.json
• create src/moduleName/middleware/Demomiddleware.js and then create your middleware

[
    {
        "route":"/firebase",
        "name":"Demomiddleware",
        "enable":false
    }
]

• route = "/firebase" means this middleware will be apply to apply to firebase module, if use / ,means apply to all modules
• enable decides if this middleware is activated

Example of setting middleware for single route

[{
  "prefix": "/module-prefix",
  "/travels" : [{
    "method": "GET",
    "middlewares": ["security.TestMiddleware"],
  }]
}]

Middleware examples

module.exports = {
  doc: {
    title: '',
    description: '',
  },
  middleware: (req, res, next) => {},
};

Shared Components

This shared components are defined as helpers and can be used globally with app.locals. It defines some constants and functions or classes :

// Constants
app.locals.src
app.locals.resources

// Helpers
app.locals.controller
app.locals.logger
app.locals.db

For example, to access db from controller, call it with app.locals.db. Each helpers are defined in lib directory and registered in utils/helpers.js

Cron jobs

For each web-modules, you can defined some recurring tasks simply by putting a cron.json file at the module root. File must be formatted like this :

[
  { "expression": "*/1 * * * *", "command": "command-name" }
]

command-name is referring to a file located at src/your-module-name/commands/command-name and expression follows UNIX cron format, if you are not familiar with this syntax there some cool tools like crontab generator to get expression.

Note 1 : in heroku, cron are in a separated worker and cannot be scaled

Note 2 : if you want to run a command in development, you can use iron cli and the command yarn iron module:command <module> <command>

iron-cmd

There is a cli called "iron-cmd" which has some usefull commands for development and debug purposes. Run it with npx iron-cmd command, here is the list of some available commands :

module:command <module> <command>  Run a specified command for a module