Proyectos de Subversion Moodle

// 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/>.

/**

 * Reactive module debug tools.

 *

 * @module     core/local/reactive/debug

 * @copyright  2021 Ferran Recio <ferran@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

import Reactive from 'core/local/reactive/reactive';

import log from 'core/log';

// The list of reactives instances.

const reactiveInstances = {};

// The reactive debugging objects.

const reactiveDebuggers = {};

/**

 * Reactive module debug tools.

 *

 * If debug is enabled, this reactive module will spy all the reactive instances and keep a record

 * of the changes and components they have.

 *

 * It is important to note that the Debug class is also a Reactive module. The debug instance keeps

 * the reactive instances data as its own state. This way it is possible to implement development tools

 * that whatches this data.

 *

 * @class      core/reactive/local/reactive/debug/Debug

 * @copyright  2021 Ferran Recio <ferran@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class Debug extends Reactive {

    /**

     * Set the initial state.

     *

     * @param {object} stateData the initial state data.

     */

    setInitialState(stateData) {

        super.setInitialState(stateData);

        log.debug(`Debug module "M.reactive" loaded.`);

    }

    /**

     * List the currents page reactives instances.

     */

    get list() {

        return JSON.parse(JSON.stringify(this.state.reactives));

    }

    /**

     * Register a new Reactive instance.

     *

     * This method is called every time a "new Reactive" is executed.

     *

     * @param {Reactive} instance the reactive instance

     */

    registerNewInstance(instance) {

        // Generate a valid variable name for that instance.

        let name = instance.name ?? `instance${this.state.reactives.length}`;

        name = name.replace(/\W/g, '');

        log.debug(`Registering new reactive instance "M.reactive.${name}"`);

        reactiveInstances[name] = instance;

        reactiveDebuggers[name] = new DebugInstance(reactiveInstances[name]);

        // Register also in the state.

        this.dispatch('putInstance', name, instance);

        // Add debug watchers to instance.

        const refreshMethod = () => {

            this.dispatch('putInstance', name, instance);

        };

        instance.target.addEventListener('readmode:on', refreshMethod);

        instance.target.addEventListener('readmode:off', refreshMethod);

        instance.target.addEventListener('registerComponent:success', refreshMethod);

        instance.target.addEventListener('transaction:end', refreshMethod);

        // We store the last transaction into the state.

        const storeTransaction = ({detail}) => {

            const changes = detail?.changes;

            this.dispatch('lastTransaction', name, changes);

        };

        instance.target.addEventListener('transaction:end', storeTransaction);

    }

    /**

     * Returns a debugging object for a specific Reactive instance.

     *

     * A debugging object is a class that wraps a Reactive instance to quick access some of the

     * reactive methods using the browser JS console.

     *

     * @param {string} name the Reactive instance name

     * @returns {DebugInstance} a debug object wrapping the Reactive instance

     */

    debug(name) {

        return reactiveDebuggers[name];

    }

}

/**

 * The debug state mutations class.

 *

 * @class core/reactive/local/reactive/debug/Mutations

 */

class Mutations {

    /**

     * Insert or update a new instance into the debug state.

     *

     * @param {StateManager} stateManager the debug state manager

     * @param {string} name the instance name

     * @param {Reactive} instance the reactive instance

     */

    putInstance(stateManager, name, instance) {

        const state = stateManager.state;

        stateManager.setReadOnly(false);

        if (state.reactives.has(name)) {

            state.reactives.get(name).countcomponents = instance.components.length;

            state.reactives.get(name).readOnly = instance.stateManager.readonly;

            state.reactives.get(name).modified = new Date().getTime();

        } else {

            state.reactives.add({

                id: name,

                countcomponents: instance.components.length,

                readOnly: instance.stateManager.readonly,

                lastChanges: [],

                modified: new Date().getTime(),

            });

        }

        stateManager.setReadOnly(true);

    }

    /**

     * Update the lastChanges attribute with a list of changes

     *

     * @param {StateManager} stateManager the debug reactive state

     * @param {string} name the instance name

     * @param {array} changes the list of changes

     */

    lastTransaction(stateManager, name, changes) {

        if (!changes || changes.length === 0) {

            return;

        }

        const state = stateManager.state;

        const lastChanges = ['transaction:start'];

        changes.forEach(change => {

            lastChanges.push(change.eventName);

        });

        lastChanges.push('transaction:end');

        stateManager.setReadOnly(false);

        // Dirty hack to force the lastChanges:updated event to be dispatched.

        state.reactives.get(name).lastChanges = [];

        // Assign the actual value.

        state.reactives.get(name).lastChanges = lastChanges;

        stateManager.setReadOnly(true);

    }

}

