getNewLibraryCopy method

docs/docs/api-reference.md

@@ -74,6 +74,7 @@ redirect_from: "/docs/api/index.html"
     - [.catchReturn](api/catchreturn.html)
     - [.catchThrow](api/catchthrow.html)
     - [.reflect](api/reflect.html)
+    - [Promise.getNewLibraryCopy](api/promise.getnewlibrarycopy.html)
     - [Promise.noConflict](api/promise.noconflict.html)
     - [Promise.setScheduler](api/promise.setscheduler.html)
 - [Built-in error types](api/built-in-error-types.html)

docs/docs/api/promise.getnewlibrarycopy.md

@@ -0,0 +1,64 @@
+---
+layout: api
+id: promise.getnewlibrarycopy
+title: Promise.getNewLibraryCopy
+---
+
+
+[← Back To API Reference](/docs/api-reference.html)
+<div class="api-code-section"><markdown>
+##Promise.getNewLibraryCopy
+
+```js
+Promise.getNewLibraryCopy() -> Object
+```
+
+Returns a new independent copy of the Bluebird library.
+
+This method should be used before you use any of the methods which would otherwise alter the global `Bluebird` object - to avoid polluting global state.
+
+A basic example:
+
+```js
+var Promise = require('bluebird');
+var Promise2 = Promise.getNewLibraryCopy();
+
+Promise2.x = 123;
+
+console.log(Promise2 == Promise); // false
+console.log(Promise2.x); // 123
+console.log(Promise.x); // undefined
+```
+
+`Promise` is independent to `Promise`. Any changes to `Promise2` do not affect the copy of Bluebird returned by `require('bluebird')`.
+
+In practice:
+
+```js
+var Promise = require('bluebird').getNewLibraryCopy();
+
+Promise.coroutine.addYieldHandler( function() { /* */ } ); // alters behavior of `Promise.coroutine()`
+
+// somewhere in another file or module in same app
+var Promise = require('bluebird');
+
+Promise.coroutine(function*() {
+    // this code is unaffected by the yieldHandler defined above
+    // because it was defined on an independent copy of Bluebird
+});
+```
+</markdown></div>
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    var disqus_title = "Promise.getNewLibraryCopy";
+    var disqus_shortname = "bluebirdjs";
+    var disqus_identifier = "disqus-id-promise.getnewlibrarycopy";
+
+    (function() {
+        var dsq = document.createElement("script"); dsq.type = "text/javascript"; dsq.async = true;
+        dsq.src = "//" + disqus_shortname + ".disqus.com/embed.js";
+        (document.getElementsByTagName("head")[0] || document.getElementsByTagName("body")[0]).appendChild(dsq);
+    })();
+</script>
+<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>

src/promise.js

@@ -165,6 +165,8 @@ Promise.prototype.error = function (fn) {
     return this.caught(util.originatesFromRejection, fn);
 };
 
+Promise.getNewLibraryCopy = module.exports;
+
 Promise.is = function (val) {
     return val instanceof Promise;
 };

test/mocha/getNewLibraryCopy.js

@@ -0,0 +1,30 @@
+"use strict";
+
+var assert = require("assert");
+var testUtils = require("./helpers/util.js");
+
+describe("Promise.getNewLibraryCopy", function() {
+    it("should return an independent copy of Bluebird library", function() {
+        var Promise2 = Promise.getNewLibraryCopy();
+        Promise2.x = 123;
+
+        assert.equal(typeof Promise2.prototype.then, "function");
+        assert.notEqual(Promise2, Promise);
+
+        assert.equal(Promise2.x, 123);
+        assert.notEqual(Promise.x, 123);
+    });
+    it("should return copy of Bluebird library with its own getNewLibraryCopy method", function() {
+        var Promise2 = Promise.getNewLibraryCopy();
+        var Promise3 = Promise2.getNewLibraryCopy();
+        Promise3.x = 123;
+
+        assert.equal(typeof Promise3.prototype.then, "function");
+        assert.notEqual(Promise3, Promise);
+        assert.notEqual(Promise3, Promise2);
+
+        assert.equal(Promise3.x, 123);
+        assert.notEqual(Promise.x, 123);
+        assert.notEqual(Promise2.x, 123);
+    });
+});