@dokebi/module 0.4.1 → 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.
@@ -0,0 +1,25 @@
1
+ /** Thrown for a preset folder that breaks a rule; index.ts turns it into INVALID_CONTRACT. */
2
+ export declare class PresetIssue extends Error {
3
+ }
4
+ /** Limits of one preset folder. */
5
+ export declare const PRESET_LIMITS: Readonly<{
6
+ /** Files in one preset folder. */
7
+ files: 200;
8
+ /** Bytes of one file. */
9
+ fileBytes: 200000;
10
+ /** Folder depth below pages/. */
11
+ depth: 8;
12
+ /** Items of app.yaml modules and menu, children of one menu item. */
13
+ items: 64;
14
+ }>;
15
+ /** The app kinds a preset is made for (dokebi-platform DEC-03). */
16
+ export declare const PRESET_KINDS: readonly ['admin', 'front'];
17
+ export type PresetKind = (typeof PRESET_KINDS)[number];
18
+ /** The keys a preset's app.yaml may have: what it fills in a new app's app.yaml. */
19
+ export declare const PRESET_APP_KEYS: readonly ['layout', 'modules', 'menu'];
20
+ /** Whether a path inside the folder is a site file (`/` separated). */
21
+ export declare function isSiteFile(file: string): boolean;
22
+ /** Checks the app.yaml of a preset: layout, modules and menu only. */
23
+ export declare function checkPresetApp(text: string, where: string): void;
24
+ /** The files of a preset folder, after checking its shape (see the file comment). */
25
+ export declare function readPreset(folder: URL, where: string): Promise<readonly string[]>;
package/dist/preset.js ADDED
@@ -0,0 +1,165 @@
1
+ // A preset of a module (dokebi-platform DEC-12, DEC-16): a folder shaped like an app's definition
2
+ // folder — app.yaml, theme.css, layouts/<name>.html, components/<name>.html, pages/**/*.html — that
3
+ // an editor copies into a new app. Its app.yaml holds only what the preset fills: layout, modules
4
+ // and menu (the new-app window gives the rest). This file checks the folder's shape when the module
5
+ // sets up and lists its files for describe; what the files hold is @dokebi/pages' check.
6
+ import { readdir, readFile, stat } from 'node:fs/promises';
7
+ import { join } from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+ import { parseDocument } from 'yaml';
10
+ /** Thrown for a preset folder that breaks a rule; index.ts turns it into INVALID_CONTRACT. */
11
+ export class PresetIssue extends Error {
12
+ }
13
+ /** Limits of one preset folder. */
14
+ export const PRESET_LIMITS = Object.freeze({
15
+ /** Files in one preset folder. */
16
+ files: 200,
17
+ /** Bytes of one file. */
18
+ fileBytes: 200_000,
19
+ /** Folder depth below pages/. */
20
+ depth: 8,
21
+ /** Items of app.yaml modules and menu, children of one menu item. */
22
+ items: 64,
23
+ });
24
+ /** The app kinds a preset is made for (dokebi-platform DEC-03). */
25
+ export const PRESET_KINDS = ['admin', 'front'];
26
+ /** The keys a preset's app.yaml may have: what it fills in a new app's app.yaml. */
27
+ export const PRESET_APP_KEYS = ['layout', 'modules', 'menu'];
28
+ // The rules below are @dokebi/pages' own (check.ts PART_NAME, definition.ts appDeclaration), so a
29
+ // preset that passes here is an app.yaml the new app starts with (review: they were looser).
30
+ /** A part name (a layout or a component): the names @dokebi/pages takes (D-0198). */
31
+ const PART = /^[a-z][a-z0-9-]{0,39}$/;
32
+ /** A segment of a page path: a name, or a value of the address in brackets (D-0205). */
33
+ const PAGE_SEGMENT = /^(?:[a-z0-9][a-z0-9_-]{0,63}|\[[a-z][a-z0-9_]{0,31}\])$/;
34
+ const MODULE_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
35
+ const ICON = /^[a-z0-9][a-z0-9-]{0,63}$/;
36
+ const PERMISSION = /^[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)+$/;
37
+ /** A menu address as app.yaml takes it. */
38
+ const MENU_PATH = /^\/[A-Za-z0-9/_.-]*$/;
39
+ /** Characters of a menu item's permission at most (app.yaml). */
40
+ const PERMISSION_MAX = 128;
41
+ /** Whether a path inside the folder is a site file (`/` separated). */
42
+ export function isSiteFile(file) {
43
+ if (file === 'app.yaml' || file === 'theme.css')
44
+ return true;
45
+ const part = /^(layouts|components)\/([^/]+)\.html$/.exec(file);
46
+ if (part)
47
+ return PART.test(part[2]);
48
+ if (!file.startsWith('pages/') || !file.endsWith('.html'))
49
+ return false;
50
+ const segments = file.slice('pages/'.length, -'.html'.length).split('/');
51
+ return (segments.length <= PRESET_LIMITS.depth &&
52
+ segments.every((segment) => PAGE_SEGMENT.test(segment)));
53
+ }
54
+ const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
55
+ /** The files of a preset folder, sorted (hidden files such as .DS_Store are left out). */
56
+ async function filesOf(folder, where) {
57
+ const files = [];
58
+ const walk = async (dir, prefix, depth) => {
59
+ if (depth > PRESET_LIMITS.depth + 1)
60
+ throw new PresetIssue(`${where} is nested too deep`);
61
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
62
+ if (entry.name.startsWith('.'))
63
+ continue;
64
+ const path = `${prefix}${entry.name}`;
65
+ if (entry.isDirectory())
66
+ await walk(join(dir, entry.name), `${path}/`, depth + 1);
67
+ else if (entry.isFile()) {
68
+ if (files.length >= PRESET_LIMITS.files)
69
+ throw new PresetIssue(`${where} has more than ${PRESET_LIMITS.files} files`);
70
+ files.push(path);
71
+ }
72
+ else
73
+ throw new PresetIssue(`${where} has ${path}, which is not a file or a folder`);
74
+ }
75
+ };
76
+ await walk(folder, '', 0);
77
+ return files.sort();
78
+ }
79
+ function menuItems(value, at, nested) {
80
+ if (!Array.isArray(value) || value.length > PRESET_LIMITS.items)
81
+ throw new PresetIssue(`${at} must be a list of at most ${PRESET_LIMITS.items} items`);
82
+ value.forEach((item, index) => {
83
+ const place = `${at}[${index}]`;
84
+ if (!plain(item))
85
+ throw new PresetIssue(`${place} must be { title, path }`);
86
+ const keys = ['title', 'path', 'icon', 'permission', ...(nested ? [] : ['children'])];
87
+ const extra = Object.keys(item).find((key) => !keys.includes(key));
88
+ if (extra)
89
+ throw new PresetIssue(`${place} has an unknown key: ${extra}`);
90
+ if (typeof item.title !== 'string' || item.title.trim() === '' || item.title.length > 200)
91
+ throw new PresetIssue(`${place}.title must be a text of 1 to 200 characters`);
92
+ if (typeof item.path !== 'string' ||
93
+ item.path.length > 256 ||
94
+ !MENU_PATH.test(item.path) ||
95
+ item.path.split('/').includes('..'))
96
+ throw new PresetIssue(`${place}.path must be an address starting with / (letters, digits, / _ . -)`);
97
+ if (item.icon !== undefined && (typeof item.icon !== 'string' || !ICON.test(item.icon)))
98
+ throw new PresetIssue(`${place}.icon must be a lower-case icon name`);
99
+ if (item.permission !== undefined &&
100
+ (typeof item.permission !== 'string' ||
101
+ item.permission.length > PERMISSION_MAX ||
102
+ !PERMISSION.test(item.permission)))
103
+ throw new PresetIssue(`${place}.permission must be a permission key`);
104
+ if (item.children !== undefined)
105
+ menuItems(item.children, `${place}.children`, true);
106
+ });
107
+ }
108
+ /** Checks the app.yaml of a preset: layout, modules and menu only. */
109
+ export function checkPresetApp(text, where) {
110
+ const document = parseDocument(text, { prettyErrors: false, uniqueKeys: true });
111
+ if (document.errors.length)
112
+ throw new PresetIssue(`${where}/app.yaml is not YAML: ${document.errors[0]?.message}`);
113
+ let value;
114
+ try {
115
+ value = document.toJS({ maxAliasCount: 0 }) ?? {};
116
+ }
117
+ catch (error) {
118
+ // An alias (`*x`) is refused by maxAliasCount 0 with a ReferenceError: the preset's problem,
119
+ // named as such, never a raw error at start (review).
120
+ throw new PresetIssue(`${where}/app.yaml uses a YAML alias (&name / *name), write it out`, {
121
+ cause: error,
122
+ });
123
+ }
124
+ if (!plain(value))
125
+ throw new PresetIssue(`${where}/app.yaml must be a mapping`);
126
+ const extra = Object.keys(value).find((key) => !PRESET_APP_KEYS.includes(key));
127
+ if (extra)
128
+ throw new PresetIssue(`${where}/app.yaml has ${extra}: a preset fills only ${PRESET_APP_KEYS.join(', ')} (the new-app window gives the rest)`);
129
+ if (value.layout !== undefined && (typeof value.layout !== 'string' || !PART.test(value.layout)))
130
+ throw new PresetIssue(`${where}/app.yaml layout must be a layout name`);
131
+ if (value.modules !== undefined &&
132
+ (!Array.isArray(value.modules) ||
133
+ value.modules.length > PRESET_LIMITS.items ||
134
+ value.modules.some((name) => typeof name !== 'string' || !MODULE_NAME.test(name))))
135
+ throw new PresetIssue(`${where}/app.yaml modules must be a list of module names`);
136
+ if (value.menu !== undefined)
137
+ menuItems(value.menu, `${where}/app.yaml menu`, false);
138
+ }
139
+ /** The files of a preset folder, after checking its shape (see the file comment). */
140
+ export async function readPreset(folder, where) {
141
+ const path = fileURLToPath(folder);
142
+ let info;
143
+ try {
144
+ info = await stat(path);
145
+ }
146
+ catch (error) {
147
+ // A folder that is not there is the contract's problem, named as such; anything else stays.
148
+ if (error.code !== 'ENOENT')
149
+ throw error;
150
+ }
151
+ if (!info?.isDirectory())
152
+ throw new PresetIssue(`${where} is not a folder: ${path}`);
153
+ const files = await filesOf(path, where);
154
+ const other = files.find((file) => !isSiteFile(file));
155
+ if (other)
156
+ throw new PresetIssue(`${where} has ${other}, which is not a site file (app.yaml, theme.css, layouts/<name>.html, components/<name>.html, pages/<path>.html)`);
157
+ for (const file of files) {
158
+ const size = (await stat(join(path, file))).size;
159
+ if (size > PRESET_LIMITS.fileBytes)
160
+ throw new PresetIssue(`${where}/${file} is larger than ${PRESET_LIMITS.fileBytes} bytes`);
161
+ }
162
+ if (files.includes('app.yaml'))
163
+ checkPresetApp(await readFile(join(path, 'app.yaml'), 'utf8'), where);
164
+ return Object.freeze(files);
165
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/module",
3
- "version": "0.4.1",
3
+ "version": "0.4.2",
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",
@@ -18,6 +18,10 @@
18
18
  ".": {
19
19
  "types": "./dist/index.d.ts",
20
20
  "import": "./dist/index.js"
21
+ },
22
+ "./dependency": {
23
+ "types": "./dist/dependency.d.ts",
24
+ "import": "./dist/dependency.js"
21
25
  }
22
26
  },
23
27
  "files": [
@@ -36,6 +40,9 @@
36
40
  "typecheck": "tsc -p tsconfig.test.json --noEmit",
37
41
  "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"
38
42
  },
43
+ "dependencies": {
44
+ "yaml": "2.9.1"
45
+ },
39
46
  "peerDependencies": {
40
47
  "@dokebi/controller": "^0.4.0",
41
48
  "@dokebi/core": "^0.4.0",
@@ -52,6 +59,9 @@
52
59
  "hosts": [
53
60
  "modules"
54
61
  ],
62
+ "contributes": [
63
+ "core:describe"
64
+ ],
55
65
  "install": {
56
66
  "directories": [
57
67
  "src/shared/modules"
@@ -95,8 +105,8 @@
95
105
  "devDependencies": {
96
106
  "@dokebi/controller": "0.4.2",
97
107
  "@dokebi/template-ejs": "0.4.3",
98
- "@dokebi/template-inertia": "0.4.4",
99
- "@dokebi/web": "0.4.3"
108
+ "@dokebi/template-inertia": "0.4.6",
109
+ "@dokebi/web": "0.4.6"
100
110
  },
101
111
  "publishConfig": {
102
112
  "access": "public",