need/README.md

Advanced node.js script loader with comparisons to built-in require

# need

need is a script loader for node.js. It acts as both a replacement and companion to the built-in *require* function. It takes the fundamental ideas of *require* and adapts them to have a tighter integration with your node.js application.

*require* is a great tool for including external node modules in to an application. However it falls short on internal node modules. *need* aims to fix this without forcing major structural changes within an application.

## Basic Usage

### require

To use need, simply run the following command in the root of your application:

	npm install need
	
Then include the following line in your node.js application:

	var need = require('need');
	
*need* has its own *require* function that acts independantly to the built-in function. The following line demonstrates how at first glance *need* is almost identical to *require*. The function returns the exports from the required file just as *require* does.

	var exported = need('./a');
	
This function will first attempt to look for *./a.js* and if a matching file is not found then it will attempt to find a file at *./a/index.js*. It is possible to override this behavior by specifying an alternate fall-back path however should only be used if absolutely required.

### scope

./

### file extensions

You should not include the file extension when requiring a file. *need* will always search for the file name before attempting the file extension and so including a file extension will first search for a file with a double-extension. For example:

	# example.js
	module.exports = function() { console.log('This one') }
	
	# example.js.js
	module.exports = function() { console.log('Not this one') }
	
	# app.js
	need('example.js')()
	
	# console:
	Not this one
	
If the file *example.js.js* did not exist then it would fall back to *example.js*.

### need many

*need* offers the ability to require multiple files at the same time. For example:

	need(['./a', './b']);

The output here is a key-value pair of paths and exports. Multiple keys may point to the same exports. For example:

	# models/index.js
	module.exports = function() { console.log('Models') }
	
	# controllers.js
	module.exports = function() { console.log('Controllers') }
	
	# app.js
	var needs = need(['./models', './controllers']);
	
	needs.get('./models')();
	needs.get('./models/index')();
	
	needs.get('./controllers')();
	needs.get('./controllers/index')();
	
	# console:
	Models
	Models
	Controllers
	[ Error ]
	
### need anything

*need* allows the use of wildcards to require multiple files without being specific. For example:

	need([
		'a/b/', // require b/index.js
		'a/b',  // require b.js, fall back to b/index.js
		'a/*/,  // recursive require in sub-directories of a
		'a/*',  // recursive require in a
		'*'     // recursive require in current directory
	]);
	
If you require a single path that includes a wildcard then the output will always be a key-value pair. If there is any uncertainty in whether a path fill include a wildcard, for example when the path is generated from another function, then simply enclose the input as though it was an array.

### need function

If *need* encounters a function then it will evaluate the function and add the results to be required. For example:

	need(function() { return ['a/b', 'd/e'] });

### need object

if *need* encounters an object instead of a string or array then it will loop through the object and add the keys to be required. For example:

	need({
		'a/b': function(){},
		'd/e': function(){}
	});
	
Note that the functions here do not do anything. The purpose of these are explained below.

### need nesting

*need* allows you to nest the various different inputs that it accepts. For example:

	need([
		['a/b', 'c/d'],
		function() {
			return 'e/f'
		},
		{
			'g/h': function(){},
			'i/j': function(){}
		}
	]);

## Advanced Usage

### need namespaces

*need* allows you to define directory namespaces to split code up in to a more logical format. For example:

	# example.js
	var models = need.set('models', './models');

This namespace can then be accessed from anywhere in an application. The best use of this functionality is when trying to require a file that is several levels away or when requiring multiple files in the same directory. The idea is to make the code cleaner and easier to understand.

	# a/b/c/d/e/example.js
	var models = need.get('models');

The result of getting or setting will be a subclass of the *need* function with the root set to the specified directory in the set function. You can then use the returned function to require files. For example:

	models(['a/b', 'c/d']);
	
This code may not be very clear as there is no longer any mention of *need*. While the above still works it may be beneficial to use the following syntax:

	models.need(['a/b', 'c/d']);

Or alternatively:

	models.require(['a/b', 'c/d']);
	
