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

package/.prettierignore

@@ -0,0 +1,4 @@
+# Prettier pads Markdown table separators to match cell width, which bloats
+# long-URL badge tables.  Exclude root READMEs to keep them minimal.
+README.md
+scripts/npmjs-readme.md

package/README.md

@@ -20,7 +20,7 @@ This example assumes your ROS 2 environment is already sourced.
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/en/) version >= 16.13.0
+- [Node.js](https://nodejs.org/en/) version >= 20.20.2
 - [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html)
 
 Before installing or running rclnodejs, source your ROS 2 environment:
@@ -52,7 +52,7 @@ rclnodejs ships with prebuilt native binaries for common Linux configurations si
 - **Ubuntu 22.04 (Jammy)** - ROS 2 Humble
 - **Ubuntu 24.04 (Noble)** - ROS 2 Jazzy, Kilted
 - **Architectures:** x64, arm64
-- **Node.js:** >= 16.20.2 (N-API compatible)
+- **Node.js:** >= 20.20.2 (N-API compatible)
 
 Installations outside this prebuilt matrix automatically fall back to building from source.
 

package/binding.gyp

@@ -12,7 +12,6 @@
     'runtime%': 'node',
     'ros_lib_dir': "<!(node -p \"require('./scripts/config.js').getROSLibPath()\")",
     'ros_include_root': "<!(node -p \"require('./scripts/config.js').getROSIncludeRootPath()\")",
-    'node_major_version': '<!(node -p \"process.versions.node.split(\'.\')[0]\")',
   },
   'targets': [
     {
@@ -85,14 +84,15 @@
             ],
             'conditions': [
               [
-                'node_major_version >= 23', {
+                # Post-Kilted ROS distros require C++20.
+                'ros_version > 2505', {
                   'cflags_cc': [
                     '-std=c++20'
                   ]
                 }
               ],
               [
-                'node_major_version < 23', {
+                'ros_version <= 2505', {
                   'cflags_cc': [
                     '-std=c++17'
                   ]
@@ -108,14 +108,15 @@
             ],
             'conditions': [
               [
-                'node_major_version >= 23', {
+                # Post-Kilted ROS distros require C++20.
+                'ros_version > 2505', {
                   'cflags_cc': [
                     '-std=c++20'
                   ]
                 }
               ],
               [
-                'node_major_version < 23', {
+                'ros_version <= 2505', {
                   'cflags_cc': [
                     '-std=c++17'
                   ]

package/index.js

@@ -39,6 +39,10 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
+const {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+} = require('./lib/qos_overriding_options.js');
 const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
@@ -258,6 +262,12 @@ let rcl = {
   /** {@link QoS} class */
   QoS: QoS,
 
+  /** {@link QoSPolicyKind} enum */
+  QoSPolicyKind: QoSPolicyKind,
+
+  /** {@link QoSOverridingOptions} class */
+  QoSOverridingOptions: QoSOverridingOptions,
+
   /** {@link RMWUtils} */
   RMWUtils: RMWUtils,
 

package/lib/action/client.js

@@ -94,12 +94,13 @@ class ActionClient extends Entity {
     };
 
     // Enable feedback subscription content filter optimization.
-    // Only supported on ROS2 Rolling and only effective when the native
-    // binding provides the required functions AND the RMW implementation
-    // actually supports content filtering on the feedback subscription.
+    // Only supported on ROS2 Lyrical or newer and only effective when the
+    // native binding provides the required functions AND the RMW
+    // implementation actually supports content filtering on the feedback
+    // subscription.
     this._enableFeedbackMsgOptimization =
       this._options.enableFeedbackMsgOptimization === true &&
-      DistroUtils.getDistroId() >= DistroUtils.DistroId.ROLLING &&
+      DistroUtils.getDistroId() >= DistroUtils.DistroId.LYRICAL &&
       typeof rclnodejs.actionConfigureFeedbackSubFilterAddGoalId === 'function';
 
     let type = this.typeClass.type();

package/lib/action/server_goal_handle.js

@@ -82,11 +82,26 @@ class ServerGoalHandle {
   }
 
   /**
-   * Updates the goal handle with the execute status and begins exection.
+   * Transitions the goal to the executing state and begins execution.
+   * Has no effect if the goal is already executing, no longer active, or destroyed.
    * @param {function} callback - An optional callback to use instead of the one provided to the action server.
    * @returns {undefined}
    */
   execute(callback) {
+    if (this._destroyed) {
+      return;
+    }
+
+    // Guard: already executing — no-op
+    if (this.status === ActionInterfaces.GoalStatus.STATUS_EXECUTING) {
+      return;
+    }
+
+    // Guard: only transition if goal is still active
+    if (!this.isActive) {
+      return;
+    }
+
     if (!this.isCancelRequested) {
       this._updateState(GoalEvent.EXECUTE);
     }
@@ -105,6 +120,16 @@ class ServerGoalHandle {
       return;
     }
 
+    if (this.status !== ActionInterfaces.GoalStatus.STATUS_EXECUTING) {
+      this._actionServer._node
+        .getLogger()
+        .warn(
+          `publishFeedback() called on goal ${this.goalId.uuid} ` +
+            `in status ${this.status}, not executing; ignoring`
+        );
+      return;
+    }
+
     let feedbackMessage =
       new this._actionServer.typeClass.impl.FeedbackMessage();
     feedbackMessage['goal_id'] = this.goalId;

package/lib/action/uuid.js

@@ -40,7 +40,7 @@ class ActionUuid {
       this._bytes = bytes;
     } else {
       // Generate random UUID.
-      let uuid = randomUUID().replace(/-/g, '');
+      let uuid = randomUUID().replaceAll('-', '');
       this._bytes = Uint8Array.from(Buffer.from(uuid, 'hex'));
     }
   }

package/lib/client.js

@@ -25,51 +25,6 @@ const {
 const { assertValidMessage } = require('./message_validation.js');
 const debug = require('debug')('rclnodejs:client');
 
-// Polyfill for AbortSignal.any() for Node.js <= 20.3.0
-// AbortSignal.any() was added in Node.js 20.3.0
-// See https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static
-if (!AbortSignal.any) {
-  AbortSignal.any = function (signals) {
-    // Filter out null/undefined values and validate inputs
-    const validSignals = Array.isArray(signals)
-      ? signals.filter((signal) => signal != null)
-      : [];
-
-    // If no valid signals, return a never-aborting signal
-    if (validSignals.length === 0) {
-      return new AbortController().signal;
-    }
-
-    const controller = new AbortController();
-    const listeners = [];
-
-    // Cleanup function to remove all event listeners
-    const cleanup = () => {
-      listeners.forEach(({ signal, listener }) => {
-        signal.removeEventListener('abort', listener);
-      });
-    };
-
-    for (const signal of validSignals) {
-      if (signal.aborted) {
-        cleanup();
-        controller.abort(signal.reason);
-        return controller.signal;
-      }
-
-      const listener = () => {
-        cleanup();
-        controller.abort(signal.reason);
-      };
-
-      signal.addEventListener('abort', listener);
-      listeners.push({ signal, listener });
-    }
-
-    return controller.signal;
-  };
-}
-
 /**
  * @class - Class representing a Client in ROS
  * @hideconstructor

package/lib/distro.js

@@ -26,7 +26,9 @@ const DistroId = {
   IRON: 2305,
   JAZZY: 2405,
   KILTED: 2505,
+  LYRICAL: 2605,
   ROLLING: 5000,
+  FUTURE: 9999, // unrecognized ROS_DISTRO assumed newer than Rolling
 };
 
 const DistroNameIdMap = new Map();
@@ -37,6 +39,7 @@ DistroNameIdMap.set('humble', DistroId.HUMBLE);
 DistroNameIdMap.set('iron', DistroId.IRON);
 DistroNameIdMap.set('jazzy', DistroId.JAZZY);
 DistroNameIdMap.set('kilted', DistroId.KILTED);
+DistroNameIdMap.set('lyrical', DistroId.LYRICAL);
 DistroNameIdMap.set('rolling', DistroId.ROLLING);
 
 const DistroUtils = {
@@ -48,11 +51,15 @@ const DistroUtils = {
    * @return {number} Return the rclnodejs distro identifier
    */
   getDistroId: function (distroName) {
-    const dname = distroName ? distroName.toLowerCase() : this.getDistroName();
+    const dname =
+      (distroName || this.getDistroName() || '').toLowerCase() || undefined;
 
-    return DistroNameIdMap.has(dname)
-      ? DistroNameIdMap.get(dname)
-      : DistroId.UNKNOWN;
+    if (dname && DistroNameIdMap.has(dname)) {
+      return DistroNameIdMap.get(dname);
+    }
+
+    // Unrecognized but provided/resolved distro name → assume future; unset → unknown
+    return dname ? DistroId.FUTURE : DistroId.UNKNOWN;
   },
 
   /**

package/lib/interface_loader.js

@@ -57,7 +57,7 @@ let interfaceLoader = {
     }
 
     // TODO(Kenny): more checks of the string argument
-    if (name.indexOf('/') !== -1) {
+    if (name.includes('/')) {
       let [packageName, type, messageName] = name.split('/');
       return this.loadInterface(packageName, type, messageName);
     }

package/lib/message_introspector.js

@@ -88,35 +88,7 @@ class MessageIntrospector {
       const instance = new this.#typeClass();
       this.#defaultsCache = toPlainObject(instance);
     }
-    return this.#deepClone(this.#defaultsCache);
-  }
-
-  /**
-   * Deep clone an object.
-   * @param {any} obj - Object to clone
-   * @returns {any} Cloned object
-   * @private
-   */
-  #deepClone(obj) {
-    if (obj === null || typeof obj !== 'object') {
-      return obj;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map((item) => this.#deepClone(item));
-    }
-
-    if (ArrayBuffer.isView(obj) && !(obj instanceof DataView)) {
-      return obj.slice();
-    }
-
-    const cloned = {};
-    for (const key in obj) {
-      if (Object.prototype.hasOwnProperty.call(obj, key)) {
-        cloned[key] = this.#deepClone(obj[key]);
-      }
-    }
-    return cloned;
+    return structuredClone(this.#defaultsCache);
   }
 }
 

package/lib/message_serialization.js

@@ -62,7 +62,7 @@ function toPlainArrays(obj) {
   if (typeof obj === 'object' && obj !== null) {
     const result = {};
     for (const key in obj) {
-      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (Object.hasOwn(obj, key)) {
         result[key] = toPlainArrays(obj[key]);
       }
     }
@@ -105,7 +105,7 @@ function toJSONSafe(obj) {
   if (typeof obj === 'object' && obj !== null) {
     const result = {};
     for (const key in obj) {
-      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (Object.hasOwn(obj, key)) {
         result[key] = toJSONSafe(obj[key]);
       }
     }

package/lib/native_loader.js

@@ -20,6 +20,10 @@ const { execSync } = require('child_process');
 const { NativeError } = require('./errors.js');
 const bindings = require('bindings');
 const debug = require('debug')('rclnodejs');
+const {
+  detectPrebuildRuntime,
+  getTaggedPrebuildFilename,
+} = require('./prebuilds');
 const { detectUbuntuCodename } = require('./utils');
 
 let nativeModule = null;
@@ -35,6 +39,7 @@ function customFallbackLoader() {
 
   const rosDistro = process.env.ROS_DISTRO;
   const arch = process.arch;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   // Require all three components for exact match
@@ -58,16 +63,22 @@ function customFallbackLoader() {
   }
 
   try {
-    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
-    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
-    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
-
-    if (fs.existsSync(exactMatchPath)) {
-      debug(`Found exact match binary: ${exactMatchFilename}`);
-      return require(exactMatchPath);
+    const candidate = getTaggedPrebuildFilename({
+      rosDistro,
+      ubuntuCodename,
+      arch,
+      runtime,
+    });
+    const candidatePath = path.join(prebuildDir, candidate);
+
+    if (fs.existsSync(candidatePath)) {
+      debug(`Found ${runtime} prebuilt binary: ${candidate}`);
+      return require(candidatePath);
     }
 
-    debug(`No exact match found for: ${exactMatchFilename}`);
+    debug(
+      `No matching ${runtime} prebuilt binary found for ${rosDistro}-${ubuntuCodename}-${arch}`
+    );
     return null;
   } catch (e) {
     debug('Error in simplified prebuilt loader:', e.message);
@@ -110,10 +121,11 @@ function loadNativeAddon() {
   }
 
   const rosDistro = process.env.ROS_DISTRO;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   debug(
-    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+    `Platform: ${process.platform}, Arch: ${process.arch}, Runtime: ${runtime}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
   );
 
   // Prebuilt binaries are only supported on Linux (Ubuntu)