dazagrohovaz / require5.js

Require5.JS: almost like NodeJS style require-Function for the browser require javascript

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.

require5.js's Issues

XHR CROSS-DOMAIN SUPPORT

Hi everone,

I have read in detail about how other libraries work, about api, and xhr, and cross-domain, and ..., and ....
reaching the conclusion all libraries have similar features but different purposes.

I know, you are thiking, XHR doesn't support cross-domain (this because are you here).
either my library, and I don't plan to integrate this support into my library, as the target of this is to run the code on closed modules, and cache the scripts into the HTML5 These Storage to reduce data traffic. If i load each script with the document.createElement function, i can't access to the source, i need the source to save it into the storage.

About the functionallity of the library: the parent module only need to know the path of the child, and the child module doesn't need to know who called him. the child module can call anothers 'brothers' (modules on same path, same folder) easily and shortly. Alias-names for the modules can be defines with the function unshift (almost like nodejs). And they parse data with into the module.exports object.

Unfortunately ALL this works only in the same domain, just like every computer on the world. If I want run the code or only read data from another machine, first i need to request the necessary permissions.
This should work only if the other server allow XHR requets from another Origin, with the OPTION header "Access-Control-Allow-Origin", otherwise... forget it.

Libraries like jQuery, dojo, mootools, etc. need to be global, and "cann't be modified", like example, if i load jQuery from http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js to get allways the last one, i cann't modified or read it, to run his code into closed module, or save then into the storage.
For this problem we have a server-side solution, the proxy... ;-)

Now, THANKS to James Burke(https://github.com/jrburke), author of require.js (http://requirejs.org/) for the advice about the eval function. I've maked a better solution to load the script, now runs much better, leaving less traces.

regards