mirta 0.0.7 → 0.1.1

package/dist/index.d.mts

@@ -1,46 +1,407 @@
+import { Event } from '@mirta/basics';
 export * from '@mirta/basics';
 
+type DeviceType = 'wired' | 'virtual' | 'zigbee';
 /** Контекст устройства. */
 interface DeviceContext {
+    get deviceType(): DeviceType;
     /** Идентификатор устройства. */
-    get id(): string;
+    get deviceId(): string;
     /**
        * Признак готовности к работе,
        * значение меняется при смене статуса. */
     get isReady(): boolean;
 }
 type TrackCallback = (controlId: string, callback: (value: WbRules.MqttValue) => void) => void;
-/** Контекст плагина для привязки к устройству. */
-interface PluginContext {
-    device: DeviceContext;
-    track: TrackCallback;
+
+/**
+ * Определяет, имеет ли свойство строго заданное значение.
+ *
+ * @example
+ * ```ts
+ * type A = IsSpecified<{ value?: string }, 'value'> // A = false
+ * type B = IsSpecified<{ value: undefined }, 'value'> // B = false
+ * type C = IsSpecified<{ value: string }, 'value'> // C = true
+ * ```
+ * @since 0.1.0
+ */
+type IsSpecified<TObject, TKey extends keyof TObject> = TObject extends Record<TKey, infer TValue> ? (TValue extends undefined ? false : true) : false;
+/**
+ * На основе заданного свойства определяет, будет ли
+ * возвращаемый тип строгим.
+ *
+ * Используется, чтобы убрать неопределённость
+ * при наличии конкретного значения.
+ *
+ * Наиболее полно раскрывает себя в контексте вызова.
+ *
+ * @example
+ * ```ts
+ * interface Options {
+ *   defaultValue?: string
+ * }
+ *
+ * function useComponent<TOptions extends Options>(
+ *   _options?: TOptions
+ * ): StrictWhenSpecified<TOptions, 'defaultValue', string> {
+ *
+ *   return void 0 as never
+ *
+ * }
+ *
+ * // Тип результата - string | undefined
+ *
+ * const r1 = useComponent()
+ * const r2 = useComponent({ defaultValue: undefined })
+ *
+ * // Тип результата - string
+ *
+ * const r3 = useComponent({ defaultValue: '' })
+ * ```
+ * @since 0.1.0
+ **/
+type StrictWhenSpecified<TObject, TKey extends keyof TObject, TReturn> = IsSpecified<TObject, TKey> extends true ? TReturn : TReturn | undefined;
+/**
+ * Устанавливает указанное свойство в readonly при выполнении указанного условия.
+ * @since 0.1.0
+ **/
+type ReadonlyPropWhen<TObject, K extends keyof TObject, TCondition extends boolean | undefined> = TCondition extends true ? Omit<TObject, K> & {
+    +readonly [P in K]-?: TObject[P];
+} : TObject;
+/**
+ * Проверяет, что указанный тип объекта имеет хотя бы одно свойство заданного типа.
+ * Применяется для работы с дженериками.
+ *
+ * @example
+ * ```ts
+ * type A = { propA: { required: true }, propB: { required: false } }
+ * type Y = HasPropertyOfType<A, { required: true }> // Y = true
+ *
+ * type B = { propA: { required: false }, propB: { required: false } }
+ * type N = HasPropertyOfType<B, { required: true }> // N = false
+ * ```
+ * @since 0.1.0
+ **/
+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;
+
+type ValueEventHandler<TValue> = (newValue: TValue, oldValue: TValue) => void;
+interface Control<TValue> {
+    /** Актуальное значение контрола. */
+    value: TValue;
+    /** Событие, происходящее когда поступило новое значение. */
+    valueReceived: Event<ValueEventHandler<TValue>>;
+    /** Событие, происходящее когда значение изменилось. */
+    valueChanged: Event<ValueEventHandler<TValue>>;
 }
-/** Плагин для расширения функциональности устройства. */
-type DevicePlugin<TPlugin = unknown> = (context: PluginContext) => TPlugin;
+type MaybeReadonlyControl<TValue, TReadonly extends boolean | undefined> = ReadonlyPropWhen<Control<TValue>, 'value', TReadonly>;
 
-interface DeviceSetupOptions {
-    context: DeviceContext;
-    setControl: (controlId: string, definition: WbRules.ControlOptions) => void;
+/**
+ * Определяет соответствие между свойствами
+ * {@link ControlType.type} и {@link ControlType.defaultValue}.
+ *
+ **/
+interface ControlType<TControl, TValue> {
+    /** Тип контрола. */
+    type: TControl;
+    /** Значение по умолчанию. */
+    defaultValue?: TValue;
 }
 /**
- * Извлекает типы возвращаемых функциями в массиве значений
- * в виде пересечения.
+ * Служит механизмом безопасного преобразования типов контролов
+ * в конкретные типы значений.
+ **/
+type TypeMapper<K extends keyof WbRules.TypeMappings = keyof WbRules.TypeMappings> = K extends infer TControl ? ControlType<TControl, WbRules.TypeMappings[K]> : never;
+type VirtualTypeMapper<K extends keyof WbRules.TypeMappings = keyof WbRules.TypeMappings> = K extends infer TControl ? (ControlType<TControl, WbRules.TypeMappings[K]> & WbRules.ControlTypeExtension<TControl>) : never;
+interface BaseControlDef {
+    /** Идентификатор контрола. Если не указан, используется название свойства. */
+    controlId?: string;
+    /** Если `true`, то значение доступно только для чтения. */
+    isReadonly?: boolean;
+}
+/**
+ * Определения основных контролов.
+ * Расширяют возможные типы контролов поддержкой общих полей.
+ **/
+type ControlDef = Expand<TypeMapper & BaseControlDef>;
+/**
+ * Определения виртуальных контролов.
+ * Расширяют определения основных контролов поддержкой дополнительных полей,
+ * характерных только для виртуальных устройств.
+ **/
+type VirtualControlDef = Expand<VirtualTypeMapper & BaseControlDef & {
+    /** Имя, публикуемое в MQTT-топике */
+    title?: WbRules.Title;
+    /** Если включено, устанавливает значение по умолчанию при перезапуске. */
+    forceDefault?: boolean;
+    /** Если включено, не создаёт контрол в MQTT, пока ему не будет присвоено какое-либо значение. */
+    lazyInit?: boolean;
+    /** Порядок следования полей */
+    order?: number;
+}>;
+/** Набор контролов, не поддерживающий переопределение. */
+type Controls = Record<string, ControlDef>;
+/** Набор контролов с поддержкой переопределения. */
+type VirtualControls = Record<string, VirtualControlDef>;
+/**
+ * Обеспечивает строго контролируемую вариативность в зависимости
+ * от контекста вызова.
+ *
+ * Проверяет совместимость с прототипом `Controls`,
+ * предотвращая появление неучтённых свойств (например тех,
+ * что используются только для виртуальных устройств).
+ **/
+type StrictControls<TControls extends Controls> = TControls & Controls;
+/**
+ * Обеспечивает строго контролируемую вариативность в зависимости
+ * от контекста вызова.
+ *
+ * Проверяет совместимость с прототипом `VirtualControls`,
+ * предотвращая появление неучтённых свойств.
+ **/
+type StrictVirtualControls<TControls extends VirtualControls> = TControls & VirtualControls;
+/**
+ * Набор готовых к использованию контролов, передаётся в `setup()`
+ * при описании устройства в `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']>>;
+};
+/** Используется для извлечения типа значения из значения по умолчанию. */
+type InferDefaultType<TProp> = [TProp] extends [{
+    defaultValue: infer TDefault;
+}] ? TDefault extends (() => infer TReturn) ? TReturn : TDefault : TProp;
+/** Извлекает реальный тип свойства из его определения. */
+type InferPropType<TProp> = [TProp] extends [ObjectConstructor | {
+    type: ObjectConstructor;
+}] ? Record<string, unknown> : [TProp] extends [BooleanConstructor | {
+    type: BooleanConstructor;
+}] ? boolean : [TProp] extends [NumberConstructor | {
+    type: NumberConstructor;
+}] ? number : [TProp] extends [StringConstructor | {
+    type: StringConstructor;
+}] ? string : [TProp] extends [DateConstructor | {
+    type: DateConstructor;
+}] ? Date : [TProp] extends [PropType<infer TValue> | {
+    type: PropType<infer TValue>;
+} | undefined] ? TValue : InferDefaultType<TProp>;
+/** Обязательные ключи свойств - потребуют их явного указания при вызове useDevice(). */
+type RequiredKeys<TProps> = {
+    [K in keyof TProps]: TProps[K] extends {
+        isRequired: true;
+    } ? TProps[K] extends {
+        defaultValue: undefined | (() => undefined);
+    } ? never : K : never;
+}[keyof TProps];
+/**
+ * Опциональные ключи свойств - указываются по необходимости.
  *
- * */
-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];
+ * Рекомендуется использовать совместно с параметром {@link PropMetadata.defaultValue}.
+ */
+type OptionalKeys<TProps> = Exclude<keyof TProps, RequiredKeys<TProps>>;
+type RequiredSetupKeys<TProps> = {
+    [K in keyof TProps]: TProps[K] extends {
+        isRequired: true;
+    } | {
+        defaultValue: unknown;
+    } ? TProps[K] extends {
+        defaultValue: undefined | (() => undefined);
+    } ? never : K : never;
+}[keyof TProps];
+type OptionalSetupKeys<TProps> = Exclude<keyof TProps, RequiredKeys<TProps>>;
+/**
+ * Параметры устройства для уточнения стартовой конфигурации.
+ *
+ * Например, можно передать значения низкого и критического уровня заряда, определяя контрол батареи.
+ */
+type Props<TProps> = {
+    [K in keyof Pick<TProps, RequiredKeys<TProps>>]: InferPropType<TProps[K]>;
+} & {
+    [K in keyof Pick<TProps, OptionalKeys<TProps>>]?: InferPropType<TProps[K]>;
+};
+/**
+ * В отличие от {@link Props}, формирует строгое значение свойства
+ * при заданном параметре {@link PropMetadata.defaultValue}.
+ *
+ **/
+type SetupProps<TProps> = {
+    [K in keyof Pick<TProps, RequiredSetupKeys<TProps>>]: Readonly<InferPropType<TProps[K]>>;
+} & {
+    [K in keyof Pick<TProps, OptionalSetupKeys<TProps>>]?: Readonly<InferPropType<TProps[K]>>;
+};
+type PropMethod<TProp, TConstructor = unknown> = [TProp] extends [
+    ((...args: unknown[]) => unknown) | undefined
+] ? {
+    new (): TConstructor;
+    (): TProp;
+    readonly prototype: TConstructor;
+} : never;
+type PropConstructor<TProp = unknown> = (new (...args: unknown[]) => TProp & {}) | (() => TProp) | PropMethod<TProp>;
+/**
+ * Тип параметра контрола.
+ * @example
+ * ```ts
+ * const useDevice = defineWiredDevice({
+ *   props: {
+ *     // Неявное использование PropType для извлечения типа.
+ *     count: Number
+ *   }
+ * })
+ * ```
+ * @example
+ * ```ts
+ * interface BatteryProps {
+ *   lowLevel: number
+ *   criticalLevel: number
+ * }
+ *
+ * const useDevice = defineWiredDevice({
+ *   props: {
+ *     // Явное использование PropType для извлечения типа.
+ *     battery: Object as PropType<BatteryProps>
+ *   }
+ * })
+ * ```
+ **/
+type PropType<TProp> = PropConstructor<TProp> | (PropConstructor<TProp>)[];
+/**
+ * Метаданные свойства.
+ *
+ * Применяются для уточнения параметров свойства.
+ *
+ * @example
+ * Делает свойство обязательным.
+ *
+ * ```ts
+ * const useDevice = defineWiredDevice({
+ *   props: {
+ *     count: { type: Number, isRequired: true }
+ *   }
+ * })
+ *
+ * const devie = useDevice('my_device_id', {
+ *   count: 0
+ * })
+ * ```
+ * @example
+ * Делает свойство опциональным, но строгим - предоставляет значение по умолчанию.
+ *
+ * ```ts
+ * const useDevice = defineWiredDevice({
+ *   props: {
+ *     count: { type: Number, defaultValue: 0 }
+ *   }
+ * })
+ *
+ * const device = useDevice('my_device_id')
+ * ```
+ **/
+interface PropMetadata<TProp> {
+    /** Тип свойства. */
+    type: TProp;
+    /** Признак обязательности. */
+    isRequired?: boolean;
+    /** Значение по умолчанию. */
+    defaultValue?: TProp | (() => TProp);
 }
-type DeviceWithPlugins<TPlugins extends DevicePlugin[]> = IntersectReturnTypes<[...TPlugins]>;
+/**
+ * Обеспечивает поддержку одновременно компактной и расширенной записи
+ * определений начальных настроек устройства.
+ *
+ * @example
+ * ```ts
+ * const useDevice = defineWiredDevice({
+ *   props: {
+ *     // Компактная форма.
+ *     count: Number,
+ *     // Расширенная форма.
+ *     checkInterval: { type: Number, defaultValue: 100 }
+ *   }
+ * })
+ * ```
+ */
+type Prop<TProp> = PropMetadata<TProp> | PropType<TProp>;
+type PropsDefinition<TProps = Record<string, unknown>> = {
+    [K in keyof TProps]: Prop<TProps[K]>;
+};
+/** Определение проводного устройства. */
+interface WiredDeviceOptions<TProps, TControls extends Controls, TResult> {
+    setup: (options: {
+        props: Readonly<Expand<SetupProps<TProps>>>;
+        controls: CreatedControls<TControls>;
+    }) => TResult;
+    props?: TProps;
+    /** Контролы проводного устройства. */
+    controls: StrictControls<TControls>;
+}
+/** Определение виртуального устройства. */
+interface VirtualDeviceOptions<TProps, TControls extends VirtualControls, TResult> {
+    setup: (options: {
+        props: Readonly<Expand<SetupProps<TProps>>>;
+        controls: CreatedControls<TControls>;
+    }) => TResult;
+    props?: TProps;
+    /** Контролы виртуального устройства. */
+    controls: StrictVirtualControls<TControls>;
+}
+/** Определение Zigbee-устройства. */
+interface ZigbeeDeviceOptions<TProps, TControls extends VirtualControls, TResult> {
+    setup: (options: {
+        props: Readonly<Expand<SetupProps<TProps>>>;
+        controls: CreatedControls<TControls>;
+    }) => TResult;
+    props?: TProps;
+    /** Контролы Zigbee-устройства. */
+    controls: StrictVirtualControls<TControls>;
+}
+/**
+ * Описывает конфигурацию устройства в зависимости от его типа - проводное, виртуальное или Zigbee.
+ *
+ * @template TDeviceType Тип устройства (проводное, виртуальное, беспроводное).
+ * @template TProps Тип списка с определениями входящих параметров.
+ * @template TControls Тип списка с определениями контролов устройства.
+ * @template TResult Итоговый тип устройства.
+ */
+type DeviceOptions<TDeviceType extends DeviceType, TProps, TControls extends Controls | VirtualControls, TResult> = TDeviceType extends 'wired' ? WiredDeviceOptions<TProps, TControls, TResult> : (TDeviceType extends 'virtual' ? VirtualDeviceOptions<TProps, TControls, TResult> : (TDeviceType extends 'zigbee' ? ZigbeeDeviceOptions<TProps, TControls, TResult> : never));
+/**
+ * Наделяет результирующее устройство возможностью передачи своего контекста.
+ *
+ * Используется во вспомогательных функциях, избавляя от необходимости прописывать идентификаторы вручную.
+ *
+ **/
 interface DeviceWithContext {
-    /** Контекст устройства. */
-    context: DeviceContext;
-    /** Метод для отслеживания изменений в топиках. */
-    track: (controlId: string, callback: (newValue: WbRules.MqttValue) => void) => void;
+    /** Контекст устройства - ключевая информация. */
+    context: {
+        /** Идентификатор устройства. */
+        deviceId: string;
+        /** Признак готовности к работе. */
+        isReady: boolean;
+    };
+}
+/** Итоговый тип устройства. */
+type Device<TDefinition> = TDefinition & DeviceWithContext;
+type UseDeviceFunc<TProps extends object, TDevice> = HasPropertyOfType<TProps, {
+    isRequired: true;
+}> extends true ? (deviceId: string, props: Expand<Props<TProps>>) => Device<TDevice> : (deviceId: string, props?: Expand<Props<TProps>>) => Device<TDevice>;
+/**
+ * Определяет структуру проводного устройства.
+ * @since 0.1.0
+ **/
+declare function defineWiredDevice<TDeviceType extends DeviceType, TProps extends PropsDefinition, TControls extends Controls | VirtualControls, TDevice extends object>(options: DeviceOptions<TDeviceType, TProps, TControls, TDevice>): UseDeviceFunc<TProps, TDevice>;
+interface WithIntegratedTitleProp {
+    title?: PropMetadata<PropType<WbRules.Title>> | PropType<WbRules.Title>;
 }
-type Device<TPlugins extends DevicePlugin[]> = DeviceWithContext & DeviceWithPlugins<TPlugins>;
-declare function defineZigbeeDevice<TPlugins extends DevicePlugin[]>(deviceId: string, options?: DefineDeviceOptions<TPlugins>): Device<TPlugins>;
+/**
+ * Определяет структуру виртуального устройства.
+ * @since 0.1.0
+ **/
+declare function defineVirtualDevice<TDeviceType extends DeviceType, TProps extends PropsDefinition, TControls extends Controls | VirtualControls, TDevice extends object>(options: DeviceOptions<TDeviceType, TProps & WithIntegratedTitleProp, TControls, TDevice>): UseDeviceFunc<TProps & WithIntegratedTitleProp, TDevice>;
+/**
+ * Определяет структуру zigbee-устройства.
+ * @since 0.1.0
+ **/
+declare function defineZigbeeDevice<TDeviceType extends DeviceType, TProps extends PropsDefinition, TControls extends Controls | VirtualControls, TDevice extends object>(options: DeviceOptions<TDeviceType, TProps, TControls, TDevice>): UseDeviceFunc<TProps, TDevice>;
 
 /**
  * Позволяет получить объект для работы с указанным устройством.
@@ -70,5 +431,5 @@ declare function getControlSafe(context: DeviceContext, controlId: string): Cont
  **/
 declare function getControlSafe(deviceId: string, controlId: string, isReadyFunc: () => boolean): ControlSafe;
 
-export { defineZigbeeDevice, getControlSafe, getDeviceSafe };
-export type { ControlSafe, DeviceContext, DevicePlugin, PluginContext, TrackCallback };
+export { defineVirtualDevice, defineWiredDevice, defineZigbeeDevice, getControlSafe, getDeviceSafe };
+export type { ControlSafe, DeviceContext, DeviceType, PropType, TrackCallback };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { useEvent, isFunction } from '@mirta/basics';
 export * from '@mirta/basics';
 import '@mirta/polyfills';
 
@@ -15,21 +16,123 @@ function getControlSafe(context, controlId, isReadyFunc = () => true) {
             }
             else {
                 return context.isReady
-                    ? control = getControl(`${context.id}/${controlId}`)
+                    ? control = getControl(`${context.deviceId}/${controlId}`)
                     : undefined;
             }
         },
     };
 }
 
