@timekadel/lazy

1. Lazy API Framework

⚠️ These instructions are incomplete. Documentation process is still in progress.

A Node.js API framework made by lazy developers for lazy developers. Easy setup and migration of MySQL table models, automated and intuitive API endpoint generation, straightforward API integration tests setup and much more.

Table of contents

• 1. Lazy API Framework
• 2. Installation
• 3. Setup
  • 3.1. Configuration
    • 3.1.1. Database options
    • 3.1.2. Server Options
    • 3.1.3. IO Options
• 4. Describing Lazys
  • 4.1. Describing Models
    • 4.1.1. Describing Schemas
      • 4.1.1.1. Describing Columns
        • 4.1.1.1.1. Foreign Key Configuration
    • 4.1.2. Model Declaration Examples
      • 4.1.2.1. Simple User Model
      • 4.1.2.2. "Complex" Friend Model (with foreign key constraints)
  • 4.2. Configuring Endpoints
• 5. Changelog
• 6. Appendix
  • 6.1. Supported Column Types

2. Installation

Lazy is free from native bindings and can be installed on Linux, Mac OS or Windows without any issues.

npm install --save @timekadel/lazy

3. Setup

3.1. Configuration

const {Lazy} = require('@timekadel/lazy'); //Requiring Lazy

//Setting up Lazy
Lazy.config({
    searchPath: String,                 //Root path to lazys configuration files (search is recursive)
    db:{                                //DB configuration
        host: String,                   //DB Host
        db: String,                     //DB name
        user: String,                   //DB user
        password: String                //DB password
    },
    server:{                            //API server configuration
        port: Number,                   //API running port. (Default: 4000)
        allowedOrigins: Array<String>,
        auth: Function                  //API server Authentication middleware function
    },
    io:{                                //Socket.io configuration (Optional)
        onConnect: Function,            //On connection function
        auth: Function,                 //Socket.io authentication middleware function 
        cookie: Boolean,                //Enable Cookies ?
        pingInterval: Number,           //Socket.io Ping interval
        pingTimeout: Number             //Socket.io Ping timeout
    }
});

Lazy recursively searches for *.lazy.js files within a provided search path from which MySQL tables and API endpoints will be generated. Lazy's API server may be configured to run over any given port.

• searchPath: rootPath to lazys configuration files (search is recursive)
• db: Database configuration
• server: Server configuration
• io: socket.io configuration (Optional)

3.1.1. Database options

The following configuration options are mandatory in order to establish a connection with the database:

• host: The hostname of the database you are connecting to. (Default: localhost)
• port: The port number to connect to. (Default: 3306) and port are ignored.
• user: The MySQL user to authenticate as.
• password: The password of that MySQL user.
• database: Name of the database to use.

3.1.2. Server Options

If a list of allowed origins is provided, API requests will be restricted to the provided list of origins and responded with a status-code 403 otherwise.

It is up to developers to setup an authentication middleware function. If none is provided, each described route should be configured with their protected parameter set to false. (see Describing Lazys).

• port: The port number to connect to. (Default: 4000)
• allowedOrigins: Access control - Allowed origins list.
• auth: API server Authentication middleware function.

3.1.3. IO Options

As a way to broadcast live messages, Lazy comes pre-packaged with socket.io. You may opt to use it within your project by providing an io configuration section to Lazy's configuration object as follows:

• onConnect: socket.io onConnection event handler
• auth: socket.io authentication middleware function
• pingInterval: Low level engine pingInterval option.
• pingTimeout: Low level engine pingTimeout option.

4. Describing Lazys

Lazy's modules called "Lazys" must be placed anywhere under the provided searchPath (see Setup section). Lazys may be used to describe models and/or API endpoints. Valid Lazys must be described as follows:

/** <appRoot>/<searchPath>/<lazyname>.lazy.js */

module.exports = {
    name: String,       //Each lazy name must be unique !.
    model: Object,      //Optional: Model configuration. (You may create virtual endpoints)
    endpoint: Object    //Optional: Endpoint configuration. (You may choose not to register endpoints)
}

• name: Unique name used to identify and require a Lazy
• model: Lazy's model description
• endpoint: Lazy's endpoint configuration

To give a better overall understanding of Lazy's syntax and operation, the following sections will be based around a very simple example described below:

4.1. Describing Models

model:{
    table: String,
    schema: Object
}

• table: Database's table name
• schema: Lazy's schema configuration object

4.1.1. Describing Schemas

schema:{
    column_1_name: Object,
    //...
    column_n_name: Object
}

• column_1_name: First column configuration object
• column_n_name: Last column configuration object

4.1.1.1. Describing Columns

column_name:{
    type: String,
    size: Number,
    default: String,
    pk: Boolean,
    fk: Object
}

