Nurturing Pluto's Martians

    smart-container

    0.2.1 • Public • Published

    smart-container

    smart-container is a dependency injection container for NodeJS which can be configured with a configuration file.

    npm version codebeat badge Build Status codecov

    Installation

    $ npm install --save smart-container
    

    Features

    • Define classes or literal objects to container,
    • Define properties to container,
    • Inject dependencies in constructor,
    • Inject dependencies in methods,
    • Setting up the container with a configuration file,
    • Lazy loading (The services are created when you need them).

    Usage

    Create and use the container without configuration file

    Get the container builder

    const containerBuilder = require('smart-container');

    Create the container

    const container = containerBuilder.create();

    Create and register a new service

    /* Create a service class */
    class Hello {
      constructor() {
        this.msg = 'Hello world!';
      }
     
      sayHello() {
        console.log(this.msg);
      }
    }
     
    /* Register the service */
    container.register('hello', Hello);

    Get and use the service

    container.get('hello').sayHello(); // Print 'Hello world!'

    The configuration file

    Here is a template of a service configuration file (the file can be a JSON or a JS file) :

    module.exports = {
      properties: {
        propertyName: 'property_value'
      },
      services: {
        serviceName: {
          path: 'relative_path_to_the_service',
          constructorArgs: ['first_arg', 'second_arg' /*... others args*/],
          isSingleton: false, /* By default a service is a singleton */
          calls: [
            {
              method: 'method_name',
              args: ['first_arg', 'second_arg' /*... others args*/]
            }
          ]
        }
      }
    };

    The properties

    Define a property

    The object properties is used to define a collection of properties. For each property, you must specify its name and its value :

    {
      properties: {
        firstName: 'John',
        lastName: 'Doe'
      }
    }

    You can create an object as property :

    {
      properties: {
        person: {
          firstName: 'John',
          lastName: 'Doe'
        }
      }
    }
    process.env support

    If you use a js configuration file instead of a JSON configuration file, you can use the environment variables:

    {
      properties: {
        host: process.env.DB_HOST,
        username: process.env.DB_USER,
        password: process.env.DB_PASS
      }
    }

    The services

    The name and path of the service

    The object services is used to define a collection of services. For each service, you must specify its name and the path of its file :

    {
      services: {
        messagePrinter: {
          path: './MessagePrinter'
        }
      }
    }
    constructorArgs

    you can specify the arguments of the service constructor :

    {
      services: {
        messagePrinter: {
          path: './MessagePrinter',
          constructorArgs: ['Hello world!']
        }
      }
    }

    It's possible to reference of a property (defined in the configuration file), just wrap the name of the property with % :

    {
      services: {
        messagePrinter: {
          path: './MessagePrinter',
          constructorArgs: ['%message%']
        }
      }
    }

    If the property is an object, you can access of the object property like that :

    '%person.firstName%'

    It's also possible to reference of a other service. Just prefix the service name with @:

    '@otherService'
    isSingleton

    You can specify if the service is a singleton or not (by default a service is a singleton) :

    {
      services: {
        messagePrinter: {
          path: './MessagePrinter',
          constructorArgs: ['%message%'],
          isSingleton: false
        }
      }
    }

    In the case of a literal object, if isSingleton is set to false, the object Is copied.

    calls

    At the creation of the service, it's possible to call several methods :

    {
      services: {
        messagePrinter: {
          path: './MessagePrinter',
          constructorArgs: ['%message%'],
          calls: [{
            method: 'setMessage',
            args: ['Hello guys!']
          }]
        }
      }
    }

    You can, like the arguments of the constuctor, make a reference to a property or a service.

    Build a container with the configuration file

    Create a service class

    MessagePrinter.js

    module.exports = class MessagePrinter {
      constructor(msg) {
        this.msg = msg;
      }
     
      setMessage(msg) {
        this.msg = msg;
      }
     
      print() {
        console.log(this.msg);
      }
    };
    Create the configuration file

    Services.js

    module.exports = {
      properties: {
        message: 'Hello world',
      },
      services: {
        messagePrinter: {
          path: './MessagePrinter',
          constructorArgs: ['%message%'],
          calls: [{
            method: 'setMessage',
            args: ['Hello guys!']
          }]
        }
      }
    };
    Get the container builder
    const containerBuilder = require('smart-container');
    Build the container
    const container = containerBuilder.build(__dirname, './Services.js');

    Get and use the service

    container.get('messagePrinter').print(); // Print 'Hello guys!'

    API

    ContainerBuilder

    create()

    Create an empty container

    build(rootDir, configPath)

    Create a container with a configuration file. The parameters are :

    • rootDir: The absolute path for the root directory (use __dirname),
    • configPath: The relative path of the configuration file.

    Container

    load(rootDir, configPath)

    Load a configuration file. The parameters are :

    • rootDir: The absolute path for the root directory (use __dirname),
    • configPath: The relative path of the configuration file.

    get(name)

    Get a service by its name

    register(name, serviceClass, isSingleton)

    Register a service. The parameters are :

    • name: The name of the service,
    • serviceClass: the class or the literal object of the service,
    • isSingleton: (optional : by default true) true if the service is a singleton, false otherwise.

    This function return an ServiceDefinition object (see below).

    hasService(name)

    Check if the service exists with its name

    getProperty(name)

    Get a property by its name. You can access of an object property like that :

    'person.firstName'

    addProperty(name, value)

    Add a property. The parameters are :

    • name: The name of the property,
    • value: the value of property.

    hasProperty(name)

    Check if the property exists with its name.

    ServiceDefinition

    This object is used to describe a service.

    addArgument(value)

    Add a argument value used by the constructor. You can use the symbol @ to make reference to an other service or wrap the value with % to make reference to a property.

    addArguments(args)

    Add several arguments used by the constructor. The parameter args is an array.

    addMethodCall(method, args)

    Add a method call. The parameters are :

    • method: the name of the method,
    • args: (optional) the array of method arguments.

    addMethodCalls(calls)

    Add a several method calls. The parameter is :

    • calls: the array of method calls.

    Each element of the calls array is an object with the following properties:

    • method: the name of the method,
    • args: the array of method arguments.

    Examples

    Check out the examples directory to see more complex examples.

    License

    The MIT License (MIT)

    Copyright (c) 2017 Axel SHAÏTA shaita.axel@gmail.com

    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.

    Install

    npm i smart-container

    DownloadsWeekly Downloads

    0

    Version

    0.2.1

    License

    MIT

    Last publish

    Collaborators

    • arkerone