Add parley.callable().

mikermcneil · Aug 10, 2019 · b87fb97 · b87fb97
1 parent 348d8ed
commit b87fb97
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 50 deletions.
diff --git a/lib/parley.js b/lib/parley.js
@@ -350,52 +350,56 @@ module.exports = function parley(handleExec, explicitCbMaybe, customMethods, tim
 };//ƒ
 
 
-// FUTURE: finish this:
-//
-// /**
-//  * parley.callable()
-//  *
-//  * Build a simple function which returns a Deferred object.
-//  * > This is a shortcut for building simple functions when you don't need the
-//  * > full customizability of calling parley() to build a Deferred for you on the
-//  * > fly (e.g. b/c as an implementor, you don't care about having custom
-//  * > chainable methods)
-//  *
-//  * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-//  * @param {AsyncFunction} gracefullyHandleExec
-//  * @param {Number?} timeout
-//  * @param {Error?} omen
-//  *
-//  * @returns {Function}
-//  */
-// module.exports.callable = function(gracefullyHandleExec, timeoutMaybe, omenMaybe){
-
-//   if (!_.isFunction(gracefullyHandleExec) || gracefullyHandleExec.constructor.name !== 'AsyncFunction') {
-//     throw new Error('parley.callable() expects an async function (e.g. `async ()=>{}`) to be provided as the first argument.  Instead, got: '+util.inspect(gracefullyHandleExec, {depth:5}));
-//   }//•
-
-//   return function handleCalling(/*…*/) {
-//     // ^Note that this function is _deliberately_ NOT an arrow function, so that
-//     // we can use `this` and `arguments` to simulate gracefullyHandleExec being
-//     // called exactly as-is.  (In most cases, this should not matter.  But
-//     // packages are sometimes used in mysterious, eclectic ways.)
-//     //
-//     // Also note that we name this function (handleCalling) so that we can
-//     // reference it below when we build an omen.
-
-//     var parley = module.exports;
-//     var newCallableFnArguments = arguments;
-//     var newCallableFnCtx = this;//« should really never matter, we just do it this way for consistency
-//     omen = omen || flaverr.omen(handleCalling);
-//     return parley((done)=>{
-//       gracefullyHandleExec.apply(newCallableFnCtx, newCallableFnArguments)
-//       .then((resultMaybe)=>{
-//         done(undefined, resultMaybe);
-//       })
-//       .catch((err)=>{
-//         done(err);
-//       });
-//     }, undefined, undefined, timeout, omen, undefined);
-//   };//ƒ
-
-// };//ƒ
+
+/**
+ * parley.callable()
+ *
+ * Build & return a "parley callable", a simple asynchronous function which,
+ * every time it is invoked, returns a Deferred object.
+ * > This is a shortcut for building simple functions when you don't need the
+ * > full customizability of calling parley() to build a Deferred for you on the
+ * > fly (e.g. b/c as an implementor, you don't care about having custom
+ * > chainable methods)
+ *
+ * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+ * @param {AsyncFunction} gracefullyHandleExec
+ * @param {Number?} timeout
+ * @param {Error?} omen
+ *
+ * @returns {Function}
+ */
+module.exports.callable = (gracefullyHandleExec, timeout, omen)=>{
+
+  if (!_.isFunction(gracefullyHandleExec) || gracefullyHandleExec.constructor.name !== 'AsyncFunction') {
+    throw new Error('parley.callable() expects an async function (e.g. `async ()=>{}`) to be provided as the first argument.  Instead, got: '+util.inspect(gracefullyHandleExec, {depth:5}));
+  }//•
+
+  // Build our "callable"
+  //
+  // Note that this function is _deliberately_ NOT an arrow function, so that
+  // we can use `this` and `arguments` to simulate gracefullyHandleExec being
+  // called exactly as-is.  (In most cases, this should not matter.  But
+  // packages are sometimes used in mysterious, eclectic ways.)
+  //
+  // Also note that we name this function so that we can reference it below
+  // when we build an omen.
+  let parleyCallableFn = function (/*…*/) {
+    let parley = module.exports;
+    let newCallableFnArguments = arguments;
+    let newCallableFnCtx = this;//« should really never matter, we just do it this way for consistency
+    omen = omen || flaverr.omen(parleyCallableFn);
+    return parley((done)=>{
+      gracefullyHandleExec.apply(newCallableFnCtx, newCallableFnArguments)
+      .then((resultMaybe)=>{
+        done(undefined, resultMaybe);
+      })
+      .catch((err)=>{
+        done(err);
+      });
+    }, undefined, undefined, timeout, omen, undefined);
+  };//ƒ
+
+  // Return our new "callable"
+  return parleyCallableFn;
+
+};//ƒ
diff --git a/lib/private/Deferred.js b/lib/private/Deferred.js
@@ -726,7 +726,7 @@ Deferred.prototype.timeout = function (ms){
 // (This is mainly to hide the `_omen` property, which is pretty scary-looking)
 Deferred.prototype.toJSON = function (){ return null; };
 Deferred.prototype.toString = function (){ return '[Deferred]'; };
-Deferred.prototype.inspect = function (){ return '[Deferred]'; };
+Deferred.prototype.inspect = function (){ return '[Deferred]'; };// «« TODO: also include the symbol equivalent for Node >=10
 
 
 /**