rclnodejs 1.9.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/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/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)

package/lib/node.js

@@ -1587,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'
       );
@@ -1621,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'
       );

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,
+};

package/lib/rmw.js

@@ -19,6 +19,7 @@ const RMWNames = {
   CONNEXT: 'rmw_connext_cpp',
   CYCLONEDDS: 'rmw_cyclonedds_cpp',
   GURUMDDS: 'rmw_gurumdds_cpp',
+  ZENOH: 'rmw_zenoh_cpp',
 };
 
 const DefaultRosRMWNameMap = new Map();
@@ -26,6 +27,9 @@ DefaultRosRMWNameMap.set('eloquent', RMWNames.FASTRTPS);
 DefaultRosRMWNameMap.set('foxy', RMWNames.FASTRTPS);
 DefaultRosRMWNameMap.set('galactic', RMWNames.CYCLONEDDS);
 DefaultRosRMWNameMap.set('humble', RMWNames.FASTRTPS);
+DefaultRosRMWNameMap.set('iron', RMWNames.FASTRTPS);
+DefaultRosRMWNameMap.set('jazzy', RMWNames.FASTRTPS);
+DefaultRosRMWNameMap.set('kilted', RMWNames.FASTRTPS);
 DefaultRosRMWNameMap.set('rolling', RMWNames.FASTRTPS);
 
 const RMWUtils = {
@@ -34,7 +38,8 @@ const RMWUtils = {
   getRMWName: function () {
     return process.env.RMW_IMPLEMENTATION
       ? process.env.RMW_IMPLEMENTATION
-      : DefaultRosRMWNameMap.get(DistroUtils.getDistroName());
+      : DefaultRosRMWNameMap.get(DistroUtils.getDistroName()) ||
+          RMWNames.FASTRTPS;
   },
 };
 

package/lib/subscription.js

@@ -147,11 +147,11 @@ class Subscription extends Entity {
 
   /**
    * Check if content filtering is supported for this subscription.
-   * Requires ROS 2 Rolling or later.
+   * Requires ROS 2 Lyrical or later.
    * @returns {boolean} True if the subscription instance supports content filtering; otherwise false.
    */
   isContentFilterSupported() {
-    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.LYRICAL) {
       return false;
     }
     return rclnodejs.isContentFilterSupported(this.handle);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.9.0",
+  "version": "2.0.0-beta.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -34,10 +34,14 @@
     "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",
-    "prebuild": "prebuildify --napi --strip --target 16.20.2 --target electron@23.0.0 && node scripts/tag_prebuilds.js"
+    "prebuild:node": "prebuildify --napi --strip --name node --target 20.20.2",
+    "prebuild:electron": "prebuildify --napi --strip --name electron --target electron@34.0.0",
+    "prebuild": "npm run prebuild:node && npm run prebuild:electron && node scripts/tag_prebuilds.js",
+    "rosocket": "node ./rosocket/cli.js"
   },
   "bin": {
-    "generate-ros-messages": "./scripts/generate_messages.js"
+    "generate-ros-messages": "./scripts/generate_messages.js",
+    "rosocket": "./rosocket/cli.js"
   },
   "authors": [
     "Minggang Wang <minggangw@gmail.com>",
@@ -67,7 +71,7 @@
     "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
-    "node-gyp": "^10.3.1",
+    "node-gyp": "^12.2.0",
     "nyc": "^18.0.0",
     "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",
@@ -84,7 +88,8 @@
     "json-bigint": "^1.0.0",
     "node-addon-api": "^8.3.1",
     "rxjs": "^7.8.1",
-    "walk": "^2.3.15"
+    "walk": "^2.3.15",
+    "ws": "^8.18.0"
   },
   "husky": {
     "hooks": {
@@ -103,6 +108,6 @@
     "directory": "test/types"
   },
   "engines": {
-    "node": ">= 16.13.0"
+    "node": ">= 20.20.2"
   }
 }

package/rosidl_gen/packages.js

@@ -29,7 +29,7 @@ const serviceMsgPath = path.join(generatedRoot, 'srv_msg');
 
 function getPackageName(filePath, amentExecuted) {
   if (os.type() === 'Windows_NT') {
-    filePath = filePath.replace(/\\/g, '/');
+    filePath = filePath.replaceAll('\\', '/');
   }
 
   if (amentExecuted) {
@@ -41,14 +41,14 @@ function getPackageName(filePath, amentExecuted) {
 
   // If |packageName| equals to the file's extension, e.g. msg/srv, one level
   // up directory will be used as the package name.
-  return packageName === path.parse(filePath).ext.substr(1)
+  return packageName === path.parse(filePath).ext.substring(1)
     ? folders.pop()
     : packageName;
 }
 
 function getSubFolder(filePath, amentExecuted) {
   if (os.type() === 'Windows_NT') {
-    filePath = filePath.replace(/\\/g, '/');
+    filePath = filePath.replaceAll('\\', '/');
   }
 
   if (amentExecuted) {
@@ -61,7 +61,7 @@ function getSubFolder(filePath, amentExecuted) {
   }
   // If the |amentExecuted| equals to false, the file's extension will be assigned as
   // the name of sub folder.
-  return path.parse(filePath).ext.substr(1);
+  return path.parse(filePath).ext.substring(1);
 }
 
 function grabInterfaceInfo(filePath, amentExecuted) {

package/rosidl_gen/templates/message-template.js

@@ -156,15 +156,15 @@ const typedArrayType = [
 ];
 
 function isPrimitivePackage(baseType) {
-  return primitiveBaseType.indexOf(baseType.type) !== -1;
+  return primitiveBaseType.includes(baseType.type);
 }
 
 function isTypedArrayType(type) {
-  return typedArrayType.indexOf(type.type.toLowerCase()) !== -1;
+  return typedArrayType.includes(type.type.toLowerCase());
 }
 
 function isBigInt(type) {
-  return ['int64', 'uint64'].indexOf(type.type.toLowerCase()) !== -1;
+  return ['int64', 'uint64'].includes(type.type.toLowerCase());
 }
 
 function getWrapperNameByType(type) {
@@ -265,6 +265,14 @@ function generateMessage(data) {
   const currentTypedArray = getTypedArrayName(spec.baseType);
   const currentTypedArrayElementType = getTypedArrayElementName(spec.baseType);
 
+  // ROS 2 Rolling (ros2/rosidl#941) added is_rosidl_buffer / owns_rosidl_buffer
+  // to every primitive sequence struct. Lyrical inherits the same ABI change.
+  // Emit the extra fields only for primitive-package types on Lyrical+.
+  const DistroUtils = require('../../lib/distro.js');
+  const needsRosidlBufferFields =
+    isPrimitivePackage(spec.baseType) &&
+    DistroUtils.getDistroId() >= DistroUtils.DistroId.LYRICAL;
+
   // Track required modules
   let existedModules = [];
   function shouldRequire(baseType, fieldType) {
@@ -275,7 +283,7 @@ function generateMessage(data) {
         !fieldType.isPrimitiveType ||
         fieldType.type === 'string');
 
-    if (shouldReq && existedModules.indexOf(requiredModule) === -1) {
+    if (shouldReq && !existedModules.includes(requiredModule)) {
       existedModules.push(requiredModule);
       return true;
     } else {
@@ -347,7 +355,13 @@ ${
     : `  data: ${refArrayType},`
 }
   size: ref.types.size_t,
-  capacity: ref.types.size_t
+  capacity: ref.types.size_t,
+${
+  needsRosidlBufferFields
+    ? `  is_rosidl_buffer: ref.types.bool,
+  owns_rosidl_buffer: ref.types.bool,`
+    : ''
+}
 });
 
 ${generateWrapperClass()}
@@ -678,7 +692,7 @@ ${spec.fields
 
   hasMember(name) {
     let memberNames = ${extractMemberNames(spec.fields)};
-    return memberNames.indexOf(name) !== -1;
+    return memberNames.includes(name);
   }
 }`;
   }