fs.stat third parameter controlling error creation

In some environment (especially when coffescript is involved) module.js
will spend a lot of time looking up nonexisting files. This is caused by the
lengthy error creation. Those errors are then immediately caught.

This change makes the lookup much faster, by avoiding the unnecessary error
creation.

module::statPath now uses the new second parameter of fs.statSync function of the
fs.js. There is a similar change for the fs.stat, adding the third parameter.

Apply suggestions from libuv pull request

Thanks saghul: joyent/libuv#1428

Fix the datastructures for async

Documentation update

Add tests and simplify Stat function

Apply the code review comments

doc/api/fs.markdown

@@ -153,12 +153,15 @@ Only available on Mac OS X.
 
 Synchronous lchmod(2).
 
-## fs.stat(path, callback)
+## fs.stat(path, callback, [throwSafe])
 
 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
 `stats` is a [fs.Stats](#fs_class_fs_stats) object.  See the [fs.Stats](#fs_class_fs_stats)
 section below for more information.
 
+The throwSafe parameter if set to true prevents the error creation. If the call
+fails, the first parameter of the callback will be true.
+
 ## fs.lstat(path, callback)
 
 Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
@@ -172,10 +175,13 @@ Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
 `stats` is a `fs.Stats` object. `fstat()` is identical to `stat()`, except that
 the file to be stat-ed is specified by the file descriptor `fd`.
 
-## fs.statSync(path)
+## fs.statSync(path, [throwSafe])
 
 Synchronous stat(2). Returns an instance of `fs.Stats`.
 
+The throwSafe parameter if set to true prevents the error creation. If the call
+fails, the first parameter of the callback will be true.
+
 ## fs.lstatSync(path)
 
 Synchronous lstat(2). Returns an instance of `fs.Stats`.

lib/fs.js

@@ -114,14 +114,16 @@ function assertEncoding(encoding) {
   }
 }
 
-function nullCheck(path, callback) {
+function nullCheck(path, callback, throwSafe) {
   if (('' + path).indexOf('\u0000') !== -1) {
-    var er = new Error('Path must be a string without null bytes.');
-    if (!callback)
-      throw er;
-    process.nextTick(function() {
-      callback(er);
-    });
+    if (!throwSafe) {
+      var er = new Error('Path must be a string without null bytes.');
+      if (!callback)
+        throw er;
+      process.nextTick(function() {
+        callback(er);
+      });
+    }
     return false;
   }
   return true;
@@ -162,21 +164,30 @@ fs.Stats.prototype.isSocket = function() {
 };
 
 fs.exists = function(path, callback) {
-  if (!nullCheck(path, cb)) return;
-  binding.stat(pathModule._makeLong(path), cb);
-  function cb(err, stats) {
-    if (callback) callback(err ? false : true);
+  if (!nullCheck(path, undefined, true)) {
+    process.nextTick(function() {
+      cb(true, false);
+    });
+    return;
+  }
+  binding.stat(pathModule._makeLong(path), cb, true);
+  function cb(err, result) {
+    if (callback) {
+      if (err) {
+        callback(false);
+      } else {
+        callback(!!result);
+      }
+    }
   }
 };
 
 fs.existsSync = function(path) {
-  try {
-    nullCheck(path);
-    binding.stat(pathModule._makeLong(path));
-    return true;
-  } catch (e) {
+  if (!nullCheck(path, undefined, true))
     return false;
-  }
+  if (!binding.stat(pathModule._makeLong(path), undefined, true))
+    return false;
+  return true;
 };
 
 fs.readFile = function(path, options, callback_) {
@@ -675,10 +686,17 @@ fs.lstat = function(path, callback) {
   binding.lstat(pathModule._makeLong(path), callback);
 };
 
-fs.stat = function(path, callback) {
+fs.stat = function(path, callback, throwSafe) {
   callback = makeCallback(callback);
-  if (!nullCheck(path, callback)) return;
-  binding.stat(pathModule._makeLong(path), callback);
+  if (!nullCheck(path, callback, throwSafe)) {
+    if (throwSafe) {
+      process.nextTick(function() {
+        callback(true, false);
+      });
+    }
+    return;
+  }
+  binding.stat(pathModule._makeLong(path), callback, throwSafe);
 };
 
 fs.fstatSync = function(fd) {
@@ -690,9 +708,11 @@ fs.lstatSync = function(path) {
   return binding.lstat(pathModule._makeLong(path));
 };
 
-fs.statSync = function(path) {
-  nullCheck(path);
-  return binding.stat(pathModule._makeLong(path));
+fs.statSync = function(path, throwSafe) {
+  if (!nullCheck(path, undefined, throwSafe))
+    return false;
+
+  return binding.stat(pathModule._makeLong(path), undefined, throwSafe);
 };
 
 fs.readlink = function(path, callback) {

lib/module.js

@@ -87,10 +87,8 @@ var debug = Module._debug;
 
 function statPath(path) {
   var fs = NativeModule.require('fs');
-  try {
-    return fs.statSync(path);
-  } catch (ex) {}
-  return false;
+
+  return fs.statSync(path, true);
 }
 
 // check if the directory is a package.json dir