@scratch/scratch-vm 11.0.0-beta.1

package/src/util/fetch-with-timeout.js

@@ -0,0 +1,53 @@
+/**
+ * @callback FetchFunction
+ * @param {RequestInfo|URL} input
+ * @param {RequestInit|undefined} [init]
+ * @returns {Promise<Response>}
+ */
+
+/**
+ * @type {FetchFunction}
+ */
+let myFetch = global.fetch;
+
+/**
+ * Tell `fetchWithTimeout` to use a specific `fetch` function.
+ * By default, `fetchWithTimeout` will use the global `fetch` function.
+ * If there is no global `fetch`, then `fetchWithTimeout` will fail unless provided with an alternative.
+ * @param {FetchFunction} newFetch The new `fetch` function to use within fetchWithTimeout.
+ */
+const setFetch = newFetch => {
+    myFetch = newFetch;
+};
+
+/**
+ * Fetch a remote resource like `fetch` does, but with a time limit.
+ * @param {Request|string} resource Remote resource to fetch.
+ * @param {?object} init An options object containing any custom settings that you want to apply to the request.
+ * @param {number} timeout The amount of time before the request is canceled, in milliseconds
+ * @returns {Promise<Response>} The response from the server.
+ */
+const fetchWithTimeout = (resource, init, timeout) => {
+    let timeoutID = null;
+    // Not supported in Safari <11
+    const controller = window.AbortController ? new window.AbortController() : null;
+    const signal = controller ? controller.signal : null;
+    // The fetch call races a timer.
+    return Promise.race([
+        myFetch(resource, Object.assign({signal}, init)).then(response => {
+            clearTimeout(timeoutID);
+            return response;
+        }),
+        new Promise((resolve, reject) => {
+            timeoutID = setTimeout(() => {
+                if (controller) controller.abort();
+                reject(new Error(`Fetch timed out after ${timeout} ms`));
+            }, timeout);
+        })
+    ]);
+};
+
+module.exports = {
+    fetchWithTimeout,
+    setFetch
+};

package/src/util/get-monitor-id.js

@@ -0,0 +1,33 @@
+/**
+ * Returns a string representing a unique id for a monitored block
+ * where a single reporter block can have more than one monitor
+ * (and therefore more than one monitor block) associated
+ * with it (e.g. when reporter blocks have inputs).
+ * @param {string} baseId The base id to use for the different monitor blocks
+ * @param {object} fields The monitor block's fields object.
+ */
+// TODO this function should eventually be the single place where all monitor
+// IDs are obtained given an opcode for the reporter block and the list of
+// selected parameters.
+const getMonitorIdForBlockWithArgs = function (id, fields) {
+    let fieldString = '';
+    for (const fieldKey in fields) {
+        let fieldValue = fields[fieldKey].value;
+        if (fieldKey === 'CURRENTMENU') {
+            // The 'sensing_current' block has field values in all caps.
+            // However, when importing from scratch 2.0, these
+            // could have gotten imported as lower case field values.
+            // Normalize the field value here so that we don't ever
+            // end up with a different monitor ID representing the same
+            // block configuration
+            // Note: we are not doing this for every block field that comes into
+            // this function so as not to make the faulty assumption that block
+            // field values coming in would be unique after being made lower case
+            fieldValue = fieldValue.toLowerCase();
+        }
+        fieldString += `_${fieldValue}`;
+    }
+    return `${id}${fieldString}`;
+};
+
+module.exports = getMonitorIdForBlockWithArgs;

package/src/util/jsonrpc.js

