Chapter 1: Practice conventions - AlexanderSychev/node-autoload GitHub Wiki

This conventions are need to correct work of package. It's a simple standard to succesfull usage of autoload.

1. Names of module files must follow the pattern "basename.auto.(js|json|node)".

Package use special Glob pattern to find autoloadable modules in directory. If module name isn't follow this.pattern, it will node be automaticaly loaded.

Examples of names:

• some-module.auto.js - Javascript Module to automatic load;
• some-config.auto.json - JSON Document to automatic load (useful to automatic loading of some configs);
• some-binary.auto.node - binary Node.JS module (written by C\C++) to automatic load;

Modules with same base name will be required by standard Node.JS "require" rules.

2. Module must export string property with name "id"

To use module inside Autoload Context you must define it's identifier field "id" which must be in exports`module.exports` object. This field is replacement of standard Node.JS module indentifier (module's path in file system).

Examples:

// Via "exports"
exports.id = 'MySuperModule';

// Via "module.exports"
module.exports = {
   id: 'MySuperModule',
   // Other entities to export
};

// TypeScript provides ES6 modules signature
const id: string = 'MySuperModule';
export {id};

3. Module with dependencies inside Autoload Context must export implemented function "bootstrap(context: IContext): any"

Any autoloadable module which use other autoloadable modules must implement and export field "bootstrap" with function with one argument - Autoload Context.

To use other autoloadble module inside you must require it via method "getContext(moduleId)" of Autoload Context instance (first argument of "bootstrap").

If autoloadable module must export something, you must return enitities to export as result of "bootstrap" function. If "bootstrap" function returns nothing, module exports nothing.

Modules without "bootstrap" function use default Node.JS export rules (exports`module.exports` object will be returned by "getContext").

DO NOT REQUIRE AUTOLOAD CONTEXT DIRECTLY VIA "require"! IT WILL BE A CIRCULAR DEPENDENCY!

Examples:

// Most simple implementation

exports.id = 'MyModule';

exports.bootstrap = function(context) {
    const MyOtherModule = context.getModule('MyOtherModule');
    const toExport = {};

    toExport.getWithOther = function() {
        let result = {};
        result.data = 'data';
        result.other = MyOtherModule.getOther();
        return result;
    };

    return toExport; // This will be returned by "context.getModule('MyModule');
};

// You can also return instance of class "Module" of package
const {Module} = require('node-autoload');

module.exports = new Module(
    'MyModule',  // Module identifier (required)
    function(context) { // Module bootstrap function (required)
        const MyOtherModule = context.getModule('MyOtherModule');
        const toExport = {};

        toExport.getWithOther = function() {
            let result = {};
            result.data = 'data';
            result.other = MyOtherModule.getOther();
            return result;
        };

        return toExport; // This will be returned by "context.getModule('MyModule');
    },
    true // Is module bootstraps lazy, on first "context.getModule" call (optional, equals "false" by default)
);

// In TypeScript you should import type definitions for modules.
// If they are use only just types, TypeScript compiler remove them.

import {IContext} from 'node-autoload';
import {IMyOtherModule} from '../IMyOtherModule';

interface IMyWithOther {
    data: string;
    other: string;
}

interface IMyModuleExports {
    getWithOther(): IMyWithOther;
}

const id = 'MyModule';

function bootstrap(context: IContext): IMyModuleExports {
    const MyOtherModule: IMyOtherModule = <IMyOtherModule> context.getModule('MyOtherModule');

    const toExport: IMyModuleExports = {
        getWithOther: function(): IMyWithOther {
            let result: IMyWithOther = {
                data: 'data',
                other: MyOtherModule.getOther()
            };
            return result;
        }
    };

    return toExport; // This will be returned by "context.getModule('MyModule');
}

export {id, bootstrap};

4. Autoloadable modules with lazy bootstrap must export boolean field "lazy" with value "true"

By default all bootstrapable modules execute immediatly. But if you export boolean field lazy with value true, module will be executed on first call of context.getModule.

Example:

exports.id = 'MyModule';

exports.lazy = true;

exports.bootstrap = function(context) {
    console.log('This message will be shown on first "context.getModule" call');
};