+const typeMappings = {
+    'text': 'string',
+    'value': 'number',
+    'switch': 'boolean',
+    'pushbutton': 'boolean',
+    'rgb': 'string',
+    'range': 'number',
+    'alarm': 'boolean',
+};
+/**
+ * Создаёт контрол устройства.
+ * @since 0.1.0
+ **/
+function createControl(context, controlId, options) {
+    const { deviceType, deviceId } = context;
+    const { type, isReadonly } = options;
+    const defaultValue = 'defaultValue' in options
+        ? options['defaultValue']
+        : void 0;
+    const control = getControlSafe(context, controlId);
+    /** Отправляет новое значение в контрол устройства. */
+    const emitValue = (newValue) => {
+        if (newValue === void 0)
+            return;
+        if (deviceType === 'zigbee') {
+            publish(`zigbee2mqtt/${deviceId}/set`, JSON.stringify({ [controlId]: newValue }));
+        }
+        else {
+            control.safe?.setValue(newValue);
+        }
+    };
+    const valueReceived = useEvent();
+    const valueChanged = useEvent();
+    let localValue;
+    /**
+     * Устанавливает новое значение, если оно отличается от существующего.
+     * @param newValue Устанавливаемое значение.
+     * @param preventEmit Предотвращает отправку значения в устройство.
+     **/
+    function setValue(newValue, preventEmit = false) {
+        const oldValue = localValue;
+        valueReceived.raise(newValue, oldValue);
+        if (oldValue === newValue)
+            return;
+        localValue = newValue;
+        if (!preventEmit)
+            emitValue(newValue);
+        valueChanged.raise(newValue, oldValue);
+    }
+    trackMqtt(`/devices/${deviceId}/controls/${controlId}`, (payload) => {
+        const incomingType = typeof payload.value;
+        const expectingType = typeMappings[type];
+        if (incomingType === 'string' && expectingType === 'number') {
+            const value = Number(payload.value);
+            if (isNaN(value)) {
+                log.error(`Value ignored: control '${deviceId}/${controlId}' expects number, but Number(value) is NaN.`);
+                return;
+            }
+            setValue(value, true);
+        }
+        else {
+            if (incomingType !== expectingType) {
+                log.error(`Value ignored: control '${deviceId}/${controlId}' expects type '${expectingType}', but received '${incomingType}'`);
+                return;
+            }
+            setValue(payload.value, true);
+        }
+    });
+    return {
+        get value() {
+            if (localValue === undefined) {
+                if (options.forceDefault)
+                    return localValue = defaultValue;
+                if (!options.lazyInit)
+                    return localValue ??= control.safe?.getValue();
+            }
+            return localValue;
+        },
+        set value(newValue) {
+            if (isReadonly) {
+                log.warning(`Value of '${deviceId}/${controlId}' is readonly`);
+                return;
+            }
+            setValue(newValue);
+        },
+        valueReceived: valueReceived
+            .withoutRaise(),
+        valueChanged: valueChanged
+            .withoutRaise(),
+    };
+}
+
 const { assign } = Object;
