rclnodejs 1.5.2 → 1.7.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/utils.js

@@ -13,6 +13,157 @@
 // limitations under the License.
 
 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)
+ * Replaces: fse.ensureDir() / fse.mkdirs()
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<void>}
+ */
+async function ensureDir(dirPath) {
+  try {
+    await fsPromises.mkdir(dirPath, { recursive: true });
+  } catch (err) {
+    // Ignore if directory already exists
+    if (err.code !== 'EEXIST') throw err;
+  }
+}
+
+/**
+ * Ensure directory exists, create recursively if needed (sync)
+ * Replaces: fse.mkdirSync()
+ * @param {string} dirPath - Path to directory
+ */
+function ensureDirSync(dirPath) {
+  try {
+    fs.mkdirSync(dirPath, { recursive: true });
+  } catch (err) {
+    // Ignore if directory already exists
+    if (err.code !== 'EEXIST') throw err;
+  }
+}
+
+/**
+ * Check if path exists (async)
+ * Replaces: fse.exists()
+ * @param {string} filePath - Path to check
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(filePath) {
+  try {
+    await fsPromises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Empty a directory (remove all contents but keep the directory)
+ * Replaces: fse.emptyDir()
+ * @param {string} dirPath - Path to directory
+ * @returns {Promise<void>}
+ */
+async function emptyDir(dirPath) {
+  try {
+    const files = await fsPromises.readdir(dirPath);
+    await Promise.all(
+      files.map((file) =>
+        fsPromises.rm(path.join(dirPath, file), {
+          recursive: true,
+          force: true,
+        })
+      )
+    );
+  } catch (err) {
+    // Ignore if directory doesn't exist
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Copy file or directory recursively
+ * Replaces: fse.copy()
+ * @param {string} src - Source path
+ * @param {string} dest - Destination path
+ * @param {object} options - Copy options
+ * @returns {Promise<void>}
+ */
+async function copy(src, dest, options = {}) {
+  const opts = {
+    recursive: true,
+    force: options.overwrite !== false,
+    ...options,
+  };
+  await fsPromises.cp(src, dest, opts);
+}
+
+/**
+ * Read and parse JSON file synchronously
+ * Replaces: fse.readJsonSync()
+ * @param {string} filePath - Path to JSON file
+ * @param {object} options - Read options
+ * @returns {any} Parsed JSON data
+ */
+function readJsonSync(filePath, options = {}) {
+  const content = fs.readFileSync(filePath, options.encoding || 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Remove file or directory (async)
+ * Replaces: fse.remove()
+ * @param {string} filePath - Path to remove
+ * @returns {Promise<void>}
+ */
+async function remove(filePath) {
+  try {
+    await fsPromises.rm(filePath, { recursive: true, force: true });
+  } catch (err) {
+    // Ignore if path doesn't exist
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Remove file or directory (sync)
+ * Replaces: fse.removeSync()
+ * @param {string} filePath - Path to remove
+ */
+function removeSync(filePath) {
+  try {
+    fs.rmSync(filePath, { recursive: true, force: true });
+  } catch (err) {
+    // Ignore if path doesn't exist
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Write file with content (async)
+ * Replaces: fse.writeFile()
+ * @param {string} filePath - Path to file
+ * @param {string|Buffer} data - Content to write
+ * @param {object} options - Write options
+ * @returns {Promise<void>}
+ */
+async function writeFile(filePath, data, options = {}) {
+  await fsPromises.writeFile(filePath, data, options);
+}
+
+/**
+ * Create directory (async)
+ * Replaces: fse.mkdir()
+ * @param {string} dirPath - Path to directory
+ * @param {object} options - mkdir options
+ * @returns {Promise<void>}
+ */
+async function mkdir(dirPath, options = {}) {
+  await fsPromises.mkdir(dirPath, options);
+}
 
 /**
  * Detect Ubuntu codename from /etc/os-release
@@ -32,6 +183,168 @@ 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.
+ *
+ * This function compares two numbers using both relative and absolute tolerance,
+ * matching the behavior of the 'is-close' npm package.
+ *
+ * The comparison uses the formula:
+ *   abs(a - b) <= max(rtol * max(abs(a), abs(b)), atol)
+ *
+ * Implementation checks:
+ *   1. Absolute tolerance: abs(a - b) <= atol
+ *   2. Relative tolerance: abs(a - b) / max(abs(a), abs(b)) <= rtol
+ *
+ * @param {number} a - The first number to compare
+ * @param {number} b - The second number to compare
+ * @param {number} [rtol=1e-9] - The relative tolerance parameter (default: 1e-9)
+ * @param {number} [atol=0.0] - The absolute tolerance parameter (default: 0.0)
+ * @returns {boolean} True if the numbers are close within the tolerance
+ *
+ * @example
+ * isClose(1.0, 1.0) // true - exact equality
+ * isClose(1.0, 1.1, 0.01) // false - relative diff: 0.1/1.1 ≈ 0.091 > 0.01
+ * isClose(10, 10.00001, 1e-6) // true - relative diff: 0.00001/10 = 1e-6 <= 1e-6
+ * isClose(0, 0.05, 0, 0.1) // true - absolute diff: 0.05 <= 0.1 (atol)
+ */
+function isClose(a, b, rtol = 1e-9, atol = 0.0) {
+  // Handle exact equality
+  if (a === b) {
+    return true;
+  }
+
+  // Handle non-finite numbers
+  if (!Number.isFinite(a) || !Number.isFinite(b)) {
+    return false;
+  }
+
+  const absDiff = Math.abs(a - b);
+
+  // Check absolute tolerance first (optimization)
+  if (atol >= absDiff) {
+    return true;
+  }
+
+  // Check relative tolerance
+  const relativeScaler = Math.max(Math.abs(a), Math.abs(b));
+
+  // Handle division by zero when both values are zero or very close to zero
+  if (relativeScaler === 0) {
+    return true; // Both are zero, already handled by absolute tolerance
+  }
+
+  const relativeDiff = absDiff / relativeScaler;
+
+  return rtol >= relativeDiff;
+}
+
+/**
+ * Compare two semantic version strings.
+ *
+ * Supports version strings in the format: x.y.z or x.y.z.w
+ * where x, y, z, w are integers.
+ *
+ * @param {string} version1 - First version string (e.g., '1.2.3')
+ * @param {string} version2 - Second version string (e.g., '1.2.4')
+ * @param {string} operator - Comparison operator: '<', '<=', '>', '>=', '==', '!='
+ * @returns {boolean} Result of the comparison
+ *
+ * @example
+ * compareVersions('1.2.3', '1.2.4', '<')   // true
+ * compareVersions('2.0.0', '1.9.9', '>')   // true
+ * compareVersions('1.2.3', '1.2.3', '==')  // true
+ * compareVersions('1.2.3', '1.2.3', '>=')  // true
+ */
+function compareVersions(version1, version2, operator) {
+  // Parse version strings into arrays of integers
+  const v1Parts = version1.split('.').map((part) => parseInt(part, 10));
+  const v2Parts = version2.split('.').map((part) => parseInt(part, 10));
+
+  // Pad arrays to same length with zeros
+  const maxLength = Math.max(v1Parts.length, v2Parts.length);
+  while (v1Parts.length < maxLength) v1Parts.push(0);
+  while (v2Parts.length < maxLength) v2Parts.push(0);
+
+  // Compare each part
+  let cmp = 0;
+  for (let i = 0; i < maxLength; i++) {
+    if (v1Parts[i] > v2Parts[i]) {
+      cmp = 1;
+      break;
+    } else if (v1Parts[i] < v2Parts[i]) {
+      cmp = -1;
+      break;
+    }
+  }
+
+  // Apply operator
+  switch (operator) {
+    case '<':
+      return cmp < 0;
+    case '<=':
+      return cmp <= 0;
+    case '>':
+      return cmp > 0;
+    case '>=':
+      return cmp >= 0;
+    case '==':
+    case '===':
+      return cmp === 0;
+    case '!=':
+    case '!==':
+      return cmp !== 0;
+    default:
+      throw new ValidationError(`Invalid operator: ${operator}`, {
+        code: 'INVALID_OPERATOR',
+        argumentName: 'operator',
+        providedValue: operator,
+        expectedType: "'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte'",
+      });
+  }
+}
+
 module.exports = {
+  // General utilities
   detectUbuntuCodename,
+  isClose,
+  normalizeNodeName,
+
+  // File system utilities (async)
+  ensureDir,
+  mkdirs: ensureDir, // Alias for fs-extra compatibility
+  exists: pathExists, // Renamed to avoid conflict with deprecated fs.exists
+  pathExists,
+  emptyDir,
+  copy,
+  remove,
+  writeFile,
+  mkdir,
+
+  // File system utilities (sync)
+  ensureDirSync,
+  mkdirSync: ensureDirSync, // Alias for fs-extra compatibility
+  removeSync,
+  readJsonSync,
+
+  compareVersions,
 };