Raven

Build common blocks and files insanely faster!

How does it work?

General working principle

We use pre-built (.txt) templates and components to be copied from our library, get some modifications based raven config file contents & your answers to the CLI prompt questions, and finally pasted as (.ts) files into your project.

Cloning and Injection

We have 2 processes to complete the previously mentioned action, cloning and injection. The tool clones the (.txt) files and replaces the placeholders with the given processed answers before the're placed in the given location. Then it injects some blocks of code in different files so you don't need to modify ANYTHING.

Before starting

Comments

You'll notice some comments in the generated files. We use those to locate the place in the code where the new blocks should be injected. Therefore, you can only remove them after you finish using the tool to build the blocks.

Placeholders

You might also notice some placeholder variables or values written in an uppercase format (e.g: FIELD_NAME). TypeScript will notify you about them (since they're not defined). You can change those whenever you want since their purpose is just to let you know about the options without causing runtime errors.

Versions

Make sure to have the exact versions for your installed libraries corresponding to each framework to avoid unexpected errors due to the constant updates on the libraries.

Nest.js

| Library | Preferred used version | | ------------------------ | :--------------------: | | @nestjs-modules/mailer | 2.0.2 | | @nestjs/common | 11.0.1 | | @nestjs/config | 4.0.0 | | @nestjs/core | 11.0.1 | | @nestjs/jwt | 11.0.0 | | @nestjs/platform-express | 11.0.9 | | @nestjs/serve-static | 5.0.2 | | @nestjs/swagger | 11.0.3 | | @nestjs/schedule | 6.0.0 | | @nestjs/typeorm | 11.0.0 |

Getting started

Installation

• Install nest-cli globally:
  npm install -g @nestjs/cli

• Install raven globally:
  npm install -g @kaiserleap/raven

• Create a new project:
  nest new project-name
cd project-name

Set up your credentials (this is currently disabled due to technical concerns)

• You need to provide a valid credentials for the tool to work, you can use these temporary credentials during the development phase of the project to use the app for the moment. Run the following command:

Note that in order for Raven to work, you need to provide credentials to the cli (use any dummy credentials for now since the tool is in its MVP phase)

raven login --email [email protected] --pass xxxxxx

Commands API

The init command

Install the recommended dependencies in your project if they're not yet installed. These are different from the ones installed using nest new command by default.

It also initialize the raven config file raven.config.json at the root of your project which will have the entire structure of your backend.

Usage: raven init

The list of dependencies

"@nestjs/config"
"@nestjs/typeorm"
"@nestjs/platform-express"
"@nestjs/serve-static"
"@nestjs/swagger"
"class-validator"
"class-transformer"
"express-session"
"typeorm"
"mysql2 "
"pg"
"uuid"
"bcrypt"
"fs"

The list of dev-dependencies

"@types/multer"
"@types/bcrypt"
"prettier"

The build command

This is the main and most important command in the system, it removes the default out directory ./src and rebuild it from scratch. It uses the specifications provided in the raven.config.json to do the following:

• Build your tables, columns, relations, validators, and enums.
• Utilize your env section to validate your .env file.

Start using the project

• Install the recommended dependencies and get the initial dev-kit:
  raven init

• Duplicate empty .env.example into .env
  cp .env.example .env

• Build the initial example:
  raven build

• In your code editor, replace all './src/' with 'src/'. We are working to fix this error automatically, but for now you need to fix manually as stated

• Duplicate populated .env.example into .env
  cp .env.example .env

• Rename main branch into prod this is essential for github workflows to function git branch -m prod

• Run the project:
  npm run dev

Now you're ready to go!

Database is already seeded with an admin user with credentials found in swagger login api example

The Raven Config File

Raven works by reading a file at the root of your project named raven.config.json, and turn its instructions to actual code (files and directories). This file contains the structure of your entire project where your can control the resultant code using the json contents.

The config file consists of the following sections:

The project section

This sub-json contains basic info about your project:

'Project' Options

| Key | Description | Type | | --------- | ---------------------------------------- | --------------------------------------------- | | framework | The currently used framework | Supported values: nest.js | | name | The name of your project | String value | | version | The current version of your project | String value follows versions format: 1.0.0 | | outDir | The destination directory of the project | String value | | debugger | Activate/Deactivate the debugging mode | Boolean value |

'Project' Example

{
    "project": {
        "framework": "nest.js",
        "name": "Testing Project",
        "version": "1.0.0",
        "outDir": "src",
        "debugger": false,
        "database": "postgres"
    }
}

The schema section

This sub-json is the core of your system, it is the one responsible for building your database schemas.

Check the full API list for the schema section at the bottom of this page

'Schema' Options

| Key | Description | | --------- | -------------------------------------------- | | tables | Contains the tables, columns, and validators | | relations | Contains relations among tables | | enums | Contains the enums using in the columns |

Example for the tables

{
    "tables": {
        "tableOneName": {
            "propertyOneName": {
                "type": "string",
                "description": "",
                "defaultValue": "",
                "validations": {
                    "isRequired": true,
                    "maxLength": 25
                }
            }
        }
    }
}

Example for the relations

{
    "relations": ["order<>item", "user>item", "user-profile"]
}

Example for the enums

{
    "enums": {
        "enumOne": ["valueOne", "valueTwo"] // camel case strings
    }
}

The services section

This sub-json controls the activation state of the optional services across the project:

'Services' Options

| Key | Description | | ------------------------- | ----------------------------------------------------------------------------- | | mailServiceIntegration | Activate the mailing service to enable your project to send emails | | dockerizeApp | Build the codes to dockerize the backend app & include dockersized DB |

'Services' Example

{
    "services": {
        "mailServiceIntegration": true,
        "dockerizeApp": true,
    }
}

The env section

This sub-json is reserved to store the keys in the env file needed for the project. When you change them from the config file, the keys will be changed in both the app and the env file.

Note that we only control the keys here, you need to change the values manually from the .env file because the config file can't contain sensitive data since it will be pushed to the repo.

Options

| Key | Env keys for | | -------- | ---------------------------------------------- | | swagger | The swagger implementation | | jwt | The JWT encryption specifications | | database | The database credentials and specifications | | mailer | The mailing service credentials | | aws | The AWS service credentials and specifications |

Example

{
    "env": {
        "swagger": {
            "allowedUrls": "FRONTEND_URLS",
            "url": "ENVIRONMENT",
            "port": "PORT"
        },
        "jwt": {
            "secret": "JWT_SECRET"
        },
        "database": {
            "host": "DATABASE_HOST",
            "port": "DATABASE_PORT",
            "user": "POSTGRES_USER",
            "password": "POSTGRES_PASSWORD",
            "name": "POSTGRES_DB"
        },
        "mailer": {
            "email": "OFFICIAL_EMAIL",
            "password": "OFFICIAL_EMAIL_PASSWORD",
            "provider": "MAILER_SERVICE_PROVIDER"
        },
        "aws": {
            "accessKey": "AWS_ACCESS_KEY",
            "secretKey": "AWS_SECRET_ACCESS_KEY",
            "region": "AWS_REGION",
            "bucketName": "S3_BUCKET_NAME"
        }
    }
}

Check our detailed docs of how you can use the tool from here:

The tables Section

This sections defines the names of teh tables and columns for the schema. It also defines the specifications and validations for each column. Most types of fields are supported.

Tables listing and naming

You must list your tables' using their names as a series of keys inside the main sub-json tables, where the value of each key will have the table's columns.

You must name your tables in snake_case format using only alphabetic letters.

{
    "tables": {
        "user": { ... },
        "item": { ... },
        "team_member": { ... },
        "order": { ... }
    }
}

Columns listing and naming

You must list your columns' using their names as a series of keys inside the related sub-json for their table, where the value of each key will have the column's specification and validations.

You must name your columns in snake_case format using only alphabetic letters.

{
    "tables": {
        "user": {
            "first_name": { ... },
            "last_name": { ... },
            "email": { ... },
        }
    }
}

Columns specification and validations

Specification

• The type of the column can be one of these:

  • string
  • enum
  • number
  • array
  • object
  • date
  • time
  • boolean
  • file

• The description of the column is an optional string

• The defaultValue of the column is an optional string

Any Column Validations

| Key | Type | Description | | ------------- | ------- | ------------------------------------------------------------------ | | isRequired | boolean | If true, the will be considered as required (can't be null) | | isUnique | boolean | If true, the values must all be unique (no duplications) | | minLength | number | If set, the value must contains at least this number of characters | | maxLength | number | If set, the value must contains at most this number of characters |

String Validations

| Key | Type | Description | | ------------- | ------- | ------------------------------------------------------------------ | | isEmail | boolean | If true, the value must be an email-like string | | isUrl | boolean | If true, the value must be a url-like string | | isLatLong | boolean | If true, the value must be a coordinations-like string | | isPhoneNumber | boolean | If true, the value must be a phone-number-like string | | enum | string | If set, the value must be one of that enum's values |

Numeric Validations

| Key | Type | Description | | ------------ | ------- | ----------------------------------------------------------- | | isDecimal | boolean | If true, the value must be decimal | | isInteger | boolean | If true, the value must be an integer | | isPercentage | boolean | If true, the value must be a percentage (value from 0 to 1) | | min | number | If set, the value must be at least this number | | max | number | If set, the value must be at most this number |

Example

{
    "tables": {
        "user": {
            "first_name": {
                "type": "string",
                "description": "The user fist name",
                "defaultValue": "my value",
                "validations": {
                    "isRequired": true,
                    "maxLength": 25
                }
            }
        }
    }
}

The relations Section

This section creates relation between the defined tables in the tables section. All types of relations are supported.

The relation is set by combining the two related tables names separated by a string annotating the relation type.

Relations Types

| Relation | Separator | Example | Meaning | | ------------ | :-------: | -------------- | ------------------------------------------------------------------------------- | | One-To-One | - | user-profile | Each user can only have one profile | | One-To-Many | > | user>item | Each user can have multiple items | | Many-To-Many | <> | order<>item | Each order can have multiple items, and each item can belong to multiple orders |

Example

{
    "relations": ["order<>item", "user>item", "user-profile"]
}

The enums Section

This section declares the enums you want to add to your columns. Any linked enum will add a validation to its column upon creating or updating any related record in the database.

You must list your enums using their names as a series of keys inside the related main sub-json for enums, where the value of each key will have an array of strings representing the possible values for each enum.

The names of each enum object must be in PascalCase format and each value must be in snake_case format using only alphanumeric letters

Example

{
    "enums": {
        "enumOne": ["valueOne", "valueTwo"] // camel case strings
    }
}

Specifications

Directories

• The main file is supposed to be located at the root ./main.ts
• The default used app directory is ./src/
• Inside the app directory, we have organized and grouped directories for each section:
  • schemas
  • dto
  • enums
  • entities
  • decorators

Naming

• The naming convention for all generated files is as follow:
  [name].[type].ts
• Examples:
  • app.module.ts
  • users.controller.ts
  • user-role.enum.ts
  • user.validator.ts
  • create-user.dto.ts

Limitations

Language

Currently, the tool only generate codes in TypeScript

Database

Currently, the only available database is PostgreSQL

Storage

Currently, the only available storage integration option is AWS S3 Bucket

Common Errors

raven doesn't have permission on your terminal

• Open your terminal (steps for Ubuntu terminals)

• Open the .bashrc file using either VSCode or the terminal itself:

  • either: code ~/.bashrc
  • or: nano ~/.bashrc

• Provide permission to run raven by adding the following line at the end of the file (after replacing the uppercase words with yours): chmod +x /home/YOUR_USERNAME/.nvm/versions/node/YOUR_NODE_VERSION/bin/raven

Future Updates

• To optionalize some of current features will be available to use
• Other DB Options will be available to use
• Other Storage Integration Options will be available to use
• Other Backend Framework Options will be available to use
• System Admin Panel will be available to use
• Auto generated comprehensive tests will be available to use
• Auto generated demo / development data seeders will be available to use
• Auto generated demo mode will be available to use
• Auto generated project technical documentation will be available to use
• Optional user-activity tracking feature will be available to use
• Optional DB / responses localization will be available to use
• Optional multi-tenant feature will be available to use
• Optional micro-service architecture implementation feature will be available to use

Development Team / Collaborators

• Mustafa Hasanat Creator
• Suhaib Ahmad Main Contributor