mirta 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Event } from '@mirta/basics';
+import { OnEvent } from '@mirta/basics';
 export * from '@mirta/basics';
 
 type DeviceType = 'wired' | 'virtual' | 'zigbee';
@@ -65,9 +65,9 @@ type StrictWhenSpecified<TObject, TKey extends keyof TObject, TReturn> = IsSpeci
  * Устанавливает указанное свойство в readonly при выполнении указанного условия.
  * @since 0.1.0
  **/
-type ReadonlyPropWhen<TObject, K extends keyof TObject, TCondition extends boolean | undefined> = TCondition extends true ? Omit<TObject, K> & {
+type ReadonlyPropWhen<TObject, K extends keyof TObject, TCondition extends boolean | undefined> = TCondition extends true ? Expand<Omit<TObject, K> & {
     +readonly [P in K]-?: TObject[P];
-} : TObject;
+}> : TObject;
 /**
  * Проверяет, что указанный тип объекта имеет хотя бы одно свойство заданного типа.
  * Применяется для работы с дженериками.
@@ -86,14 +86,66 @@ type HasPropertyOfType<TObject extends object, TProperty> = {
     [K in keyof TObject as TObject[K] extends TProperty ? K : never]: unknown;
 } extends infer R ? {} extends R ? false : true : never;
 
+/**
+ * Набор политик, управляющих доступностью смены значения контрола.
+ *
+ * @since 0.2.0
+ *
+ **/
+declare enum ChangePolicies {
+    /**
+     * Политика по умолчанию.
+     *
+     * - Применяет {@link Public} к контролам типа `switch`, `pushbutton`, `range` и `rgb`;
+     *
+     * - Применяет {@link Script} к остальным типам контролов.
+     *
+     **/
+    Default = "default",
+    /**
+     * Установка значения возможна как скриптами wb-rules, так и сторонними службами.
+     *
+     * Применимо к контролам виртуальных устройств.
+     *
+     **/
+    Public = "public",
+    /**
+     * Установка значения возможна только скриптами wb-rules.
+     *
+     * Применимо к контролам виртуальных устройств.
+     *
+     **/
+    Script = "script",
+    /**
+     * Полный запрет записи, значение доступно только для чтения.
+     *
+     * Применимо к контролам реальных устройств.
+     *
+     **/
+    ReadOnly = "read-only"
+}
+/**
+ * Определяет политику установки значений реальных устройств.
+ *
+ * @since 0.2.0
+ *
+ **/
+type ChangePolicy = `${Exclude<ChangePolicies, ChangePolicies.Public | ChangePolicies.Script>}`;
+/**
+ * Определяет политику установки значений контролов виртуальных устройств.
+ *
+ * @since 0.2.0
+ *
+ **/
+type VirtualChangePolicy = `${Exclude<ChangePolicies, ChangePolicies.ReadOnly>}`;
 type ValueEventHandler<TValue> = (newValue: TValue, oldValue: TValue) => void;
 interface Control<TValue> {
     /** Актуальное значение контрола. */
     value: TValue;
     /** Событие, происходящее когда поступило новое значение. */
-    valueReceived: Event<ValueEventHandler<TValue>>;
+    onValueReceived: OnEvent<ValueEventHandler<TValue>>;
     /** Событие, происходящее когда значение изменилось. */
-    valueChanged: Event<ValueEventHandler<TValue>>;
+    onValueChanged: OnEvent<ValueEventHandler<TValue>>;
 }
 type MaybeReadonlyControl<TValue, TReadonly extends boolean | undefined> = ReadonlyPropWhen<Control<TValue>, 'value', TReadonly>;
 
