lib/module.js

   1 // Copyright Joyent, Inc. and other Node contributors.
   2 //
   3 // Permission is hereby granted, free of charge, to any person obtaining a
   4 // copy of this software and associated documentation files (the
   5 // "Software"), to deal in the Software without restriction, including
   6 // without limitation the rights to use, copy, modify, merge, publish,
   7 // distribute, sublicense, and/or sell copies of the Software, and to permit
   8 // persons to whom the Software is furnished to do so, subject to the
   9 // following conditions:
  10 //
  11 // The above copyright notice and this permission notice shall be included
  12 // in all copies or substantial portions of the Software.
  13 //
  14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
  17 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
  18 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  19 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22 var NativeModule = require('native_module');
  23 var util = NativeModule.require('util');
  24 var runInThisContext = require('vm').runInThisContext;
  25 var runInNewContext = require('vm').runInNewContext;
  26 var assert = require('assert').ok;
  27 var fs = NativeModule.require('fs');
  28
  29
  30 // If obj.hasOwnProperty has been overridden, then calling
  31 // obj.hasOwnProperty(prop) will break.
  32 // See: https://github.com/joyent/node/issues/1707
  33 function hasOwnProperty(obj, prop) {
  34   return Object.prototype.hasOwnProperty.call(obj, prop);
  35 }
  36
  37
  38 function Module(id, parent) {
  39   this.id = id;
  40   this.exports = {};
  41   this.parent = parent;
  42   if (parent && parent.children) {
  43     parent.children.push(this);
  44   }
  45
  46   this.filename = null;
  47   this.loaded = false;
  48   this.children = [];
  49 }
  50 module.exports = Module;
  51
  52 // Set the environ variable NODE_MODULE_CONTEXTS=1 to make node load all
  53 // modules in their own context.
  54 Module._contextLoad = (+process.env['NODE_MODULE_CONTEXTS'] > 0);
  55 Module._cache = {};
  56 Module._pathCache = {};
  57 Module._extensions = {};
  58 var modulePaths = [];
  59 Module.globalPaths = [];
  60
  61 Module.wrapper = NativeModule.wrapper;
  62 Module.wrap = NativeModule.wrap;
  63
  64 var path = NativeModule.require('path');
  65
  66 Module._debug = util.debuglog('module');
  67
  68
  69 // We use this alias for the preprocessor that filters it out
  70 var debug = Module._debug;
  71
  72
  73 // given a module name, and a list of paths to test, returns the first
  74 // matching file in the following precedence.
  75 //
  76 // require("a.<ext>")
  77 //   -> a.<ext>
  78 //
  79 // require("a")
  80 //   -> a
  81 //   -> a.<ext>
  82 //   -> a/index.<ext>
  83
  84 function statPath(path) {
  85   try {
  86     return fs.statSync(path);
  87   } catch (ex) {}
  88   return false;
  89 }
  90
  91 // check if the directory is a package.json dir
  92 var packageMainCache = {};
  93
  94 function readPackage(requestPath) {
  95   if (hasOwnProperty(packageMainCache, requestPath)) {
  96     return packageMainCache[requestPath];
  97   }
  98
  99   try {
 100     var jsonPath = path.resolve(requestPath, 'package.json');
 101     var json = fs.readFileSync(jsonPath, 'utf8');
 102   } catch (e) {
 103     return false;
 104   }
 105
 106   try {
 107     var pkg = packageMainCache[requestPath] = JSON.parse(json).main;
 108   } catch (e) {
 109     e.path = jsonPath;
 110     e.message = 'Error parsing ' + jsonPath + ': ' + e.message;
 111     throw e;
 112   }
 113   return pkg;
 114 }
 115
 116 function tryPackage(requestPath, exts) {
 117   var pkg = readPackage(requestPath);
 118
 119   if (!pkg) return false;
 120
 121   var filename = path.resolve(requestPath, pkg);
 122   return tryFile(filename) || tryExtensions(filename, exts) ||
 123          tryExtensions(path.resolve(filename, 'index'), exts);
 124 }
 125
 126 // In order to minimize unnecessary lstat() calls,
 127 // this cache is a list of known-real paths.
 128 // Set to an empty object to reset.
 129 Module._realpathCache = {};
 130
 131 // check if the file exists and is not a directory
 132 function tryFile(requestPath) {
 133   var stats = statPath(requestPath);
 134   if (stats && !stats.isDirectory()) {
 135     return fs.realpathSync(requestPath, Module._realpathCache);
 136   }
 137   return false;
 138 }
 139
 140 // given a path check a the file exists with any of the set extensions
 141 function tryExtensions(p, exts) {
 142   for (var i = 0, EL = exts.length; i < EL; i++) {
 143     var filename = tryFile(p + exts[i]);
 144
 145     if (filename) {
 146       return filename;
 147     }
 148   }
 149   return false;
 150 }
 151
 152
 153 Module._findPath = function(request, paths) {
 154   var exts = Object.keys(Module._extensions);
 155
 156   if (request.charAt(0) === '/') {
 157     paths = [''];
 158   }
 159
 160   var trailingSlash = (request.slice(-1) === '/');
 161
 162   var cacheKey = JSON.stringify({request: request, paths: paths});
 163   if (Module._pathCache[cacheKey]) {
 164     return Module._pathCache[cacheKey];
 165   }
 166
 167   // For each path
 168   for (var i = 0, PL = paths.length; i < PL; i++) {
 169     var basePath = path.resolve(paths[i], request);
 170     var filename;
 171
 172     if (!trailingSlash) {
 173       // try to join the request to the path
 174       filename = tryFile(basePath);
 175
 176       if (!filename && !trailingSlash) {
 177         // try it with each of the extensions
 178         filename = tryExtensions(basePath, exts);
 179       }
 180     }
 181
 182     if (!filename) {
 183       filename = tryPackage(basePath, exts);
 184     }
 185
 186     if (!filename) {
 187       // try it with each of the extensions at "index"
 188       filename = tryExtensions(path.resolve(basePath, 'index'), exts);
 189     }
 190
 191     if (filename) {
 192       Module._pathCache[cacheKey] = filename;
 193       return filename;
 194     }
 195   }
 196   return false;
 197 };
 198
 199 // 'from' is the __dirname of the module.
 200 Module._nodeModulePaths = function(from) {
 201   // guarantee that 'from' is absolute.
 202   from = path.resolve(from);
 203
 204   // note: this approach *only* works when the path is guaranteed
 205   // to be absolute.  Doing a fully-edge-case-correct path.split
 206   // that works on both Windows and Posix is non-trivial.
 207   var splitRe = process.platform === 'win32' ? /[\/\\]/ : /\//;
 208   var paths = [];
 209   var parts = from.split(splitRe);
 210
 211   for (var tip = parts.length - 1; tip >= 0; tip--) {
 212     // don't search in .../node_modules/node_modules
 213     if (parts[tip] === 'node_modules') continue;
 214     var dir = parts.slice(0, tip + 1).concat('node_modules').join(path.sep);
 215     paths.push(dir);
 216   }
 217
 218   return paths;
 219 };
 220
 221
 222 Module._resolveLookupPaths = function(request, parent) {
 223   if (NativeModule.exists(request)) {
 224     return [request, []];
 225   }
 226
 227   var start = request.substring(0, 2);
 228   if (start !== './' && start !== '..') {
 229     var paths = modulePaths;
 230     if (parent) {
 231       if (!parent.paths) parent.paths = [];
 232       paths = parent.paths.concat(paths);
 233     }
 234     return [request, paths];
 235   }
 236
 237   // with --eval, parent.id is not set and parent.filename is null
 238   if (!parent || !parent.id || !parent.filename) {
 239     // make require('./path/to/foo') work - normally the path is taken
 240     // from realpath(__filename) but with eval there is no filename
 241     var mainPaths = ['.'].concat(modulePaths);
 242     mainPaths = Module._nodeModulePaths('.').concat(mainPaths);
 243     return [request, mainPaths];
 244   }
 245
 246   // Is the parent an index module?
 247   // We can assume the parent has a valid extension,
 248   // as it already has been accepted as a module.
 249   var isIndex = /^index\.\w+?$/.test(path.basename(parent.filename));
 250   var parentIdPath = isIndex ? parent.id : path.dirname(parent.id);
 251   var id = path.resolve(parentIdPath, request);
 252
 253   // make sure require('./path') and require('path') get distinct ids, even
 254   // when called from the toplevel js file
 255   if (parentIdPath === '.' && id.indexOf('/') === -1) {
 256     id = './' + id;
 257   }
 258
 259   debug('RELATIVE: requested:' + request +
 260         ' set ID to: ' + id + ' from ' + parent.id);
 261
 262   return [id, [path.dirname(parent.filename)]];
 263 };
 264
 265
 266 // Check the cache for the requested file.
 267 // 1. If a module already exists in the cache: return its exports object.
 268 // 2. If the module is native: call `NativeModule.require()` with the
 269 //    filename and return the result.
 270 // 3. Otherwise, create a new module for the file and save it to the cache.
 271 //    Then have it load  the file contents before returning its exports
 272 //    object.
 273 Module._load = function(request, parent, isMain) {
 274   if (parent) {
 275     debug('Module._load REQUEST  ' + (request) + ' parent: ' + parent.id);
 276   }
 277
 278   var filename = Module._resolveFilename(request, parent);
 279
 280   var cachedModule = Module._cache[filename];
 281   if (cachedModule) {
 282     return cachedModule.exports;
 283   }
 284
 285   if (NativeModule.exists(filename)) {
 286     // REPL is a special case, because it needs the real require.
 287     if (filename == 'repl') {
 288       var replModule = new Module('repl');
 289       replModule._compile(NativeModule.getSource('repl'), 'repl.js');
 290       NativeModule._cache.repl = replModule;
 291       return replModule.exports;
 292     }
 293
 294     debug('load native module ' + request);
 295     return NativeModule.require(filename);
 296   }
 297
 298   var module = new Module(filename, parent);
 299
 300   if (isMain) {
 301     process.mainModule = module;
 302     module.id = '.';
 303   }
 304
 305   Module._cache[filename] = module;
 306
 307   var hadException = true;
 308
 309   try {
 310     module.load(filename);
 311     hadException = false;
 312   } finally {
 313     if (hadException) {
 314       delete Module._cache[filename];
 315     }
 316   }
 317
 318   return module.exports;
 319 };
 320
 321 Module._resolveFilename = function(request, parent) {
 322   if (NativeModule.exists(request)) {
 323     return request;
 324   }
 325
 326   var resolvedModule = Module._resolveLookupPaths(request, parent);
 327   var id = resolvedModule[0];
 328   var paths = resolvedModule[1];
 329
 330   // look up the filename first, since that's the cache key.
 331   debug('looking for ' + JSON.stringify(id) +
 332         ' in ' + JSON.stringify(paths));
 333
 334   var filename = Module._findPath(request, paths);
 335   if (!filename) {
 336     var err = new Error("Cannot find module '" + request + "'");
 337     err.code = 'MODULE_NOT_FOUND';
 338     throw err;
 339   }
 340   return filename;
 341 };
 342
 343
 344 // Given a file name, pass it to the proper extension handler.
 345 Module.prototype.load = function(filename) {
 346   debug('load ' + JSON.stringify(filename) +
 347         ' for module ' + JSON.stringify(this.id));
 348
 349   assert(!this.loaded);
 350   this.filename = filename;
 351   this.paths = Module._nodeModulePaths(path.dirname(filename));
 352
 353   var extension = path.extname(filename) || '.js';
 354   if (!Module._extensions[extension]) extension = '.js';
 355   Module._extensions[extension](this, filename);
 356   this.loaded = true;
 357 };
 358
 359
 360 // Loads a module at the given file path. Returns that module's
 361 // `exports` property.
 362 Module.prototype.require = function(path) {
 363   assert(util.isString(path), 'path must be a string');
 364   assert(path, 'missing path');
 365   return Module._load(path, this);
 366 };
 367
 368
 369 // Resolved path to process.argv[1] will be lazily placed here
 370 // (needed for setting breakpoint when called with --debug-brk)
 371 var resolvedArgv;
 372
 373
 374 // Run the file contents in the correct scope or sandbox. Expose
 375 // the correct helper variables (require, module, exports) to
 376 // the file.
 377 // Returns exception, if any.
 378 Module.prototype._compile = function(content, filename) {
 379   var self = this;
 380   // remove shebang
 381   content = content.replace(/^\#\!.*/, '');
 382
 383   function require(path) {
 384     return self.require(path);
 385   }
 386
 387   require.resolve = function(request) {
 388     return Module._resolveFilename(request, self);
 389   };
 390
 391   Object.defineProperty(require, 'paths', { get: function() {
 392     throw new Error('require.paths is removed. Use ' +
 393                     'node_modules folders, or the NODE_PATH ' +
 394                     'environment variable instead.');
 395   }});
 396
 397   require.main = process.mainModule;
 398
 399   // Enable support to add extra extension types
 400   require.extensions = Module._extensions;
 401   require.registerExtension = function() {
 402     throw new Error('require.registerExtension() removed. Use ' +
 403                     'require.extensions instead.');
 404   };
 405
 406   require.cache = Module._cache;
 407
 408   var dirname = path.dirname(filename);
 409
 410   if (Module._contextLoad) {
 411     if (self.id !== '.') {
 412       debug('load submodule');
 413       // not root module
 414       var sandbox = {};
 415       for (var k in global) {
 416         sandbox[k] = global[k];
 417       }
 418       sandbox.require = require;
 419       sandbox.exports = self.exports;
 420       sandbox.__filename = filename;
 421       sandbox.__dirname = dirname;
 422       sandbox.module = self;
 423       sandbox.global = sandbox;
 424       sandbox.root = root;
 425
 426       return runInNewContext(content, sandbox, { filename: filename });
 427     }
 428
 429     debug('load root module');
 430     // root module
 431     global.require = require;
 432     global.exports = self.exports;
 433     global.__filename = filename;
 434     global.__dirname = dirname;
 435     global.module = self;
 436
 437     return runInThisContext(content, { filename: filename });
 438   }
 439
 440   // create wrapper function
 441   var wrapper = Module.wrap(content);
 442
 443   var compiledWrapper = runInThisContext(wrapper, { filename: filename });
 444   if (global.v8debug) {
 445     if (!resolvedArgv) {
 446       // we enter the repl if we're not given a filename argument.
 447       if (process.argv[1]) {
 448         resolvedArgv = Module._resolveFilename(process.argv[1], null);
 449       } else {
 450         resolvedArgv = 'repl';
 451       }
 452     }
 453
 454     // Set breakpoint on module start
 455     if (filename === resolvedArgv) {
 456       global.v8debug.Debug.setBreakPoint(compiledWrapper, 0, 0);
 457     }
 458   }
 459   var args = [self.exports, require, self, filename, dirname];
 460   return compiledWrapper.apply(self.exports, args);
 461 };
 462
 463
 464 function stripBOM(content) {
 465   // Remove byte order marker. This catches EF BB BF (the UTF-8 BOM)
 466   // because the buffer-to-string conversion in `fs.readFileSync()`
 467   // translates it to FEFF, the UTF-16 BOM.
 468   if (content.charCodeAt(0) === 0xFEFF) {
 469     content = content.slice(1);
 470   }
 471   return content;
 472 }
 473
 474
 475 // Native extension for .js
 476 Module._extensions['.js'] = function(module, filename) {
 477   var content = fs.readFileSync(filename, 'utf8');
 478   module._compile(stripBOM(content), filename);
 479 };
 480
 481
 482 // Native extension for .json
 483 Module._extensions['.json'] = function(module, filename) {
 484   var content = fs.readFileSync(filename, 'utf8');
 485   try {
 486     module.exports = JSON.parse(stripBOM(content));
 487   } catch (err) {
 488     err.message = filename + ': ' + err.message;
 489     throw err;
 490   }
 491 };
 492
 493
 494 //Native extension for .node
 495 Module._extensions['.node'] = process.dlopen;
 496
 497
 498 // bootstrap main module.
 499 Module.runMain = function() {
 500   // Load the main module--the command line argument.
 501   Module._load(process.argv[1], null, true);
 502   // Handle any nextTicks added in the first tick of the program
 503   process._tickCallback();
 504 };
 505
 506 Module._initPaths = function() {
 507   var isWindows = process.platform === 'win32';
 508
 509   if (isWindows) {
 510     var homeDir = process.env.USERPROFILE;
 511   } else {
 512     var homeDir = process.env.HOME;
 513   }
 514
 515   var paths = [path.resolve(process.execPath, '..', '..', 'lib', 'node')];
 516
 517   if (homeDir) {
 518     paths.unshift(path.resolve(homeDir, '.node_libraries'));
 519     paths.unshift(path.resolve(homeDir, '.node_modules'));
 520   }
 521
 522   var nodePath = process.env['NODE_PATH'];
 523   if (nodePath) {
 524     paths = nodePath.split(path.delimiter).concat(paths);
 525   }
 526
 527   modulePaths = paths;
 528
 529   // clone as a read-only copy, for introspection.
 530   Module.globalPaths = modulePaths.slice(0);
 531 };
 532
 533 // bootstrap repl
 534 Module.requireRepl = function() {
 535   return Module._load('repl', '.');
 536 };
 537
 538 Module._initPaths();
 539
 540 // backwards compatibility
 541 Module.Module = Module;