rclnodejs 1.6.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/parameter.js

@@ -20,6 +20,12 @@
 'use strict';
 
 const { isClose } = require('./utils.js');
+const {
+  TypeValidationError,
+  RangeValidationError,
+  ParameterError,
+  ParameterTypeError,
+} = require('./errors.js');
 
 /**
  * The plus/minus tolerance for determining number equivalence.
@@ -184,17 +190,25 @@ class Parameter {
       typeof this.name !== 'string' ||
       this.name.trim().length === 0
     ) {
-      throw new TypeError('Invalid name');
+      throw new TypeValidationError('name', this.name, 'non-empty string', {
+        entityType: 'parameter',
+      });
     }
 
     // validate type
     if (!validType(this.type)) {
-      throw new TypeError('Invalid type');
+      throw new ParameterError('Invalid parameter type', this.name, {
+        details: { providedType: this.type },
+      });
     }
 
     // validate value
     if (!validValue(this.value, this.type)) {
-      throw new TypeError('Incompatible value.');
+      throw new ParameterTypeError(this.name, this.type, typeof this.value, {
+        details: {
+          providedValue: this.value,
+        },
+      });
     }
 
     this._dirty = false;
@@ -383,10 +397,23 @@ class ParameterDescriptor {
       return;
     }
     if (!(range instanceof Range)) {
-      throw TypeError('Expected instance of Range.');
+      throw new TypeValidationError('range', range, 'Range', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
     if (!range.isValidType(this.type)) {
-      throw TypeError('Incompatible Range');
+      throw new ParameterError(
+        'Incompatible Range for parameter type',
+        this.name,
+        {
+          entityType: 'parameter descriptor',
+          details: {
+            rangeType: range.constructor.name,
+            parameterType: this.type,
+          },
+        }
+      );
     }
 
     this._range = range;
@@ -405,22 +432,40 @@ class ParameterDescriptor {
       typeof this.name !== 'string' ||
       this.name.trim().length === 0
     ) {
-      throw new TypeError('Invalid name');
+      throw new TypeValidationError('name', this.name, 'non-empty string', {
+        entityType: 'parameter descriptor',
+      });
     }
 
     // validate type
     if (!validType(this.type)) {
-      throw new TypeError('Invalid type');
+      throw new ParameterError('Invalid parameter type', this.name, {
+        entityType: 'parameter descriptor',
+        details: { providedType: this.type },
+      });
     }
 
     // validate description
     if (this.description && typeof this.description !== 'string') {
-      throw new TypeError('Invalid description');
+      throw new TypeValidationError('description', this.description, 'string', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
 
     // validate rangeConstraint
     if (this.hasRange() && !this.range.isValidType(this.type)) {
-      throw new TypeError('Incompatible Range');
+      throw new ParameterError(
+        'Incompatible Range for parameter type',
+        this.name,
+        {
+          entityType: 'parameter descriptor',
+          details: {
+            rangeType: this.range.constructor.name,
+            parameterType: this.type,
+          },
+        }
+      );
     }
   }
 
@@ -433,27 +478,66 @@ class ParameterDescriptor {
    */
   validateParameter(parameter) {
     if (!parameter) {
-      throw new TypeError('Parameter is undefined');
+      throw new TypeValidationError('parameter', parameter, 'Parameter', {
+        entityType: 'parameter descriptor',
+        parameterName: this.name,
+      });
     }
 
     // ensure parameter is valid
     try {
       parameter.validate();
-    } catch {
-      throw new TypeError('Parameter is invalid');
+    } catch (err) {
+      throw new ParameterError('Parameter is invalid', parameter.name, {
+        cause: err,
+        details: { validationError: err.message },
+      });
     }
 
     // ensure this descriptor is valid
     try {
       this.validate();
-    } catch {
-      throw new Error('Descriptor is invalid.');
+    } catch (err) {
+      throw new ParameterError('Descriptor is invalid', this.name, {
+        entityType: 'parameter descriptor',
+        cause: err,
+        details: { validationError: err.message },
+      });
     }
 
-    if (this.name !== parameter.name) throw new Error('Name mismatch');
-    if (this.type !== parameter.type) throw new Error('Type mismatch');
+    if (this.name !== parameter.name) {
+      throw new ParameterError('Name mismatch', this.name, {
+        details: {
+          descriptorName: this.name,
+          parameterName: parameter.name,
+        },
+      });
+    }
+    if (this.type !== parameter.type) {
+      throw new ParameterTypeError(this.name, this.type, parameter.type, {
+        details: {
+          expectedType: this.type,
+          actualType: parameter.type,
+        },
+      });
+    }
     if (this.hasRange() && !this.range.inRange(parameter.value)) {
-      throw new RangeError('Parameter value is not in descriptor range');
+      throw new RangeValidationError(
+        'value',
+        parameter.value,
+        `${this.range.fromValue} to ${this.range.toValue}`,
+        {
+          entityType: 'parameter',
+          parameterName: parameter.name,
+          details: {
+            range: {
+              from: this.range.fromValue,
+              to: this.range.toValue,
+              step: this.range.step,
+            },
+          },
+        }
+      );
     }
   }
 
