vrack2-core 0.0.1 → 1.0.0

package/src/errors/CoreError.ts

@@ -1,34 +1,37 @@
 /*
- * Copyright © 2022 Boris Bobylev. All rights reserved.
+ * Copyright © 2024 Boris Bobylev. All rights reserved.
  * Licensed under the Apache License, Version 2.0
 */
 
 /**
- * Базовый класс для реализаиции ошибок с возможностью
- * импортирования и экспортирования классов ошибок для 
- * клиент-серверных операций.
+ * Base class for error realization with the ability to 
+ * import and export error classes for client-server operations.
  * 
- * В VRack очень много передается по сети в виде JSON.  Поскольку 
- * в чистом виде ошибки не преобрзауются в JSON, были сделаны методы
- * для экспортирования и импортирования с сохранения основных важных свойств.
+ * In VRack, a lot of things are transmitted over the network as JSON.  
+ * Since pure errors are not converted to JSON, methods were made to export and 
+ * import them while preserving the main important properties.
  * 
- * Если импортируемая ошибка имеет свойства которых нет в базовом классе, буду добавлены.
- * Для получения неизвестных свойств можно воспользоватся функцией (для typescript) getUnknownProperty
- * 
- * Для работы с ошибками VRack рекомендуется использовать ErrorManager
+ * If the imported error has properties that are not in the base class,
+ * they will be added. To get unknown properties you can use the function 
+ * (for typescript) getUnknownProperty.
  * 
 */
 class CoreError extends Error{
-    /** Флаг того что ошибка пренадлежит VRack */
+
+    /** Flag that the error belongs to VRack */
     vError = true
-    /** Код ошибки VRack */
+
+    /** Error code */
     vCode = ""
-    /** Кородкий код VRack */
+
+    /** Short code */
     vShort = ""
-    /** Список дополнительных параметров */
+
+    /** List of additional parameters */
     vAdd: Array<string> = []
-    /**  */
-    vAddErrors: Array<CoreError> = []
+
+    /** Nested errors */
+    vAddErrors: Array<Error> = []
 
     constructor(name: string, message: string, code: string, short: string) {
         super(message)
@@ -38,8 +41,24 @@ class CoreError extends Error{
     }
     
     /**
-     * Импортирует ошибку пришедшую по сети в виде JSON объекта
-     * На всякий случай использует objectify для приходящего объекта
+     * Sets the stacktrace of the error above
+     * It is necessary for the stacktrace to refer to the 
+     * required file and not to ErrorManager
+     * 
+     * @param err Error 
+     * @example Example of assigning a more correct path to the file where the error occurred
+     * ```
+     *     ErrorManager.make('EM_CODE_NOT_FOUND').setTrace(new Error())
+     * ```
+    */
+    setTrace (err: Error){
+        this.stack = err.stack
+        return this
+    }
+
+    /**
+     * Imports an error that came over the network as a JSON object
+     * Uses objectify for the incoming object just in case
      * 
      * @returns {CoreError} this после модификации
     */
@@ -50,22 +69,29 @@ class CoreError extends Error{
     }
 
     /**
-     * Возвращает объект для передачи его по сети с предварительным 
-     * преобразованием в JSON
+     * Returns an object to be transmitted over the network 
+     * with preliminary conversion to JSON
+     * 
+     * @see objectify
     */
     export() : any {
         return CoreError.objectify(this)
     }
 
 
-    add(err: CoreError) {
+    /**
+     * Add nested error
+     * 
+     * @param err Nested error
+    */
+    add(err: Error) {
         this.vAddErrors.push(CoreError.objectify(err))
         return this
     }
 
     /**
-     * Для Typescript используется для получения неизвестного
-     * свойства экземпляра после импорта пришедшей ошибки
+     * For Typescript it is used to retrieve an unknown
+     * instance property after importing an incoming error
     */
     getUnknownProperty(field:string): any | undefined {
         const dynamicKey = field as keyof CoreError;
@@ -73,9 +99,9 @@ class CoreError extends Error{
     }
 
     /**
-     *  Возвращает объект для передачи его по сети
+     *  Returns an object to be transmitted over the network
      * 
-     * @param {any} error Ошибка для преобразования в объект
+     * @param {any} error Error for conversion to an object
      * */
     static objectify(error: any) : any {
         const result: any = {}

package/src/errors/ErrorManager.ts

@@ -6,65 +6,80 @@
 import BasicType from "../validator/types/BasicType"
 import CoreError from "./CoreError"
 
+
 interface RegisteredError {
+    /** Property for error grouping */
     name: string,
+    /** Unique random string code ID  like a random string  */
     code: string,
+    /** Readable unique identifier like a VS_ERROR_DATABASE_NF  */
     short: string,
+    /** Error string (description) */
     description: string,
-    rules: {[key:string]: BasicType}
+    /** 
+     * You can specify additional data when creating an error.
+     * If these data are standardized - you can specify rules for them.
+     * These rules do not validate the additional data. 
+     * But they can make it easier to understand these properties. 
+     * */
+    rules: { [key: string]: BasicType }
 }
 
 
 /**
- * Класс является точкой входа для инициализации исключений
- * 
- * Было принято решение вместо кучи мелких однотипных файлов сделать один класс
- * со стандартным функционалом
+ * A simple class for creating errors.
+ * This centralized class is useful because you can find out t
+ * he list of all registered errors and which group/component they belong to.
  */
 class ErrorManager {
 
+    /**
+     * List of registered errors
+    */
     private registeredList: Array<RegisteredError> = []
 
     /**
-     * Регистрирует тип ошибки компонента
-     * 
-     * Перед тем как менеджер ошибок может создать ошибки, необходимо зарегистрировать ее тип.
-     * 
-     * @param {string} name Название компонента
-     * @param {string} code Код ошибки
-     * @param {string} short Короткий код ошибки 
-     * @param {string} description Описание ошибки
+     * Error registration. An error must be registered before creating it 
      * 
+     * @param name Property for error grouping
+     * @param code Unique random string code ID
+     * @param short Readable unique identifier 
+     * @param description Error string (description)
     */
-    register(name: string, code: string, short: string, description: string, rules: {[key:string]: BasicType} = {}) {
+    register(name: string, code: string, short: string, description: string, rules: { [key: string]: BasicType } = {}) {
         const reg1 = this.getRegistered(code)
         const reg2 = this.getRegistered(short)
-        if (reg1 !== null || reg2 !== null) throw this.make('EM_CODE_EXISTS', {code, short})
-        const nr = { name, code, short, description, rules}
+        if (reg1 !== null || reg2 !== null) throw this.make('EM_CODE_EXISTS', { code, short })
+        const nr = { name, code, short, description, rules }
         this.registeredList.push(nr)
     }
 
     /**
-     * Создание ошибки
+     * Creating an instance of an error
      * 
-     * 
-     * 
-     * @param {string} short 
+     * @param short 
+     * @param additional 
     */
     make(short: string, additional = {}) {
         const reg = this.getRegistered(short)
         if (reg === null) throw this.make('EM_CODE_NOT_FOUND')
-        const ne = new CoreError(reg.name, reg.description,reg.code, reg.short)
+        const ne = new CoreError(reg.name, reg.description, reg.code, reg.short)
+
+        // Убираем из стека вызовы ErrorManager.make()
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(ne, this.make);
+        }
+        
         ne.vAdd = Object.keys(additional)
         return Object.assign(ne, additional)
     }
 
     /**
-     * Преобразует обычную ошибку в ошибку VRack
+     * Converts a normal error to a VRack error
      * 
-     * @param {Error} error Ошибка для преобразования
+     * @param error Ошибка для преобразования
     */
-    convert(error: any){
+    convert(error: any) {
         if (error.vError) return error
         const ne = this.make('EM_ERROR_CONVERT')
         ne.import(error)
@@ -72,14 +87,12 @@ class ErrorManager {
     }
 
     /**
-     * Возвращает тип ошибки или null
+     * Searches for an error by code or short
      * 
-     * @param {string} short Короткий код ошибки или код ошибки поиска
+     * @param short Short error code or search error code
     */
-    private getRegistered(short: string) : RegisteredError | null {
-        for (const registered of this.registeredList){
-            if (registered.code === short || registered.short === short) return registered
-        }
+    private getRegistered(short: string): RegisteredError | null {
+        for (const registered of this.registeredList) if (registered.code === short || registered.short === short) return registered
         return null
     }
 }
@@ -87,7 +100,7 @@ class ErrorManager {
 
 
 const GlobalErrorManager = new ErrorManager()
-GlobalErrorManager.register('ErrorManager','NcZIb9QvQRcq', 'EM_CODE_EXISTS', 'This code already exists')
-GlobalErrorManager.register('ErrorManager','uLYv4mE1Yo50', 'EM_CODE_NOT_FOUND', 'No such error found')
-GlobalErrorManager.register('ErrorManager','RIl3BUrxWOzP', 'EM_ERROR_CONVERT', 'Converted error')
+GlobalErrorManager.register('ErrorManager', 'NcZIb9QvQRcq', 'EM_CODE_EXISTS', 'This code already exists')
+GlobalErrorManager.register('ErrorManager', 'uLYv4mE1Yo50', 'EM_CODE_NOT_FOUND', 'No such error found')
+GlobalErrorManager.register('ErrorManager', 'RIl3BUrxWOzP', 'EM_ERROR_CONVERT', 'Converted error')
 export default GlobalErrorManager

package/src/index.ts

@@ -1,29 +1,53 @@
 /*
- * Copyright © 2022 Boris Bobylev. All rights reserved.
+ * Copyright © 2024 Boris Bobylev. All rights reserved.
  * Licensed under the Apache License, Version 2.0
 */
 
-
 /* ---------------- VALIDATOR EXPORT ------------------- */
 export { default as ErrorManager } from './errors/ErrorManager'
 export { default as CoreError } from './errors/CoreError'
 export { default as Rule } from './validator/Rule'
 export { default as Validator } from './validator/Validator'
-export { default as IValidationProblem} from './validator/IValidationProblem'
-export { default as IValidationRule} from './validator/IValidationRule'
-export { default as IValidationSubrule} from './validator/IValidationSubrule'
 
 /* ---------------- BASE OF VRACK ------------------- */
 export { default as ImportManager } from './ImportManager';
-export { default as DeviceManager } from './DeviceManager';
 export { default as Container } from './Container';
 export { default as MainProcess } from './MainProcess';
 
+/* ---------------- BOOTSTRAP ------------------- */
+
+export { default as Bootstrap } from './Bootstrap'
+export { default as BootClass } from './boot/BootClass'
+export { default as DeviceFileStorage } from './boot/DeviceFileStorage'
+export { default as DeviceManager } from './boot/DeviceManager';
+export { default as StructureStorage } from './boot/StructureStorage';
+export { default as DeviceMetrics } from './boot/DeviceMetrics';
+
+/* ---------------- INTERNAL SERVICE ------------------- */
+
 export { default as Action } from './actions/Action'
 export { default as Device } from './service/Device'
 export { default as DeviceConnect } from './service/DeviceConnect'
 export { default as DevicePort } from './service/DevicePort'
 export { default as Port } from './ports/Port'
+export { default as Metric } from './metrics/Metric'
+
+export { default as BasicPort } from './ports/BasicPort'
+export { default as BasicType } from './validator/types/BasicType'
+export { default as BasicMetric } from './metrics/BasicMetric'
+export { default as BasicAction } from './actions/BasicAction'
+
+/* ---------------- INTERFACES ------------------- */
+export { default as IMetricSettings } from './metrics/IMetricSettings'
+export { default as IPort } from './ports/IPort'
+export { default as IDeviceEvent } from './service/IDeviceEvent'
+export { default as IValidationProblem} from './validator/IValidationProblem'
+export { default as IValidationRule} from './validator/IValidationRule'
+export { default as IValidationSubrule} from './validator/IValidationSubrule'
+export { default as IServiceStructure} from './IServiceStructure'
+export { default as IStructureDevice} from './IStructureDevice'
+
+export { StorageTypes } from 'vrack-db';
 
 export * from './service/Device'
 export * from './service/DeviceConnect'

package/src/metrics/BasicMetric.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+
+import { StorageTypes, SingleDB } from "vrack-db"
+import  IMetricSettings  from "./IMetricSettings"
+
+/**
+ * Metric base class. Used internally to define device metrics.
+*/
+export default class BasicMetric {
+    /**
+     * Default metric setting
+    */
+    protected metric: IMetricSettings  = {
+        retentions: '5s:10m, 1m:2h, 15m:1d, 1h:1w, 6h:1mon, 1d:1y',
+        interval: 's',
+        vType: StorageTypes.Float,
+        tType: StorageTypes.Uint64
+    }
+
+    /**
+     * Defines the type of time storage
+     * 
+     * @param type StorageTypes type like a StorageTypes.Uint64 (default)
+    */
+    timeStorage(type: StorageTypes){
+        this.metric.tType = type
+        return this
+    }
+
+    /**
+     *  Defines the type of value storage
+     * 
+     * @param type StorageTypes type like a StorageTypes.Uint64 (default)
+    */
+    valueStorage(type: StorageTypes){
+        this.metric.vType = type
+        return this
+    }
+
+    /**
+     * Specifies the accuracy and storage period size of Graphite-style metrics
+     * 
+     * 
+     * @see SingleDB.metric
+     * @param req retentions Graphite-style `5s:10m, 1m:2h, 15m:1d, 1h:1w, 6h:1mon, 1d:1y`
+    */
+    retentions(req: string){
+        this.metric.retentions = req
+        return this
+    }
+
+    /**
+     * Metric Description
+     * 
+     * @param des Short text description of the metric
+    */
+    description(des: string){
+        this.metric.description = des
+        return this
+    }
+
+    /**
+     * To add additional data to the metric, you can specify
+     * any object describing the metric in this method.
+     * 
+     * @param add Additional information for the metric
+    */
+    additional(add: any){
+        this.metric.additional = add
+        return this
+    }
+
+    /**
+     * Returns the internal metric settings object. Used inside Container
+     * @private
+    */
+    export(){
+      return this.metric
+    }
+}

package/src/metrics/IMetricSettings.ts

@@ -0,0 +1,38 @@
+import { StorageTypes } from "vrack-db";
+
+
+export default interface IMetricSettings {
+    /**
+     *  Specifies the accuracy and storage period size of Graphite-style metrics
+     *  @see SingleDB.metric
+    */
+    retentions: string;
+    /**
+     * Interval that defines the minimal time unit
+     * 
+     * s - second
+     * ms - millisecond
+     * us - microsecond
+    */
+    interval: 's' | 'ms' | 'us';
+
+    /**
+     * Defines the type of value storage
+     * StorageTypes type like a StorageTypes.Uint64 (default)
+    */
+    vType: StorageTypes;
+
+    /**
+     * Defines the type of time storage
+     * StorageTypes type like a StorageTypes.Uint64 (default)
+    */
+    tType: StorageTypes;
+
+    /** Metric Description */
+    description?: string;
+
+    /**
+     * Additional information for the metric
+    */
+    additional?: any;
+}

package/src/metrics/IvMs.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import BasicMetric from "./BasicMetric";
+
+/**
+ * Creating a new metric with minimum time unit in milliseconds
+ * 
+ * @see BasicMetric
+*/
+export default class IvMS extends BasicMetric {
+    constructor (){
+        super()
+        this.metric.interval = 'ms'
+    }
+}

package/src/metrics/IvS.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import BasicInterval from "./BasicMetric";
+
+/**
+ * Creating a new metric with minimum time unit in Seconds
+ * 
+ * @see BasicMetric
+*/
+export default class IvS extends BasicInterval {
+    constructor (){
+        super()
+        this.metric.interval = 's'
+    }
+}

package/src/metrics/IvUs.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import BasicInterval from "./BasicMetric";
+/**
+ * Creating a new metric with minimum time unit in Microseconds
+ * 
+ * @see BasicMetric
+*/
+export default class IvUs extends BasicInterval {
+    constructor (){
+        super()
+        this.metric.interval = 'us'
+    }
+}

package/src/metrics/Metric.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright © 2025 Boris Bobylev. All rights reserved.
+ * Licensed under the Apache License, Version 2.0
+*/
+
+import IvMS from "./IvMs";
+import IvS from "./IvS";
+import IvUs from "./IvUs";
+
+export default class Metric {
+    /**
+     * Creating a new metric with minimum time unit in Seconds
+    */
+    static inS(){ return new IvS() }
+    
+    /**
+     * Creating a new metric with minimum time unit in Milliseconds
+    */
+    static inMs(){ return new IvMS() }
+
+    /**
+     * Creating a new metric with minimum time unit in Microsecond
+    */
+    static inUs(){ return new IvUs() }
+}

package/src/ports/BasicPort.ts

@@ -7,6 +7,9 @@ import BasicType from "../validator/types/BasicType";
 import ILocalPort from "./ILocalPort";
 import IPort from "./IPort";
 
+/**
+ * Port basic class.  Used internally to define device ports.
+*/
 export default class BasicPort {
     protected port: ILocalPort
 
@@ -20,22 +23,58 @@ export default class BasicPort {
         }
     }
 
+    /**
+     * Sets this port to dynamic
+     * 
+     * If you specify a port to be dynamic, you must specify the number of those ports.
+     * Also if you specify a port as dynamic, you must specify `%d` in the name, 
+     * which will be replaced by the port number.
+     * 
+     * @example 
+     * ```ts
+     * {
+     *   'command%d': Port.return().dynamic(this.options.inputs)
+     * }
+     * ```
+     * 
+     * @param count Count of ports 
+    */
     dynamic(count: number){
         this.port.count = count
         this.port.dynamic = true
         return this
     }
 
+    /**
+     * Specifies a recommendation to the data passing through the port. 
+     * This data is not actually validated by these rules, 
+     * but these rules can be used in the documentation to clarify perception.
+     * 
+     * @param req BasicType type 
+    */
     requirement(req:  BasicType ){
         this.port.requirement = req
         return this
     }
 
+    /**
+     * Port descriptions
+    */
     description(des: string){
         this.port.description = des
         return this
     }
 
+    /**
+     * Exports the port data. 
+     * Collects all data into an IPort object. 
+     * Internal types of type BasicType are also exported to the corresponding properties 
+     * 
+     * @see IPort
+     * 
+     * !hide for external users
+     * @private
+    */
     export(): IPort{
         const nPort: IPort = {
             type: this.port.type,

package/src/ports/ILocalPort.ts

@@ -2,11 +2,18 @@ import BasicType from "../validator/types/BasicType";
 
 
 export default interface ILocalPort {
+    /** Port Type - Returned or Standard */
     type: string;
+    /** Specifies a recommendation to the data passing through the port.  */
     requirement?: BasicType;
+    /** Specifies a recommendation for the data returned by the port */
     return?: BasicType;
+    /** Port description */
     description: string;
+    /** Is the connection of this port mandatory */
     required: boolean;
+    /** Whether the port is dynamic */
     dynamic: boolean;
+    /** Count of dynamic ports */
     count: number;
 }

package/src/ports/IPort.ts

@@ -2,11 +2,18 @@ import IValidationRule from "../validator/IValidationRule";
 
 
 export default interface IPort {
+    /** Port Type - Returned or Standard */
     type: string;
+    /** Specifies a recommendation to the data passing through the port.  */
     requirement?: IValidationRule;
+    /** Specifies a recommendation for the data returned by the port */
     return?: IValidationRule;
+    /** Port description */
     description: string;
+    /** Is the connection of this port mandatory */
     required: boolean;
+    /** Whether the port is dynamic */
     dynamic: boolean;
+    /** Count of dynamic ports */
     count: number;
 }

package/src/ports/Port.ts

@@ -5,12 +5,22 @@
 
 import ReturnPort from "./ReturnPort";
 import StandartPort from "./StandartPort";
-
+/**
+ * Creating a new port. Used internally to create a port
+*/
 export default class Port {
+    
+    /**
+     * Standard Port. 
+     * Used to cast a value to another port or to signal a value to another port
+    */
     static standart() {
         return new StandartPort()
     }
 
+    /**
+     * Return Port. Used to get the value over connections
+    */
     static return() {
         return new ReturnPort()
     }

package/src/ports/ReturnPort.ts

@@ -12,6 +12,11 @@ export default class ReturnPort extends BasicPort {
         this.port.type = 'return'
     }
 
+    /**
+     * Specifies a recommendation to the data return from the port.
+     * 
+     * @param req BasicType type 
+    */
     return(req:  BasicType ){
         this.port.return = req
         return this