onedeuxtriseigo.nullpo.dev
Pop-up dictionary browser extension for language learning. Successor to Yomichan. (PERSONAL FORK)
1/*
2 * Copyright (C) 2023-2025 Yomitan Authors
3 *
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <https://www.gnu.org/licenses/>.
16 */
17
18/**
19 * This type describes the structure of an API surface.
20 * It is effectively just an object containing a list of items which describe a basic API functionality.
21 */
22type ApiSurface = {
23 [name: string]: ApiDescriptor;
24};
25
26/**
27 * This type describes the structure of a single API function.
28 */
29type ApiDescriptor = {
30 /** The parameters for the function. If there are no parameters, `void` should be used. */
31 params: void | {[name: string]: unknown};
32 /** The return type for the function. */
33 return: unknown;
34};
35
36/**
37 * This type represents a mapping of an entire API surface to its handlers.
38 */
39type ApiHandlerSurface<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams> = {
40 [name in ApiNames<TSurface>]: ApiHandler<TSurface[name], TExtraParams>;
41};
42
43/**
44 * This type represents a single API map initializer.
45 * Type safety is enforced by ensuring that the name and handler signature are valid.
46 */
47type ApiMapInitItem<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams, TName extends ApiNames<TSurface>> = [
48 name: TName,
49 handler: ApiHandler<TSurface[TName], TExtraParams>,
50];
51
52/**
53 * This type represents a union of all API map initializers for a given surface.
54 */
55type ApiMapInitItemAny<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams> = {[key in ApiNames<TSurface>]: ApiMapInitItem<TSurface, TExtraParams, key>}[ApiNames<TSurface>];
56
57/** Base type for extra params, which is just a generic array. */
58type ApiTExtraParams = unknown[];
59
60/** Default type for extra params, which is an empty array. */
61type ApiExtraParamsDefault = [];
62
63/** Type alias for the params member of a descriptor. */
64export type ApiParams<TDescriptor extends ApiDescriptor> = TDescriptor['params'];
65
66/** Type alias for a single param of a descriptor. */
67export type ApiParam<TDescriptor extends ApiDescriptor, TParamName extends ApiParamNames<TDescriptor>> = ApiParams<TDescriptor>[TParamName];
68
69/** Type alias for the union of parameter names in a descriptor. */
70export type ApiParamNames<TDescriptor extends ApiDescriptor> = keyof ApiParams<TDescriptor>;
71
72/** Type alias for a tuple of parameter types for a descriptor. */
73export type ApiOrderedParams<TDescriptor extends ApiDescriptor, TParamNames extends ApiParamNames<TDescriptor>[]> = {
74 [index in keyof TParamNames]: ApiParams<TDescriptor>[TParamNames[index]];
75};
76
77/** Type alias for the return member of a descriptor. */
78export type ApiReturn<TDescriptor extends ApiDescriptor> = TDescriptor['return'];
79
80/** A type representing a synchronous handler. */
81export type ApiHandlerSync<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => ApiReturn<TDescriptor>;
82
83/** A type representing an asynchronous handler. */
84export type ApiHandlerAsync<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => Promise<ApiReturn<TDescriptor>>;
85
86/** A type representing a generic handler. */
87export type ApiHandler<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => ApiReturn<TDescriptor> | Promise<ApiReturn<TDescriptor>>;
88
89/** A union of all of the handlers for a given surface. */
90export type ApiHandlerAny<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = ApiHandlerSurface<TSurface, TExtraParams>[ApiNames<TSurface>];
91
92/** A union of all of the names for a given surface. */
93export type ApiNames<TSurface extends ApiSurface> = keyof TSurface;
94
95/** A mapping of names to the corresponding handler function. */
96export type ApiMap<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = Map<ApiNames<TSurface>, ApiHandlerAny<TSurface, TExtraParams>>;
97
98/** The initialization array structure for populating an API map. */
99export type ApiMapInit<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = ApiMapInitItemAny<TSurface, TExtraParams>[];
100
101/** The type for a public API function, using a parameters object. */
102export type ApiFunction<TSurface extends ApiSurface, TName extends ApiNames<TSurface>> = (
103 params: ApiParams<TSurface[TName]>,
104) => Promise<ApiReturn<TSurface[TName]>>;
105
106/** The type for a public API function, using ordered parameters. */
107export type ApiFunctionOrdered<TSurface extends ApiSurface, TName extends ApiNames<TSurface>, TParamNames extends ApiParamNames<TSurface[TName]>[]> = (
108 ...params: ApiOrderedParams<TSurface[TName], TParamNames>,
109) => Promise<ApiReturn<TSurface[TName]>>;
110
111/** Type alias for a union of all params types. */
112export type ApiParamsAny<TSurface extends ApiSurface> = {[name in ApiNames<TSurface>]: ApiParams<TSurface[name]>}[ApiNames<TSurface>];
113
114/** Type alias for a union of all return types. */
115export type ApiReturnAny<TSurface extends ApiSurface> = {[name in ApiNames<TSurface>]: ApiReturn<TSurface[name]>}[ApiNames<TSurface>];