homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/featureoptions.js

@@ -1,480 +0,0 @@
-/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
- *
- * featureoptions.ts: Hierarchical feature option capabilities for use in plugins and applications.
- */
-/**
- * FeatureOptions provides a hierarchical feature option system for plugins and applications.
- *
- * Supports global, controller, and device-level configuration, value-centric feature options, grouping, and category management.
- *
- * @example
- *
- * ```ts
- * // Define categories and options.
- * const categories = [
- *
- *   { name: "motion", description: "Motion Options" },
- *   { name: "audio", description: "Audio Options" }
- * ];
- *
- * const options = {
- *
- *   motion: [
- *     { name: "detect", default: true, description: "Enable motion detection." }
- *   ],
- *
- *   audio: [
- *     { name: "volume", default: false, defaultValue: 50, description: "Audio volume." }
- *   ]
- * };
- *
- * // Instantiate FeatureOptions.
- * const featureOpts = new FeatureOptions(categories, options, ["Enable.motion.detect"]);
- *
- * // Check if a feature is enabled.
- * const motionEnabled = featureOpts.test("motion.detect");
- *
- * // Get a value-centric feature option.
- * const volume = featureOpts.value("audio.volume");
- * ```
- *
- * @see FeatureOptionEntry
- * @see FeatureCategoryEntry
- * @see OptionScope
- */
-export class FeatureOptions {
-    /**
-     * Default return value for unknown options (defaults to false).
-     */
-    defaultReturnValue;
-    _categories;
-    _configuredOptions;
-    _groups;
-    _options;
-    configLookup;
-    defaults;
-    valueOptions;
-    /**
-     * Create a new FeatureOptions instance.
-     *
-     * @param categories        - Array of feature option categories.
-     * @param options           - Dictionary mapping category names to arrays of feature options.
-     * @param configuredOptions - Optional. Array of currently configured option strings.
-     *
-     * @example
-     *
-     * ```ts
-     * const featureOpts = new FeatureOptions(categories, options, ["Enable.motion.detect"]);
-     * ```
-     */
-    constructor(categories, options, configuredOptions = []) {
-        // Initialize our defaults.
-        this._categories = [];
-        this._configuredOptions = [];
-        this._groups = {};
-        this._options = {};
-        this.configLookup = new Map();
-        this.defaultReturnValue = false;
-        this.defaults = {};
-        this.valueOptions = {};
-        this.categories = categories;
-        this.configuredOptions = configuredOptions;
-        this.options = options;
-    }
-    /**
-     * Return a Bootstrap-specific color reference depending on the scope of a given feature option.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns a Bootstrap color utility class associated with each scope level. `text-info` denotes an entry that's been modified at that scope level, while
-     * `text-success` and `text-warning` denote options that were defined at higher levels in the scope hierarchy - controller and global, respectively.
-     */
-    color(option, device, controller) {
-        switch (this.scope(option, device, controller)) {
-            case "device":
-                return "text-info";
-            case "controller":
-                return "text-success";
-            case "global":
-                return device ? "text-warning" : "text-info";
-            default:
-                return "";
-        }
-    }
-    /**
-     * Return the default value for an option.
-     *
-     * @param option        - Feature option to check.
-     *
-     * @returns Returns true or false, depending on the option default.
-     */
-    defaultValue(option) {
-        // If it's unknown to us, return the default return value.
-        return this.defaults[option.toLowerCase()] ?? this.defaultReturnValue;
-    }
-    /**
-     * Return whether the option explicitly exists in the list of configured options.
-     *
-     * @param option        - Feature option to check.
-     * @param id            - Optional device or controller scope identifier to check.
-     *
-     * @returns Returns true if the option has been explicitly configured, false otherwise.
-     */
-    exists(option, id) {
-        return this.configLookup.has(option.toLowerCase() + (id ? "." + id.toLowerCase() : ""));
-    }
-    /**
-     * Return a fully formed feature option string.
-     *
-     * @param category      - Feature option category entry or category name string.
-     * @param option        - Feature option entry of option name string.
-     *
-     * @returns Returns a fully formed feature option in the form of `category.option`.
-     */
-    expandOption(category, option) {
-        const categoryName = (typeof category === "string") ? category : category.name;
-        const optionName = (typeof option === "string") ? option : option.name;
-        if (!categoryName.length) {
-            return "";
-        }
-        return (!optionName.length) ? categoryName : categoryName + "." + optionName;
-    }
-    /**
-     * Parse a floating point feature option value.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns the value of a value-centric option as a floating point number, `undefined` if it doesn't exist or couldn't be parsed, and `null` if disabled.
-     */
-    getFloat(option, device, controller) {
-        // Parse the number and return the value.
-        return this.parseOptionNumeric(this.value(option, device, controller), parseFloat);
-    }
-    /**
-     * Parse an integer feature option value.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns the value of a value-centric option as an integer, `undefined` if it doesn't exist or couldn't be parsed, and `null` if disabled.
-     */
-    getInteger(option, device, controller) {
-        // Parse the number and return the value.
-        return this.parseOptionNumeric(this.value(option, device, controller), parseInt);
-    }
-    /**
-     * Return whether an option has been set in either the device or controller scope context.
-     *
-     * @param option        - Feature option to check.
-     *
-     * @returns Returns true if the option is set at the device or controller level and false otherwise.
-     */
-    isScopeDevice(option, device) {
-        return this.exists(option, device);
-    }
-    /**
-     * Return whether an option has been set in the global scope context.
-     *
-     * @param option        - Feature option to check.
-     *
-     * @returns Returns true if the option is set globally and false otherwise.
-     */
-    isScopeGlobal(option) {
-        return this.exists(option);
-    }
-    /**
-     * Return whether an option is value-centric or not.
-     *
-     * @param option        - Feature option entry or string to check.
-     *
-     * @returns Returns true if it is a value-centric option and false otherwise.
-     */
-    isValue(option) {
-        if (!option) {
-            return false;
-        }
-        return option.toLowerCase() in this.valueOptions;
-    }
-    /**
-     * Return the scope hierarchy location of an option.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns an object containing the location in the scope hierarchy of an `option` as well as the current value associated with the option.
-     */
-    scope(option, device, controller) {
-        return this.optionInfo(option, device, controller).scope;
-    }
-    /**
-     * Return the current state of a feature option, traversing the scope hierarchy.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns true if the option is enabled, and false otherwise.
-     */
-    test(option, device, controller) {
-        return this.optionInfo(option, device, controller).value;
-    }
-    /**
-     * Return the value associated with a value-centric feature option, traversing the scope hierarchy.
-     *
-     * @param option        - Feature option to check.
-     * @param device        - Optional device scope identifier.
-     * @param controller    - Optional controller scope identifier.
-     *
-     * @returns Returns the current value associated with `option` if the feature option is enabled, `null` if disabled (or not a value-centric feature option), or
-     *          `undefined` if it's not specified.
-     */
-    value(option, device, controller) {
-        // If this isn't a value-centric feature option, we're done.
-        if (!this.isValue(option)) {
-            return null;
-        }
-        // Resolve the option through the scope hierarchy in a single traversal. This gives us the scope, enabled state, and raw value in one pass.
-        const resolved = this.resolveScope(option, device, controller);
-        // If the option has been explicitly disabled at any scope, or wasn't configured and its default is disabled, there's no value.
-        if (!resolved.enabled) {
-            return null;
-        }
-        // If we found an explicit value in the index, return it.
-        if (resolved.optionValue) {
-            return resolved.optionValue;
-        }
-        // The option is enabled but has no explicit value. If it wasn't configured at any scope (scope is "none"), fall back to the registered default value.
-        if (resolved.scope === "none") {
-            return this.valueOptions[option.toLowerCase()]?.toString() ?? null;
-        }
-        // The option is enabled at an explicit scope but no value was provided...return undefined to indicate "enabled, no value."
-        return undefined;
-    }
-    /**
-     * Return the list of available feature option categories.
-     *
-     * @returns Returns the current list of available feature option categories.
-     */
-    get categories() {
-        return this._categories;
-    }
-    /**
-     * Set the list of available feature option categories.
-     *
-     * @param category      - Array of available categories.
-     */
-    set categories(category) {
-        this._categories = category;
-        // Regenerate defaults and the lookup index.
-        this.generateDefaults();
-    }
-    /**
-     * Return the list of currently configured feature options.
-     *
-     * @returns Returns the currently configured list of feature options.
-     */
-    get configuredOptions() {
-        return this._configuredOptions;
-    }
-    /**
-     * Set the list of currently configured feature options.
-     *
-     * @param options       - Array of configured feature options.
-     */
-    set configuredOptions(options) {
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        this._configuredOptions = options ?? [];
-        // Regenerate defaults and the lookup index.
-        this.generateDefaults();
-    }
-    /**
-     * Return the list of available feature option groups.
-     *
-     * @returns Returns the current list of available feature option groups.
-     */
-    get groups() {
-        return this._groups;
-    }
-    /**
-     * Return the list of available feature options.
-     *
-     * @returns Returns the current list of available feature options.
-     */
-    get options() {
-        return this._options;
-    }
-    /**
-     * Set the list of available feature options.
-     *
-     * @param options       - Array of available feature options.
-     */
-    set options(options) {
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        this._options = options ?? {};
-        // Regenerate defaults and the lookup index.
-        this.generateDefaults();
-    }
-    // Rebuild the defaults, groups, value options, and lookup index from the current categories, options, and configured options. All three property setters call this so
-    // that state is always consistent regardless of which setter is called or in what order.
-    generateDefaults() {
-        this.defaults = {};
-        this._groups = {};
-        this.valueOptions = {};
-        for (const category of this.categories) {
-            // If the category doesn't exist, let's skip it.
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            if (!this.options[category.name]) {
-                continue;
-            }
-            // Now enumerate all the feature options for a given device and add then to the full list.
-            for (const option of this.options[category.name]) {
-                // Expand the entry.
-                const entry = this.expandOption(category, option);
-                // Index the default value.
-                this.defaults[entry.toLowerCase()] = option.default;
-                // Track value-centric options.
-                if ("defaultValue" in option) {
-                    this.valueOptions[entry.toLowerCase()] = option.defaultValue;
-                }
-                // Cross reference the feature option group it belongs to, if any.
-                if (option.group !== undefined) {
-                    const expandedGroup = category.name + (option.group.length ? ("." + option.group) : "");
-                    // Initialize the group entry if needed and add the entry.
-                    (this._groups[expandedGroup] ??= []).push(entry);
-                }
-            }
-        }
-        // Rebuild the lookup index now that we know which options are value-centric.
-        this.buildConfigIndex();
-    }
-    // Resolves a feature option through the scope hierarchy in a single traversal. Returns the scope where the option was found, whether it's enabled, and the raw string
-    // value for value-centric options. This is the core resolution method that both test()/scope() and value() build on, eliminating the need for separate traversals.
-    //
-    // There are a couple of ways to enable and disable options. The rules of the road are:
-    //
-    // 1. Explicitly disabling or enabling an option on the controller propagates to all the devices that are managed by that controller.
-    //
-    // 2. Explicitly disabling or enabling an option on a device always overrides the above. This means that it's possible to disable an option for a controller, and all
-    //    the devices that are managed by it, and then override that behavior on a single device that it's managing.
-    resolveScope(option, device, controller) {
-        const normalizedOption = option.toLowerCase();
-        let entry;
-        // Check to see if we have a device-level option first.
-        if (device) {
-            entry = this.configLookup.get(normalizedOption + "." + device.toLowerCase());
-            if (entry) {
-                return { enabled: entry.enabled, optionValue: entry.value, scope: "device" };
-            }
-        }
-        // Now check to see if we have a controller-level option.
-        if (controller) {
-            entry = this.configLookup.get(normalizedOption + "." + controller.toLowerCase());
-            if (entry) {
-                return { enabled: entry.enabled, optionValue: entry.value, scope: "controller" };
-            }
-        }
-        // Finally, we check for a global-level value.
-        entry = this.configLookup.get(normalizedOption);
-        if (entry) {
-            return { enabled: entry.enabled, optionValue: entry.value, scope: "global" };
-        }
-        // The option hasn't been set at any scope, return our default value.
-        return { enabled: this.defaultValue(option), scope: "none" };
-    }
-    // Thin wrapper over resolveScope() that returns the OptionInfoEntry shape expected by test() and scope().
-    optionInfo(option, device, controller) {
-        const resolved = this.resolveScope(option, device, controller);
-        return { scope: resolved.scope, value: resolved.enabled };
-    }
-    // Utility function to parse and return a numeric configuration parameter.
-    parseOptionNumeric(option, convert) {
-        // If the option is disabled or we don't have it configured -- we're done.
-        if (!option) {
-            return (option === null) ? null : undefined;
-        }
-        // Convert it to a number, if needed.
-        const convertedValue = convert(option);
-        // Let's validate to make sure it's really a number.
-        if (isNaN(convertedValue)) {
-            return undefined;
-        }
-        // Return the value.
-        return convertedValue;
-    }
-    // Build a lookup index from the configured option strings. Each entry is keyed by its normalized lookup path (option name, or option name + scope id) and stores
-    // whether the option is enabled along with the extracted value for value-centric options. The index is built once when configured options or option definitions change,
-    // and all subsequent lookups are O(1).
-    buildConfigIndex() {
-        this.configLookup = new Map();
-        // Collect known value option names, sorted longest first for greedy prefix matching. This ensures that when option names overlap (e.g., a category "audio" and an
-        // option "audio.volume"), the more specific name matches first.
-        const valueOptionNames = Object.keys(this.valueOptions).sort((a, b) => b.length - a.length);
-        for (const rawEntry of this._configuredOptions) {
-            // Parse the action prefix (Enable or Disable).
-            const dotIndex = rawEntry.indexOf(".");
-            if (dotIndex === -1) {
-                continue;
-            }
-            const action = rawEntry.slice(0, dotIndex).toLowerCase();
-            if ((action !== "enable") && (action !== "disable")) {
-                continue;
-            }
-            const enabled = action === "enable";
-            const tailOriginal = rawEntry.slice(dotIndex + 1);
-            const tail = tailOriginal.toLowerCase();
-            // Register the exact tail as a lookup key. First-write-wins...if the same option appears multiple times, the earliest entry in the array takes precedence.
-            if (!this.configLookup.has(tail)) {
-                this.configLookup.set(tail, { enabled });
-            }
-            // For Enable entries on value-centric options, extract the trailing value segment and register under the base key (option or option.id) so that value lookups
-            // resolve in O(1) instead of requiring regex matching and array scanning.
-            if (!enabled) {
-                continue;
-            }
-            for (const optName of valueOptionNames) {
-                if (!tail.startsWith(optName)) {
-                    continue;
-                }
-                const remainder = tail.slice(optName.length);
-                // Exact match on the option name with no trailing segments...there's no value to extract.
-                if (!remainder.length) {
-                    break;
-                }
-                // The next character must be a dot separator. If not, this option name is merely a prefix of a longer unrelated token.
-                if (!remainder.startsWith(".")) {
-                    continue;
-                }
-                const extra = remainder.slice(1);
-                const extraOriginal = tailOriginal.slice(optName.length + 1);
-                const separatorIndex = extra.indexOf(".");
-                if (separatorIndex === -1) {
-                    // Single trailing segment after the option name. At global scope this is the value; at scoped scope it's the id. Register under the option name as the
-                    // base key so that global value lookups find it.
-                    if (!this.configLookup.has(optName)) {
-                        this.configLookup.set(optName, { enabled: true, value: extraOriginal });
-                    }
-                }
-                else {
-                    // Two trailing segments: the first is the scope id and the second is the value.
-                    const idLower = extra.slice(0, separatorIndex);
-                    const valueOriginal = extraOriginal.slice(separatorIndex + 1);
-                    // Only register if the value portion is a single segment (no additional dots).
-                    if (!valueOriginal.includes(".")) {
-                        const baseKey = optName + "." + idLower;
-                        if (!this.configLookup.has(baseKey)) {
-                            this.configLookup.set(baseKey, { enabled: true, value: valueOriginal });
-                        }
-                    }
-                }
-                break;
-            }
-        }
-    }
-}
-//# sourceMappingURL=featureoptions.js.map

