@nan0web/core 1.0.1 → 1.0.5

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
- |[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 |— |
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
package/package.json CHANGED
@@ -1,15 +1,15 @@
1
1
  {
2
2
  "name": "@nan0web/core",
3
- "version": "1.0.1",
3
+ "version": "1.0.5",
4
4
  "description": "Core application framework for nan0web with database handling, internationalization, and interface connectivity",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
7
7
  "types": "types/index.d.ts",
8
8
  "files": [
9
- "src/",
10
- "types/",
11
- "package.json",
12
- "README.md"
9
+ "src/**/*.js",
10
+ "!src/**/*.test.js",
11
+ "!src/README.md.js",
12
+ "types/**/*.d.ts"
13
13
  ],
14
14
  "scripts": {
15
15
  "build": "tsc",
@@ -19,14 +19,16 @@
19
19
  "prepush": "npm test",
20
20
  "prepare": "husky",
21
21
  "prepublishOnly": "npm test && npm run build",
22
- "playground": "node playground/main.js",
22
+ "play": "node play/main.js",
23
23
  "release": "nan0release publish",
24
- "test": "node --test",
24
+ "knip": "knip --production",
25
+ "test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
25
26
  "test:docs": "node --test src/README.md.js",
26
27
  "test:release": "node --test \"releases/**/*.test.js\"",
27
28
  "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
28
29
  "test:coverage:collect": "nan0test coverage",
29
- "test:status": "nan0test status --hide-name"
30
+ "test:status": "nan0test status --hide-name",
31
+ "test:all": "npm run test && npm run test:docs && npm run build && npm run knip"
30
32
  },
31
33
  "keywords": [
32
34
  "nan0",
@@ -43,12 +45,13 @@
43
45
  "license": "ISC",
44
46
  "packageManager": "pnpm@10.11.0",
45
47
  "devDependencies": {
46
- "@nan0web/release": "workspace:*",
47
- "@nan0web/test": "workspace:*",
48
- "husky": "^9.1.7"
48
+ "@nan0web/release": "*",
49
+ "@nan0web/test": "*",
50
+ "husky": "^9.1.7",
51
+ "knip": "^5.82.1"
49
52
  },
50
53
  "dependencies": {
51
- "@nan0web/interface": "link:../interface",
52
- "@nan0web/protocol": "link:../protocol"
54
+ "@nan0web/db": "*",
55
+ "@nan0web/protocol": "*"
53
56
  }
54
57
  }
package/src/AppCore.js CHANGED
@@ -1,6 +1,6 @@
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 AppResult from './AppResult.js'
4
4
 
5
5
  /** @typedef {{id: string, icon?: string, locale?: string}} Language */
6
6
 
@@ -16,15 +16,16 @@ import AppResult from "./AppResult.js"
16
16
  * @property {Function} t - Translation function
17
17
  */
18
18
  export default class AppCore {
19
+ static DB = DB
19
20
  #initialized = false
20
21
  /** @type {DB} */
21
22
  db
22
23
  /** @type {string} */
23
- title = ""
24
+ title = ''
24
25
  /** @type {string} */
25
- uri = ""
26
+ uri = ''
26
27
  /** @type {string} */
27
- locale = "uk"
28
+ locale = 'uk'
28
29
  /** @type {object} */
29
30
  data = {}
30
31
  /** @type {Record<string, Function>} */
@@ -34,18 +35,16 @@ export default class AppCore {
34
35
  /** @type {Record<string, Language>} */
35
36
  langs = {
36
37
  en: {
37
- id: "en",
38
- icon: "🇬🇧",
39
- locale: "en-GB"
40
- }
38
+ id: 'en',
39
+ icon: '🇬🇧',
40
+ locale: 'en-GB',
41
+ },
41
42
  }
42
- /** @type {(key: string, replacements: Record<string, string>) => string} */
43
- t = (key, replacements) => key
43
+ /** @type {(key: string, replacements?: Record<string, string>) => string} */
44
+ t = (key, replacements = {}) => key
44
45
  /**
45
46
  * 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"
47
+ * @param {object} input - Application configuration
49
48
  */
50
49
  constructor(input = {}) {
51
50
  const {
@@ -59,8 +58,8 @@ export default class AppCore {
59
58
  langs = this.langs,
60
59
  t = this.t,
61
60
  } = input
62
- if (!(db instanceof DB)) {
63
- throw new Error("Database must be an instance of @nan0web/db.DB")
61
+ if (db && typeof db.fetch !== 'function') {
62
+ throw new Error('Database must be an instance of @nan0web/db.DB')
64
63
  }
65
64
  this.db = db
66
65
  this.title = String(title)
@@ -79,7 +78,7 @@ export default class AppCore {
79
78
  * @returns {Promise<void>}
80
79
  */
81
80
  async bootstrapI18n(path = `/i18n/{{locale}}.json`) {
82
- const [code, country] = this.locale.split("-")
81
+ const [code, country] = this.locale.split('-')
83
82
  let uri = path.replace('{{locale}}', this.locale)
84
83
  let i18n = await this.db.fetch(uri, { defaultValue: null })
85
84
  if (null === i18n && country) {
@@ -109,7 +108,7 @@ export default class AppCore {
109
108
  data: this.data,
110
109
  actions: this.actions,
111
110
  meta: this.meta,
112
- t: this.t
111
+ t: this.t,
113
112
  }
114
113
  }
115
114
 
package/src/index.js CHANGED
@@ -1,13 +1,9 @@
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 AppCore from './AppCore.js'
3
+ import AppResult from './AppResult.js'
4
4
 
5
5
  /** @typedef {import("./AppCore.js").Language} Language */
6
6
 
7
- export {
8
- AppCore,
9
- AppResult,
10
- ExecutableCommand,
11
- }
7
+ export { AppCore, AppResult, ExecutableCommand }
12
8
 
13
9
  export default AppCore
@@ -11,14 +11,13 @@
11
11
  * @property {Function} t - Translation function
12
12
  */
13
13
  export default class AppCore {
14
+ static DB: typeof DB;
14
15
  static from(input: any): AppCore;
15
16
  /**
16
17
  * 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"
18
+ * @param {object} input - Application configuration
20
19
  */
21
- constructor(input?: {});
20
+ constructor(input?: object);
22
21
  /** @type {DB} */
23
22
  db: DB;
24
23
  /** @type {string} */
@@ -35,8 +34,8 @@ export default class AppCore {
35
34
  meta: object;
36
35
  /** @type {Record<string, Language>} */
37
36
  langs: Record<string, Language>;
38
- /** @type {(key: string, replacements: Record<string, string>) => string} */
39
- t: (key: string, replacements: Record<string, string>) => string;
37
+ /** @type {(key: string, replacements?: Record<string, string>) => string} */
38
+ t: (key: string, replacements?: Record<string, string>) => string;
40
39
  /**
41
40
  * Bootstrap internationalization by loading translations from database
42
41
  * @param {string} path - Path to i18n file with locale placeholder
@@ -71,5 +70,5 @@ export type Language = {
71
70
  icon?: string;
72
71
  locale?: string;
73
72
  };
74
- import DB from "@nan0web/db";
75
- import AppResult from "./AppResult.js";
73
+ import DB from '@nan0web/db';
74
+ import AppResult from './AppResult.js';
package/types/index.d.ts CHANGED
@@ -1,6 +1,6 @@
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";
3
+ import AppCore from './AppCore.js';
4
+ import AppResult from './AppResult.js';
5
+ import { ExecutableCommand } from '@nan0web/protocol';
6
6
  export { AppCore, AppResult, ExecutableCommand };
@@ -1,59 +0,0 @@
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
- })
@@ -1,45 +0,0 @@
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 DELETED
@@ -1,219 +0,0 @@
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
- })