/**

 * Class used to debug a specific instance and manipulate the state from the JS console.

 *

 * @class      core/reactive/local/reactive/debug/DebugInstance

 * @copyright  2021 Ferran Recio <ferran@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class DebugInstance {

    /**

     * Constructor.

     *

     * @param {Reactive} instance the reactive instance

     */

    constructor(instance) {

        this.instance = instance;

        // Add some debug data directly into the instance. This way we avoid having attributes

        // that will confuse the console aoutocomplete.

        if (instance._reactiveDebugData === undefined) {

            instance._reactiveDebugData = {

                highlighted: false,

            };

        }

    }

    /**

     * Set the read only mode.

     *

     * Quick access to the instance setReadOnly method.

     *

     * @param {bool} value the new read only value

     */

    set readOnly(value) {

        this.instance.stateManager.setReadOnly(value);

    }

    /**

     * Get the read only value

     *

     * @returns {bool}

     */

    get readOnly() {

        return this.instance.stateManager.readonly;

    }

    /**

     * Return the current state object.

     *

     * @returns {object}

     */

    get state() {

        return this.instance.state;

    }

    /**

     * Tooggle the reactive HTML element highlight registered in this reactive instance.

     *

     * @param {bool} value the highlight value

     */

    set highlight(value) {

        this.instance._reactiveDebugData.highlighted = value;

        this.instance.components.forEach(({element}) => {

            const border = (value) ? `thick solid #0000FF` : '';

            element.style.border = border;

        });

    }

    /**

     * Get the current highligh value.

     *

     * @returns {bool}

     */

    get highlight() {

        return this.instance._reactiveDebugData.highlighted;

    }

    /**

     * List all the components registered in this instance.

     *

     * @returns {array}

     */

    get components() {

        return [...this.instance.components];

    }

    /**

     * List all the state changes evenet pending to dispatch.

     *

     * @returns {array}

     */

    get changes() {

        const result = [];

        this.instance.stateManager.eventsToPublish.forEach(

            (element) => {

                result.push(element.eventName);

            }

        );

        return result;

    }

    /**

     * Dispatch a change in the state.

     *

     * Usually reactive modules throw an error directly to the components when something

     * goes wrong. However, course editor can directly display a notification.

     *

     * @method dispatch

     * @param {*} args

     */

    async dispatch(...args) {

        this.instance.dispatch(...args);

    }

    /**

     * Return all the HTML elements registered in the instance components.

     *

     * @returns {array}

     */

    get elements() {

        const result = [];

        this.instance.components.forEach(({element}) => {

            result.push(element);

        });

        return result;

    }

    /**

     * Return a plain copy of the state data.

     *

     * @returns {object}

     */

    get stateData() {

        return JSON.parse(JSON.stringify(this.state));

    }

    /**

     * Process an update state array.

     *

     * @param {array} updates an array of update state messages

     */

    processUpdates(updates) {

        this.instance.stateManager.processUpdates(updates);

    }

}

const stateChangedEventName = 'core_reactive_debug:stateChanged';

/**

 * Internal state changed event.

 *

 * @method dispatchStateChangedEvent

 * @param {object} detail the full state

 * @param {object} target the custom event target (document if none provided)

 */

function dispatchStateChangedEvent(detail, target) {

    if (target === undefined) {

        target = document;

    }

    target.dispatchEvent(

        new CustomEvent(

            stateChangedEventName,

            {

                bubbles: true,

                detail: detail,

            }

        )

    );

}

/**

 * The main init method to initialize the reactive debug.

 * @returns {object}

 */

export const initDebug = () => {

    const debug = new Debug({

        name: 'CoreReactiveDebug',

        eventName: stateChangedEventName,

        eventDispatch: dispatchStateChangedEvent,

        mutations: new Mutations(),

        state: {

            reactives: [],

        },

    });

    // The reactiveDebuggers will be used as a way of access the debug instances but also to register every new

    // instance. To ensure this will update the reactive debug state we add the registerNewInstance method to it.

    reactiveDebuggers.registerNewInstance = debug.registerNewInstance.bind(debug);

    return {

        debug,

        debuggers: reactiveDebuggers,

    };

};