From ab847b124d418b13037b59f446b288ff435e66a4 Mon Sep 17 00:00:00 2001
From: toasted-nutbread <toasted-nutbread@users.noreply.github.com>
Date: Thu, 21 Dec 2023 09:46:50 -0500
Subject: API maps (#413)

* Add API map type descriptions

* Remove unused ApiMapInitLax

* Add createApiMap function

* Add extendApiMap

* Support promises

* Update Offscreen to use API map

* Add ApiNames<> template

* Add getApiMapHandler

* Use getApiMapHandler in offscreen
---
 types/ext/api-map.d.ts   |  55 ++++++++++++++++++++++
 types/ext/offscreen.d.ts | 116 +++++++++++++++++++++++++++--------------------
 2 files changed, 121 insertions(+), 50 deletions(-)
 create mode 100644 types/ext/api-map.d.ts

(limited to 'types')

diff --git a/types/ext/api-map.d.ts b/types/ext/api-map.d.ts
new file mode 100644
index 00000000..eebc886a
--- /dev/null
+++ b/types/ext/api-map.d.ts
@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2023  Yomitan Authors
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+type ApiSurface = {
+    [name: string]: ApiItem;
+};
+
+type ApiItem = {
+    params: void | {[name: string]: unknown};
+    return: unknown;
+};
+
+export type ApiHandler<TApiItem extends ApiItem> = (params: TApiItem['params']) => TApiItem['return'] | Promise<TApiItem['return']>;
+
+type ApiHandlerSurface<TApiSurface extends ApiSurface> = {[name in ApiNames<TApiSurface>]: ApiHandler<TApiSurface[name]>};
+
+export type ApiHandlerAny<TApiSurface extends ApiSurface> = ApiHandlerSurface<TApiSurface>[ApiNames<TApiSurface>];
+
+export type ApiNames<TApiSurface extends ApiSurface> = keyof TApiSurface;
+
+export type ApiParams<TApiSurface extends ApiSurface, TName extends ApiNames<TApiSurface>> = TApiSurface[TName]['params'];
+
+export type ApiReturn<TApiSurface extends ApiSurface, TName extends ApiNames<TApiSurface>> = TApiSurface[TName]['return'];
+
+export type ApiMap<TApiSurface extends ApiSurface> = Map<ApiNames<TApiSurface>, ApiHandlerAny<TApiSurface>>;
+
+export type ApiMapInit<TApiSurface extends ApiSurface> = ApiMapInitItemAny<TApiSurface>[];
+
+export type ApiMapInitLax<TApiSurface extends ApiSurface> = ApiMapInitLaxItem<TApiSurface>[];
+
+export type ApiMapInitLaxItem<TApiSurface extends ApiSurface> = [
+    name: ApiNames<TApiSurface>,
+    handler: ApiHandlerAny<TApiSurface>,
+];
+
+type ApiMapInitItem<TApiSurface extends ApiSurface, TName extends ApiNames<TApiSurface>> = [
+    name: TName,
+    handler: ApiHandler<TApiSurface[TName]>,
+];
+
+type ApiMapInitItemAny<TApiSurface extends ApiSurface> = {[key in ApiNames<TApiSurface>]: ApiMapInitItem<TApiSurface, key>}[ApiNames<TApiSurface>];
diff --git a/types/ext/offscreen.d.ts b/types/ext/offscreen.d.ts
index c741ac99..451f5f9e 100644
--- a/types/ext/offscreen.d.ts
+++ b/types/ext/offscreen.d.ts
@@ -15,7 +15,6 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import type * as Core from './core';
 import type * as Deinflector from './deinflector';
 import type * as Dictionary from './dictionary';
 import type * as DictionaryDatabase from './dictionary-database';
@@ -23,64 +22,84 @@ import type * as DictionaryImporter from './dictionary-importer';
 import type * as Environment from './environment';
 import type * as Translation from './translation';
 import type * as Translator from './translator';
+import type {ApiMap, ApiMapInit, ApiHandler, ApiParams, ApiReturn} from './api-map';
 
-export type Message<T extends MessageType> = (
-    MessageDetailsMap[T] extends undefined ?
-        {action: T} :
-        {action: T, params: MessageDetailsMap[T]}
-);
-
-export type MessageReturn<T extends MessageType> = MessageReturnMap[T];
-
-type MessageDetailsMap = {
-    databasePrepareOffscreen: undefined;
-    getDictionaryInfoOffscreen: undefined;
-    databasePurgeOffscreen: undefined;
+type OffscreenApiSurface = {
+    databasePrepareOffscreen: {
+        params: void;
+        return: void;
+    };
+    getDictionaryInfoOffscreen: {
+        params: void;
+        return: DictionaryImporter.Summary[];
+    };
+    databasePurgeOffscreen: {
+        params: void;
+        return: boolean;
+    };
     databaseGetMediaOffscreen: {
-        targets: DictionaryDatabase.MediaRequest[];
+        params: {
+            targets: DictionaryDatabase.MediaRequest[];
+        };
+        return: DictionaryDatabase.Media<string>[];
     };
     translatorPrepareOffscreen: {
-        deinflectionReasons: Deinflector.ReasonsRaw;
+        params: {
+            deinflectionReasons: Deinflector.ReasonsRaw;
+        };
+        return: void;
     };
     findKanjiOffscreen: {
-        text: string;
-        options: FindKanjiOptionsOffscreen;
+        params: {
+            text: string;
+            options: FindKanjiOptionsOffscreen;
+        };
+        return: Dictionary.KanjiDictionaryEntry[];
     };
     findTermsOffscreen: {
-        mode: Translator.FindTermsMode;
-        text: string;
-        options: FindTermsOptionsOffscreen;
+        params: {
+            mode: Translator.FindTermsMode;
+            text: string;
+            options: FindTermsOptionsOffscreen;
+        };
+        return: Translator.FindTermsResult;
     };
     getTermFrequenciesOffscreen: {
-        termReadingList: Translator.TermReadingList;
-        dictionaries: string[];
+        params: {
+            termReadingList: Translator.TermReadingList;
+            dictionaries: string[];
+        };
+        return: Translator.TermFrequencySimple[];
+    };
+    clearDatabaseCachesOffscreen: {
+        params: void;
+        return: void;
     };
-    clearDatabaseCachesOffscreen: undefined;
     clipboardSetBrowserOffscreen: {
-        value: Environment.Browser | null;
+        params: {
+            value: Environment.Browser | null;
+        };
+        return: void;
     };
     clipboardGetTextOffscreen: {
-        useRichText: boolean;
+        params: {
+            useRichText: boolean;
+        };
+        return: string;
+    };
+    clipboardGetImageOffscreen: {
+        params: void;
+        return: string | null;
     };
-    clipboardGetImageOffscreen: undefined;
 };
 
-type MessageReturnMap = {
-    databasePrepareOffscreen: void;
-    getDictionaryInfoOffscreen: DictionaryImporter.Summary[];
-    databasePurgeOffscreen: boolean;
-    databaseGetMediaOffscreen: DictionaryDatabase.Media<string>[];
-    translatorPrepareOffscreen: void;
-    findKanjiOffscreen: Dictionary.KanjiDictionaryEntry[];
-    findTermsOffscreen: Translator.FindTermsResult;
-    getTermFrequenciesOffscreen: Translator.TermFrequencySimple[];
-    clearDatabaseCachesOffscreen: void;
-    clipboardSetBrowserOffscreen: void;
-    clipboardGetTextOffscreen: string;
-    clipboardGetImageOffscreen: string | null;
-};
+export type Message<TName extends MessageType> = (
+    OffscreenApiParams<TName> extends void ?
+        {action: TName} :
+        {action: TName, params: OffscreenApiParams<TName>}
+);
 
-export type MessageType = keyof MessageDetailsMap;
+export type MessageType = keyof OffscreenApiSurface;
 
 export type FindKanjiOptionsOffscreen = Omit<Translation.FindKanjiOptions, 'enabledDictionaryMap'> & {
     enabledDictionaryMap: [
@@ -103,15 +122,12 @@ export type FindTermsTextReplacementOffscreen = Omit<Translation.FindTermsTextRe
     pattern: string;
 };
 
-export type MessageHandler<
-    TMessage extends MessageType,
-    TIsAsync extends boolean,
-> = (
-    details: MessageDetailsMap[TMessage],
-) => (TIsAsync extends true ? Promise<MessageReturn<TMessage>> : MessageReturn<TMessage>);
+export type OffscreenApiMap = ApiMap<OffscreenApiSurface>;
+
+export type OffscreenApiMapInit = ApiMapInit<OffscreenApiSurface>;
 
-export type MessageHandlerMap = Map<MessageType, Core.MessageHandler>;
+export type OffscreenApiHandler<TName extends keyof OffscreenApiSurface> = ApiHandler<OffscreenApiSurface[TName]>;
 
-export type MessageHandlerMapInit = MessageHandlerMapInitItem[];
+export type OffscreenApiParams<TName extends keyof OffscreenApiSurface> = ApiParams<OffscreenApiSurface, TName>;
 
-export type MessageHandlerMapInitItem = [messageType: MessageType, handler: Core.MessageHandler];
+export type OffscreenApiReturn<TName extends keyof OffscreenApiSurface> = ApiReturn<OffscreenApiSurface, TName>;
-- 
cgit v1.2.3