fs: Buffer and encoding enhancements to fs API

This makes several changes:

1. Allow path/filename to be passed in as a Buffer on fs methods
2. Add `options.encoding` to fs.readdir, fs.readdirSync, fs.readlink,
   fs.readlinkSync and fs.watch.
3. Documentation updates

For 1... it's now possible to do:

```js
fs.open(Buffer('/fs/foo/bar'), 'w+', (err, fd) => { });
```

For 2...
```js
fs.readdir('/fs/foo/bar', {encoding:'hex'}, (err,list) => { });

fs.readdir('/fs/foo/bar', {encoding:'buffer'}, (err, list) => { });
```

encoding can also be passed as a string

```js
fs.readdir('/fs/foo/bar', 'hex', (err,list) => { });
```

The default encoding is set to UTF8 so this addresses the
discrepency that existed previously between fs.readdir and
fs.watch handling filenames differently.

Fixes: https://github.com/nodejs/node/issues/2088
Refs: https://github.com/nodejs/node/issues/3519
PR-URL: https://github.com/nodejs/node/pull/5616
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>

1 files changed, 79 insertions, 27 deletions

diff --git a/lib/fs.js b/lib/fs.js
index de7af70e4b..f4a31a6f4d 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -903,17 +903,32 @@ fs.mkdirSync = function(path, mode) {
                        modeNum(mode, 0o777));
 };
 
-fs.readdir = function(path, callback) {
+fs.readdir = function(path, options, callback) {
+  options = options || {};
+  if (typeof options === 'function') {
+    callback = options;
+    options = {};
+  } else if (typeof options === 'string') {
+    options = {encoding: options};
+  }
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
+
   callback = makeCallback(callback);
   if (!nullCheck(path, callback)) return;
   var req = new FSReqWrap();
   req.oncomplete = callback;
-  binding.readdir(pathModule._makeLong(path), req);
+  binding.readdir(pathModule._makeLong(path), options.encoding, req);
 };
 
-fs.readdirSync = function(path) {
+fs.readdirSync = function(path, options) {
+  options = options || {};
+  if (typeof options === 'string')
+    options = {encoding: options};
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
   nullCheck(path);
-  return binding.readdir(pathModule._makeLong(path));
+  return binding.readdir(pathModule._makeLong(path), options.encoding);
 };
 
 fs.fstat = function(fd, callback) {
@@ -952,17 +967,31 @@ fs.statSync = function(path) {
   return binding.stat(pathModule._makeLong(path));
 };
 
-fs.readlink = function(path, callback) {
+fs.readlink = function(path, options, callback) {
+  options = options || {};
+  if (typeof options === 'function') {
+    callback = options;
+    options = {};
+  } else if (typeof options === 'string') {
+    options = {encoding: options};
+  }
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
   callback = makeCallback(callback);
   if (!nullCheck(path, callback)) return;
   var req = new FSReqWrap();
   req.oncomplete = callback;
-  binding.readlink(pathModule._makeLong(path), req);
+  binding.readlink(pathModule._makeLong(path), options.encoding, req);
 };
 
-fs.readlinkSync = function(path) {
+fs.readlinkSync = function(path, options) {
+  options = options || {};
+  if (typeof options === 'string')
+    options = {encoding: options};
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
   nullCheck(path);
-  return binding.readlink(pathModule._makeLong(path));
+  return binding.readlink(pathModule._makeLong(path), options.encoding);
 };
 
 function preprocessSymlinkDestination(path, type, linkPath) {
@@ -1363,11 +1392,15 @@ function FSWatcher() {
 }
 util.inherits(FSWatcher, EventEmitter);
 
-FSWatcher.prototype.start = function(filename, persistent, recursive) {
+FSWatcher.prototype.start = function(filename,
+                                     persistent,
+                                     recursive,
+                                     encoding) {
   nullCheck(filename);
   var err = this._handle.start(pathModule._makeLong(filename),
                                persistent,
-                               recursive);
+                               recursive,
+                               encoding);
   if (err) {
     this._handle.close();
     const error = errnoException(err, `watch ${filename}`);
@@ -1380,25 +1413,27 @@ FSWatcher.prototype.close = function() {
   this._handle.close();
 };
 
-fs.watch = function(filename) {
+fs.watch = function(filename, options, listener) {
   nullCheck(filename);
-  var watcher;
-  var options;
-  var listener;
 
-  if (arguments[1] !== null && typeof arguments[1] === 'object') {
-    options = arguments[1];
-    listener = arguments[2];
-  } else {
+  options = options || {};
+  if (typeof options === 'function') {
+    listener = options;
     options = {};
-    listener = arguments[1];
+  } else if (typeof options === 'string') {
+    options = {encoding: options};
   }
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
 
   if (options.persistent === undefined) options.persistent = true;
   if (options.recursive === undefined) options.recursive = false;
 
-  watcher = new FSWatcher();
-  watcher.start(filename, options.persistent, options.recursive);
+  const watcher = new FSWatcher();
+  watcher.start(filename,
+                options.persistent,
+                options.recursive,
+                options.encoding);
 
   if (listener) {
     watcher.addListener('change', listener);
@@ -2139,10 +2174,19 @@ SyncWriteStream.prototype.destroy = function() {
 
 SyncWriteStream.prototype.destroySoon = SyncWriteStream.prototype.destroy;
 
-fs.mkdtemp = function(prefix, callback) {
-  if (typeof callback !== 'function') {
-    throw new TypeError('"callback" argument must be a function');
+fs.mkdtemp = function(prefix, options, callback) {
+  if (!prefix || typeof prefix !== 'string')
+    throw new TypeError('filename prefix is required');
+
+  options = options || {};
+  if (typeof options === 'function') {
+    callback = options;
+    options = {};
+  } else if (typeof options === 'string') {
+    options = {encoding: options};
   }
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
 
   if (!nullCheck(prefix, callback)) {
     return;
@@ -2151,11 +2195,19 @@ fs.mkdtemp = function(prefix, callback) {
   var req = new FSReqWrap();
   req.oncomplete = callback;
 
-  binding.mkdtemp(prefix + 'XXXXXX', req);
+  binding.mkdtemp(prefix + 'XXXXXX', options.encoding, req);
 };
 
-fs.mkdtempSync = function(prefix) {
+fs.mkdtempSync = function(prefix, options) {
+  if (!prefix || typeof prefix !== 'string')
+    throw new TypeError('filename prefix is required');
+
+  options = options || {};
+  if (typeof options === 'string')
+    options = {encoding: options};
+  if (typeof options !== 'object')
+    throw new TypeError('"options" must be a string or an object');
   nullCheck(prefix);
 
-  return binding.mkdtemp(prefix + 'XXXXXX');
+  return binding.mkdtemp(prefix + 'XXXXXX', options.encoding);
 };