Both functions work identically to that of the subclassed *need* function. If you wish, these functions are also exposed on the root *need* function so you can use the following syntax:

	need.need(['a/b', 'c/d']);
	need.require(['a/b', 'c/d']);
	
These namespaces can go as deep as you like and can only be accessed from the parent namespace. For example:

	# file1.js
	var models = need.set('models', './models'),
		people = models.set('people', 'people');
	
	# file2.js
	var people = need.get('people'); // Error
		
### callback parameter

*need* accepts a callback function as a second parameter. This function is passed three parameters.

	need(['a/b', 'c/d'], function(send, each, pair) {
		// ...
	});
	
#### send

This is one of the core features of *need* and is the reason why it was developed. The idea was to make it easy to send *app* and other variables to multiple files. *send* is a function that can be called to evaluate the exports from each required file. This only applies to exports that are functions:

	# a/b.js
	exports.something = function(input) {
		console.log('a/b says: ' + input);
	}
	
	# c/d.js
	module.exports = function(input) {
		console.log('c/d says: ' + input);
	}
	
	# app.js
	need(['a/b', 'c/d'], function(send, each, pair) {
		send('Hello World!');
	});
	
	# console:
	c/d says: Hello World!
	
In the above example only *c/d.js* actually exported a function via *module.exports*. *send* then made it easy to pass values on to other files.

Of course there may be situations where you do not wish all required files to be evaluated and sent parameters. In these cases it would be advised to use a seperate *need* function or alternatively use *each*. *send* is also exposed in a more general form on the *need* variable.

#### each

*each* is a function that allows you to perform actions on each file individually. *each* is also exposed in a more general form on the *need* variable.

	# a/b.js
	module.exports = function(input) {
		console.log('a/b says: ' + input);
	}
	
	# c/d.js
	module.exports = function(input) {
		console.log('c/d says: ' + input);
	}

	# app.js
	need(['a/b', 'c/d'], function(s, each, p) {
		each(function(send, match, key, val) {
			send(key);
		});
	});
	
	# console:
	a/b says: a/b
	c/d says: c/d

In the above example each of the required functions is sent its own path.
	
#### match

*match* is only available within *each*. It evaluates a given path to see if it matches another path. *match* is also exposed on the *need* variable.

	# a/b.js
	module.exports = function(input) {
		console.log('a/b says: ' + input);
	}
	
	# c/d.js
	module.exports = function(input) {
		console.log('c/d says: ' + input);
	}
	
	# app.js
	need(['a/b', 'c/d'], function(s, each, p) {
		each(function(send, match, key, val) {
			if (match(key, 'a/*')) {
				send('Matched!');
			} else {
				send('Not matched!');
			}
		});
	});
	
	# console:
	a/b says: Matched!
	c/d says: Not matched!
	
In the above example, *match* is used to check whether the required file is within the specified directory and sends different commands depending on whether the result is true or false.

#### pair

This is the key-value object that would normally be returned from the *need* function.

#### return

The callback function is allowed to return a value. By default if nothing is returned then *need* will return the key-value pair. If the callback returns a value then this value will be returned from *need*.

### config parameter

*need* accepts a config object as a second parameter.

	need(['a/b', 'c/d'], {
		ordered: false, // default true. Set to false if required files do not need to be synchronously required in a specific order.
		logging: true, // default false. Set to true to log warnings, errors
		recurse: false, // default true. Set to false to stop recursive require
		pattern: ['*Controller'], // only require files matching pattern
		ignores: ['a/b/*'], // ignore files matching pattern/path
		success: function(){} // The callback function
	});

### logging

.

## Something

…

modules/ index.js only, not models.js
	
	var application = need.set('application', './'),
		controllers = need.set('controllers', './controllers'),
		models      = need.set('models',      './models'),
		routes      = need.set('routes',      './routes'),
		config      = need.set('config',      './config');
		
		
	need('a/{dir}/*'); // a/b/c -> c: b
	need('a/{dir}/x'); // a/b/c/x -> x: b/c
	
sending

need.send
need.each
need.match
	
future improvements:
support loading modules
support loading json
watch directory for moving files
warning levels 0 == false == off, 1 == error, 2 == warn+error, 3 == warn+error+log