rclnodejs 1.5.2 → 1.6.0

package/index.js

@@ -18,7 +18,7 @@ const DistroUtils = require('./lib/distro.js');
 const RMWUtils = require('./lib/rmw.js');
 const { Clock, ROSClock } = require('./lib/clock.js');
 const ClockType = require('./lib/clock_type.js');
-const compareVersions = require('compare-versions');
+const { compareVersions } = require('./lib/utils.js');
 const Context = require('./lib/context.js');
 const debug = require('debug')('rclnodejs');
 const Duration = require('./lib/duration.js');
@@ -47,6 +47,7 @@ const ActionUuid = require('./lib/action/uuid.js');
 const ClientGoalHandle = require('./lib/action/client_goal_handle.js');
 const { CancelResponse, GoalResponse } = require('./lib/action/response.js');
 const ServerGoalHandle = require('./lib/action/server_goal_handle.js');
+const { toJSONSafe, toJSONString } = require('./lib/message_serialization.js');
 const {
   getActionClientNamesAndTypesByNode,
   getActionServerNamesAndTypesByNode,
@@ -364,8 +365,7 @@ let rcl = {
 
     const version = await getCurrentGeneratorVersion();
     const forced =
-      version === null ||
-      compareVersions.compare(version, generator.version(), '<');
+      version === null || compareVersions(version, generator.version(), '<');
     if (forced) {
       debug(
         'The generator will begin to create JavaScript code from ROS IDL files...'
@@ -539,6 +539,23 @@ let rcl = {
    * @return {Promise<{process: ChildProcess}>} A Promise that resolves with the process.
    */
   ros2Launch: ros2Launch,
+
+  /**
+   * Convert a message object to be JSON-safe by converting TypedArrays to regular arrays
+   * and handling BigInt, Infinity, NaN, etc. for JSON serialization.
+   * @param {*} obj - The message object to convert
+   * @returns {*} A JSON-safe version of the object
+   */
+  toJSONSafe: toJSONSafe,
+
+  /**
+   * Convert a message object to a JSON string with proper handling of TypedArrays,
+   * BigInt, and other non-JSON-serializable values.
+   * @param {*} obj - The message object to convert
+   * @param {number} [space] - Space parameter for JSON.stringify formatting
+   * @returns {string} The JSON string representation
+   */
+  toJSONString: toJSONString,
 };
 
 const _sigHandler = () => {

package/lib/message_serialization.js

@@ -0,0 +1,171 @@
+// 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';
+
+/**
+ * Check if a value is a TypedArray
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a TypedArray
+ */
+function isTypedArray(value) {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+/**
+ * Check if a value needs JSON conversion (BigInt, functions, etc.)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value needs special JSON handling
+ */
+function needsJSONConversion(value) {
+  return (
+    typeof value === 'bigint' ||
+    typeof value === 'function' ||
+    typeof value === 'undefined' ||
+    value === Infinity ||
+    value === -Infinity ||
+    (typeof value === 'number' && isNaN(value))
+  );
+}
+
+/**
+ * Convert a message to plain arrays (TypedArray -> regular Array)
+ * @param {*} obj - The object to convert
+ * @returns {*} The converted object with plain arrays
+ */
+function toPlainArrays(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (isTypedArray(obj)) {
+    return Array.from(obj);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => toPlainArrays(item));
+  }
+
+  if (typeof obj === 'object' && obj !== null) {
+    const result = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        result[key] = toPlainArrays(obj[key]);
+      }
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Convert a message to be fully JSON-safe
+ * @param {*} obj - The object to convert
+ * @returns {*} The JSON-safe converted object
+ */
+function toJSONSafe(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (isTypedArray(obj)) {
+    return Array.from(obj).map((item) => toJSONSafe(item));
+  }
+
+  if (needsJSONConversion(obj)) {
+    if (typeof obj === 'bigint') {
+      // Convert BigInt to string with 'n' suffix to indicate it was a BigInt
+      return obj.toString() + 'n';
+    }
+    if (obj === Infinity) return 'Infinity';
+    if (obj === -Infinity) return '-Infinity';
+    if (typeof obj === 'number' && isNaN(obj)) return 'NaN';
+    if (typeof obj === 'undefined') return null;
+    if (typeof obj === 'function') return '[Function]';
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => toJSONSafe(item));
+  }
+
+  if (typeof obj === 'object' && obj !== null) {
+    const result = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        result[key] = toJSONSafe(obj[key]);
+      }
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Convert a message to a JSON string
+ * @param {*} obj - The object to convert
+ * @param {number} [space] - Space parameter for JSON.stringify formatting
+ * @returns {string} The JSON string representation
+ */
+function toJSONString(obj, space) {
+  const jsonSafeObj = toJSONSafe(obj);
+  return JSON.stringify(jsonSafeObj, null, space);
+}
+
+/**
+ * Apply serialization mode conversion to a message object
+ * @param {*} message - The message object to convert
+ * @param {string} serializationMode - The serialization mode ('default', 'plain', 'json')
+ * @returns {*} The converted message
+ */
+function applySerializationMode(message, serializationMode) {
+  switch (serializationMode) {
+    case 'default':
+      // No conversion needed - use native rclnodejs behavior
+      return message;
+
+    case 'plain':
+      // Convert TypedArrays to regular arrays
+      return toPlainArrays(message);
+
+    case 'json':
+      // Convert to fully JSON-safe format
+      return toJSONSafe(message);
+
+    default:
+      throw new TypeError(
+        `Invalid serializationMode: ${serializationMode}. Valid modes are: 'default', 'plain', 'json'`
+      );
+  }
+}
+
+/**
+ * Validate serialization mode
+ * @param {string} mode - The serialization mode to validate
+ * @returns {boolean} True if valid
+ */
+function isValidSerializationMode(mode) {
+  return ['default', 'plain', 'json'].includes(mode);
+}
+
+module.exports = {
+  isTypedArray,
+  needsJSONConversion,
+  toPlainArrays,
+  toJSONSafe,
+  toJSONString,
+  applySerializationMode,
+  isValidSerializationMode,
+};

package/lib/node.js

@@ -31,6 +31,7 @@ const {
   Parameter,
   ParameterDescriptor,
 } = require('./parameter.js');
+const { isValidSerializationMode } = require('./message_serialization.js');
 const ParameterService = require('./parameter_service.js');
 const Publisher = require('./publisher.js');
 const QoS = require('./qos.js');
@@ -532,6 +533,14 @@ 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 TypeError(
+        `Invalid serializationMode: ${options.serializationMode}. Valid modes are: 'default', 'plain', 'json'`
+      );
+    }
+
     return options;
   }
 
@@ -666,6 +675,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
@@ -1920,6 +1933,7 @@ class Node extends rclnodejs.ShadowNode {
  *   isRaw: false,
  *   qos: QoS.profileDefault,
  *   contentFilter: undefined,
+ *   serializationMode: 'default',
  * }
  */
 Node.getDefaultOptions = function () {
@@ -1928,6 +1942,7 @@ Node.getDefaultOptions = function () {
     isRaw: false,
     qos: QoS.profileDefault,
     contentFilter: undefined,
+    serializationMode: 'default',
   };
 };
 

package/lib/parameter.js

@@ -19,7 +19,7 @@
 
 'use strict';
 
-const IsClose = require('is-close');
+const { isClose } = require('./utils.js');
 
 /**
  * The plus/minus tolerance for determining number equivalence.
@@ -623,8 +623,8 @@ class FloatingPointRange extends Range {
     const max = Math.max(this.fromValue, this.toValue);
 
     if (
-      IsClose.isClose(value, min, this.tolerance) ||
-      IsClose.isClose(value, max, this.tolerance)
+      isClose(value, min, this.tolerance) ||
+      isClose(value, max, this.tolerance)
     ) {
       return true;
     }
@@ -633,13 +633,7 @@ class FloatingPointRange extends Range {
     }
     if (this.step != 0.0) {
       const distanceInSteps = Math.round((value - min) / this.step);
-      if (
-        !IsClose.isClose(
-          min + distanceInSteps * this.step,
-          value,
-          this.tolerance
-        )
-      ) {
+      if (!isClose(min + distanceInSteps * this.step, value, this.tolerance)) {
         return false;
       }
     }

package/lib/subscription.js

@@ -16,6 +16,7 @@
 
 const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
+const { applySerializationMode } = require('./message_serialization.js');
 const debug = require('debug')('rclnodejs:subscription');
 
 /**
@@ -42,6 +43,7 @@ class Subscription extends Entity {
     this._topic = topic;
     this._callback = callback;
     this._isRaw = options.isRaw || false;
+    this._serializationMode = options.serializationMode || 'default';
     this._node = node;
 
     if (node && eventCallbacks) {
@@ -55,7 +57,13 @@ class Subscription extends Entity {
     if (this._isRaw) {
       this._callback(msg);
     } else {
-      this._callback(msg.toPlainObject(this.typedArrayEnabled));
+      let message = msg.toPlainObject(this.typedArrayEnabled);
+
+      if (this._serializationMode !== 'default') {
+        message = applySerializationMode(message, this._serializationMode);
+      }
+
+      this._callback(message);
     }
   }
 
@@ -109,6 +117,13 @@ class Subscription extends Entity {
     return this._isRaw;
   }
 
+  /**
+   * @type {string}
+   */
+  get serializationMode() {
+    return this._serializationMode;
+  }
+
   /**
    * Test if the RMW supports content-filtered topics and that this subscription
    * has an active wellformed content-filter.

package/lib/utils.js

@@ -13,6 +13,156 @@
 // limitations under the License.
 
 const fs = require('fs');
+const fsPromises = require('fs/promises');
+const path = require('path');
+
+/**
+ * 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 +182,143 @@ function detectUbuntuCodename() {
   }
 }
 
+/**
+ * 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 Error(`Invalid operator: ${operator}`);
+  }
+}
+
 module.exports = {
+  // General utilities
   detectUbuntuCodename,
+  isClose,
+
+  // 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,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -19,7 +19,7 @@
     "rebuild:dev": "npm run clean && node-gyp -j 16 rebuild --debug",
     "generate-messages": "node scripts/generate_messages.js",
     "generate-messages-idl": "node scripts/generate_messages.js --idl",
-    "generate-messages:dev": "node scripts/generate_messages.js --debug && npx --yes prettier --ignore-path --write generated/**/*.js",
+    "generate-messages:dev": "node scripts/generate_messages.js --debug",
     "generate-tsd-messages": "node scripts/generate_tsd.js",
     "clean": "node-gyp clean && npx rimraf ./generated",
     "install": "node scripts/install.js",
@@ -76,14 +76,9 @@
     "@rclnodejs/ref-array-di": "^1.2.2",
     "@rclnodejs/ref-struct-di": "^1.1.1",
     "bindings": "^1.5.0",
-    "compare-versions": "^6.1.1",
     "debug": "^4.4.0",
-    "dot": "^1.1.3",
-    "fs-extra": "^11.2.0",
-    "is-close": "^1.3.3",
     "json-bigint": "^1.0.0",
     "node-addon-api": "^8.3.1",
-    "terser": "^5.39.0",
     "walk": "^2.3.15"
   },
   "husky": {