@nan0web/core 1.0.3 → 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
@@ -3,9 +3,7 @@
3
3
  Core application framework for nan0web providing a lightweight
4
4
  DB‑backed state container with built‑in internationalisation.
5
5
 
6
- |Package name|[Status](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Documentation|Test coverage|Features|Npm version|
7
- |---|---|---|---|---|---|
8
- |[@nan0web/core](https://github.com/nan0web/core/) |🟢 `99.1%` |🧪 [English 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/core/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/core/blob/main/docs/uk/README.md) |🟢 `95.3%` |✅ d.ts 📜 system.md 🕹️ playground |1.0.1 |
6
+ <!-- %PACKAGE_STATUS% -->
9
7
 
10
8
  ## Installation
11
9
 
@@ -32,7 +30,7 @@ How to instantiate AppCore?
32
30
  ```js
33
31
  import { AppCore } from "@nan0web/core"
34
32
  const db = new DB()
35
- const core = new AppCore({ db, title: "Demo", uri: "/demo", locale: "en" })
33
+ const core = new AppCore({ db, title: 'Demo', uri: '/demo', locale: 'en' })
36
34
  console.info(core.title) // ← Demo
37
35
  console.info(core.uri) // ← /demo
38
36
  ```
@@ -43,14 +41,12 @@ Load translation JSON from the DB and obtain a translation function.
43
41
  How does bootstrapI18n load translations?
44
42
  ```js
45
43
  const db = new DB({
46
- predefined: [
47
- ["i18n/uk.json", { "hello": "Вітаю!" }]
48
- ]
44
+ predefined: [['i18n/uk.json', { hello: 'Вітаю!' }]],
49
45
  })
50
46
  await db.connect()
51
- const core = new AppCore({ db, locale: "uk" })
47
+ const core = new AppCore({ db, locale: 'uk' })
52
48
  await core.init()
53
- const result = core.t("hello")
49
+ const result = core.t('hello')
54
50
  console.info(result) // ← Вітаю!
55
51
  ```
56
52
  ## State inspection
@@ -66,7 +62,7 @@ const state = core.state()
66
62
  How to create an AppResult instance?
67
63
  ```js
68
64
  import { AppResult } from "@nan0web/core"
69
- const res = new AppResult({ content: "Done", priority: 2, meta: { ok: true } })
65
+ const res = new AppResult({ content: 'Done', priority: 2, meta: { ok: true } })
70
66
  console.info(res.content[0]) // ← Done
71
67
  ```
72
68
  ## run() contract
@@ -79,6 +75,16 @@ const db = new DB()
79
75
  const core = new AppCore({ db })
80
76
  await core.run() // ← throws an error → AppCore: run() must be implemented
81
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
+ ```
82
88
  ## Contributing
83
89
 
84
90
  How to contribute? - [check here](./CONTRIBUTING.md)
package/package.json CHANGED
@@ -1,54 +1,56 @@
1
1
  {
2
- "name": "@nan0web/core",
3
- "version": "1.0.3",
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
- "types/**/*.d.ts"
12
- ],
13
- "scripts": {
14
- "build": "tsc",
15
- "clean": "rm -rf .cache/ && rm -rf dist/",
16
- "clean:modules": "rm -rf node_modules",
17
- "precommit": "npm test",
18
- "prepush": "npm test",
19
- "prepare": "husky",
20
- "prepublishOnly": "npm test && npm run build",
21
- "play": "node play/main.js",
22
- "release": "nan0release publish",
23
- "test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
24
- "test:docs": "node --test src/README.md.js",
25
- "test:release": "node --test \"releases/**/*.test.js\"",
26
- "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
27
- "test:coverage:collect": "nan0test coverage",
28
- "test:status": "nan0test status --hide-name",
29
- "test:all": "npm run test && npm run test:docs && npm run build"
30
- },
31
- "keywords": [
32
- "nan0",
33
- "data",
34
- "types",
35
- "utilities",
36
- "object",
37
- "array",
38
- "validation",
39
- "format",
40
- "parser"
41
- ],
42
- "author": "ЯRаСлав YaRaSLove <support@yaro.page>",
43
- "license": "ISC",
44
- "packageManager": "pnpm@10.11.0",
45
- "devDependencies": {
46
- "@nan0web/release": "1.0.1",
47
- "@nan0web/test": "1.1.3",
48
- "husky": "^9.1.7"
49
- },
50
- "dependencies": {
51
- "@nan0web/interface": "1.0.1",
52
- "@nan0web/protocol": "2.0.0"
53
- }
54
- }
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,6 +1,7 @@
1
- import DB from "@nan0web/db"
2
- import { createT } from "@nan0web/i18n"
3
- import AppResult from "./AppResult.js"
1
+ import DB from '@nan0web/db'
2
+ import { createT } from '@nan0web/i18n'
3
+ import { resolveDefaults } from '@nan0web/types'
4
+ import AppResult from './AppResult.js'
4
5
 
5
6
  /** @typedef {{id: string, icon?: string, locale?: string}} Language */
6
7
 
@@ -16,61 +17,68 @@ import AppResult from "./AppResult.js"
16
17
  * @property {Function} t - Translation function
17
18
  */
18
19
  export default class AppCore {
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
+
19
43
  #initialized = false
20
44
  /** @type {DB} */
21
45
  db
22
46
  /** @type {string} */
23
- title = ""
47
+ title
24
48
  /** @type {string} */
25
- uri = ""
49
+ uri
26
50
  /** @type {string} */
27
- locale = "uk"
51
+ locale
28
52
  /** @type {object} */
29
- data = {}
53
+ data
30
54
  /** @type {Record<string, Function>} */
31
- actions = {}
55
+ actions
32
56
  /** @type {object} */
33
- meta = {}
57
+ meta
34
58
  /** @type {Record<string, Language>} */
35
- langs = {
36
- en: {
37
- id: "en",
38
- icon: "🇬🇧",
39
- locale: "en-GB"
40
- }
41
- }
42
- /** @type {(key: string, replacements: Record<string, string>) => string} */
43
- t = (key, replacements) => key
59
+ langs
60
+ /** @type {(key: string, replacements?: Record<string, string>) => string} */
61
+ t = (key, replacements = {}) => key
62
+
44
63
  /**
45
64
  * Create an AppCore instance
46
- * @param {object} config - Application configuration
47
- * @param {DB} config.db - Database instance
48
- * @param {string} [config.locale='uk'] - Locale identifier 2 or 5 chars: "uk" | "uk-UA"
65
+ * @param {object} input - Application configuration
49
66
  */
50
67
  constructor(input = {}) {
51
- const {
52
- db,
53
- title = this.title,
54
- uri = this.uri,
55
- locale = this.locale,
56
- data = this.data,
57
- actions = this.actions,
58
- meta = this.meta,
59
- langs = this.langs,
60
- t = this.t,
61
- } = input
62
- if (!(db instanceof DB)) {
63
- throw new Error("Database must be an instance of @nan0web/db.DB")
68
+ if (input.db && typeof input.db.fetch !== 'function') {
69
+ throw new Error('Database must be an instance of @nan0web/db.DB')
64
70
  }
65
- this.db = db
66
- this.title = String(title)
67
- this.uri = String(uri)
68
- this.locale = String(locale)
69
- this.data = data
70
- this.actions = actions
71
- this.meta = meta
72
- this.langs = langs
73
- 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
74
82
  }
75
83
 
76
84
  /**
@@ -79,7 +87,7 @@ export default class AppCore {
79
87
  * @returns {Promise<void>}
80
88
  */
81
89
  async bootstrapI18n(path = `/i18n/{{locale}}.json`) {
82
- const [code, country] = this.locale.split("-")
90
+ const [code, country] = this.locale.split('-')
83
91
  let uri = path.replace('{{locale}}', this.locale)
84
92
  let i18n = await this.db.fetch(uri, { defaultValue: null })
85
93
  if (null === i18n && country) {
@@ -109,7 +117,7 @@ export default class AppCore {
109
117
  data: this.data,
110
118
  actions: this.actions,
111
119
  meta: this.meta,
112
- t: this.t
120
+ t: this.t,
113
121
  }
114
122
  }
115
123
 
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,13 +1,12 @@
1
- import { ExecutableCommand } from "@nan0web/protocol"
2
- import AppCore from "./AppCore.js"
3
- import AppResult from "./AppResult.js"
1
+ import { ExecutableCommand } from '@nan0web/protocol'
2
+ import { ModelError } from '@nan0web/types'
3
+ import AppCore from './AppCore.js'
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 {
8
- AppCore,
9
- AppResult,
10
- ExecutableCommand,
11
- }
10
+ export { AppCore, AppResult, ExecutableCommand, Model, ProjectModel, ModelError }
12
11
 
13
12
  export default AppCore
@@ -11,14 +11,45 @@
11
11
  * @property {Function} t - Translation function
12
12
  */
13
13
  export default class AppCore {
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
+ };
14
47
  static from(input: any): AppCore;
15
48
  /**
16
49
  * Create an AppCore instance
17
- * @param {object} config - Application configuration
18
- * @param {DB} config.db - Database instance
19
- * @param {string} [config.locale='uk'] - Locale identifier 2 or 5 chars: "uk" | "uk-UA"
50
+ * @param {object} input - Application configuration
20
51
  */
21
- constructor(input?: {});
52
+ constructor(input?: object);
22
53
  /** @type {DB} */
23
54
  db: DB;
24
55
  /** @type {string} */
@@ -35,8 +66,8 @@ export default class AppCore {
35
66
  meta: object;
36
67
  /** @type {Record<string, Language>} */
37
68
  langs: Record<string, Language>;
38
- /** @type {(key: string, replacements: Record<string, string>) => string} */
39
- t: (key: string, replacements: Record<string, string>) => string;
69
+ /** @type {(key: string, replacements?: Record<string, string>) => string} */
70
+ t: (key: string, replacements?: Record<string, string>) => string;
40
71
  /**
41
72
  * Bootstrap internationalization by loading translations from database
42
73
  * @param {string} path - Path to i18n file with locale placeholder
@@ -71,5 +102,5 @@ export type Language = {
71
102
  icon?: string;
72
103
  locale?: string;
73
104
  };
74
- import DB from "@nan0web/db";
75
- import AppResult from "./AppResult.js";
105
+ import DB from '@nan0web/db';
106
+ import AppResult from './AppResult.js';
@@ -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
@@ -1,6 +1,9 @@
1
1
  export default AppCore;
2
2
  export type Language = import("./AppCore.js").Language;
3
- import AppCore from "./AppCore.js";
4
- import AppResult from "./AppResult.js";
5
- import { ExecutableCommand } from "@nan0web/protocol";
6
- export { AppCore, AppResult, ExecutableCommand };
3
+ import AppCore from './AppCore.js';
4
+ import AppResult from './AppResult.js';
5
+ import { ExecutableCommand } from '@nan0web/protocol';
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 };