@@ -0,0 +1,114 @@
+class JSONRPC {
+    constructor () {
+        this._requestID = 0;
+        this._openRequests = {};
+    }
+
+    /**
+     * Make an RPC request and retrieve the result.
+     * @param {string} method - the remote method to call.
+     * @param {object} params - the parameters to pass to the remote method.
+     * @returns {Promise} - a promise for the result of the call.
+     */
+    sendRemoteRequest (method, params) {
+        const requestID = this._requestID++;
+
+        const promise = new Promise((resolve, reject) => {
+            this._openRequests[requestID] = {resolve, reject};
+        });
+
+        this._sendRequest(method, params, requestID);
+
+        return promise;
+    }
+
+    /**
+     * Make an RPC notification with no expectation of a result or callback.
+     * @param {string} method - the remote method to call.
+     * @param {object} params - the parameters to pass to the remote method.
+     */
+    sendRemoteNotification (method, params) {
+        this._sendRequest(method, params);
+    }
+
+    /**
+     * Handle an RPC request from remote, should return a result or Promise for result, if appropriate.
+     * @param {string} method - the method requested by the remote caller.
+     * @param {object} params - the parameters sent with the remote caller's request.
+     */
+    didReceiveCall (/* method , params */) {
+        throw new Error('Must override didReceiveCall');
+    }
+
+    _sendMessage (/* jsonMessageObject */) {
+        throw new Error('Must override _sendMessage');
+    }
+
+    _sendRequest (method, params, id) {
+        const request = {
+            jsonrpc: '2.0',
+            method,
+            params
+        };
+
+        if (id !== null) {
+            request.id = id;
+        }
+
+        this._sendMessage(request);
+    }
+
+    _handleMessage (json) {
+        if (json.jsonrpc !== '2.0') {
+            throw new Error(`Bad or missing JSON-RPC version in message: ${json}`);
+        }
+        if (Object.prototype.hasOwnProperty.call(json, 'method')) {
+            this._handleRequest(json);
+        } else {
+            this._handleResponse(json);
+        }
+    }
+
+    _sendResponse (id, result, error) {
+        const response = {
+            jsonrpc: '2.0',
+            id
+        };
+        if (error) {
+            response.error = error;
+        } else {
+            response.result = result || null;
+        }
+        this._sendMessage(response);
+    }
+
+    _handleResponse (json) {
+        const {result, error, id} = json;
+        const openRequest = this._openRequests[id];
+        delete this._openRequests[id];
+        if (openRequest) {
+            if (error) {
+                openRequest.reject(error);
+            } else {
+                openRequest.resolve(result);
+            }
+        }
+    }
+
+    _handleRequest (json) {
+        const {method, params, id} = json;
+        const rawResult = this.didReceiveCall(method, params);
+        if (id !== null && typeof id !== 'undefined') {
+            Promise.resolve(rawResult).then(
+                result => {
+                    this._sendResponse(id, result);
+                },
+                error => {
+                    this._sendResponse(id, null, error);
+                }
+            );
+        }
+    }
+}
+
+module.exports = JSONRPC;

package/src/util/log.js

@@ -0,0 +1,4 @@
+const minilog = require('minilog');
+minilog.enable();
+
+module.exports = minilog('vm');

package/src/util/math-util.js

@@ -0,0 +1,122 @@
+class MathUtil {
+    /**
+     * Convert a value from degrees to radians.
+     * @param {!number} deg Value in degrees.
+     * @return {!number} Equivalent value in radians.
+     */
+    static degToRad (deg) {
+        return deg * Math.PI / 180;
+    }
+
+    /**
+     * Convert a value from radians to degrees.
+     * @param {!number} rad Value in radians.
+     * @return {!number} Equivalent value in degrees.
+     */
+    static radToDeg (rad) {
+        return rad * 180 / Math.PI;
+    }
+
+    /**
+     * Clamp a number between two limits.
+     * If n < min, return min. If n > max, return max. Else, return n.
+     * @param {!number} n Number to clamp.
+     * @param {!number} min Minimum limit.
+     * @param {!number} max Maximum limit.
+     * @return {!number} Value of n clamped to min and max.
+     */
+    static clamp (n, min, max) {
+        return Math.min(Math.max(n, min), max);
+    }
+
+    /**
+     * Keep a number between two limits, wrapping "extra" into the range.
+     * e.g., wrapClamp(7, 1, 5) == 2
+     * wrapClamp(0, 1, 5) == 5
+     * wrapClamp(-11, -10, 6) == 6, etc.
+     * @param {!number} n Number to wrap.
+     * @param {!number} min Minimum limit.
+     * @param {!number} max Maximum limit.
+     * @return {!number} Value of n wrapped between min and max.
+     */
+    static wrapClamp (n, min, max) {
+        const range = (max - min) + 1;
+        return n - (Math.floor((n - min) / range) * range);
+    }
+
+
+    /**
+     * Convert a value from tan function in degrees.
+     * @param {!number} angle in degrees
+     * @return {!number} Correct tan value
+     */
+    static tan (angle) {
+        angle = angle % 360;
+        switch (angle) {
+        case -270:
+        case 90:
+            return Infinity;
+        case -90:
+        case 270:
+            return -Infinity;
+        default:
+            return parseFloat(Math.tan((Math.PI * angle) / 180).toFixed(10));
+        }
+    }
+
+    /**
+     * Given an array of unique numbers,
+     * returns a reduced array such that each element of the reduced array
+     * represents the position of that element in a sorted version of the
+     * original array.
+     * E.g. [5, 19. 13, 1] => [1, 3, 2, 0]
+     * @param {Array<number>} elts The elements to sort and reduce
+     * @return {Array<number>} The array of reduced orderings
+     */
+    static reducedSortOrdering (elts) {
+        const sorted = elts.slice(0).sort((a, b) => a - b);
+        return elts.map(e => sorted.indexOf(e));
+    }
+
+    /**
+     * Return a random number given an inclusive range and a number in that
+     * range that should be excluded.
+     *
+     * For instance, (1, 5, 3) will only pick 1, 2, 4, or 5 (with equal
+     * probability)
+     *
+     * @param {number} lower - The lower bound (inlcusive)
+     * @param {number} upper - The upper bound (inclusive), such that lower <= upper
+     * @param {number} excluded - The number to exclude (MUST be in the range)
+     * @return {number} A random integer in the range [lower, upper] that is not "excluded"
+     */
+    static inclusiveRandIntWithout (lower, upper, excluded) {
+        // Note that subtraction is the number of items in the
+        // inclusive range [lower, upper] minus 1 already
+        // (e.g. in the set {3, 4, 5}, 5 - 3 = 2).
+        const possibleOptions = upper - lower;
+
+        const randInt = lower + Math.floor(Math.random() * possibleOptions);
+        if (randInt >= excluded) {
+            return randInt + 1;
+        }
+
+        return randInt;
+    }
+ 
+    /**
+     * Scales a number from one range to another.
+     * @param {number} i number to be scaled
+     * @param {number} iMin input range minimum
+     * @param {number} iMax input range maximum
+     * @param {number} oMin output range minimum
+     * @param {number} oMax output range maximum
+     * @return {number} scaled number
+     */
+    static scale (i, iMin, iMax, oMin, oMax) {
+        const p = (i - iMin) / (iMax - iMin);
+        return (p * (oMax - oMin)) + oMin;
+    }
+}
+
+module.exports = MathUtil;

