rclnodejs 1.7.0 → 1.8.0

package/binding.gyp

@@ -26,6 +26,7 @@
         './src/rcl_action_server_bindings.cpp',
         './src/rcl_bindings.cpp',
         './src/rcl_client_bindings.cpp',
+        './src/clock_event.cpp',
         './src/rcl_context_bindings.cpp',
         './src/rcl_graph_bindings.cpp',
         './src/rcl_guard_condition_bindings.cpp',
@@ -67,6 +68,7 @@
         '-lrcl_action',
         '-lrcl_lifecycle',
         '-lrcutils',
+        '-lrcl_logging_interface',
         '-lrcl_yaml_param_parser',
         '-lrcpputils',
         '-lrmw',

package/index.js

@@ -17,7 +17,9 @@
 const DistroUtils = require('./lib/distro.js');
 const RMWUtils = require('./lib/rmw.js');
 const { Clock, ROSClock } = require('./lib/clock.js');
+const ClockEvent = require('./lib/clock_event.js');
 const ClockType = require('./lib/clock_type.js');
+const ClockChange = require('./lib/clock_change.js');
 const { compareVersions } = require('./lib/utils.js');
 const Context = require('./lib/context.js');
 const debug = require('debug')('rclnodejs');
@@ -61,7 +63,18 @@ const {
 const ParameterClient = require('./lib/parameter_client.js');
 const errors = require('./lib/errors.js');
 const ParameterWatcher = require('./lib/parameter_watcher.js');
+const MessageIntrospector = require('./lib/message_introspector.js');
+const ObservableSubscription = require('./lib/observable_subscription.js');
 const { spawn } = require('child_process');
+const {
+  ValidationProblem,
+  getMessageSchema,
+  getFieldNames,
+  getFieldType,
+  validateMessage,
+  assertValidMessage,
+  createMessageValidator,
+} = require('./lib/message_validation.js');
 
 /**
  * Get the version of the generator that was used for the currently present interfaces.
@@ -178,9 +191,15 @@ let rcl = {
   /** {@link Clock} class */
   Clock: Clock,
 
+  /** {@link ClockEvent} class */
+  ClockEvent: ClockEvent,
+
   /** {@link ClockType} enum */
   ClockType: ClockType,
 
+  /** {@link ClockChange} enum */
+  ClockChange: ClockChange,
+
   /** {@link Context} class */
   Context: Context,
 
@@ -226,6 +245,9 @@ let rcl = {
   /** {@link ParameterWatcher} class */
   ParameterWatcher: ParameterWatcher,
 
+  /** {@link ObservableSubscription} class */
+  ObservableSubscription: ObservableSubscription,
+
   /** {@link QoS} class */
   QoS: QoS,
 
@@ -386,6 +408,21 @@ let rcl = {
     _rosVersionChecked = true;
   },
 
+  /**
+   * Remove ROS-specific arguments from the given argument list.
+   * @param {string[]} argv - The argument list to process.
+   * @return {string[]} The argument list with ROS arguments removed.
+   */
+  removeROSArgs(argv) {
+    if (!Array.isArray(argv)) {
+      throw new TypeError('argv must be an array.');
+    }
+    if (!argv.every((argument) => typeof argument === 'string')) {
+      throw new TypeError('argv elements must be strings (and not null).');
+    }
+    return rclnodejs.removeROSArgs(argv);
+  },
+
   /**
    * Start detection and processing of units of work.
    * @param {Node} node - The node to be spun up.
@@ -566,6 +603,57 @@ let rcl = {
    */
   toJSONString: toJSONString,
 
+  /** {@link ValidationProblem} - Enum of validation problem types */
+  ValidationProblem: ValidationProblem,
+
+  /**
+   * Get the schema definition for a message type
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @returns {object|null} Schema definition with fields and constants
+   */
+  getMessageSchema: getMessageSchema,
+
+  /**
+   * Get field names for a message type
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @returns {string[]} Array of field names
+   */
+  getFieldNames: getFieldNames,
+
+  /**
+   * Get type information for a specific field
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @param {string} fieldName - Name of the field
+   * @returns {object|null} Field type information or null if not found
+   */
+  getFieldType: getFieldType,
+
+  /**
+   * Validate a message object against its schema
+   * @param {object} obj - Plain object to validate
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @param {object} [options] - Validation options
+   * @returns {{valid: boolean, issues: Array<object>}} Validation result
+   */
+  validateMessage: validateMessage,
+
+  /**
+   * Validate a message and throw if invalid
+   * @param {object} obj - Plain object to validate
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @param {object} [options] - Validation options
+   * @throws {MessageValidationError} If validation fails
+   */
+  assertValidMessage: assertValidMessage,
+
+  /**
+   * Create a validator function for a specific message type
+   * @param {function|string|object} typeClass - Message type class or identifier
+   * @param {object} [defaultOptions] - Default validation options
+   * @returns {function} Validator function
+   */
+  createMessageValidator: createMessageValidator,
+
   // Error classes for structured error handling
   /** {@link RclNodeError} - Base error class for all rclnodejs errors */
   RclNodeError: errors.RclNodeError,
@@ -576,6 +664,8 @@ let rcl = {
   TypeValidationError: errors.TypeValidationError,
   /** {@link RangeValidationError} - Range/value validation error */
   RangeValidationError: errors.RangeValidationError,
+  /** {@link MessageValidationError} - Message structure/type validation error */
+  MessageValidationError: errors.MessageValidationError,
   /** {@link NameValidationError} - ROS name validation error */
   NameValidationError: errors.NameValidationError,
 
@@ -644,3 +734,6 @@ const Lifecycle = require('./lib/lifecycle.js');
 
 /** Lifecycle namespace */
 rcl.lifecycle = Lifecycle;
+
+/** {@link MessageIntrospector} class */
+rcl.MessageIntrospector = MessageIntrospector;

package/lib/action/client.js

@@ -28,6 +28,7 @@ const {
   ActionError,
   OperationError,
 } = require('../errors.js');
+const { assertValidMessage } = require('../message_validation.js');
 
 /**
  * @class - ROS Action client.
@@ -80,6 +81,12 @@ class ActionClient extends Entity {
     this._options.qos.statusSubQosProfile =
       this._options.qos.statusSubQosProfile || QoS.profileActionStatusDefault;
 
+    this._validateGoals = this._options.validateGoals || false;
+    this._validationOptions = this._options.validationOptions || {
+      strict: true,
+      checkTypes: true,
+    };
+
     let type = this.typeClass.type();
 
     this._handle = rclnodejs.actionCreateClient(
@@ -200,6 +207,34 @@ class ActionClient extends Entity {
     }
   }
 
+  /**
+   * Whether goals will be validated before sending.
+   * @type {boolean}
+   */
+  get willValidateGoal() {
+    return this._validateGoals;
+  }
+
+  /**
+   * Enable or disable goal validation for this action client.
+   * @param {boolean} value - Whether to validate goals
+   */
+  set willValidateGoal(value) {
+    this._validateGoals = value;
+  }
+
+  /**
+   * Set validation options for this action client.
+   * @param {object} options - Validation options
+   * @param {boolean} [options.strict=true] - Throw on unknown fields
+   * @param {boolean} [options.checkTypes=true] - Validate field types
+   */
+  setValidation(options) {
+    if (options && Object.keys(options).length > 0) {
+      this._validationOptions = { ...this._validationOptions, ...options };
+    }
+  }
+
   /**
    * Send a goal and wait for the goal ACK asynchronously.
    *
@@ -209,9 +244,27 @@ class ActionClient extends Entity {
    * @param {object} goal - The goal request.
    * @param {function} feedbackCallback - Callback function for feedback associated with the goal.
    * @param {object} goalUuid - Universally unique identifier for the goal. If None, then a random UUID is generated.
+   * @param {object} [options] - Send options
+   * @param {boolean} [options.validate] - Override validateGoals setting for this call
    * @returns {Promise} - A Promise to a goal handle that resolves when the goal request has been accepted or rejected.
+   * @throws {MessageValidationError} If validation is enabled and goal is invalid
    */
-  sendGoal(goal, feedbackCallback, goalUuid) {
+  sendGoal(goal, feedbackCallback, goalUuid, options = {}) {
+    const shouldValidate =
+      options.validate !== undefined ? options.validate : this._validateGoals;
+
+    if (shouldValidate) {
+      const GoalType = this._typeClass.impl.SendGoalService.Request;
+      const goalInstance = new GoalType();
+      if (goalInstance.goal && goalInstance.goal.constructor) {
+        assertValidMessage(
+          goal,
+          goalInstance.goal.constructor,
+          this._validationOptions
+        );
+      }
+    }
+
     let request = new this._typeClass.impl.SendGoalService.Request();
     request['goal_id'] = goalUuid || ActionUuid.randomMessage();
     request.goal = goal;

package/lib/client.js

@@ -22,6 +22,7 @@ const {
   TimeoutError,
   AbortError,
 } = require('./errors.js');
+const { assertValidMessage } = require('./message_validation.js');
 const debug = require('debug')('rclnodejs:client');
 
 // Polyfill for AbortSignal.any() for Node.js <= 20.3.0
@@ -80,6 +81,39 @@ class Client extends Entity {
     this._nodeHandle = nodeHandle;
     this._serviceName = serviceName;
     this._sequenceNumberToCallbackMap = new Map();
+    this._validateRequests = options.validateRequests || false;
+    this._validationOptions = options.validationOptions || {
+      strict: true,
+      checkTypes: true,
+    };
+  }
+
+  /**
+   * Whether requests will be validated before sending.
+   * @type {boolean}
+   */
+  get willValidateRequest() {
+    return this._validateRequests;
+  }
+
+  /**
+   * Enable or disable request validation for this client.
+   * @param {boolean} value - Whether to validate requests
+   */
+  set willValidateRequest(value) {
+    this._validateRequests = value;
+  }
+
+  /**
+   * Set validation options for this client.
+   * @param {object} options - Validation options
+   * @param {boolean} [options.strict=true] - Throw on unknown fields
+   * @param {boolean} [options.checkTypes=true] - Validate field types
+   */
+  setValidation(options) {
+    if (options && Object.keys(options).length > 0) {
+      this._validationOptions = { ...this._validationOptions, ...options };
+    }
   }
 
   /**
@@ -96,10 +130,13 @@ class Client extends Entity {
    * Send the request and will be notified asynchronously if receiving the response.
    * @param {object} request - The request to be submitted.
    * @param {ResponseCallback} callback - Thc callback function for receiving the server response.
+   * @param {object} [options] - Send options
+   * @param {boolean} [options.validate] - Override validateRequests setting for this call
    * @return {undefined}
+   * @throws {MessageValidationError} If validation is enabled and request is invalid
    * @see {@link ResponseCallback}
    */
-  sendRequest(request, callback) {
+  sendRequest(request, callback, options = {}) {
     if (typeof callback !== 'function') {
       throw new TypeValidationError('callback', callback, 'function', {
         entityType: 'service',
@@ -107,6 +144,19 @@ class Client extends Entity {
       });
     }
 
+    const shouldValidate =
+      options.validate !== undefined
+        ? options.validate
+        : this._validateRequests;
+
+    if (shouldValidate && !(request instanceof this._typeClass.Request)) {
+      assertValidMessage(
+        request,
+        this._typeClass.Request,
+        this._validationOptions
+      );
+    }
+
     let requestToSend =
       request instanceof this._typeClass.Request
         ? request
@@ -124,9 +174,11 @@ class Client extends Entity {
    * @param {object} [options] - Optional parameters for the request.
    * @param {number} [options.timeout] - Timeout in milliseconds for the request.
    * @param {AbortSignal} [options.signal] - AbortSignal to cancel the request.
+   * @param {boolean} [options.validate] - Override validateRequests setting for this call
    * @return {Promise<object>} Promise that resolves with the service response.
    * @throws {module:rclnodejs.TimeoutError} If the request times out (when options.timeout is exceeded).
    * @throws {module:rclnodejs.AbortError} If the request is manually aborted (via options.signal).
+   * @throws {module:rclnodejs.MessageValidationError} If validation is enabled and request is invalid.
    * @throws {Error} If the request fails for other reasons.
    */
   sendRequestAsync(request, options = {}) {
@@ -191,6 +243,19 @@ class Client extends Entity {
       }
 
       try {
+        const shouldValidate =
+          options.validate !== undefined
+            ? options.validate
+            : this._validateRequests;
+
+        if (shouldValidate && !(request instanceof this._typeClass.Request)) {
+          assertValidMessage(
+            request,
+            this._typeClass.Request,
+            this._validationOptions
+          );
+        }
+
         let requestToSend =
           request instanceof this._typeClass.Request
             ? request

package/lib/clock.js

@@ -17,6 +17,9 @@
 const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
+const ClockChange = require('./clock_change.js');
+const Context = require('./context.js');
+const ClockEvent = require('./clock_event.js');
 const { TypeValidationError } = require('./errors.js');
 
 /**
@@ -48,6 +51,71 @@ class Clock {
     return this._clockType;
   }
 
+  /**
+   * Add a clock callback.
+   * @param {object} callbackObject - The object containing callback methods.
+   * @param {Function} [callbackObject._pre_callback] - Optional callback invoked before a time jump. Takes no arguments.
+   * @param {Function} [callbackObject._post_callback] - Optional callback invoked after a time jump.
+   *   Receives a jumpInfo object with properties:
+   *   - clock_change {number}: Type of clock change that occurred.
+   *   - delta {bigint}: Time delta in nanoseconds.
+   * @param {boolean} onClockChange - Whether to call the callback on clock change.
+   * @param {bigint} minForward - Minimum forward jump in nanoseconds to trigger the callback.
+   * @param {bigint} minBackward - Minimum backward jump in nanoseconds to trigger the callback.
+   */
+  addClockCallback(callbackObject, onClockChange, minForward, minBackward) {
+    if (typeof callbackObject !== 'object' || callbackObject === null) {
+      throw new TypeValidationError(
+        'callbackObject',
+        callbackObject,
+        'object',
+        {
+          entityType: 'clock',
+        }
+      );
+    }
+    if (typeof onClockChange !== 'boolean') {
+      throw new TypeValidationError('onClockChange', onClockChange, 'boolean', {
+        entityType: 'clock',
+      });
+    }
+    if (typeof minForward !== 'bigint') {
+      throw new TypeValidationError('minForward', minForward, 'bigint', {
+        entityType: 'clock',
+      });
+    }
+    if (typeof minBackward !== 'bigint') {
+      throw new TypeValidationError('minBackward', minBackward, 'bigint', {
+        entityType: 'clock',
+      });
+    }
+    rclnodejs.clockAddJumpCallback(
+      this._handle,
+      callbackObject,
+      onClockChange,
+      minForward,
+      minBackward
+    );
+  }
+
+  /**
+   * Remove a clock callback.
+   * @param {object} callbackObject - The callback object that was previously registered with addClockCallback().
+   */
+  removeClockCallback(callbackObject) {
+    if (typeof callbackObject !== 'object' || callbackObject === null) {
+      throw new TypeValidationError(
+        'callbackObject',
+        callbackObject,
+        'object',
+        {
+          entityType: 'clock',
+        }
+      );
+    }
+    rclnodejs.clockRemoveJumpCallback(this._handle, callbackObject);
+  }
+
   /**
    * Return the current time.
    * @return {Time} Return the current time.
@@ -56,6 +124,116 @@ class Clock {
     const nowInNanosec = rclnodejs.clockGetNow(this._handle);
     return new Time(0n, nowInNanosec, this._clockType);
   }
+
+  /**
+   * Sleep until a specific time is reached on this Clock.
+   *
+   * When using a ROSClock, this may sleep forever if the TimeSource is misconfigured
+   * and the context is never shut down. ROS time being activated or deactivated causes
+   * this function to cease sleeping and return false.
+   *
+   * @param {Time} until - Time at which this function should stop sleeping.
+   * @param {Context} [context=null] - Context whose validity will be checked while sleeping.
+   *   If context is null, then the default context is used. If the context is found to be
+   *   shut down before or by the time the wait completes, the returned promise resolves to false.
+   * @return {Promise<boolean>} Promise that resolves to true if 'until' was reached without
+   *   detecting a time jump or a shut down context, or false otherwise (for example, if a time
+   *   jump occurred or the context is no longer valid when the wait completes).
+   * @throws {TypeError} if until is specified for a different type of clock than this one.
+   * @throws {Error} if context has not been initialized or is shutdown.
+   */
+  async sleepUntil(until, context = null) {
+    if (!(until instanceof Time)) {
+      throw new TypeValidationError('until', until, 'Time', {
+        entityType: 'clock',
+      });
+    }
+
+    if (!context) {
+      context = Context.defaultContext();
+    }
+
+    if (!context.isValid()) {
+      throw new Error('Context is not initialized or has been shut down');
+    }
+
+    if (until.clockType !== this._clockType) {
+      throw new TypeError(
+        "until's clock type does not match this clock's type"
+      );
+    }
+
+    const event = new ClockEvent();
+    let timeSourceChanged = false;
+
+    // Callback to wake when time jumps and is past target time
+    const callbackObject = {
+      _pre_callback: () => {
+        // Optional pre-callback - no action needed
+      },
+      _post_callback: (jumpInfo) => {
+        // ROS time being activated or deactivated changes the epoch,
+        // so sleep time loses its meaning
+        timeSourceChanged =
+          timeSourceChanged ||
+          jumpInfo.clock_change === ClockChange.ROS_TIME_ACTIVATED ||
+          jumpInfo.clock_change === ClockChange.ROS_TIME_DEACTIVATED;
+
+        if (timeSourceChanged || this.now().nanoseconds >= until.nanoseconds) {
+          event.set();
+        }
+      },
+    };
+
+    // Setup jump callback with minimal forward threshold
+    this.addClockCallback(
+      callbackObject,
+      true, // onClockChange
+      1n, // minForward (1 nanosecond - any forward jump triggers)
+      0n // minBackward (0 disables backward threshold)
+    );
+
+    try {
+      // Wait based on clock type
+      if (this._clockType === ClockType.SYSTEM_TIME) {
+        await event.waitUntilSystem(this, until.nanoseconds);
+      } else if (this._clockType === ClockType.STEADY_TIME) {
+        await event.waitUntilSteady(this, until.nanoseconds);
+      } else if (this._clockType === ClockType.ROS_TIME) {
+        await event.waitUntilRos(this, until.nanoseconds);
+      }
+    } finally {
+      // Always clean up callback
+      this.removeClockCallback(callbackObject);
+    }
+
+    if (!context.isValid() || timeSourceChanged) {
+      return false;
+    }
+
+    return this.now().nanoseconds >= until.nanoseconds;
+  }
+
+  /**
+   * Sleep for a specified duration.
+   *
+   * Equivalent to: clock.sleepUntil(clock.now() + duration, context)
+   *
+   * When using a ROSClock, this may sleep forever if the TimeSource is misconfigured
+   * and the context is never shut down. ROS time being activated or deactivated causes
+   * this function to cease sleeping and return false.
+   *
+   * @param {Duration} duration - Duration of time to sleep for.
+   * @param {Context} [context=null] - Context which when shut down will cause this sleep to wake early.
+   *   If context is null, then the default context is used.
+   * @return {Promise<boolean>} Promise that resolves to true if the full duration was slept,
+   *   or false if it woke for another reason.
+   * @throws {Error} if context has not been initialized or is shutdown.
+   */
+  async sleepFor(duration, context = null) {
+    const until = this.now().add(duration);
+    return this.sleepUntil(until, context);
+  }
 }
 
 /**

package/lib/clock_change.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2025 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';
+
+/**
+ * Enum for ClockChange
+ * Represents the type of clock change that occurred during a time jump.
+ * @readonly
+ * @enum {number}
+ */
+const ClockChange = {
+  /**
+   * The source before and after the jump is ROS_TIME.
+   * @member {number}
+   */
+  ROS_TIME_NO_CHANGE: 1,
+
+  /**
+   * The source switched to ROS_TIME from SYSTEM_TIME.
+   * @member {number}
+   */
+  ROS_TIME_ACTIVATED: 2,
+
+  /**
+   * The source switched to SYSTEM_TIME from ROS_TIME.
+   * @member {number}
+   */
+  ROS_TIME_DEACTIVATED: 3,
+
+  /**
+   * The source before and after the jump is SYSTEM_TIME.
+   * @member {number}
+   */
+  SYSTEM_TIME_NO_CHANGE: 4,
+};
+
+module.exports = ClockChange;

package/lib/clock_event.js

@@ -0,0 +1,88 @@
+// Copyright (c) 2025, 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 rclnodejs = require('./native_loader.js');
+
+/**
+ * @class - Class representing a ClockEvent in ROS
+ */
+class ClockEvent {
+  constructor() {
+    this._handle = rclnodejs.createClockEvent();
+  }
+
+  /**
+   * Wait until a time specified by a steady clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilSteady(clock, until) {
+    return rclnodejs.clockEventWaitUntilSteady(
+      this._handle,
+      clock.handle,
+      until
+    );
+  }
+
+  /**
+   * Wait until a time specified by a system clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilSystem(clock, until) {
+    return rclnodejs.clockEventWaitUntilSystem(
+      this._handle,
+      clock.handle,
+      until
+    );
+  }
+
+  /**
+   * Wait until a time specified by a ROS clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilRos(clock, until) {
+    return rclnodejs.clockEventWaitUntilRos(this._handle, clock.handle, until);
+  }
+
+  /**
+   * Indicate if the ClockEvent is set.
+   * @return {boolean} - True if the ClockEvent is set.
+   */
+  isSet() {
+    return rclnodejs.clockEventIsSet(this._handle);
+  }
+
+  /**
+   * Set the event.
+   */
+  set() {
+    rclnodejs.clockEventSet(this._handle);
+  }
+
+  /**
+   * Clear the event.
+   */
+  clear() {
+    rclnodejs.clockEventClear(this._handle);
+  }
+}
+
+module.exports = ClockEvent;