Beta Release

---

Official VES Documentation

Master-branch: Develop-branch:

VNATK

VNATK is a set of client and server frameworks set to get your work started ASAP, Trying to be most Rapid system with total customization in hand.

VNATK is developed to keep the following few points in mind

• Most of the time we spend time in creating trivial APIs, that actually are identical with different models.
• we all know how tesdius it is to do maintenance of any project specially when client/company is ever changing their requirements. By looking at those issue I was missing somehting that really is fast, really RAPID APPLICATION DEVELOPMENT (RAD) framework.

VNATK-EXPRESS-SEQUELIZE is implementation of Sequelize-QL (my coined term ;) ) (Given name as per Graph-QL) that can be used as independent tool to ease your API development.

The main purpose though to develop VNATK-EXPRESS-SEQUELIZE is to provide API-Less server system for VNATK framework. It works in combination with its counter front part like VUEATK-VUE [https://github.com/gowrav-vishwakarma/vnatk-vue]

VNATK-EXPRESS-SEQUELIZE (Backend with Express and Squelize)

---

Equipped with a few endpoints that gives you all power with Sequalized-QL developed and defined by this project only.

This express middleware will give all the fule required from server to VNATK Frontend Frameworks. And this can also be used as independent API provider (inspired from Graph-QL).

Dependencies: body-parser, debug, dotenv,lodash, sequelize and your sequlize dialect

Step 1.0: setup express app

Considering we are in "Your Project Root Folder"

lets create express app (Server/service) from scratch, you are welcome to use any other way or manual if you know what you are doing

1### FOR NEW SERVICE SETUP
2
3#install express-generator globally, its easy to do setup with this
4$yourProjectRoot> npm install -g express-generator
5...
6$yourProjectRoot> express server --no-view
7...
8#lets check if a folder with server name created or not
9$yourProjectRoot> ls
10server
11
12#a default structure is also created in this folder
13$yourProjectRoot> ls server
14app.js       package.json routes    bin          public
15
16$yourProjectRoot> cd server
17
18#lets install basic things setup by express-generator
19$yourProjectRoot/server> npm install
20
21#install our dependencies now
22$yourProjectRoot/server> npm install --save bcrypt body-parser cookie-parser express-handlebars jsonwebtoken morgan cors dotenv lodash mysql2 sequelize vnatk-express-sequelize
23
24### If required vnatk-express-sequelize can be installed in existing express seuelize setup also with very ease
25
26#install sequelize cli for easy sequlize setup
27$yourProjectRoot/server> npm install --save-dev sequelize-cli
28$yourProjectRoot/server> sequelize init
29

sometimes sequelize have issues in reading models from file like this specially if your sequlize cli is old and you are using seulize v6, in case of that, you may get sequelize import method error.

replace following line in that case

1// replace following line 
2const model = sequelize['import'](path.join(__dirname, file));
3//  to this line
4    const model = require(path.join(__dirname, file))(sequelize, Sequelize.DataTypes)

Step 2.0: configure and use vnatk-express-sequelize

Please add the following code in your app.js file. (DON'T COPY PASTE WHOLE CODE, ITS NOT FULL FILE CODE)

app.js

1// somewhere on the top after 
2// var express = require('express'); <= after this line
3var cors = require('cors');
4const bodyParser = require('body-parser');
5const vnatk = require('vnatk-express-sequelize');
6...
7...
8// You can already have body-parser added, no need to add again
9app.use(bodyParser.json());
10app.use(bodyParser.urlencoded({extended: true }));
11
12// add cors is a good way and mostly you might need this also
13app.use(cors()); // Use this after the variable declaration
14
15var VnatkRouter = require('./routes/vnatk.js');
16app.use('/vnatk', VnatkRouter); // '/vnatk' is called basepath here
17

Now create a new file to export Vnatk Routes routes/vnatk.js

1var express = require('express');
2var router = express.Router();
3const vnatk = require('vnatk-express-sequelize');
4
5// Optional to use some auth middleware on this route
6//router.use(require('./middleware/adminTokenChecker'));
7
8const Models = require('../../models');
9module.exports = vnatk({ 
10    Models: Models,
11    router: router
12});
13

Step 2.1: setup Models

Create models in models folder. For more about Models in sequlize please follow sequlize documentations.

Let's have a sample model. Please read Model comments as documentation. Some properties and methods are specific to VNATK-Frontend here, feel free to skip if using only vnatk-express-sequelize for API only.

1'use strict';
2const { Model } = require('sequelize');
3
4module.exports = (sequelize, DataTypes) => {
5  class User extends Model {
6    static associate(models) {
7      // define association here
8      // City and State Models must be created in same manner in models folder also
9      User.belongsTo(models.City, { foreignKey: 'city_id' });
10      User.belongsTo(models.State, { foreignKey: 'state_id' });
11
12    }
13    
14    // Functions that will be called on loaded model
15    // In other way of sequlize you define instance variable as 
16    // sequelize.prototype=function () { ... }
17    deActivate(args) {
18      this.status = 'InActive'
19      return this.save().then(self => {
20        return self;
21      })
22    }
23
24    activate(args) {
25      this.status = 'Active'
26      return this.save().then(self => {
27        return self;
28      })
29    }
30
31    block(args) {
32      this.status = 'Blocked'
33      return this.save().then(self => {
34        return self;
35      })
36    }
37
38  }
39
40  // This init method is defined by 'define' method in other sequelize ways. technically its same ...
41
42  User.init(
43    {
44      name: {
45        type: DataTypes.STRING,
46      },
47      email: {
48        validate: { isEmail: true },
49        type: DataTypes.STRING,
50        defaultValue: 'guest@example.com'
51      },
52      mobile: {
53        type: DataTypes.STRING,
54        validate: {
55          isNumeric: {
56            msg: 'Mobile number can only contains number',
57            args: true
58          },
59        },
60      },
61      password: {
62        type: DataTypes.STRING,
63      },
64      status: DataTypes.ENUM('Applied', 'Active', 'InActive', 'Blocked'),
65      createdAt: {
66        type: DataTypes.DATE,
67        field: 'created_at'
68      },
69      updatedAt: {
70        type: DataTypes.DATE,
71        field: 'updated_at',
72      }
73    },
74    {
75      sequelize,
76      modelName: 'User',
77    }
78  );
79  return User;
80};

thats it... Start using the API at ease if not using VNATK-VUE or let's setup Vue frontend now, please follow VUEATK-VUE [https://github.com/gowrav-vishwakarma/vnatk-vue]

API Basics

NOTE: ALL APIs in Sequlize-QL are POST APIs

vnatk-express-sequlize provides two APIs

• {base_path}/crud (POST) This API is used to read data, DON'T GET CONFUSED with CRUD Name, this API DO NOT Create., Update or Delete. Instead, the API do provide infromation about Create, Update, Delete and Actions to work in combination with VNATK-VUE Fronetnd.

• {base_path}/executeaction (POST) This API is responsible for various actions includeing Create, Update, Delete and Other Methods on Models.

{base_path}/crud options

Options for API only

Option	Type	Default	Description
model	String	null	Model name to work on, [Mendatory]
read	JSON	{}	options for read operations, [Optional]
read.modeloptions	JSON		Options to pass to your model define above
read.modelscope	String|false		false to use unscoped model and avoid any default scope applied on model, or use define scope to use as string
read.autoderef	Boolean	true	Try to solve belongsTo relation and get name/title of related field ie cityId to City.name (Auto includes)
read.headers	Boolean	true	Sends headers infor about fields included for UI processing, Mainly used by VNATK-VUE, you can set to false is only using APIs.
actions	Boolean	true	Sends Actions applicable including Create, Update and Delete and their formschema, set to false if using in API only mode.

There are more rich set of options applicable when using with VNATK-VUE. To know more about those options pls follow VUEATK-VUE [https://github.com/gowrav-vishwakarma/vnatk-vue]

{base_path}/executeaction options

Option	Type	Default	Description
model	String	null	Model name to work on, [Mendatory]
read	JSON	{}	options for model to be used to apply action on, [Optional]
read.modeloptions	JSON		Options to pass to your model define above
read.modelscope	String|false		false to use unscoped model and avoid any default scope applied on model, or use define scope to use as string
action_to_execute	String	null	Action to perform on defined model supported default actions are - vnatk_add: pass arg_item data to create a new record of given model. - vnatk_edit: pass arg_item data to edit model record, arg_item must have primary/autoincrement value availabe, model will be loaded by that value and all other values passed will be updated on model. - vnatk_delete: pass arg_item data to delete model record, arg_item must have primary/autoincrement value availabe, model will be loaded by that value and then destroys. - {Any User Defined Method Name}: pass arg_item data to your method defined in Model class/declatation. Actions retuns data of added/edited/deleted item, but in any case modeloptions contains some condition that is changed due to editing, null is returned instead
arg_item	JSON	null	Argument passed for your action, for vnatk_edit and vnatk_delete actions, arg_item must have id or your primary key value to pick correct record, while for vnatk_add action data passed will be used to create fill in model.create.

---

Changes in read.modeloptions from standard Sequlize model options

1{
2  model:'User',
3  read:{
4    modeloptions:{
5      attributes:['name','age'],
6      include:[
7        {
8          model:'City', 
9          as:'MyCity',
10          scope:false // <== or String to modify City model with unscoped or scope defined by this string
11        }
12      ],
13      where:{
14        age:{
15          $lt: 18 // <== operator aliases defined in config.js file
16        }
17      }
18    },
19    modelscope:false // <== false for unscoped User or String for scope name for User model
20  }
21}

Safety and Security

---

VNATK-EXPRESS-SEQUELIZE, while provide you endpoints to do almost anything without writing code,also provides you three levels of access controls

• By providing access token checker middelware

Example: As given in setup section to use auth middelware

• Providing whiteList/Blacklist models

Example: in your vnatk routes file plass options as follows

1var express = require('express');
2var router = express.Router();
3const vnatk = require('vnatk-express-sequelize');
4
5// Optional to use some auth middleware on this route
6//router.use(require('./middleware/adminTokenChecker'));
7
8const Models = require('../../models');
9module.exports = vnatk({ 
10    Models: Models,
11    router: router,
12    // allow only following models
13    whitelistmodels:['Products','Cart'],
14    // do not allow following models
15    blacklistmodels:['Orders','Payments']
16});
17

• Providing each actions authorization function in model itself

Example

Each action checks for can_{action} function in model, if found, the function is called by passing request object. on receiving === true only then the related action is executed.

three default actions for basic crud options are vnatk_add, vnatk_edit and vnatk_delete. To make authorization related to these actions you may created can_vnatk_add, can_vnatk_edit and can_vnatk_delete function in models respectiley.

Under development: Authorization and ACL based on each Model or record is under development