vrack2-core 0.0.1 → 1.0.0

package/src/ImportManager.ts

@@ -1,8 +1,10 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, lstatSync, readdirSync, statSync } from "fs";
 import path from "path";
+
 import ErrorManager from "./errors/ErrorManager";
 import Rule from "./validator/Rule";
 
+
 ErrorManager.register('ImportManager', 'kwRobwFPzc5g', 'IM_FILE_NOT_FOUND',
     'Import file not found', {
     filePath: Rule.string().description('Path to file')
@@ -52,6 +54,14 @@ export default class ImportManager {
         return ti
     }
 
+    /**
+     * Import class like a vrack2 device style
+     * 
+     * Разделяюет переданную строку пути на 2 части. 
+     * Первая честь является названием модуля, а вторая часть классом внутри него 
+     * 
+     * @example ImportManager.importClass('vrack2-core.Container')
+    */
     static async importClass(cs:string) {
         const acts = cs.split('.')
         const vendor = acts.shift()
@@ -65,7 +75,14 @@ export default class ImportManager {
         return ret
     }
 
-    static async importJSON(filePath: string){
+    /**
+     * Attempts to open a file and use its contents as json
+     * 
+     * Returns the result of parsing json
+     * 
+     * @returns {any} json parsing result
+    */
+    static importJSON(filePath: string){
         if (!path.isAbsolute(filePath)){
             filePath =  path.join(ImportManager.systemPath(), filePath)
         }
@@ -76,6 +93,83 @@ export default class ImportManager {
         throw ErrorManager.make('IM_FILE_NOT_FOUND', { filePath })
     }
 
+    /**
+     * Returns the class name in the style of import vrack
+     * 
+     * return `Container` from 'vrack2-core.Container' string
+     * 
+     * @param cs Import class string
+     * 
+    */
+    static importClassName(cs: string){
+        const acts = cs.split('.')
+        return acts.pop()
+    }
+
+    /**
+     * Returns the vendor name in the style of import vrack
+     * 
+     * return `vrack2-core` from 'vrack2-core.Container' string
+     * 
+     * @param cs Import class string
+    */
+    static importVendorName(cs: string){
+        const acts = cs.split('.')
+        return acts.shift()
+    }
+
+    /**
+     * Returns a list of directories in the specified directory.
+     * 
+     * @param dir path to directory
+     */
+    static dirList(dir: string){
+        const files = readdirSync(dir)
+        const result = []
+        for (const i in files) if (statSync(path.join(dir, files[i])).isDirectory()) result.push(files[i])
+        return result
+    }
+
+    /**
+     * Returns a list of files in the specified directory.
+     * 
+     * @param dir path to directory
+     */
+    static fileList(dir: string){
+        const files = readdirSync(dir)
+        const result = []
+        for (const i in files) if (!statSync(path.join(dir, files[i])).isDirectory()) result.push(files[i])
+        return result
+    }
+
+    /**
+     * Checks if a path is a directory
+     * 
+     * @param dir path to directory
+    */
+    static isDir(dir: string){
+        if (existsSync(dir) && lstatSync(dir).isDirectory()) return true
+        return false
+    }
+
+    /**
+     * Checks if a path is a directory
+     * 
+     * @param f path to file
+    */
+    static isFile(f: string){
+        if (existsSync(f) && lstatSync(f).isFile()) return true
+        return false
+    }
+
+    /**
+     * Try JSON parse
+     * 
+     * Returns an CoreError[IM_JSON_INCORRECT] if there is a parsing error.
+     * 
+     * @param jsonRaw JSON raw string
+     * 
+    */
     static tryJsonParse(jsonRaw: string) : any{
         try {
             return JSON.parse(jsonRaw)
@@ -86,22 +180,36 @@ export default class ImportManager {
         }
     }
     
+    /**
+     * Return directory where VRack was launched from
+    */
+    static systemPath(){
+        return process.cwd()
+    }
+
+    /**
+     * Camelize string for input & action handlers
+     * 
+     * Splits a string with a dot and returns the string 
+     * with capital letters starting from the second word
+     * 
+     * @example
+     * ```ts
+     * ImportManager.camelize('input.device.port') // return inputDevicePort
+     * ```
+     * 
+     * @param text Like a `input.device.port` string
+    */
     static camelize(text: string) {
         return text.replace(/^([A-Z])|[.]+(\w)/g, function (match, p1, p2, offset) {
             if (p2) return p2.toUpperCase()
             return p1.toLowerCase()
         })
     }
-    
-
-    protected static getSub(imp: any, get: string){
-        return imp[get]
-    }
-
-    static systemPath(){
-        return process.cwd()
-    }
 
+    /**
+     * Try import method
+    */
     protected static async tryImport(p: string){
         try {
             return await import(p)

package/src/MainProcess.ts

@@ -1,18 +1,63 @@
+import Bootstrap, { IBootListConfig } from "./Bootstrap";
 import Container from "./Container";
-import DeviceManager from "./DeviceManager";
 import IServiceStructure from "./IServiceStructure";
-import ImportManager from "./ImportManager";
 
+interface IMainProcessInternalOptions {
+    /** Container ID  */
+    id: string;
+    /** Service structure */
+    service: IServiceStructure;
+    /** Path to extends conf file */
+    confFile? : string; 
+    /** Container class */
+    ContainerClass: typeof Container;
+    /** Bootstrap list config */
+    bootstrap: IBootListConfig
+}
+
+export interface IMainProcessOptions {
+    /** Container ID  */
+    id: string;
+    /** Service structure */
+    service: IServiceStructure;
+    /** Path to extends conf file */
+    confFile? : string; 
+    /** Container class */
+    ContainerClass?: typeof Container;
+    /** Bootstrap list config */
+    bootstrap?: IBootListConfig
+}
 
 export default class MainProcess  {
     Container: Container
-    DeviceManager : DeviceManager
-    constructor(ContainerClass: typeof Container, DeviceManagerClass: typeof DeviceManager, service: IServiceStructure){
-        this.DeviceManager = new DeviceManagerClass(ImportManager.systemPath(), './devices')
-        this.DeviceManager.updateList()
-        this.Container = new ContainerClass(service, this.DeviceManager)
+    options: IMainProcessInternalOptions = {
+        id: 'vrack2',
+        service: { 
+            devices:[] , 
+            connections:[],
+        },
+        ContainerClass: Container,
+        bootstrap: {
+            DeviceManager: { path: 'vrack2-core.DeviceManager', options: { storageDir: './storage' }},
+            DeviceStorage: { path: 'vrack2-core.DeviceFileStorage', options: {} },
+            StructureStorage: { path: 'vrack2-core.StructureStorage', options: {} },
+            DeviceMetrics: { path: 'vrack2-core.DeviceMetrics', options: {} }
+        }
+    }
+    Bootstrap: Bootstrap
+    constructor(config: IMainProcessOptions){
+        Object.assign(this.options, config)
+        this.Bootstrap = new Bootstrap(this.options.bootstrap)
+        this.Container = new this.options.ContainerClass(this.options.id, this.options.service, this.Bootstrap, this.options.confFile)
     }
+
     async run (){
-        await this.Container.run()
+        await this.check()
+        await this.Container.runProcess()
+    }
+
+    async check(){
+        await this.Bootstrap.loadBootList(this.Container)
+        await this.Container.init()
     }
 }

package/src/Utility.ts

@@ -1,44 +1,43 @@
 /*
- * Copyright © 2022 Boris Bobylev. All rights reserved.
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
  * Licensed under the Apache License, Version 2.0
 */
 
-/**
- * Преобразует строку типа `aaa.bbb.ccc` в строку типа `aaaBbbCcc`
- * Обратите внимание на то, что первый символ первого актета не преобразуется,
- * если есть такая необходимость, можно добавить точку в самое начало строки `.aaa.bbb.ccc`
- * результат выполнения будет `AaaBbbCcc`
-*/
-function camelize(text: string) {
-    return text.replace(/^([A-Z])|[.]+(\w)/g, function (match, p1, p2, offset) {
-        if (p2) return p2.toUpperCase()
-        return p1.toLowerCase()
-    })
-}
+import util from "util"
 
-/**
- * Проверяет, является ли JSON строка валидным JSON
- * Обычно используется, когда неважно в чем конретно проблема в JSON 
- * и нужно просто узнать валидный он или нет
- * 
-*/
-function validJSON(text: string) {
-    try {
-        const cfg = JSON.parse(text)
-        if (!(cfg && typeof cfg === 'object')) return false
-        return cfg
-    } catch (e) {
-        return false
+export default class Utility {
+    /** 
+     * Check device name (device ID)
+     * */
+    static async isDeviceName(name: string) {
+        return /^[a-zA-Z0-9_*-:]+$/.test(name)
     }
-}
 
-/**
- * Преобразует строку в локальный путь VRack, на данный момент
- * это просто приведение строки в lowerCase
- * 
-*/
-function toPath(text: string) {
-    return text.toLowerCase()
-}
+    /**
+     * Форматирует любое значение в красивую строку (с отступами, подсветкой и т. д.).
+     * Поддерживает: объекты, массивы, примитивы, Error, Map, Set, Buffer и др.
+     * 
+     * @param {any} value - Значение для форматирования
+     * @param {object} [options] - Дополнительные опции (как в `util.inspect()`)
+     * @returns {string} Отформатированная строка
+     */
+    static prettyFormat(value: any, options = {}) {
+        const defaultOptions = {
+            depth: null,      // Показывать всю вложенность
+            colors: true,     // Цвета в терминале
+            compact: false,   // Не сжимать в одну строку
+            breakLength: 80,  // Длина строки перед переносом
+            sorted: false,    // Сортировка ключей (если true)
+            showHidden: false, // Показывать скрытые свойства (для объектов)
+            ...options        // Переопределение дефолтных опций
+        };
 
-export { camelize, validJSON, toPath }
+        // Особые случаи (если нужно обработать их по-особому)
+        if (value instanceof Error) {
+            return value.stack; // Стек ошибки
+        }
+
+        // Всё остальное форматируем через util.inspect()
+        return util.inspect(value, defaultOptions);
+    }
+}

package/src/actions/Action.ts

@@ -3,9 +3,21 @@
  * Licensed under the Apache License, Version 2.0
 */
 
+import BasicAction from "./BasicAction";
 import GlobalAction from "./GlobalAction";
 
+/**
+ * A class for defining new actions. 
+ * It is not necessary to use `new Action`. 
+ * You must use the static method `Action.global` to define a new action
+*/
 export default class Action {
+
+    /**
+     * The only type of action game at the moment. Does not have any special properties. 
+     * 
+     * @see BasicAction 
+    */
     static global() {
         return new GlobalAction()
     }

package/src/actions/BasicAction.ts

@@ -8,6 +8,10 @@ import IAction from "./IAction";
 import ILocalAction from "./ILocalAction"
 
 
+/**
+ * Action base class. 
+ * Forms settings for a new action in `fluent interface` style
+*/
 export default class BasicAction {
     protected action: ILocalAction
 
@@ -20,21 +24,80 @@ export default class BasicAction {
         }
     }
 
+    /**
+     * Sets the requirements for incoming `Action` parameters
+     * These rules will be applied every time the user invokes this action
+     * 
+     * The method necessarily accepts an object. 
+     * An action method cannot accept anything other than an object
+     * 
+     * @example 
+     * 
+     * ```ts
+     * Action.global().requirements({
+     *       id: Rule.number().require().default(0).description('Unique ID'),
+     * })
+     * ```
+     * @param req Object of BasicType rules
+    */
     requirements(req: { [key: string]: BasicType; }){
         this.action.requirements = req
         return this
     }
 
+    /**
+     * Sets the requirements for the return value. 
+     * This method does not guarantee that this action will return this particular data type. 
+     * In fact, the return value is not validated.
+     * It may help to read the documentation for the device
+     * 
+     * @example
+     * 
+     * ```ts
+     * Action.global().returns({
+     *       id: Rule.number().require().default(0).description('Unique ID'),
+     * })
+     * ```
+     * 
+     * @param ret Object of BasicType rules
+    */
     returns (ret: { [key: string]: BasicType; }){
         this.action.returns = ret
         return this
     }
 
+    /**
+     * Set description of Action
+     * 
+     * @example 
+     * ```ts
+     * Action.global().description('Short action description')
+     * ```
+    */
     description(des: string){
         this.action.description = des
         return this
     }
 
+    /**
+     * Returns the internal Action object. 
+     * This method is used inside VRack2 when processing an Action inside Container
+     * 
+     * **Do not use this method if it is not necessary**
+    */
+    exportRaw(){
+        return this.action
+    }
+
+    /**
+     * Forms a new IAction object
+     * This method is used inside VRack2 when processing an Action inside Container
+     * 
+     * **Do not use this method if it is not necessary**
+     * 
+     * !hide for external users
+     * @private
+    */
     export(): IAction{
         const nAction: IAction = {
             type: this.action.type,

package/src/actions/GlobalAction.ts

@@ -5,6 +5,11 @@
 
 import BasicAction from "./BasicAction";
 
+/**
+ * Standart action class
+ * 
+ * @see BasicAction
+*/
 export default class GlobalAction extends BasicAction {
 
     constructor() {

package/src/actions/IAction.ts

@@ -1,8 +1,15 @@
 import IValidationRule from "../validator/IValidationRule";
 
+/**
+ * Internal (exported) Action interface
+*/
 export default interface IAction {
+    /** Type of action ('global' as default) */
     type: string;
+    /** Requirements for incoming data */
     requirements: { [key: string]: IValidationRule; };
+    /** Requirements to returned data  */
     returns: { [key: string]: IValidationRule; };
+    /** A short text description of the action */
     description: string;
 }

package/src/actions/ILocalAction.ts

@@ -1,8 +1,15 @@
 import BasicType from "../validator/types/BasicType";
 
+/**
+ * Internal (raw exported) Action interface
+*/
 export default interface ILocalAction {
+    /** Type of action ('global' as default) */
     type: string;
+    /** Requirements for incoming data */
     requirements: { [key: string]: BasicType; };
+    /** Requirements to returned data  */
     returns: { [key: string]: BasicType; };
+    /** A short text description of the action */
     description: string;
 }

package/src/boot/BootClass.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright © 2024 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import Container from '../Container';
+import BasicType from '../validator/types/BasicType';
+import Validator from '../validator/Validator';
+
+/**
+ * Boot classes are designed to override behavior outside of the container. 
+ * They can also extend the container's capabilities. 
+ * 
+ * Boot classes are similar to devices inside the container, 
+ * but they do not fall into it and do not have connections.
+ * 
+ * Boot classes are created inside a Bootstrap class. 
+ * To do this, you need to create a list of classes and specify them for bootstrapping,
+ * 
+ * here is an example of such a list
+ * 
+ * ```ts
+ *      DeviceManager: { path: 'vrack2-core.DeviceManager', options: { storageDir: './storage' }},
+ *      DeviceStorage: { path: 'vrack2-core.DeviceFileStorage', options: {} },
+ *      StructureStorage: { path: 'vrack2-core.StructureStorage', options: {} },
+ *      DeviceMetrics: { path: 'vrack2-core.DeviceMetrics', options: {} }
+ * ```
+ * Where:
+ * ```
+ *   [key: string - Unique bootclass identifier] : {
+ *      path: string - Path to bootclass,
+ *      options: {any} - Bootclass settings
+ *   }
+ * ```
+ * 
+ * @see DeviceManager For boot class example
+*/
+export default class BootClass {
+
+    /** 
+     * A unique identifier that will be filled in when the class is created within Bootstrap. 
+     * Can be used to refer to the class directly
+     * 
+     * @example 'DeviceName'
+     * */
+    id: string;
+
+    /**
+     * The path to a VRack2-style class that will be populated when the class is created inside Bootstrap. 
+     * Can be used to determine class membership
+     * 
+     * @example 'vrack.KeyManager'
+    */
+    type: string;
+
+    /** 
+     * Container for which Boot classes are loaded
+     * */
+    Container: Container;
+
+    /**
+     * Boot class parameters that will be passed from the settings of the list of boot classes
+     * 
+     * @see checkOptions()
+    */
+    options: { [key: string]: any } = {};
+
+    /**
+     * Method returns rules for validation of boot class options
+     * 
+     * @example 
+     * ```ts
+     *   return {
+     *       keysPath: Rule.string().require().default('./keys.json')
+     *   }
+     * ```
+    */
+    checkOptions(): { [key: string]: BasicType; } {
+        return {}
+    }
+
+    /**
+     * @param id Unique ID
+     * @param type Device type string 
+     * @param Container Active loader container
+    */
+    constructor(id: string, type: string, Container: Container, options: { [key: string]: any } ) {
+        this.id = id
+        this.type = type
+        this.Container = Container
+        this.options = options
+        
+        // Validating
+        const rules = this.checkOptions()
+        Validator.validate(rules, this.options)
+    }   
+
+
+    /**
+     * The method is the entry point to start the boot class
+    */
+    process() { return }
+
+    /**
+     * Similar to `process` but asynchronous, 
+     * the bootstrap loader will wait for the execution of all 
+     * the  `processPromise` methods of all bootstrap classes.
+    */
+    async processPromise() { return }
+
+    /**
+     * Method for calling container system errors
+     */
+    error(error: Error){
+        this.Container.emit('system.error', error)
+    }
+}

package/src/boot/DeviceFileStorage.ts

@@ -0,0 +1,96 @@
+/*
+ * Copyright © 2024 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import path from "path"
+import fs from 'fs';
+import ImportManager from "../ImportManager";
+import BootClass from "./BootClass";
+import BasicType from "../validator/types/BasicType";
+import Rule from "../validator/Rule";
+
+/**
+ * File storage for devices that are used by default
+ * Uses container events to load and save storage state
+ * 
+*/
+export default class DeviceFileStorage extends BootClass {
+
+    checkOptions(): { [key: string]: BasicType; } {
+        return {
+            storageDir: Rule.string().require().default('./storage')
+                .description('Dir for storage files')
+        }
+    }
+
+    process(): void {
+        if (!ImportManager.isDir(this.options.storageDir)) fs.mkdirSync(this.options.storageDir, { recursive: true })
+        
+        // Before process load storage data
+        this.Container.on('beforeProcess', () => {
+            for (const id in this.Container.devices) {
+                try {
+                    this.Container.devices[id].storage = this.loadDeviceStorage(id)
+                } catch (error) {
+                    this.Container.emit('system.error', error)
+                }
+            }
+        })
+
+        // On device save - save storage data
+        this.Container.on('device.save', (data: { device: string, data: string, trace: any }) => {
+            try {
+                this.saveDeviceStorage(data.device, data.trace)
+            } catch (error) {
+                this.Container.emit('system.error', error)
+            }
+        })
+    }
+
+    /**
+     * loading a device storage file
+     * If the primary storage file does not exist, an attempt will be made 
+     * to locate the backup temporary storage file.
+     * 
+     * @param deviceId Device ID
+     * @returns {any} Imported JSON
+    */
+    async loadDeviceStorage(deviceId: string) {
+        const fp = this.makeDeviceStoragePath(deviceId)
+        const fptmp = this.makeDeviceStoragePath(deviceId, '-tmp')
+        if (!fs.existsSync(fp)) {
+            if (!fs.existsSync(fptmp)) return {}
+            fs.renameSync(fptmp, fp)
+        }
+        return ImportManager.importJSON(fp)
+    }
+
+    /**
+     * Save data device to storage
+     * First, a temporary file is created, 
+     * and then the temporary file is copied to the main file
+     * 
+     * @param deviceId Device ID
+     * @param trace Data object for storage
+    */
+    async saveDeviceStorage(deviceId: string, trace: any) {
+        const fp = this.makeDeviceStoragePath(deviceId)
+        const dp = path.join(this.options.storageDir, this.Container.id)
+        const fptmp = this.makeDeviceStoragePath(deviceId, '-tmp')
+        if (!fs.existsSync(dp)) { fs.mkdirSync(dp, { recursive: true }) }
+        fs.writeFileSync(fptmp, JSON.stringify(trace))
+        if (fs.existsSync(fp)) fs.rmSync(fp)
+        fs.renameSync(fptmp, fp)
+    }
+
+    /**
+     * Forms the path to the storage file
+     * 
+     * @param deviceId Device ID
+     * @param prefix Prefix between the device name and its extension 
+    */
+    protected makeDeviceStoragePath(deviceId: string, prefix = '') {
+        return path.join(this.options.storageDir, this.Container.id, deviceId + prefix + '.json')
+    }
+}