rclnodejs 1.6.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');
@@ -58,7 +60,21 @@ const {
   serializeMessage,
   deserializeMessage,
 } = require('./lib/serialization.js');
+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.
@@ -175,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,
 
@@ -217,6 +239,15 @@ let rcl = {
   /** {@link ParameterType} */
   ParameterType: ParameterType,
 
+  /** {@link ParameterClient} class */
+  ParameterClient: ParameterClient,
+
+  /** {@link ParameterWatcher} class */
+  ParameterWatcher: ParameterWatcher,
+
+  /** {@link ObservableSubscription} class */
+  ObservableSubscription: ObservableSubscription,
+
   /** {@link QoS} class */
   QoS: QoS,
 
@@ -377,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.
@@ -556,6 +602,109 @@ let rcl = {
    * @returns {string} The JSON string representation
    */
   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,
+
+  /** {@link ValidationError} - Error thrown when validation fails */
+  ValidationError: errors.ValidationError,
+  /** {@link TypeValidationError} - Type validation error */
+  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,
+
+  /** {@link OperationError} - Base class for operation/runtime errors */
+  OperationError: errors.OperationError,
+  /** {@link TimeoutError} - Request timeout error */
+  TimeoutError: errors.TimeoutError,
+  /** {@link AbortError} - Request abortion error */
+  AbortError: errors.AbortError,
+  /** {@link ServiceNotFoundError} - Service not available error */
+  ServiceNotFoundError: errors.ServiceNotFoundError,
+  /** {@link NodeNotFoundError} - Remote node not found error */
+  NodeNotFoundError: errors.NodeNotFoundError,
+
+  /** {@link ParameterError} - Base error for parameter operations */
+  ParameterError: errors.ParameterError,
+  /** {@link ParameterNotFoundError} - Parameter not found error */
+  ParameterNotFoundError: errors.ParameterNotFoundError,
+  /** {@link ParameterTypeError} - Parameter type mismatch error */
+  ParameterTypeError: errors.ParameterTypeError,
+  /** {@link ReadOnlyParameterError} - Read-only parameter modification error */
+  ReadOnlyParameterError: errors.ReadOnlyParameterError,
+
+  /** {@link TopicError} - Base error for topic operations */
+  TopicError: errors.TopicError,
+  /** {@link PublisherError} - Publisher-specific error */
+  PublisherError: errors.PublisherError,
+  /** {@link SubscriptionError} - Subscription-specific error */
+  SubscriptionError: errors.SubscriptionError,
+
+  /** {@link ActionError} - Base error for action operations */
+  ActionError: errors.ActionError,
+  /** {@link GoalRejectedError} - Goal rejected by action server */
+  GoalRejectedError: errors.GoalRejectedError,
+  /** {@link ActionServerNotFoundError} - Action server not found */
+  ActionServerNotFoundError: errors.ActionServerNotFoundError,
+
+  /** {@link NativeError} - Wraps errors from native C++ layer */
+  NativeError: errors.NativeError,
 };
 
 const _sigHandler = () => {
@@ -585,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

@@ -23,6 +23,12 @@ const DistroUtils = require('../distro.js');
 const Entity = require('../entity.js');
 const loader = require('../interface_loader.js');
 const QoS = require('../qos.js');
+const {
+  TypeValidationError,
+  ActionError,
+  OperationError,
+} = require('../errors.js');
+const { assertValidMessage } = require('../message_validation.js');
 
 /**
  * @class - ROS Action client.
@@ -75,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(
@@ -103,7 +115,14 @@ class ActionClient extends Entity {
       if (goalHandle.accepted) {
         let uuid = ActionUuid.fromMessage(goalHandle.goalId).toString();
         if (this._goalHandles.has(uuid)) {
-          throw new Error(`Two goals were accepted with the same ID (${uuid})`);
+          throw new ActionError(
+            `Two goals were accepted with the same ID (${uuid})`,
+            this._actionName,
+            {
+              code: 'DUPLICATE_GOAL_ID',
+              details: { goalId: uuid },
+            }
+          );
         }
 
         this._goalHandles.set(uuid, goalHandle);
@@ -188,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.
    *
@@ -197,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;
@@ -210,8 +275,14 @@ class ActionClient extends Entity {
     );
 
     if (this._pendingGoalRequests.has(sequenceNumber)) {
-      throw new Error(
-        `Sequence (${sequenceNumber}) conflicts with pending goal request`
+      throw new OperationError(
+        `Sequence (${sequenceNumber}) conflicts with pending goal request`,
+        {
+          code: 'SEQUENCE_CONFLICT',
+          entityType: 'action client',
+          entityName: this._actionName,
+          details: { sequenceNumber: sequenceNumber, requestType: 'goal' },
+        }
       );
     }
 
@@ -274,7 +345,15 @@ class ActionClient extends Entity {
    */
   _cancelGoal(goalHandle) {
     if (!(goalHandle instanceof ClientGoalHandle)) {
-      throw new TypeError('Invalid argument, must be type of ClientGoalHandle');
+      throw new TypeValidationError(
+        'goalHandle',
+        goalHandle,
+        'ClientGoalHandle',
+        {
+          entityType: 'action client',
+          entityName: this._actionName,
+        }
+      );
     }
 
     let request = new ActionInterfaces.CancelGoal.Request();
@@ -290,8 +369,14 @@ class ActionClient extends Entity {
       request.serialize()
     );
     if (this._pendingCancelRequests.has(sequenceNumber)) {
-      throw new Error(
-        `Sequence (${sequenceNumber}) conflicts with pending cancel request`
+      throw new OperationError(
+        `Sequence (${sequenceNumber}) conflicts with pending cancel request`,
+        {
+          code: 'SEQUENCE_CONFLICT',
+          entityType: 'action client',
+          entityName: this._actionName,
+          details: { sequenceNumber: sequenceNumber, requestType: 'cancel' },
+        }
       );
     }
 
@@ -316,7 +401,15 @@ class ActionClient extends Entity {
    */
   _getResult(goalHandle) {
     if (!(goalHandle instanceof ClientGoalHandle)) {
-      throw new TypeError('Invalid argument, must be type of ClientGoalHandle');
+      throw new TypeValidationError(
+        'goalHandle',
+        goalHandle,
+        'ClientGoalHandle',
+        {
+          entityType: 'action client',
+          entityName: this._actionName,
+        }
+      );
     }
 
     let request = new this.typeClass.impl.GetResultService.Request();
@@ -327,8 +420,14 @@ class ActionClient extends Entity {
       request.serialize()
     );
     if (this._pendingResultRequests.has(sequenceNumber)) {
-      throw new Error(
-        `Sequence (${sequenceNumber}) conflicts with pending result request`
+      throw new OperationError(
+        `Sequence (${sequenceNumber}) conflicts with pending result request`,
+        {
+          code: 'SEQUENCE_CONFLICT',
+          entityType: 'action client',
+          entityName: this._actionName,
+          details: { sequenceNumber: sequenceNumber, requestType: 'result' },
+        }
       );
     }
 

package/lib/action/deferred.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const { TypeValidationError } = require('../errors.js');
+
 /**
  * @class - Wraps a promise allowing it to be resolved elsewhere.
  * @ignore
@@ -42,7 +44,9 @@ class Deferred {
    */
   beforeSetResultCallback(callback) {
     if (typeof callback !== 'function') {
-      throw new TypeError('Invalid parameter');
+      throw new TypeValidationError('callback', callback, 'function', {
+        entityType: 'deferred promise',
+      });
     }
 
     this._beforeSetResultCallback = callback;
@@ -70,7 +74,9 @@ class Deferred {
    */
   setDoneCallback(callback) {
     if (typeof callback !== 'function') {
-      throw new TypeError('Invalid parameter');
+      throw new TypeValidationError('callback', callback, 'function', {
+        entityType: 'deferred promise',
+      });
     }
 
     this._promise.finally(() => callback(this._result));

package/lib/action/server.js

@@ -23,6 +23,7 @@ const { CancelResponse, GoalEvent, GoalResponse } = require('./response.js');
 const loader = require('../interface_loader.js');
 const QoS = require('../qos.js');
 const ServerGoalHandle = require('./server_goal_handle.js');
+const { TypeValidationError } = require('../errors.js');
 
 /**
  * Execute the goal.
@@ -219,7 +220,15 @@ class ActionServer extends Entity {
    */
   registerExecuteCallback(executeCallback) {
     if (typeof executeCallback !== 'function') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'executeCallback',
+        executeCallback,
+        'function',
+        {
+          entityType: 'action server',
+          entityName: this._actionName,
+        }
+      );
     }
 
     this._callback = executeCallback;

package/lib/action/uuid.js

@@ -16,6 +16,7 @@
 
 const ActionInterfaces = require('./interfaces.js');
 const { randomUUID } = require('crypto');
+const { TypeValidationError } = require('../errors.js');
 
 /**
  * @class - Represents a unique identifier used by actions.
@@ -31,7 +32,9 @@ class ActionUuid {
   constructor(bytes) {
     if (bytes) {
       if (!(bytes instanceof Uint8Array)) {
-        throw new Error('Invalid parameter');
+        throw new TypeValidationError('bytes', bytes, 'Uint8Array', {
+          entityType: 'action uuid',
+        });
       }
 
       this._bytes = bytes;