mirta 0.0.1

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,7 @@
+# Mirta
+
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta/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/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/mirta?style=flat-square)](https://npmjs.com/package/mirta)
+
+Device helpers and wrappers, focused on developing your own wb-rules.

package/README.ru.md

@@ -0,0 +1,7 @@
+# Mirta
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta/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/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/mirta?style=flat-square)](https://npmjs.com/package/mirta)
+
+Инструменты и обёртки для поддержки работы с устройствами, призванные помочь в разработке ваших собственных правил wb-rules. 

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+export * from '@mirta/basics';
+
+/** Контекст устройства. */
+interface DeviceContext {
+    /** Идентификатор устройства. */
+    get id(): string;
+    /**
+       * Признак готовности к работе,
+       * значение меняется при смене статуса. */
+    get isReady(): boolean;
+}
+type TrackCallback = (controlId: string, callback: (value: WbRules.MqttValue) => void) => void;
+/** Контекст плагина для привязки к устройству. */
+interface PluginContext {
+    device: DeviceContext;
+    track: TrackCallback;
+}
+/** Плагин для расширения функциональности устройства. */
+type DevicePlugin<TPlugin = unknown> = (context: PluginContext) => TPlugin;
+
+interface DeviceSetupOptions {
+    context: DeviceContext;
+    setControl: (controlId: string, definition: WbRules.ControlOptions) => void;
+}
+/**
+ * Извлекает типы возвращаемых функциями в массиве значений
+ * в виде пересечения.
+ *
+ * */
+type IntersectReturnTypes<TArray> = TArray extends [(...args: unknown[]) => infer TReturn, ...infer TRest] ? TReturn & IntersectReturnTypes<TRest> : object;
+interface DefineDeviceOptions<TPlugins extends DevicePlugin[]> {
+    setup?: (options: DeviceSetupOptions) => void;
+    plugins?: [...TPlugins];
+}
+type DeviceWithPlugins<TPlugins extends DevicePlugin[]> = IntersectReturnTypes<[...TPlugins]>;
+interface DeviceWithContext {
+    /** Контекст устройства. */
+    context: DeviceContext;
+    /** Метод для отслеживания изменений в топиках. */
+    track: (controlId: string, callback: (newValue: WbRules.MqttValue) => void) => void;
+}
+type Device<TPlugins extends DevicePlugin[]> = DeviceWithContext & DeviceWithPlugins<TPlugins>;
+declare function defineZigbeeDevice<TPlugins extends DevicePlugin[]>(deviceId: string, options?: DefineDeviceOptions<TPlugins>): Device<TPlugins>;
+
+/**
+ * Позволяет получить объект для работы с указанным устройством.
+ * @param deviceId Идентификатор устройства.
+ *
+ */
+declare function getDeviceSafe(deviceId: string, isReadyFunc?: () => boolean): {
+    /** Возвращает существующий объект или пытается найти, если его ещё нет. */
+    readonly safe: WbRules.Device | undefined;
+};
+
+interface ControlSafe {
+    safe: WbRules.Control | undefined;
+}
+/**
+ * Позволяет получить объект для работы с указанным контролом устройства.
+ * @param context Контекст устройства, полученный из функций `tryConfigure`.
+ * @param controlId Идентификатор контрола.
+ *
+ **/
+declare function getControlSafe(context: DeviceContext, controlId: string): ControlSafe;
+/**
+ * Позволяет получить объект для работы с указанным контролом устройства.
+ * @param deviceId Идентификатор устройства.
+ * @param controlId Идентификатор контрола.
+ *
+ **/
+declare function getControlSafe(deviceId: string, controlId: string, isReadyFunc: () => boolean): ControlSafe;
+
+export { defineZigbeeDevice, getControlSafe, getDeviceSafe };
+export type { ControlSafe, DeviceContext, DevicePlugin, PluginContext, TrackCallback };

package/dist/index.mjs

@@ -0,0 +1,124 @@
+export * from '@mirta/basics';
+import '@mirta/polyfills';
+
+function getControlSafe(context, controlId, isReadyFunc = () => true) {
+    let control;
+    return {
+        /** Возвращает существующий объект или пытается найти, если его ещё нет. */
+        get safe() {
+            if (control)
+                return control;
+            if (typeof context === 'string') {
+                return isReadyFunc()
+                    ? control = getControl(`${context}/${controlId}`)
+                    : undefined;
+            }
+            else {
+                return context.isReady
+                    ? control = getControl(`${context.id}/${controlId}`)
+                    : undefined;
+            }
+        },
+    };
+}
+
+const { assign } = Object;
+if ((process.env.NODE_ENV === 'test')) {
+    module.static = {};
+}
+const configured = (module.static.configured ??= {});
+function createContext(deviceId, state) {
+    const context = {
+        get id() {
+            return deviceId;
+        },
+        get isReady() {
+            return state.isReady;
+        },
+    };
+    return context;
+}
+function configureContext(deviceId, setup) {
+    // Каждый юнит-тест должен проходить полный цикл построения.
+    if ((process.env.NODE_ENV === 'test'))
+        configured[deviceId] = undefined;
+    if (configured[deviceId])
+        return createContext(deviceId, configured[deviceId]);
+    const state = configured[deviceId] = {
+        isReady: false,
+        isConfigurable: true,
+    };
+    const context = createContext(deviceId, state);
+    trackMqtt(`zigbee2mqtt/${deviceId}`, () => {
+        // Предотвращает проверку каждого сообщения от zigbee2mqtt
+        if (state.isReady || !state.isConfigurable)
+            return;
+        const device = getDevice(deviceId);
+        if (setup && device?.isVirtual()) {
+            setup({
+                context,
+                setControl(controlId, description) {
+                    if (device.isControlExists(controlId))
+                        device.removeControl(controlId);
+                    if ((process.env.NODE_ENV !== 'production'))
+                        log.debug(`Replacing the control '${controlId}' on '${deviceId}'`);
+                    device.addControl(controlId, description);
+                },
+            });
+            state.isReady = true;
+        }
+        else {
+            state.isConfigurable = false;
+            if ((process.env.NODE_ENV !== 'production'))
+                log.warning(`Can't configure '${deviceId}' as a zigbee-device`);
+        }
+    });
+    return context;
+}
+function defineZigbeeDevice(deviceId, options = {}) {
+    const context = configureContext(deviceId, options.setup);
+    const lastSeen = getControlSafe(context, 'last_seen');
+    const startupStamp = lastSeen.safe?.getValue();
+    function track(controlId, callback) {
+        trackMqtt(`/devices/${deviceId}/controls/${controlId}`, (payload) => {
+            const stamp = lastSeen.safe?.getValue();
+            if (stamp === startupStamp)
+                return;
+            callback(payload.value);
+        });
+    }
+    const device = {
+        context,
+        track,
+    };
+    const plugins = options.plugins;
+    if (plugins) {
+        const pluginContext = {
+            device: context,
+            track,
+        };
+        options.plugins?.forEach((plugin) => {
+            assign(device, plugin(pluginContext));
+        });
+    }
+    return device;
+}
+
+/**
+ * Позволяет получить объект для работы с указанным устройством.
+ * @param deviceId Идентификатор устройства.
+ *
+ */
+function getDeviceSafe(deviceId, isReadyFunc = () => true) {
+    let device;
+    return {
+        /** Возвращает существующий объект или пытается найти, если его ещё нет. */
+        get safe() {
+            return device ?? (isReadyFunc()
+                ? device = getDevice(deviceId)
+                : undefined);
+        },
+    };
+}
+
+export { defineZigbeeDevice, getControlSafe, getDeviceSafe };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mirta",
+  "version": "0.0.1",
+  "license": "Unlicense",
+  "keywords": [
+    "mirta",
+    "wb-rules"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "types",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "homepage": "https://github.com/wb-mirta/core/tree/latest/packages/mirta#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wb-mirta/core.git",
+    "directory": "packages/mirta"
+  },
+  "bugs": {
+    "url": "https://github.com/wb-mirta/core/issues"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://pay.cloudtips.ru/p/58512cca"
+  },
+  "dependencies": {
+    "@mirta/basics": "0.0.1",
+    "@mirta/globals": "0.0.1",
+    "@mirta/polyfills": "0.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist build",
+    "build": "pnpm clean && rollup -c ../../rollup.config.mjs"
+  }
+}