woowahan-orm v2.0.1

woowahan-ORM

WoowahanORM is a very light promise-based Node.js ORM for MySQL. It features simple Model Queries(INSERT, UPDATE, SELECT, DELETE), Validations for Types and synchronization for Migration. WoowahanORM follows Semantic Versioning.

Installation

$ npm i woowahan-ORM
# Also need to install mysql2
$ npm i mysql2

API

const woowahanORM = require('woowahan-orm')

Connecting a Database

To connect to the database, you must passdown the connection parameters to the woowahanORM instance.

woowahanORM(connectionParams, options)

woowahanORM({
      host: process.env.DB_HOST,
      user: process.env.DB_USER,
      password: process.env.DB_PASSWORD,
      database: process.env.DB_NAME,
    },
    {
      sync: {
            force: false
      }
    }
)

options

Sync

• sync option not provided : no sync
• sync with force false : create tables if not exist
• sync with force true : drop and create tables

Defining a Table

After a connection is made, it is available to create Table Models extending WoowahanORM.Model

options

defaultWhere is automatically added to where when find calls are called.

Example

const { Model, DataTypes } = require('woowahan-orm')

class Product extends Model {
  static init() {
    return super.init(
      {
        name: { dataType: DataTypes.STRING, required: true },
        brandName: { dataType: DataTypes.STRING, required: true },
        isFeatured: { dataType: DataTypes.BOOLEAN, defaultValue: true },
      },
      {
        isFeatured: false,
      }
    )
  }
}

module.exports = User

id, createdAt, updatedAt, isDeleted are auto-generated for every Model.

id: { dataType: DataTypes.INTEGER },
isDeleted: { dataType: DataTypes.BOOLEAN },
createdAt: { dataType: DataTypes.TIMESTAMP },
updatedAt: { dataType: DataTypes.TIMESTAMP },

Supported Types

Currently Woowahan ORM supports and validates those DataTypes.

BOOLEAN: "tinyint(1)",
INTEGER: "int(11)",
DATE: "date",
DATETIME: "datetime",
TIMESTAMP: "timestamp",
STRING: "varchar(255)",
TEXT: "text",

Validation

All of the input object is validated using the internal validation function.

Validation is done for every Input(create, update, findOne, fineAll).

Filtering not related input

Input not defined in the attributes will be not filtered.

Example

For Product Class example above, validation will be done like below.

const product = await Product.create({
  brandName: 'Innisfree',
  name: 'Green tea toner',
  wrong: 'this is wrong' // will be ignored
}) // will be successfully created

Type Check

If the input type for the according attribute is incorrect, then it throws 400 Error

Example

const product = await Product.create({
  brandName: 1, // wrong type which will cause 400 Error
  name: 'Green tea toner',
})

Query

Model.create

Builds a new model instance and calls save on it.

public static async create(values: object): Promise<Model>

Example

const jane = await User.create({ name: "Jane" });

Model.update

Update a model instance. Must pass id in the values.(BulkUpdate not supported)

public static async update(values: object): Promise<void>

Example

await User.update({ id: req.user.id, nickname: "Jane" });

Model.findAll

Find all model instances match the options.

public static async findAll(options: object): Promise<Array<Model>>

Params

Example

const product = await Product.findAll({
  attributes: 'id, name, price'
  where: {
    brandName: 'Innisfree'
  }
  sortBy: {
    attribute: createdAt,
    order: 'DESC'
  }
})

// if need more detailed select query, use rawWhere.
const rawWhere = `year(date)=${where.year} AND month(date)=${where.month}`
cosnt monthlyExpenditure = await Expenditure.findAll({ '*', where: { userId: req.user.id }, rawWhere })

Model.findOne

Find the first model instance that matches the options.

public static async findAll(options: object): Promise<Model>

Params

Same with Model.findAll params.

Example

const user = await User.findOne({
  attributes: 'id, name, nickname'
  where: {
    githubId: 'zoomkoding'
  }
})

Model.delete

Delete a model instance with id.

Deleting doesn't delete the instance, it changes isDeleted attribute to true.

Find Queries will automatically ignore instances with isDeleted: true

public static async delete(id: number): Promise<void>

Examples

await History.delete(req.params.id)