rclnodejs 1.8.2 → 1.9.0-alpha.0

package/lib/parameter_watcher.js

@@ -17,6 +17,7 @@
 const EventEmitter = require('events');
 const { TypeValidationError, OperationError } = require('./errors');
 const { normalizeNodeName } = require('./utils');
+const ParameterEventHandler = require('./parameter_event_handler.js');
 const debug = require('debug')('rclnodejs:parameter_watcher');
 
 /**
@@ -30,7 +31,7 @@ const debug = require('debug')('rclnodejs:parameter_watcher');
 class ParameterWatcher extends EventEmitter {
   #node;
   #paramClient;
-  #subscription;
+  #eventHandler;
   #watchedParams;
   #remoteNodeName;
   #destroyed;
@@ -82,7 +83,7 @@ class ParameterWatcher extends EventEmitter {
     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.#eventHandler = null;
     this.#destroyed = false;
 
     debug(
@@ -133,14 +134,13 @@ class ParameterWatcher extends EventEmitter {
       return false;
     }
 
-    if (!this.#subscription) {
-      this.#subscription = this.#node.createSubscription(
-        'rcl_interfaces/msg/ParameterEvent',
-        '/parameter_events',
-        (event) => this.#handleParameterEvent(event)
+    if (!this.#eventHandler) {
+      this.#eventHandler = new ParameterEventHandler(this.#node);
+      this.#eventHandler.addParameterEventCallback((event) =>
+        this.#handleParameterEvent(event)
       );
 
-      debug('Subscribed to /parameter_events');
+      debug('Subscribed to /parameter_events via ParameterEventHandler');
     }
 
     return true;
@@ -227,13 +227,13 @@ class ParameterWatcher extends EventEmitter {
 
     debug('Destroying ParameterWatcher for node=%s', this.remoteNodeName);
 
-    if (this.#subscription) {
+    if (this.#eventHandler) {
       try {
-        this.#node.destroySubscription(this.#subscription);
+        this.#eventHandler.destroy();
       } catch (error) {
-        debug('Error destroying subscription: %s', error.message);
+        debug('Error destroying event handler: %s', error.message);
       }
-      this.#subscription = null;
+      this.#eventHandler = null;
     }
 
     if (this.#paramClient) {

package/lib/service.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
+const Logging = require('./logging.js');
 const debug = require('debug')('rclnodejs:service');
 
 /**
@@ -75,8 +76,8 @@ class Service extends Entity {
 
     const plainObj = request.toPlainObject(this.typedArrayEnabled);
     const response = new Response(this, headerHandle);
-    Promise.resolve(this._callback(plainObj, response)).then(
-      (responseToReturn) => {
+    Promise.resolve(this._callback(plainObj, response))
+      .then((responseToReturn) => {
         if (!response.sent && responseToReturn) {
           responseToReturn = new this._typeClass.Response(responseToReturn);
           const rawResponse = responseToReturn.serialize();
@@ -86,8 +87,11 @@ class Service extends Entity {
         debug(
           `Service has processed the ${this._serviceName} request and sent the response.`
         );
-      }
-    );
+      })
+      .catch((error) => {
+        const logger = Logging.getLogger('rclnodejs');
+        logger.error(`Error processing ${this._serviceName} request: ${error}`);
+      });
   }
 
   static createService(nodeHandle, serviceName, typeClass, options, callback) {

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/time_source.js

@@ -45,26 +45,6 @@ class TimeSource {
     }
   }
 
-  get isRosTimeActive() {
-    return this._isRosTimeActive;
-  }
-
-  set isRosTimeActive(enabled) {
-    if (this.isRosTimeActive === enabled) return;
-
-    this._isRosTimeActive = enabled;
-    for (const clock in this._associatedClocks) {
-      clock.isRosTimeActive = enabled;
-    }
-
-    if (enabled) {
-      this._subscribeToClockTopic();
-    } else if (this._node && this._clockSubscription) {
-      this._node.destroySubscription(this._clockSubscription);
-      this._node._clockSubscription = null;
-    }
-  }
-
   /**
    * Return status that whether the ROS time is active.
    * @name TimeSource#get:isRosTimeActive
@@ -93,6 +73,9 @@ class TimeSource {
     });
     if (enabled) {
       this._subscribeToClockTopic();
+    } else if (this._node && this._clockSubscription) {
+      this._node.destroySubscription(this._clockSubscription);
+      this._clockSubscription = undefined;
     }
   }
 

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;

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.2",
+  "version": "1.9.0-alpha.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",
@@ -65,13 +68,13 @@
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
     "node-gyp": "^12.1.0",
-    "nyc": "^17.1.0",
+    "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",

package/rosidl_gen/generate_worker.js

@@ -12,14 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-const fse = require('../lib/utils.js');
 const generateJSStructFromIDL = require('./idl_generator.js');
 const packages = require('./packages.js');
 const path = require('path');
-const idlConvertor = require('../rosidl_convertor/idl_convertor.js');
 
 const generatedRoot = path.join(__dirname, '../generated/');
-const idlPath = path.join(generatedRoot, 'share');
 const useIDL = !!process.argv.find((arg) => arg === '--idl');
 
 // Get target path from environment variable instead of workerData
@@ -32,17 +29,10 @@ async function generateInPath(targetPath) {
       (await packages.findPackagesInDirectory(targetPath)).values()
     );
   } else {
+    // Direct IDL parsing: pass .idl files to the generator which uses
+    // rosidl_parser to parse them directly (no .msg/.srv/.action conversion).
     const idlPkgs = await packages.findPackagesInDirectory(targetPath, useIDL);
-    await fse.ensureDir(idlPath);
-    const promises = [];
-    idlPkgs.forEach((pkg) => {
-      pkg.idls.forEach((idl) => {
-        promises.push(idlConvertor(idl.pkgName, idl.filePath, idlPath));
-      });
-    });
-    await Promise.all(promises);
-    const pkgsFromIdl = await packages.findPackagesInDirectory(idlPath, false);
-    pkgsInfo = Array.from(pkgsFromIdl.values());
+    pkgsInfo = Array.from(idlPkgs.values());
   }
 
   await Promise.all(

package/rosidl_gen/idl_generator.js

@@ -305,7 +305,217 @@ async function generateJSStructFromIDL(pkg, dir) {
   pkg.actions.forEach((actionInfo) => {
     results.push(generateActionJSStruct(actionInfo, dir));
   });
+
+  // Handle .idl files directly (parsed via rosidl_parser, no .msg conversion)
+  if (pkg.idls) {
+    pkg.idls.forEach((idlInfo) => {
+      results.push(generateJSStructFromIdlFile(idlInfo, dir));
+    });
+  }
+
   await Promise.all(results);
 }
 
+/**
+ * Parse an .idl file directly and generate the appropriate JS struct.
+ * This uses rosidl_parser to parse the IDL and produces the same JSON
+ * spec format, so the same templates can be used.
+ */
+async function generateJSStructFromIdlFile(idlInfo, dir) {
+  const result = await parser.parseIdlFile(idlInfo.filePath);
+  const { type, spec } = result;
+
+  if (type === 'message') {
+    await generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: idlInfo.interfaceName,
+      },
+      dir,
+      spec
+    );
+  } else if (type === 'service') {
+    // Generate request and response message JS structs
+    const requestMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_Request`,
+      },
+      dir,
+      spec.request
+    );
+
+    const responseMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_Response`,
+      },
+      dir,
+      spec.response
+    );
+
+    // Generate service JS struct
+    const serviceInfo = {
+      pkgName: idlInfo.pkgName,
+      subFolder: idlInfo.subFolder,
+      interfaceName: idlInfo.interfaceName,
+    };
+    const srv = generateServiceJSStruct(
+      serviceInfo,
+      dir,
+      /*isActionService=*/ false
+    );
+
+    await Promise.all([requestMsg, responseMsg, srv]);
+  } else if (type === 'action') {
+    // Generate goal, result, feedback message JS structs
+    const goalMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_Goal`,
+      },
+      dir,
+      spec.goal
+    );
+
+    const resultMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_Result`,
+      },
+      dir,
+      spec.result
+    );
+
+    const feedbackMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_Feedback`,
+      },
+      dir,
+      spec.feedback
+    );
+
+    // Generate derived action messages (SendGoal, GetResult, FeedbackMessage)
+    const sendGoalRequestSpec = actionMsgs.createSendGoalRequestSpec(
+      idlInfo.pkgName,
+      idlInfo.interfaceName
+    );
+    const sendGoalRequestMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_SendGoal_Request`,
+      },
+      dir,
+      sendGoalRequestSpec
+    );
+
+    const sendGoalResponseSpec = actionMsgs.createSendGoalResponseSpec(
+      idlInfo.pkgName,
+      idlInfo.interfaceName
+    );
+    const sendGoalResponseMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_SendGoal_Response`,
+      },
+      dir,
+      sendGoalResponseSpec
+    );
+
+    const sendGoalSrv = generateServiceJSStruct(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_SendGoal`,
+      },
+      dir
+    );
+
+    const getResultRequestSpec = actionMsgs.createGetResultRequestSpec(
+      idlInfo.pkgName,
+      idlInfo.interfaceName
+    );
+    const getResultRequestMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_GetResult_Request`,
+      },
+      dir,
+      getResultRequestSpec
+    );
+
+    const getResultResponseSpec = actionMsgs.createGetResultResponseSpec(
+      idlInfo.pkgName,
+      idlInfo.interfaceName
+    );
+    const getResultResponseMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_GetResult_Response`,
+      },
+      dir,
+      getResultResponseSpec
+    );
+
+    const getResultSrv = generateServiceJSStruct(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_GetResult`,
+      },
+      dir
+    );
+
+    const feedbackMessageSpec = actionMsgs.createFeedbackMessageSpec(
+      idlInfo.pkgName,
+      idlInfo.interfaceName
+    );
+    const feedbackMessageMsg = generateMessageJSStructFromSpec(
+      {
+        pkgName: idlInfo.pkgName,
+        subFolder: idlInfo.subFolder,
+        interfaceName: `${idlInfo.interfaceName}_FeedbackMessage`,
+      },
+      dir,
+      feedbackMessageSpec
+    );
+
+    const fileName =
+      idlInfo.pkgName +
+      '__' +
+      idlInfo.subFolder +
+      '__' +
+      idlInfo.interfaceName +
+      '.js';
+    const generatedCode = generateAction({ actionInfo: idlInfo });
+    const actionDir = path.join(dir, idlInfo.pkgName);
+    const action = writeGeneratedCode(actionDir, fileName, generatedCode);
+
+    await Promise.all([
+      goalMsg,
+      resultMsg,
+      feedbackMsg,
+      sendGoalRequestMsg,
+      sendGoalResponseMsg,
+      sendGoalSrv,
+      getResultRequestMsg,
+      getResultResponseMsg,
+      getResultSrv,
+      feedbackMessageMsg,
+      action,
+    ]);
+  }
+}
+
 module.exports = generateJSStructFromIDL;

package/rosidl_gen/index.js

@@ -18,10 +18,8 @@ const fse = require('../lib/utils.js');
 const generateJSStructFromIDL = require('./idl_generator.js');
 const packages = require('./packages.js');
 const path = require('path');
-const idlConvertor = require('../rosidl_convertor/idl_convertor.js');
 const generatedRoot = path.join(__dirname, '../generated/');
 const serviceMsgPath = path.join(generatedRoot, 'srv_msg');
-const idlPath = path.join(generatedRoot, 'share');
 const useIDL = !!process.argv.find((arg) => arg === '--idl');
 
 function getInstalledPackagePaths() {
@@ -35,17 +33,10 @@ async function generateInPath(path) {
       (await packages.findPackagesInDirectory(path)).values()
     );
   } else {
+    // Direct IDL parsing: pass .idl files to the generator which uses
+    // rosidl_parser to parse them directly (no .msg/.srv/.action conversion).
     const idlPkgs = await packages.findPackagesInDirectory(path, useIDL);
-    await fse.ensureDir(idlPath);
-    const promises = [];
-    idlPkgs.forEach((pkg) => {
-      pkg.idls.forEach((idl) => {
-        promises.push(idlConvertor(idl.pkgName, idl.filePath, idlPath));
-      });
-    });
-    await Promise.all(promises);
-    const pkgsFromIdl = await packages.findPackagesInDirectory(idlPath, false);
-    pkgsInfo = Array.from(pkgsFromIdl.values());
+    pkgsInfo = Array.from(idlPkgs.values());
   }
 
   await Promise.all(