homebridge-plugin-utils
Version:
Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.
271 lines (270 loc) • 10.2 kB
TypeScript
/**
* A hierarchical feature option system for plugins and applications.
*
* @module
*/
import type { Nullable } from "./util.js";
/**
* Entry describing a feature option.
*
* @property default - Default enabled/disabled state for this feature option.
* @property defaultValue - Optional. Default value for value-based feature options.
* @property description - Description of the feature option for display or documentation.
* @property group - Optional. Grouping/category for the feature option.
* @property name - Name of the feature option (used in option strings).
*/
export interface FeatureOptionEntry {
default: boolean;
defaultValue?: number | string;
description: string;
group?: string;
name: string;
}
/**
* Entry describing a feature option category.
*
* @property description - Description of the category.
* @property name - Name of the category.
*/
export interface FeatureCategoryEntry {
description: string;
name: string;
}
/**
* Describes all possible scope hierarchy locations for a feature option.
*/
export type OptionScope = "controller" | "device" | "global" | "none";
/**
* 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 declare class FeatureOptions {
/**
* Default return value for unknown options (defaults to false).
*/
defaultReturnValue: boolean;
private _categories;
private _configuredOptions;
private _groups;
private _options;
private defaults;
private 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: FeatureCategoryEntry[], options: {
[index: string]: FeatureOptionEntry[];
}, configuredOptions?: never[]);
/**
* 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: string, device?: string, controller?: string): string;
/**
* 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: string): boolean;
/**
* 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: string, id?: string): boolean;
/**
* 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: FeatureCategoryEntry | string, option: FeatureOptionEntry | string): string;
/**
* 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: string, device?: string, controller?: string): Nullable<number | undefined>;
/**
* 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: string, device?: string, controller?: string): Nullable<number | undefined>;
/**
* 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: string, device: string): boolean;
/**
* 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: string): boolean;
/**
* 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: string): boolean;
/**
* 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: string, device?: string, controller?: string): OptionScope;
/**
* 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: string, device?: string, controller?: string): boolean;
/**
* 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: string, device?: string, controller?: string): Nullable<string | undefined>;
/**
* Return the list of available feature option categories.
*
* @returns Returns the current list of available feature option categories.
*/
get categories(): FeatureCategoryEntry[];
/**
* Set the list of available feature option categories.
*
* @param category - Array of available categories.
*/
set categories(category: FeatureCategoryEntry[]);
/**
* Return the list of currently configured feature options.
*
* @returns Returns the currently configured list of feature options.
*/
get configuredOptions(): string[];
/**
* Set the list of currently configured feature options.
*
* @param options - Array of configured feature options.
*/
set configuredOptions(options: string[]);
/**
* Return the list of available feature option groups.
*
* @returns Returns the current list of available feature option groups.
*/
get groups(): {
[index: string]: string[];
};
/**
* Return the list of available feature options.
*
* @returns Returns the current list of available feature options.
*/
get options(): {
[index: string]: FeatureOptionEntry[];
};
/**
* Set the list of available feature options.
*
* @param options - Array of available feature options.
*/
set options(options: {
[index: string]: FeatureOptionEntry[];
});
private generateDefaults;
private optionInfo;
private isOptionEnabled;
private optionRegex;
private parseOptionNumeric;
private valueRegex;
}