package/dist/featureoptions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"featureoptions.js","sourceRoot":"","sources":["../src/featureoptions.ts"],"names":[],"mappings":"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"}

package/dist/mqttclient.d.ts

@@ -1,178 +0,0 @@
-/**
- * MQTT connectivity and topic management for Homebridge plugins.
- *
- * @module
- */
-import type { HomebridgePluginLogging } from "./util.js";
-/**
- * MQTT connectivity and topic management class for Homebridge plugins.
- *
- * This class manages connection, publishing, subscription, and message handling for an MQTT broker, and provides convenience methods for Homebridge accessories to
- * interact with MQTT topics using a standard topic prefix.
- *
- * @example
- *
- * ```ts
- * const mqtt = new MqttClient("mqtt://localhost:1883", "homebridge", log);
- *
- * // Publish a message to a topic.
- * mqtt.publish("device1", "status", "on");
- *
- * // Subscribe to a topic.
- * mqtt.subscribe("device1", "status", (msg) => {
- *
- *   console.log(msg.toString());
- * });
- *
- * // Subscribe to a 'get' topic and automatically publish a value in response.
- * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
- *
- * // Subscribe to a 'set' topic and handle value changes.
- * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
- *
- *   console.log("Switch set to", value);
- * });
- *
- * // Unsubscribe from a topic.
- * mqtt.unsubscribe("device1", "status");
- * ```
- */
-export declare class MqttClient {
-    private brokerUrl;
-    private isConnected;
-    private reconnectInterval;
-    private log;
-    private mqtt;
-    private subscriptions;
-    private topicPrefix;
-    /**
-     * Creates a new MQTT client for connecting to a broker and managing topics with a given prefix.
-     *
-     * @param brokerUrl          - The MQTT broker URL (e.g., "mqtt://localhost:1883").
-     * @param topicPrefix        - Prefix to use for all MQTT topics (e.g., "homebridge").
-     * @param log                - Logger for debug and info messages.
-     * @param reconnectInterval  - Optional. Interval (in seconds) to wait between reconnection attempts. Defaults to 60 seconds.
-     *
-     * @example
-     *
-     * ```ts
-     * const mqtt = new MqttClient("mqtt://localhost", "homebridge", log);
-     * ```
-     *
-     * @remarks URL must conform to formats supported by {@link https://github.com/mqttjs/MQTT.js | MQTT.js}.
-     */
-    constructor(brokerUrl: string, topicPrefix: string, log: HomebridgePluginLogging, reconnectInterval?: number);
-    /**
-     * Initializes and connects the MQTT client to the broker, setting up event handlers for connection, messages, and errors.
-     *
-     * Catches invalid broker URLs and logs errors. Handles all major MQTT client events internally.
-     */
-    private configure;
-    /**
-     * Publishes a message to a topic for a specific device.
-     *
-     * Expands the topic using the topic prefix and device ID, then publishes the provided message string.
-     *
-     * @param id      - The device or accessory identifier.
-     * @param topic   - The topic name to publish to.
-     * @param message - The message payload to publish.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.publish("device1", "status", "on");
-     * ```
-     */
-    publish(id: string, topic: string, message: string): void;
-    /**
-     * Subscribes to a topic for a specific device and registers a handler for incoming messages.
-     *
-     * The topic is expanded using the prefix and device ID, and the callback will be called for each message received.
-     *
-     * @param id       - The device or accessory identifier.
-     * @param topic    - The topic name to subscribe to.
-     * @param callback - Handler function called with the message buffer.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribe("device1", "status", (msg) => {
-     *
-     *   console.log(msg.toString());
-     * });
-     * ```
-     */
-    subscribe(id: string, topic: string, callback: (cbBuffer: Buffer) => Promise<void> | void): void;
-    /**
-     * Subscribes to a '<topic>/get' topic and publishes a value in response to "true" messages.
-     *
-     * When a message "true" is received on the '<topic>/get' topic, this method will publish the result of `getValue()` on the main topic. The log will record each status
-     * publication event.
-     *
-     * @param id       - The device or accessory identifier.
-     * @param topic    - The topic name to use.
-     * @param type     - A human-readable label for log messages (e.g., "Temperature").
-     * @param getValue - Function to get the value to publish as a string.
-     * @param log      - Optional logger for status output. Defaults to the class logger.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
-     * ```
-     */
-    subscribeGet(id: string, topic: string, type: string, getValue: () => string, log?: HomebridgePluginLogging): void;
-    /**
-     * Subscribes to a '<topic>/set' topic and calls a setter when a message is received.
-     *
-     * The `setValue` function is called with both a normalized value and the raw string. Handles both synchronous and promise-based setters. Logs when set messages are
-     * received and when errors occur.
-     *
-     * @param id        - The device or accessory identifier.
-     * @param topic     - The topic name to use.
-     * @param type      - A human-readable label for log messages (e.g., "Switch").
-     * @param setValue  - Function to call when a value is set. Can be synchronous or return a Promise.
-     * @param log       - Optional logger for status output. Defaults to the class logger.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
-     *
-     *   console.log("Switch set to", value);
-     * });
-     * ```
-     */
-    subscribeSet(id: string, topic: string, type: string, setValue: (value: string, rawValue: string) => Promise<void> | void, log?: HomebridgePluginLogging): void;
-    /**
-     * Unsubscribes from a topic for a specific device, removing its message handler.
-     *
-     * @param id    - The device or accessory identifier.
-     * @param topic - The topic name to unsubscribe from.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.unsubscribe("device1", "status");
-     * ```
-     */
-    unsubscribe(id: string, topic: string): void;
-    /**
-     * Expands a topic string into a fully-formed topic path including the prefix and device ID.
-     *
-     * Returns `null` if the device ID is missing or empty.
-     *
-     * @param id    - The device or accessory identifier.
-     * @param topic - The topic name to expand.
-     *
-     * @returns The expanded topic string, or `null` if the ID is missing.
-     *
-     * @example
-     *
-     * ```ts
-     * const topic = mqtt['expandTopic']("device1", "status");
-     * // topic = "homebridge/device1/status"
-     * ```
-     */
-    private expandTopic;
-}