vrack2-core 0.0.1 → 1.0.0

package/lib/service/Device.js

@@ -12,20 +12,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EDeviceMessageTypes = void 0;
-/**
- * Интерфейс списка исходящих портов устройства
-// */
-// export interface IDeviceOutputList {
-//     [index: string]: OutputPort;
-// }
-// /**
-//  * Интерфейс списка входящих портов устройства
-// */
-// export interface IDeviceInputList {
-//     [index: string]: InputPort;
-// }
+const CoreError_1 = __importDefault(require("../errors/CoreError"));
+const ImportManager_1 = __importDefault(require("../ImportManager"));
 var EDeviceMessageTypes;
 (function (EDeviceMessageTypes) {
     EDeviceMessageTypes["terminal"] = "terminal";
@@ -36,18 +29,30 @@ var EDeviceMessageTypes;
     EDeviceMessageTypes["alert"] = "alert";
 })(EDeviceMessageTypes = exports.EDeviceMessageTypes || (exports.EDeviceMessageTypes = {}));
 class Device {
+    /**
+     * @param id Unique ID
+     * @param type Device type string
+     * @param Container Active loader container
+    */
     constructor(id, type, Container) {
-        /** Входящие (назначаемые сверху) параметры устройства */
+        /**
+         * Device options
+         *
+         * @see checkOptions()
+        */
         this.options = {};
         /**
-         * Shares данные устройства (обновляемые данные)
-         * используется с методом `this.render`
+         * This is a fast updating data object - it will be sent
+         * to subscribers after the render() call
          *
          * @see render()
          * */
         this.shares = {};
         /**
+         * This data will be loaded for the specific instance of the device.
+         * The device itself determines this data and saves it at the right moment
          *
+         * The structure is determined by the device
         */
         this.storage = {};
         this.id = id;
@@ -59,133 +64,230 @@ class Device {
         };
     }
     /**
-     * Short device description
+     * Device settings
+     *
+     * Needs to be finalized"
+    */
+    settings() {
+        return {
+            channels: ['terminal', 'notify', 'event', 'action', 'alert', 'error', 'render']
+        };
+    }
+    /**
+     * Short device description. Can use markdown markup
      *
      * @return {string} Device description
      * */
     description() {
         return '';
     }
-    /** Список Action-методов устройства */
-    actions() { return {}; }
     /**
-     * Определение списка параметров устройства
+     * Device action list
+     * Device actions can be called from the container.
+     * This is a way to interact with the device from the outside world
      *
-     * @returns {Array<Rule>}
+     * @example
+     * ```
+     *  return {
+     *      'test.action': Action.global().requirements({
+     *          id: Rule.string().require().default('www').description('Some id')
+     *      }).description('Test action')
+     *  }
+     * ```
+     *
+     * A handler must be created for each action. For example, for `test.action` action `actionTestAction` must be created.
      * */
-    checkOptions() { return {}; }
+    actions() { return {}; }
+    /**
+     * Defining device metrics.
+     *
+     * @example
+     *
+     * ```
+     * return {
+     *  'test.metric': Metric.inS().retentions('1s:6h').description('Test metric')
+     * }
+     * ```
+     * @see BasicMetric
+    */
+    metrics() { return {}; }
+    /**
+     * Run before each device action
+     *
+     * @param action "device.action" like string
+     * @param data  data for action
+    */
+    beforeAction(action, data) { return true; }
     /**
      * Prepare options
      *
      * this method call before validating options
     */
     prepareOptions() { return; }
+    /**
+     * Defining a list of device parameters
+     *
+     * @example
+     * ```ts
+     * return {
+     *      timeout: Rule.number().integer().min(0).description('Interval timeout').example(0)
+     * }
+     * ```
+     *
+     * @returns {Array<Rule>}
+     * */
+    checkOptions() { return {}; }
+    /**
+     * Device inputs list
+     *
+     * Use like this object:
+     * {
+     *    'group.portname': Port.standart(),
+     *    'group.portname': Port.standart()
+     * }
+     *
+    */
     inputs() { return {}; }
+    /**
+     * Device output list
+     *
+     * @see inputs
+    */
     outputs() { return {}; }
     /**
-     * Метод является входной точкой для начала инициализации устройства
+     * The method is an input point to start device initialization
      *
-     * Устройство пройдет только следующие этапы создания устройства:
+     * The device will only go through the following device creation steps:
      *
-     * - Создания класса
-     * - Назначение праметров устройства
+     * - Creating a class
+     * - Assigning device prameters
      *
-     * Необходимо использовать для назначения функций вызова динамических портов
-     * устройства.
+     * Must be used to assign functions to call dynamic ports
+     * of the device.
     */
     preProcess() { return; }
     /**
-     * Метод является входной точкой для начала работы устройства
+     * The method is an input point for the start of device operation
      *
-     * Устройство пройдет следующие этапы создания устройства:
+     * The device will go through the following steps to create the device:
      *
-     * - Создания класса
-     * - Назначение праметров устройства
-     * - Создание портов
-     * - Назначение функций вызова
-     * - Создание соединений между устройствами
-     * - Линковка Shares устройства
+     * - Creating a class
+     * - Assigning device prameters
+     * - Creating ports
+     * - Assigning call functions
+     * - Creating connections between devices
+     * - Linking device Shares
      *
-     * Необходимо использовать для осуществления начала основной работы устройства
-     * например, инициализация подключений, создание таймеров и тп.
+     * Must be used to start basic operation of the device
+     * e.g. initialization of connections, creation of timers, etc.
     */
     process() { return; }
     /**
-     * По аналогии с `process` но асинхронный, загрузчик будет ждать выполнения всех
-     * методов `processPromise` всех устройств.
+     * Similar to `process` but asynchronous, the loader will wait for the execution of all the
+     * `processPromise` methods of all devices.
      *
-     * Используется, когда есть необходимость перед запуском стойки выполнить
-     * и дождаться выполнения асинхронного кода (инициализация некоторых файловых баз данных и тп)
+     * Used when there is a need to execute before starting the rack
+     * and wait for asynchronous code to execute (initialization of some file databases, etc.)
     */
     processPromise() {
         return __awaiter(this, void 0, void 0, function* () { return; });
     }
-    stop() { return; }
-    stopPromise() {
-        return __awaiter(this, void 0, void 0, function* () { return; });
-    }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к постановке в очередь устройства на обновление данных `Shares`
+     * Myby todo?
+     *
+     * stop() { return }
+     * async stopPromise() { return }
     */
-    render() { return this.event('device.render', 'shares', this.shares); }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к сохранение в локальное файловое хранилище данных `Storage`
+     * Queues device shares data updates for external consumers
+     *
+     * @see shares
     */
-    save() { return this.event('device.save', 'storage', this.storage); }
+    render() { return this.makeEvent('device.render', 'shares', this.shares, []); }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке сообщению об ошибке
+     * Save device storage
      *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Непосредственно объект ошибки, или объект который поможет разобратся в случившейся ситуации
+     * @see storage
     */
-    error(data, trace) { return this.event('device.error', data, trace); }
+    save() { return this.makeEvent('device.save', 'storage', this.storage, []); }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке информационного сообщения
+     * Write metric value
      *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param path Registered metric path
+     * @param value value record
+     * @param modify Write modify 'last' | 'first' | 'max' | 'min' | 'avg' | 'sum'
     */
-    notify(data, trace) { return this.event('device.notify', data, trace); }
+    metric(path, value, modify = 'last') {
+        return this.makeEvent('device.metric', path, { value, modify }, []);
+    }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке оповещения
-     *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param data Message
+     * @param trace Trace info (object needed)
     */
-    alert(data, trace) { return this.event('device.alert', data, trace); }
+    terminal(data, trace, ...args) { return this.makeEvent('device.terminal', data, trace, args); }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке отладочной информации
-     *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param data Message
+     * @param trace Trace info (object needed)
     */
-    terminal(data, trace) { return this.event('device.terminal', data, trace); }
+    notify(data, trace, ...args) { return this.makeEvent('device.notify', data, trace, args); }
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке сообщения о событии
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    event(data, trace, ...args) { return this.makeEvent('device.event', data, trace, args); }
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    alert(data, trace, ...args) { return this.makeEvent('device.alert', data, trace, args); }
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    error(data, trace, ...args) {
+        if (trace instanceof Error)
+            trace = CoreError_1.default.objectify(trace);
+        return this.makeEvent('device.error', data, trace, args);
+    }
+    /**
+     * Make & emit device event
      *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param type event type
+     * @param data event data string
+     * @param trace additional information
     */
-    event(type, data, trace) {
-        const nEvent = { id: this.id, data, trace };
+    makeEvent(type, data, trace, args) {
+        const nEvent = { device: this.id, data, trace };
         return this.Container.emit(type, nEvent);
     }
     /**
-     * Сообщает стойке, о том, что устройство не может дальше работать
-     * и произошла критическая ошибка
+     * Adding processing for the incoming port
      *
-     * Требует создание ошибки устройства DeviceError
+     * @param name Port name in 'port.name' format
+     * @param action CallBack function to execute
+    */
+    addInputHandler(name, action) {
+        name = ImportManager_1.default.camelize('input.' + name);
+        this[name] = action;
+    }
+    /**
+     * Adding a handle for the action
+     *
+     * @param name Action name in the format 'action.name'
+     * @param action CallBack function to execute
+    */
+    addActionHandler(name, action) {
+        name = ImportManager_1.default.camelize('action.' + name);
+        this[name] = action;
+    }
+    /**
+     * Informs the rack that the unit cannot continue to operate.
+     * and a critical error has occurred
      *
+     * Requires DeviceError to be created
     */
     terminate(error, action) {
-        return this.event('device.terminate', action, error);
+        return this.makeEvent('device.terminate', action, error, []);
     }
 }
 exports.default = Device;

package/lib/service/DeviceConnect.d.ts

@@ -1,21 +1,17 @@
 import DevicePort from "./DevicePort";
 /**
- * Класс для соедиения портов устройств
- *
+ * Class for connecting device ports
+ * Using inside Container class
 */
 export default class {
     outputLink: DevicePort;
     inputLink: DevicePort;
     /**
-     * Инициализация соединения, требует 2 порта которые привязаны
-     * к устройствам
-     *
     */
     constructor(output: DevicePort, input: DevicePort);
     /**
-     * Вызов входящего порта при вызове соединения
-     *
-     * @param {any} data Данные
+     * Handles communication between two device ports
+     * @param data Data sent by the device when the push port is invoked
     */
     push(data: any): any;
 }

package/lib/service/DeviceConnect.js

@@ -5,14 +5,11 @@
 */
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Класс для соедиения портов устройств
- *
+ * Class for connecting device ports
+ * Using inside Container class
 */
 class default_1 {
     /**
-     * Инициализация соединения, требует 2 порта которые привязаны
-     * к устройствам
-     *
     */
     constructor(output, input) {
         this.outputLink = output;
@@ -21,9 +18,8 @@ class default_1 {
         this.inputLink.addConnection(this);
     }
     /**
-     * Вызов входящего порта при вызове соединения
-     *
-     * @param {any} data Данные
+     * Handles communication between two device ports
+     * @param data Data sent by the device when the push port is invoked
     */
     push(data) {
         return this.inputLink.push(data);

package/lib/service/DevicePort.d.ts

@@ -1,24 +1,33 @@
 import IPort from "../ports/IPort";
 import DeviceConnect from "./DeviceConnect";
 /**
- * Класс для реализации порта устройства
- * Порт может быть как входящий так и исходящий
+ * A class to implement a device port.
+ * The port can be either incoming or outgoing
 */
 export default class DevicePort {
+    /** Flag to determine if the port is connected */
     connected: boolean;
+    /** Port connection list. One port can have multiple connections */
     connections: Array<DeviceConnect>;
+    /** Port ID */
     id: string;
+    /** Port type */
     type: string;
+    /** Flag determines whether the port should be connected */
     required: boolean;
+    /**
+     * Список слушателей порта
+     * Используется для захвата порта. Если какие либо данные будут проброшены
+     * в порт, они будут переданы для каждого вызнванного слушателя
+    */
+    listens: Map<number, (data: any) => void>;
     constructor(id: string, port: IPort);
     /**
-     * Добавление связи в порт
+     * Adding communication to a port
     */
     addConnection(connection: DeviceConnect): void;
     /**
-     * Вызов входящего порта при вызове соединения
-     *
-     * @param {any} data Данные
+     * Calling the incoming port when calling a connection
     */
     push(data: any): any;
 }

package/lib/service/DevicePort.js

@@ -3,39 +3,56 @@
  * Copyright © 2022 Boris Bobylev. All rights reserved.
  * Licensed under the Apache License, Version 2.0
 */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const Utility_1 = __importDefault(require("../Utility"));
 /**
- * Класс для реализации порта устройства
- * Порт может быть как входящий так и исходящий
+ * A class to implement a device port.
+ * The port can be either incoming or outgoing
 */
 class DevicePort {
     constructor(id, port) {
+        /** Flag to determine if the port is connected */
         this.connected = false;
+        /** Port connection list. One port can have multiple connections */
         this.connections = [];
+        /**
+         * Список слушателей порта
+         * Используется для захвата порта. Если какие либо данные будут проброшены
+         * в порт, они будут переданы для каждого вызнванного слушателя
+        */
+        this.listens = new Map();
         this.id = id;
         this.type = port.type;
         this.required = port.required;
     }
     /**
-     * Добавление связи в порт
+     * Adding communication to a port
     */
     addConnection(connection) {
         this.connected = true;
         this.connections.push(connection);
     }
     /**
-     * Вызов входящего порта при вызове соединения
-     *
-     * @param {any} data Данные
+     * Calling the incoming port when calling a connection
     */
     push(data) {
-        if (this.connected) {
-            if (this.connections.length === 1)
-                return this.connections[0].push(data);
-            for (const conn of this.connections) {
-                conn.push(data);
-            }
+        // Если у нас есть слушатели порта
+        // Передаем им данные и пересоздаем Map
+        if (this.listens.size) {
+            const res = Utility_1.default.prettyFormat(data);
+            for (const ls of this.listens.values())
+                ls(res);
+            this.listens = new Map();
         }
+        if (!this.connected)
+            return;
+        if (this.connections.length === 1)
+            return this.connections[0].push(data);
+        for (const conn of this.connections)
+            conn.push(data);
     }
 }
 exports.default = DevicePort;

package/lib/service/IDeviceEvent.d.ts

@@ -1,5 +1,8 @@
 export default interface IDeviceEvent {
-    id: string;
+    /** Device ID */
+    device: string;
+    /** event data string */
     data: string;
+    /** additional information */
     trace: any;
 }

package/lib/validator/IValidationProblem.d.ts

@@ -1,8 +1,15 @@
 import IValidationRule from "./IValidationRule";
 export default interface IValidationProblem {
+    /** VRack Error manager short code like a VS_ERROR_DATABASE_NF */
     type: string;
+    /** VRack Error manager error code like a random string */
     code: string;
+    /** Error string (description) */
     description: string;
+    /** Exported validation rule */
     rule: IValidationRule;
+    /** Additional arguments for error */
     arg: any;
+    /** key for getting value from object */
+    fieldKey: string;
 }

package/lib/validator/IValidationRule.d.ts

@@ -1,9 +1,21 @@
 import IValidationSubrule from "./IValidationSubrule";
 export default interface IValidationRule {
+    /** VRack Error manager short code like a VS_ERROR_DATABASE_NF */
     type: string;
+    /** VRack Error manager error code like a random string */
     require: boolean;
+    /** Error string (description) */
     default: any;
+    /** Exported validation rule */
     rules: Array<IValidationSubrule>;
+    /** Additional arguments for error */
     example: any;
+    /** key for getting value from object */
     description: string;
+    /**
+     * Template for error message string
+     * Use like a "{description} field must by like a '123' number "
+     * You can use {description} {value} {default} in template
+     */
+    message: string;
 }

package/lib/validator/IValidationSubrule.d.ts

@@ -1,4 +1,6 @@
 export default interface IValidationSubrule {
+    /** Name of subrule */
     name: string;
+    /** Subrule arguments */
     args: any;
 }

package/lib/validator/Rule.d.ts

@@ -1,12 +1,16 @@
+import AnyType from "./types/AnyType";
 import ArrayType from "./types/ArrayType";
+import BooleanType from "./types/BooleanType";
+import FunctionType from "./types/FunctionType";
 import NumberType from "./types/NumberType";
 import ObjectType from "./types/ObjectType";
 import StringType from "./types/StringType";
-/**
-*/
 export default class Rule {
+    static any(): AnyType;
     static number(): NumberType;
     static string(): StringType;
     static object(): ObjectType;
     static array(): ArrayType;
+    static boolean(): BooleanType;
+    static function(): FunctionType;
 }

package/lib/validator/Rule.js

@@ -7,13 +7,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const AnyType_1 = __importDefault(require("./types/AnyType"));
 const ArrayType_1 = __importDefault(require("./types/ArrayType"));
+const BooleanType_1 = __importDefault(require("./types/BooleanType"));
+const FunctionType_1 = __importDefault(require("./types/FunctionType"));
 const NumberType_1 = __importDefault(require("./types/NumberType"));
 const ObjectType_1 = __importDefault(require("./types/ObjectType"));
 const StringType_1 = __importDefault(require("./types/StringType"));
-/**
-*/
 class Rule {
+    static any() {
+        return new AnyType_1.default();
+    }
     static number() {
         return new NumberType_1.default();
     }
@@ -26,5 +30,11 @@ class Rule {
     static array() {
         return new ArrayType_1.default();
     }
+    static boolean() {
+        return new BooleanType_1.default();
+    }
+    static function() {
+        return new FunctionType_1.default();
+    }
 }
 exports.default = Rule;