homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/featureOptions.js

@@ -0,0 +1,870 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * featureOptions.ts: Hierarchical feature option capabilities for use in plugins and applications.
+ */
+import { formatBps, formatBytes, formatMs, formatPercent, formatSeconds } from "./formatters.js";
+// The lookup table the catalog-index builder consults to resolve a string-named renderer to the function that implements it. Plugin-side formatting logic that
+// would otherwise be duplicated across every plugin (each one reaching into util.ts to wrap formatBps for their bandwidth option, etc.) lives here once - any
+// improvement to a built-in formatter's behavior propagates to every plugin that opts into the name. Adding a new formatter is a two-line change: extend the type
+// union above and add a row here.
+//
+// The registry is module-scope and not exported. Per-plugin customization belongs in the function escape hatch on `render`; there is deliberately no API to mutate
+// the shared registry, which would create initialization-order bugs and let test fixtures leak across files.
+const BUILT_IN_FORMATTERS = {
+    // Bitrate stored as bits per second. Delegates to formatBps which selects the right human-readable magnitude (bps / kbps / Mbps).
+    bps: (value) => formatBps(Number.parseFloat(value)),
+    // Byte count rendered as bytes / KB / MB / GB via the 1024-based convention every operating system uses for file and buffer sizes.
+    bytes: (value) => formatBytes(Number.parseFloat(value)),
+    // Bitrate stored as kilobits per second. We scale into bits and reuse formatBps so the magnitude selection stays identical to the bps formatter - the only
+    // difference between bps and kbps is the storage convention the plugin chose, never the displayed form.
+    kbps: (value) => formatBps(Number.parseFloat(value) * 1_000),
+    // Duration stored as milliseconds. formatMs promotes through ms / s / min / hr based on magnitude.
+    ms: (value) => formatMs(Number.parseFloat(value)),
+    // Percentage rendered through the shared formatPercent helper so the precision policy stays uniform across every formatter in the registry - whole numbers carry
+    // no decimal, fractional values get one decimal place.
+    percent: (value) => formatPercent(Number.parseFloat(value)),
+    // Duration stored as seconds. formatSeconds promotes through s / min / hr based on magnitude.
+    seconds: (value) => formatSeconds(Number.parseFloat(value))
+};
+// Resolve a built-in formatter by name. Accepts an arbitrary string (not just a `FeatureOptionFormatter` literal) so the lookup naturally returns `undefined` when a
+// caller bypasses the type system - via JS, an `as` cast, or an out-of-date type definition - and passes an unrecognized name. Encapsulating the type-widening cast
+// here keeps the call site clean and names the intent: "look up a registered formatter by name; the result may not exist." Without the widening at this single seam,
+// TypeScript narrows the literal-keyed indexing tightly enough that the runtime safety check at the call site looks dead, and the runtime guard would either be
+// suppressed (silently weakening defense against JS callers) or removed (allowing the silent-fallback failure mode the design exists to prevent).
+function resolveBuiltInFormatter(name) {
+    return BUILT_IN_FORMATTERS[name];
+}
+/**
+ * Compose a fully formed feature option string from a category and an option. Accepts either raw strings or the catalog entry objects, mirroring how the catalog
+ * is iterated at build time. The result is the canonical key shape every other helper consumes - lowercase the result to derive lookup-index keys, preserve the
+ * caller's casing to compose entry strings.
+ *
+ * @param category - Feature option category entry or category name string.
+ * @param option   - Feature option entry or option name string.
+ *
+ * @returns The fully formed feature option in the form of `category.option`, or `category` alone when the option name is empty, or the empty string when the
+ *          category name is empty.
+ */
+export function 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;
+}
+// Compose the canonical lookup-index target key for a (option, id) pair. This is the form a setOption({ option, id, ... }) call would resolve to on the index, and
+// is the comparison key the matcher and writers share.
+function targetKey(option, id) {
+    return id?.length ? option.toLowerCase() + "." + id.toLowerCase() : option.toLowerCase();
+}
+// Parse a single configured-options entry into the lookup keys it would register on the index. Returns null for non-canonical entries (no action prefix, or an
+// unknown action). Otherwise returns the primary (raw-tail) key, optionally accompanied by a derived value key with the extracted value for value-centric Enable
+// entries. This is the SSOT for entry decoding - both buildConfigIndex (which uses it to populate the index) and entryAddressesScope (which uses it to decide
+// whether a mutation should replace this entry) consume the same result, so the writer and the reader of the storage format cannot disagree about what any given
+// entry "means."
+//
+// Greedy longest-prefix matching against the value-option registry handles the case where a shorter value-centric option name is a prefix of a longer option in
+// the catalog - the longer match wins, so an entry like `Enable.Audio.Volume.50` (when both `Audio` and `Audio.Volume` are value-centric) is unambiguously parsed
+// as `Audio.Volume` with value `50`, not `Audio` with value `Volume.50`.
+function parseEntry(catalog, rawEntry) {
+    const dotIndex = rawEntry.indexOf(".");
+    if (dotIndex === -1) {
+        return null;
+    }
+    const action = rawEntry.slice(0, dotIndex).toLowerCase();
+    if ((action !== "enable") && (action !== "disable")) {
+        return null;
+    }
+    const enabled = action === "enable";
+    const tailOriginal = rawEntry.slice(dotIndex + 1);
+    const tail = tailOriginal.toLowerCase();
+    const parsed = { enabled, primaryKey: tail };
+    // Value extraction is only meaningful for Enable entries - a disabled option carries no value regardless of trailing segments.
+    if (!enabled) {
+        return parsed;
+    }
+    // Iterate the precomputed longest-first value-option-names cache. Sorting here would re-allocate and re-traverse valueOptions on every Enable-entry parse; the
+    // cache lives on catalog.sortedValueOptionNames and is rebuilt only when the catalog changes (see buildCatalogIndex).
+    for (const optName of catalog.sortedValueOptionNames) {
+        if (!tail.startsWith(optName)) {
+            continue;
+        }
+        const remainder = tail.slice(optName.length);
+        // Exact match on the option name with no trailing segments - there is no value to extract, just a bare Enable on the value option.
+        if (!remainder.length) {
+            break;
+        }
+        // The next character must be a dot separator. Otherwise this option name is merely a prefix of a longer unrelated token, and we should continue trying shorter
+        // candidates.
+        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: global value form.
+            parsed.valueKey = optName;
+            parsed.value = extraOriginal;
+        }
+        else {
+            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) - otherwise the tail is unstructured and we leave it for the primary key.
+            if (!valueOriginal.includes(".")) {
+                parsed.valueKey = optName + "." + idLower;
+                parsed.value = valueOriginal;
+            }
+        }
+        break;
+    }
+    return parsed;
+}
+// Decide whether a configured-options entry addresses a target lookup key. Used by applySetOption/applyClearOption to find replaceable entries without exposing
+// the entry format to callers. Goes through the shared parser so the matcher is consistent with the indexer by construction.
+function entryAddressesScope({ catalog, rawEntry, target }) {
+    const parsed = parseEntry(catalog, rawEntry);
+    if (!parsed) {
+        return false;
+    }
+    return (parsed.primaryKey === target) || (parsed.valueKey === target);
+}
+/**
+ * Build the catalog-derived index from raw categories + options. The result carries the raw inputs alongside every derivation needed for O(1) catalog queries -
+ * defaults, value-options registry, groups (both directions), renderers, and the longest-first cache the entry parser consumes. Throws when a built-in formatter
+ * name on a `render` declaration does not resolve, surfacing the misconfiguration at load time rather than silently degrading the log-emission path.
+ *
+ * The index is the catalog-side input to every other pure helper in this module. Build it once per catalog; reuse it across every configured-options mutation
+ * because the catalog is invariant across those mutations. Categories without an entry in the options map are skipped silently (a plugin defines a category for
+ * future expansion before any option has migrated into it).
+ *
+ * @param categories - The raw category list.
+ * @param options    - The raw options map keyed by category name.
+ *
+ * @returns The immutable catalog index.
+ */
+export function buildCatalogIndex(categories, options) {
+    const defaults = {};
+    const groupParents = {};
+    const groups = {};
+    const renderers = {};
+    const valueOptions = {};
+    for (const category of categories) {
+        const categoryOptions = options[category.name];
+        if (!categoryOptions) {
+            continue;
+        }
+        for (const option of categoryOptions) {
+            const entry = expandOption(category, option);
+            defaults[entry.toLowerCase()] = option.default;
+            // Track value-centric options separately so the lookup index built later knows which entries can carry a trailing value segment.
+            if ("defaultValue" in option) {
+                valueOptions[entry.toLowerCase()] = option.defaultValue;
+            }
+            // Register the catalog-declared renderer when present so logFeature can consult it in O(1) without walking the options map at log time. Boolean options may
+            // declare a renderer too - it just goes unused by the logging path - so we register unconditionally rather than gating on isValue here. A string-typed
+            // declaration names a built-in formatter from BUILT_IN_FORMATTERS; an unknown name is a misconfiguration, surfaced loudly at catalog-build time rather than
+            // silently degraded to the raw-value fallback at log time.
+            if (option.render !== undefined) {
+                if (typeof option.render === "string") {
+                    const formatter = resolveBuiltInFormatter(option.render);
+                    if (formatter === undefined) {
+                        throw new Error("FeatureOptions: unknown built-in formatter \"" + option.render + "\" declared on option \"" + entry + "\".");
+                    }
+                    renderers[entry.toLowerCase()] = formatter;
+                }
+                else {
+                    renderers[entry.toLowerCase()] = option.render;
+                }
+            }
+            if (option.group !== undefined) {
+                const expandedGroup = category.name + (option.group.length ? ("." + option.group) : "");
+                // Build both directions of the parent/child relation so callers can walk it either way in O(1) - forward for a parent's children, reverse for an option's
+                // parent group.
+                (groups[expandedGroup] ??= []).push(entry);
+                groupParents[entry] = expandedGroup;
+            }
+        }
+    }
+    // Cache the value-option names sorted longest-first. parseEntry consumes this directly on every Enable-entry parse; precomputing here means the sort runs once
+    // per catalog change rather than once per parse. The list mirrors valueOptions's key set, so any future mutation that touches valueOptions must rebuild through
+    // this method to keep the two views consistent.
+    const sortedValueOptionNames = Object.keys(valueOptions).sort((a, b) => b.length - a.length);
+    return { categories, defaults, groupParents, groups, options, renderers, sortedValueOptionNames, valueOptions };
+}
+/**
+ * Build the configured-options lookup index from a catalog index + the configured-options array. Each entry contributes one or two lookup keys via the shared
+ * `parseEntry`: the raw tail (always) and an extracted value key (for value-centric Enable entries). First-write-wins on collision so the earliest entry in
+ * the array takes precedence over later duplicates - users hand-editing config and accidentally listing an option twice get the natural "first one is canonical"
+ * semantic.
+ *
+ * Rebuild whenever the configured-options array changes; reuse across reads.
+ *
+ * @param catalog           - The catalog index that defines what counts as a value-centric option.
+ * @param configuredOptions - The array of configured option strings.
+ *
+ * @returns The immutable lookup index.
+ */
+export function buildConfigIndex(catalog, configuredOptions) {
+    const lookup = new Map();
+    for (const rawEntry of configuredOptions) {
+        const parsed = parseEntry(catalog, rawEntry);
+        if (!parsed) {
+            continue;
+        }
+        if (!lookup.has(parsed.primaryKey)) {
+            lookup.set(parsed.primaryKey, { enabled: parsed.enabled });
+        }
+        if (parsed.valueKey && !lookup.has(parsed.valueKey)) {
+            lookup.set(parsed.valueKey, { enabled: true, value: parsed.value });
+        }
+    }
+    return lookup;
+}
+/**
+ * Compute the new configured-options array after setting an option's enabled state (and optionally its value) at a given scope. Drops any prior entry addressing
+ * the same option-at-scope so the new entry is the sole survivor, then appends the freshly composed entry string. Pure: does not mutate the input array; the
+ * returned array is a fresh allocation.
+ *
+ * The composed entry's action segment is canonical "Enable" / "Disable"; the option and id segments preserve the caller's casing for readability since the
+ * lookup-index keys are case-insensitive anyway. Value tails are emitted only when meaningful - disabled or non-value options never carry one - so a subsequent
+ * {@link applyClearOption} or {@link applySetOption} addressing the same scope cleanly replaces whatever was there.
+ *
+ * @param options
+ * @param options.args              - The mutation intent: option key, optional scope id, enabled state, optional value. See {@link SetOptionArgs}.
+ * @param options.catalog           - The catalog index that defines what counts as a value-centric option (which determines whether to emit a value segment).
+ * @param options.configuredOptions - The current configured-options array.
+ *
+ * @returns The new configured-options array. A fresh allocation, never a shared reference with the input.
+ */
+export function applySetOption({ args, catalog, configuredOptions }) {
+    const target = targetKey(args.option, args.id);
+    const filtered = configuredOptions.filter((entry) => !entryAddressesScope({ catalog, rawEntry: entry, target }));
+    // Compose the new entry. The action segment is canonical "Enable"/"Disable"; the rest preserves the caller's casing for readability since the index is
+    // case-insensitive anyway. Value tails are emitted only when meaningful - disabled or non-value options never carry one.
+    const segments = [args.enabled ? "Enable" : "Disable", args.option];
+    if (args.id?.length) {
+        segments.push(args.id);
+    }
+    if (args.enabled && isValueOption(catalog, args.option) && (args.value !== undefined)) {
+        segments.push(args.value.toString());
+    }
+    filtered.push(segments.join("."));
+    return filtered;
+}
+/**
+ * Compute the new configured-options array after clearing every entry addressing an option at a given scope. The match is value-aware: for value-centric options
+ * it covers both the bare scoped entry and any entry carrying a single trailing value segment, so a subsequent {@link applySetOption} cleanly replaces whatever
+ * was there.
+ *
+ * Pure: does not mutate the input array. When no entry matched the target, returns the input array reference unchanged so reference-equality consumers can detect
+ * a no-op without a contents comparison.
+ *
+ * @param options
+ * @param options.args              - The addressing intent: option key, optional scope id. See {@link ClearOptionArgs}.
+ * @param options.catalog           - The catalog index that defines what counts as a value-centric option (which the matcher consults via the shared parser).
+ * @param options.configuredOptions - The current configured-options array.
+ *
+ * @returns The new configured-options array, or the input array reference itself when nothing matched.
+ */
+export function applyClearOption({ args, catalog, configuredOptions }) {
+    const target = targetKey(args.option, args.id);
+    const filtered = configuredOptions.filter((entry) => !entryAddressesScope({ catalog, rawEntry: entry, target }));
+    // Reference-stable no-op: nothing matched, so callers comparing references see no change without inspecting contents.
+    return (filtered.length === configuredOptions.length) ? configuredOptions : filtered;
+}
+/**
+ * Resolve a feature option through the scope hierarchy in a single traversal. Returns the scope where the option was found, its enabled state, and the raw value
+ * for value-centric options. This is the core resolution primitive that every higher-level query builds on - {@link FeatureOptions.test}, {@link FeatureOptions.scope},
+ * {@link FeatureOptions.value}, and {@link FeatureOptions.logFeature} all consume the same `ResolvedOptionEntry` shape from one walk.
+ *
+ * Resolution precedence: device beats controller beats global beats default. An explicit entry at a higher-precedence scope short-circuits the lookup, so the
+ * cost is O(1) in the configured-options array size.
+ *
+ * @param args
+ * @param args.catalog            - The catalog index (consulted for the default when no scope matched).
+ * @param args.configIndex        - The configured-options lookup index.
+ * @param args.controller         - Optional controller scope identifier.
+ * @param args.defaultReturnValue - Fallback for options that don't appear in the catalog's defaults. Defaults to false.
+ * @param args.device             - Optional device scope identifier.
+ * @param args.option             - The option key to resolve (case-insensitive).
+ *
+ * @returns The resolved view: scope, enabled state, optional raw value.
+ */
+export function resolveScope({ catalog, configIndex, controller, defaultReturnValue = false, device, option }) {
+    const normalizedOption = option.toLowerCase();
+    // Check to see if we have a device-level option first.
+    if (device) {
+        const deviceEntry = configIndex.get(normalizedOption + "." + device.toLowerCase());
+        if (deviceEntry) {
+            return { enabled: deviceEntry.enabled, optionValue: deviceEntry.value, scope: "device" };
+        }
+    }
+    // Now check to see if we have a controller-level option.
+    if (controller) {
+        const controllerEntry = configIndex.get(normalizedOption + "." + controller.toLowerCase());
+        if (controllerEntry) {
+            return { enabled: controllerEntry.enabled, optionValue: controllerEntry.value, scope: "controller" };
+        }
+    }
+    // Finally, we check for a global-level value.
+    const globalEntry = configIndex.get(normalizedOption);
+    if (globalEntry) {
+        return { enabled: globalEntry.enabled, optionValue: globalEntry.value, scope: "global" };
+    }
+    // The option hasn't been set at any scope, return the catalog default. The defaultReturnValue parameter covers the case where the option is not in the catalog
+    // at all - typically a misspelling or a stale call site referring to an option that was removed from the catalog.
+    return { enabled: getDefaultValue({ catalog, defaultReturnValue, option }), scope: "none" };
+}
+/**
+ * Return the catalog-declared default for a feature option, falling back to a caller-supplied default for options that don't appear in the catalog at all.
+ *
+ * @param args
+ * @param args.catalog            - The catalog index.
+ * @param args.defaultReturnValue - Fallback when the option is not in the catalog's defaults map. Defaults to false.
+ * @param args.option             - The option key (case-insensitive).
+ *
+ * @returns The default value: catalog declaration if present, fallback otherwise.
+ */
+export function getDefaultValue({ catalog, defaultReturnValue = false, option }) {
+    return catalog.defaults[option.toLowerCase()] ?? defaultReturnValue;
+}
+/**
+ * Return whether a feature option is value-centric (carries a `defaultValue` in its catalog declaration). The presence of the option's lowercased key in the
+ * catalog's `valueOptions` map is the SSOT for this predicate.
+ *
+ * @param catalog - The catalog index.
+ * @param option  - The option key (case-insensitive). Empty string returns false.
+ *
+ * @returns True for value-centric options, false otherwise.
+ */
+export function isValueOption(catalog, option) {
+    if (!option) {
+        return false;
+    }
+    return option.toLowerCase() in catalog.valueOptions;
+}
+/**
+ * Return whether an option has been explicitly configured at the given scope. Distinct from {@link resolveScope}, which walks the hierarchy; this predicate
+ * answers only "did the user set this entry at THIS scope?" without consulting any higher or lower scopes.
+ *
+ * @param args
+ * @param args.configIndex - The configured-options lookup index.
+ * @param args.id          - Optional scope identifier (device or controller). Omit to address the global scope.
+ * @param args.option      - The option key (case-insensitive).
+ *
+ * @returns True when an explicit entry addresses this option-at-scope.
+ */
+export function optionExists({ configIndex, id, option }) {
+    return configIndex.has(option.toLowerCase() + (id ? "." + id.toLowerCase() : ""));
+}
+/**
+ * Return whether a grouped option's parent is currently enabled at the given scope. For options that aren't grouped (no `group` property in the catalog entry),
+ * always returns `true` - there is no dependency to fail. For grouped options, traverses the scope hierarchy via {@link resolveScope} to evaluate the parent's
+ * effective state at the requested device + controller view.
+ *
+ * This is the SSOT for "is this option's row currently usable?" Every caller that wants to know whether to render a grouped option's row, count it as visible,
+ * or honor its dependency-hidden state asks this function rather than reconstructing the parent path themselves. The reverse-lookup from option to parent uses
+ * the pre-built `catalog.groupParents` index, so the predicate is O(1) regardless of option-key length.
+ *
+ * @param args
+ * @param args.catalog            - The catalog index.
+ * @param args.configIndex        - The configured-options lookup index.
+ * @param args.controller         - Optional controller scope identifier.
+ * @param args.defaultReturnValue - Fallback default for options not in the catalog. Defaults to false.
+ * @param args.device             - Optional device scope identifier.
+ * @param args.option             - Fully-qualified feature option string (e.g., `"Motion.Sensitivity"`). Case-insensitive.
+ *
+ * @returns `true` when the option has no dependency or its parent is currently enabled at the requested scope; `false` when the parent is currently disabled.
+ */
+export function isDependencyMet({ catalog, configIndex, controller, defaultReturnValue = false, device, option }) {
+    const parent = catalog.groupParents[option];
+    if (!parent) {
+        return true;
+    }
+    return resolveScope({ catalog, configIndex, controller, defaultReturnValue, device, option: parent }).enabled;
+}
+// Utility function to parse and return a numeric configuration parameter. Distinguishes exactly two outcomes: null when the option is explicitly disabled, and
+// undefined-or-a-parsed-number for everything else - unset, set but unparseable, or successfully parsed - matching the public getInteger/getFloat contract, which
+// likewise groups "doesn't exist" and "couldn't be parsed" under a single undefined outcome.
+function parseOptionNumeric(option, convert) {
+    // If the option is disabled (null) or we don't have it configured (undefined), preserve that distinction in the return value so callers can tell the two apart.
+    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 (Number.isNaN(convertedValue)) {
+        return undefined;
+    }
+    // Return the value.
+    return convertedValue;
+}
+/**
+ * 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.
+ *
+ * This class is the imperative façade over the pure functional core exposed by this module ({@link buildCatalogIndex}, {@link applySetOption},
+ * {@link applyClearOption}, {@link resolveScope}, etc.). Reducer-driven consumers that want immutable state should call the pure functions directly; imperative
+ * Node-side plugin code uses this class for the same semantics with mutation-friendly ergonomics.
+ *
+ * @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;
+    #catalog;
+    #configIndex;
+    #configuredOptions;
+    /**
+     * 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 = []) {
+        this.#catalog = buildCatalogIndex(categories, options);
+        this.#configuredOptions = configuredOptions;
+        this.#configIndex = buildConfigIndex(this.#catalog, configuredOptions);
+        this.defaultReturnValue = false;
+    }
+    /**
+     * 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) {
+        return getDefaultValue({ catalog: this.#catalog, defaultReturnValue: this.defaultReturnValue, option });
+    }
+    /**
+     * 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 optionExists({ configIndex: this.#configIndex, id, option });
+    }
+    /**
+     * Return whether a grouped option's parent is currently enabled at the given scope. For options that aren't grouped (no `group` property in the catalog entry),
+     * always returns `true` - there is no dependency to fail. For grouped options, traverses the scope hierarchy via {@link resolveScope} to evaluate the parent's
+     * effective state at the requested device + controller view.
+     *
+     * This is the SSOT for "is this option's row currently usable?" Every caller that wants to know whether to render a grouped option's row, count it as visible,
+     * or honor its dependency-hidden state asks the model rather than reconstructing the parent path themselves. The reverse-lookup from option to parent uses the
+     * pre-built {@link CatalogIndex.groupParents} index, so the predicate is O(1) regardless of option-key length.
+     *
+     * @param option        - Fully-qualified feature option string (e.g., `"Motion.Sensitivity"`). Case-insensitive.
+     * @param device        - Optional device scope identifier, forwarded to {@link resolveScope}.
+     * @param controller    - Optional controller scope identifier, forwarded to {@link resolveScope}.
+     *
+     * @returns `true` when the option has no dependency or its parent is currently enabled at the requested scope; `false` when the parent is currently disabled.
+     */
+    isDependencyMet(option, device, controller) {
+        return isDependencyMet({ catalog: this.#catalog, configIndex: this.#configIndex, controller, defaultReturnValue: this.defaultReturnValue, device, option });
+    }
+    /**
+     * 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) {
+        return expandOption(category, option);
+    }
+    /**
+     * 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) {
+        return parseOptionNumeric(this.value(option, device, controller), Number.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) {
+        return parseOptionNumeric(this.value(option, device, controller), Number.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) {
+        return isValueOption(this.#catalog, option);
+    }
+    /**
+     * Emit an INFO-level log line for a feature option, but only when the user's effective configuration deviates from the declared default.
+     *
+     * This is the executable form of the project-wide startup-log convention: restating a default is log noise, and deviations should be reported in both directions - a
+     * default-off feature the user turned on, a default-on feature the user turned off, and a value the user customized away from the registered default. Callers pass
+     * the option key and a human-readable label; this method handles the direction detection and the message synthesis so every plugin emits the same shape from one
+     * place. If the convention ever evolves, every call site picks up the change without any source modification.
+     *
+     * Polymorphic over option type, mirroring how {@link FeatureOptions.test} and {@link FeatureOptions.value} already dispatch on whether the option is value-centric.
+     * The distinct emitted-line shapes, across these state combinations:
+     *
+     * | Option type      | User state vs. default                                  | Emitted line                       |
+     * |------------------|---------------------------------------------------------|------------------------------------|
+     * | Boolean          | matches default                                         | (silent)                           |
+     * | Boolean          | default off, enabled                                    | `<label> enabled.`                 |
+     * | Boolean          | default on, disabled                                    | `<label> disabled.`                |
+     * | Value-centric    | both axes match                                         | (silent)                           |
+     * | Value-centric    | default on, disabled                                    | `<label> disabled.`                |
+     * | Value-centric    | default off, enabled (value matches or differs)         | `<label> enabled at <value>.`      |
+     * | Value-centric    | default on, enabled, value differs from declared default | `<label> set to <value>.`          |
+     *
+     * A value-centric option enabled with no resolvable value anywhere - no catalog-declared default and no explicit value at any scope - collapses to the plain
+     * `<label> enabled.` line above rather than the `enabled at <value>` form, since there is nothing meaningful to render after "at" (see the defensive fallback in
+     * the implementation below).
+     *
+     * Value rendering consults the catalog-declared {@link FeatureOptionEntry.render} when present; otherwise the raw string returned by {@link FeatureOptions.value}
+     * is used. The renderer may be either a {@link FeatureOptionFormatter} string naming a built-in formatter from the shared registry (preferred when the format exists
+     * there, since this keeps the catalog JSON-serializable and lets every plugin share one implementation) or an inline function for bespoke cases. Declaring the
+     * renderer at the option's catalog entry keeps display formatting a single source of truth shared by `logFeature` and any future surface that displays the value.
+     *
+     * Scope precedence matches {@link FeatureOptions.test}: device wins over controller wins over global wins over default. Pass the scope arguments that describe the
+     * vantage point you want to log from - typically a device identifier for accessory-level configuration, optionally with a controller identifier when the plugin's
+     * controller scope is meaningful (e.g., UniFi Protect controllers).
+     *
+     * @param option        - Feature option to check (same key shape as {@link FeatureOptions.test}; case-insensitive).
+     * @param label         - Human-readable label that prefixes the emitted message. Used verbatim as the first `%s` argument; should be a noun phrase like "Motion sensor"
+     *                        or "Read-only mode" so the rendered line reads naturally ("Motion sensor enabled." / "Read-only mode disabled.").
+     * @param log           - The plugin's logger. The emitted message is INFO-level; debug-level enumeration of the full feature surface is a separate concern handled by
+     *                        the caller.
+     * @param device        - Optional device scope identifier, forwarded to {@link FeatureOptions.test}.
+     * @param controller    - Optional controller scope identifier, forwarded to {@link FeatureOptions.test}.
+     *
+     * @example
+     *
+     * ```ts
+     * // Boolean option, inside a plugin's `configureMotion()` for a specific device:
+     * featureOptions.logFeature("Motion", "Motion sensor", log, device.mac);
+     *
+     * // Value-centric option - the message shape adapts to which axis (boolean, value, or both) deviated:
+     * featureOptions.logFeature("Stream.Bandwidth", "Bandwidth", log, device.mac);
+     *
+     * // With a controller scope:
+     * featureOptions.logFeature("HKSV.Record", "HKSV recording", log, device.mac, controller.id);
+     * ```
+     */
+    logFeature(option, label, log, device, controller) {
+        const effective = this.test(option, device, controller);
+        const defaultEnabled = this.defaultValue(option);
+        const booleanDeviates = effective !== defaultEnabled;
+        // Disabled: emit only when the user turned off something whose default is on. Value-centric options collapse to the same shape here - the value is irrelevant
+        // when the option is off, and the operator only needs to know it was disabled.
+        if (!effective) {
+            if (booleanDeviates) {
+                log.info("%s disabled.", label);
+            }
+            return;
+        }
+        // Enabled. For plain boolean options that is the whole story.
+        if (!this.isValue(option)) {
+            if (booleanDeviates) {
+                log.info("%s enabled.", label);
+            }
+            return;
+        }
+        // Enabled, value-centric option. Resolve the effective value (an explicit user value when set, otherwise the registered catalog default) and compare against the
+        // declared default to detect value-axis deviation. We compare normalized strings because the registry stores stringified user input while the catalog's defaultValue
+        // is typed as `number | string`; coercing both to string is the one normalization that makes the comparison total.
+        const declaredDefault = this.#catalog.valueOptions[option.toLowerCase()]?.toString();
+        const effectiveValue = this.value(option, device, controller) ?? declaredDefault;
+        const valueDeviates = (effectiveValue !== undefined) && (effectiveValue !== declaredDefault);
+        if (!booleanDeviates && !valueDeviates) {
+            return;
+        }
+        // Defensive fallback for the degenerate case of a value-centric catalog entry with no concrete value anywhere - no registered default and no explicit value at any
+        // scope. The option is enabled per the user's choice but there is nothing meaningful to render after "at"; emitting "<label> enabled at ." would mislead a reader,
+        // so we collapse to the boolean-axis message shape and let the catalog declaration's malformed-ness surface elsewhere.
+        if (effectiveValue === undefined) {
+            log.info("%s enabled.", label);
+            return;
+        }
+        const renderedValue = this.#catalog.renderers[option.toLowerCase()]?.(effectiveValue) ?? effectiveValue;
+        // Message shape splits on which axis deviated: "enabled at" when the user turned the feature on (boolean axis crossed), "set to" when only the value moved away
+        // from the registered default. Both forms always carry the effective value, since for value-centric options the value is what the operator most needs to see.
+        if (booleanDeviates) {
+            log.info("%s enabled at %s.", label, renderedValue);
+            return;
+        }
+        log.info("%s set to %s.", label, renderedValue);
+    }
+    /**
+     * Remove every configured-options entry addressing the given option at the given scope.
+     *
+     * Callers express intent ("forget any configuration for option X at scope Y") and the model owns the entry-format end-to-end. The match is value-aware: for
+     * value-centric options it covers both the bare scoped entry and any entry carrying a single trailing value segment, so a subsequent {@link setOption} cleanly
+     * replaces whatever was there. No-op when no entry addresses the target scope, so callers can treat this as an idempotent reset.
+     *
+     * @param args - The addressing intent: option key and optional scope id. See {@link ClearOptionArgs}.
+     *
+     * @example
+     *
+     * ```ts
+     * // Remove any configured value for "Audio.Volume" on device ABC123 (drops both `Enable.Audio.Volume.ABC123` and `Enable.Audio.Volume.ABC123.50`).
+     * featureOpts.clearOption({ option: "Audio.Volume", id: "ABC123" });
+     * ```
+     */
+    clearOption(args) {
+        const next = applyClearOption({ args, catalog: this.#catalog, configuredOptions: this.#configuredOptions });
+        // Reference-stable no-op: nothing matched, so the array and the index are already coherent. Skip the rebuild and preserve the array reference so callers
+        // holding a snapshot see a stable identity for unchanged state.
+        if (next === this.#configuredOptions) {
+            return;
+        }
+        this.#configuredOptions = next;
+        // Only the index depends on the configured-options array; the catalog-derived state is invariant across config mutations and need not be touched here.
+        this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
+    }
+    /**
+     * Set the enabled state (and optionally the value) for an option at a given scope, replacing any prior entry for the same option-at-scope.
+     *
+     * This is the single mutation primitive for individual feature options. Callers express intent ("enable option X at scope Y, with value Z") and the model owns
+     * both the encoding and the prior-entry replacement - the configured-options array is canonical, the lookup index is rebuilt automatically, and the entry-string
+     * format never leaks past this method. Value segments are emitted only when `enabled` is true and the option is value-centric; passing `value` for a non-value or
+     * disabled option is silently dropped because the resulting entry would be meaningless under the resolution rules.
+     *
+     * @param args - The mutation intent: option key, optional scope id, enabled state, and optional value. See {@link SetOptionArgs}.
+     *
+     * @example
+     *
+     * ```ts
+     * // Disable "Motion.Detect" globally.
+     * featureOpts.setOption({ enabled: false, option: "Motion.Detect" });
+     *
+     * // Enable "Audio.Volume" on device ABC123 with value 50, replacing any prior device-scoped entry for the same option.
+     * featureOpts.setOption({ enabled: true, id: "ABC123", option: "Audio.Volume", value: 50 });
+     * ```
+     */
+    setOption(args) {
+        this.#configuredOptions = applySetOption({ args, catalog: this.#catalog, configuredOptions: this.#configuredOptions });
+        // Only the index depends on the configured-options array; the catalog-derived state is invariant across config mutations and need not be touched here.
+        this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
+    }
+    /**
+     * 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 the location in the scope hierarchy of `option`.
+     */
+    scope(option, device, controller) {
+        return resolveScope({ catalog: this.#catalog, configIndex: this.#configIndex, controller, defaultReturnValue: this.defaultReturnValue, device, option }).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 resolveScope({ catalog: this.#catalog, configIndex: this.#configIndex, controller, defaultReturnValue: this.defaultReturnValue, device, option }).enabled;
+    }
+    /**
+     * 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 = resolveScope({ catalog: this.#catalog, configIndex: this.#configIndex, controller, defaultReturnValue: this.defaultReturnValue, device, option });
+        // 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 a non-empty explicit value in the index, return it. An empty string is deliberately treated as unspecified - from the user's perspective an empty value
+        // is the same as not setting one - so it falls through to the default or "enabled, no value" resolution below rather than being returned verbatim.
+        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.#catalog.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() {
+        // The catalog stores the categories as readonly to encode the immutability invariant the pure functional core relies on. The public getter returns the
+        // historical mutable type for backward compatibility - the array is the same identity the caller passed at construction (or via the setter), so consumers
+        // mutating it would be mutating the catalog regardless of the return type. The readonly annotation is the discipline, not a runtime enforcement.
+        return this.#catalog.categories;
+    }
+    /**
+     * Set the list of available feature option categories.
+     *
+     * @param category      - Array of available categories.
+     */
+    set categories(category) {
+        // The catalog derivation depends on categories, and the value-options registry (rebuilt by the catalog pass) feeds the index parser, so both stages must run
+        // in order. The class assembles a new catalog from the new categories + current options, then a new config index from the new catalog + current configured
+        // options.
+        this.#catalog = buildCatalogIndex(category, this.#catalog.options);
+        this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
+    }
+    /**
+     * 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) {
+        this.#configuredOptions = options ?? [];
+        // The catalog-derived state is invariant across config mutations; only the lookup index needs rebuilding.
+        this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
+    }
+    /**
+     * Return a reverse index mapping each child option to its parent group. This provides O(1) child-to-parent lookups, complementing the forward `groups` map that maps
+     * parents to their children.
+     *
+     * @returns Returns a record mapping child option names to their parent group names.
+     */
+    get groupParents() {
+        return this.#catalog.groupParents;
+    }
+    /**
+     * Return the list of available feature option groups.
+     *
+     * @returns Returns the current list of available feature option groups.
+     */
+    get groups() {
+        // Same readonly-to-mutable cast rationale as the categories getter above: this is the same object identity held internally, so a caller mutating it would be
+        // mutating the catalog regardless of the return type. The readonly annotation is the discipline, not a runtime enforcement.
+        return this.#catalog.groups;
+    }
+    /**
+     * Return the list of available feature options.
+     *
+     * @returns Returns the current list of available feature options.
+     */
+    get options() {
+        // Same readonly-to-mutable cast rationale as the categories getter above: this is the same object identity held internally, so a caller mutating it would be
+        // mutating the catalog regardless of the return type. The readonly annotation is the discipline, not a runtime enforcement.
+        return this.#catalog.options;
+    }
+    /**
+     * Set the list of available feature options.
+     *
+     * @param options       - Array of available feature options.
+     */
+    set options(options) {
+        // The catalog derivation depends on the option definitions, and the index parser consults the resulting value-options registry, so both stages must run in
+        // order. The class assembles a new catalog from the current categories + new options, then a new config index from the new catalog + current configured options.
+        this.#catalog = buildCatalogIndex(this.#catalog.categories, options ?? {});
+        this.#configIndex = buildConfigIndex(this.#catalog, this.#configuredOptions);
+    }
+}
+//# sourceMappingURL=featureOptions.js.map