== Overview ==

This module allows you to include modules as components of your app elegantly using require('my-component') instead of require('../path/to/my-component.js').

To achieve this, a list of files is created in your node_modules folder that link to the actual modules. See the considerations for more information on how this works.

== Example ==

The following example shows what you need to do in order to get those three modules to be mapped to the short usual package names without them being an npm package in the node_modules folder:

// include this package
var shortnames = require('shortnames');

// map short module names to existing files
var result = shortnames({
	'database': './path/to/database-controller.js',
	'logger': './path/to/logging-controller.js',
	'template': './path/to/template.js'
});

// you can now access those modules directly
var database = require('database');
var logger = require('logger');
var template = require('template');

== Usage ==

=== Installation ===

Use npm to install this module:

npm install shortnames

=== Synchroneous use ===

resultObject = shortnames( moduleMap, [ options ] )

// resultObject holds information about what happened. // resultObject.error holds an error object if an error occurred.

=== Asynchroneous use* ===

shortnames( moduleMap, [ options ,] [ callback ] )

The callback function takes an error object (or null) and the resultObject as arguments:

callback = function (error, resultObject) {}

*: Even though this module allows for asynchroneous notation to be used, this functionality is only added for convenience and does in fact perform all I/O synchroneously.

=== Storing moduleMap in a JSON file ===

You can conveniently store your module mappings in a JSON file and use the require function to automatically parse it. Thus, the following is possible:

var results = shortnames( require('./components.json') [, options] );

Note that this requires the contents of components.json to be valid JSON, so be sure to follow its specification regarding quotes.

== Options ==

=== verify (boolean) ===

Whether or not to verify the integrity of already created link files. This options must be enabled for the overwrite option to have any effect.

Default value: true

=== overwrite (boolean) ===

Whether or not to overwrite files that already exist, but do not contain the assumed contents. Use this with care, especially if you have any .js files present in the root of your node_modules folder.

This flag does not have any effect, if the verify flag is set to false.

Default value: false

=== path (string) ===

The path from where to start looking for the modules that need to be mapped. If omitted, the location of the module that first required shortnames (!).

Default value: The directory of requiring module.

=== node_modules (string)===

The connecting JavaScript files will be put into this folder, if this option has been specified. By default, a node_modules folder in the directory that has been specified with the path option, will be assumed. If no path option is set, the node_modules folder of the module that first required shortnames (!) will be assumed.

If there is no node_modules folder present in the path, the parent directory will be searched.

Default value: The node_modules folder in the path directory.

== Considerations ==

To achieve the desired result, a list of files is created in your node_modules folder that link to the actual modules. This does not mess with npm as all npm packages are stored in an individual folder, not as plain JavaScript files.

This works because node will try to find the corresponding module for require('mymodule') as node_modules/mymodule.js in the nextmost node_modules folder.

Note that using this package is not "the node way" as its functionality and the effect on your code base can be confusing for other developers because it breaks the convention that components should either be accessed by relative path or as packaged modules via npm.

By default, this module does not overwrite any existing files, so no damage will accidently be done to existing files. But as a rule of thumb, do not use this module if you already manually populate your node_modules folder directly with plain .js files. You are already doing what the purpose of this module is.

== Changelog ==

=== v0.1.0 ===

Initial release of this module.

== License (MIT License)==

Copyright (C) 2013 Geerten van Meel

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.