rclnodejs 1.6.0 → 1.7.0

package/lib/parameter_watcher.js

@@ -0,0 +1,309 @@
+// Copyright (c) 2025 Mahmoud Alghalayini. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const EventEmitter = require('events');
+const { TypeValidationError, OperationError } = require('./errors');
+const { normalizeNodeName } = require('./utils');
+const debug = require('debug')('rclnodejs:parameter_watcher');
+
+/**
+ * @class ParameterWatcher - Watches parameter changes on a remote node
+ *
+ * Subscribes to /parameter_events and emits 'change' events when
+ * watched parameters on the target node are modified.
+ *
+ * @extends EventEmitter
+ */
+class ParameterWatcher extends EventEmitter {
+  #node;
+  #paramClient;
+  #subscription;
+  #watchedParams;
+  #remoteNodeName;
+  #destroyed;
+
+  /**
+   * Create a ParameterWatcher instance.
+   * Note: Use node.createParameterWatcher() instead of calling this directly.
+   *
+   * @param {object} node - The local rclnodejs Node instance
+   * @param {string} remoteNodeName - Name of the remote node to watch
+   * @param {string[]} parameterNames - Array of parameter names to watch
+   * @param {object} [options] - Options for the parameter client
+   * @param {number} [options.timeout=5000] - Default timeout for parameter operations
+   * @hideconstructor
+   */
+  constructor(node, remoteNodeName, parameterNames, options = {}) {
+    super();
+
+    if (!node || typeof node.createParameterClient !== 'function') {
+      throw new TypeValidationError('node', node, 'Node instance', {
+        entityType: 'parameter watcher',
+      });
+    }
+
+    if (typeof remoteNodeName !== 'string' || remoteNodeName.trim() === '') {
+      throw new TypeValidationError(
+        'remoteNodeName',
+        remoteNodeName,
+        'non-empty string',
+        {
+          entityType: 'parameter watcher',
+        }
+      );
+    }
+
+    if (!Array.isArray(parameterNames) || parameterNames.length === 0) {
+      throw new TypeValidationError(
+        'parameterNames',
+        parameterNames,
+        'non-empty array',
+        {
+          entityType: 'parameter watcher',
+        }
+      );
+    }
+
+    this.#node = node;
+    this.#watchedParams = new Set(parameterNames);
+    this.#paramClient = node.createParameterClient(remoteNodeName, options);
+    // Cache the remote node name for error messages (in case paramClient is destroyed)
+    this.#remoteNodeName = this.#paramClient.remoteNodeName;
+    this.#subscription = null;
+    this.#destroyed = false;
+
+    debug(
+      'Created ParameterWatcher for node=%s, params=%o',
+      remoteNodeName,
+      parameterNames
+    );
+  }
+
+  /**
+   * Get the remote node name being watched.
+   * @type {string}
+   * @readonly
+   */
+  get remoteNodeName() {
+    return this.#remoteNodeName;
+  }
+
+  /**
+   * Get the list of watched parameter names.
+   * @type {string[]}
+   * @readonly
+   */
+  get watchedParameters() {
+    return Array.from(this.#watchedParams);
+  }
+
+  /**
+   * Start watching for parameter changes.
+   * Waits for the remote node's parameter services and subscribes to parameter events.
+   *
+   * @param {number} [timeout=5000] - Timeout in milliseconds to wait for services
+   * @returns {Promise<boolean>} Resolves to true when watching has started
+   * @throws {Error} If the watcher has been destroyed
+   */
+  async start(timeout = 5000) {
+    this.#checkNotDestroyed();
+
+    debug('Starting ParameterWatcher for node=%s', this.remoteNodeName);
+
+    const available = await this.#paramClient.waitForService(timeout);
+
+    if (!available) {
+      debug(
+        'Parameter services not available for node=%s',
+        this.remoteNodeName
+      );
+      return false;
+    }
+
+    if (!this.#subscription) {
+      this.#subscription = this.#node.createSubscription(
+        'rcl_interfaces/msg/ParameterEvent',
+        '/parameter_events',
+        (event) => this.#handleParameterEvent(event)
+      );
+
+      debug('Subscribed to /parameter_events');
+    }
+
+    return true;
+  }
+
+  /**
+   * Get current values of all watched parameters.
+   *
+   * @param {object} [options] - Options for the parameter client
+   * @param {number} [options.timeout] - Timeout in milliseconds
+   * @param {AbortSignal} [options.signal] - AbortSignal for cancellation
+   * @returns {Promise<Parameter[]>} Array of Parameter objects
+   * @throws {Error} If the watcher has been destroyed
+   */
+  async getCurrentValues(options) {
+    this.#checkNotDestroyed();
+    return await this.#paramClient.getParameters(
+      Array.from(this.#watchedParams),
+      options
+    );
+  }
+
+  /**
+   * Add a parameter name to the watch list.
+   *
+   * @param {string} name - Parameter name to watch
+   * @throws {TypeError} If name is not a string
+   * @throws {Error} If the watcher has been destroyed
+   */
+  addParameter(name) {
+    this.#checkNotDestroyed();
+
+    if (typeof name !== 'string' || name.trim() === '') {
+      throw new TypeValidationError('name', name, 'non-empty string', {
+        entityType: 'parameter watcher',
+        entityName: this.remoteNodeName,
+      });
+    }
+
+    const wasAdded = !this.#watchedParams.has(name);
+    this.#watchedParams.add(name);
+
+    if (wasAdded) {
+      debug('Added parameter to watch list: %s', name);
+    }
+  }
+
+  /**
+   * Remove a parameter name from the watch list.
+   *
+   * @param {string} name - Parameter name to stop watching
+   * @returns {boolean} True if the parameter was in the watch list
+   * @throws {Error} If the watcher has been destroyed
+   */
+  removeParameter(name) {
+    this.#checkNotDestroyed();
+
+    const wasRemoved = this.#watchedParams.delete(name);
+
+    if (wasRemoved) {
+      debug('Removed parameter from watch list: %s', name);
+    }
+
+    return wasRemoved;
+  }
+
+  /**
+   * Check if the watcher has been destroyed.
+   *
+   * @returns {boolean} True if destroyed
+   */
+  isDestroyed() {
+    return this.#destroyed;
+  }
+
+  /**
+   * Destroy the watcher and clean up resources.
+   * Unsubscribes from parameter events and destroys the parameter client.
+   */
+  destroy() {
+    if (this.#destroyed) {
+      return;
+    }
+
+    debug('Destroying ParameterWatcher for node=%s', this.remoteNodeName);
+
+    if (this.#subscription) {
+      try {
+        this.#node.destroySubscription(this.#subscription);
+      } catch (error) {
+        debug('Error destroying subscription: %s', error.message);
+      }
+      this.#subscription = null;
+    }
+
+    if (this.#paramClient) {
+      try {
+        this.#node.destroyParameterClient(this.#paramClient);
+      } catch (error) {
+        debug('Error destroying parameter client: %s', error.message);
+      }
+      this.#paramClient = null;
+    }
+
+    this.removeAllListeners();
+
+    this.#destroyed = true;
+  }
+
+  /**
+   * Handle parameter event from /parameter_events topic.
+   * @private
+   */
+  #handleParameterEvent(event) {
+    if (normalizeNodeName(event.node) !== this.remoteNodeName) {
+      return;
+    }
+
+    const relevantChanges = [];
+
+    if (event.new_parameters) {
+      const newParams = event.new_parameters.filter((p) =>
+        this.#watchedParams.has(p.name)
+      );
+      relevantChanges.push(...newParams);
+    }
+
+    if (event.changed_parameters) {
+      const changedParams = event.changed_parameters.filter((p) =>
+        this.#watchedParams.has(p.name)
+      );
+      relevantChanges.push(...changedParams);
+    }
+
+    if (event.deleted_parameters) {
+      const deletedParams = event.deleted_parameters.filter((p) =>
+        this.#watchedParams.has(p.name)
+      );
+      relevantChanges.push(...deletedParams);
+    }
+
+    if (relevantChanges.length > 0) {
+      debug(
+        'Parameter change detected: %o',
+        relevantChanges.map((p) => p.name)
+      );
+      this.emit('change', relevantChanges);
+    }
+  }
+
+  /**
+   * Check if the watcher has been destroyed and throw if so.
+   * @private
+   */
+  #checkNotDestroyed() {
+    if (this.#destroyed) {
+      throw new OperationError('ParameterWatcher has been destroyed', {
+        code: 'WATCHER_DESTROYED',
+        entityType: 'parameter watcher',
+        entityName: this.remoteNodeName,
+      });
+    }
+  }
+}
+
+module.exports = ParameterWatcher;

