axy-define-asm v0.0.1

Assembly axy.define Project

See axy.define.

Install

npm install axy-define-asm

Command-Line Utility

axy-define-asm. Located in the directory bin.

Example:

axy-define-asm --source=js --outDir=outJS

No arguments, only options:

    --addExt=ext      Add an extension to assembly
-a, --all             Add all files
    --allText         Process all files as text
    --appendVars=vars Append vars to the wrapper (by default 'process, global')
-d, --define=prefix   Name of define function (axy.define by default)
-e, --error           Show information about errors
    --fixTS           Fix TypeScript artifacts
    --globalWrapper   Top wrapper for appendVars
    --ignoreDir=dir   Ignore a dir
    --ignoreExt=ext   Ignore an extension
    --ignoreFile=file Ignore a file
-o, --out             Output to stdout
    --outDir=dir      Output directory (follow the structure of source)
    --outFile=file    Assemble to a single file
    --outSelf         Rewrite source file(s)
-p, --pretty          Formatted output
-r, --root=dir        Root directory
-s, --source=dir|file Source file or directory
    --sourceMap       Changing the source map
-u, --useStrict       Add 'use strict'
-t, --utime           Check update time of destination files
    --verbose=[level] Verbose level (1, 2), silence by default

More detailed description see below.

API

var asm = require("axy-define-asm");
var options = {
    source: "/var/www/js",
    outDir: "/var/www/outJS"
};
asm.run(options);

These options are the same as CLI-options. Additional filter and wrap.

Example

Example of a source file:

exports.sum = function sum(a, b) {
    return a + b;
};

And the resulting file:

axy.define("/sum.js", function (exports, module, require, __filename, __dirname, global, process) {
exports.sum = function sum(a, b) {
    return a + b;
};
});

Description of options

Requires two options: source and one of the out-options (out, outDir, outFile or outSelf). All other options are optional.

outDir, outFile and outSelf can not be used in conjunction. out may be used together with other.

source (string)

JS source code. A single file or a directory.

outDir (string)

The directory of resulting axy.define-modules. Reproduces the structure of source.

If source is a single file then in outDir created index.js (and possible index.js.map, see sourceMap option).

outFile (string)

The single resulting file. If the source is a directory then all files from it will be assembled to the single file.

outSelf (boolean)

The source files are replaced with the final files. Is used if the original files are intermediate (compiled from TypeScript sources for example).

out (string)

The assembly result written to the stdout. For assembly in the fly.

It option may be used together with other. Simultaneous output and write in files.

Cannot be used in conjunction with verbose.

addExt (string[])

By default, processed files with extensions js and json. You can add other extensions.

In CLI the option can be used multiple times.

--addExt=txt --addExt=html

all (boolean)

Adds all of the files in the assembly (not only js and json). Then unnecessary files can be avoided using the ignore* options.

*.map files are not affected. They need to add an explicit: --addExt=map.

ignoreExt, ignoreDir, ignoreFile

Ignore specified files, directories and extensions. In CLI can be used multiple times.

--all --ignoreExt=php --ignoreDir=img

The names of files and directories are relative.

--source=/var/www/js --ignoreFile=modules/mo.js

Ignored /var/www/js/modules/mo.js.

define

Name of define function (axy.define by default).

--define=mydefine

Result:

mydefine("/mo.js", function (...) {
   // ...
});

appendVars (string)

By default to the standard CommonJS arguments list (exports...__dirname) added global and process.

--appendVars="global,process,console"

Result:

axy.define("/sum.js", function (exports, module, require, __filename, __dirname, global, process, console) {
    // ...
});

--appendVars=

Result (the standard wrapper):

axy.define("/sum.js", function (exports, module, require, __filename, __dirname) {
    // ...
});

globalWrapper (boolean)

Move additional variables to the top wrapper.

axy.define("/sum.js", function (exports, module, require, __filename, __dirname, global, process) {
    (function (exports, module, require, __filename, __dirname) {
        global; // global is available
        arguments.length; // 5
    })(exports, module, require, __filename, __dirname);    
});

useStrict (boolean)

Adds a string use strict; to the top of the code.

root (string)

By default, the source directory "mounted" to the root of the virtual file system. You can change this.

--source=/var/www/js --root=/modules

The real file /var/www/js/index.js - the virtual file /modules/index.js.

sourceMap (boolean)

This feature is not yet implemented

Moves the source map files and edits them.

utime (boolean)

This feature is not yet implemented

By default, the resulting files are created, even if they already exist.

If specified utime, existing will be checked and the time of modification will be compared. If a source file is older than the destination file, nothing is done. If specified --out the resulting file will be displayed.

verbose (boolean|number)

By default, logs are not displayed. If specify --verbose or --verbose=1 the processed files will be displayed. For --verbose=2 will be displayed additional information.

Incompatible with --out. The code will be displayed mixed with logs.

error (boolean)

By default all exceptions are caught and displayed just "error". This is done so the exception trace does not get to a browser.

But it is difficult to debug. At the time of debugging output can be enabled.

pretty (boolean)

Default output:

axy.define("/sum.js", function (exports, module, require, __filename, __dirname, global, process) {"use strict"; (function (exports, module, require, __filename, __dirname) {
var x = 1;
var y = 2;
module.exports = x + y;
})(exports, module, require, __filename, __dirname);});

Pretty output:

axy.define("/sum.js", function (exports, module, require, __filename, __dirname, global, process) {
    "use strict"; 
    (function (exports, module, require, __filename, __dirname) {
        var x = 1;
        var y = 2;
        module.exports = x + y;
    })(exports, module, require, __filename, __dirname);
});

allText (boolean)

Processes all files as text.

fixTS (boolean)

Fixes some artifacts of TypeScript.

filter (function)

Only available in the API.

(filename: string, basename: string, ext: string, isDir: boolean, options: IOptions): boolean;

Called for each file and directory and determines whether to process it (TRUE) or ignore (FALSE).

filename if relative path. For the source directory /var/www/js and a file /var/www/js/modules/mo.js:

• filename is modules/mo.js
• basename is mo.js
• ext is js
• isDir is FALSE
• options is the full options dictionary

The example:

var options = {
    source: "/var/www/js",
    outDir: "/var/www/outJS",
    filter: function (filename) {
        if (filename === "modules/trash.js") {
            return false;
        }
        return true;
    }
};

wrap (function)

Only available in the API.

(content: string, filename: string, ext: string, options: IOptions): string

Creates a wrapper for define:

axy.define("/module/name.js", <-- wrapper -->); 

• content is the file content
• filename is the relative filename
• ext is the extension
• options is the full options dictionary

Takes as input all files (not only JS). For different extensions may need a different type of wrapper. Return NULL runs the standard wrapper.

var options = {
    // ...
    wrap: function (content, filename, ext) {
        if (ext !== 'json') {
            return null; // standard wrapper for not-JSON files      
        }
        return "function () {return " + content + " }";        
    }
};