@dokebi/module 0.4.0 → 0.4.1
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 +50 -6
- package/README.md +15 -2
- package/dist/index.d.ts +17 -2
- package/dist/index.js +54 -10
- package/package.json +5 -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
package/AI.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# AI guide — @dokebi/module
|
|
1
|
+
# AI guide — @dokebi/module
|
|
2
2
|
|
|
3
|
-
A module is **one feature as a unit of business code** (D-0032). It keeps controllers, models, views, routes and sockets in one folder, and apps mount it under a prefix. Business code without a web side (job handlers, event subscriptions, shared APIs) is a module too. Node >=24.0.0, core ^0.4.0. Details are in the [README](README.md).
|
|
3
|
+
A module is **one feature as a unit of business code** (D-0032). It keeps controllers, services, models, views, routes and sockets in one folder, and apps mount it under a prefix. Business code without a web side (job handlers, event subscriptions, shared APIs) is a module too. Node >=24.0.0, core ^0.4.0. Details are in the [README](README.md).
|
|
4
4
|
|
|
5
5
|
## 1. Creating modules
|
|
6
6
|
|
|
@@ -20,7 +20,7 @@ A hand-made module folder is not registered. The generated registration code pas
|
|
|
20
20
|
src/shared/modules/<module>/
|
|
21
21
|
module.ts export default defineModule({ ... })
|
|
22
22
|
routes.ts routes registered when an app mounts the module
|
|
23
|
-
controllers/ models/ views/default/ (modules with pages) sockets/ (when needed)
|
|
23
|
+
controllers/ services/ models/ views/default/ (modules with pages) sockets/ (when needed)
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
Do not scatter controllers, models and views into layer folders (`src/shared/controllers` and so on).
|
|
@@ -30,12 +30,14 @@ Do not scatter controllers, models and views into layer folders (`src/shared/con
|
|
|
30
30
|
```ts snippet
|
|
31
31
|
import { defineModule } from '@dokebi/module';
|
|
32
32
|
import { dependency as db } from '@dokebi/db';
|
|
33
|
+
import { mcpTools } from '@dokebi/mcp';
|
|
33
34
|
import { postsController } from './controllers/posts.ts';
|
|
34
35
|
|
|
35
36
|
export default defineModule({
|
|
36
37
|
name: 'board', // the folder name; the plugin id is dokebi-module.board
|
|
37
38
|
requires: [db], // instances, descriptors, other modules
|
|
38
39
|
controllers: [postsController],
|
|
40
|
+
contributes: [mcpTools], // points of plugins this module contributes to (§3a)
|
|
39
41
|
views: new URL('./views/', import.meta.url), // default/ is required (adds a template-ejs dependency)
|
|
40
42
|
routes(route, module) { // registered for every app that mounts it, on that app's domains and prefix
|
|
41
43
|
route.get('/', async (request, reply, page) =>
|
|
@@ -57,6 +59,7 @@ export default defineModule({
|
|
|
57
59
|
- `controllers`: uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers is `NO_CONTROLLERS` (`declares no controllers`).
|
|
58
60
|
- `module.runtime` is core's runtime role (`solo`, `primary`, `worker`; D-0063 §4). Do not read `node:cluster` yourself.
|
|
59
61
|
- Route options are `WebRoute` options without `handler` and `constraints` (`ModuleRouteOptions`, so `seal` works).
|
|
62
|
+
- `contributes`: the points of other plugins this module contributes to (§3a). Without it `module.contribute` is `UNDECLARED_POINT`.
|
|
60
63
|
|
|
61
64
|
## 3. Mounting on apps and shared APIs
|
|
62
65
|
|
|
@@ -65,6 +68,36 @@ export default defineModule({
|
|
|
65
68
|
- APIs that must answer on every domain (such as `/api/*`) are not `routes`; register them in `setup` directly with `@dokebi/router` (`mount`) or web.
|
|
66
69
|
- For another module or plugin to use this module's API, put this module into its `requires` and `get(module)`; it receives what `setup` returned.
|
|
67
70
|
|
|
71
|
+
## 3a. Contributing to plugin points (MCP tools and others)
|
|
72
|
+
|
|
73
|
+
A module offers values to a plugin that collects a point ([D-0130](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0130-module-contributions.md); the points are core's, D-0063): MCP tools, prompts and resources of @dokebi/mcp (`mcpTools`, `mcpPrompts`, `mcpResources`), mail template folders, error translators. It is the same mechanism for every point; nothing is special to MCP.
|
|
74
|
+
|
|
75
|
+
```ts snippet
|
|
76
|
+
import { dependency as db } from '@dokebi/db';
|
|
77
|
+
import { mcpTools } from '@dokebi/mcp';
|
|
78
|
+
import { defineModule } from '@dokebi/module';
|
|
79
|
+
import { DocumentService } from './services/documents.ts';
|
|
80
|
+
import { ListDocuments } from './tools/list-documents.ts';
|
|
81
|
+
|
|
82
|
+
export default defineModule({
|
|
83
|
+
name: 'workspace',
|
|
84
|
+
requires: [db],
|
|
85
|
+
contributes: [mcpTools], // declared when the module is defined
|
|
86
|
+
setup(module) {
|
|
87
|
+
const documents = new DocumentService(module.getDependency(db));
|
|
88
|
+
module.contribute(mcpTools, new ListDocuments(documents)); // the module's own service
|
|
89
|
+
return { documents }; // the module API: the same object
|
|
90
|
+
},
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- **Declared, not dynamic**: `contributes` becomes the module plugin's `metadata.contributes` when `defineModule` runs, before the app registers anything, so core checks every `module.contribute` against it and `npx dokebi describe` lists it (each plugin's `contributes` and `collects`, and a summary line per module point with its collector). Points made by `definePoint`, each once, at most 64 (`INVALID_CONTRIBUTION`).
|
|
95
|
+
- **Order**: core's rule for every contributor: the module sets up (and builds its services) before every plugin that collects the point, and drains after it; registration order does not matter. Contribute in `setup` only (in `start`, `drain` or a route it is core's `CONTRIBUTIONS_CLOSED`).
|
|
96
|
+
- **The module boundary holds**: the contributed objects get the services the module built; nothing builds them again. Another module that contributes tools for this one lists it in `requires` and reads `module.get(workspace).documents`. Never write a separate `definePlugin` that builds the services a second time, and never register an app plugin by hand in `src/main.ts` or `src/infra/runtime/application.ts` for this: `npx dokebi describe` and the tests build the app from the generated registration and do not see it, and doctor and check do not read it.
|
|
97
|
+
- **A module never collects**: `module.collect` is `UNDECLARED_POINT` (collecting is a plugin's role).
|
|
98
|
+
- **No collector**: when no registered plugin collects a point (its plugin is not installed, or a test app leaves it out), the start goes on, the values are dropped and the module hears warn `POINT_NOT_COLLECTED` once per point (`point`, `count`, `fix`). Module tests without the MCP stack keep working; `npx dokebi check` makes the missing plugin an error (`module-point-not-installed`).
|
|
99
|
+
- A module that `requires` the collector of a point it contributes to is a `DEPENDENCY_CYCLE` (the contributor must set up first). Values with rules of their own are checked by the collector (two tools with one name: @dokebi/mcp's `INVALID_TOOL`, naming both modules).
|
|
100
|
+
|
|
68
101
|
## 4. View lookup order (how an app changes a module page)
|
|
69
102
|
|
|
70
103
|
1. `<app>/<template>/<module>/…`
|
|
@@ -82,18 +115,29 @@ To change a module page, an app never edits the module file; it puts a file with
|
|
|
82
115
|
- Hooks: setup (register routes, return the API) → start → drain (stop new input, wait for work in progress) → deferred cleanup. Drain runs in reverse dependency order (modules that depend on this one first); unrelated modules drain at the same time.
|
|
83
116
|
- A module instance is used by one Application only. There is no automatic discovery, dynamic import or hot reload while running.
|
|
84
117
|
- Options of the group plugin are an empty object.
|
|
85
|
-
- Debug logs (D-0047): `Modules registered` (the group), `Module set up` (requires, number of controllers, views prefix, whether routes, sockets and events exist, ms), `Module start finished`, `Module drain finished`. A missing or unreadable `views/default/` fails the start, with the original file error kept as `cause`.
|
|
118
|
+
- Debug logs (D-0047): `Modules registered` (the group), `Module set up` (requires, number of controllers, contributes, views prefix, whether routes, sockets and events exist, ms), `Module start finished`, `Module drain finished`. A missing or unreadable `views/default/` fails the start, with the original file error kept as `cause`.
|
|
86
119
|
|
|
87
120
|
## 6. Errors
|
|
88
121
|
|
|
89
122
|
<!-- docs-check: complete-error-codes ModuleErrorCode -->
|
|
90
|
-
`DokebiError` (`plugin: 'dokebi-module'`, a `fix` that says how to repair it): `INVALID_DEFINITION` (arguments of `defineModule`), `INVALID_REQUIREMENT` (shape of requires, duplicate names), `INVALID_ENTRY` (the group entry file; at registration the cause of `INVALID_PLUGIN_INPUT`), `ALREADY_SET_UP` (one instance in two apps), `NOT_SET_UP` (context used before setup), `NO_CONTROLLERS`, `VIEWS_MISSING` (no `views/default/`; the file error is the `cause`). Options of the group plugin other than an empty object are `INVALID_PLUGIN_OPTIONS` (cause `INVALID_OPTIONS`). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand). Before 0.4.0 the codes had a `MODULE_` prefix (D-0071).
|
|
123
|
+
`DokebiError` (`plugin: 'dokebi-module'`, a `fix` that says how to repair it): `INVALID_DEFINITION` (arguments of `defineModule`), `INVALID_REQUIREMENT` (shape of requires, duplicate names), `INVALID_ENTRY` (the group entry file; at registration the cause of `INVALID_PLUGIN_INPUT`), `ALREADY_SET_UP` (one instance in two apps), `NOT_SET_UP` (context used before setup), `NO_CONTROLLERS`, `VIEWS_MISSING` (no `views/default/`; the file error is the `cause`), `INVALID_CONTRIBUTION` (`contributes` is not a list of distinct points made by `definePoint`, or has more than 64), `UNDECLARED_POINT` (`module.contribute` to a point missing from `contributes`, or `module.collect`; the `fix` names the module). Warn log `POINT_NOT_COLLECTED` (core): values no registered plugin collects were dropped. Options of the group plugin other than an empty object are `INVALID_PLUGIN_OPTIONS` (cause `INVALID_OPTIONS`). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand). Before 0.4.0 the codes had a `MODULE_` prefix (D-0071).
|
|
91
124
|
|
|
92
125
|
## 7. Cautions
|
|
93
126
|
|
|
94
127
|
- A module does not depend on apps (never branch on an app name). Handle per-app differences with `page.app` and the app's view overrides.
|
|
95
128
|
- `moduleMount` and `MODULE_MOUNT` are the internal link @dokebi/app uses. App code does not use them.
|
|
96
|
-
- Socket and SSE route types (`ModuleSocketRoute`, `ModuleEventRoute`) are defined by shape only, so projects that do not use them need neither @dokebi/websocket nor @dokebi/sse. When used, add that package (otherwise the app start fails: `has sockets; add @dokebi/websocket`, `has event streams; add @dokebi/sse`).
|
|
129
|
+
- Socket and SSE route types (`ModuleSocketRoute`, `ModuleEventRoute`) are defined by shape only, so projects that do not use them need neither @dokebi/websocket nor @dokebi/sse. When used, add that package (otherwise the app start fails: `has sockets; add @dokebi/websocket`, `has event streams; add @dokebi/sse`). Both take `config: { id }`, the route id (D-0140), like the module's routes: it must be unique among the routes, sockets and streams of each app that mounts the module (`DUPLICATE_ROUTE_ID` at start otherwise).
|
|
97
130
|
- Do not treat the end of a response or a dropped connection as the work being done. Work detached from the request is awaited in the module's `drain`.
|
|
98
131
|
|
|
99
132
|
References: `examples/26-scaffold` (repeated generation, mounting and overriding), `examples/25-playground` (eight feature modules; the sse module mounts `/api/sse/events` on every app through `events`), `examples/22-web/main.ts` (assembled in code), D-0022, D-0032.
|
|
133
|
+
|
|
134
|
+
## Service composition
|
|
135
|
+
|
|
136
|
+
Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
|
|
137
|
+
services provide data and coordinate workflows through models; models own persistence.
|
|
138
|
+
Generated app/module starters include this chain. Keep services free of request/reply and
|
|
139
|
+
rendering objects, and reuse them from jobs. Compose dependencies once during setup.
|
|
140
|
+
App-specific services belong in `src/apps/<app>/services`, cross-app services in
|
|
141
|
+
`src/shared/services`, and module services in `src/shared/modules/<module>/services`.
|
|
142
|
+
Shared services must not import app-specific code. These are ordinary application classes,
|
|
143
|
+
not a new framework plugin or service registry. Existing projects are not moved automatically.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# @dokebi/module 0.4.
|
|
1
|
+
# @dokebi/module 0.4.1
|
|
2
2
|
|
|
3
|
-
An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). A module is **one feature as an MVC unit of business code** ([D-0022](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0022-plugin-boundaries-and-db.md), [D-0032](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0032-feature-modules.md)). It keeps controllers, models, views, routes and sockets in one folder, and apps mount it under a prefix. It is not an HTTP-only bundle, so business code without a web side (job processing, event subscriptions) is a module too.
|
|
3
|
+
An optional package for Node >=24.0.0 and core ^0.4.0 (public on npm). A module is **one feature as an MVC unit of business code** ([D-0022](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0022-plugin-boundaries-and-db.md), [D-0032](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0032-feature-modules.md)). It keeps controllers, services, models, views, routes and sockets in one folder, and apps mount it under a prefix. It is not an HTTP-only bundle, so business code without a web side (job processing, event subscriptions) is a module too.
|
|
4
4
|
|
|
5
5
|
## Folder
|
|
6
6
|
|
|
@@ -23,6 +23,7 @@ export default defineModule({
|
|
|
23
23
|
name: 'board', // the folder name; the ID is dokebi-module.board
|
|
24
24
|
requires: [db, other], // plugin instances, descriptors, other modules
|
|
25
25
|
controllers: [postsController], // created once with the module context
|
|
26
|
+
contributes: [mcpTools], // points of plugins it contributes to; module.contribute in setup
|
|
26
27
|
views: new URL('./views/', import.meta.url), // default/ required; template names get the prefix module.board
|
|
27
28
|
routes(route, module) { // registered per app (when mounted). page = { app, module, base, view, inertia }
|
|
28
29
|
route.get('/', (request, reply, page) =>
|
|
@@ -42,6 +43,7 @@ export default defineModule({
|
|
|
42
43
|
- **`views`:** adds a template-ejs dependency automatically. Without `views/default/` the start fails.
|
|
43
44
|
- **`controllers`:** uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers fails with `declares no controllers`.
|
|
44
45
|
- **`setup`:** optional. The older `setup(context)` form still works.
|
|
46
|
+
- **`contributes`** ([D-0130](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0130-module-contributions.md)): the points of other plugins this module contributes to (for example `mcpTools` of @dokebi/mcp). `setup` calls `module.contribute(point, value)` with objects that use the module's own services; core sets the module up before every collector of the point. A point that nothing collects drops its values with warn `POINT_NOT_COLLECTED`; an undeclared point is `UNDECLARED_POINT`; modules never collect. See AI.md §3a.
|
|
45
47
|
- **Shared APIs:** APIs that must answer on every domain are registered directly with router or web in setup, for example the playground's `/api/*`.
|
|
46
48
|
- **Mounting on apps:** `defineApp({ modules: { '/board': board } })`. Routes and sockets answer only on that app's domains and prefix. A mounted module's API is readable with `app.get(board)` without listing it in the app's `requires`. Details are in [@dokebi/app](https://git.nyx-zone.com/dokebi/framework/-/blob/main/plugins/dokebi-app/README.md).
|
|
47
49
|
- **View lookup order:**
|
|
@@ -76,3 +78,14 @@ Examples:
|
|
|
76
78
|
- `examples/22-web/main.ts`: assembled in code
|
|
77
79
|
|
|
78
80
|
See the [AI guide](AI.md) for errors and cautions.
|
|
81
|
+
|
|
82
|
+
## Service composition
|
|
83
|
+
|
|
84
|
+
Use Controller -> Service -> Model for application data. Controllers handle HTTP input/output;
|
|
85
|
+
services provide data and coordinate workflows through models; models own persistence.
|
|
86
|
+
Generated app/module starters include this chain. Keep services free of request/reply and
|
|
87
|
+
rendering objects, and reuse them from jobs. Compose dependencies once during setup.
|
|
88
|
+
App-specific services belong in `src/apps/<app>/services`, cross-app services in
|
|
89
|
+
`src/shared/services`, and module services in `src/shared/modules/<module>/services`.
|
|
90
|
+
Shared services must not import app-specific code. These are ordinary application classes,
|
|
91
|
+
not a new framework plugin or service registry. Existing projects are not moved automatically.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
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
7
|
/** 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';
|
|
8
|
+
export type ModuleErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUIREMENT' | 'INVALID_ENTRY' | 'ALREADY_SET_UP' | 'NOT_SET_UP' | 'NO_CONTROLLERS' | 'VIEWS_MISSING' | 'INVALID_CONTRIBUTION' | 'UNDECLARED_POINT';
|
|
9
9
|
/** A plugin instance (read with context.get) or a descriptor (read with context.getDependency). */
|
|
10
10
|
export type ModuleRequirement = Plugin<unknown> | PluginDependency;
|
|
11
11
|
/** The plugin context of a module, plus the controllers the module declares. */
|
|
@@ -52,6 +52,10 @@ export interface ModuleRouter {
|
|
|
52
52
|
*/
|
|
53
53
|
export interface ModuleSocketRoute {
|
|
54
54
|
readonly path: string;
|
|
55
|
+
/** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
|
|
56
|
+
readonly config?: {
|
|
57
|
+
readonly id?: string;
|
|
58
|
+
};
|
|
55
59
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
56
60
|
/**
|
|
57
61
|
* `namespace` (D-0061): one of the mounting app's `realtime.namespaces` (default its first);
|
|
@@ -69,6 +73,10 @@ export interface ModuleSocketRoute {
|
|
|
69
73
|
*/
|
|
70
74
|
export interface ModuleEventRoute {
|
|
71
75
|
readonly path: string;
|
|
76
|
+
/** `{ id }`: the route id (D-0140), unique in each app that mounts the module. */
|
|
77
|
+
readonly config?: {
|
|
78
|
+
readonly id?: string;
|
|
79
|
+
};
|
|
72
80
|
readonly constraints?: Readonly<Record<string, unknown>>;
|
|
73
81
|
authenticate(request: FastifyRequest): Awaitable<{
|
|
74
82
|
readonly tenant: string;
|
|
@@ -82,6 +90,13 @@ export interface ModuleDefinition<T> {
|
|
|
82
90
|
readonly requires?: readonly ModuleRequirement[];
|
|
83
91
|
/** `defineController` tokens, built once with this module's context. */
|
|
84
92
|
readonly controllers?: readonly ControllerDefinition<unknown>[];
|
|
93
|
+
/**
|
|
94
|
+
* Points this module contributes to (D-0130), made by `definePoint` and imported from the
|
|
95
|
+
* plugin that owns them (for example `mcpTools` of @dokebi/mcp). The module's setup calls
|
|
96
|
+
* `module.contribute(point, value)`; core sets the module up before every collector of the
|
|
97
|
+
* point. Values that no registered plugin collects are dropped with warn `POINT_NOT_COLLECTED`.
|
|
98
|
+
*/
|
|
99
|
+
readonly contributes?: readonly Pick<ContributionPoint<unknown>, 'name'>[];
|
|
85
100
|
/** Folder with one sub-folder per template (`default/` is required). */
|
|
86
101
|
readonly views?: URL;
|
|
87
102
|
/** Routes registered by every app that mounts this module (`defineApp({ modules })`). */
|
package/dist/index.js
CHANGED
|
@@ -11,21 +11,27 @@ const FIX = {
|
|
|
11
11
|
NOT_SET_UP: 'Read the module context after the module plugin has set up.',
|
|
12
12
|
NO_CONTROLLERS: 'Add the controller token to controllers of defineModule before calling module.controller().',
|
|
13
13
|
VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
|
|
14
|
+
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).',
|
|
15
|
+
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.',
|
|
14
16
|
};
|
|
15
|
-
function moduleError(code, message, cause) {
|
|
17
|
+
function moduleError(code, message, cause, fix = FIX[code]) {
|
|
16
18
|
return new DokebiError(code, message, {
|
|
17
19
|
plugin: 'dokebi-module',
|
|
18
|
-
fix
|
|
20
|
+
fix,
|
|
19
21
|
...(cause === undefined ? {} : { cause }),
|
|
20
22
|
});
|
|
21
23
|
}
|
|
22
24
|
export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
|
|
23
25
|
const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
26
|
+
/** core's point name (`<owner plugin>:<name>`) and its limit per plugin (D-0063). */
|
|
27
|
+
const POINT_NAME = /^[a-z0-9][a-z0-9._/-]{0,95}:[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
28
|
+
const POINT_LIMIT = 64;
|
|
24
29
|
const DEFINITION_KEYS = new Set([
|
|
25
30
|
'name',
|
|
26
31
|
'version',
|
|
27
32
|
'requires',
|
|
28
33
|
'controllers',
|
|
34
|
+
'contributes',
|
|
29
35
|
'views',
|
|
30
36
|
'routes',
|
|
31
37
|
'sockets',
|
|
@@ -49,7 +55,27 @@ function requirement(value) {
|
|
|
49
55
|
throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
|
|
50
56
|
return value;
|
|
51
57
|
}
|
|
52
|
-
|
|
58
|
+
/** The point names of `contributes` (D-0130): made by definePoint, distinct, at most 64. */
|
|
59
|
+
function contributedPoints(value, module) {
|
|
60
|
+
if (value === undefined)
|
|
61
|
+
return Object.freeze([]);
|
|
62
|
+
const invalid = (detail) => moduleError('INVALID_CONTRIBUTION', `Invalid contributes of module ${module}: ${detail}`);
|
|
63
|
+
if (!Array.isArray(value) || types.isProxy(value))
|
|
64
|
+
throw invalid('expected an array of points');
|
|
65
|
+
if (value.length > POINT_LIMIT)
|
|
66
|
+
throw invalid(`more than ${POINT_LIMIT} points`);
|
|
67
|
+
const names = new Set();
|
|
68
|
+
for (const point of value) {
|
|
69
|
+
const name = point?.name;
|
|
70
|
+
if (typeof name !== 'string' || !POINT_NAME.test(name))
|
|
71
|
+
throw invalid('a point made by definePoint (<owner plugin>:<name>) was expected');
|
|
72
|
+
if (names.has(name))
|
|
73
|
+
throw invalid(`${name} is listed twice`);
|
|
74
|
+
names.add(name);
|
|
75
|
+
}
|
|
76
|
+
return Object.freeze([...names]);
|
|
77
|
+
}
|
|
78
|
+
function moduleContext(context, name, declared, controllers, points) {
|
|
53
79
|
// core accepts only the descriptor object this module declared; look it up by name.
|
|
54
80
|
const own = (dependency) => declared.get(dependency?.name) ?? dependency;
|
|
55
81
|
return Object.freeze({
|
|
@@ -66,16 +92,29 @@ function moduleContext(context, name, declared, controllers) {
|
|
|
66
92
|
get drainSignal() {
|
|
67
93
|
return context.drainSignal;
|
|
68
94
|
},
|
|
95
|
+
// Set when the drain phase starts: read it there, not at setup.
|
|
96
|
+
get drainDeadline() {
|
|
97
|
+
return context.drainDeadline;
|
|
98
|
+
},
|
|
69
99
|
// The same frozen object for the whole application (core's own).
|
|
70
100
|
runtime: context.runtime,
|
|
71
101
|
get: (plugin) => context.get(plugin),
|
|
72
102
|
getDependency: (dependency) => context.getDependency(own(dependency)),
|
|
73
103
|
getOptionalDependency: (dependency) => context.getOptionalDependency(own(dependency)),
|
|
74
104
|
defer: (cleanup) => context.defer(cleanup),
|
|
75
|
-
//
|
|
76
|
-
//
|
|
77
|
-
contribute: (point, value) =>
|
|
78
|
-
|
|
105
|
+
// D-0130: a module contributes to the points of its `contributes`; core then checks the
|
|
106
|
+
// phase (CONTRIBUTIONS_CLOSED outside the module's setup) and orders the collectors after it.
|
|
107
|
+
contribute: (point, value) => {
|
|
108
|
+
const pointName = point?.name;
|
|
109
|
+
if (typeof pointName === 'string' && POINT_NAME.test(pointName) && !points.has(pointName))
|
|
110
|
+
throw moduleError('UNDECLARED_POINT', `Module ${name} does not declare the point ${pointName}`, undefined, `Add ${pointName} to contributes of defineModule({ name: '${name}', contributes: [...] }).`);
|
|
111
|
+
context.contribute(point, value);
|
|
112
|
+
},
|
|
113
|
+
// Modules never collect: reading a point is a plugin's role (definePlugin collects).
|
|
114
|
+
collect: (point) => {
|
|
115
|
+
const pointName = point?.name;
|
|
116
|
+
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.');
|
|
117
|
+
},
|
|
79
118
|
controller: (definition) => {
|
|
80
119
|
const api = controllers();
|
|
81
120
|
if (!api)
|
|
@@ -100,6 +139,8 @@ export function defineModule(definition) {
|
|
|
100
139
|
['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
101
140
|
throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
|
|
102
141
|
const { name, views } = definition;
|
|
142
|
+
const points = contributedPoints(definition.contributes, name);
|
|
143
|
+
const pointSet = new Set(points);
|
|
103
144
|
const dependencies = (definition.requires ?? []).map(requirement);
|
|
104
145
|
if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
|
|
105
146
|
throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
|
|
@@ -114,7 +155,7 @@ export function defineModule(definition) {
|
|
|
114
155
|
const prefix = `module.${name}`;
|
|
115
156
|
const hook = (key) => async (context) => {
|
|
116
157
|
const begin = performance.now();
|
|
117
|
-
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers));
|
|
158
|
+
await definition[key]?.(current ?? moduleContext(context, name, declared, () => controllers, pointSet));
|
|
118
159
|
context.logger.log('debug', `Module ${key} finished`, {
|
|
119
160
|
module: name,
|
|
120
161
|
ms: Math.round(performance.now() - begin),
|
|
@@ -126,12 +167,14 @@ export function defineModule(definition) {
|
|
|
126
167
|
version,
|
|
127
168
|
core: '^0.4.0',
|
|
128
169
|
dependencies: Object.freeze(dependencies),
|
|
170
|
+
// D-0130: declared when the module is defined, so core orders the collectors after it.
|
|
171
|
+
...(points.length ? { contributes: points, uncollected: 'warn' } : {}),
|
|
129
172
|
}),
|
|
130
173
|
async setup(context) {
|
|
131
174
|
if (started)
|
|
132
175
|
throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
|
|
133
176
|
started = true;
|
|
134
|
-
current = moduleContext(context, name, declared, () => controllers);
|
|
177
|
+
current = moduleContext(context, name, declared, () => controllers, pointSet);
|
|
135
178
|
const begin = performance.now();
|
|
136
179
|
if (definition.controllers?.length) {
|
|
137
180
|
const { createControllers } = await import('@dokebi/controller');
|
|
@@ -155,6 +198,7 @@ export function defineModule(definition) {
|
|
|
155
198
|
version,
|
|
156
199
|
requires: dependencies.map((dependency) => dependency.name),
|
|
157
200
|
controllers: definition.controllers?.length ?? 0,
|
|
201
|
+
contributes: points,
|
|
158
202
|
views: views ? prefix : false,
|
|
159
203
|
routes: Boolean(definition.routes),
|
|
160
204
|
sockets: Boolean(definition.sockets),
|
|
@@ -231,7 +275,7 @@ class ModuleGroupRuntime {
|
|
|
231
275
|
}
|
|
232
276
|
export const createPlugin = definePlugin({
|
|
233
277
|
name: 'dokebi-module',
|
|
234
|
-
version: '0.4.
|
|
278
|
+
version: '0.4.1',
|
|
235
279
|
core: '^0.4.0',
|
|
236
280
|
options,
|
|
237
281
|
entry: parseEntry,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/module",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Feature modules for Dokebi apps: controllers, models, views and routes in one folder mounted under a prefix.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dokebi",
|
|
@@ -93,10 +93,10 @@
|
|
|
93
93
|
}
|
|
94
94
|
},
|
|
95
95
|
"devDependencies": {
|
|
96
|
-
"@dokebi/controller": "0.4.
|
|
97
|
-
"@dokebi/template-ejs": "0.4.
|
|
98
|
-
"@dokebi/template-inertia": "0.4.
|
|
99
|
-
"@dokebi/web": "0.4.
|
|
96
|
+
"@dokebi/controller": "0.4.2",
|
|
97
|
+
"@dokebi/template-ejs": "0.4.3",
|
|
98
|
+
"@dokebi/template-inertia": "0.4.4",
|
|
99
|
+
"@dokebi/web": "0.4.3"
|
|
100
100
|
},
|
|
101
101
|
"publishConfig": {
|
|
102
102
|
"access": "public",
|
|
@@ -1,11 +1,22 @@
|
|
|
1
1
|
import { defineController } from '@dokebi/controller';
|
|
2
2
|
import type { ModulePage } from '@dokebi/module';
|
|
3
|
-
import {
|
|
3
|
+
import { ItemsService } from '../services/items.ts';
|
|
4
4
|
|
|
5
5
|
export class ItemsController {
|
|
6
|
+
readonly #service: ItemsService;
|
|
7
|
+
constructor(service: ItemsService) {
|
|
8
|
+
this.#service = service;
|
|
9
|
+
}
|
|
6
10
|
list(page: ModulePage) {
|
|
7
|
-
return {
|
|
11
|
+
return this.#service.list({
|
|
12
|
+
appName: page.app.name,
|
|
13
|
+
base: page.base,
|
|
14
|
+
template: page.app.template,
|
|
15
|
+
});
|
|
8
16
|
}
|
|
9
17
|
}
|
|
10
18
|
// Built once with this module's context; read it with module.controller(itemsController).
|
|
11
|
-
export const itemsController = defineController(
|
|
19
|
+
export const itemsController = defineController(
|
|
20
|
+
'items',
|
|
21
|
+
() => new ItemsController(new ItemsService()),
|
|
22
|
+
);
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
export type ModuleIdentity = { appName: string; base: string; template: string };
|
|
2
2
|
|
|
3
|
-
/**
|
|
4
|
-
export function summary(
|
|
5
|
-
return `{{module}} module in app ${
|
|
3
|
+
/** A pure model for this starter; services provide data without HTTP objects. */
|
|
4
|
+
export function summary(module: ModuleIdentity): string {
|
|
5
|
+
return `{{module}} module in app ${module.appName} at ${module.base || '/'} (template: ${module.template})`;
|
|
6
6
|
}
|
|
@@ -11,6 +11,10 @@ export default defineModule({
|
|
|
11
11
|
// Plugins and other modules this module uses (instances or dependency descriptors).
|
|
12
12
|
requires: [],
|
|
13
13
|
controllers: [itemsController],
|
|
14
|
+
// Points of plugins this module contributes to (D-0130), for example MCP tools:
|
|
15
|
+
// contributes: [mcpTools], // import { mcpTools } from '@dokebi/mcp'
|
|
16
|
+
// setup(module) { module.contribute(mcpTools, new ListItems(service)); },
|
|
17
|
+
// The contributed objects use this module's own services; the collector sets up after it.
|
|
14
18
|
// One folder per template; `default` is required. An app replaces a file of this module by
|
|
15
19
|
// putting it in src/apps/<app>/views/<template>/{{module}}/.
|
|
16
20
|
views: new URL('./views/', import.meta.url),
|
|
@@ -1,11 +1,22 @@
|
|
|
1
1
|
import { defineController } from '@dokebi/controller';
|
|
2
2
|
import type { ModulePage } from '@dokebi/module';
|
|
3
|
-
import {
|
|
3
|
+
import { ItemsService } from '../services/items.ts';
|
|
4
4
|
|
|
5
5
|
export class ItemsController {
|
|
6
|
+
readonly #service: ItemsService;
|
|
7
|
+
constructor(service: ItemsService) {
|
|
8
|
+
this.#service = service;
|
|
9
|
+
}
|
|
6
10
|
list(page: ModulePage) {
|
|
7
|
-
return {
|
|
11
|
+
return this.#service.list({
|
|
12
|
+
appName: page.app.name,
|
|
13
|
+
base: page.base,
|
|
14
|
+
template: page.app.template,
|
|
15
|
+
});
|
|
8
16
|
}
|
|
9
17
|
}
|
|
10
18
|
// Built once with this module's context; read it with module.controller(itemsController).
|
|
11
|
-
export const itemsController = defineController(
|
|
19
|
+
export const itemsController = defineController(
|
|
20
|
+
'items',
|
|
21
|
+
() => new ItemsController(new ItemsService()),
|
|
22
|
+
);
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
export type ModuleIdentity = { appName: string; base: string; template: string };
|
|
2
2
|
|
|
3
|
-
/**
|
|
4
|
-
export function summary(
|
|
5
|
-
return `{{module}} module in app ${
|
|
3
|
+
/** A pure model for this starter; services provide data without HTTP objects. */
|
|
4
|
+
export function summary(module: ModuleIdentity): string {
|
|
5
|
+
return `{{module}} module in app ${module.appName} at ${module.base || '/'} (template: ${module.template})`;
|
|
6
6
|
}
|
|
@@ -12,5 +12,9 @@ export default defineModule({
|
|
|
12
12
|
// Plugins and other modules this module uses (instances or dependency descriptors).
|
|
13
13
|
requires: [],
|
|
14
14
|
controllers: [itemsController],
|
|
15
|
+
// Points of plugins this module contributes to (D-0130), for example MCP tools:
|
|
16
|
+
// contributes: [mcpTools], // import { mcpTools } from '@dokebi/mcp'
|
|
17
|
+
// setup(module) { module.contribute(mcpTools, new ListItems(service)); },
|
|
18
|
+
// The contributed objects use this module's own services; the collector sets up after it.
|
|
15
19
|
routes,
|
|
16
20
|
});
|