rclnodejs 1.8.3 → 1.9.0

package/lib/qos_overriding_options.js

@@ -0,0 +1,358 @@
+// Copyright (c) 2026 The Robot Web Tools Contributors. 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 QoS = require('./qos.js');
+const {
+  Parameter,
+  ParameterType,
+  ParameterDescriptor,
+} = require('./parameter.js');
+
+/**
+ * Enum of overridable QoS policy kinds.
+ * Each value corresponds to a QoS property on the {@link QoS} class.
+ * @enum {number}
+ */
+const QoSPolicyKind = Object.freeze({
+  HISTORY: 1,
+  DEPTH: 2,
+  RELIABILITY: 3,
+  DURABILITY: 4,
+  LIVELINESS: 5,
+  AVOID_ROS_NAMESPACE_CONVENTIONS: 6,
+});
+
+// Maps QoSPolicyKind -> { qosProp, paramKey, paramType, toParam, fromParam }
+const POLICY_MAP = {
+  [QoSPolicyKind.HISTORY]: {
+    qosProp: 'history',
+    paramKey: 'history',
+    enumObj: QoS.HistoryPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DEPTH]: {
+    qosProp: 'depth',
+    paramKey: 'depth',
+    paramType: ParameterType.PARAMETER_INTEGER,
+    toParam: (val) => BigInt(val),
+    fromParam: (val) => Number(val),
+  },
+  [QoSPolicyKind.RELIABILITY]: {
+    qosProp: 'reliability',
+    paramKey: 'reliability',
+    enumObj: QoS.ReliabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DURABILITY]: {
+    qosProp: 'durability',
+    paramKey: 'durability',
+    enumObj: QoS.DurabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.LIVELINESS]: {
+    qosProp: 'liveliness',
+    paramKey: 'liveliness',
+    enumObj: QoS.LivelinessPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.AVOID_ROS_NAMESPACE_CONVENTIONS]: {
+    qosProp: 'avoidRosNameSpaceConventions',
+    paramKey: 'avoid_ros_namespace_conventions',
+    paramType: ParameterType.PARAMETER_BOOL,
+    toParam: (val) => val,
+    fromParam: (val) => Boolean(val),
+  },
+};
+
+/**
+ * Convert a numeric enum value to a lowercase string name.
+ * @param {number} val - enum numeric value
+ * @param {Object} enumObj - the enum object (e.g. QoS.HistoryPolicy)
+ * @returns {string}
+ */
+function _enumToString(val, enumObj) {
+  for (const [key, v] of Object.entries(enumObj)) {
+    if (v === val) {
+      // Strip the RMW prefix: "RMW_QOS_POLICY_HISTORY_KEEP_LAST" -> "keep_last"
+      const parts = key.split('_');
+      // Find the index after the policy name (HISTORY, RELIABILITY, etc.)
+      // Pattern: RMW_QOS_POLICY_<POLICY>_<VALUE>
+      const policyNames = [
+        'HISTORY',
+        'RELIABILITY',
+        'DURABILITY',
+        'LIVELINESS',
+      ];
+      let valueStart = 4; // default: skip RMW_QOS_POLICY_<X>_
+      for (let i = 3; i < parts.length; i++) {
+        if (policyNames.includes(parts[i])) {
+          valueStart = i + 1;
+          break;
+        }
+      }
+      return parts.slice(valueStart).join('_').toLowerCase();
+    }
+  }
+  return String(val);
+}
+
+/**
+ * Convert a lowercase string back to a numeric enum value.
+ * @param {string} str - the string value (e.g. "keep_last")
+ * @param {Object} enumObj - the enum object
+ * @returns {number}
+ */
+function _stringToEnum(str, enumObj) {
+  const upper = str.toUpperCase();
+  for (const [key, val] of Object.entries(enumObj)) {
+    if (key.endsWith('_' + upper)) {
+      return val;
+    }
+  }
+  throw new Error(`Unknown QoS policy value: "${str}"`);
+}
+
+/**
+ * Options for overriding QoS policies via ROS parameters.
+ *
+ * When passed to `createPublisher()` or `createSubscription()`, the node
+ * will declare read-only parameters for each specified policy kind. These
+ * parameters can be set via command-line arguments, launch files, or
+ * parameter files to override the QoS profile at startup.
+ *
+ * Parameter naming convention:
+ *   `qos_overrides.<topic>.<publisher|subscription>[_<entityId>].<policy>`
+ *
+ * @example
+ * // Override history, depth, and reliability via parameters
+ * const sub = node.createSubscription(
+ *   'std_msgs/msg/String', '/chatter',
+ *   { qos: rclnodejs.QoS.profileDefault,
+ *     qosOverridingOptions: QoSOverridingOptions.withDefaultPolicies() },
+ *   (msg) => console.log(msg.data)
+ * );
+ * // Now you can override via CLI:
+ * //   --ros-args -p "qos_overrides./chatter.subscription.depth:=20"
+ */
+class QoSOverridingOptions {
+  /**
+   * @param {Array<QoSPolicyKind>} policyKinds - Which QoS policies to expose as parameters.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Optional validation callback. Receives the
+   *   final QoS profile after overrides are applied. Should return
+   *   `{successful: true}` or `{successful: false, reason: '...'}`.
+   * @param {string} [opts.entityId] - Optional suffix to disambiguate multiple
+   *   publishers/subscriptions on the same topic.
+   */
+  constructor(policyKinds, opts = {}) {
+    this._policyKinds = Array.from(policyKinds);
+    this._callback = opts.callback || null;
+    this._entityId = opts.entityId || null;
+  }
+
+  get policyKinds() {
+    return this._policyKinds;
+  }
+
+  get callback() {
+    return this._callback;
+  }
+
+  get entityId() {
+    return this._entityId;
+  }
+
+  /**
+   * Create options that override history, depth, and reliability —
+   * the most commonly tuned policies.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Validation callback.
+   * @param {string} [opts.entityId] - Entity disambiguation suffix.
+   * @returns {QoSOverridingOptions}
+   */
+  static withDefaultPolicies(opts = {}) {
+    return new QoSOverridingOptions(
+      [QoSPolicyKind.HISTORY, QoSPolicyKind.DEPTH, QoSPolicyKind.RELIABILITY],
+      opts
+    );
+  }
+}
+
+/**
+ * Resolve QoS profile string to a mutable QoS object.
+ * If already a QoS instance, return as-is.
+ * @param {QoS|string} qos
+ * @returns {QoS}
+ */
+function _resolveQoS(qos) {
+  if (qos instanceof QoS) {
+    return qos;
+  }
+  // Plain object with QoS fields — construct a QoS from its properties
+  if (typeof qos === 'object' && qos !== null && !Array.isArray(qos)) {
+    return new QoS(
+      qos.history,
+      qos.depth,
+      qos.reliability,
+      qos.durability,
+      qos.liveliness,
+      qos.avoidRosNameSpaceConventions
+    );
+  }
+  // Profile string: create a QoS with the corresponding defaults
+  // Values must match the rmw_qos_profile_* definitions in rmw/types.h
+  switch (qos) {
+    case QoS.profileDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileSystemDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_SYSTEM_DEFAULT,
+        0,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT,
+        QoS.LivelinessPolicy.RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT
+      );
+    case QoS.profileSensorData:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        5,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileServicesDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileParameters:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1000,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileParameterEvents:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1000,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileActionStatusDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL
+      );
+    default:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+  }
+}
+
+/**
+ * Declare QoS override parameters on the node and apply any overrides
+ * to the QoS profile in-place.
+ *
+ * @param {'publisher'|'subscription'} entityType
+ * @param {Node} node
+ * @param {string} topic - Fully resolved topic name.
+ * @param {QoS} qos - Mutable QoS object (will be modified in-place).
+ * @param {QoSOverridingOptions} options
+ */
+function declareQosParameters(entityType, node, topic, qos, options) {
+  if (!options || options.policyKinds.length === 0) {
+    return;
+  }
+
+  const idSuffix = options.entityId ? `_${options.entityId}` : '';
+  const namePrefix = `qos_overrides.${topic}.${entityType}${idSuffix}`;
+
+  for (const policyKind of options.policyKinds) {
+    const mapping = POLICY_MAP[policyKind];
+    if (!mapping) {
+      continue;
+    }
+
+    const paramName = `${namePrefix}.${mapping.paramKey}`;
+    const currentValue = qos[mapping.qosProp];
+    const paramValue = mapping.toParam(currentValue, mapping.enumObj);
+
+    const descriptor = new ParameterDescriptor(
+      paramName,
+      mapping.paramType,
+      `QoS override for ${mapping.qosProp}`,
+      true // readOnly
+    );
+
+    let param;
+    try {
+      param = node.declareParameter(
+        new Parameter(paramName, mapping.paramType, paramValue),
+        descriptor
+      );
+    } catch (e) {
+      // Already declared (e.g. multiple entities on same topic) — reuse
+      if (node.hasParameter(paramName)) {
+        param = node.getParameter(paramName);
+      } else {
+        throw e;
+      }
+    }
+
+    // Apply the (possibly overridden) parameter value back to QoS
+    if (param && param.value !== paramValue) {
+      qos[mapping.qosProp] = mapping.fromParam(param.value, mapping.enumObj);
+    }
+  }
+
+  // Run validation callback if provided
+  if (options.callback) {
+    const result = options.callback(qos);
+    if (result && !result.successful) {
+      throw new Error(
+        `QoS override validation failed: ${result.reason || 'unknown reason'}`
+      );
+    }
+  }
+}
+
+module.exports = {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+  declareQosParameters,
+  _resolveQoS,
+};

