rclnodejs 1.5.2 → 1.7.0

package/lib/interface_loader.js

@@ -17,6 +17,7 @@
 const path = require('path');
 const fs = require('fs');
 const generator = require('../rosidl_gen/index.js');
+const { TypeValidationError, ValidationError } = require('./errors.js');
 
 let interfaceLoader = {
   loadInterfaceByObject(obj) {
@@ -36,8 +37,13 @@ let interfaceLoader = {
       !obj.type ||
       !obj.name
     ) {
-      throw new TypeError(
-        'Should provide an object argument to get ROS message class'
+      throw new TypeValidationError(
+        'interfaceObject',
+        obj,
+        'object with package, type, and name properties',
+        {
+          entityType: 'interface loader',
+        }
       );
     }
     return this.loadInterface(obj.package, obj.type, obj.name);
@@ -45,9 +51,9 @@ let interfaceLoader = {
 
   loadInterfaceByString(name) {
     if (typeof name !== 'string') {
-      throw new TypeError(
-        'Should provide a string argument to get ROS message class'
-      );
+      throw new TypeValidationError('name', name, 'string', {
+        entityType: 'interface loader',
+      });
     }
 
     // TODO(Kenny): more checks of the string argument
@@ -64,8 +70,15 @@ let interfaceLoader = {
       return this.loadInterfaceByPath(packagePath, interfaces);
     }
 
-    throw new TypeError(
-      'A string argument in expected in "package/type/message" format'
+    throw new ValidationError(
+      'A string argument in expected in "package/type/message" format',
+      {
+        code: 'INVALID_INTERFACE_FORMAT',
+        argumentName: 'name',
+        providedValue: name,
+        expectedType: 'string in "package/type/message" format',
+        entityType: 'interface loader',
+      }
     );
   },
 
@@ -174,8 +187,18 @@ let interfaceLoader = {
         }
       }
     }
-    throw new Error(
-      `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`
+    throw new ValidationError(
+      `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`,
+      {
+        code: 'MESSAGE_NOT_FOUND',
+        entityType: 'interface loader',
+        details: {
+          packageName: packageName,
+          type: type,
+          messageName: messageName,
+          searchPath: generator.generatedRoot,
+        },
+      }
     );
   },
 
@@ -187,7 +210,14 @@ let interfaceLoader = {
       } else if (typeof type === 'string') {
         return this.loadInterfaceByString(type);
       }
-      throw new Error(`The message required does not exist: ${type}`);
+      throw new ValidationError(
+        `The message required does not exist: ${type}`,
+        {
+          code: 'MESSAGE_NOT_FOUND',
+          entityType: 'interface loader',
+          details: { type: type },
+        }
+      );
     }
     if (packageName && type && messageName) {
       let filePath = path.join(
@@ -208,8 +238,18 @@ let interfaceLoader = {
       }
     }
     // We cannot parse `packageName`, `type` and `messageName` from the string passed.
-    throw new Error(
-      `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`
+    throw new ValidationError(
+      `The message required does not exist: ${packageName}, ${type}, ${messageName} at ${generator.generatedRoot}`,
+      {
+        code: 'MESSAGE_NOT_FOUND',
+        entityType: 'interface loader',
+        details: {
+          packageName: packageName,
+          type: type,
+          messageName: messageName,
+          searchPath: generator.generatedRoot,
+        },
+      }
     );
   },
 };

package/lib/lifecycle.js

@@ -21,6 +21,7 @@ const Context = require('./context.js');
 const Node = require('./node.js');
 const NodeOptions = require('./node_options.js');
 const Service = require('./service.js');
+const { ValidationError } = require('./errors.js');
 
 const SHUTDOWN_TRANSITION_LABEL =
   rclnodejs.getLifecycleShutdownTransitionLabel();
@@ -707,8 +708,13 @@ class LifecycleNode extends Node {
           );
 
     if (!newStateObj) {
-      throw new Error(
-        `No transition available from state ${transitionIdOrLabel}.`
+      throw new ValidationError(
+        `No transition available from state ${transitionIdOrLabel}`,
+        {
+          code: 'INVALID_TRANSITION',
+          entityType: 'lifecycle node',
+          details: { transitionIdOrLabel: transitionIdOrLabel },
+        }
       );
     }
 

package/lib/logging.js

@@ -16,6 +16,7 @@
 
 const path = require('path');
 const rclnodejs = require('./native_loader.js');
+const { TypeValidationError } = require('./errors.js');
 
 /**
  * Enum for LoggingSeverity
@@ -98,7 +99,10 @@ class Logging {
    */
   setLoggerLevel(level) {
     if (typeof level !== 'number') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('level', level, 'number', {
+        entityType: 'logger',
+        entityName: this._name,
+      });
     }
     rclnodejs.setLoggerLevel(this._name, level);
   }
@@ -164,7 +168,10 @@ class Logging {
 
   _log(message, severity) {
     if (typeof message !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('message', message, 'string', {
+        entityType: 'logger',
+        entityName: this._name,
+      });
     }
 
     let caller = new Caller();
@@ -204,7 +211,9 @@ class Logging {
    */
   static getLogger(name) {
     if (typeof name !== 'string') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('name', name, 'string', {
+        entityType: 'logger',
+      });
     }
     return new Logging(name);
   }

package/lib/message_serialization.js

@@ -0,0 +1,179 @@
+// 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 { ValidationError } = require('./errors.js');
+
+/**
+ * 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 ValidationError(
+        `Invalid serializationMode: ${serializationMode}. Valid modes are: 'default', 'plain', 'json'`,
+        {
+          code: 'INVALID_SERIALIZATION_MODE',
+          argumentName: 'serializationMode',
+          providedValue: serializationMode,
+          expectedType: "'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/native_loader.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { NativeError } = require('./errors.js');
 const bindings = require('bindings');
 const debug = require('debug')('rclnodejs');
 const { detectUbuntuCodename } = require('./utils');
@@ -100,8 +101,10 @@ function loadNativeAddon() {
       return nativeModule;
     } catch (compileError) {
       debug('Forced compilation failed:', compileError.message);
-      throw new Error(
-        `Failed to force build rclnodejs from source: ${compileError.message}`
+      throw new NativeError(
+        `Failed to force build rclnodejs from source: ${compileError.message}`,
+        'Forced compilation',
+        { cause: compileError }
       );
     }
   }
@@ -163,8 +166,10 @@ function loadNativeAddon() {
       return nativeModule;
     } catch (compileError) {
       debug('Compilation failed:', compileError.message);
-      throw new Error(
-        `Failed to build rclnodejs from source: ${compileError.message}`
+      throw new NativeError(
+        `Failed to build rclnodejs from source: ${compileError.message}`,
+        'Compilation',
+        { cause: compileError }
       );
     }
   }