Merge pull request #55 from cwillisf/storage-helper-priorities

feat: create `addHelper` to add helper w/ priority

Author: cwillisf

src/ScratchStorage.js

@@ -14,6 +14,17 @@ class ScratchStorage {
         this.builtinHelper = new BuiltinHelper(this);
         this.webHelper = new WebHelper(this);
         this.builtinHelper.registerDefaultAssets(this);
+
+        this._helpers = [
+            {
+                helper: this.builtinHelper,
+                priority: 100
+            },
+            {
+                helper: this.webHelper,
+                priority: -100
+            }
+        ];
     }
 
     /**
@@ -58,6 +69,18 @@ class ScratchStorage {
         return _AssetType;
     }
 
+    /**
+     * Add a storage helper to this manager. Helpers with a higher priority number will be checked first when loading
+     * or storing assets. For comparison, the helper for built-in assets has `priority=100` and the default web helper
+     * has `priority=-100`. The relative order of helpers with equal priorities is undefined.
+     * @param {Helper} helper - the helper to be added.
+     * @param {number} [priority] - the priority for this new helper (default: 0).
+     */
+    addHelper (helper, priority = 0) {
+        this._helpers.push({helper, priority});
+        this._helpers.sort((a, b) => b.priority - a.priority);
+    }
+
     /**
      * Synchronously fetch a cached asset from built-in storage. Assets are cached when they are loaded.
      * @param {string} assetId - The id of the asset to fetch.
@@ -152,7 +175,7 @@ class ScratchStorage {
      */
     load (assetType, assetId, dataFormat) {
         /** @type {Helper[]} */
-        const helpers = [this.builtinHelper, this.webHelper];
+        const helpers = this._helpers.map(x => x.helper);
         const errors = [];
         let helperIndex = 0;
         dataFormat = dataFormat || assetType.runtimeFormat;

test/unit/add-helper.js

@@ -0,0 +1,85 @@
+const test = require('tap').test;
+
+const ScratchStorage = require('../../dist/node/scratch-storage');
+
+/**
+ * Simulate a storage helper, adding log messages when "load" is called rather than actually loading anything.
+ */
+class LoggingHelper {
+    /**
+     * Construct a LoggingHelper instance.
+     * @param {Storage} storage - An instance of the storage module.
+     * @param {string} label - A label for this instance.
+     * @param {boolean} shouldSucceed - set to true to make `load` always succeed, or false to make `load` always fail.
+     * @param {Array.<string>} logContainer - an array in which log messages will be stored.
+     * @constructor
+     */
+    constructor (storage, label, shouldSucceed, logContainer) {
+        this.storage = storage;
+        this.label = label;
+        this.shouldSucceed = shouldSucceed;
+        this.logContainer = logContainer;
+    }
+
+    /**
+     * Pretend to fetch an asset, but instead add a message to the log container.
+     * @param {AssetType} assetType - The type of asset to fetch.
+     * @param {string} assetId - The ID of the asset to fetch: a project ID, MD5, etc.
+     * @param {DataFormat} dataFormat - The file format / file extension of the asset to fetch: PNG, JPG, etc.
+     * @return {Promise.<Asset>} A promise for the contents of the asset.
+     */
+    load (assetType, assetId, dataFormat) {
+        this.logContainer.push(this.label);
+        return this.shouldSucceed ?
+            Promise.resolve(new this.storage.Asset(assetType, assetId, dataFormat, Buffer.from(this.label))) :
+            Promise.reject(`This is an expected failure from ${this.label}`);
+    }
+}
+
+test('ScratchStorage constructor', t => {
+    const storage = new ScratchStorage();
+    t.type(storage, ScratchStorage);
+    t.end();
+});
+
+test('LoggingHelper constructor', t => {
+    const storage = new ScratchStorage();
+    const loggingHelper = new LoggingHelper(storage, 'constructor test', true, []);
+    t.type(loggingHelper, LoggingHelper);
+    t.end();
+});
+
+test('addHelper', t => {
+    const logContainer = [];
+    const storage = new ScratchStorage();
+
+    const initialHelperCount = storage._helpers.length;
+
+    // The first two helpers should fail (shouldSucceed=false) so that the storage module continues through the list.
+    // The third helper should succeed (shouldSucceed=true) so that the overall load succeeds.
+    const loggingHelpers = [
+        new LoggingHelper(storage, 'first', false, logContainer),
+        new LoggingHelper(storage, 'second', false, logContainer),
+        new LoggingHelper(storage, 'third', true, logContainer)
+    ];
+
+    // Add out of order to check that the priority values are respected
+    storage.addHelper(loggingHelpers[2], -50);
+    storage.addHelper(loggingHelpers[0], 50);
+    storage.addHelper(loggingHelpers[1], 0);
+
+    // Did they all get added?
+    t.equal(storage._helpers.length, initialHelperCount + loggingHelpers.length);
+
+    // We shouldn't have any log entries yet
+    t.deepEqual(logContainer, []);
+
+    return storage.load(storage.AssetType.Project, '0').then(() => {
+        // Verify that all helpers were consulted, and in the correct order
+        t.deepEqual(logContainer, [
+            'first',
+            'second',
+            'third'
+        ]);
+    });
+});