package/lib/subscription.js

@@ -16,14 +16,16 @@
 
 const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
+const DistroUtils = require('./distro.js');
 const { applySerializationMode } = require('./message_serialization.js');
 const debug = require('debug')('rclnodejs:subscription');
 
 /**
  * @class - Class representing a ROS 2 Subscription
- * @hideconstructor
  * Includes support for content-filtering topics beginning with the
- * ROS Humble release. To learn more about content-filtering
+ * ROS Humble release. To learn more about content-filtering topics,
+ * see the references below.
+ * @hideconstructor
  * @see {@link Node#options}
  * @see {@link Node#createSubscription}
  * @see {@link https://www.omg.org/spec/DDS/1.4/PDF|DDS 1.4 specification, Annex B}
@@ -45,6 +47,7 @@ class Subscription extends Entity {
     this._isRaw = options.isRaw || false;
     this._serializationMode = options.serializationMode || 'default';
     this._node = node;
+    this._wantsMessageInfo = callback.length >= 2;
 
     if (node && eventCallbacks) {
       this._events = eventCallbacks.createEventHandlers(this.handle);
@@ -52,10 +55,24 @@ class Subscription extends Entity {
     }
   }
 
-  processResponse(msg) {
+  /**
+   * Whether this subscription's callback wants MessageInfo as a second argument.
+   * Determined by callback.length >= 2.
+   * @type {boolean}
+   * @readonly
+   */
+  get wantsMessageInfo() {
+    return this._wantsMessageInfo;
+  }
+
+  processResponse(msg, messageInfo) {
     debug(`Message of topic ${this._topic} received.`);
     if (this._isRaw) {
-      this._callback(msg);
+      if (this._wantsMessageInfo && messageInfo) {
+        this._callback(msg, messageInfo);
+      } else {
+        this._callback(msg);
+      }
     } else {
       let message = msg.toPlainObject(this.typedArrayEnabled);
 
@@ -63,7 +80,11 @@ class Subscription extends Entity {
         message = applySerializationMode(message, this._serializationMode);
       }
 
-      this._callback(message);
+      if (this._wantsMessageInfo && messageInfo) {
+        this._callback(message, messageInfo);
+      } else {
+        this._callback(message);
+      }
     }
   }
 
