definer v0.2.5

Definer — самая простая модульная система для JavaScript на клиенте

Definer предназначен для удобной разработки. С его помощью можно использовать модули и указывать их зависимости, по которым в дальнейшем будет выполнена сборка. В результирующем файле не будет модульной системы, поэтому конечный пользователь не получит лишний код, реализующий модули.

Использование

Установка

npm install definer

Подключение

Достаточно подключить один файл.

<script src="definer.js"></script>

Объявление модулей

Пусть есть модули a и b, и модуль c, зависящий от них.

var a = definer('a', function() { return 'a'; }); // a
var b = definer('b', function() { return 'b'; }); // b
var c = definer('c', function(a, b) { return a + b + 'c'; }); // abc

Модули должны быть объявлены в правильной последовательности, иначе возникнет ошибка.

definer('b', function(a) {}); // ReferenceError: module a is not defined
definer('a', function() {});

Экспорт в глобальный контекст

Внутри модулей this указывает на глобальный контекст. Используя это, модуль может легко экспортировать данные.

definer('d', function() { this.d = 100; }); // Появилась глобальная переменная d

Методы

Метод export

При выполнении собранного результата из Node.js в объект module.exports будет добавлен ключ d со значением 100.

При выполнении в браузере будет создана аналогичная глобальная переменная.

definer.export('d', function() { return 100; });

Метод clean

В качестве параметра метод clean принимает имя глобальной переменной или массив имён.

Указанные переменные удалятся из глобального контекста и будут объявлены одноимённые модули.

Например, скроем jQuery в модуль:

definer.clean('$');
console.log($); // undefined
definer('a', function($) { $('html').text('a'); });

Очистка сразу нескольких переменных:

definer.clean(['$', '_']);

См. также: опция clean

Сборка

Представим, что имеется следующая файловая структура:

modules/
    sub/c.js
    a.js
    b.js

Находясь в директории modules для сборки проекта достаточно выполнить одну команду.

./node_modules/.bin/definer all.js

В процессе сборки definer выполнит рекурсивный поиск модулей в файлах *.js текущей директории и собранный результат будет сохранён в файл all.js:

(function(global, undefined) {
var a = (function () { return 'a'; }).call(global),
    b = (function () { return 'b'; }).call(global),
    c = (function (a, b) { return a + b + 'c'; }).call(global, a, b);
})(this);

Опции сборки

По имеющимся опциям можно получить краткую справку прямо в терминале.

./node_modules/.bin/definer --help

Опция -c, --config

Если директория, в которой выполняется запуск definer, содержит файл definer.json — сборщик использует его как конфигурационный файл автоматически.

Опция указывает на конфигурационный файл, содержащий все возможные опции сборки в JSON-формате.

./node_modules/.bin/definer -c config/definer.json all.js

Пути до директорий и файлов следует указывать относительно расположения конфигурационного файла.

Опции, введённые в командной строке имеют приоритет над опциями из конфигурационного файла.

Опция -d, --directory

Опция указывает откуда следует начать искать модули в файловой системе. Поиск модулей выполняется рекурсивно по всем вложенным директориям.

./node_modules/.bin/definer -d modules/ all.js

Возможно указание нескольких директорий через запятую.

./node_modules/.bin/definer -d modules/,modules2/ all.js

По умолчанию definer ищет модули в текущей директории.

Опция -p, --postfix

Опция задаёт постфикс файлов, в которых будет производиться поиск модулей.

./node_modules/.bin/definer -p module.js all.js

По умолчанию опции установлено значение js.

Опция -m, --module

Опция позволяет указать имя модуля, для которого необходимо выполнить сборку. В результирующий файл попадут только те модули, которые необходимы для указанного модуля.

./node_modules/.bin/definer -m c all.js

По умолчанию собираются все найденные модули.

Опция -i, --istanbul

Опция позволяет перечислить имена модулей, для которых предполагается запуск istanbul. Для всех остальных модулей будет добавлен комментарий, исключающий их из оценки покрытия тестами.

./node_modules/.bin/definer -i b all.js

Возможно указание нескольких модулей через запятую.

./node_modules/.bin/definer -i b,c all.js

По умолчанию комментарии не добавляются, поскольку запуск оценки покрытия тестами не предполагается.

Опция -v, --verbose

Опция настраивает вывод информации о сборке.

Информация делится на типы:

1. l, log — информация о процессе сборки (синим цветом)
2. i, info — сообщение о результате сборки (зелёным)
3. w, warn — предупреждения (жёлтым)
4. e, error — ошибки (красным)

Следующий пример будет выводить только предупреждения и ошибки:

./node_modules/.bin/definer -v we all.js

Идентичный пример опции в конфигурационном файле:

{
    "verbose": ["warn", "error"]
}

По умолчанию выводятся все типы информации.

Опция clean

Опция может быть указана только в конфигурационном файле.

Опция указывает пути до файлов, хранящих переменные глобального контекста. Содержимое этих файлов будет включено в результат сборки.

Несколько файлов могут быть объединены в массив, при этом они будут собраны в указанном порядке.

{
    "clean": {
        "$": [
            "jquery.js",
            "jquery.ui.js",
            "jquery.mobile.js"
        ],
        "_": "path/to/underscore.js"
    }
}

См. также: метод clean

Опция jsdoc

Опция может быть указана только в конфигурационном файле.

Опция формирует JSDoc, содержащий информацию о собранном файле.

Возможно указание относительного пути до JSON-файла, из которого сборщик получит значение одноимённого поля.

Тег date способен принять значение true и заменить его на текущую дату.

{
    "jsdoc": {
        "file": "File description",
        "copyright": "2014 Artem Kurbatov, tenorok.ru",
        "license": "MIT license",
        "version": "another.json",
        "date": true
    }
}

Результат может выглядеть примерно так:

/*!
 * @file File description
 * @copyright 2014 Artem Kurbatov, tenorok.ru
 * @license MIT license
 * @version 0.0.7
 * @date 16 June 2014
 */