@mirta/globals 0.3.0 → 0.3.2

package/eslint/index.d.ts

@@ -2,6 +2,7 @@ declare interface GlobalsMirta {
   readonly '__DEV__': false
   readonly '__TEST__': false
   readonly 'log': false
+  readonly 'debug': false
   readonly 'dev': false
   readonly 'cron': false
   readonly 'timers': false

package/eslint/index.js

@@ -2,6 +2,7 @@ export default {
   '__DEV__': 'readonly',
   '__TEST__': 'readonly',
   'log': 'readonly',
+  'debug': 'readonly',
   'dev': 'readonly',
   'cron': 'readonly',
   'timers': 'readonly',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mirta/globals",
   "description": "Complete set of types for wb-rule development in TypeScript",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "Unlicense",
   "keywords": [
     "mirta",

package/types/wb-rules.d.ts

@@ -16,6 +16,7 @@
  * // }
  * ```
  * @since 0.0.4
+ *
  **/
 declare type Expand<T> = { [K in keyof T]: T[K] } & {}
 
@@ -25,47 +26,114 @@ declare namespace WbRules {
   /** Расширение для поддержки module.static */
   type ModuleStatic = Record<string, unknown>
 
-  type LogFunc = (
-    message: string | undefined, ...args: (string | number | boolean)[]
-  ) => void
+  /**
+   * Набор методов для логирования.
+   *
+   * @since 0.3.2
+   *
+   **/
+  interface LogMethods {
 
-  interface Log {
     /**
      * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    (message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.info('Свет в комнате включён на {} мин.', 30)
+     * ```
+     **/
+    info(format: string, ...args: unknown[]): void
 
     /**
-     * Запись в лог сообщения, полезного при отладке в процессе разработки и не представляющего ценности в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    debug(message: unknown, ...args: (string | number | boolean)[]): void
+     * Запись в лог произвольного значения, полезного в долгосрочной перспективе.
+     * @param value Значение для записи в лог.
+     *
+     **/
+    info(value: unknown): void
 
     /**
-     * Запись в лог информационного сообщения, полезного в долгосрочной перспективе.
-     * @param message
-     * @param args
-     */
-    info(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог сообщения, полезного при отладке и не имеющего долгосрочной ценности.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.debug('Значение сенсора "{}": температура {} °C, влажность {} %', 'bathroom', 25, 40)
+     **/
+    debug(format: string, ...args: unknown[]): void
 
     /**
-     * Запись ненормального или неожиданного события в потоке приложения, но не прекращение выполнения.
-     * @param message
-     * @param args
-     */
-    warning(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог произвольного значения, полезного при отладке и не имеющего долгосрочной ценности.
+     *
+     * @param value Значение для записи в лог.
+     *
+     * @example
+     * ```ts
+     * log.debug(JSON.stringify({ location: 'bathroom', temperature: 25, humidity: 40 }))
+     * ```
+     **/
+    debug(value: unknown): void
 
     /**
-     * Запись события остановки выполнения из-за сбоя текущего действия.
-     * @param message
-     * @param args
-     */
-    error(message: string | undefined, ...args: (string | number | boolean)[]): void
+     * Запись в лог предупреждения о ненормальном или неожиданном событии,
+     * не приводящем к остановке программы.
+     *
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.warning('Движение в охраняемой зоне: {}', 'hallway_sensor_1')
+     * ```
+     **/
+    warning(format: string, ...args: unknown[]): void
+
+    /**
+     * Запись в лог предупреждения о ненормальном или неожиданном значении,
+     * не приводящем к остановке программы.
+     *
+     * @param value Значение для записи в лог.
+     *
+     **/
+    warning(value: unknown): void
+
+    /**
+     * Запись в лог критического события, приведшего к сбою и остановке выполнения.
+     * Используется форматированный вывод.
+     *
+     * @param format Форматируемый шаблон сообщения.
+     * @param args Параметры для заполнения формата.
+     *
+     * @example
+     * ```ts
+     * log.error('Перегев тёплого пола: {} °C, выключение', 30)
+     * ```
+     **/
+    error(format: string, ...args: unknown[]): void
+
+    /**
+     * Запись в лог критического значения, приведшего к сбою и остановке выполнения.
+     *
+     * @param value Значение для записи в лог.
+     *
+     **/
+    error(value: unknown): void
   }
 
+  /** @deprecated since version 0.3.2 */
+  type LogFunc = (format: string, ...args: unknown[]) => void
+
+  type Log = LogMethods['info'] & LogMethods
+
+  type Debug = LogMethods['debug']
+
   interface CronEntry {
     spec: string
   }
@@ -384,6 +452,62 @@ declare namespace WbRules {
     order?: number
   }>
 
+  /**
+   * Опции контрола типа `text`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type TextControlOptions = Extract<ControlOptions, { type: 'text' }>
+
+  /**
+   * Опции контрола типа `value`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type ValueControlOptions = Extract<ControlOptions, { type: 'value' }>
+
+  /**
+   * Опции контрола типа `range`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type RangeControlOptions = Extract<ControlOptions, { type: 'range' }>
+
+  /**
+   * Опции контрола типа `switch`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type SwitchControlOptions = Extract<ControlOptions, { type: 'switch' }>
+
+  /**
+   * Опции контрола типа `pushbutton`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type PushButtonControlOptions = Extract<ControlOptions, { type: 'pushbutton' }>
+
+  /**
+   * Опции контрола типа `rgb`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type RgbControlOptions = Extract<ControlOptions, { type: 'rgb' }>
+
+  /**
+   * Опции контрола типа `alarm`.
+   *
+   * @since 0.3.2
+   *
+   **/
+  type AlarmControlOptions = Extract<ControlOptions, { type: 'alarm' }>
+
   /**
    * Интерфейс устройства
    */
@@ -495,6 +619,14 @@ declare var __filename: string
 /** Используется для вывода сообщений в журнал контроллера и отладочную консоль. */
 declare var log: WbRules.Log
 
+/**
+ * Используется для вывода отладочных сообщений в журнал контроллера и отладочную консоль.
+ *
+ * @since 0.3.2
+ *
+ **/
+declare var debug: WbRules.Debug
+
 /** Объект доступа к MQTT-топикам устройства. */
 declare var dev: WbRules.Dev
 
@@ -730,28 +862,40 @@ declare class PersistentStorage {
 }
 
 /**
- * Класс оповещения
- * @abstract
- */
+ * Класс оповещения.
+ *
+ **/
 declare abstract class Notify {
   /**
-   * Отправляет почту указанному адресату
-   * @static
-   * @param to адресат
-   * @param subject тема
-   * @param text содержимое
-   * @memberof Notify
-   */
+   * Отправляет электронное письмо указанному адресату.
+   *
+   * @param to Адресат.
+   * @param subject Тема письма.
+   * @param text Текст письма.
+   *
+   **/
   static sendEmail(to: string, subject: string, text: string): void
 
   /**
    * Отправляет SMS на указанный номер
    * Для отправки SMS используется ModemManager, а если он не установлен, то gammu.
-   * @static
-   * @param to номер адресата
-   * @param text содержимое
-   * @param command используя команду
-   * @memberof Notify
-   */
+   *
+   * @param to Номер адресата.
+   * @param text Текст сообщения.
+   * @param command Используя команду.
+   *
+   **/
   static sendSMS(to: string, text: string, command?: string): void
+
+  /**
+   * Отправляет сообщение в указанный чат или канал Telegram.
+   *
+   * @param token Токен вашего бота Telegram.
+   * @param chatId Уникальный идентификатор целевого чата или username целевого канала (в формате `@channelusername`).
+   * @param text Текст сообщения.
+   *
+   * @since 0.3.2
+   *
+   **/
+  static sendTelegramMessage(token: string, chatId: string, text: string): void
 }