Adds limits subscription to the Telemetry API (#6735)

* Add subscription for limits for domain objects
---------

Co-authored-by: John Hill <john.c.hill@nasa.gov>
Co-authored-by: Andrew Henry <akhenry@gmail.com>

src/api/telemetry/TelemetryAPI.js

@@ -489,6 +489,62 @@ export default class TelemetryAPI {
     }.bind(this);
   }
 
+  /**
+   * Subscribe to run-time changes in configured telemetry limits for a specific domain object.
+   * The callback will be called whenever data is received from a
+   * limit provider.
+   *
+   * @method subscribeToLimits
+   * @memberof module:openmct.TelemetryAPI~TelemetryProvider#
+   * @param {module:openmct.DomainObject} domainObject the object
+   *        which has associated limits
+   * @param {Function} callback the callback to invoke with new data, as
+   *        it becomes available
+   * @returns {Function} a function which may be called to terminate
+   *          the subscription
+   */
+  subscribeToLimits(domainObject, callback) {
+    if (domainObject.type === 'unknown') {
+      return () => {};
+    }
+
+    const provider = this.#findLimitEvaluator(domainObject);
+
+    if (!this.limitsSubscribeCache) {
+      this.limitsSubscribeCache = {};
+    }
+
+    const keyString = objectUtils.makeKeyString(domainObject.identifier);
+    let subscriber = this.limitsSubscribeCache[keyString];
+
+    if (!subscriber) {
+      subscriber = this.limitsSubscribeCache[keyString] = {
+        callbacks: [callback]
+      };
+      if (provider && provider.subscribeToLimits) {
+        subscriber.unsubscribe = provider.subscribeToLimits(domainObject, function (value) {
+          subscriber.callbacks.forEach(function (cb) {
+            cb(value);
+          });
+        });
+      } else {
+        subscriber.unsubscribe = function () {};
+      }
+    } else {
+      subscriber.callbacks.push(callback);
+    }
+
+    return function unsubscribe() {
+      subscriber.callbacks = subscriber.callbacks.filter(function (cb) {
+        return cb !== callback;
+      });
+      if (subscriber.callbacks.length === 0) {
+        subscriber.unsubscribe();
+        delete this.limitsSubscribeCache[keyString];
+      }
+    }.bind(this);
+  }
+
   /**
    * Request telemetry staleness for a domain object.
    *
@@ -676,7 +732,7 @@ export default class TelemetryAPI {
    *
    * @param {module:openmct.DomainObject} domainObject the domain
    *        object for which to get limits
-   * @returns {module:openmct.TelemetryAPI~LimitEvaluator}
+   * @returns {LimitsResponseObject}
    * @method limits
    * @memberof module:openmct.TelemetryAPI~TelemetryProvider#
    */
@@ -723,18 +779,8 @@ export default class TelemetryAPI {
    *
    * @param {module:openmct.DomainObject} domainObject the domain
    *        object for which to display limits
-   * @returns {module:openmct.TelemetryAPI~LimitEvaluator}
-   * @method limits returns a limits object of
-   * type {
-   *          level1: {
-   *              low: { key1: value1, key2: value2, color: <supportedColor> },
-   *              high: { key1: value1, key2: value2, color: <supportedColor> }
-   *          },
-   *          level2: {
-   *              low: { key1: value1, key2: value2 },
-   *              high: { key1: value1, key2: value2 }
-   *          }
-   *       }
+   * @returns {LimitsResponseObject}
+   * @method limits returns a limits object of type {LimitsResponseObject}
    *  supported colors are purple, red, orange, yellow and cyan
    * @memberof module:openmct.TelemetryAPI~TelemetryProvider#
    */
@@ -766,7 +812,7 @@ export default class TelemetryAPI {
  * @param {*} datum the telemetry datum to evaluate
  * @param {TelemetryProperty} the property to check for limit violations
  * @memberof module:openmct.TelemetryAPI~LimitEvaluator
- * @returns {module:openmct.TelemetryAPI~LimitViolation} metadata about
+ * @returns {LimitViolation} metadata about
  *          the limit violation, or undefined if a value is within limits
  */
 
@@ -777,6 +823,42 @@ export default class TelemetryAPI {
  * @property {string} cssClass the class (or space-separated classes) to
  *           apply to display elements for values which violate this limit
  * @property {string} name the human-readable name for the limit violation
+ * @property {number} low a lower limit for violation
+ * @property {number} high a higher limit violation
+ */
+
+/**
+ * @typedef {object} LimitsResponseObject
+ * @memberof {module:openmct.TelemetryAPI~}
+ * @property {LimitDefinition} limitLevel the level name and it's limit definition
+ * @example {
+ *  [limitLevel]: {
+ *    low: {
+ *      color: lowColor,
+ *      value: lowValue
+ *    },
+ *    high: {
+ *      color: highColor,
+ *      value: highValue
+ *    }
+ *  }
+ * }
+ */
+
+/**
+ * Limit defined for a telemetry property.
+ * @typedef LimitDefinition
+ * @memberof {module:openmct.TelemetryAPI~}
+ * @property {LimitDefinitionValue} low a lower limit
+ * @property {LimitDefinitionValue} high a higher limit
+ */
+
+/**
+ * Limit definition for a Limit of a telemetry property.
+ * @typedef LimitDefinitionValue
+ * @memberof {module:openmct.TelemetryAPI~}
+ * @property {string} color color to represent this limit
+ * @property {Number} value the limit value
  */
 
 /**