package/src/util/maybe-format-message.js

@@ -0,0 +1,18 @@
+const formatMessage = require('format-message');
+
+/**
+ * Check if `maybeMessage` looks like a message object, and if so pass it to `formatMessage`.
+ * Otherwise, return `maybeMessage` as-is.
+ * @param {*} maybeMessage - something that might be a message descriptor object.
+ * @param {object} [args] - the arguments to pass to `formatMessage` if it gets called.
+ * @param {string} [locale] - the locale to pass to `formatMessage` if it gets called.
+ * @return {string|*} - the formatted message OR the original `maybeMessage` input.
+ */
+const maybeFormatMessage = function (maybeMessage, args, locale) {
+    if (maybeMessage && maybeMessage.id && maybeMessage.default) {
+        return formatMessage(maybeMessage, args, locale);
+    }
+    return maybeMessage;
+};
+
+module.exports = maybeFormatMessage;

package/src/util/new-block-ids.js

@@ -0,0 +1,33 @@
+const uid = require('./uid');
+
+/**
+ * Mutate the given blocks to have new IDs and update all internal ID references.
+ * Does not return anything to make it clear that the blocks are updated in-place.
+ * @param {array} blocks - blocks to be mutated.
+ */
+module.exports = blocks => {
+    const oldToNew = {};
+
+    // First update all top-level IDs and create old-to-new mapping
+    for (let i = 0; i < blocks.length; i++) {
+        const newId = uid();
+        const oldId = blocks[i].id;
+        blocks[i].id = oldToNew[oldId] = newId;
+    }
+
+    // Then go back through and update inputs (block/shadow)
+    // and next/parent properties
+    for (let i = 0; i < blocks.length; i++) {
+        for (const key in blocks[i].inputs) {
+            const input = blocks[i].inputs[key];
+            input.block = oldToNew[input.block];
+            input.shadow = oldToNew[input.shadow];
+        }
+        if (blocks[i].parent) {
+            blocks[i].parent = oldToNew[blocks[i].parent];
+        }
+        if (blocks[i].next) {
+            blocks[i].next = oldToNew[blocks[i].next];
+        }
+    }
+};

package/src/util/rateLimiter.js