package/lib/qos.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const { TypeValidationError } = require('./errors.js');
+
 /**
  * Enum for HistoryPolicy
  * @readonly
@@ -129,7 +131,9 @@ class QoS {
    */
   set history(history) {
     if (typeof history !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('history', history, 'number', {
+        entityType: 'qos',
+      });
     }
 
     this._history = history;
@@ -154,7 +158,9 @@ class QoS {
    */
   set depth(depth) {
     if (typeof depth !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('depth', depth, 'number', {
+        entityType: 'qos',
+      });
     }
 
     this._depth = depth;
@@ -179,7 +185,9 @@ class QoS {
    */
   set reliability(reliability) {
     if (typeof reliability !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('reliability', reliability, 'number', {
+        entityType: 'qos',
+      });
     }
 
     this._reliability = reliability;
@@ -204,7 +212,9 @@ class QoS {
    */
   set durability(durability) {
     if (typeof durability !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('durability', durability, 'number', {
+        entityType: 'qos',
+      });
     }
 
     this._durability = durability;
@@ -229,7 +239,14 @@ class QoS {
    */
   set avoidRosNameSpaceConventions(avoidRosNameSpaceConventions) {
     if (typeof avoidRosNameSpaceConventions !== 'boolean') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'avoidRosNameSpaceConventions',
+        avoidRosNameSpaceConventions,
+        'boolean',
+        {
+          entityType: 'qos',
+        }
+      );
     }
 
     this._avoidRosNameSpaceConventions = avoidRosNameSpaceConventions;

package/lib/rate.js

@@ -15,6 +15,7 @@
 const rclnodejs = require('../index.js');
 const Context = require('./context.js');
 const NodeOptions = require('./node_options.js');
+const { OperationError } = require('./errors.js');
 
 const NOP_FN = () => {};
 
@@ -86,7 +87,11 @@ class Rate {
    */
   async sleep() {
     if (this.isCanceled()) {
-      throw new Error('Rate has been cancelled.');
+      throw new OperationError('Rate has been cancelled', {
+        code: 'RATE_CANCELLED',
+        entityType: 'rate',
+        details: { frequency: this._hz },
+      });
     }
 
     return new Promise((resolve) => {

package/lib/serialization.js

@@ -15,6 +15,7 @@
 'use strict';
 
 const rclnodejs = require('./native_loader.js');
+const { TypeValidationError } = require('./errors.js');
 
 class Serialization {
   /**
@@ -25,7 +26,9 @@ class Serialization {
    */
   static serializeMessage(message, typeClass) {
     if (!(message instanceof typeClass)) {
-      throw new TypeError('Message must be a valid ros2 message type');
+      throw new TypeValidationError('message', message, typeClass.name, {
+        entityType: 'serializer',
+      });
     }
     return rclnodejs.serialize(
       typeClass.type().pkgName,
@@ -43,7 +46,9 @@ class Serialization {
    */
   static deserializeMessage(buffer, typeClass) {
     if (!(buffer instanceof Buffer)) {
-      throw new TypeError('Buffer is required for deserialization');
+      throw new TypeValidationError('buffer', buffer, 'Buffer', {
+        entityType: 'serializer',
+      });
     }
     const rosMsg = new typeClass();
     rclnodejs.deserialize(

package/lib/time.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const Duration = require('./duration.js');
 const ClockType = require('./clock_type.js');
+const { TypeValidationError, RangeValidationError } = require('./errors.js');
 const S_TO_NS = 10n ** 9n;
 
 /**
@@ -36,29 +37,49 @@ class Time {
     clockType = ClockType.SYSTEM_TIME
   ) {
     if (typeof seconds !== 'bigint') {
-      throw new TypeError('Invalid argument of seconds');
+      throw new TypeValidationError('seconds', seconds, 'bigint', {
+        entityType: 'time',
+      });
     }
 
     if (typeof nanoseconds !== 'bigint') {
-      throw new TypeError('Invalid argument of nanoseconds');
+      throw new TypeValidationError('nanoseconds', nanoseconds, 'bigint', {
+        entityType: 'time',
+      });
     }
 
     if (typeof clockType !== 'number') {
-      throw new TypeError('Invalid argument of clockType');
+      throw new TypeValidationError('clockType', clockType, 'number', {
+        entityType: 'time',
+      });
     }
 
     if (seconds < 0n) {
-      throw new RangeError('seconds value must not be negative');
+      throw new RangeValidationError('seconds', seconds, '>= 0', {
+        entityType: 'time',
+      });
     }
 
     if (nanoseconds < 0n) {
-      throw new RangeError('nanoseconds value must not be negative');
+      throw new RangeValidationError('nanoseconds', nanoseconds, '>= 0', {
+        entityType: 'time',
+      });
     }
 
     const total = seconds * S_TO_NS + nanoseconds;
     if (total >= 2n ** 63n) {
-      throw new RangeError(
-        'Total nanoseconds value is too large to store in C time point.'
+      throw new RangeValidationError(
+        'total nanoseconds',
+        total,
+        '< 2^63 (max C time point)',
+        {
+          entityType: 'time',
+          details: {
+            seconds: seconds,
+            nanoseconds: nanoseconds,
+            total: total,
+          },
+        }
       );
     }
     this._nanoseconds = total;
@@ -116,7 +137,9 @@ class Time {
         this._clockType
       );
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -127,7 +150,18 @@ class Time {
   sub(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't subtract times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return new Duration(0n, this._nanoseconds - other._nanoseconds);
     } else if (other instanceof Duration) {
@@ -137,7 +171,9 @@ class Time {
         this._clockType
       );
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time or Duration', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -148,11 +184,24 @@ class Time {
   eq(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds === other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -163,10 +212,24 @@ class Time {
   ne(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds !== other.nanoseconds;
     }
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -177,11 +240,24 @@ class Time {
   lt(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds < other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -192,11 +268,24 @@ class Time {
   lte(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds <= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -207,11 +296,24 @@ class Time {
   gt(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds > other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -222,11 +324,24 @@ class Time {
   gte(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds >= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**