@dokebi/module 0.1.3 → 0.4.0
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 +59 -48
- package/README.md +54 -52
- package/dist/index.d.ts +2 -0
- package/dist/index.js +41 -28
- package/dist/options.d.ts +7 -0
- package/dist/options.js +6 -0
- package/package.json +39 -13
package/AI.md
CHANGED
|
@@ -1,88 +1,99 @@
|
|
|
1
|
-
# AI
|
|
1
|
+
# AI guide — @dokebi/module 0.4.0
|
|
2
2
|
|
|
3
|
-
|
|
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).
|
|
4
4
|
|
|
5
|
-
## 1.
|
|
5
|
+
## 1. Creating modules
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
|
-
npx dokebi add @dokebi/module # src/shared/modules/
|
|
9
|
-
npx dokebi module add board #
|
|
10
|
-
npx dokebi module add stats --no-views #
|
|
11
|
-
npx dokebi module remove board #
|
|
8
|
+
npx dokebi add @dokebi/module # prepares src/shared/modules/
|
|
9
|
+
npx dokebi module add board # a module with pages (includes views/default)
|
|
10
|
+
npx dokebi module add stats --no-views # a module whose routes return JSON
|
|
11
|
+
npx dokebi module remove board # removes only the registration; the folder stays
|
|
12
12
|
npx dokebi module list
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
> `npx dokebi` is the @dokebi/cli installed in the project (`dokebi init` adds it to devDependencies). The npm package `dokebi` is not this CLI, so never use `npx -y dokebi`. Without an installed CLI use `npx -y @dokebi/cli …`.
|
|
16
|
+
|
|
17
|
+
A hand-made module folder is not registered. The generated registration code passes each module's default export to the group plugin's entry.
|
|
16
18
|
|
|
17
19
|
```
|
|
18
|
-
src/shared/modules
|
|
20
|
+
src/shared/modules/<module>/
|
|
19
21
|
module.ts export default defineModule({ ... })
|
|
20
|
-
routes.ts
|
|
21
|
-
controllers/ models/ views/default/(
|
|
22
|
+
routes.ts routes registered when an app mounts the module
|
|
23
|
+
controllers/ models/ views/default/ (modules with pages) sockets/ (when needed)
|
|
22
24
|
```
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
Do not scatter controllers, models and views into layer folders (`src/shared/controllers` and so on).
|
|
25
27
|
|
|
26
28
|
## 2. defineModule
|
|
27
29
|
|
|
28
|
-
```ts
|
|
30
|
+
```ts snippet
|
|
29
31
|
import { defineModule } from '@dokebi/module';
|
|
30
32
|
import { dependency as db } from '@dokebi/db';
|
|
31
33
|
import { postsController } from './controllers/posts.ts';
|
|
32
34
|
|
|
33
35
|
export default defineModule({
|
|
34
|
-
name: 'board', //
|
|
35
|
-
requires: [db], //
|
|
36
|
+
name: 'board', // the folder name; the plugin id is dokebi-module.board
|
|
37
|
+
requires: [db], // instances, descriptors, other modules
|
|
36
38
|
controllers: [postsController],
|
|
37
|
-
views: new URL('./views/', import.meta.url), // default/
|
|
38
|
-
routes(route, module) { //
|
|
39
|
+
views: new URL('./views/', import.meta.url), // default/ is required (adds a template-ejs dependency)
|
|
40
|
+
routes(route, module) { // registered for every app that mounts it, on that app's domains and prefix
|
|
39
41
|
route.get('/', async (request, reply, page) =>
|
|
40
42
|
page.view.reply(reply, 'index', { posts: await module.controller(postsController).list(), base: page.base }),
|
|
41
43
|
);
|
|
42
44
|
route.post('/', async (request, reply, page) => { /* ... */ });
|
|
43
45
|
},
|
|
44
|
-
sockets: (module) => [boardSocket(module)], // defineSocket
|
|
45
|
-
events: (module) => [boardStream(module)], // (0.1.3) @dokebi/sse
|
|
46
|
-
setup(module) { return { count: () => module.controller(postsController).count() }; }, //
|
|
46
|
+
sockets: (module) => [boardSocket(module)], // defineSocket results; tenant is <namespace>:<tenant>
|
|
47
|
+
events: (module) => [boardStream(module)], // (0.1.3) @dokebi/sse routes (SseRoute); same rules as sockets
|
|
48
|
+
setup(module) { return { count: () => module.controller(postsController).count() }; }, // the API others receive
|
|
47
49
|
start(module) {}, drain(module) {},
|
|
48
50
|
});
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
- `module`(ModuleContext) = PluginContext + `module`(
|
|
52
|
-
- `page`(ModulePage) = `{ app: { name, template, domain }, module, base, view, inertia }`.
|
|
53
|
-
- `version
|
|
54
|
-
-
|
|
53
|
+
- `module` (ModuleContext) = PluginContext + `module` (the name) + `controller(token)`. Only what `requires` declares can be read with `get` or `getDependency`. When a controller factory passes a freshly built descriptor object, the declared descriptor with that name is found.
|
|
54
|
+
- `page` (ModulePage) = `{ app: { name, template, domain }, module, base, view, inertia }`. Build links with `page.base` (each app may use a different prefix).
|
|
55
|
+
- `version` is an exact semver (default `'0.1.0'`). Requires with duplicate names are refused.
|
|
56
|
+
- `views`: adds a template-ejs dependency automatically; the start fails without `views/default/`. Template names get the prefix `module.<name>`.
|
|
57
|
+
- `controllers`: uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers is `NO_CONTROLLERS` (`declares no controllers`).
|
|
58
|
+
- `module.runtime` is core's runtime role (`solo`, `primary`, `worker`; D-0063 §4). Do not read `node:cluster` yourself.
|
|
59
|
+
- Route options are `WebRoute` options without `handler` and `constraints` (`ModuleRouteOptions`, so `seal` works).
|
|
60
|
+
|
|
61
|
+
## 3. Mounting on apps and shared APIs
|
|
62
|
+
|
|
63
|
+
- App: `defineApp({ modules: { '/board': board } })`. Routes, sockets and SSE routes answer **only on that app's domains and prefix**. Several apps can mount the same module under different prefixes. The root route (`'/'`) answers `/board` and `/board/`; other paths match exactly. Build links with `page.base` (for example `${page.base}/new`).
|
|
64
|
+
- The hub tenant of sockets and SSE routes (`events`, 0.1.3) follows the mounting app's rules ([D-0061](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0061-realtime-namespaces.md)): `<namespace>:<authenticated tenant>`, and a `namespace` returned by `authenticate` must be in the mounting app's `realtime.namespaces` (otherwise 401). The module context has no `realtime` handle. Publish with @dokebi/sse `publish({ tenantPrefix: '<namespace>:' }, …)` or the app's `app.realtime(ns).publish`. `events` are mounted by @dokebi/app 0.2.0 or later (0.1.x apps do not read the field, so no stream is created).
|
|
65
|
+
- 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
|
+
- 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.
|
|
55
67
|
|
|
56
|
-
##
|
|
68
|
+
## 4. View lookup order (how an app changes a module page)
|
|
57
69
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
70
|
+
1. `<app>/<template>/<module>/…`
|
|
71
|
+
2. `<app>/default/<module>/…`
|
|
72
|
+
3. the module's `<template>/…`
|
|
73
|
+
4. the module's `default/…`
|
|
74
|
+
5. the app's views (layouts and partials)
|
|
75
|
+
6. shared `src/shared/views`
|
|
62
76
|
|
|
63
|
-
|
|
77
|
+
To change a module page, an app never edits the module file; it puts a file with the same name into `src/apps/<app>/views/<template>/<module>/`. When an Inertia app mounts the module, the module produces props with `page.inertia.render(request, reply, 'Component', props)` and the Vue pages live in the app's `views/<template>/Pages/`.
|
|
64
78
|
|
|
65
|
-
|
|
66
|
-
2. `<앱>/default/<모듈>/…`
|
|
67
|
-
3. 모듈의 `<템플릿>/…`
|
|
68
|
-
4. 모듈의 `default/…`
|
|
69
|
-
5. 앱 views(레이아웃·부분 템플릿)
|
|
70
|
-
6. 공통 `src/shared/views`
|
|
79
|
+
## 5. Group plugin and lifecycle
|
|
71
80
|
|
|
72
|
-
|
|
81
|
+
- `createPlugin({ app, entry: { modules } })`: groups several modules into a dependency graph. The API is `{ names }` (`ModuleGroupApi`). It accepts only what `defineModule` made; duplicates are `INVALID_PLUGIN_INPUT`. A single module may also be registered directly with `app.register`.
|
|
82
|
+
- 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
|
+
- A module instance is used by one Application only. There is no automatic discovery, dynamic import or hot reload while running.
|
|
84
|
+
- 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`.
|
|
73
86
|
|
|
74
|
-
##
|
|
87
|
+
## 6. Errors
|
|
75
88
|
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
- 모듈 인스턴스는 Application 하나에만 쓴다. 실행 중 자동 검색·동적 import·hot reload는 없다.
|
|
79
|
-
- debug 로그(D-0047): `Modules registered`(묶음)·`Module set up`(requires·컨트롤러 수·views 접두사·routes·sockets·events 유무·ms)·`Module start finished`·`Module drain finished`. `views/default/`가 없거나 읽을 수 없으면 시작 실패이고 원래 파일 오류는 `cause`에 남는다.
|
|
89
|
+
<!-- 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).
|
|
80
91
|
|
|
81
|
-
##
|
|
92
|
+
## 7. Cautions
|
|
82
93
|
|
|
83
|
-
-
|
|
84
|
-
- `moduleMount
|
|
85
|
-
-
|
|
86
|
-
-
|
|
94
|
+
- 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
|
+
- `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`).
|
|
97
|
+
- 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`.
|
|
87
98
|
|
|
88
|
-
|
|
99
|
+
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.
|
package/README.md
CHANGED
|
@@ -1,76 +1,78 @@
|
|
|
1
|
-
# @dokebi/module 0.
|
|
1
|
+
# @dokebi/module 0.4.0
|
|
2
2
|
|
|
3
|
-
Node >=24.0.0
|
|
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.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Folder
|
|
6
6
|
|
|
7
7
|
```
|
|
8
|
-
src/shared/modules
|
|
8
|
+
src/shared/modules/<module>/
|
|
9
9
|
module.ts export default defineModule({ ... })
|
|
10
|
-
routes.ts
|
|
11
|
-
controllers/
|
|
12
|
-
models/
|
|
13
|
-
views/default/ (
|
|
14
|
-
sockets/ (
|
|
10
|
+
routes.ts routes registered when an app mounts the module
|
|
11
|
+
controllers/ this module's controllers (created once in the module's setup)
|
|
12
|
+
models/ this module's models (plain code)
|
|
13
|
+
views/default/ (modules with pages only) EJS views; other templates hold only changed files
|
|
14
|
+
sockets/ (when needed) defineSocket
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
`dokebi module add
|
|
17
|
+
`dokebi module add <name>` creates the skeleton and adds it to the generated registration code. Create a module without pages with `--no-views`; its routes then return JSON. `dokebi module remove <name>` removes only the registration and leaves the folder. `dokebi module list` shows the list. `dokebi add @dokebi/module` only creates the `src/shared/modules/` folder.
|
|
18
18
|
|
|
19
19
|
## defineModule
|
|
20
20
|
|
|
21
|
-
```ts
|
|
21
|
+
```ts snippet
|
|
22
22
|
export default defineModule({
|
|
23
|
-
name: 'board', //
|
|
24
|
-
requires: [db, other], //
|
|
25
|
-
controllers: [postsController], //
|
|
26
|
-
views: new URL('./views/', import.meta.url), // default/
|
|
27
|
-
routes(route, module) { //
|
|
23
|
+
name: 'board', // the folder name; the ID is dokebi-module.board
|
|
24
|
+
requires: [db, other], // plugin instances, descriptors, other modules
|
|
25
|
+
controllers: [postsController], // created once with the module context
|
|
26
|
+
views: new URL('./views/', import.meta.url), // default/ required; template names get the prefix module.board
|
|
27
|
+
routes(route, module) { // registered per app (when mounted). page = { app, module, base, view, inertia }
|
|
28
28
|
route.get('/', (request, reply, page) =>
|
|
29
29
|
page.view.reply(reply, 'index', module.controller(postsController).list(page)));
|
|
30
30
|
},
|
|
31
|
-
sockets: (module) => [boardSocket(module)], //
|
|
32
|
-
events: (module) => [boardStream(module)], // (0.1.3) SSE
|
|
33
|
-
setup(module) { return api; }, //
|
|
31
|
+
sockets: (module) => [boardSocket(module)], // registered per app under the prefix; tenant is <namespace>:<tenant>
|
|
32
|
+
events: (module) => [boardStream(module)], // (0.1.3) SSE routes (@dokebi/sse); same rules as sockets
|
|
33
|
+
setup(module) { return api; }, // optional; the return value is the API of whoever requires this module
|
|
34
34
|
start(module) {}, drain(module) {},
|
|
35
35
|
});
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
- **`module`(ModuleContext):** PluginContext
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
- **`version`:**
|
|
42
|
-
- **`views`:**
|
|
43
|
-
- **`controllers`:**
|
|
44
|
-
- **`setup`:**
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
1.
|
|
49
|
-
2.
|
|
50
|
-
3.
|
|
51
|
-
4.
|
|
52
|
-
5.
|
|
53
|
-
6.
|
|
38
|
+
- **`module` (ModuleContext):** PluginContext plus `module` (the name) and `controller(token)`.
|
|
39
|
+
- It reads only the declared `requires`.
|
|
40
|
+
- When a controller factory passes a freshly built descriptor object, the declared descriptor with that name is found.
|
|
41
|
+
- **`version`:** an exact semver, default `'0.1.0'`. Requires with duplicate names are refused.
|
|
42
|
+
- **`views`:** adds a template-ejs dependency automatically. Without `views/default/` the start fails.
|
|
43
|
+
- **`controllers`:** uses @dokebi/controller (optional peer). Calling `module.controller()` without controllers fails with `declares no controllers`.
|
|
44
|
+
- **`setup`:** optional. The older `setup(context)` form still works.
|
|
45
|
+
- **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
|
+
- **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
|
+
- **View lookup order:**
|
|
48
|
+
1. `<app>/<template>/<module>/…`
|
|
49
|
+
2. `<app>/default/<module>/…`
|
|
50
|
+
3. the module's `<template>/…`
|
|
51
|
+
4. the module's `default/…`
|
|
52
|
+
5. the app's views (layouts and partials)
|
|
53
|
+
6. shared `src/shared/views`
|
|
54
54
|
|
|
55
|
-
|
|
56
|
-
- **Inertia
|
|
57
|
-
-
|
|
58
|
-
- **`moduleMount(plugin)
|
|
55
|
+
So an app can change a single file of a module page, for example `src/apps/<app>/views/christmas/<module>/heading.ejs`.
|
|
56
|
+
- **Inertia apps:** the module produces props with `page.inertia.render(request, reply, 'Component', props)`. The app keeps the Vue pages in `views/<template>/Pages/`.
|
|
57
|
+
- **Sockets and SSE:** the return types of `sockets` and `events` (0.1.3) are defined by shape only (`ModuleSocketRoute`, `ModuleEventRoute`), so projects that do not use them need neither @dokebi/websocket nor @dokebi/sse. The mounting app registers them under its namespace rules ([D-0061](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0061-realtime-namespaces.md)): the tenant is `<namespace>:<authenticated tenant>`, and an authenticated `namespace` must be in that app's list.
|
|
58
|
+
- **`moduleMount(plugin)` and `MODULE_MOUNT`:** how the app plugin reads the mounting information. App code never needs them.
|
|
59
59
|
|
|
60
|
-
##
|
|
60
|
+
## Group plugin
|
|
61
61
|
|
|
62
|
-
`createPlugin({ app: app.view, entry: { modules: [...] } })
|
|
62
|
+
`createPlugin({ app: app.view, entry: { modules: [...] } })` groups several modules into a dependency graph and exposes the frozen `names` (plugin contract v2, [D-0028](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0028-plugin-contract-v2.md)).
|
|
63
63
|
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
- **
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
64
|
+
- **Generated code:** passes the default exports of the modules registered with `dokebi module add` to this entry. Projects with the old entry file `src/shared/modules/index.ts` get them appended after its `modules` list.
|
|
65
|
+
- **Accepted modules:** only what `defineModule` made (IDs starting with `dokebi-module.`). Duplicates are `INVALID_PLUGIN_INPUT`. A single module may also be registered directly with app.register.
|
|
66
|
+
- **Lifecycle:** setup registers routes, start prepares to run, drain stops new input and waits for work in progress, and context.defer cleans up after the whole drain.
|
|
67
|
+
- **Drain order:** reverse dependency order. A module's drain starts after the drains of the modules that depend on it have finished. Unrelated modules drain at the same time.
|
|
68
|
+
- **Instances:** module names cannot repeat. One module instance is used by one Application only.
|
|
69
|
+
- **Not provided:** automatic discovery, dynamic import, hot reload and folder scanning while running. The CLI writes registrations into the generated code.
|
|
70
|
+
- **Configuration:** the YAML settings are an empty object.
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
Examples:
|
|
73
73
|
|
|
74
|
-
- [examples/26-scaffold](
|
|
75
|
-
- [examples/25-playground](
|
|
76
|
-
- examples/22-web/main.ts
|
|
74
|
+
- [examples/26-scaffold](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/26-scaffold/README.md): repeated checks of generation, mounting and overriding
|
|
75
|
+
- [examples/25-playground](https://git.nyx-zone.com/dokebi/framework/-/blob/main/examples/25-playground/README.md): eight feature modules
|
|
76
|
+
- `examples/22-web/main.ts`: assembled in code
|
|
77
|
+
|
|
78
|
+
See the [AI guide](AI.md) for errors and cautions.
|
package/dist/index.d.ts
CHANGED
|
@@ -4,6 +4,8 @@ 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
|
+
/** 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';
|
|
7
9
|
/** A plugin instance (read with context.get) or a descriptor (read with context.getDependency). */
|
|
8
10
|
export type ModuleRequirement = Plugin<unknown> | PluginDependency;
|
|
9
11
|
/** The plugin context of a module, plus the controllers the module declares. */
|
package/dist/index.js
CHANGED
|
@@ -1,7 +1,24 @@
|
|
|
1
1
|
import { stat } from 'node:fs/promises';
|
|
2
2
|
import { fileURLToPath } from 'node:url';
|
|
3
3
|
import { types } from 'node:util';
|
|
4
|
-
import { definePlugin, dependencyOf, providerDependency, } from '@dokebi/core';
|
|
4
|
+
import { DokebiError, definePlugin, dependencyOf, providerDependency, } from '@dokebi/core';
|
|
5
|
+
import { options } from './options.js';
|
|
6
|
+
const FIX = {
|
|
7
|
+
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
|
+
INVALID_REQUIREMENT: 'List plugin instances or dependency descriptors ({ name, version }) in requires, each name once.',
|
|
9
|
+
INVALID_ENTRY: 'Export modules: an array of distinct defineModule plugins (at most 1024) from src/shared/modules/index.ts (npx dokebi module add <name> writes it).',
|
|
10
|
+
ALREADY_SET_UP: 'Create the module plugin once per Application (call defineModule for each application).',
|
|
11
|
+
NOT_SET_UP: 'Read the module context after the module plugin has set up.',
|
|
12
|
+
NO_CONTROLLERS: 'Add the controller token to controllers of defineModule before calling module.controller().',
|
|
13
|
+
VIEWS_MISSING: 'Create the views/default/ folder of the module (the cause names the file system error), or remove views.',
|
|
14
|
+
};
|
|
15
|
+
function moduleError(code, message, cause) {
|
|
16
|
+
return new DokebiError(code, message, {
|
|
17
|
+
plugin: 'dokebi-module',
|
|
18
|
+
fix: FIX[code],
|
|
19
|
+
...(cause === undefined ? {} : { cause }),
|
|
20
|
+
});
|
|
21
|
+
}
|
|
5
22
|
export const MODULE_MOUNT = Symbol.for('dokebi.module.mount');
|
|
6
23
|
const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
|
|
7
24
|
const DEFINITION_KEYS = new Set([
|
|
@@ -19,17 +36,17 @@ const DEFINITION_KEYS = new Set([
|
|
|
19
36
|
]);
|
|
20
37
|
const ejs = providerDependency({
|
|
21
38
|
name: 'dokebi-template-ejs',
|
|
22
|
-
version: '^0.
|
|
39
|
+
version: '^0.4.0',
|
|
23
40
|
packageName: '@dokebi/template-ejs',
|
|
24
41
|
load: () => import('@dokebi/template-ejs'),
|
|
25
42
|
});
|
|
26
43
|
function requirement(value) {
|
|
27
44
|
if (value === null || typeof value !== 'object')
|
|
28
|
-
throw
|
|
45
|
+
throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
|
|
29
46
|
if (typeof value.setup === 'function')
|
|
30
47
|
return dependencyOf(value);
|
|
31
48
|
if (typeof value.name !== 'string')
|
|
32
|
-
throw
|
|
49
|
+
throw moduleError('INVALID_REQUIREMENT', 'Invalid module requirement');
|
|
33
50
|
return value;
|
|
34
51
|
}
|
|
35
52
|
function moduleContext(context, name, declared, controllers) {
|
|
@@ -49,14 +66,20 @@ function moduleContext(context, name, declared, controllers) {
|
|
|
49
66
|
get drainSignal() {
|
|
50
67
|
return context.drainSignal;
|
|
51
68
|
},
|
|
69
|
+
// The same frozen object for the whole application (core's own).
|
|
70
|
+
runtime: context.runtime,
|
|
52
71
|
get: (plugin) => context.get(plugin),
|
|
53
72
|
getDependency: (dependency) => context.getDependency(own(dependency)),
|
|
54
73
|
getOptionalDependency: (dependency) => context.getOptionalDependency(own(dependency)),
|
|
55
74
|
defer: (cleanup) => context.defer(cleanup),
|
|
75
|
+
// The module plugin declares no contribution points, so core answers these with its coded
|
|
76
|
+
// errors (UNDECLARED_POINT, CONTRIBUTIONS_CLOSED); forwarded so ModuleContext stays a PluginContext.
|
|
77
|
+
contribute: (point, value) => context.contribute(point, value),
|
|
78
|
+
collect: (point) => context.collect(point),
|
|
56
79
|
controller: (definition) => {
|
|
57
80
|
const api = controllers();
|
|
58
81
|
if (!api)
|
|
59
|
-
throw
|
|
82
|
+
throw moduleError('NO_CONTROLLERS', `Module ${name} declares no controllers`);
|
|
60
83
|
return api.get(definition);
|
|
61
84
|
},
|
|
62
85
|
});
|
|
@@ -75,11 +98,11 @@ export function defineModule(definition) {
|
|
|
75
98
|
(definition.views !== undefined &&
|
|
76
99
|
(!(definition.views instanceof URL) || definition.views.protocol !== 'file:')) ||
|
|
77
100
|
['routes', 'sockets', 'events', 'setup', 'start', 'drain'].some((hook) => definition[hook] !== undefined && typeof definition[hook] !== 'function'))
|
|
78
|
-
throw
|
|
101
|
+
throw moduleError('INVALID_DEFINITION', 'Invalid module definition');
|
|
79
102
|
const { name, views } = definition;
|
|
80
103
|
const dependencies = (definition.requires ?? []).map(requirement);
|
|
81
104
|
if (new Set(dependencies.map((dependency) => dependency.name)).size !== dependencies.length)
|
|
82
|
-
throw
|
|
105
|
+
throw moduleError('INVALID_REQUIREMENT', 'Duplicate module requirement');
|
|
83
106
|
if (views && !dependencies.some((dependency) => dependency.name === ejs.name))
|
|
84
107
|
dependencies.push(ejs);
|
|
85
108
|
// core needs the declared descriptor object itself (the module's own or the one in requires).
|
|
@@ -101,12 +124,12 @@ export function defineModule(definition) {
|
|
|
101
124
|
metadata: Object.freeze({
|
|
102
125
|
name: 'dokebi-module.' + name,
|
|
103
126
|
version,
|
|
104
|
-
core: '^0.
|
|
127
|
+
core: '^0.4.0',
|
|
105
128
|
dependencies: Object.freeze(dependencies),
|
|
106
129
|
}),
|
|
107
130
|
async setup(context) {
|
|
108
131
|
if (started)
|
|
109
|
-
throw
|
|
132
|
+
throw moduleError('ALREADY_SET_UP', 'Create one module instance per Application');
|
|
110
133
|
started = true;
|
|
111
134
|
current = moduleContext(context, name, declared, () => controllers);
|
|
112
135
|
const begin = performance.now();
|
|
@@ -123,7 +146,7 @@ export function defineModule(definition) {
|
|
|
123
146
|
return undefined;
|
|
124
147
|
});
|
|
125
148
|
if (!info?.isDirectory())
|
|
126
|
-
throw
|
|
149
|
+
throw moduleError('VIEWS_MISSING', `Module ${name} has no views/default/ folder`, failure);
|
|
127
150
|
await context.getDependency(templates ?? ejs).addDirectory(views, prefix);
|
|
128
151
|
}
|
|
129
152
|
const api = (await definition.setup?.(current));
|
|
@@ -151,7 +174,7 @@ export function defineModule(definition) {
|
|
|
151
174
|
events: definition.events?.bind(definition),
|
|
152
175
|
context: () => {
|
|
153
176
|
if (!current)
|
|
154
|
-
throw
|
|
177
|
+
throw moduleError('NOT_SET_UP', `Module ${name} is not set up yet`);
|
|
155
178
|
return current;
|
|
156
179
|
},
|
|
157
180
|
});
|
|
@@ -177,7 +200,7 @@ function parseEntry(input) {
|
|
|
177
200
|
Array.isArray(input) ||
|
|
178
201
|
types.isProxy(input) ||
|
|
179
202
|
![Object.prototype, null].includes(Object.getPrototypeOf(input)))
|
|
180
|
-
throw
|
|
203
|
+
throw moduleError('INVALID_ENTRY', 'Invalid module entry');
|
|
181
204
|
let modules;
|
|
182
205
|
for (const key of Reflect.ownKeys(input)) {
|
|
183
206
|
// Module namespaces carry Symbol.toStringTag; only string exports are entry fields.
|
|
@@ -185,27 +208,17 @@ function parseEntry(input) {
|
|
|
185
208
|
continue;
|
|
186
209
|
const descriptor = Object.getOwnPropertyDescriptor(input, key);
|
|
187
210
|
if (key !== 'modules' || !descriptor || !('value' in descriptor))
|
|
188
|
-
throw
|
|
211
|
+
throw moduleError('INVALID_ENTRY', 'Invalid module entry');
|
|
189
212
|
modules = descriptor.value;
|
|
190
213
|
}
|
|
191
214
|
if (!Array.isArray(modules) || modules.length > LIMIT)
|
|
192
|
-
throw
|
|
215
|
+
throw moduleError('INVALID_ENTRY', 'Expected a modules array');
|
|
193
216
|
const names = modules.map((module) => module?.metadata?.name);
|
|
194
217
|
if (names.some((name) => typeof name !== 'string' || !name.startsWith('dokebi-module.')) ||
|
|
195
218
|
new Set(names).size !== names.length)
|
|
196
|
-
throw
|
|
219
|
+
throw moduleError('INVALID_ENTRY', 'Expected distinct module plugins');
|
|
197
220
|
return [...modules];
|
|
198
221
|
}
|
|
199
|
-
function parseOptions(input) {
|
|
200
|
-
if (input === null ||
|
|
201
|
-
typeof input !== 'object' ||
|
|
202
|
-
Array.isArray(input) ||
|
|
203
|
-
types.isProxy(input) ||
|
|
204
|
-
![Object.prototype, null].includes(Object.getPrototypeOf(input)) ||
|
|
205
|
-
Reflect.ownKeys(input).length)
|
|
206
|
-
throw new TypeError('dokebi-module accepts no options');
|
|
207
|
-
return Object.freeze({});
|
|
208
|
-
}
|
|
209
222
|
class ModuleGroupRuntime {
|
|
210
223
|
names;
|
|
211
224
|
constructor(names) {
|
|
@@ -218,9 +231,9 @@ class ModuleGroupRuntime {
|
|
|
218
231
|
}
|
|
219
232
|
export const createPlugin = definePlugin({
|
|
220
233
|
name: 'dokebi-module',
|
|
221
|
-
version: '0.
|
|
222
|
-
core: '^0.
|
|
223
|
-
options
|
|
234
|
+
version: '0.4.0',
|
|
235
|
+
core: '^0.4.0',
|
|
236
|
+
options,
|
|
224
237
|
entry: parseEntry,
|
|
225
238
|
dependencies: ({ entry }) => (entry ?? []).map((module) => dependencyOf(module)),
|
|
226
239
|
instance: ({ dependencies }) => new ModuleGroupRuntime(Object.freeze(dependencies.map((dependency) => dependency.name))),
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type OptionsOf } from '@dokebi/core';
|
|
2
|
+
/**
|
|
3
|
+
* dokebi-module has no options: dokebi.yaml may only give an empty mapping (D-0063 §3). The
|
|
4
|
+
* build writes options.schema.json from this declaration.
|
|
5
|
+
*/
|
|
6
|
+
export declare const options: import("@dokebi/core").OptionsDeclaration<{}>;
|
|
7
|
+
export type ModuleGroupOptions = OptionsOf<typeof options>;
|
package/dist/options.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/module",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Feature modules for Dokebi apps: controllers, models, views and routes in one folder mounted under a prefix.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"dokebi",
|
|
7
|
+
"dokebi-plugin",
|
|
8
|
+
"web",
|
|
9
|
+
"modules",
|
|
10
|
+
"mvc"
|
|
11
|
+
],
|
|
4
12
|
"private": false,
|
|
5
13
|
"type": "module",
|
|
6
14
|
"license": "MIT",
|
|
@@ -24,23 +32,26 @@
|
|
|
24
32
|
"node": ">=24.0.0"
|
|
25
33
|
},
|
|
26
34
|
"scripts": {
|
|
27
|
-
"build": "tsc -p tsconfig.json",
|
|
35
|
+
"build": "tsc -p tsconfig.json && node -e \"import('./dist/options.js').then(async (m) => { const { renderOptionsSchema } = await import('@dokebi/core'); process.stdout.write(renderOptionsSchema(m.options)); })\" > options.schema.json",
|
|
28
36
|
"typecheck": "tsc -p tsconfig.test.json --noEmit",
|
|
29
|
-
"test": "tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
|
|
37
|
+
"test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test .tmp/tests/tests/*.test.js"
|
|
30
38
|
},
|
|
31
39
|
"peerDependencies": {
|
|
32
|
-
"@dokebi/controller": "^0.
|
|
33
|
-
"@dokebi/core": "^0.
|
|
34
|
-
"@dokebi/template-ejs": "^0.
|
|
35
|
-
"@dokebi/template-inertia": "^0.
|
|
36
|
-
"@dokebi/web": "^0.
|
|
40
|
+
"@dokebi/controller": "^0.4.0",
|
|
41
|
+
"@dokebi/core": "^0.4.0",
|
|
42
|
+
"@dokebi/template-ejs": "^0.4.0",
|
|
43
|
+
"@dokebi/template-inertia": "^0.4.0",
|
|
44
|
+
"@dokebi/web": "^0.4.0",
|
|
37
45
|
"fastify": "^5.12.7"
|
|
38
46
|
},
|
|
39
47
|
"dokebi": {
|
|
40
48
|
"schemaVersion": 2,
|
|
41
49
|
"id": "dokebi-module",
|
|
42
|
-
"core": "^0.
|
|
50
|
+
"core": "^0.4.0",
|
|
43
51
|
"dependencies": [],
|
|
52
|
+
"hosts": [
|
|
53
|
+
"modules"
|
|
54
|
+
],
|
|
44
55
|
"install": {
|
|
45
56
|
"directories": [
|
|
46
57
|
"src/shared/modules"
|
|
@@ -49,6 +60,21 @@
|
|
|
49
60
|
"optionsSchema": "options.schema.json",
|
|
50
61
|
"documentation": "AI.md"
|
|
51
62
|
},
|
|
63
|
+
"dokebiCatalog": {
|
|
64
|
+
"kind": "plugin",
|
|
65
|
+
"summary": "Modules that hold one feature each (src/shared/modules/<module>); an app attaches them under a prefix",
|
|
66
|
+
"maturity": "preview",
|
|
67
|
+
"provides": [
|
|
68
|
+
"web.modules"
|
|
69
|
+
],
|
|
70
|
+
"doesNot": [
|
|
71
|
+
"Does not attach modules to apps by itself (modules in app.ts)"
|
|
72
|
+
],
|
|
73
|
+
"recipes": [
|
|
74
|
+
"api",
|
|
75
|
+
"blog"
|
|
76
|
+
]
|
|
77
|
+
},
|
|
52
78
|
"peerDependenciesMeta": {
|
|
53
79
|
"@dokebi/controller": {
|
|
54
80
|
"optional": true
|
|
@@ -67,10 +93,10 @@
|
|
|
67
93
|
}
|
|
68
94
|
},
|
|
69
95
|
"devDependencies": {
|
|
70
|
-
"@dokebi/controller": "0.
|
|
71
|
-
"@dokebi/template-ejs": "0.
|
|
72
|
-
"@dokebi/template-inertia": "0.
|
|
73
|
-
"@dokebi/web": "0.
|
|
96
|
+
"@dokebi/controller": "0.4.0",
|
|
97
|
+
"@dokebi/template-ejs": "0.4.0",
|
|
98
|
+
"@dokebi/template-inertia": "0.4.0",
|
|
99
|
+
"@dokebi/web": "0.4.0"
|
|
74
100
|
},
|
|
75
101
|
"publishConfig": {
|
|
76
102
|
"access": "public",
|