asvd / helios-merge

Tool for bundling Helios Kernel modules

helios-merge — merges Helios modules

helios-merge is a command-line tool which bundles JavaScript modules based upon the Helios Kernel module format. This tool can be used to prepare a library internally managed as several Helios Kernel modules to release as a plain JavaScript file (suitable for using without Helios Kernel), or to simply get a bundled module prepared for further minimizaiton. helios-merge is based upon the Esprima and Escodegen projects.

Installation

There are several options of how the tool can be installed:

• Globally using npm:

$ sudo npm install helios-merge -g

In this case you can simply launch the tool as helios-merge from anywhere (as shown in the examples below). Nevertheless the global installation is not necessary.

• Locally using npm:

$ npm install helios-merge

If you install helios-merge locally, it can be launched using

$ node ./node_modules/helios-merge/helios-merge.js ...

• Download the distribution using this link, unpack it, and launch from that location:

$ node path/to/helios-merge.js ...

Usage

$ helios-merge --input=path --output=path [additional options]

Options:

--input path of the main module to start merging from (defaults to ./main.js)

--output path to write the bundled script into. After the bundle is prepared, it could be reused instead of the original file (provided to the --input option) with the same effect

--quiet suppress informational messages display

--plain create a plain .js file suitable to be used without Helios Kernel (implies --scope=global)

--scope=subdir (default) — bundle only the scripts in the directory and subdirectories. All modules outside of the bundling scope will be treated as external dependencies and will be included into the bundled module head using the include() function of Helios Kernel

--scope=local bundle all sources available by a local path, but treat remote dependencies as external

--scope=global bundle all local and remote files (paths starting form http://...)

--help or whatever unrecognized — show help message

Example

In this example we have a library splitted between several modules relying on each other, and we are going to merge it into a single module. The source of the artificial example library could be like this:

./myLibrary.js — main library module, provides a method to say 'Hello World!':

include('./base.js');
include('./print.js');

init = function() {
    myLibrary.helloWorld = function() {
        myLibrary.print('Hello World!');
    }
}

./print.js — prints a given message:

include('./base.js');

init = function() {
    myLibrary.print = function(text) {
        console.log(text);
    }
}

./base.js — declares library object:

init = function() {
    myLibrary = {};
}

Bundling the library using helios-merge:

$ helios-merge --input=./myLibrary.js --output=./myLibraryBundled.js

The generated myLibraryBundled.js will contain the code of all modules sorted in order of dependence and will behave like this:

init = function() {
    myLibrary = {};

    myLibrary.print = function(text) {
        console.log(text);
    }

    myLibrary.helloWorld = function() {
        myLibrary.print('Hello World!');
    }
}

This code demonstrates the behaviour of the generated bundle, but in fact the code of each original module will additionally be wrapped into an anonymous function to make use of local variables declared in each original module's initializer.