feat: replace "sources" with "stores"

Sources are only for fetching, but stores allow fetching/creating/updating.  Add deprecation warnings when attempting to access "sources".  addStore accepts two additional functions, for creation and updates. Additionally, the functions can return strings or an object if additional configuration to the request to the URL is necessary. The attributes of the object are passed as options to `nets`.

BREAKING CHANGE: WebHelper.sources has been replaced by WebHelper.stores. WebHelper.addSource has been replaced by WebHelper.addStore. Storage.addWebSource has been replaced by Storage.addWebStore. BuiltinHelper.cache has been normalized to BuiltinHelper.store.

Author: Ray Schamp

src/BuiltinHelper.js

@@ -1,5 +1,7 @@
 const md5 = require('js-md5');
 
+const log = require('./log');
+
 const Asset = require('./Asset');
 const AssetType = require('./AssetType');
 const DataFormat = require('./DataFormat');
@@ -93,14 +95,28 @@ class BuiltinHelper extends Helper {
     }
 
     /**
-     * Cache an asset for future lookups by ID.
+     * Alias for store (old name of store)
+     * @deprecated Use BuiltinHelper.store
      * @param {AssetType} assetType - The type of the asset to cache.
      * @param {DataFormat} dataFormat - The dataFormat of the data for the cached asset.
      * @param {Buffer} data - The data for the cached asset.
      * @param {string} id - The id for the cached asset.
      * @returns {string} The calculated id of the cached asset, or the supplied id if the asset is mutable.
      */
     cache (assetType, dataFormat, data, id) {
+        log.warn('Deprecation: BuiltinHelper.cache has been replaced with BuiltinHelper.store.');
+        return this.store(assetType, dataFormat, data, id);
+    }
+
+    /**
+     * Cache an asset for future lookups by ID.
+     * @param {AssetType} assetType - The type of the asset to cache.
+     * @param {DataFormat} dataFormat - The dataFormat of the data for the cached asset.
+     * @param {Buffer} data - The data for the cached asset.
+     * @param {string} id - The id for the cached asset.
+     * @returns {string} The calculated id of the cached asset, or the supplied id if the asset is mutable.
+     */
+    store (assetType, dataFormat, data, id) {
         if (!dataFormat) throw new Error('Data cached without specifying its format');
         if (id !== null && typeof id !== 'undefined') {
             if (this.assets.hasOwnProperty(id) && assetType.immutable) return id;

src/ScratchStorage.js

@@ -1,3 +1,5 @@
+const log = require('./log');
+
 const BuiltinHelper = require('./BuiltinHelper');
 const WebHelper = require('./WebHelper');
 
@@ -74,16 +76,29 @@ class ScratchStorage {
      * @returns {string} The calculated id of the cached asset, or the supplied id if the asset is mutable.
      */
     cache (assetType, dataFormat, data, id) {
-        return this.builtinHelper.cache(assetType, dataFormat, data, id);
+        return this.builtinHelper.store(assetType, dataFormat, data, id);
+    }
+
+    /**
+     * Register a web-based source for assets. Sources will be checked in order of registration.
+     * @param {Array.<AssetType>} types - The types of asset provided by this source.
+     * @param {UrlFunction} getFunction - A function which computes a GET URL from an Asset.
+     * @param {UrlFunction} createFunction - A function which computes a POST URL for asset data.
+     * @param {UrlFunction} updateFunction - A function which computes a PUT URL for asset data.
+     */
+    addWebStore (types, getFunction, createFunction, updateFunction) {
+        this.webHelper.addStore(types, getFunction, createFunction, updateFunction);
     }
 
     /**
      * Register a web-based source for assets. Sources will be checked in order of registration.
+     * @deprecated Please use addWebStore
      * @param {Array.<AssetType>} types - The types of asset provided by this source.
-     * @param {UrlFunction} urlFunction - A function which computes a URL from an Asset.
+     * @param {UrlFunction} urlFunction - A function which computes a GET URL from an Asset.
      */
     addWebSource (types, urlFunction) {
-        this.webHelper.addSource(types, urlFunction);
+        log.warn('Deprecation: Storage.addWebSource has been replaced by addWebStore.');
+        this.addWebStore(types, urlFunction);
     }
 
     /**

src/WebHelper.js

@@ -1,36 +1,56 @@
 const nets = require('nets');
 
+const log = require('./log');
+
 const Asset = require('./Asset');
 const Helper = require('./Helper');
 
 /**
  * @typedef {function} UrlFunction - A function which computes a URL from asset information.
  * @param {Asset} - The asset for which the URL should be computed.
- * @returns {string} - The URL for the asset.
+ * @returns {(string|object)} - A string representing the URL for the asset request OR an object with configuration for
+ *                              the underlying `nets` call (necessary for configuring e.g. authentication)
  */
 
 class WebHelper extends Helper {
     constructor (parent) {
         super(parent);
 
         /**
-         * @type {Array.<SourceRecord>}
-         * @typedef {object} SourceRecord
-         * @property {Array.<string>} types - The types of asset provided by this source, from AssetType's name field.
-         * @property {UrlFunction} urlFunction - A function which computes a URL from an Asset.
+         * @type {Array.<StoreRecord>}
+         * @typedef {object} StoreRecord
+         * @property {Array.<string>} types - The types of asset provided by this store, from AssetType's name field.
+         * @property {UrlFunction} getFunction - A function which computes a URL from an Asset.
+         * @property {UrlFunction} createFunction - A function which computes a URL from an Asset.
+         * @property {UrlFunction} updateFunction - A function which computes a URL from an Asset.
          */
-        this.sources = [];
+        this.stores = [];
     }
 
     /**
      * Register a web-based source for assets. Sources will be checked in order of registration.
+     * @deprecated Please use addStore
      * @param {Array.<AssetType>} types - The types of asset provided by this source.
      * @param {UrlFunction} urlFunction - A function which computes a URL from an Asset.
      */
     addSource (types, urlFunction) {
-        this.sources.push({
+        log.warn('Deprecation: WebHelper.addSource has been replaced with WebHelper.addStore.');
+        this.addStore(types, urlFunction);
+    }
+
+    /**
+     * Register a web-based source for assets. Sources will be checked in order of registration.
+     * @param {Array.<AssetType>} types - The types of asset provided by this source.
+     * @param {UrlFunction} getFunction - A function which computes a GET URL for an Asset
+     * @param {UrlFunction} createFunction - A function which computes a POST URL for an Asset
+     * @param {UrlFunction} updateFunction - A function which computes a PUT URL for an Asset
+     */
+    addStore (types, getFunction, createFunction, updateFunction) {
+        this.stores.push({
             types: types.map(assetType => assetType.name),
-            urlFunction: urlFunction
+            get: getFunction,
+            create: createFunction,
+            update: updateFunction
         });
     }
 
@@ -45,34 +65,42 @@ class WebHelper extends Helper {
 
         /** @type {Array.<{url:string, result:*}>} List of URLs attempted & errors encountered. */
         const errors = [];
-        const sources = this.sources.slice();
+        const stores = this.stores.slice();
         const asset = new Asset(assetType, assetId, dataFormat);
-        let sourceIndex = 0;
+        let storeIndex = 0;
 
         return new Promise((fulfill, reject) => {
 
             const tryNextSource = () => {
 
                 /** @type {UrlFunction} */
-                let urlFunction;
+                let reqConfigFunction;
 
-                while (sourceIndex < sources.length) {
-                    const source = sources[sourceIndex];
-                    ++sourceIndex;
-                    if (source.types.indexOf(assetType.name) >= 0) {
-                        urlFunction = source.urlFunction;
+                while (storeIndex < stores.length) {
+                    const store = stores[storeIndex];
+                    ++storeIndex;
+                    if (store.types.indexOf(assetType.name) >= 0) {
+                        reqConfigFunction = store.get;
                         break;
                     }
                 }
 
-                if (urlFunction) {
-                    const url = urlFunction(asset);
-                    if (url === false) {
+                if (reqConfigFunction) {
+                    let reqConfig = reqConfigFunction(asset);
+                    if (reqConfig === false) {
                         tryNextSource();
                         return;
                     }
+                    if (typeof reqConfig === 'string') {
+                        reqConfig = {
+                            url: reqConfig
+                        };
+                    }
 
-                    nets({url: url}, (err, resp, body) => {
+                    nets({
+                        method: 'get',
+                        ...reqConfig
+                    }, (err, resp, body) => {
                         // body is a Buffer
                         if (err || Math.floor(resp.statusCode / 100) !== 2) {
                             tryNextSource();