lib/amd/src/local/reactive/reactive.js

// 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 generic single state reactive module.
 *
 * @module     core/local/reactive/reactive
 * @class      core/local/reactive/reactive
 * @copyright  2021 Ferran Recio <ferran@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
import log from 'core/log';
import StateManager from 'core/local/reactive/statemanager';
import Pending from 'core/pending';
// Count the number of pending operations done to ensure we have a unique id for each one.
let pendingCount = 0;
/**
 * Set up general reactive class to create a single state application with components.
 *
 * The reactive class is used for registering new UI components and manage the access to the state values
 * and mutations.
 *
 * When a new reactive instance is created, it will contain an empty state and and empty mutations
 * lists. When the state data is ready, the initial state can be loaded using the "setInitialState"
 * method. This will protect the state from writing and will trigger all the components "stateReady"
 * methods.
 *
 * State can only be altered by mutations. To replace all the mutations with a specific class,
 * use "setMutations" method. If you need to just add some new mutation methods, use "addMutations".
 *
 * To register new components into a reactive instance, use "registerComponent".
 *
 * Inside a component, use "dispatch" to invoke a mutation on the state (components can only access
 * the state in read only mode).
 */
export default class {
    /**
     * The component descriptor data structure.
     *
     * @typedef {object} description
     * @property {string} eventName the custom event name used for state changed events
     * @property {Function} eventDispatch the state update event dispatch function
     * @property {Element} [target] the target of the event dispatch. If not passed a fake element will be created
     * @property {Object} [mutations] an object with state mutations functions
     * @property {Object} [state] an object to initialize the state.
     */
    /**
     * Create a basic reactive manager.
     *
     * Note that if your state is not async loaded, you can pass directly on creation by using the
     * description.state attribute. However, this will initialize the state, this means
     * setInitialState will throw an exception because the state is already defined.
     *
     * @param {description} description reactive manager description.
     */
    constructor(description) {
        if (description.eventName === undefined || description.eventDispatch === undefined) {
            throw new Error(`Reactivity event required`);
        }
        if (description.name !== undefined) {
            this.name = description.name;
        }
        // Each reactive instance has its own element anchor to propagate state changes internally.
        // By default the module will create a fake DOM element to target custom events but
        // if all reactive components is constrait to a single element, this can be passed as
        // target in the description.
        this.target = description.target ?? document.createTextNode(null);
        this.eventName = description.eventName;
        this.eventDispatch = description.eventDispatch;
        // State manager is responsible for dispatch state change events when a mutation happens.
        this.stateManager = new StateManager(this.eventDispatch, this.target);
        // An internal registry of watchers and components.
        this.watchers = new Map([]);
        this.components = new Set([]);
        // Mutations can be overridden later using setMutations method.
        this.mutations = description.mutations ?? {};
        // Register the event to alert watchers when specific state change happens.
        this.target.addEventListener(this.eventName, this.callWatchersHandler.bind(this));
        // Add a pending operation waiting for the initial state.
        this.pendingState = new Pending(`core/reactive:registerInstance${pendingCount++}`);
        // Set initial state if we already have it.
        if (description.state !== undefined) {
            this.setInitialState(description.state);
        }
        // Check if we have a debug instance to register the instance.
        if (M.reactive !== undefined) {
            M.reactive.registerNewInstance(this);
        }
    }
    /**
     * State changed listener.
     *
     * This function take any state change and send it to the proper watchers.
     *
     * To prevent internal state changes from colliding with other reactive instances, only the
     * general "state changed" is triggered at document level. All the internal changes are
     * triggered at private target level without bubbling. This way any reactive instance can alert
     * only its own watchers.
     *
     * @param {CustomEvent} event
     */
    callWatchersHandler(event) {
        // Execute any registered component watchers.
        this.target.dispatchEvent(new CustomEvent(event.detail.action, {
            bubbles: false,
            detail: event.detail,
        }));
    }
    /**
     * Set the initial state.
     *
     * @param {object} stateData the initial state data.
     */
    setInitialState(stateData) {
        this.pendingState.resolve();
        this.stateManager.setInitialState(stateData);
    }
    /**
     * Add individual functions to the mutations.
     *
     * Note new mutations will be added to the existing ones. To replace the full mutation
     * object with a new one, use setMutations method.
     *
     * @method addMutations
     * @param {Object} newFunctions an object with new mutation functions.
     */
    addMutations(newFunctions) {
        // Mutations can provide an init method to do some setup in the statemanager.
        if (newFunctions.init !== undefined) {
            newFunctions.init(this.stateManager);
        }
        // Save all mutations.
        for (const [mutation, mutationFunction] of Object.entries(newFunctions)) {
            this.mutations[mutation] = mutationFunction.bind(newFunctions);
        }
    }
    /**
     * Replace the current mutations with a new object.
     *
     * This method is designed to override the full mutations class, for example by extending
     * the original one. To add some individual mutations, use addMutations instead.
     *
     * @param {object} manager the new mutations intance
     */
    setMutations(manager) {
        this.mutations = manager;
        // Mutations can provide an init method to do some setup in the statemanager.
        if (manager.init !== undefined) {
            manager.init(this.stateManager);
        }
    }
    /**
     * Return the current state.
     *
     * @return {object}
     */
    get state() {
        return this.stateManager.state;
    }
    /**
     * Get state data.
     *
     * Components access the state frequently. This convenience method is a shortcut to
     * this.reactive.state.stateManager.get() method.
     *
     * @param {String} name the state object name
     * @param {*} id an optional object id for state maps.
     * @return {Object|undefined} the state object found
     */
    get(name, id) {
        return this.stateManager.get(name, id);
    }
    /**
     * Return the initial state promise.
     *
     * Typically, components do not require to use this promise because registerComponent
     * will trigger their stateReady method automatically. But it could be useful for complex
     * components that require to combine state, template and string loadings.
     *
     * @method getState
     * @return {Promise}
     */
    getInitialStatePromise() {
        return this.stateManager.getInitialPromise();
    }
    /**
     * Register a new component.
     *
     * Component can provide some optional functions to the reactive module:
     * - getWatchers: returns an array of watchers
     * - stateReady: a method to call when the initial state is loaded
     *
     * It can also provide some optional attributes:
     * - name: the component name (default value: "Unkown component") to customize debug messages.
     *
     * The method will also use dispatchRegistrationSuccess and dispatchRegistrationFail. Those
     * are BaseComponent methods to inform parent components of the registration status.
     * Components should not override those methods.
     *
     * @method registerComponent
     * @param {object} component the new component
     * @param {string} [component.name] the component name to display in warnings and errors.
     * @param {Function} [component.dispatchRegistrationSuccess] method to notify registration success
     * @param {Function} [component.dispatchRegistrationFail] method to notify registration fail
     * @param {Function} [component.getWatchers] getter of the component watchers
     * @param {Function} [component.stateReady] method to call when the state is ready
     * @return {object} the registered component
     */
    registerComponent(component) {
        // Component name is an optional attribute to customize debug messages.
        const componentName = component.name ?? 'Unkown component';
        // Components can provide special methods to communicate registration to parent components.
        let dispatchSuccess = () => {
            return;
        };
        let dispatchFail = dispatchSuccess;
        if (component.dispatchRegistrationSuccess !== undefined) {
            dispatchSuccess = component.dispatchRegistrationSuccess.bind(component);
        }
        if (component.dispatchRegistrationFail !== undefined) {
            dispatchFail = component.dispatchRegistrationFail.bind(component);
        }
        // Components can be registered only one time.
        if (this.components.has(component)) {
            dispatchSuccess();
            return component;
        }
        // Components are fully registered only when the state ready promise is resolved.
        const pendingPromise = new Pending(`core/reactive:registerComponent${pendingCount++}`);
        // Keep track of the event listeners.
        let listeners = [];
        // Register watchers.
        let handlers = [];
        if (component.getWatchers !== undefined) {
            handlers = component.getWatchers();
        }
        handlers.forEach(({watch, handler}) => {
            if (watch === undefined) {
                dispatchFail();
                throw new Error(`Missing watch attribute in ${componentName} watcher`);
            }
            if (handler === undefined) {
                dispatchFail();
                throw new Error(`Missing handler for watcher ${watch} in ${componentName}`);
            }
            const listener = (event) => {
                // Prevent any watcher from losing the page focus.
                const currentFocus = document.activeElement;
                // Execute watcher.
                handler.apply(component, [event.detail]);
                // Restore focus in case it is lost.
                if (document.activeElement === document.body && document.body.contains(currentFocus)) {
                    currentFocus.focus();
                }
            };
            // Save the listener information in case the component must be unregistered later.
            listeners.push({target: this.target, watch, listener});
            // The state manager triggers a general "state changed" event at a document level. However,
            // for the internal watchers, each component can listen to specific state changed custom events
            // in the target element. This way we can use the native event loop without colliding with other
            // reactive instances.
            this.target.addEventListener(watch, listener);
        });
        // Register state ready function. There's the possibility a component is registered after the initial state
        // is loaded. For those cases we have a state promise to handle this specific state change.
        if (component.stateReady !== undefined) {
            this.getInitialStatePromise()
                .then(state => {
                    component.stateReady(state);
                    pendingPromise.resolve();
                    return true;
                })
                .catch(reason => {
                    pendingPromise.resolve();
                    log.error(`Initial state in ${componentName} rejected due to: ${reason}`);
                    log.error(reason);
                });
        }
        // Save unregister data.
        this.watchers.set(component, listeners);
        this.components.add(component);
        // Dispatch an event to communicate the registration to the debug module.
        this.target.dispatchEvent(new CustomEvent('registerComponent:success', {
            bubbles: false,
            detail: {component},
        }));
        dispatchSuccess();
        return component;
    }
    /**
     * Unregister a component and its watchers.
     *
     * @param {object} component the object instance to unregister
     * @returns {object} the deleted component
     */
    unregisterComponent(component) {
        if (!this.components.has(component)) {
            return component;
        }
        this.components.delete(component);
        // Remove event listeners.
        const listeners = this.watchers.get(component);
        if (listeners === undefined) {
            return component;
        }
        listeners.forEach(({target, watch, listener}) => {
            target.removeEventListener(watch, listener);
        });
        this.watchers.delete(component);
        return component;
    }
    /**
     * Dispatch a change in the state.
     *
     * This method is the only way for components to alter the state. Watchers will receive a
     * read only state to prevent illegal changes. If some user action require a state change, the
     * component should dispatch a mutation to trigger all the necessary logic to alter the state.
     *
     * @method dispatch
     * @param {string} actionName the action name (usually the mutation name)
     * @param {mixed} params any number of params the mutation needs.
     */
    async dispatch(actionName, ...params) {
        if (typeof actionName !== 'string') {
            throw new Error(`Dispatch action name must be a string`);
        }
        // JS does not have private methods yet. However, we prevent any component from calling
        // a method starting with "_" because the most accepted convention for private methods.
        if (actionName.charAt(0) === '_') {
            throw new Error(`Illegal Private ${actionName} mutation method dispatch`);
        }
        if (this.mutations[actionName] === undefined) {
            throw new Error(`Unkown ${actionName} mutation`);
        }
        const pendingPromise = new Pending(`core/reactive:${actionName}${pendingCount++}`);
        const mutationFunction = this.mutations[actionName];
        try {
            await mutationFunction.apply(this.mutations, [this.stateManager, ...params]);
            pendingPromise.resolve();
        } catch (error) {
            // Ensure the state is locked.
            this.stateManager.setReadOnly(true);
            pendingPromise.resolve();
            throw error;
        }
    }
}