@nan0web/core 1.0.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/LICENSE +15 -0
- package/README.md +88 -0
- package/package.json +54 -0
- package/src/AppCore.js +130 -0
- package/src/AppCore.test.js +59 -0
- package/src/AppResult.js +40 -0
- package/src/AppResult.test.js +45 -0
- package/src/README.md.js +219 -0
- package/src/index.js +13 -0
- package/types/AppCore.d.ts +75 -0
- package/types/AppResult.d.ts +40 -0
- package/types/index.d.ts +6 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025, ЯRаСлав (YaRaSLove) <support@yaro.page>
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and distribute this software for any purpose
|
|
6
|
+
with or without fee is hereby granted, provided that the above copyright notice
|
|
7
|
+
and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
|
10
|
+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
11
|
+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
12
|
+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
|
13
|
+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
|
14
|
+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
|
15
|
+
PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# @nan0web/core
|
|
2
|
+
|
|
3
|
+
Core application framework for nan0web providing a lightweight
|
|
4
|
+
DB‑backed state container with built‑in internationalisation.
|
|
5
|
+
|
|
6
|
+
|[Status](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Documentation|Test coverage|Features|Npm version|
|
|
7
|
+
|---|---|---|---|---|
|
|
8
|
+
|🟢 `98.9%` |🧪 [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 |— |
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
How to install with npm?
|
|
13
|
+
```bash
|
|
14
|
+
npm install @nan0web/core
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
How to install with pnpm?
|
|
18
|
+
```bash
|
|
19
|
+
pnpm add @nan0web/core
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
How to install with yarn?
|
|
23
|
+
```bash
|
|
24
|
+
yarn add @nan0web/core
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Basic usage – AppCore
|
|
28
|
+
|
|
29
|
+
Create an `AppCore` instance with a mock DB and inspect its state.
|
|
30
|
+
|
|
31
|
+
How to instantiate AppCore?
|
|
32
|
+
```js
|
|
33
|
+
import { AppCore } from "@nan0web/core"
|
|
34
|
+
const db = new DB()
|
|
35
|
+
const core = new AppCore({ db, title: "Demo", uri: "/demo", locale: "en" })
|
|
36
|
+
console.info(core.title) // ← Demo
|
|
37
|
+
console.info(core.uri) // ← /demo
|
|
38
|
+
```
|
|
39
|
+
## Internationalisation bootstrap
|
|
40
|
+
|
|
41
|
+
Load translation JSON from the DB and obtain a translation function.
|
|
42
|
+
|
|
43
|
+
How does bootstrapI18n load translations?
|
|
44
|
+
```js
|
|
45
|
+
const db = new DB({
|
|
46
|
+
predefined: [
|
|
47
|
+
["i18n/uk.json", { "hello": "Вітаю!" }]
|
|
48
|
+
]
|
|
49
|
+
})
|
|
50
|
+
await db.connect()
|
|
51
|
+
const core = new AppCore({ db, locale: "uk" })
|
|
52
|
+
await core.init()
|
|
53
|
+
const result = core.t("hello")
|
|
54
|
+
console.info(result) // ← Вітаю!
|
|
55
|
+
```
|
|
56
|
+
## State inspection
|
|
57
|
+
|
|
58
|
+
How to retrieve current state?
|
|
59
|
+
```js
|
|
60
|
+
const db = new DB()
|
|
61
|
+
const core = new AppCore({ db })
|
|
62
|
+
const state = core.state()
|
|
63
|
+
```
|
|
64
|
+
## AppResult helper
|
|
65
|
+
|
|
66
|
+
How to create an AppResult instance?
|
|
67
|
+
```js
|
|
68
|
+
import { AppResult } from "@nan0web/core"
|
|
69
|
+
const res = new AppResult({ content: "Done", priority: 2, meta: { ok: true } })
|
|
70
|
+
console.info(res.content[0]) // ← Done
|
|
71
|
+
```
|
|
72
|
+
## run() contract
|
|
73
|
+
|
|
74
|
+
The base `run` method throws an error – subclasses must implement it.
|
|
75
|
+
|
|
76
|
+
How does run() behave when not overridden?
|
|
77
|
+
```js
|
|
78
|
+
const db = new DB()
|
|
79
|
+
const core = new AppCore({ db })
|
|
80
|
+
await core.run() // ← throws an error → AppCore: run() must be implemented
|
|
81
|
+
```
|
|
82
|
+
## Contributing
|
|
83
|
+
|
|
84
|
+
How to contribute? - [check here](./CONTRIBUTING.md)
|
|
85
|
+
|
|
86
|
+
## License
|
|
87
|
+
|
|
88
|
+
How to license ISC? - [check here](./LICENSE)
|
package/package.json
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@nan0web/core",
|
|
3
|
+
"version": "1.0.0",
|
|
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/",
|
|
10
|
+
"types/",
|
|
11
|
+
"package.json",
|
|
12
|
+
"README.md"
|
|
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
|
+
"playground": "node playground/main.js",
|
|
23
|
+
"release": "nan0release publish",
|
|
24
|
+
"test": "node --test",
|
|
25
|
+
"test:docs": "node --test src/README.md.js",
|
|
26
|
+
"test:release": "node --test \"releases/**/*.test.js\"",
|
|
27
|
+
"test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
|
|
28
|
+
"test:coverage:collect": "nan0test coverage",
|
|
29
|
+
"test:status": "nan0test status --hide-name"
|
|
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": "workspace:*",
|
|
47
|
+
"@nan0web/test": "workspace:*",
|
|
48
|
+
"husky": "^9.1.7"
|
|
49
|
+
},
|
|
50
|
+
"dependencies": {
|
|
51
|
+
"@nan0web/interface": "link:../interface",
|
|
52
|
+
"@nan0web/protocol": "link:../protocol"
|
|
53
|
+
}
|
|
54
|
+
}
|
package/src/AppCore.js
ADDED
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
import DB from "@nan0web/db"
|
|
2
|
+
import { createT } from "@nan0web/i18n"
|
|
3
|
+
import AppResult from "./AppResult.js"
|
|
4
|
+
|
|
5
|
+
/** @typedef {{id: string, icon?: string, locale?: string}} Language */
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Core application class that handles database operations and internationalization.
|
|
9
|
+
*
|
|
10
|
+
* @class
|
|
11
|
+
* @property {DB} db - Database instance for data operations
|
|
12
|
+
* @property {string} locale - Current locale identifier (e.g. 'uk', 'en')
|
|
13
|
+
* @property {object} data - Application data storage
|
|
14
|
+
* @property {Record<string, Function>} actions - Application actions registry
|
|
15
|
+
* @property {object} meta - Application metadata
|
|
16
|
+
* @property {Function} t - Translation function
|
|
17
|
+
*/
|
|
18
|
+
export default class AppCore {
|
|
19
|
+
#initialized = false
|
|
20
|
+
/** @type {DB} */
|
|
21
|
+
db
|
|
22
|
+
/** @type {string} */
|
|
23
|
+
title = ""
|
|
24
|
+
/** @type {string} */
|
|
25
|
+
uri = ""
|
|
26
|
+
/** @type {string} */
|
|
27
|
+
locale = "uk"
|
|
28
|
+
/** @type {object} */
|
|
29
|
+
data = {}
|
|
30
|
+
/** @type {Record<string, Function>} */
|
|
31
|
+
actions = {}
|
|
32
|
+
/** @type {object} */
|
|
33
|
+
meta = {}
|
|
34
|
+
/** @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
|
|
44
|
+
/**
|
|
45
|
+
* 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"
|
|
49
|
+
*/
|
|
50
|
+
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")
|
|
64
|
+
}
|
|
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
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Bootstrap internationalization by loading translations from database
|
|
78
|
+
* @param {string} path - Path to i18n file with locale placeholder
|
|
79
|
+
* @returns {Promise<void>}
|
|
80
|
+
*/
|
|
81
|
+
async bootstrapI18n(path = `/i18n/{{locale}}.json`) {
|
|
82
|
+
const [code, country] = this.locale.split("-")
|
|
83
|
+
let uri = path.replace('{{locale}}', this.locale)
|
|
84
|
+
let i18n = await this.db.fetch(uri, { defaultValue: null })
|
|
85
|
+
if (null === i18n && country) {
|
|
86
|
+
uri = path.replace('{{locale}}', code)
|
|
87
|
+
i18n = await this.db.fetch(uri, { defaultValue: null })
|
|
88
|
+
}
|
|
89
|
+
this.t = createT(i18n ?? {})
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Initializes the application with async load.
|
|
94
|
+
* @returns {Promise<boolean>} True if initilized first time, false if already initialized
|
|
95
|
+
*/
|
|
96
|
+
async init() {
|
|
97
|
+
if (this.#initialized) return false
|
|
98
|
+
await this.bootstrapI18n()
|
|
99
|
+
this.#initialized = true
|
|
100
|
+
return true
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Get current application state
|
|
105
|
+
* @returns {{ data: any, actions: Record<string, Function>, meta: any, t: Function }} Current state object
|
|
106
|
+
*/
|
|
107
|
+
state() {
|
|
108
|
+
return {
|
|
109
|
+
data: this.data,
|
|
110
|
+
actions: this.actions,
|
|
111
|
+
meta: this.meta,
|
|
112
|
+
t: this.t
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Main application execution method
|
|
118
|
+
* @abstract Must be implemented in subclass
|
|
119
|
+
* @returns {Promise<AppResult>}
|
|
120
|
+
*/
|
|
121
|
+
async run() {
|
|
122
|
+
await this.init()
|
|
123
|
+
throw new Error('AppCore: run() must be implemented')
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
static from(input) {
|
|
127
|
+
if (input instanceof AppCore) return input
|
|
128
|
+
return new AppCore(input)
|
|
129
|
+
}
|
|
130
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { test, describe } from 'node:test'
|
|
2
|
+
import { strictEqual, deepEqual, rejects } from 'node:assert'
|
|
3
|
+
import AppCore from './AppCore.js'
|
|
4
|
+
import DB from '@nan0web/db'
|
|
5
|
+
|
|
6
|
+
describe('AppCore', () => {
|
|
7
|
+
test('constructor initializes properties correctly', () => {
|
|
8
|
+
const db = new DB()
|
|
9
|
+
const app = new AppCore({ db, locale: 'en' })
|
|
10
|
+
|
|
11
|
+
strictEqual(app.db, db)
|
|
12
|
+
strictEqual(app.locale, 'en')
|
|
13
|
+
deepEqual(app.data, {})
|
|
14
|
+
deepEqual(app.actions, {})
|
|
15
|
+
deepEqual(app.meta, {})
|
|
16
|
+
})
|
|
17
|
+
|
|
18
|
+
test('constructor uses default locale when not provided', () => {
|
|
19
|
+
const db = new DB()
|
|
20
|
+
const app = new AppCore({ db })
|
|
21
|
+
|
|
22
|
+
strictEqual(app.locale, 'uk')
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
test('bootstrapI18n loads translations from db', async () => {
|
|
26
|
+
const db = new DB()
|
|
27
|
+
const mockTranslations = { 'test.key': 'Test Value' }
|
|
28
|
+
db.fetch = async () => mockTranslations
|
|
29
|
+
|
|
30
|
+
const app = new AppCore({ db, locale: 'en' })
|
|
31
|
+
await app.bootstrapI18n('/custom/{{locale}}.json')
|
|
32
|
+
|
|
33
|
+
const result = app.t('test.key')
|
|
34
|
+
strictEqual(result, 'Test Value')
|
|
35
|
+
})
|
|
36
|
+
|
|
37
|
+
test('state() returns current application state', () => {
|
|
38
|
+
const db = new DB()
|
|
39
|
+
const app = new AppCore({ db })
|
|
40
|
+
|
|
41
|
+
const state = app.state()
|
|
42
|
+
deepEqual(Object.keys(state), ['data', 'actions', 'meta', 't'])
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
test('run() throws error when not implemented', async () => {
|
|
46
|
+
const db = new DB()
|
|
47
|
+
const app = new AppCore({ db })
|
|
48
|
+
|
|
49
|
+
await rejects(
|
|
50
|
+
async () => {
|
|
51
|
+
await app.run()
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
name: 'Error',
|
|
55
|
+
message: 'AppCore: run() must be implemented'
|
|
56
|
+
}
|
|
57
|
+
)
|
|
58
|
+
})
|
|
59
|
+
})
|
package/src/AppResult.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Unified application result format
|
|
3
|
+
* Used for both UI responses and logging
|
|
4
|
+
*
|
|
5
|
+
* @class
|
|
6
|
+
* @property {string[]} content - Result content lines
|
|
7
|
+
* @property {number} priority - Result priority level
|
|
8
|
+
* @property {object} meta - Result metadata
|
|
9
|
+
* @property {Error|null} error - Error object if any
|
|
10
|
+
*/
|
|
11
|
+
export default class AppResult {
|
|
12
|
+
/**
|
|
13
|
+
* Create an AppResult instance
|
|
14
|
+
* @param {object} input - Result data
|
|
15
|
+
* @param {string[]|string} input.content - Result content as string or array of strings
|
|
16
|
+
* @param {number} [input.priority=0] - Priority level (higher number means higher priority)
|
|
17
|
+
* @param {object} [input.meta={}] - Additional result metadata
|
|
18
|
+
* @param {Error|null} [input.error=null] - Error object if the result represents an error
|
|
19
|
+
*/
|
|
20
|
+
constructor({ content, priority = 0, meta = {}, error = null }) {
|
|
21
|
+
/** @type {string[]} */
|
|
22
|
+
this.content = Array.isArray(content) ? content : [content]
|
|
23
|
+
/** @type {number} */
|
|
24
|
+
this.priority = priority
|
|
25
|
+
/** @type {object} */
|
|
26
|
+
this.meta = meta
|
|
27
|
+
/** @type {Error|null} */
|
|
28
|
+
this.error = error
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Create AppResult from input data
|
|
33
|
+
* @param {object|AppResult} input - Input data or existing AppResult instance
|
|
34
|
+
* @returns {AppResult} AppResult instance
|
|
35
|
+
*/
|
|
36
|
+
static from(input) {
|
|
37
|
+
if (input instanceof AppResult) return input
|
|
38
|
+
return new AppResult(input)
|
|
39
|
+
}
|
|
40
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { test, describe } from 'node:test'
|
|
2
|
+
import { deepEqual, strictEqual, ok } from 'node:assert'
|
|
3
|
+
import AppResult from './AppResult.js'
|
|
4
|
+
|
|
5
|
+
describe('AppResult', () => {
|
|
6
|
+
test('constructor creates instance with string content', () => {
|
|
7
|
+
const result = new AppResult({
|
|
8
|
+
content: 'Test content',
|
|
9
|
+
priority: 1,
|
|
10
|
+
meta: { test: true }
|
|
11
|
+
})
|
|
12
|
+
|
|
13
|
+
deepEqual(result.content, ['Test content'])
|
|
14
|
+
strictEqual(result.priority, 1)
|
|
15
|
+
deepEqual(result.meta, { test: true })
|
|
16
|
+
strictEqual(result.error, null)
|
|
17
|
+
})
|
|
18
|
+
|
|
19
|
+
test('constructor creates instance with array content', () => {
|
|
20
|
+
const result = new AppResult({
|
|
21
|
+
content: ['Line 1', 'Line 2'],
|
|
22
|
+
priority: 2
|
|
23
|
+
})
|
|
24
|
+
|
|
25
|
+
deepEqual(result.content, ['Line 1', 'Line 2'])
|
|
26
|
+
strictEqual(result.priority, 2)
|
|
27
|
+
deepEqual(result.meta, {})
|
|
28
|
+
strictEqual(result.error, null)
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
test('static from() returns same instance if AppResult provided', () => {
|
|
32
|
+
const original = new AppResult({ content: 'test' })
|
|
33
|
+
const result = AppResult.from(original)
|
|
34
|
+
|
|
35
|
+
strictEqual(result, original)
|
|
36
|
+
})
|
|
37
|
+
|
|
38
|
+
test('static from() creates new instance if plain object provided', () => {
|
|
39
|
+
const input = { content: 'test' }
|
|
40
|
+
const result = AppResult.from(input)
|
|
41
|
+
|
|
42
|
+
ok(result instanceof AppResult)
|
|
43
|
+
deepEqual(result.content, ['test'])
|
|
44
|
+
})
|
|
45
|
+
})
|
package/src/README.md.js
ADDED
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
import { describe, it, before, beforeEach } from "node:test"
|
|
2
|
+
import assert from "node:assert/strict"
|
|
3
|
+
import FS from "@nan0web/db-fs"
|
|
4
|
+
import { NoConsole } from "@nan0web/log"
|
|
5
|
+
import { DocsParser, DatasetParser } from "@nan0web/test"
|
|
6
|
+
import {
|
|
7
|
+
AppCore,
|
|
8
|
+
AppResult,
|
|
9
|
+
ExecutableCommand,
|
|
10
|
+
} from "./index.js"
|
|
11
|
+
import DB from "@nan0web/db"
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Load package.json once before any test.
|
|
15
|
+
*/
|
|
16
|
+
let pkg
|
|
17
|
+
const fs = new FS()
|
|
18
|
+
|
|
19
|
+
before(async () => {
|
|
20
|
+
const doc = await fs.loadDocument("package.json", {})
|
|
21
|
+
pkg = doc || {}
|
|
22
|
+
})
|
|
23
|
+
|
|
24
|
+
let console = new NoConsole()
|
|
25
|
+
|
|
26
|
+
beforeEach(() => {
|
|
27
|
+
console = new NoConsole()
|
|
28
|
+
})
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Core test suite that also serves as source for README generation.
|
|
32
|
+
*
|
|
33
|
+
* Block comments inside each `it` are extracted by DocsParser to build the final README.
|
|
34
|
+
*/
|
|
35
|
+
function testRender() {
|
|
36
|
+
/**
|
|
37
|
+
* @docs
|
|
38
|
+
* # @nan0web/core
|
|
39
|
+
*
|
|
40
|
+
* Core application framework for nan0web providing a lightweight
|
|
41
|
+
* DB‑backed state container with built‑in internationalisation.
|
|
42
|
+
*
|
|
43
|
+
* <!-- %PACKAGE_STATUS% -->
|
|
44
|
+
*
|
|
45
|
+
* ## Installation
|
|
46
|
+
*/
|
|
47
|
+
it("How to install with npm?", () => {
|
|
48
|
+
/**
|
|
49
|
+
* ```bash
|
|
50
|
+
* npm install @nan0web/core
|
|
51
|
+
* ```
|
|
52
|
+
*/
|
|
53
|
+
assert.equal(pkg.name, "@nan0web/core")
|
|
54
|
+
})
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* @docs
|
|
58
|
+
*/
|
|
59
|
+
it("How to install with pnpm?", () => {
|
|
60
|
+
/**
|
|
61
|
+
* ```bash
|
|
62
|
+
* pnpm add @nan0web/core
|
|
63
|
+
* ```
|
|
64
|
+
*/
|
|
65
|
+
assert.equal(pkg.name, "@nan0web/core")
|
|
66
|
+
})
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* @docs
|
|
70
|
+
*/
|
|
71
|
+
it("How to install with yarn?", () => {
|
|
72
|
+
/**
|
|
73
|
+
* ```bash
|
|
74
|
+
* yarn add @nan0web/core
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
77
|
+
assert.equal(pkg.name, "@nan0web/core")
|
|
78
|
+
})
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* @docs
|
|
82
|
+
* ## Basic usage – AppCore
|
|
83
|
+
*
|
|
84
|
+
* Create an `AppCore` instance with a mock DB and inspect its state.
|
|
85
|
+
*/
|
|
86
|
+
it("How to instantiate AppCore?", () => {
|
|
87
|
+
//import { AppCore } from "@nan0web/core"
|
|
88
|
+
const db = new DB()
|
|
89
|
+
const core = new AppCore({ db, title: "Demo", uri: "/demo", locale: "en" })
|
|
90
|
+
console.info(core.title) // ← Demo
|
|
91
|
+
console.info(core.uri) // ← /demo
|
|
92
|
+
assert.equal(core.title, "Demo")
|
|
93
|
+
assert.equal(core.uri, "/demo")
|
|
94
|
+
assert.equal(core.locale, "en")
|
|
95
|
+
})
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* @docs
|
|
99
|
+
* ## Internationalisation bootstrap
|
|
100
|
+
*
|
|
101
|
+
* Load translation JSON from the DB and obtain a translation function.
|
|
102
|
+
*/
|
|
103
|
+
it("How does bootstrapI18n load translations?", async () => {
|
|
104
|
+
const db = new DB({
|
|
105
|
+
predefined: [
|
|
106
|
+
["i18n/uk.json", { "hello": "Вітаю!" }]
|
|
107
|
+
]
|
|
108
|
+
})
|
|
109
|
+
await db.connect()
|
|
110
|
+
const core = new AppCore({ db, locale: "uk" })
|
|
111
|
+
await core.init()
|
|
112
|
+
const result = core.t("hello")
|
|
113
|
+
console.info(result) // ← Вітаю!
|
|
114
|
+
assert.equal(result, "Вітаю!")
|
|
115
|
+
})
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* @docs
|
|
119
|
+
* ## State inspection
|
|
120
|
+
*/
|
|
121
|
+
it("How to retrieve current state?", () => {
|
|
122
|
+
const db = new DB()
|
|
123
|
+
const core = new AppCore({ db })
|
|
124
|
+
const state = core.state()
|
|
125
|
+
assert.deepEqual(Object.keys(state), ["data", "actions", "meta", "t"])
|
|
126
|
+
assert.ok(typeof state.t === "function")
|
|
127
|
+
})
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* @docs
|
|
131
|
+
* ## AppResult helper
|
|
132
|
+
*/
|
|
133
|
+
it("How to create an AppResult instance?", () => {
|
|
134
|
+
//import { AppResult } from "@nan0web/core"
|
|
135
|
+
const res = new AppResult({ content: "Done", priority: 2, meta: { ok: true } })
|
|
136
|
+
console.info(res.content[0]) // ← Done
|
|
137
|
+
assert.equal(res.content[0], "Done")
|
|
138
|
+
assert.equal(res.priority, 2)
|
|
139
|
+
assert.deepEqual(res.meta, { ok: true })
|
|
140
|
+
assert.equal(res.error, null)
|
|
141
|
+
})
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* @docs
|
|
145
|
+
* ## run() contract
|
|
146
|
+
*
|
|
147
|
+
* The base `run` method throws an error – subclasses must implement it.
|
|
148
|
+
*/
|
|
149
|
+
it("How does run() behave when not overridden?", async () => {
|
|
150
|
+
const db = new DB()
|
|
151
|
+
const core = new AppCore({ db })
|
|
152
|
+
//await core.run() // ← throws an error → AppCore: run() must be implemented
|
|
153
|
+
assert.ok(core)
|
|
154
|
+
await assert.rejects(
|
|
155
|
+
async () => {
|
|
156
|
+
await core.run()
|
|
157
|
+
},
|
|
158
|
+
{
|
|
159
|
+
name: "Error",
|
|
160
|
+
message: "AppCore: run() must be implemented"
|
|
161
|
+
}
|
|
162
|
+
)
|
|
163
|
+
})
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* ## ExecutableCommand exposure
|
|
167
|
+
*/
|
|
168
|
+
it("Are exported commands available?", () => {
|
|
169
|
+
assert.ok(ExecutableCommand)
|
|
170
|
+
})
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* ## TypeScript declarations
|
|
174
|
+
*/
|
|
175
|
+
it("Does package expose declaration files?", () => {
|
|
176
|
+
assert.equal(pkg.types, "types/index.d.ts")
|
|
177
|
+
})
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* @docs
|
|
181
|
+
* ## Contributing
|
|
182
|
+
*/
|
|
183
|
+
it("How to contribute? - [check here](./CONTRIBUTING.md)", async () => {
|
|
184
|
+
assert.equal(pkg.scripts?.precommit, "npm test")
|
|
185
|
+
assert.equal(pkg.scripts?.prepush, "npm test")
|
|
186
|
+
assert.equal(pkg.scripts?.prepare, "husky")
|
|
187
|
+
const text = await fs.loadDocument("CONTRIBUTING.md")
|
|
188
|
+
const str = String(text)
|
|
189
|
+
assert.ok(str.includes("# Contributing"))
|
|
190
|
+
})
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* @docs
|
|
194
|
+
* ## License
|
|
195
|
+
*/
|
|
196
|
+
it("How to license ISC? - [check here](./LICENSE)", async () => {
|
|
197
|
+
/** @docs */
|
|
198
|
+
const text = await fs.loadDocument("LICENSE")
|
|
199
|
+
assert.ok(String(text).includes("ISC"))
|
|
200
|
+
})
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/* Run the test suite that also generates the README */
|
|
204
|
+
describe("README.md testing", testRender)
|
|
205
|
+
|
|
206
|
+
describe("Rendering README.md", async () => {
|
|
207
|
+
let text = ""
|
|
208
|
+
const format = new Intl.NumberFormat("en-US").format
|
|
209
|
+
const parser = new DocsParser()
|
|
210
|
+
text = String(parser.decode(testRender))
|
|
211
|
+
await fs.saveDocument("README.md", text)
|
|
212
|
+
const dataset = DatasetParser.parse(text, pkg.name)
|
|
213
|
+
await fs.saveDocument(".datasets/README.dataset.jsonl", dataset)
|
|
214
|
+
|
|
215
|
+
it(`document is rendered in README.md [${format(Buffer.byteLength(text))}b]`, async () => {
|
|
216
|
+
const readme = await fs.loadDocument("README.md")
|
|
217
|
+
assert.ok(readme.includes("## Installation"))
|
|
218
|
+
})
|
|
219
|
+
})
|
package/src/index.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { ExecutableCommand } from "@nan0web/protocol"
|
|
2
|
+
import AppCore from "./AppCore.js"
|
|
3
|
+
import AppResult from "./AppResult.js"
|
|
4
|
+
|
|
5
|
+
/** @typedef {import("./AppCore.js").Language} Language */
|
|
6
|
+
|
|
7
|
+
export {
|
|
8
|
+
AppCore,
|
|
9
|
+
AppResult,
|
|
10
|
+
ExecutableCommand,
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export default AppCore
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/** @typedef {{id: string, icon?: string, locale?: string}} Language */
|
|
2
|
+
/**
|
|
3
|
+
* Core application class that handles database operations and internationalization.
|
|
4
|
+
*
|
|
5
|
+
* @class
|
|
6
|
+
* @property {DB} db - Database instance for data operations
|
|
7
|
+
* @property {string} locale - Current locale identifier (e.g. 'uk', 'en')
|
|
8
|
+
* @property {object} data - Application data storage
|
|
9
|
+
* @property {Record<string, Function>} actions - Application actions registry
|
|
10
|
+
* @property {object} meta - Application metadata
|
|
11
|
+
* @property {Function} t - Translation function
|
|
12
|
+
*/
|
|
13
|
+
export default class AppCore {
|
|
14
|
+
static from(input: any): AppCore;
|
|
15
|
+
/**
|
|
16
|
+
* 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"
|
|
20
|
+
*/
|
|
21
|
+
constructor(input?: {});
|
|
22
|
+
/** @type {DB} */
|
|
23
|
+
db: DB;
|
|
24
|
+
/** @type {string} */
|
|
25
|
+
title: string;
|
|
26
|
+
/** @type {string} */
|
|
27
|
+
uri: string;
|
|
28
|
+
/** @type {string} */
|
|
29
|
+
locale: string;
|
|
30
|
+
/** @type {object} */
|
|
31
|
+
data: object;
|
|
32
|
+
/** @type {Record<string, Function>} */
|
|
33
|
+
actions: Record<string, Function>;
|
|
34
|
+
/** @type {object} */
|
|
35
|
+
meta: object;
|
|
36
|
+
/** @type {Record<string, Language>} */
|
|
37
|
+
langs: Record<string, Language>;
|
|
38
|
+
/** @type {(key: string, replacements: Record<string, string>) => string} */
|
|
39
|
+
t: (key: string, replacements: Record<string, string>) => string;
|
|
40
|
+
/**
|
|
41
|
+
* Bootstrap internationalization by loading translations from database
|
|
42
|
+
* @param {string} path - Path to i18n file with locale placeholder
|
|
43
|
+
* @returns {Promise<void>}
|
|
44
|
+
*/
|
|
45
|
+
bootstrapI18n(path?: string): Promise<void>;
|
|
46
|
+
/**
|
|
47
|
+
* Initializes the application with async load.
|
|
48
|
+
* @returns {Promise<boolean>} True if initilized first time, false if already initialized
|
|
49
|
+
*/
|
|
50
|
+
init(): Promise<boolean>;
|
|
51
|
+
/**
|
|
52
|
+
* Get current application state
|
|
53
|
+
* @returns {{ data: any, actions: Record<string, Function>, meta: any, t: Function }} Current state object
|
|
54
|
+
*/
|
|
55
|
+
state(): {
|
|
56
|
+
data: any;
|
|
57
|
+
actions: Record<string, Function>;
|
|
58
|
+
meta: any;
|
|
59
|
+
t: Function;
|
|
60
|
+
};
|
|
61
|
+
/**
|
|
62
|
+
* Main application execution method
|
|
63
|
+
* @abstract Must be implemented in subclass
|
|
64
|
+
* @returns {Promise<AppResult>}
|
|
65
|
+
*/
|
|
66
|
+
run(): Promise<AppResult>;
|
|
67
|
+
#private;
|
|
68
|
+
}
|
|
69
|
+
export type Language = {
|
|
70
|
+
id: string;
|
|
71
|
+
icon?: string;
|
|
72
|
+
locale?: string;
|
|
73
|
+
};
|
|
74
|
+
import DB from "@nan0web/db";
|
|
75
|
+
import AppResult from "./AppResult.js";
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Unified application result format
|
|
3
|
+
* Used for both UI responses and logging
|
|
4
|
+
*
|
|
5
|
+
* @class
|
|
6
|
+
* @property {string[]} content - Result content lines
|
|
7
|
+
* @property {number} priority - Result priority level
|
|
8
|
+
* @property {object} meta - Result metadata
|
|
9
|
+
* @property {Error|null} error - Error object if any
|
|
10
|
+
*/
|
|
11
|
+
export default class AppResult {
|
|
12
|
+
/**
|
|
13
|
+
* Create AppResult from input data
|
|
14
|
+
* @param {object|AppResult} input - Input data or existing AppResult instance
|
|
15
|
+
* @returns {AppResult} AppResult instance
|
|
16
|
+
*/
|
|
17
|
+
static from(input: object | AppResult): AppResult;
|
|
18
|
+
/**
|
|
19
|
+
* Create an AppResult instance
|
|
20
|
+
* @param {object} input - Result data
|
|
21
|
+
* @param {string[]|string} input.content - Result content as string or array of strings
|
|
22
|
+
* @param {number} [input.priority=0] - Priority level (higher number means higher priority)
|
|
23
|
+
* @param {object} [input.meta={}] - Additional result metadata
|
|
24
|
+
* @param {Error|null} [input.error=null] - Error object if the result represents an error
|
|
25
|
+
*/
|
|
26
|
+
constructor({ content, priority, meta, error }: {
|
|
27
|
+
content: string[] | string;
|
|
28
|
+
priority?: number | undefined;
|
|
29
|
+
meta?: object;
|
|
30
|
+
error?: Error | null | undefined;
|
|
31
|
+
});
|
|
32
|
+
/** @type {string[]} */
|
|
33
|
+
content: string[];
|
|
34
|
+
/** @type {number} */
|
|
35
|
+
priority: number;
|
|
36
|
+
/** @type {object} */
|
|
37
|
+
meta: object;
|
|
38
|
+
/** @type {Error|null} */
|
|
39
|
+
error: Error | null;
|
|
40
|
+
}
|
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export default AppCore;
|
|
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 };
|