@@ -124,6 +145,18 @@ class Subscription extends Entity {
     return this._serializationMode;
   }
 
+  /**
+   * Check if content filtering is supported for this subscription.
+   * Requires ROS 2 Rolling or later.
+   * @returns {boolean} True if the subscription instance supports content filtering; otherwise false.
+   */
+  isContentFilterSupported() {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+      return false;
+    }
+    return rclnodejs.isContentFilterSupported(this.handle);
+  }
+
   /**
    * Test if the RMW supports content-filtered topics and that this subscription
    * has an active wellformed content-filter.

package/lib/timer.js

@@ -30,7 +30,8 @@ class Timer {
   }
 
   /**
-   * @type {bigint} - The period of the timer in nanoseconds.
+   * The period of the timer in nanoseconds.
+   * @type {bigint}
    */
   get period() {
     return this._period;
@@ -149,7 +150,7 @@ class Timer {
 
   /**
    * Call a timer and starts counting again, retrieves actual and expected call time.
-   * @return {object} - The timer information.
+   * @return {{expectedCallTime: bigint, actualCallTime: bigint}} - The timer information.
    */
   callTimerWithInfo() {
     if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {

package/lib/wait_for_message.js

@@ -0,0 +1,111 @@
+// 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 { TimeoutError } = require('./errors.js');
+
+/**
+ * Wait for a single message on a topic.
+ *
+ * Creates a temporary subscription, waits for the first message to arrive,
+ * and returns it. The temporary subscription is always cleaned up, even on
+ * timeout or error. The node must be spinning before calling this function.
+ *
+ * This is the rclnodejs equivalent of rclpy's `wait_for_message`.
+ *
+ * @param {function|string|object} typeClass - The ROS message type class.
+ * @param {Node} node - The node to create the temporary subscription on.
+ * @param {string} topic - The topic name to listen on.
+ * @param {object} [options] - Options.
+ * @param {number} [options.timeout] - Timeout in milliseconds. If omitted, waits indefinitely.
+ * @param {object} [options.qos] - QoS profile for the subscription.
+ * @returns {Promise<object>} - Resolves with the received message.
+ * @throws {Error} If timeout expires before a message arrives.
+ *
+ * @example
+ * node.spin();
+ * const msg = await waitForMessage(
+ *   'std_msgs/msg/String',
+ *   node,
+ *   '/my_topic',
+ *   { timeout: 5000 }
+ * );
+ * console.log('Received:', msg.data);
+ */
+function waitForMessage(typeClass, node, topic, options = {}) {
+  return new Promise((resolve, reject) => {
+    let subscription = null;
+    let timer = null;
+    let settled = false;
+
+    const cleanup = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (subscription) {
+        try {
+          node.destroySubscription(subscription);
+        } catch {
+          // Subscription may already be destroyed if node is shutting down
+        }
+        subscription = null;
+      }
+    };
+
+    const settle = (err, msg) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (err) {
+        reject(err);
+      } else {
+        resolve(msg);
+      }
+    };
+
+    try {
+      const subOptions = {};
+      if (options.qos) {
+        subOptions.qos = options.qos;
+      }
+
+      subscription = node.createSubscription(
+        typeClass,
+        topic,
+        subOptions,
+        (msg) => {
+          settle(null, msg);
+        }
+      );
+
+      if (options.timeout != null && options.timeout >= 0) {
+        timer = setTimeout(() => {
+          settle(
+            new TimeoutError(
+              `waitForMessage timed out after ${options.timeout}ms on topic '${topic}'`,
+              { entityType: 'topic', entityName: topic }
+            )
+          );
+        }, options.timeout);
+      }
+    } catch (err) {
+      cleanup();
+      reject(err);
+    }
+  });
+}
+
+module.exports = waitForMessage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -24,10 +24,13 @@
     "clean": "node-gyp clean && npx rimraf ./generated",
     "install": "node scripts/install.js",
     "postinstall": "npm run generate-messages",
-    "docs": "cd docs && make",
+    "docs": "make -C tools/jsdoc",
+    "docs:gh-pages": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --preserve-published",
+    "docs:gh-pages:full": "node tools/jsdoc/regenerate-published-docs.js --branch origin/gh-pages --full-rebuild",
     "test": "nyc node --expose-gc ./scripts/run_test.js && tsd && npm install --no-save electron && node test/electron/run_test.js",
     "test-idl": "nyc node --expose-gc ./scripts/run_test.js --idl",
     "lint": "eslint && node ./scripts/cpplint.js",
+    "test:asan": "bash scripts/run_asan_test.sh",
     "format": "clang-format -i -style=file ./src/*.cpp ./src/*.h && npx --yes prettier --write \"{lib,rosidl_gen,rostsd_gen,rosidl_parser,types,example,test,scripts,benchmark,rostsd_gen}/**/*.{js,md,ts}\" ./*.{js,md,ts}",
     "prepare": "husky",
     "coverage": "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js",
@@ -64,14 +67,14 @@
     "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
-    "node-gyp": "^12.1.0",
+    "node-gyp": "^10.3.1",
     "nyc": "^18.0.0",
     "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",
     "sinon": "^21.0.0",
     "tree-kill": "^1.2.2",
     "tsd": "^0.33.0",
-    "typescript": "^5.7.2"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "@rclnodejs/ref-array-di": "^1.2.2",