Merge pull request #339 from toasted-nutbread/type-annotations

Type annotations

1 files changed, 229 insertions, 26 deletions

diff --git a/ext/js/language/dictionary-database.js b/ext/js/language/dictionary-database.js
index da365da7..c47e1e90 100644
--- a/ext/js/language/dictionary-database.js
+++ b/ext/js/language/dictionary-database.js
@@ -21,29 +21,45 @@ import {Database} from '../data/database.js';
 
 export class DictionaryDatabase {
     constructor() {
+        /** @type {Database<import('dictionary-database').ObjectStoreName>} */
         this._db = new Database();
+        /** @type {string} */
         this._dbName = 'dict';
-        this._schemas = new Map();
+        /** @type {import('dictionary-database').CreateQuery<string>} */
         this._createOnlyQuery1 = (item) => IDBKeyRange.only(item);
+        /** @type {import('dictionary-database').CreateQuery<import('dictionary-database').DictionaryAndQueryRequest>} */
         this._createOnlyQuery2 = (item) => IDBKeyRange.only(item.query);
+        /** @type {import('dictionary-database').CreateQuery<import('dictionary-database').TermExactRequest>} */
         this._createOnlyQuery3 = (item) => IDBKeyRange.only(item.term);
+        /** @type {import('dictionary-database').CreateQuery<import('dictionary-database').MediaRequest>} */
         this._createOnlyQuery4 = (item) => IDBKeyRange.only(item.path);
+        /** @type {import('dictionary-database').CreateQuery<string>} */
         this._createBoundQuery1 = (item) => IDBKeyRange.bound(item, `${item}\uffff`, false, false);
+        /** @type {import('dictionary-database').CreateQuery<string>} */
         this._createBoundQuery2 = (item) => { item = stringReverse(item); return IDBKeyRange.bound(item, `${item}\uffff`, false, false); };
-        this._createTermBind1 = this._createTerm.bind(this, 'term', 'exact');
-        this._createTermBind2 = this._createTerm.bind(this, 'sequence', 'exact');
+        /** @type {import('dictionary-database').CreateResult<import('dictionary-database').TermExactRequest, import('dictionary-database').DatabaseTermEntryWithId, import('dictionary-database').TermEntry>} */
+        this._createTermBind1 = this._createTermExact.bind(this);
+        /** @type {import('dictionary-database').CreateResult<import('dictionary-database').DictionaryAndQueryRequest, import('dictionary-database').DatabaseTermEntryWithId, import('dictionary-database').TermEntry>} */
+        this._createTermBind2 = this._createTermSequenceExact.bind(this);
+        /** @type {import('dictionary-database').CreateResult<string, import('dictionary-database').DatabaseTermMeta, import('dictionary-database').TermMeta>} */
         this._createTermMetaBind = this._createTermMeta.bind(this);
+        /** @type {import('dictionary-database').CreateResult<string, import('dictionary-database').DatabaseKanjiEntry, import('dictionary-database').KanjiEntry>} */
         this._createKanjiBind = this._createKanji.bind(this);
+        /** @type {import('dictionary-database').CreateResult<string, import('dictionary-database').DatabaseKanjiMeta, import('dictionary-database').KanjiMeta>} */
         this._createKanjiMetaBind = this._createKanjiMeta.bind(this);
+        /** @type {import('dictionary-database').CreateResult<import('dictionary-database').MediaRequest, import('dictionary-database').MediaDataArrayBufferContent, import('dictionary-database').Media>} */
         this._createMediaBind = this._createMedia.bind(this);
     }
 
+    /** */
     async prepare() {
         await this._db.open(
             this._dbName,
             60,
-            [
-                {
+            /** @type {import('database').StructureDefinition<import('dictionary-database').ObjectStoreName>[]} */
+            ([
+                /** @type {import('database').StructureDefinition<import('dictionary-database').ObjectStoreName>} */
+                ({
                     version: 20,
                     stores: {
                         terms: {
@@ -63,7 +79,7 @@ export class DictionaryDatabase {
                             indices: ['title', 'version']
                         }
                     }
-                },
+                }),
                 {
                     version: 30,
                     stores: {
@@ -108,18 +124,25 @@ export class DictionaryDatabase {
                         }
                     }
                 }
-            ]
+            ])
         );
     }
 
+    /** */
     async close() {
         this._db.close();
     }
 
+    /**
+     * @returns {boolean}
+     */
     isPrepared() {
         return this._db.isOpen();
     }
 
+    /**
+     * @returns {Promise<boolean>}
+     */
     async purge() {
         if (this._db.isOpening()) {
             throw new Error('Cannot purge database while opening');
@@ -138,14 +161,13 @@ export class DictionaryDatabase {
         return result;
     }
 
+    /**
+     * @param {string} dictionaryName
+     * @param {number} progressRate
+     * @param {import('dictionary-database').DeleteDictionaryProgressCallback} onProgress
+     */
     async deleteDictionary(dictionaryName, progressRate, onProgress) {
-        if (typeof progressRate !== 'number') {
-            progressRate = 1;
-        }
-        if (typeof onProgress !== 'function') {
-            onProgress = () => {};
-        }
-
+        /** @type {[objectStoreName: import('dictionary-database').ObjectStoreName, key: string][][]} */
         const targetGroups = [
             [
                 ['kanji', 'dictionary'],
@@ -165,6 +187,7 @@ export class DictionaryDatabase {
             storeCount += targets.length;
         }
 
+        /** @type {import('dictionary-database').DeleteDictionaryProgressData} */
         const progressData = {
             count: 0,
             processed: 0,
@@ -172,6 +195,10 @@ export class DictionaryDatabase {
             storesProcesed: 0
         };
 
+        /**
+         * @param {IDBValidKey[]} keys
+         * @returns {IDBValidKey[]}
+         */
         const filterKeys = (keys) => {
             ++progressData.storesProcesed;
             progressData.count += keys.length;
@@ -197,8 +224,15 @@ export class DictionaryDatabase {
         }
     }
 
+    /**
+     * @param {string[]} termList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @param {import('dictionary-database').MatchType} matchType
+     * @returns {Promise<import('dictionary-database').TermEntry[]>}
+     */
     findTermsBulk(termList, dictionaries, matchType) {
         const visited = new Set();
+        /** @type {import('dictionary-database').FindPredicate<string, import('dictionary-database').DatabaseTermEntryWithId>} */
         const predicate = (row) => {
             if (!dictionaries.has(row.dictionary)) { return false; }
             const {id} = row;
@@ -224,54 +258,106 @@ export class DictionaryDatabase {
         return this._findMultiBulk('terms', indexNames, termList, createQuery, predicate, createResult);
     }
 
+    /**
+     * @param {import('dictionary-database').TermExactRequest[]} termList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @returns {Promise<import('dictionary-database').TermEntry[]>}
+     */
     findTermsExactBulk(termList, dictionaries) {
+        /** @type {import('dictionary-database').FindPredicate<import('dictionary-database').TermExactRequest, import('dictionary-database').DatabaseTermEntry>} */
         const predicate = (row, item) => (row.reading === item.reading && dictionaries.has(row.dictionary));
         return this._findMultiBulk('terms', ['expression'], termList, this._createOnlyQuery3, predicate, this._createTermBind1);
     }
 
+    /**
+     * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
+     * @returns {Promise<import('dictionary-database').TermEntry[]>}
+     */
     findTermsBySequenceBulk(items) {
+        /** @type {import('dictionary-database').FindPredicate<import('dictionary-database').DictionaryAndQueryRequest, import('dictionary-database').DatabaseTermEntry>} */
         const predicate = (row, item) => (row.dictionary === item.dictionary);
         return this._findMultiBulk('terms', ['sequence'], items, this._createOnlyQuery2, predicate, this._createTermBind2);
     }
 
+    /**
+     * @param {string[]} termList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @returns {Promise<import('dictionary-database').TermMeta[]>}
+     */
     findTermMetaBulk(termList, dictionaries) {
+        /** @type {import('dictionary-database').FindPredicate<string, import('dictionary-database').DatabaseTermMeta>} */
         const predicate = (row) => dictionaries.has(row.dictionary);
         return this._findMultiBulk('termMeta', ['expression'], termList, this._createOnlyQuery1, predicate, this._createTermMetaBind);
     }
 
+    /**
+     * @param {string[]} kanjiList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @returns {Promise<import('dictionary-database').KanjiEntry[]>}
+     */
     findKanjiBulk(kanjiList, dictionaries) {
+        /** @type {import('dictionary-database').FindPredicate<string, import('dictionary-database').DatabaseKanjiEntry>} */
         const predicate = (row) => dictionaries.has(row.dictionary);
         return this._findMultiBulk('kanji', ['character'], kanjiList, this._createOnlyQuery1, predicate, this._createKanjiBind);
     }
 
+    /**
+     * @param {string[]} kanjiList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @returns {Promise<import('dictionary-database').KanjiMeta[]>}
+     */
     findKanjiMetaBulk(kanjiList, dictionaries) {
+        /** @type {import('dictionary-database').FindPredicate<string, import('dictionary-database').DatabaseKanjiMeta>} */
         const predicate = (row) => dictionaries.has(row.dictionary);
         return this._findMultiBulk('kanjiMeta', ['character'], kanjiList, this._createOnlyQuery1, predicate, this._createKanjiMetaBind);
     }
 
+    /**
+     * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
+     * @returns {Promise<(import('dictionary-database').Tag|undefined)[]>}
+     */
     findTagMetaBulk(items) {
+        /** @type {import('dictionary-database').FindPredicate<import('dictionary-database').DictionaryAndQueryRequest, import('dictionary-database').Tag>} */
         const predicate = (row, item) => (row.dictionary === item.dictionary);
         return this._findFirstBulk('tagMeta', 'name', items, this._createOnlyQuery2, predicate);
     }
 
-    findTagForTitle(name, title) {
+    /**
+     * @param {string} name
+     * @param {string} dictionary
+     * @returns {Promise<?import('dictionary-database').Tag>}
+     */
+    findTagForTitle(name, dictionary) {
         const query = IDBKeyRange.only(name);
-        return this._db.find('tagMeta', 'name', query, (row) => (row.dictionary === title), null, null);
+        return this._db.find('tagMeta', 'name', query, (row) => (/** @type {import('dictionary-database').Tag} */ (row).dictionary === dictionary), null, null);
     }
 
+    /**
+     * @param {import('dictionary-database').MediaRequest[]} items
+     * @returns {Promise<import('dictionary-database').Media[]>}
+     */
     getMedia(items) {
+        /** @type {import('dictionary-database').FindPredicate<import('dictionary-database').MediaRequest, import('dictionary-database').MediaDataArrayBufferContent>} */
         const predicate = (row, item) => (row.dictionary === item.dictionary);
         return this._findMultiBulk('media', ['path'], items, this._createOnlyQuery4, predicate, this._createMediaBind);
     }
 
+    /**
+     * @returns {Promise<import('dictionary-importer').Summary[]>}
+     */
     getDictionaryInfo() {
         return new Promise((resolve, reject) => {
             const transaction = this._db.transaction(['dictionaries'], 'readonly');
             const objectStore = transaction.objectStore('dictionaries');
-            this._db.getAll(objectStore, null, resolve, reject);
+            this._db.getAll(objectStore, null, resolve, reject, null);
         });
     }
 
+    /**
+     * @param {string[]} dictionaryNames
+     * @param {boolean} getTotal
+     * @returns {Promise<import('dictionary-database').DictionaryCounts>}
+     */
     getDictionaryCounts(dictionaryNames, getTotal) {
         return new Promise((resolve, reject) => {
             const targets = [
@@ -290,10 +376,11 @@ export class DictionaryDatabase {
                 return {objectStore, index};
             });
 
+            /** @type {import('database').CountTarget[]} */
             const countTargets = [];
             if (getTotal) {
                 for (const {objectStore} of databaseTargets) {
-                    countTargets.push([objectStore, null]);
+                    countTargets.push([objectStore, void 0]);
                 }
             }
             for (const dictionaryName of dictionaryNames) {
@@ -303,18 +390,23 @@ export class DictionaryDatabase {
                 }
             }
 
+            /**
+             * @param {number[]} results
+             */
             const onCountComplete = (results) => {
                 const resultCount = results.length;
                 const targetCount = targets.length;
+                /** @type {import('dictionary-database').DictionaryCountGroup[]} */
                 const counts = [];
                 for (let i = 0; i < resultCount; i += targetCount) {
+                    /** @type {import('dictionary-database').DictionaryCountGroup} */
                     const countGroup = {};
                     for (let j = 0; j < targetCount; ++j) {
                         countGroup[targets[j][0]] = results[i + j];
                     }
                     counts.push(countGroup);
                 }
-                const total = getTotal ? counts.shift() : null;
+                const total = getTotal ? /** @type {import('dictionary-database').DictionaryCountGroup} */ (counts.shift()) : null;
                 resolve({total, counts});
             };
 
@@ -322,22 +414,47 @@ export class DictionaryDatabase {
         });
     }
 
+    /**
+     * @param {string} title
+     * @returns {Promise<boolean>}
+     */
     async dictionaryExists(title) {
         const query = IDBKeyRange.only(title);
         const result = await this._db.find('dictionaries', 'title', query, null, null, void 0);
         return typeof result !== 'undefined';
     }
 
+    /**
+     * @template {import('dictionary-database').ObjectStoreName} T
+     * @param {T} objectStoreName
+     * @param {import('dictionary-database').ObjectStoreData<T>[]} items
+     * @param {number} start
+     * @param {number} count
+     * @returns {Promise<void>}
+     */
     bulkAdd(objectStoreName, items, start, count) {
         return this._db.bulkAdd(objectStoreName, items, start, count);
     }
 
     // Private
 
+    /**
+     * @template [TRow=unknown]
+     * @template [TItem=unknown]
+     * @template [TResult=unknown]
+     * @param {import('dictionary-database').ObjectStoreName} objectStoreName
+     * @param {string[]} indexNames
+     * @param {TItem[]} items
+     * @param {import('dictionary-database').CreateQuery<TItem>} createQuery
+     * @param {import('dictionary-database').FindPredicate<TItem, TRow>} predicate
+     * @param {import('dictionary-database').CreateResult<TItem, TRow, TResult>} createResult
+     * @returns {Promise<TResult[]>}
+     */
     _findMultiBulk(objectStoreName, indexNames, items, createQuery, predicate, createResult) {
         return new Promise((resolve, reject) => {
             const itemCount = items.length;
             const indexCount = indexNames.length;
+            /** @type {TResult[]} */
             const results = [];
             if (itemCount === 0 || indexCount === 0) {
                 resolve(results);
@@ -352,6 +469,10 @@ export class DictionaryDatabase {
             }
             let completeCount = 0;
             const requiredCompleteCount = itemCount * indexCount;
+            /**
+             * @param {TRow[]} rows
+             * @param {import('dictionary-database').FindMultiBulkData<TItem>} data
+             */
             const onGetAll = (rows, data) => {
                 for (const row of rows) {
                     if (predicate(row, data.item)) {
@@ -366,15 +487,28 @@ export class DictionaryDatabase {
                 const item = items[i];
                 const query = createQuery(item);
                 for (let j = 0; j < indexCount; ++j) {
-                    this._db.getAll(indexList[j], query, onGetAll, reject, {item, itemIndex: i, indexIndex: j});
+                    /** @type {import('dictionary-database').FindMultiBulkData<TItem>} */
+                    const data = {item, itemIndex: i, indexIndex: j};
+                    this._db.getAll(indexList[j], query, onGetAll, reject, data);
                 }
             }
         });
     }
 
+    /**
+     * @template [TRow=unknown]
+     * @template [TItem=unknown]
+     * @param {import('dictionary-database').ObjectStoreName} objectStoreName
+     * @param {string} indexName
+     * @param {TItem[]} items
+     * @param {import('dictionary-database').CreateQuery<TItem>} createQuery
+     * @param {import('dictionary-database').FindPredicate<TItem, TRow>} predicate
+     * @returns {Promise<(TRow|undefined)[]>}
+     */
     _findFirstBulk(objectStoreName, indexName, items, createQuery, predicate) {
         return new Promise((resolve, reject) => {
             const itemCount = items.length;
+            /** @type {(TRow|undefined)[]} */
             const results = new Array(itemCount);
             if (itemCount === 0) {
                 resolve(results);
@@ -385,6 +519,10 @@ export class DictionaryDatabase {
             const objectStore = transaction.objectStore(objectStoreName);
             const index = objectStore.index(indexName);
             let completeCount = 0;
+            /**
+             * @param {TRow|undefined} row
+             * @param {number} itemIndex
+             */
             const onFind = (row, itemIndex) => {
                 results[itemIndex] = row;
                 if (++completeCount >= itemCount) {
@@ -399,16 +537,47 @@ export class DictionaryDatabase {
         });
     }
 
+    /**
+     * @param {import('dictionary-database').MatchType} matchType
+     * @param {import('dictionary-database').DatabaseTermEntryWithId} row
+     * @param {import('dictionary-database').FindMultiBulkData<string>} data
+     * @returns {import('dictionary-database').TermEntry}
+     */
     _createTermGeneric(matchType, row, data) {
         const matchSourceIsTerm = (data.indexIndex === 0);
         const matchSource = (matchSourceIsTerm ? 'term' : 'reading');
         if ((matchSourceIsTerm ? row.expression : row.reading) === data.item) {
             matchType = 'exact';
         }
-        return this._createTerm(matchSource, matchType, row, data);
+        return this._createTerm(matchSource, matchType, row, data.itemIndex);
+    }
+
+    /**
+     * @param {import('dictionary-database').DatabaseTermEntryWithId} row
+     * @param {import('dictionary-database').FindMultiBulkData<import('dictionary-database').TermExactRequest>} data
+     * @returns {import('dictionary-database').TermEntry}
+     */
+    _createTermExact(row, data) {
+        return this._createTerm('term', 'exact', row, data.itemIndex);
     }
 
-    _createTerm(matchSource, matchType, row, {itemIndex: index}) {
+    /**
+     * @param {import('dictionary-database').DatabaseTermEntryWithId} row
+     * @param {import('dictionary-database').FindMultiBulkData<import('dictionary-database').DictionaryAndQueryRequest>} data
+     * @returns {import('dictionary-database').TermEntry}
+     */
+    _createTermSequenceExact(row, data) {
+        return this._createTerm('sequence', 'exact', row, data.itemIndex);
+    }
+
+    /**
+     * @param {import('dictionary-database').MatchSource} matchSource
+     * @param {import('dictionary-database').MatchType} matchType
+     * @param {import('dictionary-database').DatabaseTermEntryWithId} row
+     * @param {number} index
+     * @returns {import('dictionary-database').TermEntry}
+     */
+    _createTerm(matchSource, matchType, row, index) {
         const {sequence} = row;
         return {
             index,
@@ -427,7 +596,13 @@ export class DictionaryDatabase {
         };
     }
 
+    /**
+     * @param {import('dictionary-database').DatabaseKanjiEntry} row
+     * @param {import('dictionary-database').FindMultiBulkData<string>} data
+     * @returns {import('dictionary-database').KanjiEntry}
+     */
     _createKanji(row, {itemIndex: index}) {
+        const {stats} = row;
         return {
             index,
             character: row.character,
@@ -435,23 +610,51 @@ export class DictionaryDatabase {
             kunyomi: this._splitField(row.kunyomi),
             tags: this._splitField(row.tags),
             definitions: row.meanings,
-            stats: row.stats,
+            stats: typeof stats === 'object' && stats !== null ? stats : {},
             dictionary: row.dictionary
         };
     }
 
+    /**
+     * @param {import('dictionary-database').DatabaseTermMeta} row
+     * @param {import('dictionary-database').FindMultiBulkData<string>} data
+     * @returns {import('dictionary-database').TermMeta}
+     * @throws {Error}
+     */
     _createTermMeta({expression: term, mode, data, dictionary}, {itemIndex: index}) {
-        return {term, mode, data, dictionary, index};
+        switch (mode) {
+            case 'freq':
+                return {index, term, mode, data, dictionary};
+            case 'pitch':
+                return {index, term, mode, data, dictionary};
+            default:
+                throw new Error(`Unknown mode: ${mode}`);
+        }
     }
 
+    /**
+     * @param {import('dictionary-database').DatabaseKanjiMeta} row
+     * @param {import('dictionary-database').FindMultiBulkData<string>} data
+     * @returns {import('dictionary-database').KanjiMeta}
+     */
     _createKanjiMeta({character, mode, data, dictionary}, {itemIndex: index}) {
-        return {character, mode, data, dictionary, index};
+        return {index, character, mode, data, dictionary};
     }
 
+    /**
+     * @param {import('dictionary-database').MediaDataArrayBufferContent} row
+     * @param {import('dictionary-database').FindMultiBulkData<import('dictionary-database').MediaRequest>} data
+     * @returns {import('dictionary-database').Media}
+     */
     _createMedia(row, {itemIndex: index}) {
-        return Object.assign({}, row, {index});
+        const {dictionary, path, mediaType, width, height, content} = row;
+        return {index, dictionary, path, mediaType, width, height, content};
     }
 
+    /**
+     * @param {unknown} field
+     * @returns {string[]}
+     */
     _splitField(field) {
         return typeof field === 'string' && field.length > 0 ? field.split(' ') : [];
     }