refactor: code cosmetics and JSDoc comments

src/background/index.js

@@ -34,12 +34,14 @@ hookOptions((changes) => {
 });
 
 Object.assign(commands, {
+  /** @return {Promise<Object>} */
   async GetData() {
     const data = await getData();
     data.sync = sync.getStates();
     data.version = VM_VER;
     return data;
   },
+  /** @return {Promise<Object>} */
   async GetInjected(url, src) {
     const { id: tabId } = src.tab || {};
     if (src.frameId === 0) resetValueOpener(tabId);

src/background/utils/db.js

@@ -22,7 +22,7 @@ storage.script.onDump = (item) => {
 Object.assign(commands, {
   CheckPosition: sortScripts,
   CheckRemove: checkRemove,
-  /** @return {string | null} */
+  /** @return {?string} */
   CheckScript({ name, namespace }) {
     const script = getScript({ meta: { name, namespace } });
     return script && !script.config.removed
@@ -102,14 +102,14 @@ preInitialize.push(async () => {
   const idMap = {};
   const uriMap = {};
   Object.entries(data).forEach(([key, script]) => {
-    if (key.startsWith('scr:')) {
+    if (key.startsWith(storage.script.prefix)) {
       // {
       //   meta,
       //   custom,
       //   props: { id, position, uri },
       //   config: { enabled, shouldUpdate },
       // }
-      const id = getInt(key.slice(4));
+      const id = getInt(key.slice(storage.script.prefix.length));
       if (!id || idMap[id]) {
         // ID conflicts!
         // Should not happen, discard duplicates.
@@ -190,12 +190,12 @@ export async function sortScripts() {
   return changed;
 }
 
-/** @return {VMScript} */
+/** @return {?VMScript} */
 export function getScriptById(id) {
   return store.scriptMap[id];
 }
 
-/** @return {VMScript} */
+/** @return {?VMScript} */
 export function getScript({ id, uri, meta }) {
   let script;
   if (id) {
@@ -215,7 +215,7 @@ export function getScripts() {
 /**
  * @desc Load values for batch updates.
  * @param {number[]} ids
- * @return {Promise}
+ * @return {Promise<Object>}
  */
 export function getValueStoresByIds(ids) {
   return storage.value.getMulti(ids);
@@ -224,7 +224,7 @@ export function getValueStoresByIds(ids) {
 /**
  * @desc Dump values for batch updates.
  * @param {Object} valueDict { id1: value1, id2: value2, ... }
- * @return {Promise}
+ * @return {Promise<Object>}
  */
 export async function dumpValueStores(valueDict) {
   if (process.env.DEBUG) console.info('Update value stores', valueDict);
@@ -232,7 +232,7 @@ export async function dumpValueStores(valueDict) {
   return valueDict;
 }
 
-/** @return {Promise<Object|undefined>} */
+/** @return {Promise<?Object>} */
 export async function dumpValueStore(where, valueStore) {
   const id = where.id || getScript(where)?.props.id;
   return id && dumpValueStores({ [id]: valueStore });
@@ -247,7 +247,7 @@ const gmValues = [
 
 /**
  * @desc Get scripts to be injected to page with specific URL.
- * @return {Promise}
+ * @return {Promise<{ scripts, require, cache, values, code }>}
  */
 export async function getScriptsByURL(url) {
   const scripts = testBlacklist(url)
@@ -299,7 +299,7 @@ function getIconUrls() {
 
 /**
  * @desc Get data for dashboard.
- * @return {Promise}
+ * @return {Promise<{ scripts: VMScript[], cache: Object }>}
  */
 export async function getData() {
   return {
@@ -333,7 +333,7 @@ function getUUID(id) {
 /**
  * @param {VMScript} script
  * @param {string} code
- * @return {Promise<Array>} [VMScript, codeString]
+ * @return {Promise<VMScript[]>}
  */
 async function saveScript(script, code) {
   const config = script.config || {};
@@ -375,7 +375,7 @@ async function saveScript(script, code) {
   ]);
 }
 
-/** @return {Promise} */
+/** @return {Promise<void>} */
 export async function updateScriptInfo(id, data) {
   const script = store.scriptMap[id];
   if (!script) throw null;
@@ -385,7 +385,7 @@ export async function updateScriptInfo(id, data) {
   return sendCmd(CMD_SCRIPT_UPDATE, { where: { id }, update: script });
 }
 
-/** @return {Promise} */
+/** @return {Promise<{ isNew?, update, where }>} */
 export async function parseScript(src) {
   const meta = parseMeta(src.code);
   if (!meta.name) throw i18n('msgInvalidScript');
@@ -590,19 +590,19 @@ export async function vacuum() {
  * @property {string} description
  * @property {string} downloadURL
  * @property {string[]} exclude
- * @property {string[]} exclude-match
+ * @property {string[]} excludeMatch
  * @property {string[]} grant
  * @property {string} homepageURL
  * @property {string} icon
  * @property {string[]} include
- * @property {'auto' | 'page' | 'content'} inject-into
+ * @property {'auto' | 'page' | 'content'} injectInto
  * @property {string[]} match
  * @property {string} namespace
  * @property {string} name
  * @property {boolean} noframes
  * @property {string[]} require
  * @property {Object} resource
- * @property {VMScriptRunAt} run-at
+ * @property {VMScriptRunAt} runAt
  * @property {string} supportURL
  * @property {string} version
  */

src/background/utils/notifications.js

@@ -4,6 +4,7 @@ import { commands } from './message';
 const openers = {};
 
 Object.assign(commands, {
+  /** @return {Promise<string>} */
   async Notification(data, src) {
     const srcTab = src.tab || {};
     const notificationId = await browser.notifications.create({

src/background/utils/options.js

@@ -7,12 +7,15 @@ import { preInitialize } from './init';
 import { commands } from './message';
 
 Object.assign(commands, {
+  /** @return {Object} */
   GetAllOptions() {
     return commands.GetOptions(defaults);
   },
+  /** @return {Object} */
   GetOptions(data) {
     return objectMap(data, key => getOption(key));
   },
+  /** @return {void} */
   SetOptions(data) {
     ensureArray(data).forEach(item => setOption(item.key, item.value));
   },

src/background/utils/requests.js

@@ -14,6 +14,7 @@ const verify = {};
 
 Object.assign(commands, {
   ConfirmInstall: confirmInstall,
+  /** @return {string} */
   GetRequestId(eventsToNotify = []) {
     eventsToNotify.push('loadend');
     const id = getUniqId();
@@ -24,12 +25,14 @@ Object.assign(commands, {
     };
     return id;
   },
+  /** @return {void} */
   HttpRequest(details, src) {
     const { tab, frameId } = src;
     httpRequest(details, src, res => (
       sendTabCmd(tab.id, 'HttpRequested', res, { frameId })
     ));
   },
+  /** @return {void} */
   AbortRequest(id) {
     const req = requests[id];
     if (req) {

src/background/utils/script.js

@@ -6,17 +6,20 @@ import { getOption } from './options';
 import cache from './cache';
 
 Object.assign(commands, {
+  /** @return {string} */
   CacheNewScript(data) {
     const id = getUniqId();
     cache.put(`new-${id}`, newScript(data));
     return id;
   },
+  /** @return {Promise<Array>} */
   InjectScript(code, src) {
     return browser.tabs.executeScript(src.tab.id, {
       code,
       runAt: 'document_start',
     });
   },
+  /** @return {VMScript} */
   NewScript(id) {
     return id && cache.get(`new-${id}`) || newScript();
   },

src/background/utils/tabs.js

@@ -5,6 +5,7 @@ import { commands } from './message';
 const openers = {};
 
 Object.assign(commands, {
+  /** @return {Promise<{ id: number }>} */
   async TabOpen({ url, active, insert = true }, src) {
     // src.tab may be absent when invoked from popup (e.g. edit/create buttons)
     const { id: openerTabId, index, windowId } = src?.tab || await getActiveTab() || {};
@@ -21,6 +22,7 @@ Object.assign(commands, {
     openers[id] = openerTabId;
     return { id };
   },
+  /** @return {void} */
   TabClose({ id } = {}, src) {
     const tabId = id || src?.tab?.id;
     if (tabId >= 0) browser.tabs.remove(tabId);

src/background/utils/update.js

@@ -8,10 +8,12 @@ import { getOption, setOption } from './options';
 import { commands, notify } from './message';
 
 Object.assign(commands, {
+  /** @return {Promise<true?>} */
   CheckUpdate(id) {
     return checkUpdate(getScriptById(id));
   },
-  CheckUpdateAll() {
+  /** @return {Promise<boolean>} */
+  async CheckUpdateAll() {
     setOption('lastUpdate', Date.now());
     const toUpdate = getScripts().filter(item => item.config.shouldUpdate);
     const results = await Promise.all(toUpdate.map(checkUpdate));

src/background/utils/values.js

@@ -8,15 +8,18 @@ let cache;
 let timer;
 
 Object.assign(commands, {
+  /** @return {Promise<Object>} */
   async GetValueStore(id) {
     const stores = await getValueStoresByIds([id]);
     return stores[id] || {};
   },
+  /** @return {Promise<void>} */
   async SetValueStore({ where, valueStore }) {
     // Value store will be replaced soon.
     const store = await dumpValueStore(where, valueStore);
-    return broadcastUpdates(store);
+    broadcastUpdates(store);
   },
+  /** @return {Promise<void>} */
   UpdateValue({ id, update }) {
     // Value will be updated to store later.
     updateLater();