@moccacoders/node-obremap

OBREMAP - Node ORM

OBREMAP Node ORM is an Object-Relational Mapping tool for Node JS based on the famous ORM of Laravel, Eloquent ORM. OBREMAP provides a beautiful and simple ActiveRecord implementation to work with your database. Each database table has a corresponding "OBREMAP Model" that is used to interact with that table. Models allow you to query data in your tables, as well as insert new records into the table.

Before starting, make sure you configure your databases correctly. For more information on database configuration, see the database configuration.

HOW TO INSTALL?

// Use this with NPM
$ npm install @moccacoders/node-obremap --save
// or this wiht YARN
$ yarn add @moccacoders/node-obremap

// if using mysql driver this is peer dependency anyway
npm install mysql@latest --save
//If using MongoDB drive
npm install mongodb@latest --save

DATABASE CONFIGURATION

With OBREMAP Node ORM you have many ways to configure your databases. The first is by adding your databases to your environment variables (most recommended) or using the configuration file obremap.config.js.

-> Environment Variables

To configure your databases you must define the following variables:

DB_DRIVER="mysql"
DB_HOST="127.0.0.1"
DB_USERNAME="username"
DB_PASSWORD="password"
DB_NAME="database_name"

-> OBREMAP Configuration File

Another way to add databases connection you can use the OBREMAP configuration file, this will allow you to configure your databases independently.

What you should do is create a file with the name obremap.config.js in the root folder of your application and add the following basic configuration.

• It is important to add the default key to the database configuration, as this will be the main information that will be used for the connection. If the database connection with the name "default" is not defined, you will have to indicate which database you are going to use.

module.exports = {
  databases: {
    default: {
      // IMPORTANT ADD "DEFAULT".
      // THIS WILL BE THE MAIN CONNECTION INFORMATION
      host: "localhost",
      user: "user",
      password: "pass",
      database: "database_name",
      port: 3306,
      driver: "mysql",
    },
  },
};

Configuration using URL's

Commonly, database settings use multiple settings such as host,database, username, password, etc. Each of them corresponds to an environment variable. This means that when you configure your databases on your production server, you will have to handle many environment variables.

Many of the database services provide a single database connection "URL", which contains all the necessary information for the connection in a single string. An example of data-giving URLs looks very similar to this:

mysql://root:password@127.0.0.1/forge?charset=UTF-8

These URLs usually follow a standard schema convention:

driver://username:password@host:port/database?options

For your convenience, OBREMAP Node ORM supports these URLs as an alternative to configuring their databases with multiple configuration options. That is, if a database configuration URL is found (or its corresponding DATABASE_URL environment variable) it will be used to extract the database connection and credential information.

-> ENVIRONMENT VARIABLES

DATABASE_URL="mysql://root:password@127.0.0.1/database_name"

-> OBREMAP CONFIGURATION FILE

The configuration is similar to the previous one. Only instead of saving an object within the default configuration, you should add the URL as a string.

module.exports = {
  databases: {
    default: "mysql://root:password@127.0.0.1/database_name",
  },
};

Configuration of multiple databases

OBREMAP Node ORM provides the possibility of making multiple connections to multiple databases. You have no limit in terms of connections, you can configure all the connections you need, all the databases you require. The configuration is similar to what was seen previously.

-> Environment variables

To configure multiple connections using the environment variables OBREMAP Node ORM take all the variables with the prefix DB_ and assign the following value as the configuration variable. So if you define DB_HOST this will be the main configuration variable default that contains the database hostname. However, if you define an identifier after the DB_ prefix, it will be taken as the connection name, it must be followed by the name of the connection variable, example: DB_LOCAL_HOST in this case the connection name will be local and the connection variable will be host.

// MAIN CONNECTION
DB_DRIVER = "mysql";
DB_HOST = "127.0.0.1";
DB_USERNAME = "user";
DB_PASSWORD = "pass";
DB_NAME = "database_name";

// SECONDARY CONNECTION NAMED LOCAL
DB_LOCAL_DRIVER = "mysql";
DB_LOCAL_HOST = "localhost";
DB_LOCAL_USERNAME = "loca_user";
DB_LOCAL_PASSWORD = "local_pass";
DB_LOCAL_NAME = "other_database";

-> OBREMAP configuration file

Just as you can configure multiple connections to the database with a small modification in the environment variables, you can also do it using the OBREMAP configuration file the only thing you will have to do is add one more element to your object databases, taking into account that the name you give to the new element will be the name of your connection.

module.exports = {
  databases: {
    // MAIN CONNECTION
    default: "mysql://root:password@127.0.0.1/database_name",
    // SECONDARY CONNECTION NAMED LOCAL
    local: "mysql://loca_user:local_pass@localhost/other_database",
  },
};

