rclnodejs 1.6.0 → 1.8.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/publisher.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const debug = require('debug')('rclnodejs:publisher');
 const Entity = require('./entity.js');
+const { assertValidMessage } = require('./message_validation.js');
 
 /**
  * @class - Class representing a Publisher in ROS
@@ -27,6 +28,11 @@ class Publisher extends Entity {
   constructor(handle, typeClass, topic, options, node, eventCallbacks) {
     super(handle, typeClass, options);
     this._node = node;
+    this._validateMessages = options.validateMessages || false;
+    this._validationOptions = options.validationOptions || {
+      strict: true,
+      checkTypes: true,
+    };
     if (node && eventCallbacks) {
       this._events = eventCallbacks.createEventHandlers(this.handle);
       node._events.push(...this._events);
@@ -44,12 +50,24 @@ class Publisher extends Entity {
    * Publish a message
    * @param {object|Buffer} message - The message to be sent, could be kind of JavaScript message generated from .msg
    *                                  or be a Buffer for a raw message.
+   * @param {object} [options] - Publish options
+   * @param {boolean} [options.validate] - Override validateMessages setting for this publish call
    * @return {undefined}
+   * @throws {MessageValidationError} If validation is enabled and message is invalid
    */
-  publish(message) {
+  publish(message, options = {}) {
     if (message instanceof Buffer) {
       rclnodejs.publishRawMessage(this._handle, message);
     } else {
+      const shouldValidate =
+        options.validate !== undefined
+          ? options.validate
+          : this._validateMessages;
+
+      if (shouldValidate && !(message instanceof this._typeClass)) {
+        assertValidMessage(message, this._typeClass, this._validationOptions);
+      }
+
       // Enables call by plain object/number/string argument
       //  e.g. publisher.publish(3.14);
       //       publisher.publish('The quick brown fox...');
@@ -65,6 +83,35 @@ class Publisher extends Entity {
     debug(`Message of topic ${this.topic} has been published.`);
   }
 
+  /**
+   * Whether messages will be validated before publishing.
+   * @type {boolean}
+   */
+  get willValidateMessage() {
+    return this._validateMessages;
+  }
+
+  /**
+   * Enable or disable message validation for this publisher.
+   * @param {boolean} value - Whether to validate messages before publishing
+   */
+  set willValidateMessage(value) {
+    this._validateMessages = value;
+  }
+
+  /**
+   * Set validation options for this publisher.
+   * @param {object} options - Validation options
+   * @param {boolean} [options.strict=true] - Throw on unknown fields
+   * @param {boolean} [options.checkTypes=true] - Validate field types
+   * @param {boolean} [options.checkRequired=false] - Check for missing fields
+   */
+  setValidation(options) {
+    if (options && Object.keys(options).length > 0) {
+      this._validationOptions = { ...this._validationOptions, ...options };
+    }
+  }
+
   static createPublisher(node, typeClass, topic, options, eventCallbacks) {
     let type = typeClass.type();
     let handle = rclnodejs.createPublisher(
@@ -112,6 +159,14 @@ class Publisher extends Entity {
     return rclnodejs.waitForAllAcked(this._handle, timeout);
   }
 
+  /**
+   * Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC).
+   * @return {undefined}
+   */
+  assertLiveliness() {
+    rclnodejs.assertLiveliness(this._handle);
+  }
+
   /**
    * Get the event handlers for this publisher.
    * @returns {Array} The array of event handlers for this publisher.

package/lib/qos.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const { TypeValidationError } = require('./errors.js');
+
 /**
  * Enum for HistoryPolicy
  * @readonly
@@ -56,6 +58,24 @@ let DurabilityPolicy = {
   RMW_QOS_POLICY_DURABILITY_VOLATILE: 2,
 };
 
+/**
+ * Enum for LivelinessPolicy
+ * @readonly
+ * @enum {number}
+ */
+let LivelinessPolicy = {
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT: 0,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_AUTOMATIC: 1,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC: 3,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_UNKNOWN: 4,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE: 5,
+};
+
 /** Class representing middleware quality of service */
 class QoS {
   /**
@@ -71,12 +91,14 @@ class QoS {
     depth = 0,
     reliability = ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT,
     durability = DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT,
+    liveliness = LivelinessPolicy.RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT,
     avoidRosNameSpaceConventions = false
   ) {
     this._history = history;
     this._depth = depth;
     this._reliability = reliability;
     this._durability = durability;
+    this._liveliness = liveliness;
     this._avoidRosNameSpaceConventions = avoidRosNameSpaceConventions;
   }
 
@@ -110,6 +132,16 @@ class QoS {
     return DurabilityPolicy;
   }
 
+  /**
+   * Get LivelinessPolicy enum.
+   * @name QoS#static get:LivelinessPolicy
+   * @function
+   * @return {LivelinessPolicy}
+   */
+  static get LivelinessPolicy() {
+    return LivelinessPolicy;
+  }
+
   /**
    * Get the history value.
    * @name QoS#get:history
@@ -129,7 +161,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 +188,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 +215,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,12 +242,41 @@ 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;
   }
 
+  /**
+   * Get the liveliness value.
+   * @name QoS#get:liveliness
+   * @function
+   * @return {number}
+   */
+  get liveliness() {
+    return this._liveliness;
+  }
+
+  /**
+   * Set the liveliness value.
+   * @param {number} liveliness - value to be set.
+   * @name QoS#set:liveliness
+   * @function
+   * @return {undefined}
+   */
+  set liveliness(liveliness) {
+    if (typeof liveliness !== 'number') {
+      throw new TypeValidationError('liveliness', liveliness, 'number', {
+        entityType: 'qos',
+      });
+    }
+
+    this._liveliness = liveliness;
+  }
+
   /**
    * Get the avoidRosNameSpaceConventions value.
    * @name QoS#get:avoidRosNameSpaceConventions
@@ -229,7 +296,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

@@ -151,6 +151,14 @@ class Subscription extends Entity {
       : this.clearContentFilter();
   }
 
+  /**
+   * Get the current content-filter.
+   * @returns {object} - The content-filter description {expression: string, parameters: string[]} or undefined if not set/supported.
+   */
+  getContentFilter() {
+    return rclnodejs.getContentFilter(this.handle);
+  }
+
   /**
    * Clear the current content-filter. No filtering is to be applied.
    * @returns {boolean} - True if successful; false otherwise