Reworked Streaming API behavior in browser environments to fix #204.

I removed conditional requires that were causing problems described in #204, so it shouldn't be a problem now.

The reasoning behind these conditions was to avoid bloating browser bundles that usually don't require Streaming API.
Streaming API is built upon 'streams' Node.js module that can grow the bundles up to ~100 Kb.

To still keep this benefit while allowing users to explicitly enable Streaming API on the browser, I restructured the dependencies:
 1. In package.json 'browser.stream' module is set to false, thus ignored by default (require('stream') returns empty object).
 2. In index.js we check if require('stream') returns non-empty object and enable Streaming API by dependency-injecting this module
    to streams.js.
 3. Otherwise, we create small shims for 'encodeStream' and 'decodeStream' functions that throw exceptions when called,
    with a message that helps users to explicitly enable Streaming APIs using 'iconv.enableStreamingAPI'. The idea is that this
    should be a very rare case.

Also add tests for browser streaming behaviors with webpack/karma setup

Author: ashtuchkin

.travis.yml

@@ -1,24 +1,19 @@
- sudo: false
- language: node_js
- node_js:
-   - "0.10"
-   - "0.11"
-   - "0.12"
-   - "iojs"
-   - "4"
-   - "6"
-   - "8"
-   - "10"
-   - "12"
-   - "node"
-
- env:
-   - CXX=g++-4.8
- addons:
-   apt:
-     sources:
-       - ubuntu-toolchain-r-test
-     packages:
-       - gcc-4.8
-       - g++-4.8
+language: node_js
+node_js:
+  - "0.10"
+  - "0.11"
+  - "0.12"
+  - "iojs"
+  - "4"
+  - "6"
+  - "8"
+  - "10"
+  - "12"
+  - "node"
 
+jobs:
+  include:
+    - name: webpack
+      node_js: "12"
+      install: cd test/webpack; npm install
+      script: npm test

README.md

@@ -1,14 +1,13 @@
-## Pure JS character encoding conversion
+## iconv-lite: Pure JS character encoding conversion
 
