1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
/*
* Copyright (C) 2023-2024 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/>.
*/
/**
* This type describes the structure of an API surface.
* It is effectively just an object containing a list of items which describe a basic API functionality.
*/
type ApiSurface = {
[name: string]: ApiDescriptor;
};
/**
* This type describes the structure of a single API function.
*/
type ApiDescriptor = {
/** The parameters for the function. If there are no parameters, `void` should be used. */
params: void | {[name: string]: unknown};
/** The return type for the function. */
return: unknown;
};
/**
* This type represents a mapping of an entire API surface to its handlers.
*/
type ApiHandlerSurface<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams> = {
[name in ApiNames<TSurface>]: ApiHandler<TSurface[name], TExtraParams>;
};
/**
* This type represents a single API map initializer.
* Type safety is enforced by ensuring that the name and handler signature are valid.
*/
type ApiMapInitItem<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams, TName extends ApiNames<TSurface>> = [
name: TName,
handler: ApiHandler<TSurface[TName], TExtraParams>,
];
/**
* This type represents a union of all API map initializers for a given surface.
*/
type ApiMapInitItemAny<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams> = {[key in ApiNames<TSurface>]: ApiMapInitItem<TSurface, TExtraParams, key>}[ApiNames<TSurface>];
/** Base type for extra params, which is just a generic array. */
type ApiTExtraParams = unknown[];
/** Default type for extra params, which is an empty array. */
type ApiExtraParamsDefault = [];
/** Type alias for the params member of a descriptor. */
export type ApiParams<TDescriptor extends ApiDescriptor> = TDescriptor['params'];
/** Type alias for a single param of a descriptor. */
export type ApiParam<TDescriptor extends ApiDescriptor, TParamName extends ApiParamNames<TDescriptor>> = ApiParams<TDescriptor>[TParamName];
/** Type alias for the union of parameter names in a descriptor. */
export type ApiParamNames<TDescriptor extends ApiDescriptor> = keyof ApiParams<TDescriptor>;
/** Type alias for a tuple of parameter types for a descriptor. */
export type ApiOrderedParams<TDescriptor extends ApiDescriptor, TParamNames extends ApiParamNames<TDescriptor>[]> = {
[index in keyof TParamNames]: ApiParams<TDescriptor>[TParamNames[index]];
};
/** Type alias for the return member of a descriptor. */
export type ApiReturn<TDescriptor extends ApiDescriptor> = TDescriptor['return'];
/** A type representing a synchronous handler. */
export type ApiHandlerSync<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => ApiReturn<TDescriptor>;
/** A type representing an asynchronous handler. */
export type ApiHandlerAsync<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => Promise<ApiReturn<TDescriptor>>;
/** A type representing a generic handler. */
export type ApiHandler<TDescriptor extends ApiDescriptor, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = (params: ApiParams<TDescriptor>, ...extraParams: TExtraParams) => ApiReturn<TDescriptor> | Promise<ApiReturn<TDescriptor>>;
/** A union of all of the handlers for a given surface. */
export type ApiHandlerAny<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = ApiHandlerSurface<TSurface, TExtraParams>[ApiNames<TSurface>];
/** A union of all of the names for a given surface. */
export type ApiNames<TSurface extends ApiSurface> = keyof TSurface;
/** A mapping of names to the corresponding handler function. */
export type ApiMap<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = Map<ApiNames<TSurface>, ApiHandlerAny<TSurface, TExtraParams>>;
/** The initialization array structure for populating an API map. */
export type ApiMapInit<TSurface extends ApiSurface, TExtraParams extends ApiTExtraParams = ApiExtraParamsDefault> = ApiMapInitItemAny<TSurface, TExtraParams>[];
/** The type for a public API function, using a parameters object. */
export type ApiFunction<TSurface extends ApiSurface, TName extends ApiNames<TSurface>> = (
params: ApiParams<TSurface[TName]>,
) => Promise<ApiReturn<TSurface[TName]>>;
/** The type for a public API function, using ordered parameters. */
export type ApiFunctionOrdered<TSurface extends ApiSurface, TName extends ApiNames<TSurface>, TParamNames extends ApiParamNames<TSurface[TName]>[]> = (
...params: ApiOrderedParams<TSurface[TName], TParamNames>,
) => Promise<ApiReturn<TSurface[TName]>>;
/** Type alias for a union of all params types. */
export type ApiParamsAny<TSurface extends ApiSurface> = {[name in ApiNames<TSurface>]: ApiParams<TSurface[name]>}[ApiNames<TSurface>];
/** Type alias for a union of all return types. */
export type ApiReturnAny<TSurface extends ApiSurface> = {[name in ApiNames<TSurface>]: ApiReturn<TSurface[name]>}[ApiNames<TSurface>];
|