@@ -0,0 +1,73 @@
+const Timer = require('../util/timer');
+
+class RateLimiter {
+    /**
+     * A utility for limiting the rate of repetitive send operations, such as
+     * bluetooth messages being sent to hardware devices. It uses the token bucket
+     * strategy: a counter accumulates tokens at a steady rate, and each send costs
+     * a token. If no tokens remain, it's not okay to send.
+     * @param {number} maxRate the maximum number of sends allowed per second
+     * @constructor
+     */
+    constructor (maxRate) {
+        /**
+         * The maximum number of tokens.
+         * @type {number}
+         */
+        this._maxTokens = maxRate;
+
+        /**
+         * The interval in milliseconds for refilling one token. It is calculated
+         * so that the tokens will be filled to maximum in one second.
+         * @type {number}
+         */
+        this._refillInterval = 1000 / maxRate;
+
+        /**
+         * The current number of tokens in the bucket.
+         * @type {number}
+         */
+        this._count = this._maxTokens;
+
+        this._timer = new Timer();
+        this._timer.start();
+
+        /**
+         * The last time in milliseconds when the token count was updated.
+         * @type {number}
+         */
+        this._lastUpdateTime = this._timer.timeElapsed();
+    }
+
+    /**
+     * Check if it is okay to send a message, by updating the token count,
+     * taking a token and then checking if we are still under the rate limit.
+     * @return {boolean} true if we are under the rate limit
+     */
+    okayToSend () {
+        // Calculate the number of tokens to refill the bucket with, based on the
+        // amount of time since the last refill.
+        const now = this._timer.timeElapsed();
+        const timeSinceRefill = now - this._lastUpdateTime;
+        const refillCount = Math.floor(timeSinceRefill / this._refillInterval);
+
+        // If we're adding at least one token, reset _lastUpdateTime to now.
+        // Otherwise, don't reset it so that we can continue measuring time until
+        // the next refill.
+        if (refillCount > 0) {
+            this._lastUpdateTime = now;
+        }
+
+        // Refill the tokens up to the maximum
+        this._count = Math.min(this._maxTokens, this._count + refillCount);
+
+        // If we have at least one token, use one, and it's okay to send.
+        if (this._count > 0) {
+            this._count--;
+            return true;
+        }
+        return false;
+    }
+}
+
+module.exports = RateLimiter;

package/src/util/scratch-link-websocket.js

@@ -0,0 +1,133 @@
+/**
+ * This class provides a ScratchLinkSocket implementation using WebSockets,
+ * attempting to connect with the locally installed Scratch-Link.
+ *
+ * To connect with ScratchLink without WebSockets, you must implement all of the
+ * public methods in this class.
+ * - open()
+ * - close()
+ * - setOn[Open|Close|Error]
+ * - setHandleMessage
+ * - sendMessage(msgObj)
+ * - isOpen()
+ */
+class ScratchLinkWebSocket {
+    constructor (type) {
+        this._type = type;
+        this._onOpen = null;
+        this._onClose = null;
+        this._onError = null;
+        this._handleMessage = null;
+
+        this._ws = null;
+    }
+
+    open () {
+        if (!(this._onOpen && this._onClose && this._onError && this._handleMessage)) {
+            throw new Error('Must set open, close, message and error handlers before calling open on the socket');
+        }
+
+        let pathname;
+        switch (this._type) {
+        case 'BLE':
+            pathname = 'scratch/ble';
+            break;
+        case 'BT':
+            pathname = 'scratch/bt';
+            break;
+        default:
+            throw new Error(`Unknown ScratchLink socket Type: ${this._type}`);
+        }
+
+        // Try ws:// (the new way) and wss:// (the old way) simultaneously. If either connects, close the other. If we
+        // were to try one and fall back to the other on failure, that could mean a delay of 30 seconds or more for
+        // those who need the fallback.
+        // If both connections fail we should report only one error.
+
+        const setSocket = (socketToUse, socketToClose) => {
+            socketToClose.onopen = socketToClose.onerror = null;
+            socketToClose.close();
+
+            this._ws = socketToUse;
+            this._ws.onopen = this._onOpen;
+            this._ws.onclose = this._onClose;
+            this._ws.onerror = this._onError;
+            this._ws.onmessage = this._onMessage.bind(this);
+        };
+
+        const ws = new WebSocket(`ws://127.0.0.1:20111/${pathname}`);
+        const wss = new WebSocket(`wss://device-manager.scratch.mit.edu:20110/${pathname}`);
+
+        const connectTimeout = setTimeout(() => {
+            // neither socket succeeded before the timeout
+            setSocket(ws, wss);
+            this._ws.onerror(new Event('timeout'));
+        }, 15 * 1000);
+        ws.onopen = openEvent => {
+            clearTimeout(connectTimeout);
+            setSocket(ws, wss);
+            this._ws.onopen(openEvent);
+        };
+        wss.onopen = openEvent => {
+            clearTimeout(connectTimeout);
+            setSocket(wss, ws);
+            this._ws.onopen(openEvent);
+        };
+
+        let wsError;
+        let wssError;
+        const errorHandler = () => {
+            // if only one has received an error, we haven't overall failed yet
+            if (wsError && wssError) {
+                clearTimeout(connectTimeout);
+                setSocket(ws, wss);
+                this._ws.onerror(wsError);
+            }
+        };
+        ws.onerror = errorEvent => {
+            wsError = errorEvent;
+            errorHandler();
+        };
+        wss.onerror = errorEvent => {
+            wssError = errorEvent;
+            errorHandler();
+        };
+    }
+
+    close () {
+        this._ws.close();
+        this._ws = null;
+    }
+
+    sendMessage (message) {
+        const messageText = JSON.stringify(message);
+        this._ws.send(messageText);
+    }
+
+    setOnOpen (fn) {
+        this._onOpen = fn;
+    }
+
+    setOnClose (fn) {
+        this._onClose = fn;
+    }
+
+    setOnError (fn) {
+        this._onError = fn;
+    }
+
+    setHandleMessage (fn) {
+        this._handleMessage = fn;
+    }
+
+    isOpen () {
+        return this._ws && this._ws.readyState === this._ws.OPEN;
+    }
+
+    _onMessage (e) {
+        const json = JSON.parse(e.data);
+        this._handleMessage(json);
+    }
+}
+
+module.exports = ScratchLinkWebSocket;

