This package has been deprecated

Author message:

this package has been deprecated

@ximerajs/base

0.10.1 • Public • Published

Ximera-JS

build status bitHound Overall Score bitHound Code npm Dependency Status

Ximera-JS is a simple yet powerful component container for Node.JS large scale application. It let you easily create reusable features that are detected and loaded at container startup. It let you structure the code the way you like, and still discover all components, asynchronously loading them when all their dependencies have been resolved. Ximera-JS is a very lightweight core container, but supports various plugins that let you quickly install reusable features like authentication, restful resources, mongodb database support and much more, just by installing a new npm module. You can also create your own plugins, to share reusable code between your applications.

Pre-Requisites

You need to install Node.JS version 6.x+ and have a GIT client.

Your First Project

mkdir myproject
cd myproject
npm init
npm install @ximerajs/base
mkdir src
mkdir test

In the src folder, use your favorite editor and create the index.js file.

const Ximera = require('@ximerajs/base');

// Instantiate the Ximera container targeting our current folder
let ximera = new Ximera(__dirname, {
    timeout: 5000,
    plugins: [
        "express",
        "webpack",
        "mongodb",
        "logger",
        "restful"
    ]
});

// Execute the ximera lifecycle (init, load, start)
module.exports = ximera.init()
    .then( () => ximera.load() )
    .then( () => ximera.start() )
    .then( () => {
        console.log("Ximera was successfully started");
        return ximera;
    })
    .catch( (err) => console.log("Ximera failed", err));

Plugins

Ximera-JS comes with a very small core, the actual container, component lifecycle rules, loaders and dependency injector. But to do something useful with your project, you need to install plugins. While you can create all components yourself, it's way faster to reuse available plugins, that will register a number of frequently used components for you. See the sidebar for documentation of all plugins we publish.

Plugins will register themselves as a component source during the init phase of the container. At this time, they will usually register a component path and also a number of component loaders (see below). For example, the express plugin will register a route loader that will register all route.js files in your project with the global express instance, freeing you from this task. You only have to define, easy to test routes in their own file and let the container find them.

So to run our sample, you need to install these plugins first:

npm install @ximerajs/express @ximerajs/logger @ximerajs/webpack @ximerajs/mongodb @ximerajs/restful --save 

project structure

An interesting feature of Ximera-JS is that it doesn't forces a specific project structure and this is by design. Some organizations want to group all controllers together, models together or sometimes, they want to take a feature approach and group everything related to a feature in a specific folder. Ximera-JS has not pre-condition on the actual folder. It will glob all files recognized by loaders recursively inside the specific project folder (the __dirname first parameter when constructing the container).

We think that this approach has many benefits

  • You can choose the structure that is the most adapted to your project.
  • You can evolve and grow the structure with the number of components
  • You can have both client and server components in your project

This is somewhat similar to MeteorJS, but the loading order is defined by loaders and their dependencies, not by the depth or any special folders.

Loaders

Loaders are the most important component found in Ximera-JS. They actually define what kind of components you can create in your application. They also orchestrate initialization sequence, making sure all dependencies for your components are loaded before executing your factory. Loaders are responsible for locating component based on their file pattern (you could find them otherwise if you want, this is a convention, not a rule). Searching all registered component paths (core, your project and any plugins), the loader will identify all matching files and execute the exported component factory.

By default, Ximera-JS offer the following loaders:

  • metaloader (load loaders!)
  • config
  • service

All other loaders are provided by plugins.

Component Factories

After many years of Node.JS development, we have identified a simple pattern that helps in many ways when structuring large projects. All components are not directly exported through module.exports, but they always export a factory that will create the component. This factory is a simple function declaring a number of parameters. We borrowed Angular.JS parameter injection and applied this pattern to all our components. The direct benefit is that you never have to instantiate any collaborators and you can easily override any parameter value when testing, greatly simplifying unit testing.

Loaders expects that all components exports a factory like this :

module.exports = function(config, server, log, app) {

    // private members

    // Public interface
    return {
        doSomething: function() {

            // access to parameters
            log.debug("Doing something!");

            return true;
        }
    }
};

Only the public object will be made available to other components. All parameters are automatically injected by the container, when they are resolved. It means that everything is asynchronous, promise-based. As promises are resolved, factories will get executed and components will get created and registered. In our example above, this component would only be registered after the app parameter is injected, meaning that it needs ximera-express to create the express application first. This orchestration is provided to you out of the box. You only need to take care of a few edge cases like circular dependencies.

Circular dependencies

Sometimes, you'll get a component waiting for another component waiting for the first component. This will prevent your server from starting. Ximera-JS has circular resolver in place and will try to resolve circular dependencies to its best capacity. Of course, if you have two factories waiting for each other, Ximera-JS will timeout and report the situation. When this happens, you can easily resolve the problem by injecting the injector directly, and using injector.resolve manually in one of your component, when the component is used for example.

app.config.js

All .config.js files will be detected and loaded by the container to create a single config instance. Your application can add as many config files as required and your config files may override existing framework config like logging. Here's a simple src/app.config overriding the log, the server port and adding a simple title to the app.

module.exports = {
    log: {
        console: {
            level: debug
        }
    },
    port: 9000,
    app:{
        $filter: 'env',
        production:{
            title: 'My Project - Production'
        },
        developement: {
            title: "My Project - dev"
        },
        $default: {
            title: "My Project"
        }
    }
}

We use (Confidence)(https://github.com/hapijs/confidence) to create environment specific configuration. Only the env variable is exposed right now.

Running your server

Simply execute your index file

node src

This will start your server in development mode, starting a simple express server without any routes or services.

Readme

Keywords

none

Package Sidebar

Install

npm i @ximerajs/base

Weekly Downloads

3

Version

0.10.1

License

Apache-2.0

Last publish

Collaborators

  • jgrenon