rclnodejs 1.6.0 → 1.8.0

package/lib/time.js

@@ -17,6 +17,7 @@
 const rclnodejs = require('./native_loader.js');
 const Duration = require('./duration.js');
 const ClockType = require('./clock_type.js');
+const { TypeValidationError, RangeValidationError } = require('./errors.js');
 const S_TO_NS = 10n ** 9n;
 
 /**
@@ -36,29 +37,49 @@ class Time {
     clockType = ClockType.SYSTEM_TIME
   ) {
     if (typeof seconds !== 'bigint') {
-      throw new TypeError('Invalid argument of seconds');
+      throw new TypeValidationError('seconds', seconds, 'bigint', {
+        entityType: 'time',
+      });
     }
 
     if (typeof nanoseconds !== 'bigint') {
-      throw new TypeError('Invalid argument of nanoseconds');
+      throw new TypeValidationError('nanoseconds', nanoseconds, 'bigint', {
+        entityType: 'time',
+      });
     }
 
     if (typeof clockType !== 'number') {
-      throw new TypeError('Invalid argument of clockType');
+      throw new TypeValidationError('clockType', clockType, 'number', {
+        entityType: 'time',
+      });
     }
 
     if (seconds < 0n) {
-      throw new RangeError('seconds value must not be negative');
+      throw new RangeValidationError('seconds', seconds, '>= 0', {
+        entityType: 'time',
+      });
     }
 
     if (nanoseconds < 0n) {
-      throw new RangeError('nanoseconds value must not be negative');
+      throw new RangeValidationError('nanoseconds', nanoseconds, '>= 0', {
+        entityType: 'time',
+      });
     }
 
     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 time point)',
+        {
+          entityType: 'time',
+          details: {
+            seconds: seconds,
+            nanoseconds: nanoseconds,
+            total: total,
+          },
+        }
       );
     }
     this._nanoseconds = total;
@@ -116,7 +137,9 @@ class Time {
         this._clockType
       );
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Duration', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -127,7 +150,18 @@ class Time {
   sub(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't subtract times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return new Duration(0n, this._nanoseconds - other._nanoseconds);
     } else if (other instanceof Duration) {
@@ -137,7 +171,9 @@ class Time {
         this._clockType
       );
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time or Duration', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -148,11 +184,24 @@ class Time {
   eq(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds === other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -163,10 +212,24 @@ class Time {
   ne(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds !== other.nanoseconds;
     }
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -177,11 +240,24 @@ class Time {
   lt(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds < other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -192,11 +268,24 @@ class Time {
   lte(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds <= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -207,11 +296,24 @@ class Time {
   gt(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds > other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**
@@ -222,11 +324,24 @@ class Time {
   gte(other) {
     if (other instanceof Time) {
       if (other._clockType !== this._clockType) {
-        throw new TypeError("Can't compare times with different clock types");
+        throw new TypeValidationError(
+          'other',
+          other,
+          `Time with clock type ${this._clockType}`,
+          {
+            entityType: 'time',
+            details: {
+              expectedClockType: this._clockType,
+              providedClockType: other._clockType,
+            },
+          }
+        );
       }
       return this._nanoseconds >= other.nanoseconds;
     }
-    throw new TypeError('Invalid argument');
+    throw new TypeValidationError('other', other, 'Time', {
+      entityType: 'time',
+    });
   }
 
   /**

package/lib/time_source.js

@@ -19,6 +19,7 @@ const { Clock, ROSClock } = require('./clock.js');
 const { ClockType } = Clock;
 const { Parameter, ParameterType } = require('./parameter.js');
 const Time = require('./time.js');
+const { TypeValidationError, OperationError } = require('./errors.js');
 
 const USE_SIM_TIME_PARAM = 'use_sim_time';
 const CLOCK_TOPIC = '/clock';
@@ -102,7 +103,9 @@ class TimeSource {
    */
   attachNode(node) {
     if ((!node) instanceof rclnodejs.ShadowNode) {
-      throw new TypeError('Invalid argument, must be type of Node');
+      throw new TypeValidationError('node', node, 'Node', {
+        entityType: 'time source',
+      });
     }
 
     if (this._node) {
@@ -150,8 +153,12 @@ class TimeSource {
   detachNode() {
     if (this._clockSubscription) {
       if (!this._node) {
-        throw new Error(
-          'Unable to destroy previously created clock subscription'
+        throw new OperationError(
+          'Unable to destroy previously created clock subscription',
+          {
+            code: 'NO_NODE_ATTACHED',
+            entityType: 'time source',
+          }
         );
       }
       this._node.destroySubscription(this._clockSubscription);
@@ -167,7 +174,9 @@ class TimeSource {
    */
   attachClock(clock) {
     if (!(clock instanceof ROSClock)) {
-      throw new TypeError('Only clocks with type ROS_TIME can be attached.');
+      throw new TypeValidationError('clock', clock, 'ROSClock', {
+        entityType: 'time source',
+      });
     }
     clock.rosTimeOverride = this._lastTimeSet;
     clock.isRosTimeActive = this._isRosTimeActive;

package/lib/timer.js

@@ -88,6 +88,19 @@ class Timer {
     return rclnodejs.timerGetTimeUntilNextCall(this._handle);
   }
 
+  /**
+   * Get the absolute time in nanoseconds when the next callback is due.
+   * Note: Only available on ROS2 distributions after Humble.
+   * @return {bigint | null} - The next call time in nanoseconds, or null if the timer is canceled.
+   *   Returns undefined if not supported on current ROS2 distribution.
+   */
+  getNextCallTime() {
+    if (typeof rclnodejs.getTimerNextCallTime !== 'function') {
+      return undefined;
+    }
+    return rclnodejs.getTimerNextCallTime(this._handle);
+  }
+
   /**
    * Change the timer period.
    * @param {bigint} period - The new period in nanoseconds.
@@ -105,6 +118,35 @@ class Timer {
     return rclnodejs.getTimerPeriod(this._handle);
   }
 
+  /**
+   * Set the on reset callback.
+   * @param {function} callback - The callback to be called when the timer is reset.
+   * @return {undefined}
+   */
+  setOnResetCallback(callback) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'setOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.setTimerOnResetCallback(this._handle, callback);
+  }
+
+  /**
+   * Clear the on reset callback.
+   * @return {undefined}
+   */
+  clearOnResetCallback() {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'clearOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.clearTimerOnResetCallback(this._handle);
+  }
+
   /**
    * Call a timer and starts counting again, retrieves actual and expected call time.
    * @return {object} - The timer information.

package/lib/utils.js

@@ -15,6 +15,7 @@
 const fs = require('fs');
 const fsPromises = require('fs/promises');
 const path = require('path');
+const { ValidationError } = require('./errors.js');
 
 /**
  * Ensure directory exists, create recursively if needed (async)
@@ -182,6 +183,25 @@ function detectUbuntuCodename() {
   }
 }
 
+/**
+ * Normalize a ROS 2 node name by removing the leading slash if present.
+ *
+ * ROS 2 node names may be specified with or without a leading slash depending
+ * on the context. This utility ensures consistent representation without the
+ * leading slash, which is the standard format for most ROS 2 APIs.
+ *
+ * @param {string} nodeName - The node name to normalize
+ * @returns {string} The normalized node name without leading slash
+ *
+ * @example
+ * normalizeNodeName('my_node')    // 'my_node'
+ * normalizeNodeName('/my_node')   // 'my_node'
+ * normalizeNodeName('/ns/my_node') // 'ns/my_node'
+ */
+function normalizeNodeName(nodeName) {
+  return nodeName.startsWith('/') ? nodeName.substring(1) : nodeName;
+}
+
 /**
  * Check if two numbers are equal within a given tolerance.
  *
@@ -294,7 +314,12 @@ function compareVersions(version1, version2, operator) {
     case '!==':
       return cmp !== 0;
     default:
-      throw new Error(`Invalid operator: ${operator}`);
+      throw new ValidationError(`Invalid operator: ${operator}`, {
+        code: 'INVALID_OPERATOR',
+        argumentName: 'operator',
+        providedValue: operator,
+        expectedType: "'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte'",
+      });
   }
 }
 
@@ -302,6 +327,7 @@ module.exports = {
   // General utilities
   detectUbuntuCodename,
   isClose,
+  normalizeNodeName,
 
   // File system utilities (async)
   ensureDir,

package/lib/validator.js

@@ -15,84 +15,139 @@
 'use strict';
 
 const rclnodejs = require('./native_loader.js');
+const { TypeValidationError, NameValidationError } = require('./errors.js');
 
 /**
  * An object - Representing a validator in ROS.
  * @exports validator
  */
 let validator = {
-  _createErrorFromValidation: function (result) {
-    let err = new Error(result[0]);
-    err.invalidIndex = result[1];
-    return err;
+  _createErrorFromValidation: function (result, nameValue, nameType) {
+    return new NameValidationError(nameValue, nameType, result[0], result[1]);
   },
 
   /**
    * Validate a given topic or service name, and throw an error if invalid.
-   * @param {string} topic - The name of topic/service. and it must be fully-qualified and already expanded.
-   * @return {boolean} - True if it is valid.
+   * @param {string} topic - The name of topic/service. Must be fully-qualified and already expanded.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If topic is not a string.
+   * @throws {NameValidationError} If the topic name is invalid.
    */
   validateFullTopicName(topic) {
     if (typeof topic !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('topic', topic, 'string');
     }
 
     let result = rclnodejs.validateFullTopicName(topic);
     if (result === null) {
       return true;
     }
-    throw this._createErrorFromValidation(result);
+    throw this._createErrorFromValidation(result, topic, 'topic');
+  },
+
+  /**
+   * Check if a fully-qualified topic name is valid without throwing.
+   * @param {string} topic - The name of topic/service. Must be fully-qualified and already expanded.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidFullTopicName(topic) {
+    if (typeof topic !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateFullTopicName(topic) === null;
   },
 
   /**
    * Validate a given node name, and throw an error if invalid.
    * @param {string} name - The name of node.
-   * @return {boolean} - True if it is valid.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If name is not a string.
+   * @throws {NameValidationError} If the node name is invalid.
    */
   validateNodeName(name) {
     if (typeof name !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('name', name, 'string');
     }
 
     let result = rclnodejs.validateNodeName(name);
     if (result === null) {
       return true;
     }
-    throw this._createErrorFromValidation(result);
+    throw this._createErrorFromValidation(result, name, 'node');
+  },
+
+  /**
+   * Check if a node name is valid without throwing.
+   * @param {string} name - The name of node.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidNodeName(name) {
+    if (typeof name !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateNodeName(name) === null;
   },
 
   /**
    * Validate a given topic or service name, and throw an error if invalid.
-   * @param {string} topic - The name of topic/service and does not have to be fully-qualified and is not expanded.
-   * @return {boolean} - True if it is valid.
+   * @param {string} topic - The name of topic/service. Does not have to be fully-qualified.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If topic is not a string.
+   * @throws {NameValidationError} If the topic name is invalid.
    */
   validateTopicName(topic) {
     if (typeof topic !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('topic', topic, 'string');
     }
 
     let result = rclnodejs.validateTopicName(topic);
     if (result === null) {
       return true;
     }
-    throw this._createErrorFromValidation(result);
+    throw this._createErrorFromValidation(result, topic, 'topic');
+  },
+
+  /**
+   * Check if a topic name is valid without throwing.
+   * @param {string} topic - The name of topic/service. Does not have to be fully-qualified.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidTopicName(topic) {
+    if (typeof topic !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateTopicName(topic) === null;
   },
 
   /**
    * Validate a given namespace, and throw an error if invalid.
-   * @param {string} namespace - The namespace to be validated
-   * @return {boolean} - True if it is valid.
+   * @param {string} namespace - The namespace to be validated.
+   * @returns {true} Always returns true if valid.
+   * @throws {TypeValidationError} If namespace is not a string.
+   * @throws {NameValidationError} If the namespace is invalid.
    */
   validateNamespace(namespace) {
     if (typeof namespace !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('namespace', namespace, 'string');
     }
 
     let result = rclnodejs.validateNamespace(namespace);
     if (result === null) {
       return true;
     }
-    throw this._createErrorFromValidation(result);
+    throw this._createErrorFromValidation(result, namespace, 'namespace');
+  },
+
+  /**
+   * Check if a namespace is valid without throwing.
+   * @param {string} namespace - The namespace to be validated.
+   * @returns {boolean} True if valid, false otherwise.
+   */
+  isValidNamespace(namespace) {
+    if (typeof namespace !== 'string') {
+      return false;
+    }
+    return rclnodejs.validateNamespace(namespace) === null;
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
-    "@types/node": "^24.5.2",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.18.0",
     "@typescript-eslint/parser": "^8.18.0",
     "clang-format": "^1.8.0",
@@ -64,6 +64,7 @@
     "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
+    "node-gyp": "^12.1.0",
     "nyc": "^17.1.0",
     "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",
@@ -79,6 +80,7 @@
     "debug": "^4.4.0",
     "json-bigint": "^1.0.0",
     "node-addon-api": "^8.3.1",
+    "rxjs": "^7.8.1",
     "walk": "^2.3.15"
   },
   "husky": {