Select database

Once you have configured your multiple databases, what you should do is indicate to the model which connection to use. And this is only done by adding a static method within your model. Remember that the name you put here is the name you gave your connection in the multiple database connection settings.

import { Model } from "@moccacoders/node-obremap";

class Chat extends Model {
  static connection = "local";
}

export default new Chat();

Create a Model

To begin, we will create a Obremap Model. Models are usually found in the root folder inside the MODELS folder, however you can place them where you prefer, as long as you can access them. All OBREMAP Models must extend from the Model class within @moccacoders/node-obremap pack. The easiest way to create your models is using the Obremap CLI with the obremap make: model function

// chat.js

import { Model } from "@moccacoders/node-obremap";

class Chat extends Model {
  /*
    overwrite table name, this is optional
    static tableName = 'dashboard_chats';
  */
}

export default new Chat();

Using the Model

Once you have created the OBREMAP Model (and associated the database table correctly), you are ready to get data from your databases. Think of OBREMAP Models as efficient way to help you make your queries easly and efficient.

Example:

import Chat from './chat'

async function getChats {
  let chats = await Chat.all()
  console.log(chats)
}

Supported methods

• .all() Returns everything in the table
• .count() Returns a numerical value corresponding to the total number of records extracted
• .create({field: 'value'}) Create a new record
• .delete(where || <primary key>) Unregister
• .find(<primary key>) Find and return a relation currently only id since primary key is supported but dynamic primary key will be coming soon
• .first() Returns the first record
• .join(tableName, <local key>, <remote key>) Create joins between tables
• .limit(5) Limit the total results
• .offset(10) Defines the start of the search
• .orderBy('fieldName' || {fieldName:" asc "}) Returns the ordered results
• .select('column', 'column2') Defines the columns of the database to extract
• .update({field: 'value'}, where) Update a record
• .where({fieldName: 'value'}) Returns the results that match the expression

Query Building

Chat.all();

Chunk.count();

Chat.where({ messages: "blah" }).count();

Chat.create({ user_id: 23 });

User.find(1);

Chat.select("messages", "id").where({ messages: "blah" }).get();

Chat.where({ messages: "blah" }).get();

Chat.select("messages").first();

Chat.where({ messages: "blah" }).limit(2).get();

Chat.update({ name: "Raymundo" }, { id: 1 });

Chat.delete(1);

Relationships

This is a huge WIP, feel free to contribute :)

Supported:

• One To One
• One To Many

Todo:

• Many To Many
• Has Many Through
• Polymorphic Relations
• Many To Many Polymorphic Relations

One to One Example

import { Model } from 'node-obremap'


export default class User extends Model {

}

export default class Chat extends Model {
  user() {
    return this.hasOne(User)
  }
}

let chat = await Chat.first()

//any relationship will return a promise with the result
let user = await chat.user

expect(user.name).to.be.equal('Bob')

One to Many Example

import { Model } from 'node-obremap'


export default class User extends Model {
  chats() {
    return this.hasMany(Chat)
  }
}

export default class Chat extends Model {

}

let user = await User.first()

//has many results return a query builder instance
let chats = await user.chats.first()

CLI

By installing node-obremap globally (npm install @moccacoders/node-obremap -g) you can access CLI methods to help create models, connections, etc. and use the different creation wizards. They are currently in Spanish and English.

Methods

• obremap make:model <name> [options] Create a new Obremap Model Class.
• obremap make:connection <name> [options] Create a new Database Connection
• obremap make:migration <name> [options] Create a new migration file
  • obremap migrate [options] Execute all migrations
  • obremap migrate:reset [options] Rollback all database migrations
  • obremap migrate:refresh [options] Reset and re-run all migrations
  • obremap migrate:rollback [options] Rollback the last database migration
  • obremap migrate:refresh [options] Drop all tables and re-run all migrations
• obremap make:seeder <name> [options] Create a new seeder file
  • obremap seed [options]

Models

obremap make:model

It will initialize the Models creation wizard which will guide you in creating your model, requesting the necessary information for it. Additionally, and only if necessary, it will display the connection creation wizard. Creates a file in your current directory /models/user.js with a default model

Connections

obremap make:connection

It will initialize the Connections creation wizard which will ask you for the necessary information to create connections; It will also allow you to select between using the OBREMAP configuration file or your Environment Variables.

Migrations

obremap make:migration Create a migration file.

Seeders

obremap make:seeder Create a Seeder file.

Everything

• Add more Database drivers
• CLI
  • Add more functions
  • Add more languages
• Migrations

Contributing