• type: Column type. (see supported types section for valid options):
• size: Column size (If required. see supported types section)
• default: Column's default value
• pk: Select column as primary key
• fk: Column foreign key configuration object

4.1.1.1.1. Foreign Key Configuration

fk:{
    join: Object<Lazy>,
    on: String,
    as: String,
    delete: String,
    update: String,
}

• join: Reference to Lazy to be joined.
• on: Join column selection.
• as: Retrieve foreign row under a specific alias name. (Optional)
• delete: On delete action (see supported actions section).
• update: On cascade action (see supported actions section).

4.1.2. Model Declaration Examples

To give a better overall understanding of the Lazy's model features, Basic examples based aroud the implementation of the following class diagram are described within the next section.

⚠️ WIP, This section is incomplete.

4.1.2.1. Simple User Model

module.exports = {
    name: "LazyUser",
    model:{
        table: "users",
        schema:{
            id:{
                type: "VARCHAR",
                size: 50,
                pk: true
            },
            fname:{
                type: "VARCHAR",
                size: 20,
                default: "Fname"
            },
            lname:{
                type: "VARCHAR",
                size: 20,
                default: "Lname"
            },
        },
    },
    //...Endpoint declaration
}

4.1.2.2. "Complex" Friend Model (with foreign key constraints)

const {Lazy} = require('@timekadel/lazy');
const LazyUser = Lazy.require('LazyUser');

module.exports = {
    name: "LazyFriend",
    model:{
        table: "friends",
        schema:{
            user_id:{
                type: "VARCHAR",
                size: 50,
                fk: {
                    join: LazyUser,
                    on: "id",
                    delete: "CASCADE",
                    update:  "CASCADE"
                }
            },
            friend_id:{
                type: "VARCHAR",
                size: 50,
                fk: {
                    join: LazyUser,
                    on: "id",
                    as: "friend",
                    delete: "CASCADE",
                    update:  "CASCADE"
                }
            },
            timestamp:{
                type: "TIMESTAMP",
                size: 3,
                default: "CURRENT_TIMESTAMP"
            }
        }
    },
    //...Endpoint declaration

4.2. Configuring Endpoints

endpoint:{
    root: String,
    protected: Boolean,
    methods: Object
}

• root: Database's table name
• protected: Lazy's schema configuration object
• methods: Lazy's schema configuration object

⚠️ WIP, This section is incomplete.

5. Changelog

• 1.0.21:
  • Implemented direction for ORDER BY clause
  • Patched lazy.controller.js to avoid automatically fetching resources for tables without private key
• 1.0.20:
  • Improved instructions sections organisation/numbering
• 1.0.19:
  • Created git repository
  • Updated links to git repository
  • Updated Model declaration examples
• 1.0.18:
  • Patched lazy.model.js to multiple join queries on same foreign table.
  • Numbered instruction sections to make things clearer
• 1.0.17:
  • Patched lazy.model.js to multiple join queries on same foreign table.
  • Patched lazy.controller to avoid throwing errors when no tests are beign described.
  • Patched lazy.js to avoid throwing error when no auth functions are provided.
  • Patched lazy.js to avoid throwing error if io configuration does not exist
  • Updated Instructions

6. Appendix

6.1. Supported Column Types

⚠️ WIP, This section is incomplete/invalid.

Type String	Is Typed	Additional Parameters
CHAR	yes	none
VARCHAR	yes	none
BINARY	yes	none
VARBINARY	yes	none
TINYBLOB	yes	none
TINYTEXT	yes	none
TEXT	yes	none
BLOB	yes	none
MEDIUMTEXT	yes	none
MEDIUMBLOB	yes	none
LONGTEXT	yes	none
LONGBLOB	yes	none
ENUM	yes	none
CHAR	yes	none
VARCHAR	yes	none
BINARY	yes	none
VARBINARY	yes	none
TINYBLOB	yes	none
TINYTEXT	yes	none
TEXT	yes	none
BLOB	yes	none
MEDIUMTEXT	yes	none
MEDIUMBLOB	yes	none
LONGTEXT	yes	none
LONGBLOB	yes	none
ENUM	yes	none
SET	yes	none
BIT	yes	none
TINYINT	yes	none
BOOL	yes	none
BOOLEAN	yes	none
SMALLINT	yes	none
MEDIUMINT	yes	none
INT	yes	none
INTEGER	yes	none
BIGINT	yes	none
FLOAT	yes	none
DOUBLE	yes	none
DOUBLE PRECISION	yes	none
DECIMAL	yes	none
DEC	yes	none
DATE	yes	none
DATETIME	yes	none
TIMESTAMP	yes	none
TIME	yes	none
YEAR	yes	none