README

@kwaeri-node-kit-driver

The @kwaeri/driver component for the @kwaeri/node-kit application platform

The Implementation

@kwaeri/driver reinvents and modernizes the driver portion of the nk application platform.

As the driver component was originally baked into the nk module, its usage was entirely controlled by it. As we discern the process for decoupling the individual components which make up a kwaeri application, we'll begin to simplify the act of doing so, and provide documentation for utilizing each component individually.

The documentation is continually deployed, and located at the Gitlab Hosted Documentation for @kwaeri/driver

Getting Started

@kwaeri/node-kit wraps the various components under the kwaeri scope necessary for building a kwaeri application, and provides a single entry point for easing the process of building a kwaeri application.

However, if you wish to install @kwaeri/driver and utilize it specifically - perform the following steps to get started:

Installation

Install @kwaeri/driver:

npm install @kwaeri/driver

Include the Component

To leverage the database driver, you'll first need to include it:

// INCLUDES
import { Driver } from '@kwaeri/driver';

Provide a configuration

In order to instantiate a driver object, you'll need to provide a configuration for a database type, as well as provide the appropriate database driver provider to the driver module constructor. Here's an example configuration for both MySQL and PostgreSQL:

MySQL

let dbConf = {
  type:     "mysql",
  host:     "localhost",
  port:     3306,
  database: "dbname",
  user:     "root",
  pass:     "password"
};

Postgres

let dbConf ={
  type:     "postgresql",
  host:     "localhost",
  port:     5432,
  database: "dbname",
  user:     "dbuser",
  password: "password"
};

Using the Driver

To use the Driver, you must supply the Driver constructor with the configuration created in the previous step - AND a database driver provider which is derived from @kwaeri/database-driver's BaseDriver that implements the DatabaseDriver interface. Here's an example in full:

import { MySQLDriver } from '@kwaeri/mysql-database-driver';
import { Driver } from '@kwaeri/driver';

let driver = new Driver( dbConf, MySQLDriver );

Notice that the driver provider type is what is passed. Now we can utilize the driver provider anywhere you have access to the Driver module:

let dbo = driver.get();

let result = await dbo.query( "..." );

[...]

Providing a Custom Driver

The Driver component module exists, and in such a way, so as to decouple dependencies from a derived @kwaeri/node-kit application. This means that our development typescript will resolve dependencies and pass tests with out having to have unneccessary dependency modules installed - because we depend solely on the BaseDriver type, which can be satisfied by any database-provider that extends it; @kwaeri/session does something extremely similar with it's session-store providers. Polymorphism ftw!

This also means that its super easy to utilize any database provider with the Driver module, and even to wrap a custom database provider. We've gone with a simple required method, internally, of query(); Mostly because MySQl and PostgreSQL can both leverage this singular method for their functionality. However, you are free to add new methods for the sake of making your databse provider work. This is essentially done in hopes of standardizing database integration such that all aspects of an application will work seamlessly regardless of the database provider used.

NOTE It isn't necessarily inapproparite - at this time - to foregoe the Driver module altogether, and leverage a database provider directly - especially if the technology simply won't integrate with out major changes that break seamless functionality across different database providers. In the future, we'll be providing an elogquent API for each database provider - such that all databse providers can seamlessly interchange (including nosql providers).

To provider a custom provider to the Driver module, you'll need to derive one from the DatabaseDriver class (found in @kwaeri/database-driver), overriding the query method appropriately if possible. Here's an example custom driver implementation in Typescript (that's just a redefinition of MySQLDriver for example's sake):

// INCLUDES (You'll also want to import your database
// module here, so you can wrap it)
import { DatabaseDriver, BaseDriver, DriverConnectionBits, QueryResult } from "@kwaeri/database-driver";


// DEFINES

// If you take a look at @kwaeri/mysql-database-driver/src/mysql.ts, you'll see that we have a partial
// implementation for a more eloquent API. We may finish it eventually.


// Your custom implementation:
export class CustomDriver extends BaseDriver
{
    /**
     * An example class property. This was used
     * to store a connection pool for MySQL
     */
    public pool;

    /**
     * An example class property. This would be
     * used to provide a more eloquent API for
     * making database transactions...Eventually.
     */
    public queryString: string;

    /**
     * Class constructor
     *
     * @since 0.1.0
     */
    constructor( config: DriverConnectionBits )
    {
        super( config );
    }

