Koa DALs

Data access layers management for Koa@2.

Installation

npm install @bloxite/koa-dals --save

Usage

Import guard object

const dals = require('@bloxite/koa-dals')
// or in ES6-way
import dals from '@bloxite/koa-dals'

This module made for work with koa-router.

There is only three methods for manage your DALs: connect, register and get.

Connect to database

First you need to create a connections factory, that will create a connection for every request. Of course you can use connections pool or share single connection, factory — it's just an abstraction. For create new connection use connect method:

// let's connecto to MySQL server using pool from promise-mysql library
const mysql = require('promise-mysql').createPool(MYSQL_URL)
// dals is a singleton object, so we can use it anywhere in program
const dals = require('@bloxite/koa-dals')

// register connection
dals.connect('mysql', {
  // connect's functions "take" and "release" can return Promise or connec in syncronous way
  take: () => mysql.getConnection()
  release: (con) => mysql.releaseConnection(con)
})

Here two parameters: first is name of connection, second is factory object that contain two properties: take and release. take is a connection factory, that provides new connection. release is a connection destructor. DALs manager share connections between every DAL, so you can use transactions inside your route. For example:

// we assume `transactions`, `posts` and `user` DALs inside uses `mysql` connection
// so `mysql` connection will be shared between them
router.post(
  // method `get` will be described below
  '/posts', dals.get([ 'transactions', 'posts', 'user' ]),
  async ({ dals: { transactions, posts, user } }) => {
    // begin transaction
    await transactions.begin()

    posts.create(/* ... */)
    user.increasePostsCount(/* ... */)

    // commit transaction
    await transactions.commit()
  }
)

Create DAL

To register new DAL you should pass two arguments to method register: first — name of DAL, second — DAL description object.

DAL description is an object with two properties. First property is required — is a list of required connections for current DAL, e.g. [ 'mysql', 'redis' ]. Second property is factory-function named create, that create a DAL object. This function receives object with connections and can return DAL.

Here is example:

// register a functions for manage blog posts
dals.register('posts', {
  required: [ 'mysql' ], // list of required connections
  create: function posts ({ mysql }) { // method that creates DAL
    // create new post
    async function create ({ title, content }) {
      await mysql.query('INSERT INTO ...')
      return 'POST_CREATED'
    }

    return { create, ... }
  }
})

Using DALs

Okay, this is easiest part of this doc. To use your DAL you should use a get method. This method accepts list of DALs you want to use (e.g. [ 'posts', 'user' ]) and return a middleware for koa-router. Middleware patches request context and creates new property called dals that contains all required DALs. Example:

router.get(
  '/',
  dals.get([ 'posts' ]) // load DAL for posts
  async (ctx) => {
    const { posts } = ctx.dals // here be you DALs

    // use DAL
    const status = await posts.create({
      title: 'Hello World!',
      content: '<h1>Hello World!</h1>\nThis is my first post.'
    })

    ctx.response.body = status // "POST_CREATED"
  }
)

License

MIT License

Copyright (c) 2017 Bloxite

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.