kizunajs 2.0.0-beta.2 → 2.0.0-beta.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/dist/{adapter-CZW-unqX.mjs → adapter-BSqNrxhq.mjs} +522 -104
- package/dist/adapter-C3WYdSfx.d.cts +2754 -0
- package/dist/{adapter-DDR_yo9L.cjs → adapter-ClaFZoab.cjs} +638 -196
- package/dist/adapter-D4bTPElA.d.mts +2754 -0
- package/dist/adapter.cjs +37 -29
- package/dist/adapter.d.cts +3 -5
- package/dist/adapter.d.mts +3 -5
- package/dist/adapter.mjs +5 -5
- package/dist/{error-response-C8Ragjcd.cjs → error-response-C9ymqSU4.cjs} +25 -5
- package/dist/{error-response-C839d8By.mjs → error-response-CNQaKVYd.mjs} +20 -6
- package/dist/{security-scheme-BrszwGD5.d.cts → error-response-NoOGdh8H.d.mts} +151 -24
- package/dist/{security-scheme-D3nb4XKj.d.mts → error-response-YbkRMKno.d.cts} +151 -24
- package/dist/generator.cjs +190 -95
- package/dist/generator.d.cts +189 -28
- package/dist/generator.d.mts +189 -28
- package/dist/generator.mjs +151 -60
- package/dist/index.cjs +159 -84
- package/dist/index.d.cts +193 -253
- package/dist/index.d.mts +193 -253
- package/dist/index.mjs +112 -38
- package/dist/jobs-entry.cjs +12 -11
- package/dist/jobs-entry.d.cts +1 -1
- package/dist/jobs-entry.d.mts +1 -1
- package/dist/jobs-entry.mjs +3 -2
- package/dist/plugin-Dw-yCjTY.cjs +233 -0
- package/dist/{cache-CLN5y0Xp.mjs → plugin-server-BztlE1fz.mjs} +188 -49
- package/dist/{cache-BgohRj0i.cjs → plugin-server-kUsK7thV.cjs} +238 -93
- package/dist/plugin-xxCxibmu.mjs +138 -0
- package/dist/plugin.cjs +8 -72
- package/dist/plugin.d.cts +3 -3
- package/dist/plugin.d.mts +3 -3
- package/dist/plugin.mjs +2 -68
- package/dist/{protected-resource-metadata-CA0v5cjg.d.mts → protected-resource-metadata-B9hMFQ9N.d.cts} +1 -1
- package/dist/{protected-resource-metadata-Cprrv0mt.d.cts → protected-resource-metadata-CfBVsqIk.d.mts} +1 -1
- package/dist/{schemas-C56no6bv.cjs → schemas-DNPVDvkd.cjs} +28 -1
- package/dist/{schemas-CJQcc97N.mjs → schemas-HW2FDsvz.mjs} +23 -2
- package/dist/schemas.cjs +3 -2
- package/dist/schemas.d.cts +24 -3
- package/dist/schemas.d.mts +24 -3
- package/dist/schemas.mjs +3 -3
- package/package.json +1 -1
- package/src/adapter.ts +245 -29
- package/src/api-definition.ts +12 -16
- package/src/api.ts +7 -3
- package/src/brand.ts +29 -0
- package/src/config.ts +51 -10
- package/src/configured.ts +13 -6
- package/src/define-config.ts +118 -39
- package/src/generator.ts +363 -46
- package/src/group-routes.ts +106 -0
- package/src/groups.ts +140 -0
- package/src/handler-pipeline.ts +78 -19
- package/src/index.ts +15 -6
- package/src/job-runner.ts +5 -0
- package/src/job-transport.ts +3 -3
- package/src/job.ts +8 -6
- package/src/jobs-dev-runner.ts +6 -0
- package/src/jobs.ts +61 -8
- package/src/kizuna.ts +56 -33
- package/src/plugin-server.ts +129 -19
- package/src/plugin.ts +269 -127
- package/src/routes.ts +80 -32
- package/src/schemas.ts +1 -0
- package/src/tool-answer.ts +21 -0
- package/src/tool-definitions.ts +166 -0
- package/src/tool-events.ts +90 -18
- package/src/tool-records.ts +11 -3
- package/src/tool-runner.ts +298 -0
- package/src/types.ts +90 -24
- package/src/zod-internals.ts +22 -5
- package/src/zod-meta.ts +7 -2
- package/dist/adapter-BGfMqEkM.d.cts +0 -563
- package/dist/adapter-Ci3cfcoT.d.mts +0 -563
- package/dist/api-definition-BHnh15zD.d.mts +0 -803
- package/dist/api-definition-DQj-ewHy.d.cts +0 -803
- package/dist/error-response-BBGSdgYw.d.mts +0 -67
- package/dist/error-response-Do38sr-9.d.cts +0 -67
- package/dist/plugin-Cz0kn6Lk.d.mts +0 -830
- package/dist/plugin-DhKvx_T0.d.cts +0 -830
- package/src/tags.ts +0 -67
package/src/plugin-server.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type
|
|
1
|
+
import type { z } from 'zod';
|
|
2
|
+
import { PLUGIN_ROUTES_META_KEY, PLUGIN_SERVERS_META_KEY, type PluginApi, type PluginDeclaration, type ResolvedPlugin } from './plugin.js';
|
|
3
|
+
import type { RoutePath, Routes } from './types.js';
|
|
3
4
|
|
|
4
5
|
/**
|
|
5
6
|
* The plugin routes `assembleApi` stashed on the api. Empty without plugins, so
|
|
@@ -34,24 +35,133 @@ export const pluginExportsOf = (api: unknown): Record<string, unknown> => {
|
|
|
34
35
|
};
|
|
35
36
|
|
|
36
37
|
/**
|
|
37
|
-
*
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
38
|
+
* One issue as the app should read it: the field, and what's wrong with it.
|
|
39
|
+
*/
|
|
40
|
+
export const describeIssue = (issue: z.core.$ZodIssue): string => {
|
|
41
|
+
const field = issue.path.map(String).join('.');
|
|
42
|
+
if (issue.code === 'invalid_type' && issue.message.endsWith('received undefined')) {
|
|
43
|
+
return `${field} is required`;
|
|
44
|
+
}
|
|
45
|
+
return field === '' ? issue.message : `${field}: ${issue.message}`;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* A route's path under its plugin's base path. A route at `/` serves the base
|
|
50
|
+
* path itself, since `/webhooks` and `/webhooks/` are different paths.
|
|
51
|
+
*/
|
|
52
|
+
const underBasePath = (basePath: string, path: string): RoutePath => (path === '/' ? basePath : `${basePath}${path}`) as RoutePath;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* The base path a plugin's routes are served under: the app's, else the
|
|
56
|
+
* plugin's own. An app can only move a plugin that declares one.
|
|
57
|
+
*/
|
|
58
|
+
const basePathOf = (declaration: PluginDeclaration): string | undefined => {
|
|
59
|
+
const { definition, slug } = declaration;
|
|
60
|
+
if (declaration.basePath !== undefined && definition.basePath === undefined) {
|
|
61
|
+
throw new Error(`[kizuna] Plugin '${slug}' declares no \`basePath\`, so its routes can't be moved. Remove \`basePath\`.`);
|
|
62
|
+
}
|
|
63
|
+
const basePath = declaration.basePath ?? definition.basePath;
|
|
64
|
+
if (basePath !== undefined && (!basePath.startsWith('/') || basePath.endsWith('/'))) {
|
|
65
|
+
throw new Error(
|
|
66
|
+
`[kizuna] Plugin '${slug}' has the base path '${basePath}'. A base path starts with \`/\` and doesn't end with one.`
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
return basePath;
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Validate one installed plugin's options and run its `setup`.
|
|
74
|
+
*/
|
|
75
|
+
const resolvePlugin = (declaration: PluginDeclaration, api: PluginApi): ResolvedPlugin => {
|
|
76
|
+
const { definition, slug } = declaration;
|
|
77
|
+
let options: unknown = undefined;
|
|
78
|
+
if (definition.options !== undefined) {
|
|
79
|
+
const parsed = definition.options.safeParse(declaration.input);
|
|
80
|
+
if (!parsed.success) {
|
|
81
|
+
throw new Error(`[kizuna] Plugin '${slug}' has invalid options: ${parsed.error.issues.map(describeIssue).join('; ')}`);
|
|
82
|
+
}
|
|
83
|
+
options = parsed.data;
|
|
84
|
+
}
|
|
85
|
+
const setup = definition.setup({
|
|
86
|
+
options: options as never,
|
|
87
|
+
api,
|
|
88
|
+
});
|
|
89
|
+
const basePath = basePathOf(declaration);
|
|
90
|
+
const routes = setup.routes ?? {};
|
|
91
|
+
return {
|
|
92
|
+
slug,
|
|
93
|
+
definedSlug: definition.slug,
|
|
94
|
+
options,
|
|
95
|
+
routes:
|
|
96
|
+
basePath === undefined
|
|
97
|
+
? routes
|
|
98
|
+
: Object.fromEntries(
|
|
99
|
+
Object.entries(routes).map(([routeKey, route]) => [
|
|
100
|
+
routeKey,
|
|
101
|
+
{
|
|
102
|
+
...route,
|
|
103
|
+
path: underBasePath(basePath, route.path),
|
|
104
|
+
},
|
|
105
|
+
])
|
|
106
|
+
),
|
|
107
|
+
exports: setup.exports,
|
|
108
|
+
generators: setup.generators ?? [],
|
|
109
|
+
validate: setup.validate,
|
|
110
|
+
};
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Resolve every installed plugin, keyed by slug. Two plugins on one slug throw,
|
|
115
|
+
* naming both, since handlers could only reach one of them.
|
|
116
|
+
*/
|
|
117
|
+
export const resolvePlugins = (declarations: readonly PluginDeclaration[] | undefined, api: PluginApi): Record<string, ResolvedPlugin> => {
|
|
118
|
+
const resolved: Record<string, ResolvedPlugin> = {};
|
|
119
|
+
for (const declaration of declarations ?? []) {
|
|
120
|
+
const existing = resolved[declaration.slug];
|
|
121
|
+
if (existing !== undefined) {
|
|
122
|
+
throw new Error(
|
|
123
|
+
`[kizuna] Two plugins are installed under the slug '${declaration.slug}': '${existing.definedSlug}' and '${declaration.definition.slug}'. Pass one of them a \`slug\` of its own.`
|
|
124
|
+
);
|
|
53
125
|
}
|
|
54
|
-
resolved[
|
|
126
|
+
resolved[declaration.slug] = resolvePlugin(declaration, api);
|
|
55
127
|
}
|
|
56
128
|
return resolved;
|
|
57
129
|
};
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* A stand-in for the api that plugins receive in `setup`, before it exists.
|
|
133
|
+
* Reading it inside a handler works once `bind` has run; reading it during
|
|
134
|
+
* `setup` throws, since the api is still being assembled.
|
|
135
|
+
*/
|
|
136
|
+
export const createApiReference = (): { api: PluginApi; bind: (target: object) => void } => {
|
|
137
|
+
let current: object | undefined;
|
|
138
|
+
const assembled = (): object => {
|
|
139
|
+
if (current === undefined) {
|
|
140
|
+
throw new Error('[kizuna] A plugin read the api during `setup`. Read it inside a handler, once the config has assembled.');
|
|
141
|
+
}
|
|
142
|
+
return current;
|
|
143
|
+
};
|
|
144
|
+
const api = new Proxy(
|
|
145
|
+
{},
|
|
146
|
+
{
|
|
147
|
+
get: (_target, key) => Reflect.get(assembled(), key),
|
|
148
|
+
has: (_target, key) => Reflect.has(assembled(), key),
|
|
149
|
+
ownKeys: () => Reflect.ownKeys(assembled()),
|
|
150
|
+
getOwnPropertyDescriptor: (_target, key) => {
|
|
151
|
+
const descriptor = Reflect.getOwnPropertyDescriptor(assembled(), key);
|
|
152
|
+
return descriptor === undefined
|
|
153
|
+
? undefined
|
|
154
|
+
: {
|
|
155
|
+
...descriptor,
|
|
156
|
+
configurable: true,
|
|
157
|
+
};
|
|
158
|
+
},
|
|
159
|
+
}
|
|
160
|
+
) as PluginApi;
|
|
161
|
+
return {
|
|
162
|
+
api,
|
|
163
|
+
bind: (target) => {
|
|
164
|
+
current = target;
|
|
165
|
+
},
|
|
166
|
+
};
|
|
167
|
+
};
|
package/src/plugin.ts
CHANGED
|
@@ -1,8 +1,14 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { createRoute, type RouteWithHandler } from './route.js';
|
|
1
3
|
import type { HandlerArgs, HandlerReturn } from './handler-pipeline.js';
|
|
2
4
|
import type { RawResponse } from './raw-response.js';
|
|
3
|
-
import type {
|
|
5
|
+
import type { GeneratedFile } from './config.js';
|
|
6
|
+
import type { AuthoredRouteDefinition, RouteHiddenToolCheck, Routes, RouteDefinition } from './types.js';
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
import type { RoutePath } from './types.js';
|
|
9
|
+
|
|
10
|
+
export type { RoutePath };
|
|
11
|
+
export type { ApiContext } from './configured.js';
|
|
6
12
|
|
|
7
13
|
// Registry-global: adapters read these off the api, and a dual ESM/CJS install
|
|
8
14
|
// would otherwise hold two different symbols.
|
|
@@ -10,115 +16,290 @@ export const PLUGIN_ROUTES_META_KEY: unique symbol = Symbol.for('kizuna.plugin-r
|
|
|
10
16
|
export const PLUGIN_SERVERS_META_KEY: unique symbol = Symbol.for('kizuna.plugin-servers') as symbol as typeof PLUGIN_SERVERS_META_KEY;
|
|
11
17
|
|
|
12
18
|
/**
|
|
13
|
-
* The routes a plugin serves
|
|
14
|
-
*
|
|
15
|
-
* and the generators do not see them.
|
|
19
|
+
* The routes a plugin serves, keyed by name. Each carries its handler, declared
|
|
20
|
+
* with {@link route}.
|
|
16
21
|
*/
|
|
17
22
|
export type PluginRoutes = Record<string, RouteDefinition>;
|
|
18
23
|
|
|
19
24
|
/**
|
|
20
|
-
* What a plugin
|
|
21
|
-
*
|
|
25
|
+
* What a plugin's `setup` returns. Every key is optional, and everything in it
|
|
26
|
+
* shares whatever `setup` created.
|
|
22
27
|
*/
|
|
23
|
-
export interface
|
|
24
|
-
R extends PluginRoutes = PluginRoutes,
|
|
25
|
-
Props = unknown,
|
|
26
|
-
Exports = unknown,
|
|
27
|
-
Slug extends string = string,
|
|
28
|
-
HandlerContext = unknown,
|
|
29
|
-
> {
|
|
28
|
+
export interface PluginSetup {
|
|
30
29
|
/**
|
|
31
|
-
*
|
|
30
|
+
* Functions every route and job handler reaches at `plugins.<slug>`.
|
|
32
31
|
*/
|
|
32
|
+
exports?: unknown;
|
|
33
33
|
/**
|
|
34
|
-
*
|
|
35
|
-
* Each plugin defaults it; an app installing two of the same plugin gives
|
|
36
|
-
* the second one its own.
|
|
34
|
+
* Routes an outside system calls, like a webhook or a status check.
|
|
37
35
|
*/
|
|
38
|
-
|
|
39
|
-
routes: R;
|
|
36
|
+
routes?: PluginRoutes;
|
|
40
37
|
/**
|
|
41
|
-
*
|
|
38
|
+
* Files `kizuna generate` writes, built with `defineGenerator`.
|
|
42
39
|
*/
|
|
43
|
-
|
|
40
|
+
generators?: readonly GeneratedFile[];
|
|
44
41
|
/**
|
|
45
|
-
*
|
|
46
|
-
*
|
|
42
|
+
* Runs once the config has assembled, with the api available. Throw to stop
|
|
43
|
+
* the app starting, for a check that needs the app's routes or identities.
|
|
47
44
|
*/
|
|
48
|
-
|
|
45
|
+
validate?: () => void;
|
|
49
46
|
}
|
|
50
47
|
|
|
51
48
|
/**
|
|
52
|
-
*
|
|
53
|
-
* it
|
|
49
|
+
* The assembled api, as a plugin's handlers read it. It exists once the config
|
|
50
|
+
* has assembled, so read it inside a handler, never in `setup` itself.
|
|
51
|
+
*/
|
|
52
|
+
export type PluginApi = Record<string | symbol, unknown> & {
|
|
53
|
+
readonly routes: Routes;
|
|
54
|
+
};
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* What `setup` receives.
|
|
54
58
|
*/
|
|
55
|
-
export interface
|
|
56
|
-
|
|
57
|
-
|
|
59
|
+
export interface PluginSetupContext<Options> {
|
|
60
|
+
/**
|
|
61
|
+
* The options the app passed, validated against the plugin's `options`
|
|
62
|
+
* schema.
|
|
63
|
+
*/
|
|
64
|
+
options: Options;
|
|
65
|
+
/**
|
|
66
|
+
* The assembled api, for handlers that read the app's routes or identities.
|
|
67
|
+
*/
|
|
68
|
+
api: PluginApi;
|
|
58
69
|
}
|
|
59
70
|
|
|
71
|
+
type OptionsOutput<Schema> = Schema extends z.ZodType ? z.output<Schema> : undefined;
|
|
72
|
+
type OptionsInput<Schema> = Schema extends z.ZodType ? z.input<Schema> : {};
|
|
73
|
+
|
|
60
74
|
/**
|
|
61
|
-
* What {@link
|
|
75
|
+
* What {@link definePlugin} takes.
|
|
62
76
|
*/
|
|
63
|
-
export interface PluginDefinition<
|
|
77
|
+
export interface PluginDefinition<
|
|
78
|
+
Slug extends string,
|
|
79
|
+
Schema extends z.ZodType | undefined,
|
|
80
|
+
Setup extends PluginSetup,
|
|
81
|
+
BasePath extends RoutePath | undefined = undefined,
|
|
82
|
+
> {
|
|
83
|
+
/**
|
|
84
|
+
* Handlers reach the plugin at `plugins.<slug>`.
|
|
85
|
+
*/
|
|
64
86
|
slug: Slug;
|
|
65
|
-
routes: R;
|
|
66
87
|
/**
|
|
67
|
-
*
|
|
88
|
+
* Where the plugin's routes are served. Each route's `path` is relative to
|
|
89
|
+
* it, and a route at `/` serves the base path itself. The app can pass
|
|
90
|
+
* another one when it clashes with its own routes.
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* basePath: '/webhooks',
|
|
68
94
|
*/
|
|
69
|
-
|
|
70
|
-
|
|
95
|
+
basePath?: BasePath;
|
|
96
|
+
/**
|
|
97
|
+
* A Zod schema for what the app passes in. It's validated once, when the
|
|
98
|
+
* config assembles, and a failure names the plugin and the field.
|
|
99
|
+
*/
|
|
100
|
+
options?: Schema;
|
|
101
|
+
/**
|
|
102
|
+
* Builds the plugin from its validated options, once, when the config
|
|
103
|
+
* assembles. It runs during `kizuna generate` too, so it creates clients and
|
|
104
|
+
* leaves connections to the handlers.
|
|
105
|
+
*/
|
|
106
|
+
setup: (context: PluginSetupContext<OptionsOutput<Schema>>) => Setup;
|
|
71
107
|
}
|
|
72
108
|
|
|
73
109
|
/**
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
|
|
110
|
+
* One installed plugin: the slug it's installed under, the plugin it is, and the
|
|
111
|
+
* options the app passed, still unvalidated.
|
|
112
|
+
*/
|
|
113
|
+
export interface PluginDeclaration<Slug extends string = string, Setup extends PluginSetup = PluginSetup> {
|
|
114
|
+
readonly slug: Slug;
|
|
115
|
+
/**
|
|
116
|
+
* The base path the app passed, when it moved the plugin's routes.
|
|
117
|
+
*/
|
|
118
|
+
readonly basePath?: string;
|
|
119
|
+
readonly definition: PluginDefinition<string, z.ZodType | undefined, PluginSetup, RoutePath | undefined>;
|
|
120
|
+
readonly input: unknown;
|
|
121
|
+
/**
|
|
122
|
+
* Carries what `setup` returns, for the types. Never set at runtime.
|
|
123
|
+
*/
|
|
124
|
+
readonly setupType?: Setup;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* What {@link definePlugin} returns: the function an app calls in `plugins`.
|
|
77
129
|
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
130
|
+
* Two overloads. Passing `slug` installs the plugin under it; leaving it out
|
|
131
|
+
* installs it under the plugin's own. The one without `slug` comes last, so
|
|
132
|
+
* `ReturnType<typeof emailPlugin>`, which `kizuna generate` writes, keeps the
|
|
133
|
+
* plugin's own slug rather than widening it to `string`.
|
|
134
|
+
*/
|
|
135
|
+
export type PluginFactory<
|
|
136
|
+
DefaultSlug extends string,
|
|
137
|
+
Schema extends z.ZodType | undefined,
|
|
138
|
+
Setup extends PluginSetup,
|
|
139
|
+
BasePath extends RoutePath | undefined = undefined,
|
|
140
|
+
> =
|
|
141
|
+
{} extends OptionsInput<Schema>
|
|
142
|
+
? {
|
|
143
|
+
<const Slug extends string>(
|
|
144
|
+
options: OptionsInput<Schema> & InstallOptions<BasePath> & SlugOption<Slug>
|
|
145
|
+
): PluginDeclaration<Slug, Setup>;
|
|
146
|
+
(options?: OptionsInput<Schema> & InstallOptions<BasePath>): PluginDeclaration<DefaultSlug, Setup>;
|
|
147
|
+
}
|
|
148
|
+
: {
|
|
149
|
+
<const Slug extends string>(
|
|
150
|
+
options: OptionsInput<Schema> & InstallOptions<BasePath> & SlugOption<Slug>
|
|
151
|
+
): PluginDeclaration<Slug, Setup>;
|
|
152
|
+
(options: OptionsInput<Schema> & InstallOptions<BasePath>): PluginDeclaration<DefaultSlug, Setup>;
|
|
153
|
+
};
|
|
154
|
+
|
|
155
|
+
export interface SlugOption<Slug extends string> {
|
|
156
|
+
/**
|
|
157
|
+
* Install the plugin under another slug, when two plugins want the same one.
|
|
158
|
+
*/
|
|
159
|
+
slug: Slug;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* `basePath` at install, offered only by a plugin that declares one.
|
|
164
|
+
*/
|
|
165
|
+
export type InstallOptions<BasePath> = BasePath extends RoutePath
|
|
166
|
+
? {
|
|
167
|
+
/**
|
|
168
|
+
* Serve the plugin's routes somewhere else, when they clash with the
|
|
169
|
+
* app's own.
|
|
170
|
+
*/
|
|
171
|
+
basePath?: RoutePath;
|
|
172
|
+
}
|
|
173
|
+
: {
|
|
174
|
+
basePath?: never;
|
|
175
|
+
};
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Declare a plugin: its slug, the options an app passes it, and the `setup` that
|
|
179
|
+
* builds what it brings. Returns the function an app installs it with.
|
|
80
180
|
*
|
|
81
181
|
* @example
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
* },
|
|
93
|
-
* },
|
|
94
|
-
* },
|
|
95
|
-
* props,
|
|
96
|
-
* serve: ({ store }) => ({
|
|
97
|
-
* router: {
|
|
98
|
-
* recent: async () => ({ status: 200, body: await store.recent() }),
|
|
99
|
-
* },
|
|
182
|
+
* export const emailPlugin = definePlugin({
|
|
183
|
+
* slug: 'email',
|
|
184
|
+
* options: z.object({
|
|
185
|
+
* apiKey: z.string(),
|
|
186
|
+
* from: z.string(),
|
|
187
|
+
* }),
|
|
188
|
+
* setup: ({ options }) => {
|
|
189
|
+
* const resend = new Resend(options.apiKey);
|
|
190
|
+
*
|
|
191
|
+
* return {
|
|
100
192
|
* exports: {
|
|
101
|
-
*
|
|
193
|
+
* send: (email: Email) =>
|
|
194
|
+
* resend.emails.send({
|
|
195
|
+
* from: options.from,
|
|
196
|
+
* ...email,
|
|
197
|
+
* }),
|
|
102
198
|
* },
|
|
103
|
-
* }
|
|
104
|
-
* }
|
|
199
|
+
* };
|
|
200
|
+
* },
|
|
201
|
+
* });
|
|
202
|
+
*/
|
|
203
|
+
export const definePlugin = <
|
|
204
|
+
Slug extends string,
|
|
205
|
+
Setup extends PluginSetup,
|
|
206
|
+
Schema extends z.ZodType | undefined = undefined,
|
|
207
|
+
BasePath extends RoutePath | undefined = undefined,
|
|
208
|
+
>(
|
|
209
|
+
definition: PluginDefinition<Slug, Schema, Setup, BasePath>
|
|
210
|
+
): PluginFactory<Slug, Schema, Setup, BasePath> =>
|
|
211
|
+
((input?: Record<string, unknown>) => {
|
|
212
|
+
const { slug, basePath, ...options } = input ?? {};
|
|
213
|
+
return {
|
|
214
|
+
slug: typeof slug === 'string' ? slug : definition.slug,
|
|
215
|
+
...(typeof basePath === 'string'
|
|
216
|
+
? {
|
|
217
|
+
basePath,
|
|
218
|
+
}
|
|
219
|
+
: {}),
|
|
220
|
+
definition: definition as unknown as PluginDefinition<string, z.ZodType | undefined, PluginSetup, RoutePath | undefined>,
|
|
221
|
+
input: options,
|
|
222
|
+
};
|
|
223
|
+
}) as never;
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* Declare one of a plugin's routes and the handler that answers it, the way
|
|
227
|
+
* `k.route` does for an app's own.
|
|
105
228
|
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
229
|
+
* @example
|
|
230
|
+
* check: route({
|
|
231
|
+
* method: 'GET',
|
|
232
|
+
* path: '/status',
|
|
233
|
+
* auth: false,
|
|
234
|
+
* responses: {
|
|
235
|
+
* 200: StatusSchema,
|
|
236
|
+
* },
|
|
237
|
+
* }).handler(() => ({
|
|
238
|
+
* status: 200,
|
|
239
|
+
* body: {
|
|
240
|
+
* status: 'ok',
|
|
241
|
+
* },
|
|
242
|
+
* })),
|
|
243
|
+
*/
|
|
244
|
+
export const route = createRoute as unknown as <const Definition extends AuthoredRouteDefinition>(
|
|
245
|
+
definition: Definition & RouteHiddenToolCheck<Definition>
|
|
246
|
+
) => PluginRouteBuilder<Definition>;
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* What {@link route} returns: the route, and the `handler` that answers it. A
|
|
250
|
+
* plugin's handler may also answer with `rawResponse` when its wire format is
|
|
251
|
+
* not JSON.
|
|
252
|
+
*/
|
|
253
|
+
export type PluginRouteBuilder<Definition extends AuthoredRouteDefinition> = Definition & {
|
|
254
|
+
handler(
|
|
255
|
+
fn: (args: HandlerArgs<Definition>) => Promise<HandlerReturn<Definition> | RawResponse> | HandlerReturn<Definition> | RawResponse
|
|
256
|
+
): RouteWithHandler<Definition>;
|
|
257
|
+
};
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* Accepts a route path, for a plugin that takes one of its routes' paths as an
|
|
261
|
+
* option.
|
|
262
|
+
*/
|
|
263
|
+
export const RoutePathSchema = z.custom<RoutePath>((value) => typeof value === 'string' && value.startsWith('/'), {
|
|
264
|
+
error: 'must start with /',
|
|
120
265
|
});
|
|
121
266
|
|
|
267
|
+
/**
|
|
268
|
+
* Accepts exactly what a route's `auth` does, for a plugin that takes one of its
|
|
269
|
+
* routes' `auth` as an option. `defineConfig` checks the value against the app's
|
|
270
|
+
* identities.
|
|
271
|
+
*/
|
|
272
|
+
export const RouteAuthSchema = z.union([
|
|
273
|
+
z.literal(false),
|
|
274
|
+
z.string(),
|
|
275
|
+
z.array(z.string()),
|
|
276
|
+
z.object({
|
|
277
|
+
identity: z.union([z.string(), z.array(z.string())]),
|
|
278
|
+
roles: z.union([z.string(), z.array(z.string())]).optional(),
|
|
279
|
+
requires: z.record(z.string(), z.array(z.string())).optional(),
|
|
280
|
+
}),
|
|
281
|
+
]);
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* A plugin once the config has assembled: its options validated and `setup`
|
|
285
|
+
* run.
|
|
286
|
+
*/
|
|
287
|
+
export interface ResolvedPlugin {
|
|
288
|
+
/**
|
|
289
|
+
* The slug it's installed under.
|
|
290
|
+
*/
|
|
291
|
+
slug: string;
|
|
292
|
+
/**
|
|
293
|
+
* The slug the plugin declared, whatever the app installed it under.
|
|
294
|
+
*/
|
|
295
|
+
definedSlug: string;
|
|
296
|
+
options: unknown;
|
|
297
|
+
routes: PluginRoutes;
|
|
298
|
+
exports: unknown;
|
|
299
|
+
generators: readonly GeneratedFile[];
|
|
300
|
+
validate: (() => void) | undefined;
|
|
301
|
+
}
|
|
302
|
+
|
|
122
303
|
/**
|
|
123
304
|
* Plugins keyed by their slug, which is what `plugins.*` in handler args
|
|
124
305
|
* resolves against.
|
|
@@ -126,34 +307,16 @@ export const createPlugin = <Props, const R extends PluginRoutes, const Slug ext
|
|
|
126
307
|
export type ApiPlugins = Record<string, AnyPlugin>;
|
|
127
308
|
|
|
128
309
|
/**
|
|
129
|
-
* Any plugin, whatever it declares.
|
|
130
|
-
* plugin is not assignable to a widened one; this stands in wherever a plugin
|
|
131
|
-
* is a constraint rather than a value.
|
|
310
|
+
* Any plugin, whatever it declares.
|
|
132
311
|
*/
|
|
133
|
-
export type AnyPlugin = PluginDeclaration<
|
|
312
|
+
export type AnyPlugin = PluginDeclaration<string, any>;
|
|
134
313
|
|
|
135
314
|
/**
|
|
136
|
-
* The plugins a config installs, as
|
|
137
|
-
*
|
|
315
|
+
* The plugins a config installs, as a list. Each carries its own slug, which is
|
|
316
|
+
* what handlers reach it under.
|
|
138
317
|
*/
|
|
139
318
|
export type PluginList = readonly AnyPlugin[];
|
|
140
319
|
|
|
141
|
-
/**
|
|
142
|
-
* One plugin declaration under a different slug, for a factory that lets an app
|
|
143
|
-
* rename what it installs.
|
|
144
|
-
*
|
|
145
|
-
* @example
|
|
146
|
-
* export function auditPlugin<const Slug extends string = 'audit'>(
|
|
147
|
-
* props?: AuditProps<Slug>
|
|
148
|
-
* ): WithSlug<ReturnType<typeof declare>, Slug> {
|
|
149
|
-
* return declare(props?.slug ?? 'audit', props ?? {}) as never;
|
|
150
|
-
* }
|
|
151
|
-
*/
|
|
152
|
-
export type WithSlug<Declaration, Slug extends string> =
|
|
153
|
-
Declaration extends PluginDeclaration<infer R, infer Props, infer Exports, string, infer HandlerContext>
|
|
154
|
-
? PluginDeclaration<R, Props, Exports, Slug, HandlerContext>
|
|
155
|
-
: never;
|
|
156
|
-
|
|
157
320
|
/**
|
|
158
321
|
* A plugin list as a record keyed by each plugin's own slug.
|
|
159
322
|
*/
|
|
@@ -161,13 +324,11 @@ export type PluginsBySlug<Plugins extends PluginList> = {
|
|
|
161
324
|
[Plugin in Plugins[number] as Plugin['slug']]: Plugin;
|
|
162
325
|
};
|
|
163
326
|
|
|
164
|
-
|
|
327
|
+
type SetupOf<Declaration> = Declaration extends PluginDeclaration<string, infer Setup> ? Setup : never;
|
|
165
328
|
|
|
166
|
-
export type
|
|
167
|
-
Declaration extends PluginDeclaration<infer _R, infer Props, infer _E, string, infer _H> ? Props : never;
|
|
329
|
+
export type PluginRoutesOf<Declaration> = SetupOf<Declaration> extends { routes: infer R extends PluginRoutes } ? R : Record<string, never>;
|
|
168
330
|
|
|
169
|
-
export type PluginExportsOf<Declaration> =
|
|
170
|
-
Declaration extends PluginDeclaration<infer _R, infer _P, infer Exports, string, infer _H> ? Exports : never;
|
|
331
|
+
export type PluginExportsOf<Declaration> = SetupOf<Declaration> extends { exports: infer Exports } ? Exports : undefined;
|
|
171
332
|
|
|
172
333
|
export type PluginExportValues<Plugins extends ApiPlugins> = {
|
|
173
334
|
[Key in keyof Plugins]: PluginExportsOf<Plugins[Key]>;
|
|
@@ -186,32 +347,13 @@ export type PluginArgs<Plugins extends ApiPlugins> = string extends keyof Plugin
|
|
|
186
347
|
};
|
|
187
348
|
|
|
188
349
|
/**
|
|
189
|
-
* Every plugin's routes as one tree, keyed by
|
|
190
|
-
*
|
|
350
|
+
* Every plugin's routes as one tree, keyed by slug, for the adapter to walk as
|
|
351
|
+
* it walks the api's own.
|
|
191
352
|
*/
|
|
192
|
-
export const pluginRouteTree = (plugins:
|
|
353
|
+
export const pluginRouteTree = (plugins: Record<string, { routes: PluginRoutes }> | undefined): Routes => {
|
|
193
354
|
const tree: Record<string, unknown> = {};
|
|
194
|
-
for (const [
|
|
195
|
-
tree[
|
|
355
|
+
for (const [slug, plugin] of Object.entries(plugins ?? {})) {
|
|
356
|
+
tree[slug] = plugin.routes;
|
|
196
357
|
}
|
|
197
358
|
return tree as Routes;
|
|
198
359
|
};
|
|
199
|
-
|
|
200
|
-
/**
|
|
201
|
-
* A plugin's handlers, typed against its routes. A plugin may also answer with
|
|
202
|
-
* {@link rawResponse} when its wire format is not JSON.
|
|
203
|
-
*/
|
|
204
|
-
export type PluginRouter<R extends PluginRoutes, HandlerContext> = {
|
|
205
|
-
[Key in keyof R]: (
|
|
206
|
-
args: HandlerArgs<R[Key]> & HandlerContext
|
|
207
|
-
) => Promise<HandlerReturn<R[Key]> | RawResponse> | HandlerReturn<R[Key]> | RawResponse;
|
|
208
|
-
};
|
|
209
|
-
|
|
210
|
-
/**
|
|
211
|
-
* Every plugin in a list, keyed by its own slug.
|
|
212
|
-
*/
|
|
213
|
-
export const pluginsBySlug = (plugins: PluginList | undefined): ApiPlugins => {
|
|
214
|
-
const bySlug: Record<string, unknown> = {};
|
|
215
|
-
for (const plugin of plugins ?? []) bySlug[plugin.slug] = plugin;
|
|
216
|
-
return bySlug as ApiPlugins;
|
|
217
|
-
};
|