// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* A helper used to inform Behat that an operation is in progress and that Behat must wait for it to complete.
*
* @module core/pending
* @copyright 2018 Andrew Nicols <andrew@nicols.co.uk>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
* @since 3.6
*/
/**
* A helper used to register any long-running operations that are in-progress and that Behat must wait for it to complete.
*
* This is useful in cases where the user interface may be updated and take some time to change - for example where
* applying a transition.
*
* This data is used by Behat, but may also be consumed by other location too.
*
* By informing Behat that an action is about to happen, and then that it is complete, allows
* Behat to wait for that completion and avoid random failures in automated testing.
*
* Note: It is recommended that a descriptive key be used to aid in debugging where possible, but this is optional.
*/
export default class {
/**
* Create a new Pending Promise statically.
*
* @param {String} pendingKey An identifier to help in debugging
* @return {Promise} A Native Promise
* @deprecated since Moodle 4.2
*/
static request(pendingKey) {
window.console.error(
`The core/pending::request method has been deprecated. ` +
`Please use one of the alternative calls to core/pending, for example "new Pending('${pendingKey}')". ` +
`Called with ${pendingKey}`
);
return new this(pendingKey);
}
/**
* Request a new pendingPromise for later resolution.
*
* When the action you are performing is complete, simply call resolve on the returned Promise.
*
* @param {String} [pendingKey='pendingPromise'] An identifier to help in debugging
* @return {Promise} A Native Promise
* @example
* import Pending from 'core/pending';
* import {getString} from 'core/str';
*
* const stringPromise = new Pending('mod_myexample/setup');
* const myString = getString('ok')
* .then(okay => {
* window.console.log(okay);
* })
* .then(okay => stringPromise.resolve(okay));
*/
constructor(pendingKey = 'pendingPromise') {
let resolver;
let rejector;
const pendingPromise = this.constructor.Promise((resolve, reject) => {
resolver = resolve;
rejector = reject;
}, pendingKey);
pendingPromise.resolve = resolver;
pendingPromise.reject = rejector;
return pendingPromise;
}
/**
* Create a new Pending Promise with the same interface as a native Promise.
*
* @param {Callable} fn A callable which takes the resolve and reject arguments as in a Native Promise constructor.
* @param {String} [pendingKey='pendingPromise'] An identifier to help in debugging
* @returns {Promise}
* @since Moodle 4.2
* @example
* // Use the Pending class in the same way that you would a Native Promise.
* import Pending from 'core/pending';
* import {getString} from 'core/str';
*
* export const init => {
* Pending.Promise((resolve, reject) => {
* getString('ok')
* .then(okay => {
* window.console.log(okay);
* return okay;
* })
* .then(resolve)
* .catch(reject);
* }, 'mod_myexample/setup:init');
* };
*/
static Promise(fn, pendingKey = 'pendingPromise') {
const resolver = new Promise((resolve, reject) => {
M.util.js_pending(pendingKey);
fn(resolve, reject);
});
resolver.then(() => {
M.util.js_complete(pendingKey);
return;
}).catch();
return resolver;
}
}