rclnodejs 1.5.2 → 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/subscription.js

@@ -16,6 +16,7 @@
 
 const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
+const { applySerializationMode } = require('./message_serialization.js');
 const debug = require('debug')('rclnodejs:subscription');
 
 /**
@@ -42,6 +43,7 @@ class Subscription extends Entity {
     this._topic = topic;
     this._callback = callback;
     this._isRaw = options.isRaw || false;
+    this._serializationMode = options.serializationMode || 'default';
     this._node = node;
 
     if (node && eventCallbacks) {
@@ -55,7 +57,13 @@ class Subscription extends Entity {
     if (this._isRaw) {
       this._callback(msg);
     } else {
-      this._callback(msg.toPlainObject(this.typedArrayEnabled));
+      let message = msg.toPlainObject(this.typedArrayEnabled);
+
+      if (this._serializationMode !== 'default') {
+        message = applySerializationMode(message, this._serializationMode);
+      }
+
+      this._callback(message);
     }
   }
 
@@ -109,6 +117,13 @@ class Subscription extends Entity {
     return this._isRaw;
   }
 
+  /**
+   * @type {string}
+   */
+  get serializationMode() {
+    return this._serializationMode;
+  }
+
   /**
    * Test if the RMW supports content-filtered topics and that this subscription
    * has an active wellformed content-filter.