ashley-koa v1.0.0

Ashley integration with the Koa framework

Ashley can work in any Koa application as is without any support, after all it's just plain JavaScript. However, in the context of a web framework, it's often useful be able to bound a life time of an object to the current request. This integration adds a few helper methods to do that with minimal effort.

• Installation
• Usage
• Example app
• How it works
• Recommendations
• License

Installation

npm install ashley ashley-koa

Usage

First, it's necessary to initialize Ashley itself. This part is not yet Koa specific and it's possible to use any constructs mentioned in the documentation.

In the following example, container will act as the parent container and will be available across all incoming requests. It's the place to bind objects whose life time is bound to the application, not to a particular web request.

const Ashley = require('ashley');
const container = new Ashley({
  root: __dirname
});

const integration = require('ashley-koa');

container.object('Config', 'src/config');
container.instance('DatabaseConnection', 'src/db_connection', ['Config'], {
  initialize: true,
  deinitialize: true
});

Note that Ashley will make sure that the initialize method on the instance will be called just once even if there are multiple requests asking for the not yet initialized instance at the very beginning.

Next, it's necessary to use the integration and bind objects whose life time should be bound to the incoming request they are associated with.

const Koa = require('koa');
const app = new Koa();

integration.initialize(app, container, requestContainer => {
  requestContainer.instance('UserRegistry', 'src/user_registry', ['DatabaseConnection']);
  requestContainer.instance('CurrentUser', 'src/current_user');

  requestContainer.function('BasicAuth', 'src/basic_auth', [Ashley._, Ashley._, 'CurrentUser', 'UserRegistry']);
  requestContainer.function('IndexRoute', 'src/routes/index', [Ashley._, Ashley._, 'CurrentUser']);
});

The first argument of the initialize function is an instance of Koa. The next argument is the parent container and finally, the third argument is a function. This function will be invoked with a single parameter, the request bound container.

As the name suggests, the requestContainer container should contain only binds whose life time is bound to the associated request. All instances will be automatically de-initialized at the end of the request (there's no need to call shutdown manually).

All middlewares are binded as functions with an Ashley placeholder as the first argument and the required dependencies as the rest. When a such function is resolved, it returns a generator function which can be then called with arguments. These arguments will be passed in instead of Ashley placeholders to the binded function along with the resolved dependencies. The IndexRoute middleware can thus look as follows.

// src/routes/index

module.exports = async function(ctx, next, currentUser) {
  ctx.body = `Hello ${currentUser.name}!`;
};

Finally, it's time to actually use the bound functions. Notice the functions are passed to Koa outside of the user-defined function passed to initialize. That's important because the function will be called for every request.

// Use the binded function as middleware
koa.use(integration.middleware('BasicAuth'));
koa.use(integration.middleware('IndexRoute'));

koa.listen(3000);

Example app

There's an example application available in the example folder in the root of the repository. It contains a slightly extended version of the app described above.

How it works

Internally, the initialize function adds a middleware to the passed Koa instance. The middleware will create a new child container from the parent container for every request and pass it into the user defined function. The function then set ups the request bound binds. Since the function will be ran for every request, it should NOT add any new middlewares (call koa.use), otherwise they would be added more than once.

Recommendations

Treat the Koa framework as an implementation detail

It's often the case with Koa applications that the current state of the application (e.g. the current user) is stored in the current context (this.user / this.state.user). Further, it's very common to see Koa middlewares to actually contain the business logic of the application. While it certainly works, an alternative is to treat the fact that the data comes from a web request as an implementation detail.

In this model, middlewares act as mediators. They have access to the data coming in from web requests and they depend on Ashley to inject the necessary objects which contain the actual business logic. The only logic in these mediators is concerned with taking the data out of the web request (e.g. this.params) and passing it into an object which knows what to do with it.

// routes/articles/create
const boom = require('koa-boom');

module.exports = async function create(ctx, next, currentUser, articleRegistry) {
  try {
    articleRegistry.add(currentUser, this.params);
    ctx.status = 201;
  } catch (e) {
    // Handle the error or let it bubble up the chain.
    boom.badRequest(ctx, e.message);
  }
};

The advantage of this approach is that since the web interface is just a detail, you can, for example, add more of them. Is HTTP too slow? Let's implement a Protocol Buffers or Cap’n Proto interface. Is REST not the right fit? Let's add a GraphQL interface. The same business logic, just assembled differently.

Testing is also much easier. Since the logic is not tied to a web framework / web request, it's possible to test the individual objects in total isolation without having to spin up SuperTest every time.

License

ISC