vrack2-core 0.0.1 → 1.0.0

package/src/service/Device.ts

@@ -3,30 +3,15 @@
  * Licensed under the Apache License, Version 2.0
 */
 
-
-// import DeviceError from "../errors/DeviceError";
-// import Rule from "../validator/ValidatorRule";
 import BasicType from "../validator/types/BasicType";
 import Container from '../Container';
 import BasicAction from "../actions/BasicAction";
 import BasicPort from "../ports/BasicPort";
 import DevicePort from "./DevicePort";
-import  IDeviceEvent  from "./IDeviceEvent";
-
-
-/**
- * Интерфейс списка исходящих портов устройства
-// */
-// export interface IDeviceOutputList {
-//     [index: string]: OutputPort;
-// }
-
-// /**
-//  * Интерфейс списка входящих портов устройства
-// */
-// export interface IDeviceInputList {
-//     [index: string]: InputPort;
-// }
+import IDeviceEvent from "./IDeviceEvent";
+import CoreError from "../errors/CoreError";
+import BasicMetric from "../metrics/BasicMetric";
+import ImportManager from "../ImportManager";
 
 export enum EDeviceMessageTypes {
     terminal = "terminal",
@@ -37,26 +22,64 @@ export enum EDeviceMessageTypes {
     alert = "alert",
 }
 
-interface IDevicePorts {
-    input: {[key:string]: DevicePort}
-    output: {[key:string]: DevicePort}
+interface IDeviceSettings {
+    /**
+     * List of broadcast channels 
+     * Device channels list:
+     *  - terminal
+     *  - notify
+     *  - event
+     *  - action
+     *  - alert
+     *  - error
+     *  - render
+    */
+    channels: Array<'terminal' | 'notify' | 'event' | 'action' | 'alert' | 'error' | 'render'>;
 }
 
 export default class Device {
-    /** Идентификатор устройства */
+
+    /** 
+     * Device unique for this container id   
+     * the name usually begins with a capital letter
+     * 
+     * @example 'DeviceName'
+     * */
     id: string;
+
+    /**
+     * Device type string 
+     * Uses the vendor name and device name
+     * @example 'vrack.KeyManager'
+    */
     type: string;
- 
 
-    ports: IDevicePorts
+    /**
+     * Allows access to port management. 
+    */
+    ports: {
+        input: { [key: string]: DevicePort }
+        output: { [key: string]: DevicePort }
+    }
 
-    /** Экземпляр класса виртуальной стойки */
+    /** 
+     * Active loader container
+     * */
     Container: Container;
 
-    /** Входящие (назначаемые сверху) параметры устройства */
-    options: {[key: string]: any} = {};
+    /**
+     * Device options
+     * 
+     * @see checkOptions()
+    */
+    options: { [key: string]: any } = {};
 
-    constructor(id: string, type: string, Container: Container){
+    /**
+     * @param id Unique ID
+     * @param type Device type string 
+     * @param Container Active loader container
+    */
+    constructor(id: string, type: string, Container: Container) {
         this.id = id
         this.type = type
         this.Container = Container
@@ -66,37 +89,82 @@ export default class Device {
         }
     }
 
+    /**
+     * Device settings
+     *  
+     * Needs to be finalized"
+    */
+    settings(): IDeviceSettings {
+        return {
+            channels: ['terminal', 'notify', 'event', 'action', 'alert', 'error', 'render']
+        }
+    }
+
     /** 
-     * Short device description
+     * Short device description. Can use markdown markup
      * 
      * @return {string} Device description
      * */
-    description(): string{
+    description(): string {
         return ''
     }
 
     /** 
-     * Shares данные устройства (обновляемые данные) 
-     * используется с методом `this.render`
+     * This is a fast updating data object - it will be sent 
+     * to subscribers after the render() call
      * 
      * @see render()
      * */
     shares: any = {};
 
     /**
+     * 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
     */
     storage: any = {}
 
-    /** Список Action-методов устройства */
-    actions() : { [key: string] : BasicAction} { 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(): {[key:string]: BasicType} { return {} }
+    actions(): { [key: string]: BasicAction } { return {} }
+
+    /**
+     * Defining device metrics. 
+     * 
+     * @example
+     * 
+     * ```
+     * return {
+     *  'test.metric': Metric.inS().retentions('1s:6h').description('Test metric')
+     * }
+     * ```
+     * @see BasicMetric
+    */
+    metrics(): { [key: string]: BasicMetric } { return {} }
+
+
+    /**
+     * Run before each device action
+     * 
+     * @param action "device.action" like string
+     * @param data  data for action
+    */
+    beforeAction(action: string, data: any) { return true }
 
     /**
      * Prepare options 
@@ -105,121 +173,184 @@ export default class Device {
     */
     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(): { [key: string]: BasicType } { return {} }
+
+    /**
+     * Device inputs list 
+     * 
+     * Use like this object:
+     * {
+     *    'group.portname': Port.standart(),
+     *    'group.portname': Port.standart()
+     * }
+     * 
+    */
+    inputs(): { [key: string]: BasicPort } { return {} }
 
-    inputs () : {[key:string]: BasicPort} { return {} }
-    outputs () : {[key:string]: BasicPort} { return {} }
+    /**
+     * Device output list
+     * 
+     * @see inputs
+    */
+    outputs(): { [key: string]: BasicPort } { 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.)
     */
     async processPromise() { return }
 
-    stop() { return }
-
-    async stopPromise() { 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: string, trace: any) { 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: string, trace: any) { return this.event('device.notify', data, trace) }
+    metric(path: string, value: number, modify: 'last' | 'first' | 'max' | 'min' | 'avg' | 'sum' = 'last') {
+        return this.makeEvent('device.metric', path, { value, modify }, [])
+    }
 
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке оповещения
-     * 
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    terminal(data: string, trace: { [key: string]: any }, ...args: any[]) { return this.makeEvent('device.terminal', data, trace, args) }
+
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    notify(data: string, trace: { [key: string]: any }, ...args: any[]) { return this.makeEvent('device.notify', data, trace, args) }
+
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    event(data: string, trace: { [key: string]: any }, ...args: any[]) { return this.makeEvent('device.event', data, trace, args) }
+
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
     */
-    alert(data: string, trace: any) { return this.event('device.alert', data, trace) }
+    alert(data: string, trace: { [key: string]: any }, ...args: any[]) { return this.makeEvent('device.alert', data, trace, args) }
 
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке отладочной информации
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    error(data: string, trace: { [key: string]: any }, ...args: any[]) {
+        if (trace instanceof Error) trace = CoreError.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
     */
-    terminal(data: string, trace: any) { return this.event('device.terminal', data, trace) }
+    protected makeEvent(type: string, data: string, trace: { [key: string]: any }, args: any[]) {
+        const nEvent: IDeviceEvent = { device: this.id, data, trace }
+        return this.Container.emit(type, nEvent)
+    }
 
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке сообщения о событии
+     * Adding processing for the incoming port
      * 
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param name Port name in 'port.name' format
+     * @param action CallBack function to execute
     */
-    protected event(type:string, data: string, trace: any) { 
-        const nEvent: IDeviceEvent = {id: this.id, data, trace}
-        return this.Container.emit(type, nEvent) 
+    addInputHandler(name: string, action: (data: any) => any) {
+        name = ImportManager.camelize('input.' + name)
+        this[name as keyof Device] = action
     }
 
     /**
-     * Сообщает стойке, о том, что устройство не может дальше работать
-     * и произошла критическая ошибка
+     * Adding a handle for the action
      * 
-     * Требует создание ошибки устройства DeviceError
+     * @param name Action name in the format 'action.name'
+     * @param action CallBack function to execute
+    */
+    addActionHandler(name: string, action: (data: any) => any) {
+        name = ImportManager.camelize('action.' + name)
+        this[name as keyof Device] = action
+    }
+
+    /**
+     * Informs the rack that the unit cannot continue to operate.
+     * and a critical error has occurred
      * 
+     * Requires DeviceError to be created
     */
     terminate(error: Error, action: string) {
-        return this.event('device.terminate', action, error)
+        return this.makeEvent('device.terminate', action, error, [])
     }
 }

package/src/service/DeviceConnect.ts

@@ -6,17 +6,14 @@
 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) {
         this.outputLink = output
@@ -26,9 +23,8 @@ export default class {
     }
 
     /**
-     * Вызов входящего порта при вызове соединения
-     * 
-     * @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 {
         return this.inputLink.push(data)

package/src/service/DevicePort.ts

@@ -5,17 +5,34 @@
 
 import IPort from "../ports/IPort"
 import DeviceConnect from "./DeviceConnect"
+import Utility from "../Utility"
 
 /**
- * Класс для реализации порта устройства
- * Порт может быть как входящий так и исходящий
+ * 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 = false
+
+    /** 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 = new Map<number, (data:any) => void>()
+
     constructor(id: string, port: IPort) {
         this.id = id
         this.type = port.type
@@ -23,7 +40,7 @@ export default class DevicePort {
     }
 
     /**
-     * Добавление связи в порт
+     * Adding communication to a port
     */
     addConnection(connection: DeviceConnect) {
         this.connected = true
@@ -31,16 +48,18 @@ export default class DevicePort {
     }
 
     /**
-     * Вызов входящего порта при вызове соединения
-     * 
-     * @param {any} data Данные 
+     * Calling the incoming port when calling a connection 
     */
     push(data: any): any { 
-        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.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)
     }
 }

package/src/service/IDeviceEvent.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/src/validator/IValidationProblem.ts

@@ -1,9 +1,16 @@
 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/src/validator/IValidationRule.ts

@@ -1,10 +1,22 @@
 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/src/validator/IValidationSubrule.ts

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

package/src/validator/Rule.ts

@@ -3,15 +3,20 @@
  * Licensed under the Apache License, Version 2.0
 */
 
+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() {
+        return new AnyType()
+    }
+
     static number() {
         return new NumberType()
     }
@@ -27,4 +32,13 @@ export default class Rule {
     static array (){
         return new ArrayType()
     }
+
+    static boolean (){
+        return new BooleanType()
+    }
+
+    static function (){
+        return new FunctionType()
+    }
+
 }