rclnodejs 1.9.0-alpha.0 → 2.0.0-beta.0

package/lib/node.js

@@ -48,6 +48,10 @@ 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');
@@ -157,7 +161,9 @@ class Node extends rclnodejs.ShadowNode {
     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;
@@ -250,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();
+        }
       }
     });
 
@@ -622,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') {
@@ -643,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);
@@ -705,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.
    */
@@ -752,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,
@@ -795,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.
@@ -848,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,
@@ -1494,7 +1587,7 @@ class Node extends rclnodejs.ShadowNode {
    * @returns {Array} - list of clients
    */
   getClientsInfoByService(service, noDemangle = false) {
-    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.LYRICAL) {
       console.warn(
         'getClientsInfoByService is not supported by this version of ROS 2'
       );
@@ -1528,7 +1621,7 @@ class Node extends rclnodejs.ShadowNode {
    * @returns {Array} - list of servers
    */
   getServersInfoByService(service, noDemangle = false) {
-    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.LYRICAL) {
       console.warn(
         'getServersInfoByService is not supported by this version of ROS 2'
       );
@@ -2015,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;
@@ -2084,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: '',
@@ -2128,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.
    *

package/lib/parameter_event_handler.js

@@ -16,6 +16,7 @@
 
 const { TypeValidationError, OperationError } = require('./errors');
 const { normalizeNodeName } = require('./utils');
+const validator = require('./validator');
 const debug = require('debug')('rclnodejs:parameter_event_handler');
 
 const PARAMETER_EVENT_MSG_TYPE = 'rcl_interfaces/msg/ParameterEvent';
@@ -210,6 +211,64 @@ class ParameterEventHandler {
     return handle;
   }
 
+  /**
+   * Configure which node parameter events will be received.
+   *
+   * If nodeNames is omitted or empty, the current node filter is cleared.
+   * When a filter is active, parameter and event callbacks only receive
+   * events from the specified nodes.
+   *
+   * @param {string[]} [nodeNames] - Node names to filter parameter events from.
+   *   Relative names are resolved against the handler node namespace.
+   * @returns {boolean} True if the filter is active or was successfully cleared.
+   */
+  configureNodesFilter(nodeNames) {
+    this.#checkNotDestroyed();
+
+    if (nodeNames === undefined || nodeNames === null) {
+      this.#subscription.clearContentFilter();
+      return !this.#subscription.hasContentFilter();
+    }
+
+    if (!Array.isArray(nodeNames)) {
+      throw new TypeValidationError('nodeNames', nodeNames, 'string[]', {
+        entityType: 'parameter event handler',
+      });
+    }
+
+    if (nodeNames.length === 0) {
+      this.#subscription.clearContentFilter();
+      return !this.#subscription.hasContentFilter();
+    }
+
+    const resolvedNodeNames = nodeNames.map((nodeName, index) => {
+      if (typeof nodeName !== 'string' || nodeName.trim() === '') {
+        throw new TypeValidationError(
+          `nodeNames[${index}]`,
+          nodeName,
+          'non-empty string',
+          {
+            entityType: 'parameter event handler',
+          }
+        );
+      }
+
+      const resolvedNodeName = this.#resolvePath(nodeName.trim());
+      this.#validateFullyQualifiedNodePath(resolvedNodeName);
+      return resolvedNodeName;
+    });
+
+    const contentFilter = {
+      expression: resolvedNodeNames
+        .map((_, index) => `node = %${index}`)
+        .join(' OR '),
+      parameters: resolvedNodeNames.map((nodeName) => `'${nodeName}'`),
+    };
+
+    this.#subscription.setContentFilter(contentFilter);
+    return this.#subscription.hasContentFilter();
+  }
+
   /**
    * Remove a previously added parameter callback.
    *
@@ -450,6 +509,45 @@ class ParameterEventHandler {
     return `${paramName}\0${nodeName}`;
   }
 
+  /**
+   * Resolve a node path to the fully qualified name used in ParameterEvent.node.
+   * @private
+   */
+  #resolvePath(nodePath) {
+    // Absolute node paths are already rooted. Relative names are resolved
+    // against the handler node namespace before building the content filter.
+    const unresolvedPath = nodePath.startsWith('/')
+      ? nodePath
+      : `${this.#node.namespace().replace(/\/+$/, '')}/${nodePath}`;
+
+    // Collapse repeated separators for inputs like '/ns//node/' or 'nested//node'.
+    const resolvedPath = unresolvedPath.replace(/\/+/g, '/');
+
+    // Preserve the root namespace as '/' and strip trailing slashes everywhere
+    // else so the filter matches the canonical ParameterEvent.node format.
+    if (resolvedPath === '/') {
+      return resolvedPath;
+    }
+
+    return resolvedPath.replace(/\/+$/, '');
+  }
+
+  /**
+   * Validate a fully qualified node path before using it in a content filter.
+   * @private
+   */
+  #validateFullyQualifiedNodePath(nodePath) {
+    const normalizedPath =
+      nodePath.length > 1 ? nodePath.replace(/\/+$/, '') : nodePath;
+    const separatorIndex = normalizedPath.lastIndexOf('/');
+    const nodeNamespace =
+      separatorIndex === 0 ? '/' : normalizedPath.slice(0, separatorIndex);
+    const nodeName = normalizedPath.slice(separatorIndex + 1);
+
+    validator.validateNamespace(nodeNamespace);
+    validator.validateNodeName(nodeName);
+  }
+
   /**
    * Check if the handler has been destroyed and throw if so.
    * @private

package/lib/prebuilds.js

@@ -0,0 +1,47 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// 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 PREBUILD_PACKAGE_NAME = 'rclnodejs';
+const SUPPORTED_PREBUILD_RUNTIMES = new Set(['node', 'electron']);
+
+function detectPrebuildRuntime() {
+  if (process.env.npm_config_runtime === 'electron') {
+    return 'electron';
+  }
+
+  return process.versions.electron ? 'electron' : 'node';
+}
+
+function getTaggedPrebuildFilename({
+  rosDistro,
+  ubuntuCodename,
+  arch,
+  runtime,
+}) {
+  return `${rosDistro}-${ubuntuCodename}-${arch}-${runtime}-${PREBUILD_PACKAGE_NAME}.node`;
+}
+
+function getRuntimeFromGeneratedPrebuild(fileName) {
+  const runtime = fileName.split('.')[0];
+  return SUPPORTED_PREBUILD_RUNTIMES.has(runtime) ? runtime : null;
+}
+
+module.exports = {
+  detectPrebuildRuntime,
+  getRuntimeFromGeneratedPrebuild,
+  getTaggedPrebuildFilename,
+  PREBUILD_PACKAGE_NAME,
+};