Add support for Promises (#458)

Return a Promise when a callback is not provided.

Author: recrsn

README.md

@@ -102,7 +102,26 @@ bcrypt.compare(someOtherPlaintextPassword, hash, function(err, res) {
     // res == false
 });
 ```
+### with promises
 
+bcrypt uses whatever Promise implementation is available in `global.Promise`. NodeJS >= 0.12 has a native Promise implementation built in. However, this should work in any Promises/A+ compilant implementation.
+
+Async methods that accept a callback, return a `Promise` when callback is not specified if Promise support is available.
+
+```javascript
+bcrypt.hash(myPlaintextPassword, saltRounds).then(function(hash) {
+    // Store hash in your password DB.
+});
+```
+```javascript
+// Load hash from your password DB.
+bcrypt.compare(myPlaintextPassword, hash).then(function(res) {
+    // res == true
+});
+bcrypt.compare(someOtherPlaintextPassword, hash).then(function(res) {
+    // res == false
+});
+```
 
 ### sync
 
@@ -151,7 +170,7 @@ If you are using bcrypt on a simple script, using the sync mode is perfectly fin
     * `rounds` - [OPTIONAL] - the cost of processing the data. (default - 10)
   * `genSalt(rounds, cb)`
     * `rounds` - [OPTIONAL] - the cost of processing the data. (default - 10)
-    * `cb` - [REQUIRED] - a callback to be fired once the salt has been generated. uses eio making it asynchronous.
+    * `cb` - [OPTIONAL] - a callback to be fired once the salt has been generated. uses eio making it asynchronous. If `cb` is not specified, a `Promise` is returned if Promise support is available.
       * `err` - First parameter to the callback detailing any errors.
       * `salt` - Second parameter to the callback providing the generated salt.
   * `hashSync(data, salt)`
@@ -160,7 +179,7 @@ If you are using bcrypt on a simple script, using the sync mode is perfectly fin
   * `hash(data, salt, cb)`
     * `data` - [REQUIRED] - the data to be encrypted.
     * `salt` - [REQUIRED] - the salt to be used to hash the password. if specified as a number then a salt will be generated with the specified number of rounds and used (see example under **Usage**).
-    * `cb` - [REQUIRED] - a callback to be fired once the data has been encrypted. uses eio making it asynchronous.
+    * `cb` - [OPTIONAL] - a callback to be fired once the data has been encrypted. uses eio making it asynchronous. If `cb` is not specified, a `Promise` is returned if Promise support is available.
       * `err` - First parameter to the callback detailing any errors.
       * `encrypted` - Second parameter to the callback providing the encrypted form.
   * `compareSync(data, encrypted)`
@@ -169,7 +188,7 @@ If you are using bcrypt on a simple script, using the sync mode is perfectly fin
   * `compare(data, encrypted, cb)`
     * `data` - [REQUIRED] - data to compare.
     * `encrypted` - [REQUIRED] - data to be compared to.
-    * `cb` - [REQUIRED] - a callback to be fired once the data has been compared. uses eio making it asynchronous.
+    * `cb` - [OPTIONAL] - a callback to be fired once the data has been compared. uses eio making it asynchronous. If `cb` is not specified, a `Promise` is returned if Promise support is available.
       * `err` - First parameter to the callback detailing any errors.
       * `same` - Second parameter to the callback providing whether the data and encrypted forms match [true | false].
   * `getRounds(encrypted)` - return the number of rounds used to encrypt a given hash

bcrypt.js

@@ -7,6 +7,8 @@ var bindings = require(binding_path);
 
 var crypto = require('crypto');
 
+var promises = require('./lib/promises');
+
 /// generate a salt (sync)
 /// @param {Number} [rounds] number of rounds (default 10)
 /// @return {String} salt
@@ -36,6 +38,10 @@ module.exports.genSalt = function(rounds, ignore, cb) {
         cb = arguments[1];
     }
 
+    if (!cb) {
+        return promises.promise(this.genSalt, this, arguments);
+    }
+
     // default 10 rounds
     if (!rounds) {
         rounds = 10;
@@ -46,10 +52,6 @@ module.exports.genSalt = function(rounds, ignore, cb) {
         });
     }
 
-    if (!cb) {
-        return;
-    }
-
     crypto.randomBytes(16, function(error, randomBytes) {
         if (error) {
             cb(error);
@@ -97,6 +99,16 @@ module.exports.hash = function(data, salt, cb) {
         });
     }
 
+    // cb exists but is not a function
+    // return a rejecting promise
+    if (cb && typeof cb !== 'function') {
+        return promises.reject(new Error('cb must be a function or null to return a Promise'));
+    }
+
+    if (!cb) {
+        return promises.promise(this.hash, this, arguments);
+    }
+
     if (data == null || salt == null) {
         return process.nextTick(function() {
             cb(new Error('data and salt arguments required'));
@@ -109,9 +121,6 @@ module.exports.hash = function(data, salt, cb) {
         });
     }
 
-    if (!cb || typeof cb !== 'function') {
-        return;
-    }
 
     if (typeof salt === 'number') {
         return module.exports.genSalt(salt, function(err, salt) {
@@ -155,8 +164,14 @@ module.exports.compare = function(data, hash, cb) {
         });
     }
 
-    if (!cb || typeof cb !== 'function') {
-        return;
+    // cb exists but is not a function
+    // return a rejecting promise
+    if (cb && typeof cb !== 'function') {
+        return promises.reject(new Error('cb must be a function or null to return a Promise'));
+    }
+
+    if (!cb) {
+        return promises.promise(this.compare, this, arguments);
     }
 
     return bindings.compare(data, hash, cb);

lib/promises.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/// encapsulate a method with a node-style callback in a Promise
+/// @param {object} 'this' of the encapsulated function
+/// @param {function} function to be encapsulated
+/// @param {Array-like} args to be passed to the called function
+/// @return {Promise} a Promise encapuslaing the function
+module.exports.promise = function (fn, context, args) {
+
+    //can't do anything without Promise so fail silently
+    if (typeof Promise === 'undefined') {
+        return;
+    }
+
+    if (!Array.isArray(args)) {
+        args = Array.prototype.slice.call(args);
+    }
+
+    if (typeof fn !== 'function') {
+        return Promise.reject(new Error('fn must be a function'));
+    }
+
+    return new Promise(function(resolve, reject) {
+        args.push(function(err, data) {
+            if (err) {
+                reject(err);
+            } else {
+                resolve(data);
+            }
+        });
+
+        fn.apply(context, args);
+    });
+};
+
+/// @param {err} the error to be thrown
+module.exports.reject = function (err) {
+
+    // silently swallow errors if Promise is not defined
+    // emulating old behavior
+    if (typeof Promise === 'undefined') {
+        return;
+    }
+
+    return Promise.reject(err);
+};

test/promise.js

@@ -0,0 +1,188 @@
+var bcrypt = require('../bcrypt');
+
+var fail = function(assert, error) {
+    assert.ok(false, error);
+    assert.done();
+};
+
+// only run these tests if Promise is available
+if (typeof Promise !== 'undefined') {
+    module.exports = {
+        test_salt_returns_promise_on_no_args: function(assert) {
+            // make sure test passes with non-native implementations such as bluebird
+            // http://stackoverflow.com/questions/27746304/how-do-i-tell-if-an-object-is-a-promise
+            assert.ok(typeof bcrypt.genSalt().then === 'function', "Should return a promise");
+            assert.done();
+        },
+        test_salt_length: function(assert) {
+            assert.expect(2);
+            bcrypt.genSalt(10).then(function(salt) {
+                assert.ok(typeof salt !== 'undefined', 'salt must not be undefined');
+                assert.equals(29, salt.length, "Salt isn't the correct length.");
+                assert.done();
+            });
+        },
+        test_salt_rounds_is_string_number: function(assert) {
+            assert.expect(1);
+            bcrypt.genSalt('10').then(function() {
+                fail(assert, "should not be resolved");
+            }).catch(function(err) {
+                assert.ok((err instanceof Error), "Should be an Error. genSalt requires round to be of type number.");
+            }).then(function() {
+                assert.done();
+            });
+        },
+        test_salt_rounds_is_string_non_number: function(assert) {
+            assert.expect(1);
+            bcrypt.genSalt('b').then(function() {
+                fail(assert, "should not be resolved");
+            }).catch(function(err) {
+                assert.ok((err instanceof Error), "Should be an Error. genSalt requires round to be of type number.");
+            }).then(function() {
+                assert.done();
+            });
+        },
+        test_hash: function(assert) {
+            assert.expect(1);
+            bcrypt.genSalt(10).then(function(salt) {
+                return bcrypt.hash('password', salt);
+            }).then(function(res) {
+                assert.ok(res, "Res should be defined.");
+                assert.done();
+            });
+        },
+        test_hash_rounds: function(assert) {
+            assert.expect(1);
+            bcrypt.hash('bacon', 8).then(function(hash) {
+                assert.equals(bcrypt.getRounds(hash), 8, "Number of rounds should be that specified in the function call.");
+                assert.done();
+            });
+        },
+        test_hash_empty_strings: function(assert) {
+            assert.expect(2);
+            Promise.all([
+                bcrypt.genSalt(10).then(function(salt) {
+                    return bcrypt.hash('', salt);
+                }).then(function(res) {
+                    assert.ok(res, "Res should be defined even with an empty pw.");
+                }),
+                bcrypt.hash('', '').then(function() {
+                    fail(assert, "should not be resolved")
+                }).catch(function(err) {
+                    assert.ok(err);
+                }),
+            ]).then(function() {
+                assert.done();
+            });
+        },
+        test_hash_no_params: function(assert) {
+            assert.expect(1);
+            bcrypt.hash().then(function() {
+                fail(assert, "should not be resolved");
+            }).catch(function(err) {
+                assert.ok(err, "Should be an error. No params.");
+            }).then(function() {
+                assert.done();
+            });
+        },
+        test_hash_one_param: function(assert) {
+            assert.expect(1);
+            bcrypt.hash('password').then(function() {
+                fail(assert, "should not be resolved");
+            }).catch(function(err) {
+                assert.ok(err, "Should be an error. No salt.");
+            }).then(function() {
+                assert.done();
+            });
+        },
+        test_hash_salt_validity: function(assert) {
+            assert.expect(3);
+            Promise.all(
+                [
+                    bcrypt.hash('password', '$2a$10$somesaltyvaluertsetrse').then(function(enc) {
+                        assert.ok(enc, "should be resolved with a value");
+                    }),
+                    bcrypt.hash('password', 'some$value').then(function() {
+                        fail(assert, "should not resolve");
+                    }).catch(function(err) {
+                        assert.notEqual(err, undefined);
+                        assert.equal(err.message, "Invalid salt. Salt must be in the form of: $Vers$log2(NumRounds)$saltvalue");
+                    })
+                ]).then(function() {
+                assert.done();
+            });
+        },
+        test_verify_salt: function(assert) {
+            assert.expect(2);
+            bcrypt.genSalt(10).then(function(salt) {
+                var split_salt = salt.split('$');
+                assert.ok(split_salt[1], '2a');
+                assert.ok(split_salt[2], '10');
+                assert.done();
+            });
+        },
+        test_verify_salt_min_rounds: function(assert) {
+            assert.expect(2);
+            bcrypt.genSalt(1).then(function(salt) {
+                var split_salt = salt.split('$');
+                assert.ok(split_salt[1], '2a');
+                assert.ok(split_salt[2], '4');
+                assert.done();
+            });
+        },
+        test_verify_salt_max_rounds: function(assert) {
+            assert.expect(2);
+            bcrypt.genSalt(100).then(function(salt) {
+                var split_salt = salt.split('$');
+                assert.ok(split_salt[1], '2a');
+                assert.ok(split_salt[2], '31');
+                assert.done();
+            });
+        },
+        test_hash_compare: function(assert) {
+            assert.expect(3);
+            bcrypt.genSalt(10).then(function(salt) {
+                assert.equals(29, salt.length, "Salt isn't the correct length.");
+                return bcrypt.hash("test", salt);
+            }).then(function(hash) {
+                return Promise.all(
+                    [
+                        bcrypt.compare("test", hash).then(function(res) {
+                            assert.equal(res, true, "These hashes should be equal.");
+                        }),
+                        bcrypt.compare("blah", hash).then(function(res) {
+                            assert.equal(res, false, "These hashes should not be equal.");
+                        })
+                    ]).then(function() {
+                    assert.done();
+                });
+            });
+        },
+        test_hash_compare_empty_strings: function(assert) {
+            assert.expect(2);
+            var hash = bcrypt.hashSync("test", bcrypt.genSaltSync(10));
+            bcrypt.compare("", hash).then(function(res) {
+                assert.equal(res, false, "These hashes should be equal.");
+                return bcrypt.compare("", "");
+            }).then(function(res) {
+                assert.equal(res, false, "These hashes should be equal.");
+                assert.done();
+            });
+        },
+        test_hash_compare_invalid_strings: function(assert) {
+            var fullString = 'envy1362987212538';
+            var hash = '$2a$10$XOPbrlUPQdwdJUpSrIF6X.LbE14qsMmKGhM1A8W9iqaG3vv1BD7WC';
+            var wut = ':';
+            Promise.all([
+                bcrypt.compare(fullString, hash).then(function(res) {
+                    assert.ok(res);
+                }),
+                bcrypt.compare(fullString, wut).then(function(res) {
+                    assert.ok(!res);
+                })
+            ]).then(function() {
+                assert.done();
+            });
+        }
+    };
+}