rclnodejs 1.5.2 → 1.7.0

package/lib/node.js

@@ -31,7 +31,15 @@ const {
   Parameter,
   ParameterDescriptor,
 } = require('./parameter.js');
+const { isValidSerializationMode } = require('./message_serialization.js');
+const {
+  TypeValidationError,
+  RangeValidationError,
+  ValidationError,
+} = require('./errors.js');
 const ParameterService = require('./parameter_service.js');
+const ParameterClient = require('./parameter_client.js');
+const ParameterWatcher = require('./parameter_watcher.js');
 const Publisher = require('./publisher.js');
 const QoS = require('./qos.js');
 const Rates = require('./rate.js');
@@ -73,8 +81,11 @@ class Node extends rclnodejs.ShadowNode {
   ) {
     super();
 
-    if (typeof nodeName !== 'string' || typeof namespace !== 'string') {
-      throw new TypeError('Invalid argument.');
+    if (typeof nodeName !== 'string') {
+      throw new TypeValidationError('nodeName', nodeName, 'string');
+    }
+    if (typeof namespace !== 'string') {
+      throw new TypeValidationError('namespace', namespace, 'string');
     }
 
     this._init(nodeName, namespace, options, context, args, useGlobalArguments);
@@ -110,6 +121,8 @@ class Node extends rclnodejs.ShadowNode {
     this._events = [];
     this._actionClients = [];
     this._actionServers = [];
+    this._parameterClients = [];
+    this._parameterWatchers = [];
     this._rateTimerServer = null;
     this._parameterDescriptors = new Map();
     this._parameters = new Map();
@@ -132,8 +145,13 @@ class Node extends rclnodejs.ShadowNode {
     if (options.parameterOverrides.length > 0) {
       for (const parameter of options.parameterOverrides) {
         if ((!parameter) instanceof Parameter) {
-          throw new TypeError(
-            'Parameter-override must be an instance of Parameter.'
+          throw new TypeValidationError(
+            'parameterOverride',
+            parameter,
+            'Parameter instance',
+            {
+              nodeName: name,
+            }
           );
         }
         this._parameterOverrides.set(parameter.name, parameter);
@@ -513,7 +531,9 @@ class Node extends rclnodejs.ShadowNode {
       options !== undefined &&
       (options === null || typeof options !== 'object')
     ) {
-      throw new TypeError('Invalid argument of options');
+      throw new TypeValidationError('options', options, 'object', {
+        nodeName: this.name(),
+      });
     }
 
     if (options === undefined) {
@@ -532,6 +552,21 @@ class Node extends rclnodejs.ShadowNode {
       options = Object.assign(options, { isRaw: false });
     }
 
+    if (options.serializationMode === undefined) {
+      options = Object.assign(options, { serializationMode: 'default' });
+    } else if (!isValidSerializationMode(options.serializationMode)) {
+      throw new ValidationError(
+        `Invalid serializationMode: ${options.serializationMode}. Valid modes are: 'default', 'plain', 'json'`,
+        {
+          code: 'INVALID_SERIALIZATION_MODE',
+          argumentName: 'serializationMode',
+          providedValue: options.serializationMode,
+          expectedType: "'default' | 'plain' | 'json'",
+          nodeName: this.name(),
+        }
+      );
+    }
+
     return options;
   }
 
@@ -549,8 +584,15 @@ class Node extends rclnodejs.ShadowNode {
       clock = arguments[3];
     }
 
-    if (typeof period !== 'bigint' || typeof callback !== 'function') {
-      throw new TypeError('Invalid argument');
+    if (typeof period !== 'bigint') {
+      throw new TypeValidationError('period', period, 'bigint', {
+        nodeName: this.name(),
+      });
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeValidationError('callback', callback, 'function', {
+        nodeName: this.name(),
+      });
     }
 
     const timerClock = clock || this._clock;
@@ -575,13 +617,20 @@ class Node extends rclnodejs.ShadowNode {
    */
   async createRate(hz = 1) {
     if (typeof hz !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('hz', hz, 'number', {
+        nodeName: this.name(),
+      });
     }
 
     const MAX_RATE_HZ_IN_MILLISECOND = 1000.0;
     if (hz <= 0.0 || hz > MAX_RATE_HZ_IN_MILLISECOND) {
-      throw new RangeError(
-        `Hz must be between 0.0 and ${MAX_RATE_HZ_IN_MILLISECOND}`
+      throw new RangeValidationError(
+        'hz',
+        hz,
+        `0.0 < hz <= ${MAX_RATE_HZ_IN_MILLISECOND}`,
+        {
+          nodeName: this.name(),
+        }
       );
     }
 
@@ -626,12 +675,32 @@ class Node extends rclnodejs.ShadowNode {
     }
     options = this._validateOptions(options);
 
+    if (typeof typeClass !== 'function') {
+      throw new TypeValidationError('typeClass', typeClass, 'function', {
+        nodeName: this.name(),
+        entityType: 'publisher',
+      });
+    }
+    if (typeof topic !== 'string') {
+      throw new TypeValidationError('topic', topic, 'string', {
+        nodeName: this.name(),
+        entityType: 'publisher',
+      });
+    }
     if (
-      typeof typeClass !== 'function' ||
-      typeof topic !== 'string' ||
-      (eventCallbacks && !(eventCallbacks instanceof PublisherEventCallbacks))
+      eventCallbacks &&
+      !(eventCallbacks instanceof PublisherEventCallbacks)
     ) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'eventCallbacks',
+        eventCallbacks,
+        'PublisherEventCallbacks',
+        {
+          nodeName: this.name(),
+          entityType: 'publisher',
+          entityName: topic,
+        }
+      );
     }
 
     let publisher = publisherClass.createPublisher(
@@ -666,6 +735,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {boolean} options.enableTypedArray - The topic will use TypedArray if necessary, default: true.
    * @param {QoS} options.qos - ROS Middleware "quality of service" settings for the subscription, default: QoS.profileDefault.
    * @param {boolean} options.isRaw - The topic is serialized when true, default: false.
+   * @param {string} [options.serializationMode='default'] - Controls message serialization format:
+   *  'default': Use native rclnodejs behavior (respects enableTypedArray setting),
+   *  'plain': Convert TypedArrays to regular arrays,
+   *  'json': Fully JSON-safe (handles TypedArrays, BigInt, etc.).
    * @param {object} [options.contentFilter=undefined] - The content-filter, default: undefined.
    *  Confirm that your RMW supports content-filtered topics before use. 
    * @param {string} options.contentFilter.expression - Specifies the criteria to select the data samples of
@@ -691,14 +764,39 @@ class Node extends rclnodejs.ShadowNode {
     }
     options = this._validateOptions(options);
 
+    if (typeof typeClass !== 'function') {
+      throw new TypeValidationError('typeClass', typeClass, 'function', {
+        nodeName: this.name(),
+        entityType: 'subscription',
+      });
+    }
+    if (typeof topic !== 'string') {
+      throw new TypeValidationError('topic', topic, 'string', {
+        nodeName: this.name(),
+        entityType: 'subscription',
+      });
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeValidationError('callback', callback, 'function', {
+        nodeName: this.name(),
+        entityType: 'subscription',
+        entityName: topic,
+      });
+    }
     if (
-      typeof typeClass !== 'function' ||
-      typeof topic !== 'string' ||
-      typeof callback !== 'function' ||
-      (eventCallbacks &&
-        !(eventCallbacks instanceof SubscriptionEventCallbacks))
+      eventCallbacks &&
+      !(eventCallbacks instanceof SubscriptionEventCallbacks)
     ) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'eventCallbacks',
+        eventCallbacks,
+        'SubscriptionEventCallbacks',
+        {
+          nodeName: this.name(),
+          entityType: 'subscription',
+          entityName: topic,
+        }
+      );
     }
 
     let subscription = Subscription.createSubscription(
@@ -733,8 +831,17 @@ class Node extends rclnodejs.ShadowNode {
     }
     options = this._validateOptions(options);
 
-    if (typeof typeClass !== 'function' || typeof serviceName !== 'string') {
-      throw new TypeError('Invalid argument');
+    if (typeof typeClass !== 'function') {
+      throw new TypeValidationError('typeClass', typeClass, 'function', {
+        nodeName: this.name(),
+        entityType: 'client',
+      });
+    }
+    if (typeof serviceName !== 'string') {
+      throw new TypeValidationError('serviceName', serviceName, 'string', {
+        nodeName: this.name(),
+        entityType: 'client',
+      });
     }
 
     let client = Client.createClient(
@@ -788,12 +895,24 @@ class Node extends rclnodejs.ShadowNode {
     }
     options = this._validateOptions(options);
 
-    if (
-      typeof typeClass !== 'function' ||
-      typeof serviceName !== 'string' ||
-      typeof callback !== 'function'
-    ) {
-      throw new TypeError('Invalid argument');
+    if (typeof typeClass !== 'function') {
+      throw new TypeValidationError('typeClass', typeClass, 'function', {
+        nodeName: this.name(),
+        entityType: 'service',
+      });
+    }
+    if (typeof serviceName !== 'string') {
+      throw new TypeValidationError('serviceName', serviceName, 'string', {
+        nodeName: this.name(),
+        entityType: 'service',
+      });
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeValidationError('callback', callback, 'function', {
+        nodeName: this.name(),
+        entityType: 'service',
+        entityName: serviceName,
+      });
     }
 
     let service = Service.createService(
@@ -810,6 +929,52 @@ class Node extends rclnodejs.ShadowNode {
     return service;
   }
 
+  /**
+   * Create a ParameterClient for accessing parameters on a remote node.
+   * @param {string} remoteNodeName - The name of the remote node whose parameters to access.
+   * @param {object} [options] - Options for parameter client.
+   * @param {number} [options.timeout=5000] - Default timeout in milliseconds for service calls.
+   * @return {ParameterClient} - An instance of ParameterClient.
+   */
+  createParameterClient(remoteNodeName, options = {}) {
+    if (typeof remoteNodeName !== 'string' || remoteNodeName.trim() === '') {
+      throw new TypeError('Remote node name must be a non-empty string');
+    }
+
+    const parameterClient = new ParameterClient(this, remoteNodeName, options);
+    debug(
+      'Finish creating parameter client for remote node = %s.',
+      remoteNodeName
+    );
+    this._parameterClients.push(parameterClient);
+
+    return parameterClient;
+  }
+
+  /**
+   * Create a ParameterWatcher for watching parameter changes on a remote node.
+   * @param {string} remoteNodeName - The name of the remote node whose parameters to watch.
+   * @param {string[]} parameterNames - Array of parameter names to watch.
+   * @param {object} [options] - Options for parameter watcher.
+   * @param {number} [options.timeout=5000] - Default timeout in milliseconds for service calls.
+   * @return {ParameterWatcher} - An instance of ParameterWatcher.
+   */
+  createParameterWatcher(remoteNodeName, parameterNames, options = {}) {
+    const watcher = new ParameterWatcher(
+      this,
+      remoteNodeName,
+      parameterNames,
+      options
+    );
+    debug(
+      'Finish creating parameter watcher for remote node = %s.',
+      remoteNodeName
+    );
+    this._parameterWatchers.push(watcher);
+
+    return watcher;
+  }
+
   /**
    * Create a guard condition.
    * @param {Function} callback - The callback to be called when the guard condition is triggered.
@@ -817,7 +982,10 @@ class Node extends rclnodejs.ShadowNode {
    */
   createGuardCondition(callback) {
     if (typeof callback !== 'function') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('callback', callback, 'function', {
+        nodeName: this.name(),
+        entityType: 'guard_condition',
+      });
     }
 
     let guard = GuardCondition.createGuardCondition(callback, this.context);
@@ -843,6 +1011,9 @@ class Node extends rclnodejs.ShadowNode {
     this._actionClients.forEach((actionClient) => actionClient.destroy());
     this._actionServers.forEach((actionServer) => actionServer.destroy());
 
+    this._parameterClients.forEach((paramClient) => paramClient.destroy());
+    this._parameterWatchers.forEach((watcher) => watcher.destroy());
+
     this.context.onNodeDestroyed(this);
 
     this.handle.release();
@@ -855,6 +1026,8 @@ class Node extends rclnodejs.ShadowNode {
     this._guards = [];
     this._actionClients = [];
     this._actionServers = [];
+    this._parameterClients = [];
+    this._parameterWatchers = [];
 
     if (this._rateTimerServer) {
       this._rateTimerServer.shutdown();
@@ -869,7 +1042,14 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroyPublisher(publisher) {
     if (!(publisher instanceof Publisher)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'publisher',
+        publisher,
+        'Publisher instance',
+        {
+          nodeName: this.name(),
+        }
+      );
     }
     if (publisher.events) {
       publisher.events.forEach((event) => {
@@ -887,7 +1067,14 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroySubscription(subscription) {
     if (!(subscription instanceof Subscription)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError(
+        'subscription',
+        subscription,
+        'Subscription instance',
+        {
+          nodeName: this.name(),
+        }
+      );
     }
     if (subscription.events) {
       subscription.events.forEach((event) => {
@@ -906,7 +1093,9 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroyClient(client) {
     if (!(client instanceof Client)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('client', client, 'Client instance', {
+        nodeName: this.name(),
+      });
     }
     this._destroyEntity(client, this._clients);
   }
@@ -918,11 +1107,39 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroyService(service) {
     if (!(service instanceof Service)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('service', service, 'Service instance', {
+        nodeName: this.name(),
+      });
     }
     this._destroyEntity(service, this._services);
   }
 
+  /**
+   * Destroy a ParameterClient.
+   * @param {ParameterClient} parameterClient - The ParameterClient to be destroyed.
+   * @return {undefined}
+   */
+  destroyParameterClient(parameterClient) {
+    if (!(parameterClient instanceof ParameterClient)) {
+      throw new TypeError('Invalid argument');
+    }
+    this._removeEntityFromArray(parameterClient, this._parameterClients);
+    parameterClient.destroy();
+  }
+
+  /**
+   * Destroy a ParameterWatcher.
+   * @param {ParameterWatcher} watcher - The ParameterWatcher to be destroyed.
+   * @return {undefined}
+   */
+  destroyParameterWatcher(watcher) {
+    if (!(watcher instanceof ParameterWatcher)) {
+      throw new TypeError('Invalid argument');
+    }
+    this._removeEntityFromArray(watcher, this._parameterWatchers);
+    watcher.destroy();
+  }
+
   /**
    * Destroy a Timer.
    * @param {Timer} timer - The Timer to be destroyed.
@@ -930,7 +1147,9 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroyTimer(timer) {
     if (!(timer instanceof Timer)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('timer', timer, 'Timer instance', {
+        nodeName: this.name(),
+      });
     }
     this._destroyEntity(timer, this._timers);
   }
@@ -942,7 +1161,9 @@ class Node extends rclnodejs.ShadowNode {
    */
   destroyGuardCondition(guard) {
     if (!(guard instanceof GuardCondition)) {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('guard', guard, 'GuardCondition instance', {
+        nodeName: this.name(),
+      });
     }
     this._destroyEntity(guard, this._guards);
   }
@@ -989,7 +1210,7 @@ class Node extends rclnodejs.ShadowNode {
 
   /**
    * Get the current time using the node's clock.
-   * @returns {Time} - The current time.
+   * @returns {Timer} - The current time.
    */
   now() {
     return this.getClock().now();
@@ -1234,14 +1455,14 @@ class Node extends rclnodejs.ShadowNode {
    *
    * @param {Parameter} parameter - Parameter to declare.
    * @param {ParameterDescriptor} [descriptor] - Optional descriptor for parameter.
-   * @param {boolean} [ignoreOveride] - When true disregard any parameter-override that may be present.
+   * @param {boolean} [ignoreOverride] - When true disregard any parameter-override that may be present.
    * @return {Parameter} - The newly declared parameter.
    */
-  declareParameter(parameter, descriptor, ignoreOveride = false) {
+  declareParameter(parameter, descriptor, ignoreOverride = false) {
     const parameters = this.declareParameters(
       [parameter],
       descriptor ? [descriptor] : [],
-      ignoreOveride
+      ignoreOverride
     );
     return parameters.length == 1 ? parameters[0] : null;
   }
@@ -1282,16 +1503,25 @@ class Node extends rclnodejs.ShadowNode {
    */
   declareParameters(parameters, descriptors = [], ignoreOverrides = false) {
     if (!Array.isArray(parameters)) {
-      throw new TypeError('Invalid parameter: expected array of Parameter');
+      throw new TypeValidationError('parameters', parameters, 'Array', {
+        nodeName: this.name(),
+      });
     }
     if (!Array.isArray(descriptors)) {
-      throw new TypeError(
-        'Invalid parameters: expected array of ParameterDescriptor'
-      );
+      throw new TypeValidationError('descriptors', descriptors, 'Array', {
+        nodeName: this.name(),
+      });
     }
     if (descriptors.length > 0 && parameters.length !== descriptors.length) {
-      throw new TypeError(
-        'Each parameter must have a cooresponding ParameterDescriptor'
+      throw new ValidationError(
+        'Each parameter must have a corresponding ParameterDescriptor',
+        {
+          code: 'PARAMETER_DESCRIPTOR_MISMATCH',
+          argumentName: 'descriptors',
+          providedValue: descriptors.length,
+          expectedType: `Array with length ${parameters.length}`,
+          nodeName: this.name(),
+        }
       );
     }
 
@@ -1731,7 +1961,9 @@ class Node extends rclnodejs.ShadowNode {
    */
   resolveTopicName(topicName, onlyExpand = false) {
     if (typeof topicName !== 'string') {
-      throw new TypeError('Invalid argument: expected string');
+      throw new TypeValidationError('topicName', topicName, 'string', {
+        nodeName: this.name(),
+      });
     }
     return rclnodejs.resolveName(
       this.handle,
@@ -1749,7 +1981,9 @@ class Node extends rclnodejs.ShadowNode {
    */
   resolveServiceName(service, onlyExpand = false) {
     if (typeof service !== 'string') {
-      throw new TypeError('Invalid argument: expected string');
+      throw new TypeValidationError('service', service, 'string', {
+        nodeName: this.name(),
+      });
     }
     return rclnodejs.resolveName(
       this.handle,
@@ -1920,6 +2154,7 @@ class Node extends rclnodejs.ShadowNode {
  *   isRaw: false,
  *   qos: QoS.profileDefault,
  *   contentFilter: undefined,
+ *   serializationMode: 'default',
  * }
  */
 Node.getDefaultOptions = function () {
@@ -1928,6 +2163,7 @@ Node.getDefaultOptions = function () {
     isRaw: false,
     qos: QoS.profileDefault,
     contentFilter: undefined,
+    serializationMode: 'default',
   };
 };