rclnodejs 1.6.0 → 1.7.0

package/index.js

@@ -58,6 +58,9 @@ 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 { spawn } = require('child_process');
 
 /**
@@ -217,6 +220,12 @@ let rcl = {
   /** {@link ParameterType} */
   ParameterType: ParameterType,
 
+  /** {@link ParameterClient} class */
+  ParameterClient: ParameterClient,
+
+  /** {@link ParameterWatcher} class */
+  ParameterWatcher: ParameterWatcher,
+
   /** {@link QoS} class */
   QoS: QoS,
 
@@ -556,6 +565,56 @@ let rcl = {
    * @returns {string} The JSON string representation
    */
   toJSONString: toJSONString,
+
+  // 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 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 = () => {

package/lib/action/client.js

@@ -23,6 +23,11 @@ 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');
 
 /**
  * @class - ROS Action client.
@@ -103,7 +108,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);
@@ -210,8 +222,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 +292,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 +316,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 +348,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 +367,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;

package/lib/client.js

@@ -17,8 +17,58 @@
 const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
+const {
+  TypeValidationError,
+  TimeoutError,
+  AbortError,
+} = require('./errors.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
@@ -33,7 +83,7 @@ class Client extends Entity {
   }
 
   /**
-   * This callback is called when a resopnse is sent back from service
+   * This callback is called when a response is sent back from service
    * @callback ResponseCallback
    * @param {Object} response - The response sent from the service
    * @see [Client.sendRequest]{@link Client#sendRequest}
@@ -43,7 +93,7 @@ class Client extends Entity {
    */
 
   /**
-   * Send the request and will be notified asynchronously if receiving the repsonse.
+   * 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.
    * @return {undefined}
@@ -51,7 +101,10 @@ class Client extends Entity {
    */
   sendRequest(request, callback) {
     if (typeof callback !== 'function') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('callback', callback, 'function', {
+        entityType: 'service',
+        entityName: this._serviceName,
+      });
     }
 
     let requestToSend =
@@ -65,6 +118,102 @@ class Client extends Entity {
     this._sequenceNumberToCallbackMap.set(sequenceNumber, callback);
   }
 
+  /**
+   * Send the request and return a Promise that resolves with the response.
+   * @param {object} request - The request to be submitted.
+   * @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.
+   * @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 {Error} If the request fails for other reasons.
+   */
+  sendRequestAsync(request, options = {}) {
+    return new Promise((resolve, reject) => {
+      let sequenceNumber = null;
+      let isResolved = false;
+      let isTimeout = false;
+
+      const cleanup = () => {
+        if (sequenceNumber !== null) {
+          this._sequenceNumberToCallbackMap.delete(sequenceNumber);
+        }
+        isResolved = true;
+      };
+
+      let effectiveSignal = options.signal;
+
+      if (options.timeout !== undefined && options.timeout >= 0) {
+        const timeoutSignal = AbortSignal.timeout(options.timeout);
+
+        timeoutSignal.addEventListener('abort', () => {
+          isTimeout = true;
+        });
+
+        if (options.signal) {
+          effectiveSignal = AbortSignal.any([options.signal, timeoutSignal]);
+        } else {
+          effectiveSignal = timeoutSignal;
+        }
+      }
+
+      if (effectiveSignal) {
+        if (effectiveSignal.aborted) {
+          const error = isTimeout
+            ? new TimeoutError('Service request', options.timeout, {
+                entityType: 'service',
+                entityName: this._serviceName,
+              })
+            : new AbortError('Service request', undefined, {
+                entityType: 'service',
+                entityName: this._serviceName,
+              });
+          reject(error);
+          return;
+        }
+
+        effectiveSignal.addEventListener('abort', () => {
+          if (!isResolved) {
+            cleanup();
+            const error = isTimeout
+              ? new TimeoutError('Service request', options.timeout, {
+                  entityType: 'service',
+                  entityName: this._serviceName,
+                })
+              : new AbortError('Service request', undefined, {
+                  entityType: 'service',
+                  entityName: this._serviceName,
+                });
+            reject(error);
+          }
+        });
+      }
+
+      try {
+        let requestToSend =
+          request instanceof this._typeClass.Request
+            ? request
+            : new this._typeClass.Request(request);
+
+        let rawRequest = requestToSend.serialize();
+        sequenceNumber = rclnodejs.sendRequest(this._handle, rawRequest);
+
+        debug(`Client has sent a ${this._serviceName} request (async).`);
+
+        this._sequenceNumberToCallbackMap.set(sequenceNumber, (response) => {
+          if (!isResolved) {
+            cleanup();
+            resolve(response);
+          }
+        });
+      } catch (error) {
+        cleanup();
+        reject(error);
+      }
+    });
+  }
+
   processResponse(sequenceNumber, response) {
     if (this._sequenceNumberToCallbackMap.has(sequenceNumber)) {
       debug(`Client has received ${this._serviceName} response from service.`);

package/lib/clock.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
+const { TypeValidationError } = require('./errors.js');
 
 /**
  * @class - Class representing a Clock in ROS
@@ -102,7 +103,9 @@ class ROSClock extends Clock {
 
   set rosTimeOverride(time) {
     if (!(time instanceof Time)) {
-      throw new TypeError('Invalid argument, must be type of Time');
+      throw new TypeValidationError('time', time, 'Time', {
+        entityType: 'clock',
+      });
     }
     rclnodejs.setRosTimeOverride(this._handle, time._handle);
   }

package/lib/context.js

@@ -15,6 +15,7 @@
 'use strict';
 
 const rclnodejs = require('./native_loader.js');
+const { OperationError } = require('./errors.js');
 
 let defaultContext = null;
 
@@ -184,11 +185,20 @@ class Context {
 
   onNodeCreated(node) {
     if (!node) {
-      throw new Error('Node must be defined to add to Context');
+      throw new OperationError('Node must be defined to add to Context', {
+        code: 'NODE_UNDEFINED',
+        entityType: 'context',
+      });
     }
 
     if (this.isShutdown()) {
-      throw new Error('Can not add a Node to a Context that is shutdown');
+      throw new OperationError(
+        'Can not add a Node to a Context that is shutdown',
+        {
+          code: 'CONTEXT_SHUTDOWN',
+          entityType: 'context',
+        }
+      );
     }
 
     if (this._nodes.includes(node)) {

package/lib/duration.js

@@ -15,6 +15,7 @@
 'use strict';
 
 const rclnodejs = require('./native_loader.js');
+const { TypeValidationError, RangeValidationError } = require('./errors.js');
 const S_TO_NS = 10n ** 9n;
 
 /**
@@ -29,17 +30,31 @@ class Duration {
    */
   constructor(seconds = 0n, nanoseconds = 0n) {
     if (typeof seconds !== 'bigint') {
-      throw new TypeError('Invalid argument of seconds');
+      throw new TypeValidationError('seconds', seconds, 'bigint', {
+        entityType: 'duration',
+      });
     }
 
     if (typeof nanoseconds !== 'bigint') {
-      throw new TypeError('Invalid argument of nanoseconds');
+      throw new TypeValidationError('nanoseconds', nanoseconds, 'bigint', {
+        entityType: 'duration',
+      });
     }
 
     const total = seconds * S_TO_NS + nanoseconds;
     if (total >= 2n ** 63n) {
-      throw new RangeError(
-        'Total nanoseconds value is too large to store in C time point.'
+      throw new RangeValidationError(
+        'total nanoseconds',
+        total,
+        '< 2^63 (max C duration)',
+        {
+          entityType: 'duration',
+          details: {
+            seconds: seconds,
+            nanoseconds: nanoseconds,
+            total: total,
+          },
+        }
       );
     }
 
@@ -67,9 +82,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds === other.nanoseconds;
     }
-    throw new TypeError(
-      `Can't compare duration with object of type: ${other.constructor.name}`
-    );
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 
   /**
@@ -81,7 +96,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds !== other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 
   /**
@@ -93,7 +110,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds < other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 
   /**
@@ -105,7 +124,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds <= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 
   /**
@@ -117,7 +138,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds > other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 
   /**
@@ -129,7 +152,9 @@ class Duration {
     if (other instanceof Duration) {
       return this._nanoseconds >= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'duration',
+    });
   }
 }