@mirta/globals 0.0.2

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,26 @@
+# @mirta/globals
+
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-globals/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-globals/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/globals?style=flat-square)](https://npmjs.com/package/@mirta/globals)
+
+Provides a complete set of necessary types enabling development of wb-rules in TypeScript.
+
+## Installation
+
+```sh
+pnpm add -D @mirta/globals
+```
+Add following lines to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "types": [
+      "@mirta/globals",
+      "node"
+    ]
+  }
+}
+```

package/README.ru.md

@@ -0,0 +1,25 @@
+# @mirta/globals
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-globals/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-globals/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/globals?style=flat-square)](https://npmjs.com/package/@mirta/globals)
+
+Содержит все необходимые типы для разработки правил wb-rules на TypeScript.
+
+## Установка
+
+```sh
+pnpm add -D @mirta/globals
+```
+Добавьте следующие строки в ваш `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "node"
+      "@mirta/globals",
+    ]
+  }
+}
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mirta/globals",
+  "description": "Complete set of types for wb-rule development in TypeScript",
+  "version": "0.0.2",
+  "license": "Unlicense",
+  "keywords": [
+    "mirta",
+    "globals",
+    "wb-rules"
+  ],
+  "files": [
+    "types",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts"
+    }
+  },
+  "homepage": "https://github.com/wb-mirta/core/tree/latest/packages/mirta-globals#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wb-mirta/core.git",
+    "directory": "packages/mirta-globals"
+  },
+  "bugs": {
+    "url": "https://github.com/wb-mirta/core/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,6 @@
+/// <reference path="./wb-rules.d.ts" />
+
+/** Признак сборки в режиме разработки. */
+declare var __DEV__: boolean
+/** Признак запуска в режиме тестирования. */
+declare var __TEST__: boolean

package/types/wb-rules.d.ts

@@ -0,0 +1,497 @@
+/** Типы и интерфейсы правил wb-rules */
+declare namespace WbRules {
+
+  /** Расширение для поддержки module.static */
+  type ModuleStatic = Record<string, unknown>
+
+  type LogFunc = (
+    message: string | undefined, ...args: (string | number | boolean)[]
+  ) => void
+
+  interface Log {
+    /**
+     * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
+     * @param message
+     * @param args
+     */
+    (message: string | undefined, ...args: (string | number | boolean)[]): void
+
+    /**
+     * Запись в лог сообщения, полезного при отладке в процессе разработки и не представляющего ценности в долгосрочной перспективе.
+     * @param message
+     * @param args
+     */
+    debug(message: unknown, ...args: (string | number | boolean)[]): void
+
+    /**
+     * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
+     * @param message
+     * @param args
+     */
+    info(message: string | undefined, ...args: (string | number | boolean)[]): void
+
+    /**
+     * Запись ненормального или неожиданного события в потоке приложения, но не прекращение выполнения.
+     * @param message
+     * @param args
+     */
+    warning(message: string | undefined, ...args: (string | number | boolean)[]): void
+
+    /**
+     * Запись события остановки выполнения из-за сбоя текущего действия.
+     * @param message
+     * @param args
+     */
+    error(message: string | undefined, ...args: (string | number | boolean)[]): void
+  }
+
+  type DevControl = Record<string, unknown>
+  type Dev = Record<string, DevControl | undefined>
+
+  interface Timer {
+    firing: boolean
+
+    stop(): void
+  }
+
+  type TimerCollection = Record<string, Timer>
+
+  /** Тип значения топика MQTT. */
+  type MqttValue = string | number | boolean
+
+  interface MqttMessage {
+    topic: string
+    value: MqttValue
+  }
+
+  /**
+   * Объект описания правила
+   */
+  interface RuleOptions {
+    /**
+     * Поле или список полей, которые необходимо отслеживать
+     */
+    whenChanged?: string[] | string
+
+    /**
+     * Правило срабатывает, когда значение, возвращаемое функцией, меняется с false на true.
+     */
+    asSoonAs?(): boolean
+
+    /**
+     * Функция, которая сигнализирует, что правило должно отработать
+     */
+    when?(): number | boolean
+
+    /**
+     * Функция, которая вызывается при срабатывании правила
+     * @param newValue Новое значение
+     * @param deviceId Устройство, сгенерировавшее событие
+     * @param controlId Поле, по которому произошло событие
+     */
+    then(
+      newValue?: MqttValue,
+      deviceId?: string,
+      controlId?: string
+    ): void
+  }
+
+  enum ControlType {
+    SWITCH = 'switch',
+    ALARM = 'alarm',
+    PUSHBUTTON = 'pushbutton',
+    RANGE = 'range',
+    RGB = 'rgb',
+    TEXT = 'text',
+    VALUE = 'value'
+  }
+
+  /**
+   * Объект настроек передаваемого в контрол значения.
+   */
+  interface ControlValueOptions {
+    /**
+     * Значение контрола
+     */
+    value: string | number | boolean
+
+    /**
+     * Уведомить правила об изменении значения,
+     * по умолчанию - `true`.
+     */
+    notify?: boolean
+  }
+
+  /**
+   * Контрол устройства
+   */
+  interface Control {
+    /**
+     * Устанавливает заголовок.
+     * @param title
+     */
+    setTitle(title: string): void
+
+    /**
+     * Устанавливает описание.
+     * @param description
+     */
+    setDescription(description: string): void
+
+    /**
+     * Устанавливает тип значения.
+     * @param type Тип значения.
+     * @see ControlType
+     */
+    setType(controlType: ControlType): void
+
+    setUnits(units: string): void
+
+    setReadonly(isReadonly: boolean): void
+
+    setMax(max: number): void
+
+    setMin(min: number): void
+
+    setError(order: number): void
+
+    setValue(value: MqttValue | ControlValueOptions): void
+
+    getId(): string
+
+    getTitle(): string
+
+    getDescription(): string
+
+    getType(): string
+
+    getUnits(): string
+
+    getReadonly(): boolean
+
+    getMax(): number
+
+    getMin(): number
+
+    getError(): string
+
+    getOrder(): number
+
+    getValue(): string | number | boolean
+  }
+
+  /**
+   * Конфигурация контрола.
+   */
+  interface ControlOptions {
+    /**
+     * имя, публикуемое в MQTT-топике
+     */
+    title?: string
+    /**
+     * тип, публикуемый в MQTT-топике
+     * @see ControlType
+     */
+    type: string
+    /**
+     * значение параметра по умолчанию
+     */
+    value: string | number | boolean
+    /**
+     * когда задано истинное значение, при запуске контроллера параметр всегда устанавливается в значение по умолчанию.
+     * Иначе он будет установлен в последнее сохранённое значение.
+     */
+    forceDefault?: boolean
+    /**
+     * когда задано истинное значение, параметр объявляется read-only
+     */
+    readonly?: boolean
+    precision?: number
+    /**
+     * когда задано истинное значение, при описании контрола в коде фактическое создание его в mqtt происходить
+     * не будет до тех пор, пока этому контролу не будет присвоено какое-то значение
+     * (например dev[deviceID][controlID] = "string")
+     */
+    lazyInit?: boolean
+    /**
+     * Порядок следования полей
+     */
+    order?: number
+    /**
+     * для параметра типа range может задавать его максимально допустимое значение
+     */
+    max?: number
+    /**
+     * для параметра типа range может задавать его минимально допустимое значение
+     */
+    min?: number
+  }
+
+  /**
+   * Интерфейс устройства
+   */
+  interface Device {
+    getId(): string
+
+    getCellId(cellName: string): string
+
+    addControl(cellName: string, description: ControlOptions): void
+
+    removeControl(cellName: string): void
+
+    getControl(cellName: string): Control
+
+    isControlExists(cellName: string): boolean
+
+    controlsList(): Control[]
+
+    isVirtual(): boolean
+  }
+
+  type ControlOptionsTree = Record<string, ControlOptions>
+
+  interface DeviceOptions {
+    title: string
+    cells: ControlOptionsTree
+  }
+
+  /**
+   * Функция, вызываемая при завершении процесса
+   * @param exitCode код возврата процесса
+   * @param capturedOutput захваченный stdout процесса в виде строки в случае, когда задана опция captureOutput
+   * @param capturedErrorOutput захваченный stderr процесса в виде строки в случае, когда задана опция captureErrorOutput
+   */
+  type ExitCallback = (
+    exitCode: number,
+    capturedOutput?: string,
+    capturedErrorOutput?: string
+  ) => void
+
+  interface SpawnOptions {
+    /**
+     * Если true, захватить stdout процесса и передать его в виде строки в exitCallback
+     */
+    captureOutput?: boolean
+    /**
+     * Если true, захватить stderr процесса и передать его в виде строки в exitCallback.
+     * Если данный параметр не задан, то stderr дочернего процесса направляется в stderr процесса wb-rules
+     */
+    captureErrorOutput?: boolean
+    /**
+     * Строка, которую следует использовать в качестве содержимого stdin процесса
+     */
+    input?: string
+
+    /**
+     * Функция, вызываемая при завершении процесса
+     */
+    exitCallback?: ExitCallback
+  }
+
+  interface ReadConfigOptions {
+    logErrorOnNoFile: boolean
+  }
+
+  interface StorageOptions {
+    global: boolean
+  }
+
+  type PersistentStorage = new (
+    name: string,
+    options: StorageOptions
+  ) => PersistentStorage
+}
+
+declare namespace NodeJS {
+  interface Module {
+    /**
+       * Хранит данные, общие для всех экземпляров данного модуля.
+      */
+    static: WbRules.ModuleStatic
+  }
+}
+
+declare var log: WbRules.Log
+
+/**
+ * Объект доступа к MQTT-топикам устройства
+ */
+declare var dev: WbRules.Dev
+
+/**
+ * Объект доступа к именованным таймерам
+ */
+declare var timers: WbRules.TimerCollection
+
+/**
+ * Создаёт правило обработки.
+ * @param ruleName Название правила.
+ * @param options Конфигурация правила.
+ */
+declare function defineRule(name: string, options: WbRules.RuleOptions): void
+/**
+ * Создаёт анонимное правило обработки.
+ * @param options Конфигурация правила.
+ */
+declare function defineRule(options: WbRules.RuleOptions): void
+
+/**
+ * Создаёт виртуальное устройство.
+ * @param deviceId Идентификатор устройства.
+ * @param options Конфигурация устройства.
+ */
+declare function defineVirtualDevice(
+  deviceId: string,
+  options: WbRules.DeviceOptions
+): WbRules.Device
+
+/**
+ * Позволяет получить объект для работы с указанным устройством.
+ * @param deviceId Идентификатор устройства.
+ */
+declare function getDevice(deviceId: string): WbRules.Device | undefined
+
+/**
+ * Позволяет получить объект для работы с указанным контролом устройства.
+ * @param controlPath Строка в формате "deviceId/controlId"
+ */
+declare function getControl(controlPath: string): WbRules.Control | undefined
+
+/**
+ * Запускает периодический таймер с указанным интервалом.
+ *
+ * К таймеру можно обратиться через `timers.<name>` внутри when при работе с `defineRule`.
+ *
+ * @param name Идентификатор таймера в глобальном наборе `timers`.
+ * @param delay Интервал срабатывания, в миллисекундах
+ */
+declare function startTicker(name: string, interval: number): void
+
+/**
+ * Запускает однократный таймер с указанным именем,
+ * к которому можно обратиться через `timers.<name>`,
+ *
+ * см. [руководство по однократным таймерам](https://github.com/wirenboard/wb-rules?tab=readme-ov-file#однократные)
+ *
+ * @param name Идентификатор таймера в глобальном наборе `timers`.
+ * @param delay
+ *
+ * Используется при работе с определениями правил:
+ *
+ * @example
+ * ```ts
+ * defineRule('1', {
+ *   asSoonAs: () => dev['test_buzzer/enabled'],
+ *   then: () => {
+ *     startTimer('one_second', 1000)
+ *     dev['buzzer/enabled'] = true
+ *   }
+ * })
+ *
+ * defineRule('2', {
+ *   when: () => timers.one_second.firing,
+ *   then: () => {
+ *     dev['buzzer/enabled'] = false
+ *     dev['test_buzzed/enabled'] = false
+ *   }
+ * })
+ *
+ * ```
+ *
+ */
+declare function startTimer(name: string, delay: number): void
+
+/**
+ * Запуск внешних процессов
+ * @param cmd
+ * @param args
+ * @param options
+ */
+declare function spawn(
+  cmd: string,
+  args: string[],
+  options: WbRules.SpawnOptions | WbRules.ExitCallback
+): void
+
+declare function runShellCommand(
+  command: string,
+  options: WbRules.SpawnOptions | WbRules.ExitCallback
+): void
+
+declare function readConfig(
+  fileName: string,
+  options?: WbRules.ReadConfigOptions
+): object
+
+/**
+ *
+ * @param alias Альтернативное наименование для контрола.
+ * @param controlPath Путь к контролу устройства в формате `deviceId/controlId`
+ *
+ * @example
+ * ```ts
+ * defineAlias('heaterOn', 'Relays/Relay 1')
+ * ```
+ */
+declare function defineAlias(alias: string, controlPath: string): void
+
+/**
+ * Следует учесть, что функция format и xformat съедают одинарные квадратные скобки!
+ * Поэтому, если необходимо их вывести, то нужно дублировать.
+ */
+interface String {
+  format(...args: (string | number | boolean)[]): string
+  xformat(...args: (string | number | boolean)[]): string
+}
+
+/**
+ * Подписаться на топик (допустимы символы # и +)
+ * @param topic
+ * @param callback
+ */
+declare function trackMqtt(
+  topic: string,
+  callback: (message: WbRules.MqttMessage) => void
+): void
+
+/**
+ * Публикация сообщений в MQTT
+ * Важно: не используйте publish() для изменения значения параметров устройств.
+ * @param topic
+ * @param payload
+ * @param QoS
+ * @param retain
+ */
+declare function publish(
+  topic: string,
+  value: WbRules.MqttValue,
+  QoS?: number,
+  retain?: boolean
+): void
+
+/**
+ * Класс оповещения
+ * @abstract
+ */
+declare abstract class Notify {
+  /**
+   * Отправляет почту указанному адресату
+   * @static
+   * @param to адресат
+   * @param subject тема
+   * @param text содержимое
+   * @memberof Notify
+   */
+  static sendEmail(to: string, subject: string, text: string): void
+
+  /**
+   * Отправляет SMS на указанный номер
+   * Для отправки SMS используется ModemManager, а если он не установлен, то gammu.
+   * @static
+   * @param to номер адресата
+   * @param text содержимое
+   * @param command используя команду
+   * @memberof Notify
+   */
+  static sendSMS(to: string, text: string, command?: string): void
+}