package/src/util/string-util.js

@@ -0,0 +1,94 @@
+const log = require('./log');
+
+class StringUtil {
+    static withoutTrailingDigits (s) {
+        let i = s.length - 1;
+        while ((i >= 0) && ('0123456789'.indexOf(s.charAt(i)) > -1)) i--;
+        return s.slice(0, i + 1);
+    }
+
+    static unusedName (name, existingNames) {
+        if (existingNames.indexOf(name) < 0) return name;
+        name = StringUtil.withoutTrailingDigits(name);
+        let i = 2;
+        while (existingNames.indexOf(name + i) >= 0) i++;
+        return name + i;
+    }
+
+    /**
+     * Split a string on the first occurrence of a split character.
+     * @param {string} text - the string to split.
+     * @param {string} separator - split the text on this character.
+     * @returns {string[]} - the two parts of the split string, or [text, null] if no split character found.
+     * @example
+     * // returns ['foo', 'tar.gz']
+     * splitFirst('foo.tar.gz', '.');
+     * @example
+     * // returns ['foo', null]
+     * splitFirst('foo', '.');
+     * @example
+     * // returns ['foo', '']
+     * splitFirst('foo.', '.');
+     */
+    static splitFirst (text, separator) {
+        const index = text.indexOf(separator);
+        if (index >= 0) {
+            return [text.substring(0, index), text.substring(index + 1)];
+        }
+        return [text, null];
+
+    }
+
+    /**
+     * A customized version of JSON.stringify that sets Infinity/NaN to 0,
+     * instead of the default (null).
+     * Needed because null is not of type number, but Infinity/NaN are, which
+     * can lead to serialization producing JSON that isn't valid based on the parser schema.
+     * It is also consistent with the behavior of saving 2.0 projects.
+     * This is only needed when stringifying an object for saving.
+     *
+     * @param {!object} obj - The object to serialize
+     * @return {!string} The JSON.stringified string with Infinity/NaN replaced with 0
+     */
+    static stringify (obj) {
+        return JSON.stringify(obj, (_key, value) => {
+            if (typeof value === 'number' &&
+               (value === Infinity || value === -Infinity || isNaN(value))){
+                return 0;
+            }
+            return value;
+        });
+    }
+    /**
+     * A function to replace unsafe characters (not allowed in XML) with safe ones. This is used
+     * in cases where we're replacing non-user facing strings (e.g. variable IDs).
+     * When replacing user facing strings, the xmlEscape utility function should be used
+     * instead so that the user facing string does not change how it displays.
+     * @param {!string | !Array.<string>} unsafe Unsafe string possibly containing unicode control characters.
+     * In some cases this argument may be an array (e.g. hacked inputs from 2.0)
+     * @return {string} String with control characters replaced.
+     */
+    static replaceUnsafeChars (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 = StringUtil;