- * Doesn't need native code compilation. Works on Windows and in sandboxed environments like [Cloud9](http://c9.io).
+ * No need for native code compilation. Quick to install, works on Windows and in sandboxed environments like [Cloud9](http://c9.io).
  * Used in popular projects like [Express.js (body_parser)](https://github.com/expressjs/body-parser), 
    [Grunt](http://gruntjs.com/), [Nodemailer](http://www.nodemailer.com/), [Yeoman](http://yeoman.io/) and others.
  * Faster than [node-iconv](https://github.com/bnoordhuis/node-iconv) (see below for performance comparison).
- * Intuitive encode/decode API
- * Streaming support for Node v0.10+
- * In-browser usage via [Browserify](https://github.com/substack/node-browserify) (~180k gzip compressed with Buffer shim included).
+ * Intuitive encode/decode API, including Streaming support.
+ * In-browser usage via [browserify](https://github.com/substack/node-browserify) or [webpack](https://webpack.js.org/) (~180kb gzip compressed with Buffer shim included).
  * Typescript [type definition file](https://github.com/ashtuchkin/iconv-lite/blob/master/lib/index.d.ts) included.
- * React Native is supported (need to explicitly `npm install` two more modules: `buffer` and `stream`).
+ * React Native is supported (need to install `stream` module to enable Streaming API).
  * License: MIT.
 
 [![NPM Stats](https://nodei.co/npm/iconv-lite.png)](https://npmjs.org/package/iconv-lite/)  
@@ -22,20 +21,20 @@
 ```javascript
 var iconv = require('iconv-lite');
 
-// Convert from an encoded buffer to js string.
+// Convert from an encoded buffer to a js string.
 str = iconv.decode(Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f]), 'win1251');
 
-// Convert from js string to an encoded buffer.
+// Convert from a js string to an encoded buffer.
 buf = iconv.encode("Sample input string", 'win1251');
 
 // Check if encoding is supported
 iconv.encodingExists("us-ascii")
 ```
 
-### Streaming API (Node v0.10+)
+### Streaming API
 ```javascript
 
-// Decode stream (from binary stream to js strings)
+// Decode stream (from binary data stream to js strings)
 http.createServer(function(req, res) {
     var converterStream = iconv.decodeStream('win1251');
     req.pipe(converterStream);

lib/index.js

@@ -1,7 +1,5 @@
 "use strict";
 
-// Some environments don't have global Buffer (e.g. React Native).
-// Solution would be installing npm modules "buffer" and "stream" explicitly.
 var Buffer = require("safer-buffer").Buffer;
 
 var bomHandling = require("./bom-handling"),
@@ -133,18 +131,50 @@ iconv.getDecoder = function getDecoder(encoding, options) {
     return decoder;
 }
 
+// Streaming API
+// NOTE: Streaming API naturally depends on 'stream' module from Node.js. Unfortunately in browser environments this module can add
+// up to 100Kb to the output bundle. To avoid unnecessary code bloat, we don't enable Streaming API in browser by default.
+// If you would like to enable it explicitly, please add the following code to your app:
+// > iconv.enableStreamingAPI(require('stream'));
+iconv.enableStreamingAPI = function enableStreamingAPI(stream_module) {
+    if (iconv.supportsStreams)
+        return;
+
+    // Dependency-inject stream module to create IconvLite stream classes.
+    var streams = require("./streams")(stream_module);
+
+    // Not public API yet, but expose the stream classes.
+    iconv.IconvLiteEncoderStream = streams.IconvLiteEncoderStream;
+    iconv.IconvLiteDecoderStream = streams.IconvLiteDecoderStream;
+
+    // Streaming API.
+    iconv.encodeStream = function encodeStream(encoding, options) {
+        return new iconv.IconvLiteEncoderStream(iconv.getEncoder(encoding, options), options);
+    }
 
-// Load extensions in Node. All of them are omitted in Browserify build via 'browser' field in package.json.
-var nodeVer = typeof process !== 'undefined' && process.versions && process.versions.node;
-if (nodeVer) {
-
-    // Load streaming support in Node v0.10+
-    var nodeVerArr = nodeVer.split(".").map(Number);
-    if (nodeVerArr[0] > 0 || nodeVerArr[1] >= 10) {
-        require("./streams")(iconv);
+    iconv.decodeStream = function decodeStream(encoding, options) {
+        return new iconv.IconvLiteDecoderStream(iconv.getDecoder(encoding, options), options);
     }
+
+    iconv.supportsStreams = true;
+}
+
+// Enable Streaming API automatically if 'stream' module is available and non-empty (the majority of environments).
+var stream_module;
+try {
+    stream_module = require("stream");
+} catch (e) {}
+
+if (stream_module && stream_module.Transform) {
+    iconv.enableStreamingAPI(stream_module);
+
+} else {
+    // In rare cases where 'stream' module is not available by default, throw a helpful exception.
+    iconv.encodeStream = iconv.decodeStream = function() {
+        throw new Error("iconv-lite Streaming API is not enabled. Use iconv.enableStreamingAPI(require('stream')); to enable it.");
+    };
 }
 
 if ("Ā" != "\u0100") {
-    console.error("iconv-lite warning: javascript files use encoding different from utf-8. See https://github.com/ashtuchkin/iconv-lite/wiki/Javascript-source-file-encodings for more info.");
+    console.error("iconv-lite warning: js files use non-utf8 encoding. See https://github.com/ashtuchkin/iconv-lite/wiki/Javascript-source-file-encodings for more info.");
 }

lib/streams.js

@@ -1,121 +1,109 @@
 "use strict";
 
-var Buffer = require("buffer").Buffer,
-    Transform = require("stream").Transform;
+var Buffer = require("safer-buffer").Buffer;
 
+// NOTE: Due to 'stream' module being pretty large (~100Kb, significant in browser environments), 
+// we opt to dependency-inject it instead of creating a hard dependency.
+module.exports = function(stream_module) {
+    var Transform = stream_module.Transform;
 
-// == Exports ==================================================================
-module.exports = function(iconv) {
-    
-    // Additional Public API.
-    iconv.encodeStream = function encodeStream(encoding, options) {
-        return new IconvLiteEncoderStream(iconv.getEncoder(encoding, options), options);
+    // == Encoder stream =======================================================
+
+    function IconvLiteEncoderStream(conv, options) {
+        this.conv = conv;
+        options = options || {};
+        options.decodeStrings = false; // We accept only strings, so we don't need to decode them.
+        Transform.call(this, options);
     }
 
-    iconv.decodeStream = function decodeStream(encoding, options) {
-        return new IconvLiteDecoderStream(iconv.getDecoder(encoding, options), options);
+    IconvLiteEncoderStream.prototype = Object.create(Transform.prototype, {
+        constructor: { value: IconvLiteEncoderStream }
+    });
+
+    IconvLiteEncoderStream.prototype._transform = function(chunk, encoding, done) {
+        if (typeof chunk != 'string')
+            return done(new Error("Iconv encoding stream needs strings as its input."));
+        try {
+            var res = this.conv.write(chunk);
+            if (res && res.length) this.push(res);
+            done();
+        }
+        catch (e) {
+            done(e);
+        }
     }
 
-    iconv.supportsStreams = true;
+    IconvLiteEncoderStream.prototype._flush = function(done) {
+        try {
+            var res = this.conv.end();
+            if (res && res.length) this.push(res);
+            done();
+        }
+        catch (e) {
+            done(e);
+        }
+    }
 
+    IconvLiteEncoderStream.prototype.collect = function(cb) {
+        var chunks = [];
+        this.on('error', cb);
+        this.on('data', function(chunk) { chunks.push(chunk); });
+        this.on('end', function() {
+            cb(null, Buffer.concat(chunks));
+        });
+        return this;
+    }
 
-    // Not published yet.
-    iconv.IconvLiteEncoderStream = IconvLiteEncoderStream;
-    iconv.IconvLiteDecoderStream = IconvLiteDecoderStream;
-    iconv._collect = IconvLiteDecoderStream.prototype.collect;
-};
 
+    // == Decoder stream =======================================================
 
-// == Encoder stream =======================================================
-function IconvLiteEncoderStream(conv, options) {
-    this.conv = conv;
-    options = options || {};
-    options.decodeStrings = false; // We accept only strings, so we don't need to decode them.
-    Transform.call(this, options);
-}
-
-IconvLiteEncoderStream.prototype = Object.create(Transform.prototype, {
-    constructor: { value: IconvLiteEncoderStream }
-});
-
-IconvLiteEncoderStream.prototype._transform = function(chunk, encoding, done) {
-    if (typeof chunk != 'string')
-        return done(new Error("Iconv encoding stream needs strings as its input."));
-    try {
-        var res = this.conv.write(chunk);
-        if (res && res.length) this.push(res);
-        done();
-    }
-    catch (e) {
-        done(e);
+    function IconvLiteDecoderStream(conv, options) {
+        this.conv = conv;
+        options = options || {};
+        options.encoding = this.encoding = 'utf8'; // We output strings.
+        Transform.call(this, options);
     }
-}
 
-IconvLiteEncoderStream.prototype._flush = function(done) {
-    try {
-        var res = this.conv.end();
-        if (res && res.length) this.push(res);
-        done();
-    }
-    catch (e) {
-        done(e);
-    }
-}
-
-IconvLiteEncoderStream.prototype.collect = function(cb) {
-    var chunks = [];
-    this.on('error', cb);
-    this.on('data', function(chunk) { chunks.push(chunk); });
-    this.on('end', function() {
-        cb(null, Buffer.concat(chunks));
+    IconvLiteDecoderStream.prototype = Object.create(Transform.prototype, {
+        constructor: { value: IconvLiteDecoderStream }
     });
-    return this;
-}
-
-
-// == Decoder stream =======================================================
-function IconvLiteDecoderStream(conv, options) {
-    this.conv = conv;
-    options = options || {};
-    options.encoding = this.encoding = 'utf8'; // We output strings.
-    Transform.call(this, options);
-}
-
-IconvLiteDecoderStream.prototype = Object.create(Transform.prototype, {
-    constructor: { value: IconvLiteDecoderStream }
-});
-
-IconvLiteDecoderStream.prototype._transform = function(chunk, encoding, done) {
-    if (!Buffer.isBuffer(chunk))
-        return done(new Error("Iconv decoding stream needs buffers as its input."));
-    try {
-        var res = this.conv.write(chunk);
-        if (res && res.length) this.push(res, this.encoding);
-        done();
-    }
-    catch (e) {
-        done(e);
+
+    IconvLiteDecoderStream.prototype._transform = function(chunk, encoding, done) {
+        if (!Buffer.isBuffer(chunk))
+            return done(new Error("Iconv decoding stream needs buffers as its input."));
+        try {
+            var res = this.conv.write(chunk);
+            if (res && res.length) this.push(res, this.encoding);
+            done();
+        }
+        catch (e) {
+            done(e);
+        }
     }
-}
 
-IconvLiteDecoderStream.prototype._flush = function(done) {
-    try {
-        var res = this.conv.end();
-        if (res && res.length) this.push(res, this.encoding);                
-        done();
+    IconvLiteDecoderStream.prototype._flush = function(done) {
+        try {
+            var res = this.conv.end();
+            if (res && res.length) this.push(res, this.encoding);                
+            done();
+        }
+        catch (e) {
+            done(e);
+        }
     }
-    catch (e) {
-        done(e);
+
+    IconvLiteDecoderStream.prototype.collect = function(cb) {
+        var res = '';
+        this.on('error', cb);
+        this.on('data', function(chunk) { res += chunk; });
+        this.on('end', function() {
+            cb(null, res);
+        });
+        return this;
     }
-}
-
-IconvLiteDecoderStream.prototype.collect = function(cb) {
-    var res = '';
-    this.on('error', cb);
-    this.on('data', function(chunk) { res += chunk; });
-    this.on('end', function() {
-        cb(null, res);
-    });
-    return this;
-}
 
+    return {
+        IconvLiteEncoderStream: IconvLiteEncoderStream,
+        IconvLiteDecoderStream: IconvLiteDecoderStream,
+    };
+};

package.json

@@ -26,7 +26,7 @@
         "test": "mocha --reporter spec --grep ."
     },
     "browser": {
-        "./lib/streams": false
+        "stream": false
     },
     "devDependencies": {
         "mocha": "^3.1.0",

test/browserify-test.js

@@ -0,0 +1,46 @@
+var assert = require('assert').strict;
+
+describe("iconv-lite", function() {
+    var iconv;
+
+    it("can be require-d successfully", function() {
+        // Emulate more complex environments that are both web- and node.js-compatible (e.g. Electron renderer process).
+        // See https://github.com/ashtuchkin/iconv-lite/issues/204 for details.
+        process.versions.node = "12.0.0";
+
+        iconv = require(".").iconv;
+    });
+
+    it("does not support streams by default", function() {
+        assert(!iconv.supportsStreams);
+
+        assert.throws(function() { 
+            iconv.encodeStream()
+        }, /Streaming API is not enabled/);
+    });
+
+    it("can encode/decode sbcs encodings", function() {
+        var buf = iconv.encode("abc", "win1251");
+        var str = iconv.decode(buf, "win1251");
+        assert.equal(str, "abc");
+    });
+
+    it("can encode/decode dbcs encodings", function() {
+        var buf = iconv.encode("abc", "shiftjis");
+        var str = iconv.decode(buf, "shiftjis");
+        assert.equal(str, "abc");
+    });
+
+    it("can encode/decode internal encodings", function() {
+        var buf = iconv.encode("💩", "utf8");
+        var str = iconv.decode(buf, "utf8");
+        assert.equal(str, "💩");
+    });
+});
+
+describe("stream module", function() {
+    it("is not included in the bundle", function() {
+        var stream_module_name = "stream";
+        assert.throws(function() { return require(stream_module_name) }, /Cannot find module 'stream'/);
+    });
+});

test/webpack/basic-test.js

@@ -0,0 +1,3 @@
+
+// Reexport iconv-lite for tests.
+exports.iconv = require('iconv-lite');

test/webpack/index.js

@@ -0,0 +1,78 @@
+// Karma configuration
+// Generated on Sat May 23 2020 18:02:48 GMT-0400 (Eastern Daylight Time)
+
+module.exports = function(config) {
+  config.set({
+
+    // base path that will be used to resolve all patterns (eg. files, exclude)
+    basePath: '',
+
+
+    // frameworks to use
+    // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
+    frameworks: ['mocha'],
+
+
+    // list of files / patterns to load in the browser
+    files: [
+      { pattern: '*test.js', watched: false },
+    ],
+
+    // preprocess matching files before serving them to the browser
+    // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
+    preprocessors: {
+      '*test.js': ['webpack']
+    },
+
+    webpack: {
+      "mode": "development",
+      // karma watches the test entry points
+      // (you don't need to specify the entry option)
+      // webpack watches dependencies
+      // webpack configuration
+    },
+
+    webpackMiddleware: {
+      // Don't watch.
+      "watchOptions": {
+        ignored: ["**/*"],
+      },
+    },
+
+    // test results reporter to use
+    // possible values: 'dots', 'progress'
+    // available reporters: https://npmjs.org/browse/keyword/karma-reporter
+    reporters: ['progress'],
+
+
+    // web server port
+    port: 9876,
+
+
+    // enable / disable colors in the output (reporters and logs)
+    colors: true,
+
+
+    // level of logging
+    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG
+    logLevel: config.LOG_INFO,
+
+
+    // enable / disable watching file and executing tests whenever any file changes
+    autoWatch: false,
+
+
+    // start these browsers
+    // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
+    browsers: ['PhantomJS'],
+
+
+    // Continuous Integration mode
+    // if true, Karma captures browsers, runs the tests and exits
+    singleRun: true,
+
+    // Concurrency level
+    // how many browser should be started simultaneous
+    concurrency: Infinity
+  })
+}

test/webpack/karma.conf.js

@@ -0,0 +1,20 @@
+{
+  "name": "webpack-test",
+  "private": true,
+  "version": "1.0.0",
+  "scripts": {
+    "test": "karma start"
+  },
+  "devDependencies": {
+    "karma": "^5.0.9",
+    "karma-mocha": "^2.0.1",
+    "karma-phantomjs-launcher": "^1.0.4",
+    "karma-webpack": "^4.0.2",
+    "mocha": "^7.2.0",
+    "phantomjs-prebuilt": "^2.1.16",
+    "webpack": "^4.43.0"
+  },
+  "dependencies": {
+    "iconv-lite": "file:../.."
+  }
+}

test/webpack/package.json

@@ -0,0 +1,25 @@
+var assert = require('assert').strict;
+
+describe("iconv-lite with streams", function() {
+    var iconv = require(".").iconv;
+
+    it("supports streams when explicitly enabled", function() {
+        iconv.enableStreamingAPI(require('stream'));
+        assert(iconv.supportsStreams);
+    });
+
+    it("can encode/decode in streaming mode", function(done) {
+        var stream1 = iconv.encodeStream("win1251");
+        var stream2 = iconv.decodeStream("win1251");
+        stream1.pipe(stream2);
+
+        stream1.end("abc");
+        stream2.collect(function(err, str) {
+            if (err)
+                return done(err);
+
+            assert.equal(str, "abc");
+            done(null);
+        });
+    });
+});