Napoleonic Political Magnificence


    1.0.6 • Public • Published


    Build Status Prod Dependencies Dev Dependencies Coverage Status npm version

    Stats Downloads

    IoC middleware functionality for Express/Connect based web applications. Uses the somersault project as the container implementation but can use alternate providers that implement the same contract.

    Targets NodeJS >= 4.x, support for all later versions (including up to 6.x). For specific versions we test with, please review the .travis.yml file in our repository.


    To install:

    npm install --save connect-ioc


    To add the middleware to your application:

        const ioc = require('connect-ioc');
        // Create instance of the IoC middleware
        const instance = ioc();
        // Register objects for injection with
        // the root container
        instance.rootContainer.register('someService', class|arrowFunc|func|obj-here);
        // Register the middleware function with
        // your Express/Connect application.

    Within your requests you will now have the following ioc object attached to req:

    const myRouteHandler = (req, res) => {
      // Handle some request.
      // Able to now dynamically build up classes with a someService constructor
      // argument automatically.
      const anotherWay =;
      // Call other methods here.
      const myObject = req.ioc.resolve('someService');  // Make me a some-service
      // Can also register dependencies per-request
      req.ioc.register('someService', overrideObjectHere);

    Each request has it's own independent IoC child context, meaning that when you modify or add registrations, it only affects that specific request: each request is independent in this regard.

    The following registrations are done automatically on your behalf:

    • req, request - The current Connect/Express request.
    • res, response - The current Connect/Express response.

    For further information on how to register components for dependency injection or perform run-time build-up of objects, please refer to the documentation for somersault which covers this in more detail.

    Automatic Registrations

    It is possible to pass an autoRegister parameter via the options object on the middleware constructor, allowing automatic registration of modules in a path with the IoC solution:

        const ioc = require('connect-ioc');
        const instance = ioc({
            autoRegister: { pattern: './services/**/*.js', rootDirectory: __dirname },

    This will effectively iterate through all *.js files in the services directory relative to the currently executing script, calling:

    rootContainer.register('friendlyName', require('./services/folder/file'))

    Where friendlyname is determined as:

    - filename.split('-').map(x => upperFirst(x)).join()
        - some-file-name.js --> someFileName
        - someFileName --> someFileName
        - AlreadyCaps -> alreadyCaps

    If you want to customise the alias to register your object as, then modify module.exports and have an additional .tags property, i.e:

    module.exports.tags = ['serviceAliasHere'];

    Configuration Detail

    The middleware has a constructor take takes the following arguments:

        // Provide your own base container for all requests. If not, creates
        // an empty root container.
        // Automatic registration of IoC services at at root/app level.
        autoRegister: {
            // Files to find, uses `glob`
            pattern: './service-objects/**/*.js',
            // Root directory
            rootDirectory: __dirname


    To debug (OS X / Linux):

    export DEBUG=connect-ioc

    Or on Windows;

    set DEBUG=connect-ioc

    This will show debug information about what your application is doing and why.


    npm i connect-ioc

    DownloadsWeekly Downloads






    Last publish


    • steve-gray