@nan0web/core 1.0.5 → 1.1.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/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.1",
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.4.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,67 @@ 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 = {}
57
+ meta
35
58
  /** @type {Record<string, Language>} */
36
- langs = {
37
- en: {
38
- id: 'en',
39
- icon: '🇬🇧',
40
- locale: 'en-GB',
41
- },
42
- }
59
+ langs
43
60
  /** @type {(key: string, replacements?: Record<string, string>) => string} */
44
61
  t = (key, replacements = {}) => key
62
+
45
63
  /**
46
64
  * Create an AppCore instance
47
65
  * @param {object} input - Application configuration
48
66
  */
49
67
  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') {
68
+ if (input.db && typeof input.db.fetch !== 'function') {
62
69
  throw new Error('Database must be an instance of @nan0web/db.DB')
63
70
  }
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
71
+ /** @type {any} */
72
+ const resolved = resolveDefaults(AppCore, { ...input })
73
+
74
+ this.db = /** @type {DB} */ (resolved.db)
75
+ this.title = String(resolved.title)
76
+ this.uri = String(resolved.uri)
77
+ this.locale = String(resolved.locale)
78
+ this.data = resolved.data
79
+ this.actions = resolved.actions
80
+ this.meta = resolved.meta
81
+ this.langs = resolved.langs
73
82
  }
74
83
 
75
84
  /**
package/src/Model.js ADDED
@@ -0,0 +1,47 @@
1
+ import { resolveDefaults, resolveAliases, resolveValidation } from '@nan0web/types'
2
+
3
+ /**
4
+ * Domain Data Model for a Project Configuration
5
+ * Implements Model-as-Schema (Project-as-Data)
6
+ *
7
+ * Ця модель є дзеркалом `project.schema.yaml` та джерелом правди
8
+ * для автоматичних інструментів валідації та генерації ТЗ.
9
+ *
10
+ * @example
11
+ * import { Model } from '@nan0web/core'
12
+ * const model = new Model({ description: 'My App', tags: ['ui'] })
13
+ */
14
+ export class Model {
15
+ #options = {}
16
+ /**
17
+ * @param {Partial<Model>} data Data from YAML or Markdown frontmatter
18
+ * @param {object} [options] Extended options (db, etc.)
19
+ */
20
+ constructor(data = {}, options = {}) {
21
+ const Model = this.constructor
22
+ Object.assign(this, resolveDefaults(Model, resolveAliases(Model, data)))
23
+ this.#options = options
24
+ }
25
+
26
+ /** @returns {import('@nan0web/db').default | undefined} */
27
+ get db() {
28
+ return this.#options.db
29
+ }
30
+
31
+ /**
32
+ * Environment options dependencies
33
+ * @returns {object}
34
+ */
35
+ get _() {
36
+ return this.#options
37
+ }
38
+
39
+ /**
40
+ * Validate instance against static schema metadata.
41
+ * @returns {boolean} True if validation passes
42
+ * @throws {import('@nan0web/types').ModelError}
43
+ */
44
+ validate() {
45
+ return resolveValidation(this.constructor, this)
46
+ }
47
+ }
@@ -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
@@ -0,0 +1,32 @@
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
+ * @example
9
+ * import { Model } from '@nan0web/core'
10
+ * const model = new Model({ description: 'My App', tags: ['ui'] })
11
+ */
12
+ export class Model {
13
+ /**
14
+ * @param {Partial<Model>} data Data from YAML or Markdown frontmatter
15
+ * @param {object} [options] Extended options (db, etc.)
16
+ */
17
+ constructor(data?: Partial<Model>, options?: object);
18
+ /** @returns {import('@nan0web/db').default | undefined} */
19
+ get db(): import("@nan0web/db").default | undefined;
20
+ /**
21
+ * Environment options dependencies
22
+ * @returns {object}
23
+ */
24
+ get _(): object;
25
+ /**
26
+ * Validate instance against static schema metadata.
27
+ * @returns {boolean} True if validation passes
28
+ * @throws {import('@nan0web/types').ModelError}
29
+ */
30
+ validate(): boolean;
31
+ #private;
32
+ }
@@ -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 };