rclnodejs 1.8.3 → 1.9.0

package/lib/node.js

@@ -40,12 +40,18 @@ const {
 const ParameterService = require('./parameter_service.js');
 const ParameterClient = require('./parameter_client.js');
 const ParameterWatcher = require('./parameter_watcher.js');
+const ParameterEventHandler = require('./parameter_event_handler.js');
 const Publisher = require('./publisher.js');
 const QoS = require('./qos.js');
 const Rates = require('./rate.js');
 const Service = require('./service.js');
 const Subscription = require('./subscription.js');
 const ObservableSubscription = require('./observable_subscription.js');
+const MessageInfo = require('./message_info.js');
+const {
+  declareQosParameters,
+  _resolveQoS,
+} = require('./qos_overriding_options.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
@@ -148,13 +154,16 @@ class Node extends rclnodejs.ShadowNode {
     this._actionServers = [];
     this._parameterClients = [];
     this._parameterWatchers = [];
+    this._parameterEventHandlers = [];
     this._rateTimerServer = null;
     this._parameterDescriptors = new Map();
     this._parameters = new Map();
     this._parameterService = null;
     this._typeDescriptionService = null;
     this._parameterEventPublisher = null;
+    this._preSetParametersCallbacks = [];
     this._setParametersCallbacks = [];
+    this._postSetParametersCallbacks = [];
     this._logger = new Logging(rclnodejs.getNodeLoggerName(this.handle));
     this._spinning = false;
     this._enableRosout = options.enableRosout;
@@ -247,8 +256,14 @@ class Node extends rclnodejs.ShadowNode {
 
     timersReady.forEach((timer) => {
       if (timer.isReady()) {
-        rclnodejs.callTimer(timer.handle);
-        timer.callback();
+        let timerInfo;
+        if (typeof rclnodejs.callTimerWithInfo === 'function') {
+          timerInfo = rclnodejs.callTimerWithInfo(timer.handle);
+          timer.callback(timerInfo);
+        } else {
+          rclnodejs.callTimer(timer.handle);
+          timer.callback();
+        }
       }
     });
 
@@ -269,9 +284,22 @@ class Node extends rclnodejs.ShadowNode {
       this._runWithMessageType(
         subscription.typeClass,
         (message, deserialize) => {
-          let success = rclnodejs.rclTake(subscription.handle, message);
-          if (success) {
-            subscription.processResponse(deserialize());
+          if (subscription.wantsMessageInfo) {
+            let rawInfo = rclnodejs.rclTakeWithInfo(
+              subscription.handle,
+              message
+            );
+            if (rawInfo) {
+              subscription.processResponse(
+                deserialize(),
+                new MessageInfo(rawInfo)
+              );
+            }
+          } else {
+            let success = rclnodejs.rclTake(subscription.handle, message);
+            if (success) {
+              subscription.processResponse(deserialize());
+            }
           }
         }
       );
@@ -606,15 +634,43 @@ class Node extends rclnodejs.ShadowNode {
   /**
    * Create a Timer.
    * @param {bigint} period - The number representing period in nanoseconds.
-   * @param {function} callback - The callback to be called when timeout.
-   * @param {Clock} [clock] - The clock which the timer gets time from.
+   * @param {function} callback - The callback to be called when the timer fires.
+   *   On distros with native support, the callback receives a `TimerInfo` object
+   *   describing the expected and actual call time.
+   * @param {object|Clock} [optionsOrClock] - Timer options or the clock which the timer gets time from.
+   *   Supported options: `{ autostart?: boolean }`.
+   * @param {Clock} [clock] - The clock which the timer gets time from when options are provided.
    * @return {Timer} - An instance of Timer.
    */
-  createTimer(period, callback, clock = null) {
-    if (arguments.length === 3 && !(arguments[2] instanceof Clock)) {
-      clock = null;
-    } else if (arguments.length === 4) {
-      clock = arguments[3];
+  createTimer(period, callback, optionsOrClock = null, clock = null) {
+    let options = {};
+
+    if (optionsOrClock instanceof Clock.Clock) {
+      clock = optionsOrClock;
+    } else if (optionsOrClock === null || optionsOrClock === undefined) {
+      // Keep the 4th argument as the clock when the 3rd argument is omitted or explicitly null.
+    } else {
+      if (typeof optionsOrClock !== 'object' || Array.isArray(optionsOrClock)) {
+        throw new TypeValidationError(
+          'options',
+          optionsOrClock,
+          'object or Clock',
+          {
+            nodeName: this.name(),
+          }
+        );
+      }
+      options = optionsOrClock;
+    }
+
+    if (
+      arguments.length === 4 &&
+      clock !== null &&
+      !(clock instanceof Clock.Clock)
+    ) {
+      throw new TypeValidationError('clock', clock, 'Clock', {
+        nodeName: this.name(),
+      });
     }
 
     if (typeof period !== 'bigint') {
@@ -627,12 +683,27 @@ class Node extends rclnodejs.ShadowNode {
         nodeName: this.name(),
       });
     }
+    if (
+      options.autostart !== undefined &&
+      typeof options.autostart !== 'boolean'
+    ) {
+      throw new TypeValidationError(
+        'options.autostart',
+        options.autostart,
+        'boolean',
+        {
+          nodeName: this.name(),
+        }
+      );
+    }
 
     const timerClock = clock || this._clock;
+    const autostart = options.autostart ?? true;
     let timerHandle = rclnodejs.createTimer(
       timerClock.handle,
       this.context.handle,
-      period
+      period,
+      autostart
     );
     let timer = new Timer(timerHandle, period, callback);
     debug('Finish creating timer, period = %d.', period);
@@ -689,6 +760,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {object} options - The options argument used to parameterize the publisher.
    * @param {boolean} options.enableTypedArray - The topic will use TypedArray if necessary, default: true.
    * @param {QoS} options.qos - ROS Middleware "quality of service" settings for the publisher, default: QoS.profileDefault.
+   * @param {QoSOverridingOptions} [options.qosOverridingOptions] - If provided, declares read-only ROS parameters
+   *  for the specified QoS policies (e.g. `qos_overrides./topic.publisher.depth`). These can be overridden at
+   *  startup via `--ros-args -p` or `--params-file`. If qos is a profile string, it will be resolved to a
+   *  mutable QoS object before overrides are applied.
    * @param {PublisherEventCallbacks} eventCallbacks - The event callbacks for the publisher.
    * @return {Publisher} - An instance of Publisher.
    */
@@ -736,6 +811,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'publisher',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let publisher = publisherClass.createPublisher(
       this,
       typeClass,
@@ -779,6 +869,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {string[]} [options.contentFilter.parameters=undefined] - Array of strings that give values to
    *  the ‘parameters’ (i.e., "%n" tokens) in the filter_expression. The number of supplied parameters must
    *  fit with the requested values in the filter_expression (i.e., the number of %n tokens). default: undefined.
+   * @param {QoSOverridingOptions} [options.qosOverridingOptions] - If provided, declares read-only ROS parameters
+   *  for the specified QoS policies (e.g. `qos_overrides./topic.subscription.depth`). These can be overridden at
+   *  startup via `--ros-args -p` or `--params-file`. If qos is a profile string, it will be resolved to a
+   *  mutable QoS object before overrides are applied.
    * @param {SubscriptionCallback} callback - The callback to be call when receiving the topic subscribed. The topic will be an instance of null-terminated Buffer when options.isRaw is true.
    * @param {SubscriptionEventCallbacks} eventCallbacks - The event callbacks for the subscription.
    * @return {Subscription} - An instance of Subscription.
@@ -832,6 +926,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'subscription',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let subscription = Subscription.createSubscription(
       this,
       typeClass,
@@ -1082,6 +1191,7 @@ class Node extends rclnodejs.ShadowNode {
 
     this._parameterClients.forEach((paramClient) => paramClient.destroy());
     this._parameterWatchers.forEach((watcher) => watcher.destroy());
+    this._parameterEventHandlers.forEach((handler) => handler.destroy());
 
     this.context.onNodeDestroyed(this);
 
@@ -1102,6 +1212,7 @@ class Node extends rclnodejs.ShadowNode {
     this._actionServers = [];
     this._parameterClients = [];
     this._parameterWatchers = [];
+    this._parameterEventHandlers = [];
 
     if (this._rateTimerServer) {
       this._rateTimerServer.shutdown();
@@ -1214,6 +1325,38 @@ class Node extends rclnodejs.ShadowNode {
     watcher.destroy();
   }
 
+  /**
+   * Create a ParameterEventHandler that monitors parameter changes on any node.
+   *
+   * Unlike {@link ParameterWatcher} which watches specific parameters on a single
+   * remote node, ParameterEventHandler can register callbacks for parameters on
+   * any node in the ROS 2 graph by subscribing to /parameter_events.
+   *
+   * @param {object} [options] - Options for the handler
+   * @param {object} [options.qos] - QoS profile for the parameter_events subscription
+   * @return {ParameterEventHandler} - An instance of ParameterEventHandler
+   * @see {@link ParameterEventHandler}
+   */
+  createParameterEventHandler(options = {}) {
+    const handler = new ParameterEventHandler(this, options);
+    debug('Created ParameterEventHandler on node=%s', this.name());
+    this._parameterEventHandlers.push(handler);
+    return handler;
+  }
+
+  /**
+   * Destroy a ParameterEventHandler.
+   * @param {ParameterEventHandler} handler - The handler to be destroyed.
+   * @return {undefined}
+   */
+  destroyParameterEventHandler(handler) {
+    if (!(handler instanceof ParameterEventHandler)) {
+      throw new TypeError('Invalid argument');
+    }
+    this._removeEntityFromArray(handler, this._parameterEventHandlers);
+    handler.destroy();
+  }
+
   /**
    * Destroy a Timer.
    * @param {Timer} timer - The Timer to be destroyed.
@@ -1965,6 +2108,29 @@ class Node extends rclnodejs.ShadowNode {
    * @return {SetParameterResult} - A single collective result.
    */
   _setParametersAtomically(parameters = [], declareParameterMode = false) {
+    // 1) PRE callbacks — pipeline: each callback receives the output of the previous
+    if (this._preSetParametersCallbacks.length > 0) {
+      for (const callback of this._preSetParametersCallbacks) {
+        const result = callback(parameters);
+        if (!Array.isArray(result)) {
+          return {
+            successful: false,
+            reason:
+              'pre-set parameters callback must return an array of Parameters',
+          };
+        }
+        parameters = result;
+        if (parameters.length === 0) {
+          return {
+            successful: false,
+            reason:
+              'parameter list is empty after pre-set callback; set rejected',
+          };
+        }
+      }
+    }
+
+    // 2) Validate
     let result = this._validateParameters(parameters, declareParameterMode);
     if (!result.successful) {
       return result;
@@ -2034,6 +2200,11 @@ class Node extends rclnodejs.ShadowNode {
     // Publish ParameterEvent.
     this._parameterEventPublisher.publish(parameterEvent);
 
+    // POST callbacks — for side effects after successful set
+    for (const callback of this._postSetParametersCallbacks) {
+      callback(parameters);
+    }
+
     return {
       successful: true,
       reason: '',
@@ -2078,6 +2249,82 @@ class Node extends rclnodejs.ShadowNode {
     }
   }
 
+  /**
+   * A callback invoked before parameter validation and setting.
+   * It receives the parameter list and must return a (possibly modified) parameter list.
+   *
+   * @callback PreSetParametersCallback
+   * @param {Parameter[]} parameters - The parameters about to be set.
+   * @returns {Parameter[]} - The modified parameter list to proceed with.
+   *
+   * @see [Node.addPreSetParametersCallback]{@link Node#addPreSetParametersCallback}
+   * @see [Node.removePreSetParametersCallback]{@link Node#removePreSetParametersCallback}
+   */
+
+  /**
+   * Add a callback invoked before parameter validation.
+   * The callback receives the parameter list and must return a (possibly modified)
+   * parameter list. This can be used to coerce, add, or remove parameters before
+   * they are validated and applied. If any pre-set callback returns an empty list,
+   * the set is rejected.
+   *
+   * @param {PreSetParametersCallback} callback - The callback to add.
+   * @returns {undefined}
+   */
+  addPreSetParametersCallback(callback) {
+    this._preSetParametersCallbacks.unshift(callback);
+  }
+
+  /**
+   * Remove a pre-set parameters callback.
+   *
+   * @param {PreSetParametersCallback} callback - The callback to remove.
+   * @returns {undefined}
+   */
+  removePreSetParametersCallback(callback) {
+    const idx = this._preSetParametersCallbacks.indexOf(callback);
+    if (idx > -1) {
+      this._preSetParametersCallbacks.splice(idx, 1);
+    }
+  }
+
+  /**
+   * A callback invoked after parameters have been successfully set.
+   * It receives the final parameter list. For side effects only (return value is ignored).
+   *
+   * @callback PostSetParametersCallback
+   * @param {Parameter[]} parameters - The parameters that were set.
+   * @returns {undefined}
+   *
+   * @see [Node.addPostSetParametersCallback]{@link Node#addPostSetParametersCallback}
+   * @see [Node.removePostSetParametersCallback]{@link Node#removePostSetParametersCallback}
+   */
+
+  /**
+   * Add a callback invoked after parameters are successfully set.
+   * The callback receives the final parameter list. Useful for triggering
+   * side effects (e.g., reconfiguring a component when a parameter changes).
+   *
+   * @param {PostSetParametersCallback} callback - The callback to add.
+   * @returns {undefined}
+   */
+  addPostSetParametersCallback(callback) {
+    this._postSetParametersCallbacks.unshift(callback);
+  }
+
+  /**
+   * Remove a post-set parameters callback.
+   *
+   * @param {PostSetParametersCallback} callback - The callback to remove.
+   * @returns {undefined}
+   */
+  removePostSetParametersCallback(callback) {
+    const idx = this._postSetParametersCallbacks.indexOf(callback);
+    if (idx > -1) {
+      this._postSetParametersCallbacks.splice(idx, 1);
+    }
+  }
+
   /**
    * Get the fully qualified name of the node.
    *