require2

IMPORTANT!!! This package is currently in being drafted. All suggestions to how it should work are welcomed! No implementation is provided for now until some parts of the interface are agreed upon.

Next-gen require() functionality for NodeJS.
This includes requireing multiple files at once using glob patterns and custom strategies for requireing.

Installation

Usage

var require2, includes, templates;
require2 = require('require2').bind(global);

// the following
includes = require2('./includes/*.js');
// is equivalent to
includes = [require('./includes/include1.js'), require('./includes/include2.js')];

// and the following
templates = require2('./templates/*.hbs', {
              strategy: 'object',
              keys: ['path-reduce', 'strip-extension']
            });
// is equivalent to
templates = {
              'template1': require('./templates/template1.hbs'),
              'template2': require('./templates/template2.hbs')
            };

Interface of require2(pattern [, options])

Pattern must be a string and can be a traditional module identifier (same as original require) or a glob pattern.
The second parameter to require must be an object and supports the following keys:

strategy [optional, default: 'array']

The strategy parameter can be provided in two formats:

• 'name-of-strategy'
• ['name-of-strategy', ...options-for-strategy]

Possible values are

• 'array': requires all matched files in order and returns them as an array.

• 'map': returns an object.

Every matched file is represented by a key and it's respective require call as the value. The keys are generated by the option of the same name as the strategy.

• function(base, files, config) { return /* whatever you want */; }

You can provide a custom function. It takes the parameters base (the path of the file that is being transformed), files (an array that contains all the files matched by the glob, sorted on their full path) and config (the config object passed to the require call in the source file). If you believe your custom function is of general purpose to others, you can add a pull request for it.

• You can "globally" extend the require2 strategies by assigning to require('require2').strategies

require('require2/strategies')['my-custom-strategy'] = function(base, files, config) {
    return /* my-awesome-output */;
};

// from now on, you can do the following from any file
  require2('./my/glob/**/*', {strategy: 'my-custom-strategy'});

If you believe your strategy could benefit a lot of people, you can submit a pull request to have your strategy added to the main package or start an issue.

map [optional, default:["path-reduce", "strip-extension"]]

The list of functions to determine the key of a matched file when strategy: "map" is used. You can provide a single value, but you can also provide an array of these values. In the case an array is provided, the functions are executed in order to determine the final key.

Possible values are

• 'path'

Every file uses it's relative path (as returned by node-glob) as its key.

• 'strip-ext'

Every file has it's extension removed, but only if it would not cause a duplicate key.

• 'path-reduce'

Strips the common path from all matches.

• 'reduce-prefix'

Tries to reduce the key by determining the largest common prefix of each match and removing them from the matched filename.

• 'reduce-postfix'

Tries to reduce the key by determining the largest common postfix of each match and removing them from the matched filename.

• 'reduce'

Combination of reduce-prefix and reduce-postfix.

• function(base, files, config) { return {"/full/path/to/file": "key"} }

You can provide a custom function. It takes the parameters base (the path of the file that is being transformed), files (an object that contains all the files matched by the glob, using their full path as keys) and config (the config object passed to the require call in the source file).

• You can "globally" extend the require2 key resolvers by assigning to require('require2').keys

require('require2/keys')['my-custom-key'] = function(base, keyMap, config) {
    var i = 0, newKeyMap = {};
    for (file in keyMap) {
      newKeyMap[file] = '' + (i++); // just use numbers as keys
    }
    return newKeyMap;
};

// from now on, you can do the following from any file
  require2('./my/glob/**/*', {strategy: 'my-custom-strategy'});

If you believe your custom function is of general purpose to others, you can add a pull request for it.

• You are very welcome to suggest other options by starting an issue!.

glob [optional, default:{}]

This allows options to be provided to node-glob, which is used internally to find matching files.

Credits

Original concept based on require-globify.

License

MIT

Changelog

• 0.0.0-draft.* : First proposal of interface.