-if ((process.env.NODE_ENV === 'test')) {
+if ((process.env.NODE_ENV === 'test'))
     module.static = {};
-}
-const configured = (module.static.configured ??= {});
-function createContext(deviceId, state) {
+/**
+ * Содержит список проинициализированных устройств,
+ * а также их статус готовности к работе.
+ *
+ * Например, если какой-либо из скриптов создал виртуальное устройство,
+ * другие скрипты не должны пытаться создать его повторно.
+ *
+ **/
+const alreadyConfigured = (module.static.configured ??= {});
+function createContext(deviceType, deviceId, state) {
     const context = {
-        get id() {
+        get deviceType() {
+            return deviceType;
+        },
+        get deviceId() {
             return deviceId;
         },
         get isReady() {
@@ -38,70 +141,168 @@ function createContext(deviceId, state) {
     };
     return context;
 }
-function configureContext(deviceId, setup) {
-    // Каждый юнит-тест должен проходить полный цикл построения.
+function configureControls(deviceId, controls) {
+    const device = getDevice(deviceId);
+    if (!device)
+        return;
+    Object.keys(controls).forEach((key) => {
+        const control = controls[key];
+        const controlId = control.controlId ?? key;
+        if ((process.env.NODE_ENV !== 'production'))
+            log.debug(`Replacing the control '${controlId}' on '${deviceId}'`);
+        if (device.isControlExists(controlId))
+            device.removeControl(controlId);
+        device.addControl(controlId, assign({}, control, {
+            value: control.defaultValue,
+            readonly: control.isReadonly,
+        }));
+    });
+}
+function configureContext(type, deviceId, controls, title) {
     if ((process.env.NODE_ENV === 'test'))
-        configured[deviceId] = undefined;
-    if (configured[deviceId])
-        return createContext(deviceId, configured[deviceId]);
-    const state = configured[deviceId] = {
+        alreadyConfigured[deviceId] = undefined;
+    if (alreadyConfigured[deviceId])
+        return createContext(type, deviceId, alreadyConfigured[deviceId]);
+    const state = alreadyConfigured[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);
-                },
-            });
+    const context = createContext(type, deviceId, state);
+    if (state.isReady || !state.isConfigurable)
+        return;
+    if (type === 'zigbee') {
+        trackMqtt(`zigbee2mqtt/${deviceId}`, () => {
+            if (state.isReady || !state.isConfigurable)
+                return;
+            configureControls(deviceId, controls);
             state.isReady = true;
+        });
+    }
+    else {
+        if (type === 'virtual') {
+            const cells = {};
+            Object.keys(controls).forEach((key) => {
+                const cell = assign({}, controls[key], {
+                    value: controls[key]['defaultValue'],
+                }, controls[key]['isReadonly'] ? { readonly: true } : {});
+                cells[key] = cell;
+            });
+            global.defineVirtualDevice(deviceId, {
+                title: title ?? 'Untitled Virtual Device',
+                cells,
+            });
         }
-        else {
-            state.isConfigurable = false;
-            if ((process.env.NODE_ENV !== 'production'))
-                log.warning(`Can't configure '${deviceId}' as a zigbee-device`);
-        }
-    });
+        state.isReady = true;
+    }
     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);
+function getValueOrDefault(value, defaultValue) {
+    return value ?? (isFunction(defaultValue)
+        ? defaultValue()
+        : defaultValue);
+}
+function createDevice(deviceType, deviceId, propDefs, props, options) {
+    const controlDefs = options.controls;
+    const setupProps = {};
+    const controls = {};
+    Object.keys(propDefs).forEach((key) => {
+        // Устанавливает значение свойства по умолчанию,
+        // если не указано иного.
+        //
+        setupProps[key] = getValueOrDefault(props[key], propDefs[key]['defaultValue']);
+    });
+    const context = configureContext(deviceType, deviceId, controlDefs, deviceType === 'virtual'
+        ? setupProps['title']
+        : '');
+    Object.keys(controlDefs).forEach((key) => {
+        const controlDef = controlDefs[key];
+        const controlId = controlDef.controlId ?? key;
+        const control = createControl({ deviceType, deviceId, isReady: true }, controlId, {
+            type: controlDef.type,
+            defaultValue: controlDef.defaultValue,
+            isReadonly: controlDef.isReadonly,
+            forceDefault: controlDef.forceDefault,
+            lazyInit: controlDef.lazyInit,
         });
-    }
-    const device = {
-        context,
-        track,
+        controls[key] = control;
+    });
+    const device = options.setup({
+        props: setupProps,
+        controls: controls,
+    });
+    return assign(device, { context });
+}
+/**
+ * В пределах каждого скрипта wb-rules (точки входа),
+ * содержит синглтоны построенных в нём устройств соответственно
+ * переданному в `useDevice()` идентификатору.
+ *
+ */
+const devices = {};
+function defineDevice(type, options) {
+    return (deviceId, props) => {
+        // Девайс должен проходить полный цикл построения в юнит-тестах.
+        if ((process.env.NODE_ENV === 'test'))
+            devices[deviceId] = void 0;
+        return (
+        // Строится единожды на скрипт, далее берётся из кэша.
+        // При повторном вызове переданные свойства будут проигнорированы.
+        devices[deviceId] ??= createDevice(type, deviceId, options.props ?? {}, props ?? {}, options));
     };
-    const plugins = options.plugins;
-    if (plugins) {
-        const pluginContext = {
-            device: context,
-            track,
-        };
-        options.plugins?.forEach((plugin) => {
-            assign(device, plugin(pluginContext));
-        });
-    }
-    return device;
+}
+/**
+ * Определяет структуру проводного устройства.
+ * @since 0.1.0
+ **/
+function defineWiredDevice(options) {
+    return defineDevice('wired', options);
+}
+let virtualPerScript = 0;
+/**
+ * Обеспечивает нумерацию безымянных виртуальных
+ * устройств в пределах скрипта.
+ *
+ **/
+const getNextVirtualNumber = () => virtualPerScript += 1;
+/**
+ * Использует {@link getNextVirtualNumber} и возвращает
+ * номер устройства, дополненный ведущими нулями.
+ *
+ * @returns Дополненная ведущими нулями строка с номером.
+ *
+ **/
+function getNextVirtualNumberPadded() {
+    const nextNumber = String(getNextVirtualNumber());
+    if (nextNumber.length < 2)
+        return '00' + nextNumber;
+    if (nextNumber.length < 3)
+        return '0' + nextNumber;
+    return nextNumber;
+}
+/**
+ * Определяет структуру виртуального устройства.
+ * @since 0.1.0
+ **/
+function defineVirtualDevice(options) {
+    // Виртуальные устройства определяют заголовок по умолчанию,
+    // если он не передан во входящих параметрах.
+    //
+    options.props = assign({}, {
+        title: {
+            type: Object, defaultValue: () => {
+                const match = /\/([^/]+?)(?:\.js)?$/.exec(__filename);
+                return `Virtual #${getNextVirtualNumberPadded()}${match?.[1] ? ` at '${match[1]}'` : ''}`;
+            },
+        },
+    }, options.props);
+    return defineDevice('virtual', options);
+}
+/**
+ * Определяет структуру zigbee-устройства.
+ * @since 0.1.0
+ **/
+function defineZigbeeDevice(options) {
+    return defineDevice('zigbee', options);
 }
 
 /**
@@ -121,4 +322,4 @@ function getDeviceSafe(deviceId, isReadyFunc = () => true) {
     };
 }
 
-export { defineZigbeeDevice, getControlSafe, getDeviceSafe };
+export { 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.0.7",
+  "version": "0.1.1",
   "license": "Unlicense",
   "keywords": [
     "mirta",
@@ -36,9 +36,9 @@
     "url": "https://pay.cloudtips.ru/p/58512cca"
   },
   "dependencies": {
-    "@mirta/basics": "0.0.7",
-    "@mirta/globals": "0.0.7",
-    "@mirta/polyfills": "0.0.7"
+    "@mirta/basics": "0.1.1",
+    "@mirta/polyfills": "0.1.1",
+    "@mirta/globals": "0.1.1"
   },
   "publishConfig": {
     "access": "public"