rclnodejs 1.7.0 → 1.8.0

package/lib/node_options.js

@@ -27,18 +27,24 @@ class NodeOptions {
    * @param {array} [parameterOverrides=[]]
    * @param {boolean} [automaticallyDeclareParametersFromOverrides=false]
    * @param {boolean} [startTypeDescriptionService=true]
+   * @param {boolean} [enableRosout=true]
+   * @param {QoS} [rosoutQos=QoS.profileDefault]
    */
   constructor(
     startParameterServices = true,
     parameterOverrides = [],
     automaticallyDeclareParametersFromOverrides = false,
-    startTypeDescriptionService = true
+    startTypeDescriptionService = true,
+    enableRosout = true,
+    rosoutQos = null
   ) {
     this._startParameterServices = startParameterServices;
     this._parameterOverrides = parameterOverrides;
     this._automaticallyDeclareParametersFromOverrides =
       automaticallyDeclareParametersFromOverrides;
     this._startTypeDescriptionService = startTypeDescriptionService;
+    this._enableRosout = enableRosout;
+    this._rosoutQos = rosoutQos;
   }
 
   /**
@@ -125,6 +131,39 @@ class NodeOptions {
     this._startTypeDescriptionService = willStartTypeDescriptionService;
   }
 
+  /**
+   * Get the enableRosout option.
+   * Default value = true;
+   * @returns {boolean} - true if the rosout logging is enabled.
+   */
+  get enableRosout() {
+    return this._enableRosout;
+  }
+
+  /**
+   * Set enableRosout.
+   * @param {boolean} enableRosout
+   */
+  set enableRosout(enableRosout) {
+    this._enableRosout = enableRosout;
+  }
+
+  /**
+   * Get the rosoutQos option.
+   * @returns {QoS} - The QoS profile for rosout.
+   */
+  get rosoutQos() {
+    return this._rosoutQos;
+  }
+
+  /**
+   * Set rosoutQos.
+   * @param {QoS} rosoutQos
+   */
+  set rosoutQos(rosoutQos) {
+    this._rosoutQos = rosoutQos;
+  }
+
   /**
    * Return an instance configured with default options.
    * @returns {NodeOptions} - An instance with default values.

package/lib/observable_subscription.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2025 Mahmoud Alghalayini. 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 { Subject } = require('rxjs');
+
+/**
+ * A wrapper that provides RxJS Observable support for ROS 2 subscriptions.
+ * This class wraps a standard Subscription and emits messages through an Observable.
+ *
+ * @class ObservableSubscription
+ * @hideconstructor
+ */
+class ObservableSubscription {
+  #subscription;
+  #subject;
+  #destroyed;
+
+  /**
+   * Create an ObservableSubscription wrapper.
+   * @param {Subscription} subscription - The underlying ROS 2 subscription
+   */
+  constructor(subscription) {
+    this.#subscription = subscription;
+    this.#subject = new Subject();
+    this.#destroyed = false;
+  }
+
+  /**
+   * Get the RxJS Observable for this subscription.
+   * Use this to pipe operators and subscribe to messages.
+   * @type {Observable}
+   */
+  get observable() {
+    return this.#subject.asObservable();
+  }
+
+  /**
+   * Get the underlying ROS 2 subscription.
+   * @type {Subscription}
+   */
+  get subscription() {
+    return this.#subscription;
+  }
+
+  /**
+   * Get the topic name.
+   * @type {string}
+   */
+  get topic() {
+    return this.#subscription.topic;
+  }
+
+  /**
+   * Check if this observable subscription has been destroyed.
+   * @type {boolean}
+   */
+  get isDestroyed() {
+    return this.#destroyed;
+  }
+
+  /**
+   * Internal method to emit a message to subscribers.
+   * Called by the subscription's processResponse.
+   * @private
+   * @param {any} message - The message to emit
+   */
+  _emit(message) {
+    if (!this.#destroyed) {
+      this.#subject.next(message);
+    }
+  }
+
+  /**
+   * Complete the observable and clean up resources.
+   * After calling this, no more messages will be emitted.
+   */
+  complete() {
+    if (!this.#destroyed) {
+      this.#destroyed = true;
+      this.#subject.complete();
+    }
+  }
+
+  /**
+   * Alias for complete() for consistency with RxJS naming.
+   */
+  destroy() {
+    this.complete();
+  }
+}
+
+module.exports = ObservableSubscription;

package/lib/publisher.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const debug = require('debug')('rclnodejs:publisher');
 const Entity = require('./entity.js');
+const { assertValidMessage } = require('./message_validation.js');
 
 /**
  * @class - Class representing a Publisher in ROS
@@ -27,6 +28,11 @@ class Publisher extends Entity {
   constructor(handle, typeClass, topic, options, node, eventCallbacks) {
     super(handle, typeClass, options);
     this._node = node;
+    this._validateMessages = options.validateMessages || false;
+    this._validationOptions = options.validationOptions || {
+      strict: true,
+      checkTypes: true,
+    };
     if (node && eventCallbacks) {
       this._events = eventCallbacks.createEventHandlers(this.handle);
       node._events.push(...this._events);
@@ -44,12 +50,24 @@ class Publisher extends Entity {
    * Publish a message
    * @param {object|Buffer} message - The message to be sent, could be kind of JavaScript message generated from .msg
    *                                  or be a Buffer for a raw message.
+   * @param {object} [options] - Publish options
+   * @param {boolean} [options.validate] - Override validateMessages setting for this publish call
    * @return {undefined}
+   * @throws {MessageValidationError} If validation is enabled and message is invalid
    */
-  publish(message) {
+  publish(message, options = {}) {
     if (message instanceof Buffer) {
       rclnodejs.publishRawMessage(this._handle, message);
     } else {
+      const shouldValidate =
+        options.validate !== undefined
+          ? options.validate
+          : this._validateMessages;
+
+      if (shouldValidate && !(message instanceof this._typeClass)) {
+        assertValidMessage(message, this._typeClass, this._validationOptions);
+      }
+
       // Enables call by plain object/number/string argument
       //  e.g. publisher.publish(3.14);
       //       publisher.publish('The quick brown fox...');
@@ -65,6 +83,35 @@ class Publisher extends Entity {
     debug(`Message of topic ${this.topic} has been published.`);
   }
 
+  /**
+   * Whether messages will be validated before publishing.
+   * @type {boolean}
+   */
+  get willValidateMessage() {
+    return this._validateMessages;
+  }
+
+  /**
+   * Enable or disable message validation for this publisher.
+   * @param {boolean} value - Whether to validate messages before publishing
+   */
+  set willValidateMessage(value) {
+    this._validateMessages = value;
+  }
+
+  /**
+   * Set validation options for this publisher.
+   * @param {object} options - Validation options
+   * @param {boolean} [options.strict=true] - Throw on unknown fields
+   * @param {boolean} [options.checkTypes=true] - Validate field types
+   * @param {boolean} [options.checkRequired=false] - Check for missing fields
+   */
+  setValidation(options) {
+    if (options && Object.keys(options).length > 0) {
+      this._validationOptions = { ...this._validationOptions, ...options };
+    }
+  }
+
   static createPublisher(node, typeClass, topic, options, eventCallbacks) {
     let type = typeClass.type();
     let handle = rclnodejs.createPublisher(
@@ -112,6 +159,14 @@ class Publisher extends Entity {
     return rclnodejs.waitForAllAcked(this._handle, timeout);
   }
 
+  /**
+   * Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC).
+   * @return {undefined}
+   */
+  assertLiveliness() {
+    rclnodejs.assertLiveliness(this._handle);
+  }
+
   /**
    * Get the event handlers for this publisher.
    * @returns {Array} The array of event handlers for this publisher.

package/lib/qos.js

@@ -58,6 +58,24 @@ let DurabilityPolicy = {
   RMW_QOS_POLICY_DURABILITY_VOLATILE: 2,
 };
 
+/**
+ * Enum for LivelinessPolicy
+ * @readonly
+ * @enum {number}
+ */
+let LivelinessPolicy = {
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT: 0,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_AUTOMATIC: 1,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC: 3,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_UNKNOWN: 4,
+  /** @member {number} */
+  RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE: 5,
+};
+
 /** Class representing middleware quality of service */
 class QoS {
   /**
@@ -73,12 +91,14 @@ class QoS {
     depth = 0,
     reliability = ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT,
     durability = DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT,
+    liveliness = LivelinessPolicy.RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT,
     avoidRosNameSpaceConventions = false
   ) {
     this._history = history;
     this._depth = depth;
     this._reliability = reliability;
     this._durability = durability;
+    this._liveliness = liveliness;
     this._avoidRosNameSpaceConventions = avoidRosNameSpaceConventions;
   }
 
@@ -112,6 +132,16 @@ class QoS {
     return DurabilityPolicy;
   }
 
+  /**
+   * Get LivelinessPolicy enum.
+   * @name QoS#static get:LivelinessPolicy
+   * @function
+   * @return {LivelinessPolicy}
+   */
+  static get LivelinessPolicy() {
+    return LivelinessPolicy;
+  }
+
   /**
    * Get the history value.
    * @name QoS#get:history
@@ -220,6 +250,33 @@ class QoS {
     this._durability = durability;
   }
 
+  /**
+   * Get the liveliness value.
+   * @name QoS#get:liveliness
+   * @function
+   * @return {number}
+   */
+  get liveliness() {
+    return this._liveliness;
+  }
+
+  /**
+   * Set the liveliness value.
+   * @param {number} liveliness - value to be set.
+   * @name QoS#set:liveliness
+   * @function
+   * @return {undefined}
+   */
+  set liveliness(liveliness) {
+    if (typeof liveliness !== 'number') {
+      throw new TypeValidationError('liveliness', liveliness, 'number', {
+        entityType: 'qos',
+      });
+    }
+
+    this._liveliness = liveliness;
+  }
+
   /**
    * Get the avoidRosNameSpaceConventions value.
    * @name QoS#get:avoidRosNameSpaceConventions

package/lib/subscription.js

@@ -151,6 +151,14 @@ class Subscription extends Entity {
       : this.clearContentFilter();
   }
 
+  /**
+   * Get the current content-filter.
+   * @returns {object} - The content-filter description {expression: string, parameters: string[]} or undefined if not set/supported.
+   */
+  getContentFilter() {
+    return rclnodejs.getContentFilter(this.handle);
+  }
+
   /**
    * Clear the current content-filter. No filtering is to be applied.
    * @returns {boolean} - True if successful; false otherwise

package/lib/timer.js

@@ -88,6 +88,19 @@ class Timer {
     return rclnodejs.timerGetTimeUntilNextCall(this._handle);
   }
 
+  /**
+   * Get the absolute time in nanoseconds when the next callback is due.
+   * Note: Only available on ROS2 distributions after Humble.
+   * @return {bigint | null} - The next call time in nanoseconds, or null if the timer is canceled.
+   *   Returns undefined if not supported on current ROS2 distribution.
+   */
+  getNextCallTime() {
+    if (typeof rclnodejs.getTimerNextCallTime !== 'function') {
+      return undefined;
+    }
+    return rclnodejs.getTimerNextCallTime(this._handle);
+  }
+
   /**
    * Change the timer period.
    * @param {bigint} period - The new period in nanoseconds.
@@ -105,6 +118,35 @@ class Timer {
     return rclnodejs.getTimerPeriod(this._handle);
   }
 
+  /**
+   * Set the on reset callback.
+   * @param {function} callback - The callback to be called when the timer is reset.
+   * @return {undefined}
+   */
+  setOnResetCallback(callback) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'setOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.setTimerOnResetCallback(this._handle, callback);
+  }
+
+  /**
+   * Clear the on reset callback.
+   * @return {undefined}
+   */
+  clearOnResetCallback() {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'clearOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.clearTimerOnResetCallback(this._handle);
+  }
+
   /**
    * Call a timer and starts counting again, retrieves actual and expected call time.
    * @return {object} - The timer information.

package/lib/validator.js

@@ -28,8 +28,10 @@ let validator = {
 
   /**
    * Validate a given topic or service name, and throw an error if invalid.
-   * @param {string} topic - The name of topic/service. and it must be fully-qualified and already expanded.
-   * @return {boolean} - True if it is valid.
+   * @param {string} topic - The name of topic/service. Must be fully-qualified and already expanded.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If topic is not a string.
+   * @throws {NameValidationError} If the topic name is invalid.
    */
   validateFullTopicName(topic) {
     if (typeof topic !== 'string') {
@@ -43,10 +45,24 @@ let validator = {
     throw this._createErrorFromValidation(result, topic, 'topic');
   },
 
+  /**
+   * Check if a fully-qualified topic name is valid without throwing.
+   * @param {string} topic - The name of topic/service. Must be fully-qualified and already expanded.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidFullTopicName(topic) {
+    if (typeof topic !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateFullTopicName(topic) === null;
+  },
+
   /**
    * Validate a given node name, and throw an error if invalid.
    * @param {string} name - The name of node.
-   * @return {boolean} - True if it is valid.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If name is not a string.
+   * @throws {NameValidationError} If the node name is invalid.
    */
   validateNodeName(name) {
     if (typeof name !== 'string') {
@@ -60,10 +76,24 @@ let validator = {
     throw this._createErrorFromValidation(result, name, 'node');
   },
 
+  /**
+   * Check if a node name is valid without throwing.
+   * @param {string} name - The name of node.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidNodeName(name) {
+    if (typeof name !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateNodeName(name) === null;
+  },
+
   /**
    * Validate a given topic or service name, and throw an error if invalid.
-   * @param {string} topic - The name of topic/service and does not have to be fully-qualified and is not expanded.
-   * @return {boolean} - True if it is valid.
+   * @param {string} topic - The name of topic/service. Does not have to be fully-qualified.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If topic is not a string.
+   * @throws {NameValidationError} If the topic name is invalid.
    */
   validateTopicName(topic) {
     if (typeof topic !== 'string') {
@@ -77,10 +107,24 @@ let validator = {
     throw this._createErrorFromValidation(result, topic, 'topic');
   },
 
+  /**
+   * Check if a topic name is valid without throwing.
+   * @param {string} topic - The name of topic/service. Does not have to be fully-qualified.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidTopicName(topic) {
+    if (typeof topic !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateTopicName(topic) === null;
+  },
+
   /**
    * Validate a given namespace, and throw an error if invalid.
-   * @param {string} namespace - The namespace to be validated
-   * @return {boolean} - True if it is valid.
+   * @param {string} namespace - The namespace to be validated.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If namespace is not a string.
+   * @throws {NameValidationError} If the namespace is invalid.
    */
   validateNamespace(namespace) {
     if (typeof namespace !== 'string') {
@@ -93,6 +137,18 @@ let validator = {
     }
     throw this._createErrorFromValidation(result, namespace, 'namespace');
   },
+
+  /**
+   * Check if a namespace is valid without throwing.
+   * @param {string} namespace - The namespace to be validated.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidNamespace(namespace) {
+    if (typeof namespace !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateNamespace(namespace) === null;
+  },
 };
 
 module.exports = validator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
-    "@types/node": "^24.5.2",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",
     "clang-format": "^1.8.0",
@@ -64,6 +64,7 @@
     "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
+    "node-gyp": "^12.1.0",
     "nyc": "^17.1.0",
     "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",
@@ -79,6 +80,7 @@
     "debug": "^4.4.0",
     "json-bigint": "^1.0.0",
     "node-addon-api": "^8.3.1",
+    "rxjs": "^7.8.1",
     "walk": "^2.3.15"
   },
   "husky": {

package/rosidl_gen/message_translator.js

@@ -58,66 +58,6 @@ function copyMsgObject(msg, obj) {
   }
 }
 
-function verifyMessage(message, obj) {
-  if (message.constructor.isROSArray) {
-    // It's a ROS message array
-    // Note: there won't be any JavaScript array in message.
-    if (!Array.isArray(obj)) {
-      return false;
-    }
-    // TODO(Kenny): deal with TypedArray in the future
-    // TODO(Kenny): if the elements are objects, check the objects
-  } else {
-    // It's a ROS message
-    const def = message.constructor.ROSMessageDef;
-    let obj = {};
-    for (let i in def.fields) {
-      const name = def.fields[i].name;
-      if (def.fields[i].type.isPrimitiveType) {
-        // check type/existence
-        switch (def.fields[i].type) {
-          case 'char':
-          case 'int16':
-          case 'int32':
-          case 'byte':
-          case 'uint16':
-          case 'uint32':
-          case 'float32':
-          case 'float64':
-            if (typeof obj[name] != 'number') {
-              return false;
-            }
-            break;
-          case 'int64':
-          case 'uint64':
-            if (typeof obj[name] != 'bigint') {
-              return false;
-            }
-          case 'bool':
-            if (typeof obj[name] != 'boolean') {
-              return false;
-            }
-            break;
-          case 'string':
-            if (typeof obj[name] != 'string') {
-              return false;
-            }
-            break;
-        }
-      } else if (!verifyMessage(message[name], obj[name])) {
-        // Proceed further on this member
-        return false;
-      }
-    }
-  }
-  return true;
-}
-
-function verifyMessageStruct(MessageType, obj) {
-  const msg = new MessageType();
-  return verifyMessage(msg, obj);
-}
-
 function toPlainObject(message, enableTypedArray = true) {
   if (!message) return undefined;
 
@@ -186,7 +126,6 @@ function constructFromPlanObject(msg, obj) {
 }
 
 module.exports = {
-  verifyMessageStruct: verifyMessageStruct,
   toROSMessage: toROSMessage,
   toPlainObject: toPlainObject,
   constructFromPlanObject: constructFromPlanObject,

package/scripts/config.js

@@ -33,6 +33,7 @@ const dependencies = [
   'rosidl_runtime_c',
   'rosidl_dynamic_typesupport',
   'type_description_interfaces',
+  'rcl_logging_interface',
 ];
 
 const command = os.type() === 'Windows_NT' ? 'where ros2' : 'which ros2';

package/src/addon.cpp

@@ -15,6 +15,7 @@
 #include <node_api.h>
 #include <rcutils/logging.h>
 
+#include "clock_event.hpp"
 #include "macros.h"
 #include "rcl_action_client_bindings.h"
 #include "rcl_action_goal_bindings.h"
@@ -74,6 +75,7 @@ Napi::Object InitModule(Napi::Env env, Napi::Object exports) {
   rclnodejs::InitActionGoalBindings(env, exports);
   rclnodejs::InitActionServerBindings(env, exports);
   rclnodejs::InitClientBindings(env, exports);
+  rclnodejs::InitClockEventBindings(env, exports);
   rclnodejs::InitContextBindings(env, exports);
   rclnodejs::InitGraphBindings(env, exports);
   rclnodejs::InitGuardConditionBindings(env, exports);