homebridge-plugin-utils 1.0.0

package/LICENSE.md

@@ -0,0 +1,16 @@
+Internet Systems Consortium License
+===================================
+
+Copyright (c) `2017-2024`, `HJD https://github.com/hjdhjd`
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+<SPAN ALIGN="CENTER" STYLE="text-align:center">
+<DIV ALIGN="CENTER" STYLE="text-align:center">
+
+# Homebridge Plugin Utilities
+[![Downloads](https://img.shields.io/npm/dt/homebridge-plugin-utils?color=%23491F59&logo=icloud&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/homebridge-plugin-utils)
+[![Version](https://img.shields.io/npm/v/homebridge-plugin-utils?color=%23491F59&label=Latest%20Version&logo=homebridge&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/homebridge-plugin-utils)
+[![Homebridge Discord](https://img.shields.io/discord/432663330281226270?color=%23491F59&label=Discord&logo=discord&logoColor=%23FFFFFF&style=for-the-badge)](https://discord.gg/QXqfHEW)
+</DIV>
+</SPAN>
+
+`homebridge-plugin-utils` is a utility library for [Homebridge](https://homebridge.io) [plugins](https://developers.homebridge.io) that aims to provide a set of common core capabilities that can accelerate and streamline plugin development. It's opinionated and largely derived from my other plugins and my desire to increase code reuse and make it easier to provide rich capabilities across all my plugins so that each of my plugins can focus on providing their unique capabilities rather than copying over the same capabilities (feature options, MQTT support, and a rich webUI interface to name a few) time after time.
+
+The design decisions are driven by my own needs as I continue to create, evolve, and maintain my plugins but I also wanted to provide these as a resource to others, should it be of interest.
+
+### Features
+
+- **Feature options*.* Feature options are a hierarchical configuration system and matching webUI that allows users to set global defaults and override them at a granular level, enabling easier mass-customization of capabilities. For plugins that can potentially enumerate dozens of devices, this comes in quite handy so you don't need to configure each and every device, and instead you can focus on the exceptions.
+
+- **Configuration webUI.** This a rich, custom webUI for enumerating all the devices a plugin knows about, and configuring feature options.
+
+- **MQTT client.** Building in MQTT client capabilities is made easier through a set of utilities that allow you to easily publish and subscribe to events.
+
+- **And more...**
+
+## Documentation
+* Coming in the future.
+
+## Plugin Development Dashboard
+This is mostly of interest to the true developer nerds amongst us.
+
+[![License](https://img.shields.io/npm/l/homebridge-plugin-utils?color=%23491F59&logo=open%20source%20initiative&logoColor=%23FFFFFF&style=for-the-badge)](https://github.com/hjdhjd/homebridge-plugin-utils/blob/main/LICENSE.md)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/hjdhjd/homebridge-plugin-utils/ci.yml?branch=main&color=%23491F59&logo=github-actions&logoColor=%23FFFFFF&style=for-the-badge)](https://github.com/hjdhjd/homebridge-plugin-utils/actions?query=workflow%3A%22Continuous+Integration%22)
+[![Dependencies](https://img.shields.io/librariesio/release/npm/homebridge-plugin-utils?color=%23491F59&logo=dependabot&style=for-the-badge)](https://libraries.io/npm/homebridge-plugin-utils)
+[![GitHub commits since latest release (by SemVer)](https://img.shields.io/github/commits-since/hjdhjd/homebridge-plugin-utils/latest?color=%23491F59&logo=github&sort=semver&style=for-the-badge)](https://github.com/hjdhjd/homebridge-plugin-utils/commits/main)

package/build/eslint-rules.mjs

@@ -0,0 +1,82 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * eslint-rules.mjs: Opinionated default linting rules for Homebridge plugins.
+ */
+import stylistic from "@stylistic/eslint-plugin";
+import tsEslint from "@typescript-eslint/eslint-plugin";
+
+// ESlint plugins to use.
+const eslintPlugins = {
+
+  "@stylistic": stylistic,
+  "@typescript-eslint": tsEslint
+};
+
+// TypeScript-specific rules.
+const eslintTsRules = {
+
+  ...tsEslint.configs.strictTypeChecked,
+  ...tsEslint.configs.stylisticTypeChecked,
+  "@typescript-eslint/explicit-function-return-type": "warn",
+  "@typescript-eslint/explicit-module-boundary-types": "warn",
+  "@typescript-eslint/no-explicit-any": "warn",
+  "@typescript-eslint/no-floating-promises": ["warn", { "ignoreIIFE": true }],
+  "@typescript-eslint/no-non-null-assertion": "warn",
+  "no-dupe-class-members": "off",
+  "no-undef": "off",
+  "no-unused-vars": "off"
+};
+
+// JavaScript-specific rules.
+const eslintJsRules = {
+
+  ...tsEslint.configs.disableTypeChecked,
+  "@typescript-eslint/no-floating-promises": "off"
+};
+
+// Rules that exist across both JavaScript and TypeScript files.
+const eslintCommonRules = {
+
+  ...tsEslint.configs.eslintRecommended,
+  "@stylistic/brace-style": "error",
+  "@stylistic/comma-dangle": "error",
+  "@stylistic/generator-star-spacing": "error",
+  "@stylistic/implicit-arrow-linebreak": "error",
+  "@stylistic/indent": ["warn", 2, { "SwitchCase": 1 }],
+  "@stylistic/keyword-spacing": ["error",
+    { "overrides": { "catch": { "after": false }, "for": { "after": false }, "if": { "after": false }, "switch": { "after": false}, "while": { "after": false } } }],
+  "@stylistic/linebreak-style": ["warn", "unix"],
+  "@stylistic/lines-between-class-members": ["warn", "always", { "exceptAfterSingleLine": true }],
+  "@stylistic/max-len": ["warn", 170],
+  "@stylistic/no-tabs": "error",
+  "@stylistic/no-trailing-spaces": "error",
+  "@stylistic/semi": ["warn", "always"],
+  "@stylistic/space-before-function-paren": ["error", { "anonymous": "never", "asyncArrow": "always", "named": "never" }],
+  "@stylistic/space-in-parens": "error",
+  "@stylistic/space-infix-ops": "error",
+  "@stylistic/space-unary-ops": "error",
+  "@typescript-eslint/no-this-alias": "warn",
+  "camelcase": "warn",
+  "curly": ["warn", "all"],
+  "dot-notation": "warn",
+  "eqeqeq": "warn",
+  "no-await-in-loop": "warn",
+  "no-console": "warn",
+  "prefer-arrow-callback": "warn",
+  "quotes": ["warn", "double", { "avoidEscape": true }],
+  "sort-imports": "warn",
+  "sort-keys": "warn",
+  "sort-vars": "warn"
+};
+
+export default {
+
+  plugins: eslintPlugins,
+  rules: {
+
+    common: eslintCommonRules,
+    js: eslintJsRules,
+    ts: eslintTsRules
+  }
+};
+

package/build/tsconfig.json

@@ -0,0 +1,45 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * tsconfig.json: Default TypeScript transpiler options for ESM Homebridge plugins.
+ */
+{
+  "compilerOptions": {
+
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "lib": [
+
+      "DOM",
+      "ES2022"
+    ],
+
+    "module": "ES2022",
+    "moduleResolution":"node",
+    "sourceMap": true,
+    "strict": true,
+    "target": "ES2022"
+  }
+}
+/* When creating your own tsconfig.json, use the following as a starting point to inherit these defaults:
+ *
+ * {
+ *   "compilerOptions": {
+ * 
+ *     "outDir": "dist",
+ *     "rootDir": "src"
+ *   },
+ * 
+ *   "extends": "./build/tsconfig.json",
+ * 
+ *   "include": [
+ * 
+ *     "build",
+ *     "eslint.config.mjs",
+ *     "src",
+ *     "ui"
+ *   ]
+ * }
+ */

package/dist/featureoptions.d.ts

@@ -0,0 +1,177 @@
+export interface FeatureOptionEntry {
+    default: boolean;
+    defaultValue?: number;
+    description: string;
+    group?: string;
+    name: string;
+}
+export interface FeatureCategoryEntry {
+    description: string;
+    name: string;
+    validFor: string[];
+}
+type OptionScope = "controller" | "device" | "global" | "none";
+export declare class FeatureOptions {
+    private _categories;
+    private _configuredOptions;
+    private _groups;
+    private _options;
+    defaultReturnValue: boolean;
+    private defaults;
+    private valueOptions;
+    constructor(categories: FeatureCategoryEntry[], options: {
+        [index: string]: FeatureOptionEntry[];
+    }, configuredOptions: string[]);
+    color(option: string, device?: 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 value        - Value to parse.
+     *
+     * @returns Returns a floating point number from a string, or `undefined` if it couldn't be parsed.
+     */
+    getFloat(value: string | undefined): number | undefined;
+    /**
+     * Parse an integer feature option value.
+     *
+     * @param value        - Value to parse.
+     *
+     * @returns Returns an integer from a string, or `undefined` if it couldn't be parsed.
+     */
+    getInteger(value: string | undefined): 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` or `undefined` if none.
+     */
+    value(option: string, device?: string, controller?: string): 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 options       - Array of available feature options.
+     */
+    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 getOptionInfo;
+    private isOptionEnabled;
+    private optionRegex;
+    private parseOptionNumeric;
+    private valueRegex;
+}
+export {};