@converse/headless/shared/api/promise.js

Converse.js Headless build

import _converse from '../_converse.js';
import { getOpenPromise } from '@converse/openpromise';
import { waitUntil } from '../../utils/promise.js';
import { isFunction } from '../../utils/object.js';

export default {
    /**
     * Converse and its plugins trigger various events which you can listen to via the
     * {@link _converse.api.listen} namespace.
     *
     * Some of these events are also available as Promises although not all of them could
     * logically act as promises, since some events might be fired multiple times whereas
     * promises are to be resolved (or rejected) only once.
     *
     * Events which are also promises include:
     *
     * * cachedRoster
     * * chatBoxesFetched
     * * pluginsInitialized
     * * roster
     * * rosterContactsFetched
     * * rosterGroupsFetched
     * * rosterInitialized
     *
     * The various plugins might also provide promises, and they do this by using the
     * `promises.add` api method.
     *
     * @namespace _converse.api.promises
     * @memberOf _converse.api
     */
    promises: {
        /**
         * By calling `promises.add`, a new [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
         * is made available for other code or plugins to depend on via the
         * {@link _converse.api.waitUntil} method.
         *
         * Generally, it's the responsibility of the plugin which adds the promise to
         * also resolve it.
         *
         * This is done by calling {@link _converse.api.trigger}, which not only resolves the
         * promise, but also emits an event with the same name (which can be listened to
         * via {@link _converse.api.listen}).
         *
         * @method _converse.api.promises.add
         * @param {string|array} [promises] The name or an array of names for the promise(s) to be added
         * @param {boolean} [replace=true] Whether this promise should be replaced with a new one when the user logs out.
         * @example _converse.api.promises.add('foo-completed');
         */
        add(promises, replace = true) {
            promises = Array.isArray(promises) ? promises : [promises];
            promises.forEach((name) => {
                /** @type {import('../types').ReplaceableOpenPromise} */
                const promise = getOpenPromise();
                promise.replace = replace;
                _converse.promises[name] = promise;
            });
        },
    },

    /**
     * Wait until a promise is resolved or until the passed in function returns
     * a truthy value.
     * @method _converse.api.waitUntil
     * @param {string|function} condition - The name of the promise to wait for,
     * or a function which should eventually return a truthy value.
     * @returns {Promise}
     */
    waitUntil(condition) {
        if (isFunction(condition)) {
            return waitUntil(/** @type {Function} */ (condition));
        } else {
            const promise = _converse.promises[condition];
            if (promise === undefined) {
                return null;
            }
            return promise;
        }
    },
};