vrack2-core 0.0.1 → 1.0.1

package/lib/service/Device.d.ts

@@ -3,9 +3,7 @@ import Container from '../Container';
 import BasicAction from "../actions/BasicAction";
 import BasicPort from "../ports/BasicPort";
 import DevicePort from "./DevicePort";
-/**
- * Интерфейс списка исходящих портов устройства
-// */
+import BasicMetric from "../metrics/BasicMetric";
 export declare enum EDeviceMessageTypes {
     terminal = "terminal",
     info = "info",
@@ -14,49 +12,145 @@ export declare enum EDeviceMessageTypes {
     action = "action",
     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;
-    /** Входящие (назначаемые сверху) параметры устройства */
+    /**
+     * Device options
+     *
+     * @see checkOptions()
+    */
     options: {
         [key: string]: any;
     };
+    /**
+     * @param id Unique ID
+     * @param type Device type string
+     * @param Container Active loader container
+    */
     constructor(id: string, type: string, Container: Container);
     /**
-     * Short device description
+     * Device settings
+     *
+     * Needs to be finalized"
+    */
+    settings(): IDeviceSettings;
+    /**
+     * Short device description. Can use markdown markup
      *
      * @return {string} Device description
      * */
     description(): string;
     /**
-     * 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-методов устройства */
+    /**
+     * Device action list
+     * Device actions can be called from the container.
+     * This is a way to interact with the device from the outside world
+     *
+     * @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.
+     * */
     actions(): {
         [key: string]: BasicAction;
     };
     /**
-     * Определение списка параметров устройства
+     * Defining device metrics.
+     *
+     * @example
+     *
+     * ```
+     * return {
+     *  'test.metric': Metric.inS().retentions('1s:6h').description('Test metric')
+     * }
+     * ```
+     * @see BasicMetric
+    */
+    metrics(): {
+        [key: string]: BasicMetric;
+    };
+    /**
+     * Run before each device action
+     *
+     * @param action "device.action" like string
+     * @param data  data for action
+    */
+    beforeAction(action: string, data: any): boolean;
+    /**
+     * Prepare options
+     *
+     * this method call before validating options
+    */
+    prepareOptions(): void;
+    /**
+     * Defining a list of device parameters
+     *
+     * @example
+     * ```ts
+     * return {
+     *      timeout: Rule.number().integer().min(0).description('Interval timeout').example(0)
+     * }
+     * ```
      *
      * @returns {Array<Rule>}
      * */
@@ -64,111 +158,152 @@ export default class Device {
         [key: string]: BasicType;
     };
     /**
-     * Prepare options
+     * Device inputs list
+     *
+     * Use like this object:
+     * {
+     *    'group.portname': Port.standart(),
+     *    'group.portname': Port.standart()
+     * }
      *
-     * this method call before validating options
     */
-    prepareOptions(): void;
     inputs(): {
         [key: string]: BasicPort;
     };
+    /**
+     * Device output list
+     *
+     * @see inputs
+    */
     outputs(): {
         [key: string]: BasicPort;
     };
     /**
-     * Метод является входной точкой для начала инициализации устройства
+     * 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(): void;
     /**
-     * Метод является входной точкой для начала работы устройства
+     * 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(): void;
     /**
-     * По аналогии с `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(): Promise<void>;
-    stop(): void;
-    stopPromise(): Promise<void>;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к постановке в очередь устройства на обновление данных `Shares`
+     * Myby todo?
+     *
+     * stop() { return }
+     * async stopPromise() { return }
+    */
+    /**
+     * Queues device shares data updates for external consumers
+     *
+     * @see shares
     */
     render(): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к сохранение в локальное файловое хранилище данных `Storage`
+     * Save device storage
+     *
+     * @see storage
     */
     save(): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке сообщению об ошибке
+     * 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'
     */
-    error(data: string, trace: any): boolean;
+    metric(path: string, value: number, modify?: 'last' | 'first' | 'max' | 'min' | 'avg' | 'sum'): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке информационного сообщения
-     *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param data Message
+     * @param trace Trace info (object needed)
     */
-    notify(data: string, trace: any): boolean;
+    terminal(data: string, trace: {
+        [key: string]: any;
+    }, ...args: any[]): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке оповещения
-     *
-     * @param {string} data Сообщение об ошибке
-     * @param {any} trace Дополнительная информация
+     * @param data Message
+     * @param trace Trace info (object needed)
     */
-    alert(data: string, trace: any): boolean;
+    notify(data: string, trace: {
+        [key: string]: any;
+    }, ...args: any[]): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке отладочной информации
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    event(data: string, trace: {
+        [key: string]: any;
+    }, ...args: any[]): boolean;
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    alert(data: string, trace: {
+        [key: string]: any;
+    }, ...args: any[]): boolean;
+    /**
+     * @param data Message
+     * @param trace Trace info (object needed)
+    */
+    error(data: string, trace: {
+        [key: string]: any;
+    }, ...args: any[]): boolean;
+    /**
+     * 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): boolean;
+    protected makeEvent(type: string, data: string, trace: {
+        [key: string]: any;
+    }, args: any[]): boolean;
     /**
-     * Метод заменяется загрузчиком стойки, после чего, вызов этого метода приводит
-     * к отправке сообщения о событии
+     * 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): boolean;
+    addInputHandler(name: string, action: (data: any) => any): void;
     /**
-     * Сообщает стойке, о том, что устройство не может дальше работать
-     * и произошла критическая ошибка
+     * 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): void;
+    /**
+     * 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): boolean;
 }