    /**
     * Implements the standard (REQUIRED) query method of a database driver. Here we
     * show the implementation for MySQL.
     *
     * @param { string } queryString The query string to be executed
     *
     * @return { Promise<QueryResult> } A promise object for allowing asynchronous chaining
     */
    public async query<T extends QueryResult>( queryString: string ): Promise<T>
    {
        // Fetch the connection pool:
        this.pool = mysql.createPool
        (
            {
                host: this.connection.host,
                port: this.connection.port,
                database: this.connection.database,
                user: this.connection.user,
                password: this.connection.password
            }
        );

        // Create a promise wrapper for a connection:
        let promisePool = this.pool.promise();

        // Execute the query:
        let [ rows, fields ] = await promisePool.execute( queryString );

        // Return a promise resolution:
        return Promise.resolve( <T>{ rows: rows, fields: fields } );
    }
}

Once you've created your implementation, you'll need to pass a configuration - and the database-driver - to the Driver constructor so it may be consumed:

// INCLUDES:
import { CustomDriver } from "../my/custom/driver";

// DEFINES:
let dbConfig = {
  type:     'custom',
  host:     'localhost',
  database: 'dbname',
  user:     'root',
  password: 'password'
};

let dbo = new Driver( dbConfig, CustomDriver );

And the Driver class will store, wrap, and make use of your custom databse driver implementation.

Usage

We have not discerned the entire process one will need to follow in order to make use of @kwaeri/driver individually. The component was originally intended to be used in conjunction with several other components which make up the nk application platform.

As we discern the process for doing so, this section will be expanded.

Query the Database

An example of querying the database with the provided MySQL driver:

let results;

// Always catch errors when expecting a promise. You
// could use traditional async/await like here, or
// go the traditional route.
try
{
  results = await dbo
  .query( `select * from people where first_name='Richard' and last_name='Winters';` );

  console.log( 'Returned record: Id: ' +  results.rows[0].id +
              ', First name: ' + results.rows[0].first_name +
              ', Last name: ' + results.rows[0].last_name +
              ', Age: ' + results.rows[0].age );
}
catch( error )
{
  console.log( '[ERROR]: ' + error );
}

How the return is structured is dependent on the driver implementation, but this is typically how it should be.

NOTE

How to Contribute Code

Our Open Source projects are always open to contribution. If you'd like to cocntribute, all we ask is that you follow the guidelines for contributions, which can be found at the Massively Modified Wiki

There you'll find topics such as the guidelines for contributions; step-by-step walk-throughs for getting set up, Coding Standards, CSS Naming Conventions, and more.

Other Ways to Contribute

There are other ways to contribute to the project other than with code. Consider testing the software, or in case you've found an Bug - please report it. You can also support the project monetarly through donations via PayPal.

Regardless of how you'd like to contribute, you can also find in-depth information for how to do so at the Massively Modified Wiki

Bug Reports

To submit bug reports, request enhancements, and/or new features - please make use of the issues system baked-in to our source control project space at Gitlab

You may optionally start an issue, track, and manage it via email by sending an email to our project's support desk.

For more in-depth documentation on the process of submitting bug reports, please visit the Massively Modified Wiki on Bug Reports

Vulnerability Reports

Our Vulnerability Reporting process is very similar to Gitlab's. In fact, you could say its a fork.

To submit vulnerability reports, please email our Security Group. We will try to acknowledge receipt of said vulnerability by the next business day, and to also provide regular updates about our progress. If you are curious about the status of your report feel free to email us again. If you wish to encrypt your disclosure email, like with gitlab - please email us to ask for our GPG Key.

Please refrain from requesting compensation for reporting vulnerabilities. We will publicly acknowledge your responsible disclosure, if you request us to do so. We will also try to make the confidential issue public after the vulnerability is announced.

You are not allowed, and will not be able, to search for vulnerabilities on Gitlab.com. As our software is open source, you may download a copy of the source and test against that.

Confidential Issues

When a vulnerability is discovered, we create a [confidential issue] to track it internally. Security patches will be pushed to private branches and eventually merged into a security branch. Security issues that are not vulnerabilites can be seen on our public issue tracker.

For more in-depth information regarding vulnerability reports, confidentiality, and our practices; Please visit the Massively Modified Wiki on Vulnerability

Donations

If you cannot contribute time or energy to neither the code base, documentation, nor community support; please consider making a monetary contribution which is extremely useful for maintaining the Massively Modified network and all the goodies offered free to the public.

@kwaeri/driver

Usage no npm install needed!