modulapp

v1.0.1

Published

2 years ago

Modular application framework

Downloads

0High
0Medium
0Low

nauwep

module plugin architecture architect dependency

Modulapp

Modular application framework for node.js

Overview

Modulapp is a framework for defining application in a modular way. It provides an App class and a Module class.

Module concept

Basically a module is an autonomous part of the application. It could be a npm package or it could be a dedicated file in the app's repository. A module can have dependencies (ie. other modules) and can also provides its own API to other dependants.

A module is an instance of the Module class (which extends EventEmitter). You can add any property and functions to that instance.

Modulapp allows to define hooks for a module. The lifecycle of a module has 4 steps: setup, enable, disable and destroy. A specific behavior of the module can be defined during those 4 steps. It's during those hooks that dependencies and options are injected to the module.

The App instance is managing the lifecycle of all modules and dealing with the dependencies and options.

App concept

The App manages the dependencies and the lifecycle of the modules.

An app is an instance of the App class (which extends EventEmitter). The modules must be declared to the app. Then the lifecycle of the app can be performed. The app's lifecycle is composed of 5 steps:

resolve: Checks the modules and resolve the dependency tree
setup: Synchronously execute the setup hook of every module following the dependency tree order
start: Synchronously execute the enable hook of every module following the dependency tree order
stop: Synchronously execute the disable hook of every module following the dependency tree reverse order
destroy: Synchronously execute the destroy hook of every module following the dependency tree reverse order

As the modules are processed synchronously following the dependency tree, the dependencies of a particular module have already been processed before it.

Usage

Install from npm

npm install modulapp

To write a module, import the Module class.

const Module = require('modulapp').Module;

To write an app, import the App class.

const App = require('modulapp').App;

Example

Module class

// myModule.js
const Module = require('modulapp').Module;
let myModule = new Module("myModule");

// define the dependencies by referencing other modulapp modules' id
myModule.dependencies = ['server', 'db'];

// custom property
myModule.foo = 'foo';

// custom function
myModule.bar = function() {
    myModule.emit('bar'); // Module extends EventEmitter
};

// overwrite the setup hook
myModule.setup = function(app, imports, options, done) {
    console.log('setting up myModule');
    done(null); // executing the done callback is required
};

// overwrite the enable hook
myModule.enable = function(app, imports, options, done) {
    console.log('enabling myModule');

        let db = imports.db;
        db.on('disconnected', () => {
            // Do some stuff on event
        });

        let server = imports.server
        server.doSomething((err) => {
            if (err) {
                done(err);  // if something wrong return done with the error
            } else {
                done(null);
            }
        });
};

// myModule.disable can also be overwritten
// myModule.destroy can also be overwritten

module.exports = myModule;

App class

// app.js
const App = require('modulapp').App;
let app = new App();

// Get the modules
let server = require('./server.js');
let db = require('./db.js');
let myModule = require('./myModule.js');

// set the configuration
app.addConfig(server, db, myModule);

// start the application
// start() will itself execute resolve() and setup() if not done
app.start((err) => {
    if (err) {
        console.log(err);
    } else {
        console.log('app started!');
    }
});

someListener.on('destroy app', () => {
    app.stop((err) => {
        if (err) {
            console.log(err);
        } else {
            app.destroy((err) => {
                if (err) {
                    console.log(err);
                } else {
                    console.log('app destroyed!');
                }
            });
        }
    });
});

API References

Classes

App ⇐ EventEmitter

Class representing an App.

Kind: global class
Extends: EventEmitter
Emits: resolving, resolved, setting_up, setup, starting, started, stopping, stopped, destroying, destroyed
Access: public
Since: 1.0.0
Author: nauwep [email protected]

App ⇐ EventEmitter
- new App([config], [options])
- instance
  - .id : String
  - .config : Array.<Module>
  - .options : Object
  - .status : String
  - .addOptions([options])
  - .addConfig([...config])
  - events
  - lifecycle management
- static
  - .events : enum
  - .status : enum

new App([config], [options])

Provide a new instance of App. The config and options are optionnal.

Throws:

Error ERR_APP_011 if options is not an Object.
Error ERR_APP_013 if a module is not a Module instance.

| Param | Type | Default | Description | | --- | --- | --- | --- | | [config] | Module | Array.<Module> | [] | The list of modules. | | [options] | Object | {} | Options for the modules. |

Example

const App = require('modulapp').App;
let app = new App();

let serverModule = require('./server.js');
let dbModule = require('./db.js');

app.addConfig(serverModule, dbModule);

app.start((err) => {
    console.log('App started!');
});

app.id : String

The id of the app, randomly generated.

Kind: instance property of App
Access: public
Read only: true
Since: 1.0.0
Author: nauwep [email protected]
Example

console.log(app.id); // -> '123456789'
app.id = 'anotherId'; // -> throw Error read-only

app.config : Array.<Module>

The configuration of the app. Getting config never return null, at least an empty Array []. Setting null or undefined replaces the current config by an empty Array []. Setting a module will build an Array with that single module.

Kind: instance property of App
Throws:

Error ERR_APP_013 if a module is not a Module instance.
Error ERR_APP_014 if the module is not in created status.

Access: public
Since: 1.0.0
Author: nauwep [email protected]

| Param | Type | Default | Description | | --- | --- | --- | --- | | [newConfig] | Module | Array.<Module> | [] | The new config. |

Example

console.log(app.config); // -> [loggerModule]
app.config = [serverModule, dbModule]; // -> [serverModule, dbModule]
app.config = null; // -> []
app.config = serverModule; // -> [serverModule]

app.options : Object

The options of the app's modules. Read-write property. Getting options never return null, at least an empty Object {}. Setting null or undefined replaces the current options by an empty Object {}.

Kind: instance property of App
Throws:

Error ERR_APP_009 if the app is not in created status.
Error ERR_APP_008 if not an Object

Access: public
Since: 1.0.0
Author: nauwep [email protected]

| Param | Type | Default | Description | | --- | --- | --- | --- | | [newOptions] | Object | {} | The new options. |

Example

console.log(app.options); // -> {server: {port: 8080}}
app.options = {server: {host: 'localhost'}}; // -> {server: {host: 'localhost'}}
app.options = null; // -> {}

app.status : String

The status of the module. The value is part of the supported status.

Kind: instance property of App
Access: public
Read only: true
Since: 1.0.0
Author: nauwep [email protected]
Example

console.log(app.status); // -> 'created'
app.status = App.status.RESOLVED; // -> throw Error read-only

app.addOptions([options])

Add options to the app's modules. Merge with existing options.

Kind: instance method of App
Throws:

Error ERR_APP_008 if the options parameter is not an Object.

Access: public
Since: 1.0.0
Author: nauwep [email protected]

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | {} | The options to add. |

Example

console.log(app.options); // -> {server: {port: 8080}}
app.addOptions({server: {host: 'localhost'}}); // -> {server: {port: 8080, host: 'localhost'}}
app.addOptions(null); // -> {server: {port: 8080, host: 'localhost'}}
app.addOptions(); // -> {server: {port: 8080, host: 'localhost'}}
app.addOptions({db: {host: '127.0.0.0'}}); // -> {server: {port: 8080, host: 'localhost'}, db: {host: '127.0.0.0'}}

app.addConfig([...config])

Add modules to the app's configuration. Merge with existing config and check the new modules and remove duplicates and null.

Kind: instance method of App
Throws:

Error ERR_APP_013 if a module is not a Module instance.

Access: public
Since: 1.0.0
Author: nauwep [email protected]

| Param | Type | Description | | --- | --- | --- | | [...config] | Module | Array.<Module> | The modules to add. |

Example

console.log(app.config); // -> [loggerModule]
app.addConfig([serverModule]); // -> [loggerModule, serverModule]
app.addConfig(null); // -> [loggerModule, serverModule]
app.addConfig(); // -> [loggerModule, serverModule]
app.addConfig(socketModule); // -> [loggerModule, serverModule, socketModule]
app.addConfig(socketModule, utilsModule, [dbModule, serverModule]); // -> [loggerModule, serverModule, socketModule, utilsModule, dbModule]