Source: util/sync-promise.js

  1. /**
  2.  * Copyright (C) 2015-2018 Regents of the University of California.
  3.  * @author: Jeff Thompson <jefft0@remap.ucla.edu>
  4.  *
  5.  * This program is free software: you can redistribute it and/or modify
  6.  * it under the terms of the GNU Lesser General Public License as published by
  7.  * the Free Software Foundation, either version 3 of the License, or
  8.  * (at your option) any later version.
  9.  *
  10.  * This program is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13.  * GNU Lesser General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Lesser General Public License
  16.  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17.  * A copy of the GNU Lesser General Public License is in the file COPYING.
  18.  */
  20. /** @ignore */
  21. var NdnCommon = require('./ndn-common.js').NdnCommon;
  23. /**
  24.  * A SyncPromise is a promise which is immediately fulfilled or rejected, used
  25.  * to return a promise in synchronous code.
  26.  * This private constructor creates a SyncPromise fulfilled or rejected with the
  27.  * given value. You should normally not call this constructor but call
  28.  * SyncPromise.resolve or SyncPromise.reject. Note that we don't need a
  29.  * constructor like SyncPromise(function(resolve, reject)) because this would be
  30.  * for scheduling the function to be called later, which we don't do.
  31.  * @param {any} value If isRejected is false, this is the value of the fulfilled
  32.  * promise, else if isRejected is true, this is the error.
  33.  * @param {boolean} isRejected True to create a promise in the rejected state,
  34.  * where value is the error.
  35.  * @constructor
  36.  */
  37. var SyncPromise = function SyncPromise(value, isRejected)
  38. {
  39.   this.value = value;
  40.   this.isRejected = isRejected;
  41. };
  43. exports.SyncPromise = SyncPromise;
  45. /**
  46.  * If this promise is fulfilled, immediately call onFulfilled with the fulfilled
  47.  * value as described below. Otherwise, if this promise is rejected, immediately
  48.  * call onRejected with the error as described below.
  49.  * @param {function} (optional) onFulfilled If this promise is fulfilled, this
  50.  * calls onFulfilled(value) with the value of this promise and returns the
  51.  * result. The function should return a promise. To use all synchronous code,
  52.  * onFulfilled should return SyncPromise.resolve(newValue).
  53.  * @param {function} (optional) onRejected If this promise is rejected, this
  54.  * calls onRejected(err) with the error value of this promise and returns the
  55.  * result. The function should return a promise. To use all synchronous code,
  56.  * onFulfilled should return SyncPromise.resolve(newValue) (or throw an
  57.  * exception).
  58.  * @return {Promise|SyncPromise} If this promise is fulfilled, return the result
  59.  * of calling onFulfilled(value). Note that this does not create a promise which
  60.  * is scheduled to execute later. Rather it immediately calls onFulfilled which
  61.  * should return a promise. But if onFulfilled is undefined, simply return this
  62.  * promise to pass it forward. If this promise is rejected, return the result of
  63.  * calling onRejected(err) with the error value. But if onRejected is undefined,
  64.  * simply return this promise to pass it forward. However, if onFulfilled or
  65.  * onRejected throws an exception, then return a new SyncPromise in the rejected
  66.  * state with the exception.
  67.  */
  68. SyncPromise.prototype.then = function(onFulfilled, onRejected)
  69. {
  70.   if (this.isRejected) {
  71.     if (onRejected) {
  72.       try {
  73.         return onRejected(this.value);
  74.       }
  75.       catch(err) {
  76.         return new SyncPromise(err, true);
  77.       }
  78.     }
  79.     else
  80.       // Pass the error forward.
  81.       return this;
  82.   }
  83.   else {
  84.     if (onFulfilled) {
  85.       try {
  86.         return onFulfilled(this.value);
  87.       }
  88.       catch(err) {
  89.         return new SyncPromise(err, true);
  90.       }
  91.     }
  92.     else
  93.       // Pass the fulfilled value forward.
  94.       return this;
  95.   }
  96. };
  98. /**
  99.  * Call this.then(undefined, onRejected) and return the result. If this promise
  100.  * is rejected then onRejected will process it. If this promise is fulfilled,
  101.  * this simply passes it forward.
  102.  */
  103. SyncPromise.prototype.catch = function(onRejected)
  104. {
  105.   return this.then(undefined, onRejected);
  106. };
  108. /**
  109.  * Return a new SyncPromise which is already fulfilled to the given value.
  110.  * @param {any} value The value of the promise.
  111.  */
  112. SyncPromise.resolve = function(value)
  113. {
  114.   return new SyncPromise(value, false);
  115. };
  117. /**
  118.  * Return a new SyncPromise which is already rejected with the given error.
  119.  * @param {any} err The error for the rejected promise.
  120.  */
  121. SyncPromise.reject = function(err)
  122. {
  123.   return new SyncPromise(err, true);
  124. };
  126. /**
  127.  * This static method checks if the promise is a SyncPromise and immediately
  128.  * returns its value or throws the error if promise is rejected. If promise is
  129.  * not a SyncPromise, this throws an exception since it is not possible to
  130.  * immediately get the value. This can be used with "promise-based" code which
  131.  * you expect to always return a SyncPromise to operate in synchronous mode.
  132.  * @param {SyncPromise} promise The SyncPromise with the value to get.
  133.  * @return {any} The value of the promise.
  134.  * @throws Error If promise is not a SyncPromise.
  135.  * @throws any If promise is a SyncPromise in the rejected state, this throws
  136.  * the error.
  137.  */
  138. SyncPromise.getValue = function(promise)
  139. {
  140.   if (promise instanceof SyncPromise) {
  141.     if (promise.isRejected)
  142.       throw promise.value;
  143.     else
  144.       return promise.value;
  145.   }
  146.   else
  147.     throw new Error("Cannot return immediately because promise is not a SyncPromise");
  148. };
  150. /**
  151.  * This can be called with complete(onComplete, promise) or
  152.  * complete(onComplete, onError, promise) to handle both synchronous and
  153.  * asynchronous code based on whether the caller supplies the onComlete callback.
  154.  * If onComplete is defined, call promise.then with a function which calls
  155.  * onComplete(value) when fulfilled (possibly in asynchronous mode). If
  156.  * onComplete is undefined, then we are in synchronous mode so return
  157.  * SyncPromise.getValue(promise) which will throw an exception if the promise is
  158.  * not a SyncPromise (or is a SyncPromise in the rejected state).
  159.  * @param {function} onComplete If defined, this calls promise.then to fulfill
  160.  * the promise, then calls onComplete(value) with the value of the promise.
  161.  * If onComplete is undefined, the return value is described below.
  162.  * NOTE: The library will log any exceptions thrown by this callback, but for
  163.  * better error handling the callback should catch and properly handle any
  164.  * exceptions.
  165.  * @param {function} onError (optional) If defined, then onComplete must be
  166.  * defined and if there is an error when this calls promise.then, this calls
  167.  * onError(err) with the value of the error. If onComplete is undefined, then
  168.  * onError is ignored and this will call SyncPromise.getValue(promise) which may
  169.  * throw an exception.
  170.  * NOTE: The library will log any exceptions thrown by this callback, but for
  171.  * better error handling the callback should catch and properly handle any
  172.  * exceptions.
  173.  * @param {Promise|SyncPromise} promise If onComplete is defined, this calls
  174.  * promise.then. Otherwise, this calls SyncPromise.getValue(promise).
  175.  * @return {any} If onComplete is undefined, return SyncPromise.getValue(promise).
  176.  * Otherwise, if onComplete is supplied then return undefined and use
  177.  * onComplete as described above.
  178.  * @throws Error If onComplete is undefined and promise is not a SyncPromise.
  179.  * @throws any If onComplete is undefined and promise is a SyncPromise in the
  180.  * rejected state.
  181.  */
  182. SyncPromise.complete = function(onComplete, onErrorOrPromise, promise)
  183. {
  184.   var onError;
  185.   if (promise)
  186.     onError = onErrorOrPromise;
  187.   else {
  188.     promise = onErrorOrPromise;
  189.     onError = null;
  190.   }
  192.   if (onComplete)
  193.     promise
  194.     .then(function(value) {
  195.       try {
  196.         onComplete(value);
  197.       } catch (ex) {
  198.         console.log("Error in onComplete: " + NdnCommon.getErrorWithStackTrace(ex));
  199.       }
  200.     }, function(err) {
  201.       if (onError) {
  202.         try {
  203.           onError(err);
  204.         } catch (ex) {
  205.           console.log("Error in onError: " + NdnCommon.getErrorWithStackTrace(ex));
  206.         }
  207.       }
  208.       else {
  209.         if (promise instanceof SyncPromise)
  210.           throw err;
  211.         else
  212.           // We are in an async promise callback, so a thrown exception won't
  213.           // reach the caller. Just log it.
  214.           console.log("Uncaught exception from a Promise: " +
  215.             NdnCommon.getErrorWithStackTrace(err));
  216.       }
  217.     });
  218.   else
  219.     return SyncPromise.getValue(promise);
  220. };