Options util updates (#475)

* Simplify async handling

* Update comments

* Add description

* Update update 22

2 files changed, 132 insertions, 183 deletions

diff --git a/ext/js/data/options-util.js b/ext/js/data/options-util.js
index eb9af9b6..c6acf373 100644
--- a/ext/js/data/options-util.js
+++ b/ext/js/data/options-util.js
@@ -507,7 +507,7 @@ export class OptionsUtil {
 
     /**
      * @param {import('options-util').IntermediateOptions} options
-     * @param {import('options-util').ModernUpdate[]} updates
+     * @param {import('options-util').UpdateFunction[]} updates
      * @returns {Promise<import('settings').Options>}
      */
     async _applyUpdates(options, updates) {
@@ -519,9 +519,9 @@ export class OptionsUtil {
         }
 
         for (let i = Math.max(0, Math.floor(currentVersion)); i < targetVersion; ++i) {
-            const {update, async} = updates[i];
-            const result = update(options);
-            options = (async ? await result : result);
+            const update = updates[i];
+            const result = update.call(this, options);
+            if (result instanceof Promise) { await result; }
         }
 
         options.version = targetVersion;
@@ -530,35 +530,33 @@ export class OptionsUtil {
 
     /**
      * @param {?number} targetVersion
-     * @returns {import('options-util').ModernUpdate[]}
+     * @returns {import('options-util').UpdateFunction[]}
      */
     _getVersionUpdates(targetVersion) {
-        /* eslint-disable no-multi-spaces */
         const result = [
-            {async: false, update: this._updateVersion1.bind(this)},
-            {async: false, update: this._updateVersion2.bind(this)},
-            {async: true,  update: this._updateVersion3.bind(this)},
-            {async: true,  update: this._updateVersion4.bind(this)},
-            {async: false, update: this._updateVersion5.bind(this)},
-            {async: true,  update: this._updateVersion6.bind(this)},
-            {async: false, update: this._updateVersion7.bind(this)},
-            {async: true,  update: this._updateVersion8.bind(this)},
-            {async: false, update: this._updateVersion9.bind(this)},
-            {async: true,  update: this._updateVersion10.bind(this)},
-            {async: false, update: this._updateVersion11.bind(this)},
-            {async: true,  update: this._updateVersion12.bind(this)},
-            {async: true,  update: this._updateVersion13.bind(this)},
-            {async: false, update: this._updateVersion14.bind(this)},
-            {async: false, update: this._updateVersion15.bind(this)},
-            {async: false, update: this._updateVersion16.bind(this)},
-            {async: false, update: this._updateVersion17.bind(this)},
-            {async: false, update: this._updateVersion18.bind(this)},
-            {async: false, update: this._updateVersion19.bind(this)},
-            {async: false, update: this._updateVersion20.bind(this)},
-            {async: true,  update: this._updateVersion21.bind(this)},
-            {async: false, update: this._updateVersion22.bind(this)}
+            this._updateVersion1,
+            this._updateVersion2,
+            this._updateVersion3,
+            this._updateVersion4,
+            this._updateVersion5,
+            this._updateVersion6,
+            this._updateVersion7,
+            this._updateVersion8,
+            this._updateVersion9,
+            this._updateVersion10,
+            this._updateVersion11,
+            this._updateVersion12,
+            this._updateVersion13,
+            this._updateVersion14,
+            this._updateVersion15,
+            this._updateVersion16,
+            this._updateVersion17,
+            this._updateVersion18,
+            this._updateVersion19,
+            this._updateVersion20,
+            this._updateVersion21,
+            this._updateVersion22
         ];
-        /* eslint-enable no-multi-spaces */
         if (typeof targetVersion === 'number' && targetVersion < result.length) {
             result.splice(targetVersion);
         }
@@ -566,57 +564,50 @@ export class OptionsUtil {
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added options.global.database.prefixWildcardsSupported = false.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion1(options) {
-        // Version 1 changes:
-        //  Added options.global.database.prefixWildcardsSupported = false.
         options.global = {
             database: {
                 prefixWildcardsSupported: false
             }
         };
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Legacy profile update process moved into this upgrade function.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion2(options) {
-        // Version 2 changes:
-        //  Legacy profile update process moved into this upgrade function.
         for (const profile of options.profiles) {
             if (!Array.isArray(profile.conditionGroups)) {
                 profile.conditionGroups = [];
             }
             profile.options = this._legacyProfileUpdateUpdateVersion(profile.options);
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Pitch accent Anki field templates added.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion3(options) {
-        // Version 3 changes:
-        //  Pitch accent Anki field templates added.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v2.handlebars');
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Options conditions converted to string representations.
+     * - Added usePopupWindow.
+     * - Updated handlebars templates to include "clipboard-image" definition.
+     * - Updated handlebars templates to include "clipboard-text" definition.
+     * - Added hideDelay.
+     * - Added inputs to profileOptions.scanning.
+     * - Added pointerEventsEnabled to profileOptions.scanning.
+     * - Added preventMiddleMouse to profileOptions.scanning.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion4(options) {
-        // Version 4 changes:
-        //  Options conditions converted to string representations.
-        //  Added usePopupWindow.
-        //  Updated handlebars templates to include "clipboard-image" definition.
-        //  Updated handlebars templates to include "clipboard-text" definition.
-        //  Added hideDelay.
-        //  Added inputs to profileOptions.scanning.
-        //  Added pointerEventsEnabled to profileOptions.scanning.
-        //  Added preventMiddleMouse to profileOptions.scanning.
         for (const {conditionGroups} of options.profiles) {
             for (const {conditions} of conditionGroups) {
                 for (const condition of conditions) {
@@ -689,31 +680,27 @@ export class OptionsUtil {
             profileOptions.scanning.inputs = scanningInputs;
         }
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v4.handlebars');
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Removed legacy version number from profile options.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion5(options) {
-        // Version 5 changes:
-        //  Removed legacy version number from profile options.
         for (const profile of options.profiles) {
             delete profile.options.version;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Updated handlebars templates to include "conjugation" definition.
+     * - Added global option showPopupPreview.
+     * - Added global option useSettingsV2.
+     * - Added anki.checkForDuplicates.
+     * - Added general.glossaryLayoutMode; removed general.compactGlossaries.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion6(options) {
-        // Version 6 changes:
-        //  Updated handlebars templates to include "conjugation" definition.
-        //  Added global option showPopupPreview.
-        //  Added global option useSettingsV2.
-        //  Added anki.checkForDuplicates.
-        //  Added general.glossaryLayoutMode; removed general.compactGlossaries.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v6.handlebars');
         options.global.showPopupPreview = false;
         options.global.useSettingsV2 = false;
@@ -726,7 +713,6 @@ export class OptionsUtil {
                 profile.options.anki.fieldTemplates = this._updateVersion6AnkiTemplatesCompactTags(fieldTemplates);
             }
         }
-        return options;
     }
 
     /**
@@ -758,15 +744,14 @@ export class OptionsUtil {
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added general.maximumClipboardSearchLength.
+     * - Added general.popupCurrentIndicatorMode.
+     * - Added general.popupActionBarVisibility.
+     * - Added general.popupActionBarLocation.
+     * - Removed global option showPopupPreview.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion7(options) {
-        // Version 7 changes:
-        //  Added general.maximumClipboardSearchLength.
-        //  Added general.popupCurrentIndicatorMode.
-        //  Added general.popupActionBarVisibility.
-        //  Added general.popupActionBarLocation.
-        //  Removed global option showPopupPreview.
         delete options.global.showPopupPreview;
         for (const profile of options.profiles) {
             profile.options.general.maximumClipboardSearchLength = 1000;
@@ -774,29 +759,27 @@ export class OptionsUtil {
             profile.options.general.popupActionBarVisibility = 'auto';
             profile.options.general.popupActionBarLocation = 'right';
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Added translation.textReplacements.
+     * - Moved anki.sentenceExt to sentenceParsing.scanExtent.
+     * - Added sentenceParsing.enableTerminationCharacters.
+     * - Added sentenceParsing.terminationCharacters.
+     * - Changed general.popupActionBarLocation.
+     * - Added inputs.hotkeys.
+     * - Added anki.suspendNewCards.
+     * - Added popupWindow.
+     * - Updated handlebars templates to include "stroke-count" definition.
+     * - Updated global.useSettingsV2 to be true (opt-out).
+     * - Added audio.customSourceType.
+     * - Moved general.enableClipboardPopups => clipboard.enableBackgroundMonitor.
+     * - Moved general.enableClipboardMonitor => clipboard.enableSearchPageMonitor. Forced value to false due to a bug which caused its value to not be read.
+     * - Moved general.maximumClipboardSearchLength => clipboard.maximumSearchLength.
+     * - Added clipboard.autoSearchContent.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion8(options) {
-        // Version 8 changes:
-        //  Added translation.textReplacements.
-        //  Moved anki.sentenceExt to sentenceParsing.scanExtent.
-        //  Added sentenceParsing.enableTerminationCharacters.
-        //  Added sentenceParsing.terminationCharacters.
-        //  Changed general.popupActionBarLocation.
-        //  Added inputs.hotkeys.
-        //  Added anki.suspendNewCards.
-        //  Added popupWindow.
-        //  Updated handlebars templates to include "stroke-count" definition.
-        //  Updated global.useSettingsV2 to be true (opt-out).
-        //  Added audio.customSourceType.
-        //  Moved general.enableClipboardPopups => clipboard.enableBackgroundMonitor.
-        //  Moved general.enableClipboardMonitor => clipboard.enableSearchPageMonitor. Forced value to false due to a bug which caused its value to not be read.
-        //  Moved general.maximumClipboardSearchLength => clipboard.maximumSearchLength.
-        //  Added clipboard.autoSearchContent.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v8.handlebars');
         options.global.useSettingsV2 = true;
         for (const profile of options.profiles) {
@@ -868,32 +851,28 @@ export class OptionsUtil {
             delete profile.options.general.enableClipboardMonitor;
             delete profile.options.general.maximumClipboardSearchLength;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added general.frequencyDisplayMode.
+     * - Added general.termDisplayMode.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion9(options) {
-        // Version 9 changes:
-        //  Added general.frequencyDisplayMode.
-        //  Added general.termDisplayMode.
         for (const profile of options.profiles) {
             profile.options.general.frequencyDisplayMode = 'split-tags-grouped';
             profile.options.general.termDisplayMode = 'ruby';
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Removed global option useSettingsV2.
+     * - Added part-of-speech field template.
+     * - Added an argument to hotkey inputs.
+     * - Added definitionsCollapsible to dictionary options.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion10(options) {
-        // Version 10 changes:
-        //  Removed global option useSettingsV2.
-        //  Added part-of-speech field template.
-        //  Added an argument to hotkey inputs.
-        //  Added definitionsCollapsible to dictionary options.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v10.handlebars');
         delete options.global.useSettingsV2;
         for (const profile of options.profiles) {
@@ -922,17 +901,15 @@ export class OptionsUtil {
                 }
             }
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Changed dictionaries to an array.
+     * - Changed audio.customSourceUrl's {expression} marker to {term}.
+     * - Added anki.displayTags.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion11(options) {
-        // Version 11 changes:
-        //  Changed dictionaries to an array.
-        //  Changed audio.customSourceUrl's {expression} marker to {term}.
-        //  Added anki.displayTags.
         const customSourceUrlPattern = /\{expression\}/g;
         for (const profile of options.profiles) {
             const dictionariesNew = [];
@@ -949,18 +926,16 @@ export class OptionsUtil {
 
             profile.options.anki.displayTags = 'never';
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Changed sentenceParsing.enableTerminationCharacters to sentenceParsing.terminationCharacterMode.
+     * - Added {search-query} field marker.
+     * - Updated audio.sources[] to change 'custom' into 'custom-json'.
+     * - Removed audio.customSourceType.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion12(options) {
-        // Version 12 changes:
-        //  Changed sentenceParsing.enableTerminationCharacters to sentenceParsing.terminationCharacterMode.
-        //  Added {search-query} field marker.
-        //  Updated audio.sources[] to change 'custom' into 'custom-json'.
-        //  Removed audio.customSourceType.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v12.handlebars');
         for (const profile of options.profiles) {
             const {sentenceParsing, audio} = profile.options;
@@ -984,73 +959,63 @@ export class OptionsUtil {
             delete audio.customSourceUrl;
             delete audio.textToSpeechVoice;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Handlebars templates updated to use formatGlossary.
+     * - Handlebars templates updated to use new media format.
+     * - Added {selection-text} field marker.
+     * - Added {sentence-furigana} field marker.
+     * - Added anki.duplicateScopeCheckAllModels.
+     * - Updated pronunciation templates.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion13(options) {
-        // Version 13 changes:
-        //  Handlebars templates updated to use formatGlossary.
-        //  Handlebars templates updated to use new media format.
-        //  Added {selection-text} field marker.
-        //  Added {sentence-furigana} field marker.
-        //  Added anki.duplicateScopeCheckAllModels.
-        //  Updated pronunciation templates.
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v13.handlebars');
         for (const profile of options.profiles) {
             profile.options.anki.duplicateScopeCheckAllModels = false;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added accessibility options.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion14(options) {
-        // Version 14 changes:
-        //  Added accessibility options.
         for (const profile of options.profiles) {
             profile.options.accessibility = {
                 forceGoogleDocsHtmlRendering: false
             };
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added general.sortFrequencyDictionary.
+     * - Added general.sortFrequencyDictionaryOrder.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion15(options) {
-        // Version 15 changes:
-        //  Added general.sortFrequencyDictionary.
-        //  Added general.sortFrequencyDictionaryOrder.
         for (const profile of options.profiles) {
             profile.options.general.sortFrequencyDictionary = null;
             profile.options.general.sortFrequencyDictionaryOrder = 'descending';
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added scanning.matchTypePrefix.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion16(options) {
-        // Version 16 changes:
-        //  Added scanning.matchTypePrefix.
         for (const profile of options.profiles) {
             profile.options.scanning.matchTypePrefix = false;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added vertical sentence punctuation to terminationCharacters.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion17(options) {
-        // Version 17 changes:
-        //  Added vertical sentence punctuation to terminationCharacters.
         const additions = ['︒', '︕', '︖', '︙'];
         for (const profile of options.profiles) {
             /** @type {import('settings').SentenceParsingTerminationCharacterOption[]} */
@@ -1071,19 +1036,17 @@ export class OptionsUtil {
                 });
             }
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - general.popupTheme's 'default' value changed to 'light'
+     * - general.popupOuterTheme's 'default' value changed to 'light'
+     * - general.popupOuterTheme's 'auto' value changed to 'site'
+     * - Added scanning.hidePopupOnCursorExit.
+     * - Added scanning.hidePopupOnCursorExitDelay.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion18(options) {
-        // Version 18 changes:
-        //  general.popupTheme's 'default' value changed to 'light'
-        //  general.popupOuterTheme's 'default' value changed to 'light'
-        //  general.popupOuterTheme's 'auto' value changed to 'site'
-        //  Added scanning.hidePopupOnCursorExit.
-        //  Added scanning.hidePopupOnCursorExitDelay.
         for (const profile of options.profiles) {
             const {general} = profile.options;
             if (general.popupTheme === 'default') {
@@ -1096,23 +1059,21 @@ export class OptionsUtil {
             profile.options.scanning.hidePopupOnCursorExit = false;
             profile.options.scanning.hidePopupOnCursorExitDelay = profile.options.scanning.hideDelay;
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added anki.noteGuiMode.
+     * - Added anki.apiKey.
+     * - Renamed scanning.inputs[].options.scanOnPenPress to scanOnPenMove.
+     * - Renamed scanning.inputs[].options.scanOnPenRelease to scanOnPenReleaseHover.
+     * - Added scanning.inputs[].options.scanOnTouchPress.
+     * - Added scanning.inputs[].options.scanOnTouchRelease.
+     * - Added scanning.inputs[].options.scanOnPenPress.
+     * - Added scanning.inputs[].options.scanOnPenRelease.
+     * - Added scanning.inputs[].options.preventPenScrolling.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion19(options) {
-        // Version 19 changes:
-        //  Added anki.noteGuiMode.
-        //  Added anki.apiKey.
-        //  Renamed scanning.inputs[].options.scanOnPenPress to scanOnPenMove.
-        //  Renamed scanning.inputs[].options.scanOnPenRelease to scanOnPenReleaseHover.
-        //  Added scanning.inputs[].options.scanOnTouchPress.
-        //  Added scanning.inputs[].options.scanOnTouchRelease.
-        //  Added scanning.inputs[].options.scanOnPenPress.
-        //  Added scanning.inputs[].options.scanOnPenRelease.
-        //  Added scanning.inputs[].options.preventPenScrolling.
         for (const profile of options.profiles) {
             profile.options.anki.noteGuiMode = 'browse';
             profile.options.anki.apiKey = '';
@@ -1126,18 +1087,16 @@ export class OptionsUtil {
                 input.options.preventPenScrolling = input.options.preventTouchScrolling;
             }
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionSync}
+     * - Added anki.downloadTimeout.
+     * - Added scanning.normalizeCssZoom.
+     * - Fixed general.popupTheme invalid default.
+     * - Fixed general.popupOuterTheme invalid default.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion20(options) {
-        // Version 20 changes:
-        //  Added anki.downloadTimeout.
-        //  Added scanning.normalizeCssZoom.
-        //  Fixed general.popupTheme invalid default.
-        //  Fixed general.popupOuterTheme invalid default.
         for (const profile of options.profiles) {
             profile.options.anki.downloadTimeout = 0;
             profile.options.scanning.normalizeCssZoom = true;
@@ -1149,11 +1108,12 @@ export class OptionsUtil {
                 general.popupOuterTheme = 'light';
             }
         }
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Converted Handlebars templates to new format.
+     * - Assigned flag to show users a warning about template changes.
+     * @type {import('options-util').UpdateFunction}
      */
     async _updateVersion21(options) {
         await this._applyAnkiFieldTemplatesPatch(options, '/data/templates/anki-field-templates-upgrade-v21.handlebars');
@@ -1170,15 +1130,13 @@ export class OptionsUtil {
             await this._createTab(chrome.runtime.getURL('/welcome.html'));
             chrome.storage.session.set({'openedWelcomePage': true});
         }
-
-        return options;
     }
 
     /**
-     * @type {import('options-util').ModernUpdateFunctionAsync}
+     * - Added translation.searchResolution.
+     * @type {import('options-util').UpdateFunction}
      */
     _updateVersion22(options) {
-        //  Added translation.searchResolution
         for (const {options: profileOptions} of options.profiles) {
             profileOptions.translation.searchResolution = 'letter';
         }
diff --git a/types/ext/options-util.d.ts b/types/ext/options-util.d.ts
index e03e4be2..7242dc22 100644
--- a/types/ext/options-util.d.ts
+++ b/types/ext/options-util.d.ts
@@ -23,13 +23,4 @@ export type IntermediateOptions = Core.SafeAny;
 
 export type LegacyUpdateFunction = (options: LegacyOptions) => void;
 
-export type ModernUpdateFunction = ModernUpdateFunctionSync | ModernUpdateFunctionAsync;
-
-export type ModernUpdateFunctionSync = (options: IntermediateOptions) => IntermediateOptions;
-
-export type ModernUpdateFunctionAsync = (options: IntermediateOptions) => Promise<IntermediateOptions>;
-
-export type ModernUpdate = {
-    async: boolean;
-    update: ModernUpdateFunction;
-};
+export type UpdateFunction = (options: IntermediateOptions) => void | Promise<void>;