Require5.JS

almost like NodeJS style require-Function for the browser require javascript

Features:

• load, compile and run scripts once.
  
• support sync and async XHR requests.
  
• storage the scripts on HTML5 Storage if available.
  
• data transfer only if required, load scripts from storage or cache if available (no transfer), otherwise load scripts via XHR (data transfer).
  
• cross-domain requests (don't support data storage or other features, just push the scripts into the document's head tag)
  

Supported Methods

(see the example bellow)

• Synchronic
  

  var sync = require('./path/to/scripts/file.js');
  console.log(sync.works);       // returns 'yes, it\' works...!!'

• Asynchronic
  

  require('./path/to/scripts/file.js', function(exports){
    var async = exports;
    console.log(async.works);    // returns 'yes, it\' works...!!'
  });

Example

• file.js
  

var counter = 0;

// How to overwrite exports with a function
exports = module.exports = function inc(){
  return ++counter;
};

exports.reset = function(){
  return counter = 0;
};

exports.works = 'yes, it\' works...!!';

Working with the 'unshift' function

The unshift function is more like an alias, define a shortname for access quickly to the javascript files

• Example
  

  require.paths.unshift('file', 'lib/scripts/file.js');
  var unshift = require('file');

  console.log(unshift.works);    // returns 'yes, it\' works...!!'

The Example Site

Concept / Idea

  foo.js is the application, but it depends from other scripts, like jQuery. Normaly, these need to be loaded first.
  Well in this case 'foo.js' depends from 'bar.js'.

The structure of the site

  http://www.example.com/index.html
  http://www.example.com/path/to/scripts/foo.js  // depends from bar.js
  http://www.example.com/path/to/scripts/bar.js

Into the index.html file

The "normal" ways to implement and run these scripts (foo & bar) into the page are

* first 'bar.js' because 'foo.js' depends of this one

  <script src="path/to/scripts/bar.js"></script> or
  <script src="/path/to/scripts/bar.js"></script> or
  <script src="./path/to/scripts/bar.js"></script>
  <script src="http://www.example.com/path/to/scripts/bar.js"></script>

* then 'foo.js'

  <script src="./path/to/scripts/foo.js"></script>

Now the same with Require5.JS, with a few changes

The structure of example site with Require5.JS

  http://www.example.com/index.html
  http://www.example.com/path/to/require/require5.js
  http://www.example.com/path/to/scripts/foo.js  // depends of bar.js
  http://www.example.com/path/to/scripts/bar.js

Into the index.html file

  <script src="./path/to/require/require5.js"></script>
  <script>
    require.paths.unshift('foo', './path/to/scripts/foo.js');
    require('foo');
  </script>

at the top of the 'foo.js' file

  require('./bar.js');
  // then the code

Other Features and Properties of Require5.JS

Private Values

  __dirname  : following the previous example, into 'foo.js' it will return 'http://www.example.com/path/to/scripts/'
  __filename : following the previous example, into 'foo.js' it will return 'foo.js'

The 'require.paths' Attribute

  return a object with all module-paths and their status

  - 'loaded'   : the script is on storage
  - 'fails'    : the script couldn't be loaded or compiled
  - 'unschift' : only an alias name was setted for this script, it is not used any time
  - 'ready'    : the script is loaded and compiled
  - undefined  : the script isn't used, defined or called

  { 'http://www.example.com/path/to/scripts/foo.js': 'unschift', 'http://www.example.com/path/to/scripts/bar.js': 'loaded' }

The 'require.alias' Attribute

  return a object with all alias and their paths

  { 'foo': 'http://www.example.com/path/to/scripts/foo.js' }
  

The Unshift-Function's returned Value:

Alias-Names for Script-Files with Path recognition

  var path = require.paths.unshift('foo', './path/to/scripts/foo.js');
  // if the Unshift-Function was called at http://www.example.com/index.html
  // returns 'http://www.example.com/path/to/scripts/foo.js'

  var path = require.paths.unshift('bar', './bar.js');
  // if the Unshift-Function was called at http://www.example.com/path/to/scripts/foo.js
  // returns 'http://www.example.com/path/to/scripts/bar.js'

The Resolve-Function's returned Object:

Path, Alias and Status recognition

  var res = require.resolve('foo');
  // returns a object with 3 elements, the alias (setted with unshift), the path and the status

  { alias: 'foo', path: 'http://www.example.com/path/to/scripts/foo.js', status: 'unshift' }


  var res = require.resolve('./bar.js');
  // if the Unshift-Function was called at http://www.example.com/path/to/scripts/foo.js
  // returns a object with 3 elements, the alias, the path, and the status

  { alias: undefined, path: 'http://www.example.com/path/to/scripts/bar.js', status: 'loaded' }
  

The Require-Function's returned Arguments:

exports, module, require, __dirname, __filename

  function requestHandler(exports, module, require, __dirname, __filename){
    // require continue to work as it will be at 'http://www.example.com/path/to/scripts/foo.js'
    require('./bar.js');

    // do something
    console.log(__filename);      // returns 'foo.js'
    console.log(__dirname);       // returns 'http://www.example.com/path/to/scripts/'
    console.log(exports.works);   // returns 'yes, it\' works...!!'
  }
  require(./path/to/scripts/foo.js', requestHandler);

The Require-Function's returned getContext-Function:

Access to the Module-Context of Asynchronic Calls

  var async = require('./path/to/scripts/foo.js', function(){
    var context = async();
    context.require('./bar.js');

    // do something
    console.log(context.__filename);      // returns 'foo.js'
    console.log(context.__dirname);       // returns 'http://www.example.com/path/to/scripts/'
    console.log(context.exports.works);   // returns 'yes, it\' works...!!'
  });

Cross-Domain Calls

These are complete asynchronic and don't support storage or other features, just push scripts into the documen'st head tag,
for example: We use this to load outside libraries like jQuery or MooTools from googleapis.com to get allways the last one.

  // with callback
  require('http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js', function(state){
    if(state == 'ready') console.log('great!')
  });

  // without callback
  require.paths.unshift('jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js')
  var ret = require('jquery');

  function sayGreat(){
    if(ret().ready){
      console.log('great!');
    }else{
      setTimeout(sayGreat, 10);
    }
  }
  setTimeout(sayGreat, 10);

####
Require5.JS
###### almost like NodeJS style require-Function for the browser require javascript
(c) DazaGrohovaz.Net / ProxyJS.com

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.