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

| Name | Type | Attributes | Description | | -------- | ----------- | -------- | ----------- | | options | object | optional | A hash of options(currently only sync exists) | options.sync | object | optional, default: false| Sync this Model to the DB, that is create the table.

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

| Name | Type | Attribute | Description | | -------- | ----------- | -------- | ----------- | | attributes | object | required | A hash of attributes with dataType(Required), required(Optional), defaultValue(Optional) | defaultWhere | object | optional | A hash of attributes that should be always included in where.

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

| Name | Type | Attribute | Description | | -------- | ----------- | -------- | ----------- | | options | object | optional | A hash of options to describe the scope of the search | options.attributes | string | optional, default: '*' | A Comma Separated list of the attributes that you want to select | options.where | object | optional | A hash of attributes to describe your search (v 1.0.0 only Exact Match is supported) | options.rawWhere | string | optional | A raw subQuery you can put in where | options.sortBy | object | optional | Specifies an ordering. (object needs to has two keys attribute, order).

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)