@@ -117,8 +169,8 @@ type VirtualTypeMapper<K extends keyof WbRules.TypeMappings = keyof WbRules.Type
 interface BaseControlDef {
     /** Идентификатор контрола. Если не указан, используется название свойства. */
     controlId?: string;
-    /** Если `true`, то значение доступно только для чтения. */
-    isReadonly?: boolean;
+    /** Политика доступа на запись значения. */
+    changePolicy?: VirtualChangePolicy | ChangePolicy;
 }
 /**
  * Определения основных контролов.
@@ -166,7 +218,7 @@ type StrictVirtualControls<TControls extends VirtualControls> = TControls & Virt
  * при описании устройства в `defineDevice()`.
  **/
 type CreatedControls<TControls extends Controls | VirtualControls> = {
-    [K in keyof TControls]: Expand<MaybeReadonlyControl<StrictWhenSpecified<TControls[K], 'defaultValue', WbRules.TypeMappings[TControls[K]['type']]>, TControls[K]['isReadonly']>>;
+    [K in keyof TControls]: Expand<MaybeReadonlyControl<StrictWhenSpecified<TControls[K], 'defaultValue', WbRules.TypeMappings[TControls[K]['type']]>, TControls[K]['changePolicy'] extends ChangePolicies.ReadOnly ? true : false>>;
 };
 /** Используется для извлечения типа значения из значения по умолчанию. */
 type InferDefaultType<TProp> = [TProp] extends [{
@@ -431,5 +483,5 @@ declare function getControlSafe(context: DeviceContext, controlId: string): Cont
  **/
 declare function getControlSafe(deviceId: string, controlId: string, isReadyFunc: () => boolean): ControlSafe;
 
-export { defineVirtualDevice, defineWiredDevice, defineZigbeeDevice, getControlSafe, getDeviceSafe };
+export { ChangePolicies, defineVirtualDevice, defineWiredDevice, defineZigbeeDevice, getControlSafe, getDeviceSafe };
 export type { ControlSafe, DeviceContext, DeviceType, PropType, TrackCallback };

package/dist/index.mjs

@@ -23,6 +23,45 @@ function getControlSafe(context, controlId, isReadyFunc = () => true) {
     };
 }
 
+/**
+ * Набор политик, управляющих доступностью смены значения контрола.
+ *
+ * @since 0.2.0
+ *
+ **/
+var ChangePolicies;
+(function (ChangePolicies) {
+    /**
+     * Политика по умолчанию.
+     *
+     * - Применяет {@link Public} к контролам типа `switch`, `pushbutton`, `range` и `rgb`;
+     *
+     * - Применяет {@link Script} к остальным типам контролов.
+     *
+     **/
+    ChangePolicies["Default"] = "default";
+    /**
+     * Установка значения возможна как скриптами wb-rules, так и сторонними службами.
+     *
+     * Применимо к контролам виртуальных устройств.
+     *
+     **/
+    ChangePolicies["Public"] = "public";
+    /**
+     * Установка значения возможна только скриптами wb-rules.
+     *
+     * Применимо к контролам виртуальных устройств.
+     *
+     **/
+    ChangePolicies["Script"] = "script";
+    /**
+     * Полный запрет записи, значение доступно только для чтения.
+     *
+     * Применимо к контролам реальных устройств.
+     *
+     **/
+    ChangePolicies["ReadOnly"] = "read-only";
+})(ChangePolicies || (ChangePolicies = {}));
 const typeMappings = {
     'text': 'string',
     'value': 'number',
@@ -35,10 +74,11 @@ const typeMappings = {
 /**
  * Создаёт контрол устройства.
  * @since 0.1.0
+ *
  **/
 function createControl(context, controlId, options) {
     const { deviceType, deviceId } = context;
-    const { type, isReadonly } = options;
+    const { type, changePolicy = ChangePolicies.Default } = options;
     const defaultValue = 'defaultValue' in options
         ? options['defaultValue']
         : void 0;
@@ -61,6 +101,7 @@ function createControl(context, controlId, options) {
      * Устанавливает новое значение, если оно отличается от существующего.
      * @param newValue Устанавливаемое значение.
      * @param preventEmit Предотвращает отправку значения в устройство.
+     *
      **/
     function setValue(newValue, preventEmit = false) {
         const oldValue = localValue;
@@ -102,16 +143,14 @@ function createControl(context, controlId, options) {
             return localValue;
         },
         set value(newValue) {
-            if (isReadonly) {
-                log.warning(`Value of '${deviceId}/${controlId}' is readonly`);
+            if (changePolicy === ChangePolicies.ReadOnly) {
+                log.warning(`A new value of '${deviceId}/${controlId}' has been rejected: control is readonly.`);
                 return;
             }
             setValue(newValue);
         },
-        valueReceived: valueReceived
-            .withoutRaise(),
-        valueChanged: valueChanged
-            .withoutRaise(),
+        onValueReceived: valueReceived.on,
+        onValueChanged: valueChanged.on,
     };
 }
 
@@ -141,6 +180,9 @@ function createContext(deviceType, deviceId, state) {
     };
     return context;
 }
+const extendWithReadonly = (changePolicy) => changePolicy && changePolicy !== ChangePolicies.Default
+    ? { readonly: changePolicy === ChangePolicies.Script || changePolicy === ChangePolicies.ReadOnly }
+    : {};
 function configureControls(deviceId, controls) {
     const device = getDevice(deviceId);
     if (!device)
@@ -154,8 +196,7 @@ function configureControls(deviceId, controls) {
             device.removeControl(controlId);
         device.addControl(controlId, assign({}, control, {
             value: control.defaultValue,
-            readonly: control.isReadonly,
-        }));
+        }, extendWithReadonly(control.changePolicy)));
     });
 }
 function configureContext(type, deviceId, controls, title) {
@@ -182,9 +223,10 @@ function configureContext(type, deviceId, controls, title) {
         if (type === 'virtual') {
             const cells = {};
             Object.keys(controls).forEach((key) => {
-                const cell = assign({}, controls[key], {
-                    value: controls[key]['defaultValue'],
-                }, controls[key]['isReadonly'] ? { readonly: true } : {});
+                const control = controls[key];
+                const cell = assign({}, control, {
+                    value: control['defaultValue'],
+                }, extendWithReadonly(control['changePolicy']));
                 cells[key] = cell;
             });
             global.defineVirtualDevice(deviceId, {
@@ -219,8 +261,8 @@ function createDevice(deviceType, deviceId, propDefs, props, options) {
         const controlId = controlDef.controlId ?? key;
         const control = createControl({ deviceType, deviceId, isReady: true }, controlId, {
             type: controlDef.type,
+            changePolicy: controlDef.changePolicy ?? ChangePolicies.Default,
             defaultValue: controlDef.defaultValue,
-            isReadonly: controlDef.isReadonly,
             forceDefault: controlDef.forceDefault,
             lazyInit: controlDef.lazyInit,
         });
@@ -322,4 +364,4 @@ function getDeviceSafe(deviceId, isReadyFunc = () => true) {
     };
 }
 
-export { defineVirtualDevice, defineWiredDevice, defineZigbeeDevice, getControlSafe, getDeviceSafe };
+export { ChangePolicies, defineVirtualDevice, defineWiredDevice, defineZigbeeDevice, getControlSafe, getDeviceSafe };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mirta",
   "description": "The powerful framework to write smart home automation scripts.",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "Unlicense",
   "keywords": [
     "mirta",
@@ -36,9 +36,9 @@
     "url": "https://pay.cloudtips.ru/p/58512cca"
   },
   "dependencies": {
-    "@mirta/basics": "0.1.1",
-    "@mirta/polyfills": "0.1.1",
-    "@mirta/globals": "0.1.1"
+    "@mirta/globals": "0.2.0",
+    "@mirta/basics": "0.2.0",
+    "@mirta/polyfills": "0.2.0"
   },
   "publishConfig": {
     "access": "public"