@@ -550,7 +634,9 @@ class Range {
         true
       );
     } else if (typeof value !== 'number' && typeof value !== 'bigint') {
-      throw new TypeError('Value must be a number or bigint');
+      throw new TypeValidationError('value', value, 'number or bigint', {
+        entityType: 'range',
+      });
     }
 
     return true;
@@ -693,30 +779,80 @@ class IntegerRange extends Range {
  * @param {any} value - The value to infer it's ParameterType
  * @returns {ParameterType} - The ParameterType that best scribes the value.
  */
-// eslint-disable-next-line no-unused-vars
 function parameterTypeFromValue(value) {
-  if (!value) return ParameterType.PARAMETER_NOT_SET;
-  if (typeof value === 'boolean') return ParameterType.PARAMETER_BOOL;
-  if (typeof value === 'string') return ParameterType.PARAMETER_STRING;
-  if (typeof value === 'number') return ParameterType.PARAMETER_DOUBLE;
-  if (Array.isArray(value)) {
+  if (value === null || value === undefined) {
+    return ParameterType.PARAMETER_NOT_SET;
+  }
+
+  if (typeof value === 'boolean') {
+    return ParameterType.PARAMETER_BOOL;
+  }
+
+  if (typeof value === 'string') {
+    return ParameterType.PARAMETER_STRING;
+  }
+
+  if (typeof value === 'bigint') {
+    return ParameterType.PARAMETER_INTEGER;
+  }
+
+  if (typeof value === 'number') {
+    // Distinguish between integer and double
+    return Number.isInteger(value)
+      ? ParameterType.PARAMETER_INTEGER
+      : ParameterType.PARAMETER_DOUBLE;
+  }
+
+  // Handle TypedArrays
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    if (value instanceof Uint8Array) {
+      return ParameterType.PARAMETER_BYTE_ARRAY;
+    }
+    // For other typed arrays, infer from first element
     if (value.length > 0) {
-      const elementType = parameterTypeFromValue(value[0]);
-      switch (elementType) {
-        case ParameterType.PARAMETER_BOOL:
-          return ParameterType.PARAMETER_BOOL_ARRAY;
-        case ParameterType.PARAMETER_DOUBLE:
-          return ParameterType.PARAMETER_DOUBLE_ARRAY;
-        case ParameterType.PARAMETER_STRING:
-          return ParameterType.PARAMETER_STRING_ARRAY;
+      const firstType = parameterTypeFromValue(value[0]);
+      if (firstType === ParameterType.PARAMETER_INTEGER) {
+        return ParameterType.PARAMETER_INTEGER_ARRAY;
       }
+      return ParameterType.PARAMETER_DOUBLE_ARRAY;
     }
-
     return ParameterType.PARAMETER_NOT_SET;
   }
 
-  // otherwise unrecognized value
-  throw new TypeError('Unrecognized parameter type.');
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return ParameterType.PARAMETER_NOT_SET;
+    }
+
+    const elementType = parameterTypeFromValue(value[0]);
+    switch (elementType) {
+      case ParameterType.PARAMETER_BOOL:
+        return ParameterType.PARAMETER_BOOL_ARRAY;
+      case ParameterType.PARAMETER_INTEGER:
+        return ParameterType.PARAMETER_INTEGER_ARRAY;
+      case ParameterType.PARAMETER_DOUBLE:
+        return ParameterType.PARAMETER_DOUBLE_ARRAY;
+      case ParameterType.PARAMETER_STRING:
+        return ParameterType.PARAMETER_STRING_ARRAY;
+      default:
+        return ParameterType.PARAMETER_NOT_SET;
+    }
+  }
+
+  // Unrecognized value type
+  throw new TypeValidationError('value', value, 'valid parameter type', {
+    entityType: 'parameter',
+    details: {
+      supportedTypes: [
+        'boolean',
+        'string',
+        'number',
+        'boolean[]',
+        'number[]',
+        'string[]',
+      ],
+    },
+  });
 }
 
 /**
@@ -826,4 +962,5 @@ module.exports = {
   FloatingPointRange,
   IntegerRange,
   DEFAULT_NUMERIC_RANGE_TOLERANCE,
+  parameterTypeFromValue,
 };