Add comments.

lib/authenticator.js

@@ -165,12 +165,49 @@ Authenticator.prototype.authenticate = function(strategy, options, callback) {
   return this._framework.authenticate(this, strategy, options, callback);
 };
 
-
-Authenticator.prototype.authenticateWith = function(strategy, options, callback) {
-  return this._framework.authenticateWith(this, strategy, options, callback);
+/**
+ * Middleware that uses the given `configurator` to setup a strategy, which it
+ * will use authenticate a request, with optional `options` and `callback`.
+ *
+ * Examples:
+ *
+ *     function config(req, done) {
+ *       var lstrategy = new LocalStrategy(function(username, password, done) {
+ *         var db = dbs[req.params.directory];
+ *
+ *         db.users.verify(username, password, function(err, user) {
+ *           if (err) { return next(err); }
+ *           if (!user) { return done(null, false); }
+ *           return done(null, user);
+ *         });
+ *       }
+ *
+ *       return done(null, lstrategy);
+ *     }
+ *
+ *     passport.authenticateWith(config, { successRedirect: '/', failureRedirect: '/login' })(req, res);
+ *
+ *     passport.authenticateWith(config, function(err, user) {
+ *       if (!user) { return res.redirect('/login'); }
+ *       res.end('AuthenticateWithd!');
+ *     })(req, res);
+ *
+ *     passport.authenticateWith(config, { session: false })(req, res);
+ *
+ *     app.get('/authenticate', passport.authenticateWith(config), function(req, res) {
+ *       res.json(req.user);
+ *     });
+ *
+ * @param {Strategy} configurator
+ * @param {Object} options
+ * @param {Function} callback
+ * @return {Function} middleware
+ * @api public
+ */
+Authenticator.prototype.authenticateWith = function(configurator, options, callback) {
+  return this._framework.authenticateWith(this, configurator, options, callback);
 };
 
-
 /**
  * Middleware that will authorize a third-party account using the given
  * `strategy` name, with optional `options`.

lib/middleware/authenticateWith.js

@@ -5,22 +5,45 @@ var authenticate = require('./authenticate')
   , Strategy = require('passport-strategy')
 
 
+
+/**
+ * Dynamically configures methods for authenticating requests.
+ *
+ * Employs the `configurator` to dynamically determine either a Strategy or
+ * list of strategy names with which to authenticate the request. This allows
+ * the authentication to be undertaken with context of the individual request.
+ * If the configurator returns a list of strategy names, those strategies must
+ * be preconfigured, as for the standard `authenticate` middleware.
+ *
+ * See the superior `authenticate` middleware for more information and details.
+ *
+ * @param {Function} configurator
+ * @param {Object} options
+ * @param {Function} callback
+ * @return {Function}
+ * @api public
+ */
 module.exports = function authenticateWith(passport, configurator, options, callback) {
   if (typeof options == 'function') {
     callback = options;
     options = {};
   }
   options = options || {};
 
-  if (!configurator) { throw new TypeError('passport.authenticateWith middleware requires a configuration function'); }
+  // The default configurator will cause `authenticate` to fail and handle
+  // that failure as per how it is set up.
+  configurator = configurator || function(req, done) { return done(); }
 
   return function authenticateWith(req, res, next) {
 
     function configured(err, method) {
       if (err) { return next(err); }
-      if (!method) {
-        return next(new Error('Dynamic configuration did not return a valid passport strategy'));
-      }
+
+      // If configuration does not return a Strategy or name(s) of strategies,
+      // we will pass up an empty array, which `authenticate` will handle using
+      // the preferred failure mode. This provides the least behavioral
+      // divergence between this middleware and `authenticate`.
+      method = method || [];
 
       return authenticate(passport, method, options, callback)(req, res, next);
     }