@mirta/globals 0.3.5 → 0.4.0

package/eslint/index.d.ts

@@ -7,6 +7,9 @@ declare interface GlobalsMirta {
   readonly 'cron': false
   readonly 'timers': false
   readonly 'defineRule': false
+  readonly 'disableRule': false
+  readonly 'enableRule': false
+  readonly 'runRule': false
   readonly 'defineAlias': false
   readonly 'defineVirtualDevice': false
   readonly 'getDevice': false

package/eslint/index.js

@@ -7,6 +7,9 @@ export default {
   'cron': 'readonly',
   'timers': 'readonly',
   'defineRule': 'readonly',
+  'disableRule': 'readonly',
+  'enableRule': 'readonly',
+  'runRule': 'readonly',
   'defineAlias': 'readonly',
   'defineVirtualDevice': 'readonly',
   'getDevice': '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.5",
+  "version": "0.4.0",
   "license": "Unlicense",
   "keywords": [
     "mirta",
@@ -14,6 +14,7 @@
     "LICENSE",
     "README.md"
   ],
+  "types": "./types/index.d.ts",
   "exports": {
     ".": {
       "types": "./types/index.d.ts"

package/types/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./utils.d.ts" />
 /// <reference path="./wb-rules.d.ts" />
 
 /** Признак сборки в режиме разработки. */

package/types/utils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Используется для нормализации составных типов.
+ *
+ * @example
+ * ```ts
+ * interface A { value: number }
+ * interface B { isReadonly: boolean }
+ *
+ * type C = A & B
+ * // A & B
+ *
+ * type D = Expand<A & B>
+ * // {
+ * //   value: number;
+ * //   isReadonly: boolean;
+ * // }
+ * ```
+ * @since 0.0.4
+ *
+ **/
+declare type Expand<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * Разрешает частичное заполнение полей объекта, но требует наличия хотя бы одного поля.
+ *
+ * @example
+ * ```ts
+ * interface SafeRange {
+ *   minValue: number
+ *   maxValue: number
+ * }
+ *
+ * // Корректное объявление
+ * const a: AtLeastOne<SafeRange> = {
+ *   minValue: 0
+ * }
+ *
+ * // Ошибка - требуется хотя бы одно из обязательных полей
+ * const b: AtLeastOne<SafeRange> = { }
+ * ```
+ * @since 0.3.3
+ *
+ **/
+declare type AtLeastOne<T, U = { [K in keyof T]: Pick<T, K> }> = Partial<T> & U[keyof U]
+
+/**
+ * Утилита для создания "брендированных типов" (branded types).
+ *
+ * Позволяет создавать типобезопасные псевдонимы простых типов, предотвращая их взаимозаменяемость.
+ * Полезно для разграничения значений, имеющих одинаковый базовый тип, но разное назначение.
+ *
+ * На уровне JavaScript это не оказывает влияния (исчезает при компиляции),
+ * однако при работе с TypeScript обеспечивает строгую проверку типов.
+ *
+ * @template TValue - Базовый тип (например, string, number)
+ * @template TBrand - Уникальная метка, определяющая семантику типа
+ *
+ * @example
+ * type UserID = Branded<string, 'UserID'>
+ * type OrderID = Branded<string, 'OrderID'>
+ *
+ * const userId: UserID = 'user-123' as UserID
+ * const orderId: OrderID = userId // Ошибка: типы 'UserID' и 'OrderID' несовместимы
+ *
+ * @since 0.4.0
+ *
+ **/
+declare type Branded<TValue, TBrand extends string | symbol>
+  = TValue & { readonly __brand: TBrand }

package/types/wb-rules.d.ts

@@ -1,50 +1,6 @@
+/// <reference path="./utils.d.ts" />
 /// <reference path="./wb-rules/alarms.d.ts" />
 
-/**
- * Используется для нормализации составных типов.
- *
- * @example
- * ```ts
- * interface A { value: number }
- * interface B { isReadonly: boolean }
- *
- * type C = A & B
- * // A & B
- *
- * type D = Expand<A & B>
- * // {
- * //   value: number;
- * //   isReadonly: boolean;
- * // }
- * ```
- * @since 0.0.4
- *
- **/
-declare type Expand<T> = { [K in keyof T]: T[K] } & {}
-
-/**
- * Разрешает частичное заполнение полей объекта, но требует наличия хотя бы одного поля.
- *
- * @example
- * ```ts
- * interface SafeRange {
- *   minValue: number
- *   maxValue: number
- * }
- *
- * // Корректное объявление
- * const a: AtLeastOne<SafeRange> = {
- *   minValue: 0
- * }
- *
- * // Ошибка - требуется хотя бы одно из обязательных полей
- * const b: AtLeastOne<SafeRange> = { }
- * ```
- * @since 0.3.3
- *
- **/
-declare type AtLeastOne<T, U = { [K in keyof T]: Pick<T, K> }> = Partial<T> & U[keyof U]
-
 /** Типы и интерфейсы правил wb-rules */
 declare namespace WbRules {
 
@@ -216,6 +172,31 @@ declare namespace WbRules {
     ): void
   }
 
+  /**
+   * Дескриптор, возвращаемый функцией {@link defineRule}.
+   *
+   * Используется для управления правилом: отключение,
+   * включение, принудительный запуск.
+   *
+   * @example
+   * ```ts
+   * const cabinetLightRule = defineRule('cabinet_light', {
+   *   whenChanged: 'motion/sensor',
+   *   then: (newValue) => dev['light/power'] = newValue
+   * })
+   *
+   * // Отключить правило
+   * disableRule(cabinetLightRule)
+   *
+   * // Включить снова
+   * enableRule(cabinetLightRule)
+   * ```
+   *
+   * @since 0.4.0
+   *
+   **/
+  type RuleHandle = Branded<number, 'WbRules.RuleHandle'>
+
   /**
    * Соответствие типа контрола его типу значения.
    * @since 0.0.4
@@ -716,14 +697,63 @@ declare function cron(spec: string): WbRules.CronEntry
  * @param options Конфигурация правила.
  *
  **/
-declare function defineRule(name: string, options: WbRules.RuleOptions): void
+declare function defineRule(name: string, options: WbRules.RuleOptions): WbRules.RuleHandle
 
 /**
  * Создаёт анонимное правило обработки.
  * @param options Конфигурация правила.
  *
  **/
-declare function defineRule(options: WbRules.RuleOptions): void
+declare function defineRule(options: WbRules.RuleOptions): WbRules.RuleHandle
+
+/**
+ * Отключает правило. Оно перестаёт реагировать на события.
+ * Сохраняется в памяти — можно включить снова.
+ *
+ * @param rule - Дескриптор правила, возвращённый {@link defineRule}.
+ *
+ * @example
+ * ```ts
+ * const cabinetLightRule = defineRule({ ... })
+ * disableRule(cabinetLightRule)
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function disableRule(rule: WbRules.RuleHandle): void
+
+/**
+ * Включает ранее отключённое правило.
+ *
+ * @param rule - Дескриптор правила, возвращённый {@link defineRule}.
+ *
+ * @example
+ * ```ts
+ * enableRule(cabinetLightRule)
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare function enableRule(rule: WbRules.RuleHandle): void
+
+/**
+ * Запускает правило по его дескриптору.
+ *
+ * @warning
+ * Контекст вызова будет пустым:
+ * - `newValue = undefined`
+ * - `deviceId = undefined`
+ * - `controlId = undefined`
+ *
+ * Не используйте `runRule` для правил, зависящих от этих значений.
+ * Вместо этого выносите общую логику в отдельную функцию и вызывайте её напрямую.
+ *
+ * @param rule - Дескриптор правила, возвращённый {@link defineRule}.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function runRule(rule: WbRules.RuleHandle): void
 
 /**
  * Создаёт виртуальное устройство.