@dokebi/module 0.4.0 → 0.4.2
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/AI.md +292 -7
- package/README.md +19 -2
- package/dist/action-api.d.ts +73 -0
- package/dist/action-api.js +249 -0
- package/dist/action.d.ts +152 -0
- package/dist/action.js +498 -0
- package/dist/contract.d.ts +305 -0
- package/dist/contract.js +524 -0
- package/dist/data-api.d.ts +49 -0
- package/dist/data-api.js +147 -0
- package/dist/data-source.d.ts +238 -0
- package/dist/data-source.js +742 -0
- package/dist/dependency.d.ts +3 -0
- package/dist/dependency.js +10 -0
- package/dist/index.d.ts +43 -3
- package/dist/index.js +208 -16
- package/dist/parts.d.ts +75 -0
- package/dist/parts.js +231 -0
- package/dist/preset.d.ts +25 -0
- package/dist/preset.js +165 -0
- package/package.json +15 -5
- package/templates/module/controllers/items.ts +14 -3
- package/templates/module/models/summary.ts +4 -4
- package/templates/module/module.ts +4 -0
- package/templates/module/services/items.ts +7 -0
- package/templates/module-api/controllers/items.ts +14 -3
- package/templates/module-api/models/summary.ts +4 -4
- package/templates/module-api/module.ts +4 -0
- package/templates/module-api/services/items.ts +7 -0
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// The module group as a dependency (D-0199): an app's routes read the group API with
|
|
2
|
+
// `app.getDependency(dependency)` — `data.routes(route)` mounts the general read of the data sources.
|
|
3
|
+
import { defineProvider } from '@dokebi/core';
|
|
4
|
+
export const provider = defineProvider({
|
|
5
|
+
name: 'dokebi-module',
|
|
6
|
+
packageName: '@dokebi/module',
|
|
7
|
+
version: '^0.4.2',
|
|
8
|
+
load: () => import('./index.js'),
|
|
9
|
+
});
|
|
10
|
+
export const dependency = provider.dependency;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,17 +1,29 @@
|
|
|
1
1
|
import type { ControllerDefinition } from '@dokebi/controller';
|
|
2
|
-
import { type Awaitable, type Plugin, type PluginContext, type PluginDependency } from '@dokebi/core';
|
|
2
|
+
import { type Awaitable, type ContributionPoint, type Plugin, type PluginContext, type PluginDependency } from '@dokebi/core';
|
|
3
3
|
import type { TemplateApi } from '@dokebi/template-ejs';
|
|
4
4
|
import type { InertiaApi } from '@dokebi/template-inertia';
|
|
5
5
|
import type { WebRoute } from '@dokebi/web';
|
|
6
6
|
import type { FastifyReply, FastifyRequest } from 'fastify';
|
|
7
|
+
import { type ActionApi, type ActionErrorCode } from './action-api.js';
|
|
8
|
+
import { type DescribedModule, type ModuleContract, type ModuleContractFields } from './contract.js';
|
|
9
|
+
import { type DataApi, type DataErrorCode } from './data-api.js';
|
|
10
|
+
export { ACTION_LIMITS, type ActionActor, type ActionField, type ActionFieldProblem, type ActionRun, type ActionTextFormat, checkInput, inputSchema, type ModuleAction, TEXT_FORMATS, } from './action.js';
|
|
11
|
+
export { type ActionApi, type ActionBody, type ActionEntry, type ActionErrorCode, type ActionHandler, type ActionResult, type ActionRouter, ActionValidationError, actionConflict, actionError, actionInvalid, actorOf, runAction, } from './action-api.js';
|
|
12
|
+
export { CONTRACT_LIMITS, type DescribedAction, type DescribedDataSource, type DescribedModule, islandName, type ModuleContract, type ModuleContractFields, type ModuleDataSource, type ModuleMenuEntry, type ModuleMenuItem, type ModulePermission, type ModulePreset, type ModuleText, type ModuleWidget, type ModuleWidgetLoadInput, } from './contract.js';
|
|
13
|
+
export { type DataApi, type DataErrorCode, type DataHandler, type DataPage, type DataRouter, dataError, } from './data-api.js';
|
|
14
|
+
export { CHOICE_TONES, type ChoiceTone, checkQuery, DATA_LIMITS, type DataAction, type DataField, type DataFieldType, type DataFilter, type DataFilterKind, type DataFilterValue, type DataRow, type DataSearch, type DataSort, type DataSourceRead, type DataValue, decodeCursor, encodeCursor, FIELD_TYPES, type ReadSql, readSql, } from './data-source.js';
|
|
15
|
+
export { checkParts, type ModulePart, type ModuleParts, PART_KINDS, PARTS_LIMITS, type PartEvent, type PartKind, type PartProp, type PartSlot, PartsIssue, type PartText, type PartVariant, readParts, } from './parts.js';
|
|
16
|
+
export { checkPresetApp, isSiteFile, PRESET_APP_KEYS, PRESET_KINDS, PRESET_LIMITS, type PresetKind, } from './preset.js';
|
|
7
17
|
/** Codes of the errors this package throws (`DokebiError` with `plugin: 'dokebi-module'`). */
|
|
8
|
-
export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING';
|
|
18
|
+
export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING' | 'INVALID_CONTRIBUTION' | 'UNDECLARED_POINT' | 'INVALID_CONTRACT' | 'MODULE_MISSING' | DataErrorCode | ActionErrorCode;
|
|
9
19
|
/** A plugin instance (read with context.get) or a descriptor (read with context.getDependency). */
|
|
10
20
|
export type ModuleRequirement = Plugin<unknown> | PluginDependency;
|
|
11
21
|
/** The plugin context of a module, plus the controllers the module declares. */
|
|
12
22
|
export interface ModuleContext extends PluginContext {
|
|
13
23
|
/** The module name (the folder name under src/shared/modules). */
|
|
14
24
|
readonly module: string;
|
|
25
|
+
/** The checked contract of the module (D-0197): what `@dokebi/module/mcp` reads its actions from. */
|
|
26
|
+
readonly contract: ModuleContract;
|
|
15
27
|
controller<T>(definition: ControllerDefinition<T>): T;
|
|
16
28
|
}
|
|
17
29
|
/** What a module route handler receives besides the Fastify request and reply (D-0032). */
|
|
@@ -52,6 +64,10 @@ export interface ModuleRouter {
|
|
|
52
64
|
*/
|
|
53
65
|
export interface ModuleSocketRoute {
|
|
54
66
|
readonly path: string;
|
|
67
|
+
/** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
|
|
68
|
+
readonly config?: {
|
|
69
|
+
readonly id?: string;
|
|
70
|
+
};
|
|
55
71
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
56
72
|
/**
|
|
57
73
|
* `namespace` (D-0061): one of the mounting app's `realtime.namespaces` (default its first);
|
|
@@ -69,19 +85,30 @@ export interface ModuleSocketRoute {
|
|
|
69
85
|
*/
|
|
70
86
|
export interface ModuleEventRoute {
|
|
71
87
|
readonly path: string;
|
|
88
|
+
/** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
|
|
89
|
+
readonly config?: {
|
|
90
|
+
readonly id?: string;
|
|
91
|
+
};
|
|
72
92
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
73
93
|
authenticate(request: FastifyRequest): Awaitable<{
|
|
74
94
|
readonly tenant: string;
|
|
75
95
|
readonly namespace?: string;
|
|
76
96
|
} | undefined>;
|
|
77
97
|
}
|
|
78
|
-
export interface ModuleDefinition<T> {
|
|
98
|
+
export interface ModuleDefinition<T> extends ModuleContractFields {
|
|
79
99
|
readonly name: string;
|
|
80
100
|
/** Exact plugin version of this module. Default '0.1.0'. */
|
|
81
101
|
readonly version?: string;
|
|
82
102
|
readonly requires?: readonly ModuleRequirement[];
|
|
83
103
|
/** `defineController` tokens, built once with this module's context. */
|
|
84
104
|
readonly controllers?: readonly ControllerDefinition<unknown>[];
|
|
105
|
+
/**
|
|
106
|
+
* Points this module contributes to (D-0130), made by `definePoint` and imported from the
|
|
107
|
+
* plugin that owns them (for example `mcpTools` of @dokebi/mcp). The module's setup calls
|
|
108
|
+
* `module.contribute(point, value)`; core sets the module up before every collector of the
|
|
109
|
+
* point. Values that no registered plugin collects are dropped with warn `POINT_NOT_COLLECTED`.
|
|
110
|
+
*/
|
|
111
|
+
readonly contributes?: readonly Pick<ContributionPoint<unknown>, 'name'>[];
|
|
85
112
|
/** Folder with one sub-folder per template (`default/` is required). */
|
|
86
113
|
readonly views?: URL;
|
|
87
114
|
/** Routes registered by every app that mounts this module (`defineApp({ modules })`). */
|
|
@@ -109,6 +136,10 @@ export interface ModuleMount {
|
|
|
109
136
|
readonly events: ModuleDefinition<unknown>['events'];
|
|
110
137
|
/** The module context; available once the module has been set up. */
|
|
111
138
|
context(): ModuleContext;
|
|
139
|
+
/** The checked contract (D-0197): what the module declares about itself. */
|
|
140
|
+
readonly contract: ModuleContract;
|
|
141
|
+
/** The module as `dokebi describe --json` gives it (reads its folders and widget templates). */
|
|
142
|
+
describe(): Promise<DescribedModule>;
|
|
112
143
|
}
|
|
113
144
|
export declare const MODULE_MOUNT: unique symbol;
|
|
114
145
|
export declare function defineModule<T = void>(definition: ModuleDefinition<T>): Plugin<T>;
|
|
@@ -119,5 +150,14 @@ export interface ModuleEntry {
|
|
|
119
150
|
}
|
|
120
151
|
export interface ModuleGroupApi {
|
|
121
152
|
readonly names: readonly string[];
|
|
153
|
+
/**
|
|
154
|
+
* The mount of a module of this group by its name (`members`), or undefined (D-0198): what an
|
|
155
|
+
* app runtime such as @dokebi/pages reads to draw the module's widgets.
|
|
156
|
+
*/
|
|
157
|
+
module(name: string): ModuleMount | undefined;
|
|
158
|
+
/** The data sources of the modules (D-0199): the general read and its route. */
|
|
159
|
+
readonly data: DataApi;
|
|
160
|
+
/** The actions of the modules (D-0202): the general write and its route. */
|
|
161
|
+
readonly actions: ActionApi;
|
|
122
162
|
}
|
|
123
163
|
export declare const createPlugin: import("@dokebi/core").PluginFactory<ModuleGroupApi>;
|
package/dist/index.js
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
1
|
import { stat } from 'node:fs/promises';
|
|
2
2
|
import { fileURLToPath } from 'node:url';
|
|
3
3
|
import { types } from 'node:util';
|
|
4
|
-
import { DokebiError, definePlugin, dependencyOf, providerDependency, } from '@dokebi/core';
|
|
4
|
+
import { DokebiError, definePlugin, definePoint, dependencyOf, providerDependency, } from '@dokebi/core';
|
|
5
|
+
import { createActionApi, } from './action-api.js';
|
|
6
|
+
import { CONTRACT_KEYS, ContractIssue, describeContract, readContract, readPresets, readTemplate, } from './contract.js';
|
|
7
|
+
import { createDataApi } from './data-api.js';
|
|
5
8
|
import { options } from './options.js';
|
|
9
|
+
export { ACTION_LIMITS, checkInput, inputSchema, TEXT_FORMATS, } from './action.js';
|
|
10
|
+
export { ActionValidationError, actionConflict, actionError, actionInvalid, actorOf, runAction, } from './action-api.js';
|
|
11
|
+
export { CONTRACT_LIMITS, islandName, } from './contract.js';
|
|
12
|
+
export { dataError, } from './data-api.js';
|
|
13
|
+
export { CHOICE_TONES, checkQuery, DATA_LIMITS, decodeCursor, encodeCursor, FIELD_TYPES, readSql, } from './data-source.js';
|
|
14
|
+
export { checkParts, PART_KINDS, PARTS_LIMITS, PartsIssue, readParts, } from './parts.js';
|
|
15
|
+
export { checkPresetApp, isSiteFile, PRESET_APP_KEYS, PRESET_KINDS, PRESET_LIMITS, } from './preset.js';
|
|
6
16
|
const FIX = {
|
|
7
17
|
INVALID_DEFINITION: 'Pass defineModule a lower-case name (a-z, 0-9, ., _, -) and only the documented fields: requires and controllers arrays, views as a file: URL, hooks as functions.',
|
|
8
18
|
INVALID_REQUIREMENT: 'List plugin instances or dependency descriptors ({ name, version }) in requires, each name once.',
|
|
@@ -11,21 +21,36 @@ const FIX = {
|
|
|
11
21
|
NOT_SET_UP: 'Read the module context after the module plugin has set up.',
|
|
12
22
|
NO_CONTROLLERS: 'Add the controller token to controllers of defineModule before calling module.controller().',
|
|
13
23
|
VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
|
|
24
|
+
INVALID_CONTRIBUTION: 'List in contributes the points made by definePoint that the module contributes to, each once and at most 64 (import them from the plugin that owns them, as mcpTools from @dokebi/mcp).',
|
|
25
|
+
UNDECLARED_POINT: 'Add the point to contributes of defineModule and call module.contribute(point, value) in the setup of the module. Modules only contribute: a plugin collects.',
|
|
26
|
+
INVALID_CONTRACT: 'Correct the contract fields of defineModule as the message says (AI.md of @dokebi/module, section 2a): titles, permission keys <module>.<action>, data source, action (input fields, permission, danger with preview), widget and menu names, file: URLs for db, locales and widget templates (.html, at most 64 KB).',
|
|
27
|
+
MODULE_MISSING: 'Add the module the message names to the project (npx dokebi module add <name>, or its package), or remove it from modules of the module that needs it.',
|
|
14
28
|
};
|
|
15
|
-
function moduleError(code, message, cause) {
|
|
29
|
+
function moduleError(code, message, cause, fix = FIX[code]) {
|
|
16
30
|
return new DokebiError(code, message, {
|
|
17
31
|
plugin: 'dokebi-module',
|
|
18
|
-
fix
|
|
32
|
+
fix,
|
|
19
33
|
...(cause === undefined ? {} : { cause }),
|
|
20
34
|
});
|
|
21
35
|
}
|
|
22
36
|
export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
|
|
23
37
|
const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
38
|
+
/** Module plugins are `dokebi-module.<name>` (D-0032). */
|
|
39
|
+
const MODULE_PREFIX = 'dokebi-module.';
|
|
40
|
+
/**
|
|
41
|
+
* The `core:describe` point of @dokebi/core 0.4.2, declared here by name (its identity) so this
|
|
42
|
+
* package keeps working with older cores, which never describe.
|
|
43
|
+
*/
|
|
44
|
+
const describePoint = definePoint('core:describe');
|
|
45
|
+
/** core's point name (`<owner plugin>:<name>`) and its limit per plugin (D-0063). */
|
|
46
|
+
const POINT_NAME = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
47
|
+
const POINT_LIMIT = 64;
|
|
24
48
|
const DEFINITION_KEYS = new Set([
|
|
25
49
|
'name',
|
|
26
50
|
'version',
|
|
27
51
|
'requires',
|
|
28
52
|
'controllers',
|
|
53
|
+
'contributes',
|
|
29
54
|
'views',
|
|
30
55
|
'routes',
|
|
31
56
|
'sockets',
|
|
@@ -33,6 +58,7 @@ const DEFINITION_KEYS = new Set([
|
|
|
33
58
|
'setup',
|
|
34
59
|
'start',
|
|
35
60
|
'drain',
|
|
61
|
+
...CONTRACT_KEYS,
|
|
36
62
|
]);
|
|
37
63
|
const ejs = providerDependency({
|
|
38
64
|
name: 'dokebi-template-ejs',
|
|
@@ -49,11 +75,32 @@ function requirement(value) {
|
|
|
49
75
|
throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
|
|
50
76
|
return value;
|
|
51
77
|
}
|
|
52
|
-
|
|
78
|
+
/** The point names of `contributes` (D-0130): made by definePoint, distinct, at most 64. */
|
|
79
|
+
function contributedPoints(value, module) {
|
|
80
|
+
if (value === undefined)
|
|
81
|
+
return Object.freeze([]);
|
|
82
|
+
const invalid = (detail) => moduleError('INVALID_CONTRIBUTION', `Invalid contributes of module ${module}: ${detail}`);
|
|
83
|
+
if (!Array.isArray(value) || types.isProxy(value))
|
|
84
|
+
throw invalid('expected an array of points');
|
|
85
|
+
if (value.length > POINT_LIMIT)
|
|
86
|
+
throw invalid(`more than ${POINT_LIMIT} points`);
|
|
87
|
+
const names = new Set();
|
|
88
|
+
for (const point of value) {
|
|
89
|
+
const name = point?.name;
|
|
90
|
+
if (typeof name !== 'string' || !POINT_NAME.test(name))
|
|
91
|
+
throw invalid('a point made by definePoint (<owner plugin>:<name>) was expected');
|
|
92
|
+
if (names.has(name))
|
|
93
|
+
throw invalid(`${name} is listed twice`);
|
|
94
|
+
names.add(name);
|
|
95
|
+
}
|
|
96
|
+
return Object.freeze([...names]);
|
|
97
|
+
}
|
|
98
|
+
function moduleContext(context, name, declared, controllers, points, contract) {
|
|
53
99
|
// core accepts only the descriptor object this module declared; look it up by name.
|
|
54
100
|
const own = (dependency) => declared.get(dependency?.name) ?? dependency;
|
|
55
101
|
return Object.freeze({
|
|
56
102
|
module: name,
|
|
103
|
+
contract,
|
|
57
104
|
get app() {
|
|
58
105
|
return context.app;
|
|
59
106
|
},
|
|
@@ -66,16 +113,29 @@ function moduleContext(context, name, declared, controllers) {
|
|
|
66
113
|
get drainSignal() {
|
|
67
114
|
return context.drainSignal;
|
|
68
115
|
},
|
|
116
|
+
// Set when the drain phase starts: read it there, not at setup.
|
|
117
|
+
get drainDeadline() {
|
|
118
|
+
return context.drainDeadline;
|
|
119
|
+
},
|
|
69
120
|
// The same frozen object for the whole application (core's own).
|
|
70
121
|
runtime: context.runtime,
|
|
71
122
|
get: (plugin) => context.get(plugin),
|
|
72
123
|
getDependency: (dependency) => context.getDependency(own(dependency)),
|
|
73
124
|
getOptionalDependency: (dependency) => context.getOptionalDependency(own(dependency)),
|
|
74
125
|
defer: (cleanup) => context.defer(cleanup),
|
|
75
|
-
//
|
|
76
|
-
//
|
|
77
|
-
contribute: (point, value) =>
|
|
78
|
-
|
|
126
|
+
// D-0130: a module contributes to the points of its `contributes`; core then checks the
|
|
127
|
+
// phase (CONTRIBUTIONS_CLOSED outside the module's setup) and orders the collectors after it.
|
|
128
|
+
contribute: (point, value) => {
|
|
129
|
+
const pointName = point?.name;
|
|
130
|
+
if (typeof pointName === 'string' && POINT_NAME.test(pointName) && !points.has(pointName))
|
|
131
|
+
throw moduleError('UNDECLARED_POINT', `Module ${name} does not declare the point ${pointName}`, undefined, `Add ${pointName} to contributes of defineModule({ name: '${name}', contributes: [...] }).`);
|
|
132
|
+
context.contribute(point, value);
|
|
133
|
+
},
|
|
134
|
+
// Modules never collect: reading a point is a plugin's role (definePlugin collects).
|
|
135
|
+
collect: (point) => {
|
|
136
|
+
const pointName = point?.name;
|
|
137
|
+
throw moduleError('UNDECLARED_POINT', `Module ${name} cannot collect ${typeof pointName === 'string' ? pointName : 'a point'}`, undefined, 'Modules only contribute. Collect the point in a plugin that declares it in collects (definePlugin), and give the module what it needs through requires.');
|
|
138
|
+
},
|
|
79
139
|
controller: (definition) => {
|
|
80
140
|
const api = controllers();
|
|
81
141
|
if (!api)
|
|
@@ -100,7 +160,21 @@ export function defineModule(definition) {
|
|
|
100
160
|
['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
101
161
|
throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
|
|
102
162
|
const { name, views } = definition;
|
|
163
|
+
let contract;
|
|
164
|
+
try {
|
|
165
|
+
contract = readContract(name, definition);
|
|
166
|
+
}
|
|
167
|
+
catch (error) {
|
|
168
|
+
if (error instanceof ContractIssue)
|
|
169
|
+
throw moduleError('INVALID_CONTRACT', error.message);
|
|
170
|
+
throw error;
|
|
171
|
+
}
|
|
172
|
+
const points = contributedPoints(definition.contributes, name);
|
|
173
|
+
const pointSet = new Set(points);
|
|
103
174
|
const dependencies = (definition.requires ?? []).map(requirement);
|
|
175
|
+
// D-0197: the modules it needs by name and range; core refuses the start without them.
|
|
176
|
+
for (const [other, range] of Object.entries(contract.modules))
|
|
177
|
+
dependencies.push(Object.freeze({ name: MODULE_PREFIX + other, version: range }));
|
|
104
178
|
if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
|
|
105
179
|
throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
|
|
106
180
|
if (views && !dependencies.some((dependency) => dependency.name === ejs.name))
|
|
@@ -114,7 +188,7 @@ export function defineModule(definition) {
|
|
|
114
188
|
const prefix = `module.${name}`;
|
|
115
189
|
const hook = (key) => async (context) => {
|
|
116
190
|
const begin = performance.now();
|
|
117
|
-
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers));
|
|
191
|
+
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet, contract));
|
|
118
192
|
context.logger.log('debug', `Module ${key} finished`, {
|
|
119
193
|
module: name,
|
|
120
194
|
ms: Math.round(performance.now() - begin),
|
|
@@ -122,16 +196,18 @@ export function defineModule(definition) {
|
|
|
122
196
|
};
|
|
123
197
|
const plugin = {
|
|
124
198
|
metadata: Object.freeze({
|
|
125
|
-
name:
|
|
199
|
+
name: MODULE_PREFIX + name,
|
|
126
200
|
version,
|
|
127
201
|
core: '^0.4.0',
|
|
128
202
|
dependencies: Object.freeze(dependencies),
|
|
203
|
+
// D-0130: declared when the module is defined, so core orders the collectors after it.
|
|
204
|
+
...(points.length ? { contributes: points, uncollected: 'warn' } : {}),
|
|
129
205
|
}),
|
|
130
206
|
async setup(context) {
|
|
131
207
|
if (started)
|
|
132
208
|
throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
|
|
133
209
|
started = true;
|
|
134
|
-
current = moduleContext(context, name, declared, () => controllers);
|
|
210
|
+
current = moduleContext(context, name, declared, () => controllers, pointSet, contract);
|
|
135
211
|
const begin = performance.now();
|
|
136
212
|
if (definition.controllers?.length) {
|
|
137
213
|
const { createControllers } = await import('@dokebi/controller');
|
|
@@ -149,16 +225,44 @@ export function defineModule(definition) {
|
|
|
149
225
|
throw moduleError('VIEWS_MISSING', `Module ${name} has no views/default/ folder`, failure);
|
|
150
226
|
await context.getDependency(templates ?? ejs).addDirectory(views, prefix);
|
|
151
227
|
}
|
|
228
|
+
// D-0197: a widget's first HTML must be readable and its settings valid before anything runs.
|
|
229
|
+
for (const [widget, item] of Object.entries(contract.widgets)) {
|
|
230
|
+
try {
|
|
231
|
+
await readTemplate(item.template);
|
|
232
|
+
}
|
|
233
|
+
catch (cause) {
|
|
234
|
+
throw moduleError('INVALID_CONTRACT', `The template of widget ${widget} of module ${name} cannot be read as UTF-8 HTML of at most 64 KB`, cause);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
// dokebi-platform DEC-16: a preset folder must have the shape of an app folder before anything runs.
|
|
238
|
+
try {
|
|
239
|
+
await readPresets(name, contract.presets);
|
|
240
|
+
}
|
|
241
|
+
catch (error) {
|
|
242
|
+
if (error instanceof ContractIssue)
|
|
243
|
+
throw moduleError('INVALID_CONTRACT', error.message);
|
|
244
|
+
throw error;
|
|
245
|
+
}
|
|
246
|
+
// Throws INVALID_PLUGIN_OPTIONS (paths, never values) for settings that do not fit.
|
|
247
|
+
contract.settings?.read(context.app.config);
|
|
152
248
|
const api = (await definition.setup?.(current));
|
|
153
249
|
context.logger.log('debug', 'Module set up', {
|
|
154
250
|
module: name,
|
|
155
251
|
version,
|
|
156
252
|
requires: dependencies.map((dependency) => dependency.name),
|
|
157
253
|
controllers: definition.controllers?.length ?? 0,
|
|
254
|
+
contributes: points,
|
|
158
255
|
views: views ? prefix : false,
|
|
159
256
|
routes: Boolean(definition.routes),
|
|
160
257
|
sockets: Boolean(definition.sockets),
|
|
161
258
|
events: Boolean(definition.events),
|
|
259
|
+
modules: contract.modules,
|
|
260
|
+
permissions: Object.keys(contract.permissions).length,
|
|
261
|
+
dataSources: Object.keys(contract.dataSources),
|
|
262
|
+
actions: Object.keys(contract.actions),
|
|
263
|
+
widgets: Object.keys(contract.widgets),
|
|
264
|
+
menu: contract.menu.length,
|
|
265
|
+
settings: contract.settings?.section ?? false,
|
|
162
266
|
ms: Math.round(performance.now() - begin),
|
|
163
267
|
});
|
|
164
268
|
return api;
|
|
@@ -177,6 +281,27 @@ export function defineModule(definition) {
|
|
|
177
281
|
throw moduleError('NOT_SET_UP', `Module ${name} is not set up yet`);
|
|
178
282
|
return current;
|
|
179
283
|
},
|
|
284
|
+
contract,
|
|
285
|
+
describe: () => describeContract({
|
|
286
|
+
name,
|
|
287
|
+
version,
|
|
288
|
+
requires: dependencies
|
|
289
|
+
.map((dependency) => dependency.name)
|
|
290
|
+
.filter((dependency) => !dependency.startsWith(MODULE_PREFIX)),
|
|
291
|
+
contributes: points,
|
|
292
|
+
views: views ? prefix : undefined,
|
|
293
|
+
hooks: {
|
|
294
|
+
routes: Boolean(definition.routes),
|
|
295
|
+
sockets: Boolean(definition.sockets),
|
|
296
|
+
events: Boolean(definition.events),
|
|
297
|
+
},
|
|
298
|
+
contract,
|
|
299
|
+
}).catch((error) => {
|
|
300
|
+
// A parts file that breaks its rules (D-0203) is found here, when it is read.
|
|
301
|
+
if (error instanceof ContractIssue)
|
|
302
|
+
throw moduleError('INVALID_CONTRACT', error.message);
|
|
303
|
+
throw error;
|
|
304
|
+
}),
|
|
180
305
|
});
|
|
181
306
|
Object.defineProperty(plugin, MODULE_MOUNT, { value: mount });
|
|
182
307
|
return Object.freeze(plugin);
|
|
@@ -214,27 +339,94 @@ function parseEntry(input) {
|
|
|
214
339
|
if (!Array.isArray(modules) || modules.length > LIMIT)
|
|
215
340
|
throw moduleError('INVALID_ENTRY', 'Expected a modules array');
|
|
216
341
|
const names = modules.map((module) => module?.metadata?.name);
|
|
217
|
-
if (names.some((name) => typeof name !== 'string' || !name.startsWith(
|
|
342
|
+
if (names.some((name) => typeof name !== 'string' || !name.startsWith(MODULE_PREFIX)) ||
|
|
218
343
|
new Set(names).size !== names.length)
|
|
219
344
|
throw moduleError('INVALID_ENTRY', 'Expected distinct module plugins');
|
|
345
|
+
// D-0197: a module that needs another one which is not in the project says so by name, before
|
|
346
|
+
// core's MISSING_DEPENDENCY (whose message only names the plugin).
|
|
347
|
+
const present = new Set(names);
|
|
348
|
+
for (const module of modules) {
|
|
349
|
+
const mount = moduleMount(module);
|
|
350
|
+
for (const [other, range] of Object.entries(mount?.contract?.modules ?? {}))
|
|
351
|
+
if (!present.has(MODULE_PREFIX + other))
|
|
352
|
+
throw moduleError('MODULE_MISSING', `Module ${mount?.name} needs module ${other} (${range}), which is not in the project`, undefined, `Add module ${other} to the project (npx dokebi module add ${other}, or install the package that provides it), or remove ${other} from modules of module ${mount?.name}.`);
|
|
353
|
+
}
|
|
220
354
|
return [...modules];
|
|
221
355
|
}
|
|
222
356
|
class ModuleGroupRuntime {
|
|
223
357
|
names;
|
|
224
|
-
|
|
358
|
+
modules;
|
|
359
|
+
constructor(names, modules) {
|
|
225
360
|
this.names = names;
|
|
361
|
+
this.modules = modules;
|
|
226
362
|
}
|
|
227
363
|
setup(context) {
|
|
228
364
|
context.logger.log('debug', 'Modules registered', { modules: this.names });
|
|
229
|
-
|
|
365
|
+
// D-0197: only `dokebi describe` (runtime.describing) asks; a normal start adds nothing.
|
|
366
|
+
if (context.runtime.describing) {
|
|
367
|
+
const mounts = this.modules
|
|
368
|
+
.map((module) => moduleMount(module))
|
|
369
|
+
.filter((mount) => mount !== undefined);
|
|
370
|
+
context.contribute(describePoint, {
|
|
371
|
+
section: 'modules',
|
|
372
|
+
describe: async () => {
|
|
373
|
+
const described = [];
|
|
374
|
+
for (const mount of mounts)
|
|
375
|
+
described.push(await mount.describe());
|
|
376
|
+
return described;
|
|
377
|
+
},
|
|
378
|
+
});
|
|
379
|
+
}
|
|
380
|
+
const byName = new Map();
|
|
381
|
+
for (const module of this.modules) {
|
|
382
|
+
const mount = moduleMount(module);
|
|
383
|
+
if (mount)
|
|
384
|
+
byName.set(mount.name, mount);
|
|
385
|
+
}
|
|
386
|
+
const sources = new Map();
|
|
387
|
+
for (const mount of byName.values())
|
|
388
|
+
for (const [name, declaration] of Object.entries(mount.contract?.dataSources ?? {}))
|
|
389
|
+
sources.set(`${mount.name}.${name}`, {
|
|
390
|
+
module: mount.name,
|
|
391
|
+
declaration,
|
|
392
|
+
context: () => mount.context(),
|
|
393
|
+
});
|
|
394
|
+
const data = createDataApi(sources, context.logger);
|
|
395
|
+
context.logger.log('debug', 'Data sources registered', { sources: data.ids });
|
|
396
|
+
const actions = new Map();
|
|
397
|
+
for (const mount of byName.values())
|
|
398
|
+
for (const [name, declaration] of Object.entries(mount.contract?.actions ?? {}))
|
|
399
|
+
actions.set(`${mount.name}.${name}`, {
|
|
400
|
+
id: `${mount.name}.${name}`,
|
|
401
|
+
module: mount.name,
|
|
402
|
+
declaration,
|
|
403
|
+
context: () => mount.context(),
|
|
404
|
+
});
|
|
405
|
+
// D-0202: a row action naming another module's action names one that module declares.
|
|
406
|
+
for (const mount of byName.values())
|
|
407
|
+
for (const [source, item] of Object.entries(mount.contract?.dataSources ?? {}))
|
|
408
|
+
for (const [name, rowAction] of Object.entries(item.actions ?? {})) {
|
|
409
|
+
const target = rowAction.action;
|
|
410
|
+
if (target?.includes('.') && !actions.has(target))
|
|
411
|
+
throw moduleError('INVALID_CONTRACT', `dataSources.${source}.actions.${name}.action of module ${mount.name} names ${target}, which no module of the project declares`);
|
|
412
|
+
}
|
|
413
|
+
const write = createActionApi(actions, context.logger);
|
|
414
|
+
context.logger.log('debug', 'Actions registered', { actions: write.ids });
|
|
415
|
+
return Object.freeze({
|
|
416
|
+
names: this.names,
|
|
417
|
+
module: (name) => byName.get(name),
|
|
418
|
+
data,
|
|
419
|
+
actions: write,
|
|
420
|
+
});
|
|
230
421
|
}
|
|
231
422
|
}
|
|
232
423
|
export const createPlugin = definePlugin({
|
|
233
424
|
name: 'dokebi-module',
|
|
234
|
-
version: '0.4.
|
|
425
|
+
version: '0.4.2',
|
|
235
426
|
core: '^0.4.0',
|
|
236
427
|
options,
|
|
428
|
+
contributes: [describePoint],
|
|
237
429
|
entry: parseEntry,
|
|
238
430
|
dependencies: ({ entry }) => (entry ?? []).map((module) => dependencyOf(module)),
|
|
239
|
-
instance: ({ dependencies }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name))),
|
|
431
|
+
instance: ({ dependencies, entry }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name)), Object.freeze([...(entry ?? [])])),
|
|
240
432
|
});
|
package/dist/parts.d.ts
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/** A text, or a text per locale (`{ en: 'Button', ko: '단추' }`). */
|
|
2
|
+
export type PartText = string | Readonly<Record<string, string>>;
|
|
3
|
+
export declare const PART_KINDS: readonly ['component', 'directive', 'class', 'widget'];
|
|
4
|
+
export type PartKind = (typeof PART_KINDS)[number];
|
|
5
|
+
export interface PartProp {
|
|
6
|
+
readonly name: string;
|
|
7
|
+
/** The type as written (`'sm' | 'md'`, `boolean`, `UiOption[]`). */
|
|
8
|
+
readonly type: string;
|
|
9
|
+
readonly required: boolean;
|
|
10
|
+
/** The default as written (`'md'`, `false`, `() => []`), when there is one. */
|
|
11
|
+
readonly default?: string;
|
|
12
|
+
readonly description?: PartText;
|
|
13
|
+
}
|
|
14
|
+
export interface PartSlot {
|
|
15
|
+
readonly name: string;
|
|
16
|
+
/** What the slot hands its content (`{ row, value }`), when anything. */
|
|
17
|
+
readonly props?: string;
|
|
18
|
+
readonly description?: PartText;
|
|
19
|
+
}
|
|
20
|
+
export interface PartEvent {
|
|
21
|
+
readonly name: string;
|
|
22
|
+
/** The payload type (`[value: string]`), when there is one. */
|
|
23
|
+
readonly payload?: string;
|
|
24
|
+
readonly description?: PartText;
|
|
25
|
+
}
|
|
26
|
+
export interface PartVariant {
|
|
27
|
+
/** A class (`btn-primary`) or a prop value (`variant="outline"`). */
|
|
28
|
+
readonly name: string;
|
|
29
|
+
readonly description?: PartText;
|
|
30
|
+
}
|
|
31
|
+
export interface ModulePart {
|
|
32
|
+
/** `UiButton`, `v-truncate-tooltip`, `.btn`, or the widget's name. */
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly kind: PartKind;
|
|
35
|
+
/** One line: what it is. */
|
|
36
|
+
readonly title: PartText;
|
|
37
|
+
readonly description?: PartText;
|
|
38
|
+
/** When to use it (and when not). */
|
|
39
|
+
readonly use?: PartText;
|
|
40
|
+
/** The source file, relative to the module folder. */
|
|
41
|
+
readonly file?: string;
|
|
42
|
+
readonly props?: readonly PartProp[];
|
|
43
|
+
readonly slots?: readonly PartSlot[];
|
|
44
|
+
readonly events?: readonly PartEvent[];
|
|
45
|
+
readonly variants?: readonly PartVariant[];
|
|
46
|
+
/** Markup to start from (Vue template or page HTML). */
|
|
47
|
+
readonly examples?: readonly string[];
|
|
48
|
+
/** Where its live sample is (`/ui#buttons`), an address of the app that shows the samples. */
|
|
49
|
+
readonly sample?: string;
|
|
50
|
+
/** kind `widget`: the widget of this module (`admin-header`). */
|
|
51
|
+
readonly widget?: string;
|
|
52
|
+
}
|
|
53
|
+
export interface ModuleParts {
|
|
54
|
+
readonly parts: readonly ModulePart[];
|
|
55
|
+
}
|
|
56
|
+
export declare const PARTS_LIMITS: Readonly<{
|
|
57
|
+
/** Bytes of the parts file. */
|
|
58
|
+
fileBytes: 2000000;
|
|
59
|
+
parts: 512;
|
|
60
|
+
/** Props, slots, events or variants of one part. */
|
|
61
|
+
members: 128;
|
|
62
|
+
examples: 16;
|
|
63
|
+
/** Characters of one text (a description, a type, a default). */
|
|
64
|
+
textChars: 2000;
|
|
65
|
+
/** Characters of one example. */
|
|
66
|
+
exampleChars: 8000;
|
|
67
|
+
locales: 32;
|
|
68
|
+
}>;
|
|
69
|
+
/** Thrown for a parts file that breaks a rule; the caller turns it into INVALID_CONTRACT. */
|
|
70
|
+
export declare class PartsIssue extends Error {
|
|
71
|
+
}
|
|
72
|
+
/** Checks parsed parts (`{ parts: [...] }`) against the module's widget names. */
|
|
73
|
+
export declare function checkParts(value: unknown, widgets: Iterable<string>, where?: string): ModuleParts;
|
|
74
|
+
/** Reads and checks a module's parts file (UTF-8 JSON of at most PARTS_LIMITS.fileBytes). */
|
|
75
|
+
export declare function readParts(file: URL, widgets: Iterable<string>): Promise<ModuleParts>;
|