// 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;
}
}
}