@kaiserleap/raven v2.0.6

Raven

Build common blocks and files insanely faster!

Ho does it work?

General working principle

We use pre-built (.txt) templates and components to be copied from our library, get some modifications based on your answers to the CLI prompt, 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

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

• 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 example@email.com --pass xxxxxx

Start using the project

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

• Build the initial example:
  raven build

• Run the project:
  npm run dev

Now you're ready to go!

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:

Options

Example

{
    "project": {
        "framework": "nest.js",
        "name": "Raven Project",
        "version": "1.0.0",
        "outDir": "./src",
        "debugger": false
    }
}

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

Options

Example for the tables

{
    "tables": {
        "item": {
            "name": {
                "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": {
        "UserRole": ["admin", "owner", "employee", "customer"]
    }
}

The services section

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

Options

Example

{
    "services": {
        "mailer": true,
        "aws": 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

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"
        }
    }
}

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.

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

Future Updates

• MongoDB will be available to use

Full APIs

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

• The description of the column is an optional string

• The defaultValue of the column is an optional string

Strings Validations

Numeric Validations

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

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": {
        "UserRole": ["admin", "owner", "employee", "customer"]
    }
}

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