@nan0web/core 1.0.5 → 1.1.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/README.md CHANGED
@@ -75,6 +75,16 @@ const db = new DB()
75
75
  const core = new AppCore({ db })
76
76
  await core.run() // ← throws an error → AppCore: run() must be implemented
77
77
  ```
78
+ ## AppCore Static Meta
79
+
80
+ Core components like `AppCore` and `ProjectModel` implement a `static UI`
81
+ metadata block defining their semantic display defaults according to the system contract.
82
+
83
+ How to get semantic static UI data?
84
+ ```js
85
+ import { AppCore, ProjectModel } from "@nan0web/core"
86
+ console.info(`${AppCore.UI.icon} ${AppCore.UI.title}`) // ← ⚙️ Application Core
87
+ ```
78
88
  ## Contributing
79
89
 
80
90
  How to contribute? - [check here](./CONTRIBUTING.md)
package/package.json CHANGED
@@ -1,57 +1,56 @@
1
1
  {
2
- "name": "@nan0web/core",
3
- "version": "1.0.5",
4
- "description": "Core application framework for nan0web with database handling, internationalization, and interface connectivity",
5
- "type": "module",
6
- "main": "src/index.js",
7
- "types": "types/index.d.ts",
8
- "files": [
9
- "src/**/*.js",
10
- "!src/**/*.test.js",
11
- "!src/README.md.js",
12
- "types/**/*.d.ts"
13
- ],
14
- "scripts": {
15
- "build": "tsc",
16
- "clean": "rm -rf .cache/ && rm -rf dist/",
17
- "clean:modules": "rm -rf node_modules",
18
- "precommit": "npm test",
19
- "prepush": "npm test",
20
- "prepare": "husky",
21
- "prepublishOnly": "npm test && npm run build",
22
- "play": "node play/main.js",
23
- "release": "nan0release publish",
24
- "knip": "knip --production",
25
- "test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
26
- "test:docs": "node --test src/README.md.js",
27
- "test:release": "node --test \"releases/**/*.test.js\"",
28
- "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
29
- "test:coverage:collect": "nan0test coverage",
30
- "test:status": "nan0test status --hide-name",
31
- "test:all": "npm run test && npm run test:docs && npm run build && npm run knip"
32
- },
33
- "keywords": [
34
- "nan0",
35
- "data",
36
- "types",
37
- "utilities",
38
- "object",
39
- "array",
40
- "validation",
41
- "format",
42
- "parser"
43
- ],
44
- "author": "ЯRаСлав YaRaSLove <support@yaro.page>",
45
- "license": "ISC",
46
- "packageManager": "pnpm@10.11.0",
47
- "devDependencies": {
48
- "@nan0web/release": "*",
49
- "@nan0web/test": "*",
50
- "husky": "^9.1.7",
51
- "knip": "^5.82.1"
52
- },
53
- "dependencies": {
54
- "@nan0web/db": "*",
55
- "@nan0web/protocol": "*"
56
- }
57
- }
2
+ "name": "@nan0web/core",
3
+ "version": "1.1.2",
4
+ "description": "Core application framework for nan0web with database handling, internationalization, and interface connectivity",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "types": "types/index.d.ts",
8
+ "files": [
9
+ "src/**/*.js",
10
+ "!src/**/*.test.js",
11
+ "!src/README.md.js",
12
+ "types/**/*.d.ts"
13
+ ],
14
+ "keywords": [
15
+ "nan0",
16
+ "data",
17
+ "types",
18
+ "utilities",
19
+ "object",
20
+ "array",
21
+ "validation",
22
+ "format",
23
+ "parser"
24
+ ],
25
+ "author": "ЯRаСлав YaRaSLove <support@yaro.page>",
26
+ "license": "ISC",
27
+ "devDependencies": {
28
+ "@nan0web/release": "^1.0.2",
29
+ "@nan0web/test": "^1.1.3",
30
+ "husky": "^9.1.7",
31
+ "knip": "^5.86.0"
32
+ },
33
+ "dependencies": {
34
+ "@nan0web/db": "^1.4.3",
35
+ "@nan0web/i18n": "^1.3.0",
36
+ "@nan0web/protocol": "^2.0.0",
37
+ "@nan0web/types": "^1.6.0"
38
+ },
39
+ "scripts": {
40
+ "build": "tsc",
41
+ "clean": "rm -rf .cache/ && rm -rf dist/",
42
+ "clean:modules": "rm -rf node_modules",
43
+ "precommit": "npm test",
44
+ "prepush": "npm test",
45
+ "play": "node play/main.js",
46
+ "release": "nan0release publish",
47
+ "knip": "knip --production",
48
+ "test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
49
+ "test:docs": "node --test src/README.md.js",
50
+ "test:release": "node --test \"releases/**/*.test.js\"",
51
+ "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
52
+ "test:coverage:collect": "nan0test coverage",
53
+ "test:status": "nan0test status --hide-name",
54
+ "test:all": "npm run test && npm run test:docs && npm run build && npm run knip"
55
+ }
56
+ }
package/src/AppCore.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import DB from '@nan0web/db'
2
2
  import { createT } from '@nan0web/i18n'
3
+ import { resolveDefaults } from '@nan0web/types'
3
4
  import AppResult from './AppResult.js'
4
5
 
5
6
  /** @typedef {{id: string, icon?: string, locale?: string}} Language */
@@ -17,59 +18,70 @@ import AppResult from './AppResult.js'
17
18
  */
18
19
  export default class AppCore {
19
20
  static DB = DB
21
+ static UI = {
22
+ title: 'Application Core',
23
+ description: 'Base application logic and state container',
24
+ icon: '⚙️',
25
+ }
26
+
27
+ static title = { default: '' }
28
+ static uri = { default: '' }
29
+ static locale = { default: 'uk' }
30
+ static data = { default: {} }
31
+ static actions = { default: {} }
32
+ static meta = { default: {} }
33
+ static langs = {
34
+ default: {
35
+ en: {
36
+ id: 'en',
37
+ icon: '🇬🇧',
38
+ locale: 'en-GB',
39
+ },
40
+ },
41
+ }
42
+
20
43
  #initialized = false
21
44
  /** @type {DB} */
22
45
  db
23
46
  /** @type {string} */
24
- title = ''
47
+ title
25
48
  /** @type {string} */
26
- uri = ''
49
+ uri
27
50
  /** @type {string} */
28
- locale = 'uk'
51
+ locale
29
52
  /** @type {object} */
30
- data = {}
53
+ data
31
54
  /** @type {Record<string, Function>} */
32
- actions = {}
55
+ actions
33
56
  /** @type {object} */
34
- meta = {}
35
- /** @type {Record<string, Language>} */
36
- langs = {
37
- en: {
38
- id: 'en',
39
- icon: '🇬🇧',
40
- locale: 'en-GB',
41
- },
42
- }
57
+ meta
58
+ /** @type {object} */
59
+ langs
60
+ /** @type {object} */
61
+ element
43
62
  /** @type {(key: string, replacements?: Record<string, string>) => string} */
44
63
  t = (key, replacements = {}) => key
64
+
45
65
  /**
46
66
  * Create an AppCore instance
47
67
  * @param {object} input - Application configuration
48
68
  */
49
69
  constructor(input = {}) {
50
- const {
51
- db,
52
- title = this.title,
53
- uri = this.uri,
54
- locale = this.locale,
55
- data = this.data,
56
- actions = this.actions,
57
- meta = this.meta,
58
- langs = this.langs,
59
- t = this.t,
60
- } = input
61
- if (db && typeof db.fetch !== 'function') {
70
+ if (input.db && typeof input.db.fetch !== 'function') {
62
71
  throw new Error('Database must be an instance of @nan0web/db.DB')
63
72
  }
64
- this.db = db
65
- this.title = String(title)
66
- this.uri = String(uri)
67
- this.locale = String(locale)
68
- this.data = data
69
- this.actions = actions
70
- this.meta = meta
71
- this.langs = langs
72
- this.t = t
73
+ /** @type {any} */
74
+ const resolved = resolveDefaults(AppCore, { ...input })
75
+
76
+ this.db = /** @type {DB} */ (resolved.db)
77
+ this.title = String(resolved.title)
78
+ this.uri = String(resolved.uri)
79
+ this.locale = String(resolved.locale)
80
+ this.data = resolved.data
81
+ this.actions = resolved.actions
82
+ this.meta = resolved.meta
83
+ this.langs = resolved.langs
84
+ this.element = resolved.element || input.element || {}
73
85
  }
74
86
 
75
87
  /**
@@ -123,7 +135,7 @@ export default class AppCore {
123
135
  }
124
136
 
125
137
  static from(input) {
126
- if (input instanceof AppCore) return input
127
- return new AppCore(input)
138
+ if (input instanceof this) return input
139
+ return new this(input)
128
140
  }
129
141
  }
package/src/Model.js ADDED
@@ -0,0 +1,3 @@
1
+ import { Model } from '@nan0web/types'
2
+
3
+ export { Model }
@@ -0,0 +1,74 @@
1
+ import { Model } from './Model.js'
2
+
3
+ const LANGS = ['en', 'uk', 'de', 'fr', 'es', 'pl']
4
+
5
+ /**
6
+ * Domain Data Model for a Project Configuration
7
+ * Implements Model-as-Schema (Project-as-Data)
8
+ *
9
+ * Ця модель є дзеркалом `project.schema.yaml` та джерелом правди
10
+ * для автоматичних інструментів валідації та генерації ТЗ.
11
+ *
12
+ * Instance field defaults come from static metadata via resolveDefaults()
13
+ * in the parent Model constructor. Do NOT use class field initializers here
14
+ * as they execute AFTER super() and would overwrite resolved values.
15
+ *
16
+ * @example
17
+ * import { ProjectModel } from '@nan0web/core'
18
+ * const project = new ProjectModel({ description: 'My App', tags: ['ui'] })
19
+ */
20
+ export class ProjectModel extends Model {
21
+ static UI = {
22
+ title: 'Project Data',
23
+ }
24
+ static description = {
25
+ help: 'Project description (1-2 sentences)',
26
+ type: 'string',
27
+ default: '',
28
+ positional: true,
29
+ }
30
+ static tags = {
31
+ help: 'Tags (ui, core, cli...)',
32
+ type: 'string[]',
33
+ default: [],
34
+ }
35
+ static locale = {
36
+ help: 'Primary locale',
37
+ type: 'string',
38
+ options: LANGS,
39
+ default: 'uk',
40
+ errorInvalid: 'Invalid primary locale',
41
+ validate: (val) => LANGS.includes(val) || ProjectModel.locale.errorInvalid,
42
+ }
43
+ static i18n = {
44
+ help: 'Additional translation locales',
45
+ type: 'array',
46
+ options: LANGS,
47
+ default: [],
48
+ errorInvalid: 'Invalid translation locales',
49
+ validate: (val) => (Array.isArray(val) && val.every((l) => LANGS.includes(l))) || ProjectModel.i18n.errorInvalid,
50
+ }
51
+ static status = {
52
+ help: 'Project status',
53
+ type: 'string',
54
+ default: 'planned',
55
+ options: ['done', 'active', 'early', 'planned', 'idle', 'legacy'],
56
+ errorInvalid: 'Invalid project status',
57
+ validate: (val) => ProjectModel.status.options.includes(val) || ProjectModel.status.errorInvalid,
58
+ }
59
+
60
+ /**
61
+ * @param {Partial<ProjectModel>} data Data from YAML or Markdown frontmatter
62
+ * @param {object} [options] Extended options (db, etc.)
63
+ */
64
+ constructor(data = {}, options = {}) {
65
+ super(data, options)
66
+
67
+ if (typeof this.tags === 'string') {
68
+ this.tags = /** @type {string} */ (this.tags)
69
+ .split(',')
70
+ .map((t) => t.trim())
71
+ .filter(Boolean)
72
+ }
73
+ }
74
+ }
package/src/index.js CHANGED
@@ -1,9 +1,12 @@
1
1
  import { ExecutableCommand } from '@nan0web/protocol'
2
+ import { ModelError } from '@nan0web/types'
2
3
  import AppCore from './AppCore.js'
3
4
  import AppResult from './AppResult.js'
5
+ import { Model } from './Model.js'
6
+ import { ProjectModel } from './ProjectModel.js'
4
7
 
5
8
  /** @typedef {import("./AppCore.js").Language} Language */
6
9
 
7
- export { AppCore, AppResult, ExecutableCommand }
10
+ export { AppCore, AppResult, ExecutableCommand, Model, ProjectModel, ModelError }
8
11
 
9
12
  export default AppCore
@@ -12,6 +12,38 @@
12
12
  */
13
13
  export default class AppCore {
14
14
  static DB: typeof DB;
15
+ static UI: {
16
+ title: string;
17
+ description: string;
18
+ icon: string;
19
+ };
20
+ static title: {
21
+ default: string;
22
+ };
23
+ static uri: {
24
+ default: string;
25
+ };
26
+ static locale: {
27
+ default: string;
28
+ };
29
+ static data: {
30
+ default: {};
31
+ };
32
+ static actions: {
33
+ default: {};
34
+ };
35
+ static meta: {
36
+ default: {};
37
+ };
38
+ static langs: {
39
+ default: {
40
+ en: {
41
+ id: string;
42
+ icon: string;
43
+ locale: string;
44
+ };
45
+ };
46
+ };
15
47
  static from(input: any): AppCore;
16
48
  /**
17
49
  * Create an AppCore instance
@@ -32,8 +64,10 @@ export default class AppCore {
32
64
  actions: Record<string, Function>;
33
65
  /** @type {object} */
34
66
  meta: object;
35
- /** @type {Record<string, Language>} */
36
- langs: Record<string, Language>;
67
+ /** @type {object} */
68
+ langs: object;
69
+ /** @type {object} */
70
+ element: object;
37
71
  /** @type {(key: string, replacements?: Record<string, string>) => string} */
38
72
  t: (key: string, replacements?: Record<string, string>) => string;
39
73
  /**
@@ -0,0 +1,2 @@
1
+ export { Model };
2
+ import { Model } from '@nan0web/types';
@@ -0,0 +1,62 @@
1
+ /**
2
+ * Domain Data Model for a Project Configuration
3
+ * Implements Model-as-Schema (Project-as-Data)
4
+ *
5
+ * Ця модель є дзеркалом `project.schema.yaml` та джерелом правди
6
+ * для автоматичних інструментів валідації та генерації ТЗ.
7
+ *
8
+ * Instance field defaults come from static metadata via resolveDefaults()
9
+ * in the parent Model constructor. Do NOT use class field initializers here
10
+ * as they execute AFTER super() and would overwrite resolved values.
11
+ *
12
+ * @example
13
+ * import { ProjectModel } from '@nan0web/core'
14
+ * const project = new ProjectModel({ description: 'My App', tags: ['ui'] })
15
+ */
16
+ export class ProjectModel extends Model {
17
+ static UI: {
18
+ title: string;
19
+ };
20
+ static description: {
21
+ help: string;
22
+ type: string;
23
+ default: string;
24
+ positional: boolean;
25
+ };
26
+ static tags: {
27
+ help: string;
28
+ type: string;
29
+ default: never[];
30
+ };
31
+ static locale: {
32
+ help: string;
33
+ type: string;
34
+ options: string[];
35
+ default: string;
36
+ errorInvalid: string;
37
+ validate: (val: any) => string | true;
38
+ };
39
+ static i18n: {
40
+ help: string;
41
+ type: string;
42
+ options: string[];
43
+ default: never[];
44
+ errorInvalid: string;
45
+ validate: (val: any) => string | true;
46
+ };
47
+ static status: {
48
+ help: string;
49
+ type: string;
50
+ default: string;
51
+ options: string[];
52
+ errorInvalid: string;
53
+ validate: (val: any) => string | true;
54
+ };
55
+ /**
56
+ * @param {Partial<ProjectModel>} data Data from YAML or Markdown frontmatter
57
+ * @param {object} [options] Extended options (db, etc.)
58
+ */
59
+ constructor(data?: Partial<ProjectModel>, options?: object);
60
+ tags: string[] | undefined;
61
+ }
62
+ import { Model } from './Model.js';
package/types/index.d.ts CHANGED
@@ -3,4 +3,7 @@ export type Language = import("./AppCore.js").Language;
3
3
  import AppCore from './AppCore.js';
4
4
  import AppResult from './AppResult.js';
5
5
  import { ExecutableCommand } from '@nan0web/protocol';
6
- export { AppCore, AppResult, ExecutableCommand };
6
+ import { Model } from './Model.js';
7
+ import { ProjectModel } from './ProjectModel.js';
8
+ import { ModelError } from '@nan0web/types';
9
+ export { AppCore, AppResult, ExecutableCommand, Model, ProjectModel, ModelError };