lib/amd/src/pending.js

  1. // This file is part of Moodle - http://moodle.org/
  2. //
  3. // Moodle is free software: you can redistribute it and/or modify
  4. // it under the terms of the GNU General Public License as published by
  5. // the Free Software Foundation, either version 3 of the License, or
  6. // (at your option) any later version.
  7. //
  8. // Moodle is distributed in the hope that it will be useful,
  9. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. // GNU General Public License for more details.
  12. //
  13. // You should have received a copy of the GNU General Public License
  14. // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16. /**
  17.  * A helper used to inform Behat that an operation is in progress and that Behat must wait for it to complete.
  18.  *
  19.  * @module     core/pending
  20.  * @copyright  2018 Andrew Nicols <andrew@nicols.co.uk>
  21.  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22.  * @since      3.6
  23.  */
  25. /**
  26.  * A helper used to register any long-running operations that are in-progress and that Behat must wait for it to complete.
  27.  *
  28.  * This is useful in cases where the user interface may be updated and take some time to change - for example where
  29.  * applying a transition.
  30.  *
  31.  * This data is used by Behat, but may also be consumed by other location too.
  32.  *
  33.  * By informing Behat that an action is about to happen, and then that it is complete, allows
  34.  * Behat to wait for that completion and avoid random failures in automated testing.
  35.  *
  36.  * Note: It is recommended that a descriptive key be used to aid in debugging where possible, but this is optional.
  37.  */
  38. export default class {
  40.     /**
  41.      * Create a new Pending Promise statically.
  42.      *
  43.      * @param {String} pendingKey An identifier to help in debugging
  44.      * @return {Promise} A Native Promise
  45.      * @deprecated since Moodle 4.2
  46.      */
  47.     static request(pendingKey) {
  48.         window.console.error(
  49.             `The core/pending::request method has been deprecated. ` +
  50.             `Please use one of the alternative calls to core/pending, for example "new Pending('${pendingKey}')". ` +
  51.             `Called with ${pendingKey}`
  52.         );
  53.         return new this(pendingKey);
  54.     }
  56.     /**
  57.      * Request a new pendingPromise for later resolution.
  58.      *
  59.      * When the action you are performing is complete, simply call resolve on the returned Promise.
  60.      *
  61.      * @param {String} [pendingKey='pendingPromise'] An identifier to help in debugging
  62.      * @return {Promise} A Native Promise
  63.      * @example
  64.      * import Pending from 'core/pending';
  65.      * import {getString} from 'core/str';
  66.      *
  67.      * const stringPromise = new Pending('mod_myexample/setup');
  68.      * const myString = getString('ok')
  69.      *     .then(okay => {
  70.      *         window.console.log(okay);
  71.      *     })
  72.      *     .then(okay => stringPromise.resolve(okay));
  73.      */
  74.     constructor(pendingKey = 'pendingPromise') {
  75.         let resolver;
  76.         let rejector;
  77.         const pendingPromise = this.constructor.Promise((resolve, reject) => {
  78.             resolver = resolve;
  79.             rejector = reject;
  80.         }, pendingKey);
  81.         pendingPromise.resolve = resolver;
  82.         pendingPromise.reject = rejector;
  84.         return pendingPromise;
  85.     }
  87.     /**
  88.      * Create a new Pending Promise with the same interface as a native Promise.
  89.      *
  90.      * @param {Callable} fn A callable which takes the resolve and reject arguments as in a Native Promise constructor.
  91.      * @param {String} [pendingKey='pendingPromise'] An identifier to help in debugging
  92.      * @returns {Promise}
  93.      * @since Moodle 4.2
  94.      * @example
  95.      * // Use the Pending class in the same way that you would a Native Promise.
  96.      * import Pending from 'core/pending';
  97.      * import {getString} from 'core/str';
  98.      *
  99.      * export const init => {
  100.      *     Pending.Promise((resolve, reject) => {
  101.      *         getString('ok')
  102.      *             .then(okay => {
  103.      *                 window.console.log(okay);
  104.      *                 return okay;
  105.      *             })
  106.      *             .then(resolve)
  107.      *             .catch(reject);
  108.      *     }, 'mod_myexample/setup:init');
  109.      * };
  110.      */
  111.     static Promise(fn, pendingKey = 'pendingPromise') {
  112.         const resolver = new Promise((resolve, reject) => {
  113.             M.util.js_pending(pendingKey);
  115.             fn(resolve, reject);
  116.         });
  118.         resolver.then(() => {
  119.             M.util.js_complete(pendingKey);
  120.             return;
  121.         }).catch();
  123.         return resolver;
  124.     }
  125. }