@scratch/scratch-vm 11.0.0-beta.1

package/src/util/task-queue.js

@@ -0,0 +1,203 @@
+const Timer = require('../util/timer');
+
+/**
+ * This class uses the token bucket algorithm to control a queue of tasks.
+ */
+class TaskQueue {
+    /**
+     * Creates an instance of TaskQueue.
+     * To allow bursts, set `maxTokens` to several times the average task cost.
+     * To prevent bursts, set `maxTokens` to the cost of the largest tasks.
+     * Note that tasks with a cost greater than `maxTokens` will be rejected.
+     *
+     * @param {number} maxTokens - the maximum number of tokens in the bucket (burst size).
+     * @param {number} refillRate - the number of tokens to be added per second (sustain rate).
+     * @param {object} options - optional settings for the new task queue instance.
+     * @property {number} startingTokens - the number of tokens the bucket starts with (default: `maxTokens`).
+     * @property {number} maxTotalCost - reject a task if total queue cost would pass this limit (default: no limit).
+     * @memberof TaskQueue
+     */
+    constructor (maxTokens, refillRate, options = {}) {
+        this._maxTokens = maxTokens;
+        this._refillRate = refillRate;
+        this._pendingTaskRecords = [];
+        this._tokenCount = Object.prototype.hasOwnProperty.call(options, 'startingTokens') ?
+            options.startingTokens : maxTokens;
+        this._maxTotalCost = Object.prototype.hasOwnProperty.call(options, 'maxTotalCost') ?
+            options.maxTotalCost : Infinity;
+        this._timer = new Timer();
+        this._timer.start();
+        this._timeout = null;
+        this._lastUpdateTime = this._timer.timeElapsed();
+
+        this._runTasks = this._runTasks.bind(this);
+    }
+
+    /**
+     * Get the number of queued tasks which have not yet started.
+     *
+     * @readonly
+     * @memberof TaskQueue
+     */
+    get length () {
+        return this._pendingTaskRecords.length;
+    }
+
+    /**
+     * Wait until the token bucket is full enough, then run the provided task.
+     *
+     * @param {Function} task - the task to run.
+     * @param {number} [cost=1] - the number of tokens this task consumes from the bucket.
+     * @returns {Promise} - a promise for the task's return value.
+     * @memberof TaskQueue
+     */
+    do (task, cost = 1) {
+        if (this._maxTotalCost < Infinity) {
+            const currentTotalCost = this._pendingTaskRecords.reduce((t, r) => t + r.cost, 0);
+            if (currentTotalCost + cost > this._maxTotalCost) {
+                return Promise.reject(new Error('Maximum total cost exceeded'));
+            }
+        }
+        const newRecord = {
+            cost
+        };
+        newRecord.promise = new Promise((resolve, reject) => {
+            newRecord.cancel = () => {
+                reject(new Error('Task canceled'));
+            };
+
+            // The caller, `_runTasks()`, is responsible for cost-checking and spending tokens.
+            newRecord.wrappedTask = () => {
+                try {
+                    resolve(task());
+                } catch (e) {
+                    reject(e);
+                }
+            };
+        });
+        this._pendingTaskRecords.push(newRecord);
+
+        // If the queue has been idle we need to prime the pump
+        if (this._pendingTaskRecords.length === 1) {
+            this._runTasks();
+        }
+
+        return newRecord.promise;
+    }
+
+    /**
+     * Cancel one pending task, rejecting its promise.
+     *
+     * @param {Promise} taskPromise - the promise returned by `do()`.
+     * @returns {boolean} - true if the task was found, or false otherwise.
+     * @memberof TaskQueue
+     */
+    cancel (taskPromise) {
+        const taskIndex = this._pendingTaskRecords.findIndex(r => r.promise === taskPromise);
+        if (taskIndex !== -1) {
+            const [taskRecord] = this._pendingTaskRecords.splice(taskIndex, 1);
+            taskRecord.cancel();
+            if (taskIndex === 0 && this._pendingTaskRecords.length > 0) {
+                this._runTasks();
+            }
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Cancel all pending tasks, rejecting all their promises.
+     *
+     * @memberof TaskQueue
+     */
+    cancelAll () {
+        if (this._timeout !== null) {
+            this._timer.clearTimeout(this._timeout);
+            this._timeout = null;
+        }
+        const oldTasks = this._pendingTaskRecords;
+        this._pendingTaskRecords = [];
+        oldTasks.forEach(r => r.cancel());
+    }
+
+    /**
+     * Shorthand for calling _refill() then _spend(cost).
+     *
+     * @see {@link TaskQueue#_refill}
+     * @see {@link TaskQueue#_spend}
+     * @param {number} cost - the number of tokens to try to spend.
+     * @returns {boolean} true if we had enough tokens; false otherwise.
+     * @memberof TaskQueue
+     */
+    _refillAndSpend (cost) {
+        this._refill();
+        return this._spend(cost);
+    }
+
+    /**
+     * Refill the token bucket based on the amount of time since the last refill.
+     *
+     * @memberof TaskQueue
+     */
+    _refill () {
+        const now = this._timer.timeElapsed();
+        const timeSinceRefill = now - this._lastUpdateTime;
+        if (timeSinceRefill <= 0) return;
+
+        this._lastUpdateTime = now;
+        this._tokenCount += timeSinceRefill * this._refillRate / 1000;
+        this._tokenCount = Math.min(this._tokenCount, this._maxTokens);
+    }
+
+    /**
+     * If we can "afford" the given cost, subtract that many tokens and return true.
+     * Otherwise, return false.
+     *
+     * @param {number} cost - the number of tokens to try to spend.
+     * @returns {boolean} true if we had enough tokens; false otherwise.
+     * @memberof TaskQueue
+     */
+    _spend (cost) {
+        if (cost <= this._tokenCount) {
+            this._tokenCount -= cost;
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Loop until the task queue is empty, running each task and spending tokens to do so.
+     * Any time the bucket can't afford the next task, delay asynchronously until it can.
+     *
+     * @memberof TaskQueue
+     */
+    _runTasks () {
+        if (this._timeout) {
+            this._timer.clearTimeout(this._timeout);
+            this._timeout = null;
+        }
+        for (;;) {
+            const nextRecord = this._pendingTaskRecords.shift();
+            if (!nextRecord) {
+                // We ran out of work. Go idle until someone adds another task to the queue.
+                return;
+            }
+            if (nextRecord.cost > this._maxTokens) {
+                throw new Error(`Task cost ${nextRecord.cost} is greater than bucket limit ${this._maxTokens}`);
+            }
+            // Refill before each task in case the time it took for the last task to run was enough to afford the next.
+            if (this._refillAndSpend(nextRecord.cost)) {
+                nextRecord.wrappedTask();
+            } else {
+                // We can't currently afford this task. Put it back and wait until we can and try again.
+                this._pendingTaskRecords.unshift(nextRecord);
+                const tokensNeeded = Math.max(nextRecord.cost - this._tokenCount, 0);
+                const estimatedWait = Math.ceil(1000 * tokensNeeded / this._refillRate);
+                this._timeout = this._timer.setTimeout(this._runTasks, estimatedWait);
+                return;
+            }
+        }
+    }
+}
+
+module.exports = TaskQueue;

package/src/util/timer.js

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview
+ * A utility for accurately measuring time.
+ * To use:
+ * ---
+ * var timer = new Timer();
+ * timer.start();
+ * ... pass some time ...
+ * var timeDifference = timer.timeElapsed();
+ * ---
+ * Or, you can use the `time` function
+ * to do some measurement yourself.
+ */
+
+class Timer {
+    constructor (nowObj = Timer.nowObj) {
+        /**
+         * Used to store the start time of a timer action.
+         * Updated when calling `timer.start`.
+         */
+        this.startTime = 0;
+
+        /**
+         * Used to pass custom logic for determining the value for "now",
+         * which is sometimes useful for compatibility with Scratch 2
+         */
+        this.nowObj = nowObj;
+    }
+
+    /**
+     * Disable use of self.performance for now as it results in lower performance
+     * However, instancing it like below (caching the self.performance to a local variable) negates most of the issues.
+     * @type {boolean}
+     */
+    static get USE_PERFORMANCE () {
+        return false;
+    }
+
+    /**
+     * Legacy object to allow for us to call now to get the old style date time (for backwards compatibility)
+     * @deprecated This is only called via the nowObj.now() if no other means is possible...
+     */
+    static get legacyDateCode () {
+        return {
+            now: function () {
+                return new Date().getTime();
+            }
+        };
+    }
+
+    /**
+     * Use this object to route all time functions through single access points.
+     */
+    static get nowObj () {
+        if (Timer.USE_PERFORMANCE && typeof self !== 'undefined' && self.performance && 'now' in self.performance) {
+            return self.performance;
+        } else if (Date.now) {
+            return Date;
+        }
+        return Timer.legacyDateCode;
+    }
+
+    /**
+     * Return the currently known absolute time, in ms precision.
+     * @returns {number} ms elapsed since 1 January 1970 00:00:00 UTC.
+     */
+    time () {
+        return this.nowObj.now();
+    }
+
+    /**
+     * Start a timer for measuring elapsed time,
+     * at the most accurate precision possible.
+     */
+    start () {
+        this.startTime = this.nowObj.now();
+    }
+
+    timeElapsed () {
+        return this.nowObj.now() - this.startTime;
+    }
+
+    /**
+     * Call a handler function after a specified amount of time has elapsed.
+     * @param {function} handler - function to call after the timeout
+     * @param {number} timeout - number of milliseconds to delay before calling the handler
+     * @returns {number} - the ID of the new timeout
+     */
+    setTimeout (handler, timeout) {
+        return global.setTimeout(handler, timeout);
+    }
+
+    /**
+     * Clear a timeout from the pending timeout pool.
+     * @param {number} timeoutId - the ID returned by `setTimeout()`
+     * @memberof Timer
+     */
+    clearTimeout (timeoutId) {
+        global.clearTimeout(timeoutId);
+    }
+}
+
+module.exports = Timer;

package/src/util/uid.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview UID generator, from Blockly.
+ */
+
+/**
+ * Legal characters for the unique ID.
+ * Should be all on a US keyboard.  No XML special characters or control codes.
+ * Removed $ due to issue 251.
+ * @private
+ */
+const soup_ = '!#%()*+,-./:;=?@[]^_`{|}~' +
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Generate a unique ID, from Blockly.  This should be globally unique.
+ * 87 characters ^ 20 length > 128 bits (better than a UUID).
+ * @return {string} A globally unique ID string.
+ */
+const uid = function () {
+    const length = 20;
+    const soupLength = soup_.length;
+    const id = [];
+    for (let i = 0; i < length; i++) {
+        id[i] = soup_.charAt(Math.random() * soupLength);
+    }
+    return id.join('');
+};
+
+module.exports = uid;

package/src/util/variable-util.js

@@ -0,0 +1,48 @@
+class VariableUtil {
+    static _mergeVarRefObjects (accum, obj2) {
+        for (const id in obj2) {
+            if (accum[id]) {
+                accum[id] = accum[id].concat(obj2[id]);
+            } else {
+                accum[id] = obj2[id];
+            }
+        }
+        return accum;
+    }
+
+    /**
+     * Get all variable/list references in the given list of targets
+     * in the project.
+     * @param {Array.<Target>} targets The list of targets to get the variable
+     * and list references from.
+     * @param {boolean} shouldIncludeBroadcast Whether to include broadcast message fields.
+     * @return {object} An object with variable ids as the keys and a list of block fields referencing
+     * the variable.
+     */
+    static getAllVarRefsForTargets (targets, shouldIncludeBroadcast) {
+        return targets
+            .map(t => t.blocks.getAllVariableAndListReferences(null, shouldIncludeBroadcast))
+            .reduce(VariableUtil._mergeVarRefObjects, {});
+    }
+
+    /**
+     * Give all variable references provided a new id and possibly new name.
+     * @param {Array<object>} referencesToUpdate Context of the change, the object containing variable
+     * references to update.
+     * @param {string} newId ID of the variable that the old references should be replaced with
+     * @param {?string} optNewName New variable name to merge with. The old
+     * variable name in the references being updated should be replaced with this new name.
+     * If this parameter is not provided or is '', no name change occurs.
+     */
+    static updateVariableIdentifiers (referencesToUpdate, newId, optNewName) {
+        referencesToUpdate.map(ref => {
+            ref.referencingField.id = newId;
+            if (optNewName) {
+                ref.referencingField.value = optNewName;
+            }
+            return ref;
+        });
+    }
+}
+
+module.exports = VariableUtil;

package/src/util/xml-escape.js

@@ -0,0 +1,33 @@
+const log = require('./log');
+
+/**
+ * Escape a string to be safe to use in XML content.
+ * CC-BY-SA: hgoebl
+ * https://stackoverflow.com/questions/7918868/
+ * how-to-escape-xml-entities-in-javascript
+ * @param {!string | !Array.<string>} unsafe Unsafe string.
+ * @return {string} XML-escaped string, for use within an XML tag.
+ */
+const xmlEscape = function (unsafe) {
+    if (typeof unsafe !== 'string') {
+        if (Array.isArray(unsafe)) {
+            // This happens when we have hacked blocks from 2.0
+            // See #1030
+            unsafe = String(unsafe);
+        } else {
+            log.error('Unexpected input recieved in replaceUnsafeChars');
+            return unsafe;
+        }
+    }
+    return unsafe.replace(/[<>&'"]/g, c => {
+        switch (c) {
+        case '<': return '&lt;';
+        case '>': return '&gt;';
+        case '&': return '&amp;';
+        case '\'': return '&apos;';
+        case '"': return '&quot;';
+        }
+    });
+};
+
+module.exports = xmlEscape;