Amend: Document and test binary mode with encoding set false

README.md

@@ -99,9 +99,11 @@ Default: `true`
 ##### `options.encoding`
 
 Optionally transcode from the given encoding. The default is `'utf8'`. We use
-[iconv-lite], please refer to its Wiki for a list of supported encodings.
+[iconv-lite], please refer to its Wiki for a list of supported encodings. You
+can set this to `false` to avoid any transcoding, and effectively just pass
+around raw binary data.
 
-Type: `String`
+Type: `String` or `Boolean`
 
 Default: `'utf8'`
 
@@ -193,9 +195,11 @@ Default: `true` (always overwrite existing files)
 ##### `options.encoding`
 
 Optionally transcode to the given encoding. The default is `'utf8'`. We use
-[iconv-lite], please refer to its Wiki for a list of supported encodings.
+[iconv-lite], please refer to its Wiki for a list of supported encodings. You
+can set this to `false` to avoid any transcoding, and effectively just pass
+around raw binary data.
 
-Type: `String`
+Type: `String` or `Boolean`
 
 Default: `'utf8'`.
 

lib/dest/options.js

@@ -26,7 +26,7 @@ var config = {
     },
   },
   encoding: {
-    type: 'string',
+    type: ['string', 'boolean'],
     default: 'utf8',
   },
   sourcemaps: {

lib/src/options.js

@@ -17,7 +17,7 @@ var config = {
     default: true,
   },
   encoding: {
-    type: 'string',
+    type: ['string', 'boolean'],
     default: 'utf8',
   },
   sourcemaps: {

test/dest.js

@@ -40,6 +40,7 @@ var outputRenamePath = testConstants.outputRenamePath;
 var inputDirpath = testConstants.inputDirpath;
 var outputDirpath = testConstants.outputDirpath;
 var encodedInputPath = testConstants.encodedInputPath;
+var ranBomInputPath = testConstants.ranBomInputPath;
 var contents = testConstants.contents;
 var sourcemapContents = testConstants.sourcemapContents;
 var bomContents = testConstants.bomContents;
@@ -610,6 +611,50 @@ describe('.dest()', function() {
     ], done);
   });
 
