Skip to content

Latest commit

 

History

History
384 lines (337 loc) · 11.3 KB

README.md

File metadata and controls

384 lines (337 loc) · 11.3 KB
Raw

Welwit Framework

Angola API License

Welwit is an CLI Framework based API and ORM builder, made to automate API development and database modeling. Supports costum route creation, code generation, automated scripts and much more. Currently in alpha development, check the section #roadmap for more details.

Overview

Note:This is an detailed explanation of the program. For quick setup skip to last session <3 .


There are 3 main options for API-GRAN to use, server, generate and database.

Server

The server mode generate an full server within just two files, the first contains the database configuration, and the second all the tables you might want to include (not required at all). For the server you just need to configure an file, call it any name you want, but .gra is cool to :) .

Base configuration file:

    server={
        "ip" : IP,
        "port" : PORT,
        "orm" : DATABASE_ORM,
        "database" : DATABASE
    };

Where:

Option Explanation Example
IP Your machine ip 127.0.0.1
PORT Database port 3306
ORM ORM to use sequelize
DATABASE Database name to use my_database

Example, config.txt contains the following:

server={
    "ip" : "127.0.0.1",
    "port" : 3306,
    "orm" : "sequelize",
    "database" : "my_database"
};

There are more options fo include in the config file,and can be added as it follows, separed by ; (example):

option1={
    "value1" : "foo",
    "value2" : "bar",
};
option2={
    "value1" : "foo",
    "value2" : "bar",
};
option3={
    "value1" : "foo",
    "value2" : "bar",
};

The second file contains all the database you want to include for the API, also the routes. The basic structure looks like: 
    table_name={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    };
Multiple tables can be included tho: 
    table1={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    };
    table2={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    };
    table3={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    };
Since you're building an API, you might want to specify the routes where those tables will interact with the user, put your path inside "<>" as the example: 
    table1={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    }</v1/login>;
    table2={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    }</v1/register>;
    table3={
        FIELD1 : TYPE,
        FIELD2 : TYPE,
        FIELD3 : TYPE,
    }</v1/post>;
API grandma will automatically create the GET and POST router for the tables, no REST support is currently implemented (in development).

Table Tutorial

Base

The following is an example of a table:

login={
    id : INT~20-PK-AI,
    user : STR~20,
    password : STR~20
}</v1/account>;

How it works? The parser will identify the field type and the special attributes and add automatically to the code being generated.

In detail, the first line id : INT~20-PK-AI is splited with "-" to:

[
    "INT~20",
    "PK",
    "AI"
]

The code is translated as (SQL like) command: id INT(20) primary key auto_increment "INT~20" is:

  • INT -> Datatype, INT
  • 20 -> Field lenght
PK, AI are translated to "primary key" and "auto_increment", resulting to this SQL statement for the "login" table:
create table login( id INT(20) primary key auto_increment, user varchar(20), password varchar(20) );

And that is! You finished the basic setup. For complete overview of the table generation methods, check the examples above.

Table definition and examples

Basic table creation

table_name={
    field1 : type,
    field2 : type,
    field3 : type,
    field(n) : type(n)
}</api/path/here>;

Multiple tables

document={
    id : INT~20-PK-AI,
    number : STR,
    date : DATE,
    region : STR~10
}</v1/document>;
account={
    id : INT~20-PK-AI,
    name : STR~20,
    country : INT~20
}</route/account>;

Ok, whe have the base server and table config files. Building will be like:

node app.js --server --input=server.txt --tables=tests/input/test1.txt --orm=sequelize --output=tests/output/

Where

    --server         -> Server mode
    --input=         -> Server config file
    --tables=        -> Tables config file
    --orm=           -> Prefered orm (if not specified, sequelize will be used)
    --output=        -> Path to output

And then, there is the terminal output:

Then, run "npm install " to install it localy inside the project output. If you specified Sequelize, run "npm install sequelize". Note: mysql2 may be required for sequelize or another in your generated project, run "npm install mysql2" to fix it.


Finally, start the app via "node app.js" and have fun :) <3>. ### Generate

Creates base server, in development...

Note: "--database --input=tables.txt" is equivalent to "--tables=tables.txt", the main difference is their purpose, since option1 is for simple database/table generation and option2 is for database/table generation along with server routes, and tests. Avoid using then at the same time! Recomended: output to 'output' folder with different dirs.

node app.js --generate --input=input.txt --output='output/myapp/'

Database

This option only generates the database tables. The table setup is the same, but uses differents params. (in development, do not use yet)

node app.js --database --orm=sequelize --input=input.txt

Quick setup

Create two files, one called config.txt and another tables.txt.
Insert code bellow into config.txt:

server={
    "ip" : "127.0.0.1",
    "port" : 3306,
    "orm" : "sequelize",
    "database" : "book_store"
};

Note: create an database named book_store first.
And for tables.txt:

    book={
        id : INT~20-PK-AI,
        name : STR~20,
        author : STR~20,
        creation : DATE
    }</v1/book>;
    client={
        id : INT~20-PK-AI,
        name : STR~20,
        age : STR~20
    }</v1/client>;

Create an tests folder with the structure:

  • tests
    • input
    • output

Save the files to tests/input and execute the following code from grandma:

    node app.js --server --input=tests/input/config.txt --tables=tests/input/tables.txt --orm=sequelize --output=tests/output/

Move to the tests/output dir, open the terminal and type:

    npm init -y
    npm install sequelize
    npm install mysql2 # may be required
    npm install

    Depending of your os, you may run:

    ./start.bat        # windows
    sh start.sh        # linux

    Finally

    node app.js

POST requests to send
1 POST /v1/book HTTP/1.1 Host: 127.0.0.1:9999 Content-Type: application/x-www-form-urlencoded

id=0&name=StrangerThings&author=Homer Simpson&creation=12/12/2021
2 POST /v1/book HTTP/1.1 Host: 127.0.0.1:9999 Content-Type: application/x-www-form-urlencoded

id=0&name=Javascript Hell&author=Devil&creation=12/12/2021
3 POST /v1/book HTTP/1.1 Host: 127.0.0.1:9999 Content-Type: application/x-www-form-urlencoded

id=0&name=Made by Angola&author=Heber Julio&creation=12/12/2021 GET request: GET /v1/book HTTP/1.1 Host: 127.0.0.1:9999

Meaning and convections

API GRANDMA SEQUELIZE
INT INTEGER
STR STRING
PK PRIMARY KEY

Supported ORMs

Database CRUD PrimaryKeys 1:1 1:n n:n Status Experimental Production
Sequelize Yes No No Yes Incomplete No Yes Basic API

Roadmap (not ordered)

  • Fix bug about primary key not being filled [Done]
  • Typescript migration
  • Code refactoring and review
  • Add support to TypeORM and more databases
  • Add option to use mysql or mongodb (anything excepto than ORM)
  • Export some functions to classes
  • Bug fix for directy creation (mitigated with app executed twice) [Done]
  • Add more options to create API
  • REST support
  • Export API following Software Principles and convections (SOLID, MVC, MVP and so on)
  • Upgraded parser
  • Better documentation

Work with me

My social media