process: add setPromiseImplementation API

nodejs · chrisdickinson · Feb 1, 2016 · Feb 1, 2016 · Feb 1, 2016 · Feb 1, 2016
commit 082fa0801032e98650f8c67e113b701f8195508d
diff --git a/doc/api/process.markdown b/doc/api/process.markdown
@@ -908,6 +908,29 @@ need to be root or have the `CAP_SETGID` capability.
 
 The list can contain group IDs, group names or both.
 
+## process.setPromiseImplementation(impl)
+
+Sets the [`Promise`][def-promises] implementation for the process. All promises
+returned by core APIs will be resolved by this implementation, giving third
+party promise implementations an opportunity to cast native promises into a
+different type.
+
+**Only top-level applications should use this API.** If this API is called more
+than once, subsequent calls will issue deprecation warnings so authors can
+track down offending modules.
+
+```javascript
+process.setPromiseImplementation(require('bluebird'));
+
+const fs = require('fs');
+
+fs.readFile('/usr/share/dict/words', 'utf8').then((words) => {
+  console.log(`a picture is worth ${words.split('\n').length} words.`);
+}, (err) => {
+  console.error('there are no words.');
+});
+```
+
 ## process.setuid(id)
 
 Note: this function is only available on POSIX platforms (i.e. not Windows,

diff --git a/lib/internal/promises.js b/lib/internal/promises.js
@@ -24,19 +24,10 @@ function setResolver(wrapper) {
 
 function setup(process) {
   var implSet = false;
-  var where = null
+  var where = null;
   process.setPromiseImplementation = function setImpl(impl) {
     const assert = require('assert');
     const util = require('internal/util');
-    if (!implSet) {
-      implSet = true;
-      where = new Error('setPromiseImplementation');
-      process.setPromiseImplementation = util.deprecate(
-        setImpl,
-        'setPromiseImplementation has already been called for this process:\n' +
-        where.stack + '\n'
-      );
-    }
     assert(
       (typeof impl === 'object' || typeof impl === 'function') && impl,
       'implementation should be a truthy object'
@@ -50,6 +41,15 @@ function setup(process) {
       test && typeof test.then === 'function',
       '.resolve should return a thenable'
     );
+    if (!implSet) {
+      implSet = true;
+      where = new Error('setPromiseImplementation');
+      process.setPromiseImplementation = util.deprecate(
+        setImpl,
+        'setPromiseImplementation has already been called for this process:\n' +
+        where.stack + '\n'
+      );
+    }
     setResolver(impl);
   };
 }
diff --git a/test/parallel/test-process-set-promises-impl.js b/test/parallel/test-process-set-promises-impl.js
@@ -0,0 +1,58 @@
+'use strict';
+
+require('../common');
+
+const fs = require('fs');
+var assert = require('assert');
+
+assert.throws(() => {
+  process.setPromiseImplementation(null);
+});
+
+assert.throws(() => {
+  process.setPromiseImplementation('ok');
+});
+
+assert.throws(() => {
+  process.setPromiseImplementation({});
+});
+
+assert.throws(() => {
+  process.setPromiseImplementation({
+    resolve() {
+    }
+  });
+});
+
+assert.throws(() => {
+  process.setPromiseImplementation({
+    resolve() {
+      return {};
+    }
+  });
+});
+
+process.setPromiseImplementation({
+  resolve(promise) {
+    return {
+      hello: 'world',
+      then(fn0, fn1) {
+        return promise.then(fn0, fn1);
+      }
+    };
+  }
+});
+
+// affects old requires:
+const p = fs.readFile(__filename, 'utf8');
+p.then((lines) => {
+  assert.ok(lines.indexOf("'use strict'") !== -1);
+});
+assert.equal(p.hello, 'world');
+
+// affects new requires:
+const r = require('crypto').randomBytesAsync(16);
+r.then((bytes) => {
+  assert.ok(Buffer.isBuffer(bytes));
+});
+assert.equal(r.hello, 'world');