+  it('does not do any transcoding with encoding option set to false (buffer)', function(done) {
+    var expectedContents = fs.readFileSync(ranBomInputPath);
+    var file = new File({
+      base: inputBase,
+      path: inputPath,
+      contents: expectedContents,
+    });
+
+    function assert(files) {
+      var outputContents = fs.readFileSync(outputPath);
+
+      expect(files.length).toEqual(1);
+      expect(outputContents).toMatch(expectedContents);
+    }
+
+    pipe([
+      from.obj([file]),
+      vfs.dest(outputBase, { encoding: false }),
+      concat(assert),
+    ], done);
+  });
+
+  it('does not do any transcoding with encoding option set to false (stream)', function(done) {
+    var expectedContents = fs.readFileSync(ranBomInputPath);
+    var file = new File({
+      base: inputBase,
+      path: inputPath,
+      contents: fs.createReadStream(ranBomInputPath),
+    });
+
+    function assert(files) {
+      var outputContents = fs.readFileSync(outputPath);
+
+      expect(files.length).toEqual(1);
+      expect(outputContents).toMatch(expectedContents);
+    }
+
+    pipe([
+      from.obj([file]),
+      vfs.dest(outputBase, { encoding: false }),
+      concat(assert),
+    ], done);
+  });
+
   it('transcodes utf8 to gb2312 with encoding option (buffer)', function(done) {
     var expectedContents = fs.readFileSync(encodedInputPath);
     var file = new File({

test/src.js

@@ -3,7 +3,6 @@
 var path = require('path');
 
 var fs = require('graceful-fs');
-var iconv = require('iconv-lite');
 var File = require('vinyl');
 var expect = require('expect');
 var miss = require('mississippi');
@@ -25,9 +24,10 @@ var beBomInputPath = testConstants.beBomInputPath;
 var leBomInputPath = testConstants.leBomInputPath;
 var beNotBomInputPath = testConstants.beNotBomInputPath;
 var leNotBomInputPath = testConstants.leNotBomInputPath;
-var bomContents = testConstants.bomContents;
+var ranBomInputPath = testConstants.ranBomInputPath;
 var encodedInputPath = testConstants.encodedInputPath;
 var encodedContents = testConstants.encodedContents;
+var bomContents = testConstants.bomContents;
 var contents = testConstants.contents;
 
 describe('.src()', function() {
@@ -474,6 +474,90 @@ describe('.src()', function() {
     ], done);
   });
 
+  it('does not do any transcoding with encoding option set to false (buffer)', function(done) {
+    var expectedContents = fs.readFileSync(ranBomInputPath);
+
+    function assert(files) {
+      expect(files.length).toEqual(1);
+      expect(files[0].contents).toMatch(expectedContents);
+    }
+
+    pipe([
+      vfs.src(ranBomInputPath, { encoding: false }),
+      concat(assert),
+    ], done);
+  });
+
+  it('does not do any transcoding with encoding option set to false (stream)', function(done) {
+    var expectedContents = fs.readFileSync(ranBomInputPath);
+
+    function assertContent(contents) {
+      expect(contents).toMatch(expectedContents);
+    }
+
+    function compareContents(file, enc, cb) {
+      pipe([
+        file.contents,
+        concat(assertContent),
+      ], function(err) {
+        cb(err, file);
+      });
+    }
+
+    function assert(files) {
+      expect(files.length).toEqual(1);
+      expect(files[0].isStream()).toEqual(true);
+    }
+
+    pipe([
+      vfs.src(ranBomInputPath, { encoding: false, buffer: false }),
+      through.obj(compareContents),
+      concat(assert),
+    ], done);
+  });
+
+  it('does not remove utf8 BOM with encoding option set to false (buffer)', function(done) {
+    var expectedContents = fs.readFileSync(bomInputPath);
+
+    function assert(files) {
+      expect(files.length).toEqual(1);
+      expect(files[0].contents).toMatch(expectedContents);
+    }
+
+    pipe([
+      vfs.src(bomInputPath, { encoding: false }),
+      concat(assert),
+    ], done);
+  });
+
+  it('does not remove utf8 BOM with encoding option set to false (stream)', function(done) {
+    var expectedContents = fs.readFileSync(bomInputPath);
+
+    function assertContent(contents) {
+      expect(contents).toMatch(expectedContents);
+    }
+
+    function compareContents(file, enc, cb) {
+      pipe([
+        file.contents,
+        concat(assertContent),
+      ], function(err) {
+        cb(err, file);
+      });
+    }
+
+    function assert(files) {
+      expect(files.length).toEqual(1);
+      expect(files[0].isStream()).toEqual(true);
+    }
+
+    pipe([
+      vfs.src(bomInputPath, { encoding: false, buffer: false }),
+      through.obj(compareContents),
+      concat(assert),
+    ], done);
+  });
+
   it('transcodes gb2312 to utf8 with encoding option (buffer)', function(done) {
     var expectedContents = new Buffer(encodedContents);
 
@@ -489,7 +573,7 @@ describe('.src()', function() {
   });
 
   it('transcodes gb2312 to utf8 with encoding option (stream)', function(done) {
-    var expectedContents = iconv.encode(encodedContents, 'utf8');
+    var expectedContents = new Buffer(encodedContents);
 
     function assertContent(contents) {
       expect(contents).toMatch(expectedContents);

test/utils/test-constants.js

@@ -29,6 +29,7 @@ var leBomInputPath = path.join(inputBase, './bom-utf16le.txt');
 var bomContents = 'This file is saved as UTF-X with the appropriate BOM.\n';
 var beNotBomInputPath = path.join(inputBase, './not-bom-utf16be.txt');
 var leNotBomInputPath = path.join(inputBase, './not-bom-utf16le.txt');
+var ranBomInputPath = path.join(inputBase, './ranbom.bin');
 // Used for encoding tests
 var encodedInputPath = path.join(inputBase, './enc-gb2312.txt');
 var encodedContents = '\u5b54\u5b50\u8bf4\u590d\u6d3b\u8282\u5f69\u86cb\n';
@@ -68,6 +69,7 @@ module.exports = {
   leBomInputPath: leBomInputPath,
   beNotBomInputPath: beNotBomInputPath,
   leNotBomInputPath: leNotBomInputPath,
+  ranBomInputPath: ranBomInputPath,
   bomContents: bomContents,
   encodedInputPath: encodedInputPath,
   encodedContents: encodedContents,