rclnodejs 1.9.0-alpha.0 → 2.0.0-beta.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/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/lib/timer.js

@@ -150,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.9.0-alpha.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": "^12.1.0",
+    "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);
   }
 }`;
   }