scratch-storage 2.3.284 → 3.0.0

package/src/{FetchWorkerTool.js → FetchWorkerTool.ts}

@@ -1,9 +1,21 @@
-const {Headers, applyMetadata} = require('./scratchFetch');
+import {Headers, applyMetadata} from './scratchFetch';
+import {ScratchGetRequest, Tool} from './Tool';
+
+interface DeferredJob {
+    id: string,
+    resolve: (buffer: ArrayBuffer) => void;
+    reject: (error: unknown) => void;
+}
 
 /**
  * Get and send assets with a worker that uses fetch.
  */
-class PrivateFetchWorkerTool {
+class PrivateFetchWorkerTool implements Tool {
+    private _workerSupport: {fetch: boolean};
+    private _supportError: unknown;
+    private worker: Worker | null;
+    private jobs: Record<string, DeferredJob | undefined>;
+
     constructor () {
         /**
          * What does the worker support of the APIs we need?
@@ -33,10 +45,13 @@ class PrivateFetchWorkerTool {
 
         try {
             if (this.isGetSupported) {
-                // eslint-disable-next-line global-require
-                const FetchWorker = require('worker-loader?{"inline":true,"fallback":true}!./FetchWorkerTool.worker');
-
-                const worker = new FetchWorker();
+                // Yes, this is a browser API and we've specified `browser: false` in the eslint env,
+                // but `isGetSupported` checks for the presence of Worker and uses it only if present.
+                // Also see https://webpack.js.org/guides/web-workers/
+                // eslint-disable-next-line no-undef
+                const worker = new Worker(
+                    /* webpackChunkName: "fetch-worker" */ new URL('./FetchWorkerTool.worker', import.meta.url)
+                );
 
                 worker.addEventListener('message', ({data}) => {
                     if (data.support) {
@@ -44,11 +59,12 @@ class PrivateFetchWorkerTool {
                         return;
                     }
                     for (const message of data) {
-                        if (this.jobs[message.id]) {
+                        const job = this.jobs[message.id];
+                        if (job) {
                             if (message.error) {
-                                this.jobs[message.id].reject(message.error);
+                                job.reject(message.error);
                             } else {
-                                this.jobs[message.id].resolve(message.buffer);
+                                job.resolve(message.buffer);
                             }
                             delete this.jobs[message.id];
                         }
@@ -70,7 +86,7 @@ class PrivateFetchWorkerTool {
      * guess that it does if the window does until the worker can inform us.
      * @returns {boolean} Is get supported?
      */
-    get isGetSupported () {
+    get isGetSupported (): boolean {
         return (
             typeof Worker !== 'undefined' &&
             this._workerSupport.fetch &&
@@ -84,8 +100,14 @@ class PrivateFetchWorkerTool {
      * @param {{method:string}} options - Additional options to configure fetch.
      * @returns {Promise.<Buffer|Uint8Array|null>} Resolve to Buffer of data from server.
      */
-    get ({url, ...options}) {
-        return new Promise((resolve, reject) => {
+    get ({url, ...options}: ScratchGetRequest): Promise<Uint8Array | null> {
+        const worker = this.worker;
+
+        if (!worker) {
+            return Promise.reject(new Error('The worker could not be initialized'));
+        }
+
+        return new Promise<ArrayBuffer>((resolve, reject) => {
             // TODO: Use a Scratch standard ID generator ...
             const id = Math.random().toString(16)
                 .substring(2);
@@ -99,7 +121,8 @@ class PrivateFetchWorkerTool {
             if (augmentedOptions && augmentedOptions.headers instanceof Headers) {
                 augmentedOptions.headers = Array.from(augmentedOptions.headers.entries());
             }
-            this.worker.postMessage({
+
+            worker.postMessage({
                 id,
                 url,
                 options: augmentedOptions
@@ -118,7 +141,7 @@ class PrivateFetchWorkerTool {
      * Is sending supported? always false for FetchWorkerTool.
      * @returns {boolean} Is sending supported?
      */
-    get isSendSupported () {
+    get isSendSupported (): boolean {
         return false;
     }
 
@@ -126,10 +149,12 @@ class PrivateFetchWorkerTool {
      * Send data to a server.
      * @throws {Error} A not implemented error.
      */
-    send () {
+    send (): never {
         throw new Error('Not implemented.');
     }
 
+    private static _instance?: PrivateFetchWorkerTool;
+
     /**
      * Return a static PrivateFetchWorkerTool instance on demand.
      * @returns {PrivateFetchWorkerTool} A static PrivateFetchWorkerTool
@@ -146,7 +171,9 @@ class PrivateFetchWorkerTool {
 /**
  * Get and send assets with a worker that uses fetch.
  */
-class PublicFetchWorkerTool {
+export default class PublicFetchWorkerTool {
+    private inner: PrivateFetchWorkerTool;
+
     constructor () {
         /**
          * Shared instance of an internal worker. PublicFetchWorkerTool proxies
@@ -160,7 +187,7 @@ class PublicFetchWorkerTool {
      * Is get supported?
      * @returns {boolean} Is get supported?
      */
-    get isGetSupported () {
+    get isGetSupported (): boolean {
         return this.inner.isGetSupported;
     }
 
@@ -169,7 +196,7 @@ class PublicFetchWorkerTool {
      * @param {{url:string}} reqConfig - Request configuration for data to get.
      * @returns {Promise.<Buffer|Uint8Array|null>} Resolve to Buffer of data from server.
      */
-    get (reqConfig) {
+    get (reqConfig: ScratchGetRequest): Promise<Uint8Array | null> {
         return this.inner.get(reqConfig);
     }
 
@@ -177,7 +204,7 @@ class PublicFetchWorkerTool {
      * Is sending supported?
      * @returns {boolean} Is sending supported?
      */
-    get isSendSupported () {
+    get isSendSupported (): boolean {
         return false;
     }
 
@@ -185,9 +212,7 @@ class PublicFetchWorkerTool {
      * Send data to a server with a worker that uses fetch.
      * @throws {Error} A not implemented error.
      */
-    send () {
+    send (): never {
         throw new Error('Not implemented.');
     }
 }
-
-module.exports = PublicFetchWorkerTool;

package/src/{Helper.js → Helper.ts}

@@ -1,9 +1,16 @@
+import Asset, {AssetId} from './Asset';
+import {AssetType} from './AssetType';
+import {DataFormat} from './DataFormat';
+import {ScratchStorage} from './ScratchStorage';
+
 /**
  * Base class for asset load/save helpers.
  * @abstract
  */
-class Helper {
-    constructor (parent) {
+export default class Helper {
+    public parent!: ScratchStorage;
+
+    constructor (parent: ScratchStorage) {
         this.parent = parent;
     }
 
@@ -14,9 +21,7 @@ class Helper {
      * @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) {
+    load (assetType: AssetType, assetId: AssetId, dataFormat: DataFormat): Promise<Asset | null> | null {
         return Promise.reject(new Error(`No asset of type ${assetType} for ID ${assetId} with format ${dataFormat}`));
     }
 }
-
-module.exports = Helper;

package/src/{ProxyTool.js → ProxyTool.ts}

@@ -1,5 +1,6 @@
-const FetchWorkerTool = require('./FetchWorkerTool');
-const FetchTool = require('./FetchTool');
+import FetchWorkerTool from './FetchWorkerTool';
+import {FetchTool} from './FetchTool';
+import {ScratchGetRequest, ScratchSendRequest, Tool} from './Tool';
 
 /**
  * @typedef {object} Request
@@ -9,12 +10,32 @@ const FetchTool = require('./FetchTool');
  * @property {boolean} withCredentials
  */
 
+type ToolFilter = typeof ProxyTool.TOOL_FILTER[keyof typeof ProxyTool.TOOL_FILTER];
+
 /**
  * Get and send assets with other tools in sequence.
  */
-class ProxyTool {
-    constructor (filter = ProxyTool.TOOL_FILTER.ALL) {
-        let tools;
+export default class ProxyTool implements Tool {
+    public tools: Tool[];
+
+    /**
+     * Constant values that filter the set of tools in a ProxyTool instance.
+     * @enum {string}
+     */
+    public static TOOL_FILTER = {
+        /**
+         * Use all tools.
+         */
+        ALL: 'all',
+
+        /**
+         * Use tools that are ready right now.
+         */
+        READY: 'ready'
+    } as const;
+
+    constructor (filter: ToolFilter = ProxyTool.TOOL_FILTER.ALL) {
+        let tools: Tool[];
         if (filter === ProxyTool.TOOL_FILTER.READY) {
             tools = [new FetchTool()];
         } else {
@@ -32,7 +53,7 @@ class ProxyTool {
      * Is get supported? false if all proxied tool return false.
      * @returns {boolean} Is get supported?
      */
-    get isGetSupported () {
+    get isGetSupported (): boolean {
         return this.tools.some(tool => tool.isGetSupported);
     }
 
@@ -41,9 +62,9 @@ class ProxyTool {
      * @param {Request} reqConfig - Request configuration for data to get.
      * @returns {Promise.<Buffer>} Resolve to Buffer of data from server.
      */
-    get (reqConfig) {
+    get (reqConfig: ScratchGetRequest): Promise<Uint8Array | null> {
         let toolIndex = 0;
-        const nextTool = err => {
+        const nextTool = (err?: unknown): Promise<Uint8Array | null> => {
             const tool = this.tools[toolIndex++];
             if (!tool) {
                 throw err;
@@ -60,7 +81,7 @@ class ProxyTool {
      * Is sending supported? false if all proxied tool return false.
      * @returns {boolean} Is sending supported?
      */
-    get isSendSupported () {
+    get isSendSupported (): boolean {
         return this.tools.some(tool => tool.isSendSupported);
     }
 
@@ -69,9 +90,9 @@ class ProxyTool {
      * @param {Request} reqConfig - Request configuration for data to send.
      * @returns {Promise.<Buffer|string|object>} Server returned metadata.
      */
-    send (reqConfig) {
+    send (reqConfig: ScratchSendRequest): Promise<string> {
         let toolIndex = 0;
-        const nextTool = err => {
+        const nextTool = (err?: unknown): Promise<string> => {
             const tool = this.tools[toolIndex++];
             if (!tool) {
                 throw err;
@@ -84,21 +105,3 @@ class ProxyTool {
         return nextTool();
     }
 }
-
-/**
- * Constant values that filter the set of tools in a ProxyTool instance.
- * @enum {string}
- */
-ProxyTool.TOOL_FILTER = {
-    /**
-     * Use all tools.
-     */
-    ALL: 'all',
-
-    /**
-     * Use tools that are ready right now.
-     */
-    READY: 'ready'
-};
-
-module.exports = ProxyTool;

package/src/{ScratchStorage.js → ScratchStorage.ts}

@@ -1,20 +1,32 @@
-const log = require('./log');
+import log from './log';
 
-const BuiltinHelper = require('./BuiltinHelper');
-const WebHelper = require('./WebHelper');
+import BuiltinHelper from './BuiltinHelper';
+import WebHelper, {UrlFunction} from './WebHelper';
 
-const _Asset = require('./Asset');
-const _AssetType = require('./AssetType');
-const _DataFormat = require('./DataFormat');
-const _scratchFetch = require('./scratchFetch');
+import _Asset, {AssetData, AssetId} from './Asset';
+import {AssetType as _AssetType, AssetType} from './AssetType';
+import {DataFormat as _DataFormat, DataFormat} from './DataFormat';
+import _scratchFetch from './scratchFetch';
+import Helper from './Helper';
+
+interface HelperWithPriority {
+    helper: Helper,
+    priority: number
+}
+
+export class ScratchStorage {
+    public defaultAssetId: Record<AssetType['name'], AssetId>;
+    public builtinHelper: BuiltinHelper;
+    public webHelper: WebHelper;
+
+    private _helpers: HelperWithPriority[];
 
-class ScratchStorage {
     constructor () {
         this.defaultAssetId = {};
 
         this.builtinHelper = new BuiltinHelper(this);
         this.webHelper = new WebHelper(this);
-        this.builtinHelper.registerDefaultAssets(this);
+        this.builtinHelper.registerDefaultAssets();
 
         this._helpers = [
             {
@@ -85,7 +97,7 @@ class ScratchStorage {
      * @param {Helper} helper - the helper to be added.
      * @param {number} [priority] - the priority for this new helper (default: 0).
      */
-    addHelper (helper, priority = 0) {
+    addHelper (helper: Helper, priority: number = 0) {
         this._helpers.push({helper, priority});
         this._helpers.sort((a, b) => b.priority - a.priority);
     }
@@ -95,7 +107,7 @@ class ScratchStorage {
      * @param {string} assetId - The id of the asset to fetch.
      * @returns {?Asset} The asset, if it exists.
      */
-    get (assetId) {
+    get (assetId: string): _Asset | null {
         return this.builtinHelper.get(assetId);
     }
 
@@ -107,7 +119,7 @@ class ScratchStorage {
      * @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) {
+    cache (assetType: AssetType, dataFormat: DataFormat, data: AssetData, id: AssetId): AssetId {
         log.warn('Deprecation: Storage.cache is deprecated. Use Storage.createAsset, and store assets externally.');
         return this.builtinHelper._store(assetType, dataFormat, data, id);
     }
@@ -121,7 +133,13 @@ class ScratchStorage {
      * @param {bool} [generateId] - flag to set id to an md5 hash of data if `id` isn't supplied
      * @returns {Asset} generated Asset with `id` attribute set if not supplied
      */
-    createAsset (assetType, dataFormat, data, id, generateId) {
+    createAsset (
+        assetType: AssetType,
+        dataFormat: DataFormat,
+        data: AssetData,
+        id: AssetId,
+        generateId: boolean
+    ): _Asset {
         if (!dataFormat) throw new Error('Tried to create asset without a dataFormat');
         return new _Asset(assetType, id, dataFormat, data, generateId);
     }
@@ -133,7 +151,12 @@ class ScratchStorage {
      * @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) {
+    addWebStore (
+        types: AssetType[],
+        getFunction: UrlFunction,
+        createFunction?: UrlFunction,
+        updateFunction?: UrlFunction
+    ): void {
         this.webHelper.addStore(types, getFunction, createFunction, updateFunction);
     }
 
@@ -143,7 +166,7 @@ class ScratchStorage {
      * @param {Array.<AssetType>} types - The types of asset provided by this source.
      * @param {UrlFunction} urlFunction - A function which computes a GET URL from an Asset.
      */
-    addWebSource (types, urlFunction) {
+    addWebSource (types: AssetType[], urlFunction: UrlFunction): void {
         log.warn('Deprecation: Storage.addWebSource has been replaced by addWebStore.');
         this.addWebStore(types, urlFunction);
     }
@@ -153,7 +176,7 @@ class ScratchStorage {
      * @param {AssetType} type - Get the default ID for assets of this type.
      * @return {?string} The ID of the default asset of the given type, if any.
      */
-    getDefaultAssetId (type) {
+    getDefaultAssetId (type: AssetType): AssetId | undefined {
         if (Object.prototype.hasOwnProperty.call(this.defaultAssetId, type.name)) {
             return this.defaultAssetId[type.name];
         }
@@ -167,7 +190,7 @@ class ScratchStorage {
      * @param {AssetType} type - The type of asset for which the default will be set.
      * @param {string} id - The default ID to use for this type of asset.
      */
-    setDefaultAssetId (type, id) {
+    setDefaultAssetId (type: AssetType, id: AssetId): void {
         this.defaultAssetId[type.name] = id;
     }
 
@@ -182,15 +205,14 @@ class ScratchStorage {
      *   If the promise is rejected, there was an error on at least one asset source. HTTP 404 does not count as an
      *   error here, but (for example) HTTP 403 does.
      */
-    load (assetType, assetId, dataFormat) {
-        /** @type {Helper[]} */
+    load (assetType: AssetType, assetId: AssetId, dataFormat: DataFormat): Promise<_Asset | null> {
         const helpers = this._helpers.map(x => x.helper);
-        const errors = [];
+        const errors: unknown[] = [];
         dataFormat = dataFormat || assetType.runtimeFormat;
 
         let helperIndex = 0;
-        let helper;
-        const tryNextHelper = err => {
+        let helper: Helper;
+        const tryNextHelper = (err?: unknown): Promise<_Asset | null> => {
             if (err) { // Track the error, but continue looking
                 errors.push(err);
             }
@@ -227,18 +249,19 @@ class ScratchStorage {
      * @param {?string} [assetId] - The ID of the asset to fetch: a project ID, MD5, etc.
      * @return {Promise.<object>} A promise for asset metadata
      */
-    store (assetType, dataFormat, data, assetId) {
+    store (assetType: AssetType, dataFormat: DataFormat | null | undefined, data: AssetData, assetId?: AssetId) {
         dataFormat = dataFormat || assetType.runtimeFormat;
-        return new Promise(
-            (resolve, reject) =>
-                this.webHelper.store(assetType, dataFormat, data, assetId)
-                    .then(body => {
-                        this.builtinHelper._store(assetType, dataFormat, data, body.id);
-                        return resolve(body);
-                    })
-                    .catch(error => reject(error))
-        );
+
+        return this.webHelper.store(assetType, dataFormat, data, assetId)
+            .then(body => {
+                // The previous logic here ignored that the body can be a string (if it's not a JSON),
+                // so just ignore that case.
+                // Also, having undefined was the previous behavior
+                // eslint-disable-next-line no-undefined
+                const id = typeof body === 'string' ? undefined : body.id;
+
+                this.builtinHelper._store(assetType, dataFormat, data, id);
+                return body;
+            });
     }
 }
-
-module.exports = ScratchStorage;

package/src/Tool.ts

@@ -0,0 +1,10 @@
+export type ScratchGetRequest = {url: string} & RequestInit;
+export type ScratchSendRequest = {url: string, withCredentials?: boolean} & RequestInit;
+
+export interface Tool {
+  get isGetSupported (): boolean;
+  get (request: ScratchGetRequest): Promise<Uint8Array | null>;
+
+  get isSendSupported (): boolean;
+  send (request: ScratchSendRequest): Promise<string>;
+}

package/src/{WebHelper.js → WebHelper.ts}

@@ -1,8 +1,11 @@
-const log = require('./log');
+import log from './log';
 
-const Asset = require('./Asset');
-const Helper = require('./Helper');
-const ProxyTool = require('./ProxyTool');
+import Asset, {AssetData, AssetId} from './Asset';
+import Helper from './Helper';
+import ProxyTool from './ProxyTool';
+import {ScratchGetRequest, ScratchSendRequest, Tool} from './Tool';
+import {AssetType} from './AssetType';
+import {DataFormat} from './DataFormat';
 
 const ensureRequestConfig = reqConfig => {
     if (typeof reqConfig === 'string') {
@@ -20,7 +23,20 @@ const ensureRequestConfig = reqConfig => {
  *                              the underlying fetch call (necessary for configuring e.g. authentication)
  */
 
-class WebHelper extends Helper {
+export type UrlFunction = (asset: Asset) => string | ScratchGetRequest | ScratchSendRequest;
+
+interface StoreRecord {
+    types: string[],
+    get: UrlFunction,
+    create?: UrlFunction,
+    update?: UrlFunction
+}
+
+export default class WebHelper extends Helper {
+    public stores: StoreRecord[];
+    public assetTool: Tool;
+    public projectTool: Tool;
+
     constructor (parent) {
         super(parent);
 
@@ -56,7 +72,7 @@ class WebHelper extends Helper {
      * @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) {
+    addSource (types: AssetType[], urlFunction: UrlFunction): void {
         log.warn('Deprecation: WebHelper.addSource has been replaced with WebHelper.addStore.');
         this.addStore(types, urlFunction);
     }
@@ -68,7 +84,12 @@ class WebHelper extends Helper {
      * @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) {
+    addStore (
+        types: AssetType[],
+        getFunction: UrlFunction,
+        createFunction?: UrlFunction,
+        updateFunction?: UrlFunction
+    ): void {
         this.stores.push({
             types: types.map(assetType => assetType.name),
             get: getFunction,
@@ -84,13 +105,13 @@ class WebHelper extends Helper {
      * @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) {
+    load (assetType: AssetType, assetId: AssetId, dataFormat: DataFormat): Promise<Asset | null> {
 
         /** @type {Array.<{url:string, result:*}>} List of URLs attempted & errors encountered. */
-        const errors = [];
+        const errors: unknown[] = [];
         const stores = this.stores.slice()
             .filter(store => store.types.indexOf(assetType.name) >= 0);
-        
+
         // New empty asset but it doesn't have data yet
         const asset = new Asset(assetType, assetId, dataFormat);
 
@@ -100,7 +121,7 @@ class WebHelper extends Helper {
         }
 
         let storeIndex = 0;
-        const tryNextSource = err => {
+        const tryNextSource = (err?: unknown): Promise<Asset | null> => {
             if (err) {
                 errors.push(err);
             }
@@ -143,7 +164,12 @@ class WebHelper extends Helper {
      * @param {?string} assetId - The ID of the asset to fetch: a project ID, MD5, etc.
      * @return {Promise.<object>} A promise for the response from the create or update request
      */
-    store (assetType, dataFormat, data, assetId) {
+    store (
+        assetType: AssetType,
+        dataFormat: DataFormat | undefined,
+        data: AssetData,
+        assetId?: AssetId
+    ): Promise<string | {id: string}> {
         const asset = new Asset(assetType, assetId, dataFormat);
         // If we have an asset id, we should update, otherwise create to get an id
         const create = assetId === '' || assetId === null || typeof assetId === 'undefined';
@@ -168,7 +194,10 @@ class WebHelper extends Helper {
         }
 
         const reqConfig = ensureRequestConfig(
-            create ? store.create(asset) : store.update(asset)
+            // The non-nullability of this gets checked above while looking up the store.
+            // Making TS understand that is going to require code refactoring which we currently don't
+            // feel safe to do.
+            create ? store.create!(asset) : store.update!(asset)
         );
         const reqBodyConfig = Object.assign({body: data, method}, reqConfig);
         return tool.send(reqBodyConfig)
@@ -191,5 +220,3 @@ class WebHelper extends Helper {
             });
     }
 }
-
-module.exports = WebHelper;

package/src/index.ts

@@ -0,0 +1,19 @@
+import {ScratchStorage} from './ScratchStorage';
+import Asset, {AssetId} from './Asset';
+import {AssetType} from './AssetType';
+import {DataFormat} from './DataFormat';
+import Helper from './Helper';
+
+export {
+    /**
+     * Export for use with NPM & Node.js.
+     * @type {ScratchStorage}
+     */
+    ScratchStorage,
+
+    Asset,
+    AssetId,
+    AssetType,
+    DataFormat,
+    Helper
+};

package/src/log.ts

@@ -0,0 +1,4 @@
+import minilog from 'minilog';
+minilog.enable();
+
+export default minilog('storage');