rclnodejs 1.6.0 → 1.8.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,8 @@
 
 const path = require('path');
 const rclnodejs = require('./native_loader.js');
+const { TypeValidationError } = require('./errors.js');
+const Context = require('./context.js');
 
 /**
  * Enum for LoggingSeverity
@@ -88,6 +90,8 @@ class Caller {
 class Logging {
   constructor(name) {
     this._name = name;
+    this._parentName = null;
+    this._subName = null;
   }
 
   /**
@@ -98,7 +102,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 +171,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();
@@ -196,6 +206,50 @@ class Logging {
     return this._name;
   }
 
+  /**
+   * Create a child logger.
+   * @param {string} name - name of the child logger.
+   * @function
+   * @return {Logging} Return the child logger object.
+   */
+  getChild(name) {
+    if (typeof name !== 'string' || !name) {
+      throw new Error('Child logger name must be a non-empty string.');
+    }
+
+    let fullname = name;
+    if (this._name) {
+      fullname = this._name + '.' + name;
+    }
+
+    const logger = new Logging(fullname);
+    if (this._name) {
+      if (
+        rclnodejs.addRosoutSublogger &&
+        rclnodejs.addRosoutSublogger(this._name, name)
+      ) {
+        logger._parentName = this._name;
+        logger._subName = name;
+      }
+    }
+    return logger;
+  }
+
+  /**
+   * Destroy the logger and remove it from the parent logger if it is a child logger.
+   * @function
+   * @return {undefined}
+   */
+  destroy() {
+    if (this._parentName && this._subName) {
+      if (rclnodejs.removeRosoutSublogger) {
+        rclnodejs.removeRosoutSublogger(this._parentName, this._subName);
+      }
+      this._parentName = null;
+      this._subName = null;
+    }
+  }
+
   /**
    * Create a logger by name.
    * @param {string} name - name of the logger.
@@ -204,10 +258,43 @@ 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);
   }
+
+  /**
+   * Configure the logging system with the given context.
+   * @param {Context} context - The context to configure logging for.
+   * @function
+   * @return {undefined}
+   */
+  static configure(context) {
+    if (!(context instanceof Context)) {
+      throw new TypeValidationError('context', context, 'Context');
+    }
+    rclnodejs.loggingConfigure(context.handle);
+  }
+
+  /**
+   * Shutdown the logging system.
+   * @function
+   * @return {undefined}
+   */
+  static shutdown() {
+    rclnodejs.loggingFini();
+  }
+
+  /**
+   * Get the logging directory.
+   * @function
+   * @return {string} - The logging directory.
+   */
+  static getLoggingDirectory() {
+    return rclnodejs.getLoggingDirectory();
+  }
 }
 
 module.exports = Logging;

package/lib/message_introspector.js

@@ -0,0 +1,123 @@
+// 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 loader = require('./interface_loader.js');
+const { toPlainObject } = require('../rosidl_gen/message_translator.js');
+const { TypeValidationError } = require('./errors.js');
+
+/**
+ * A utility class for inspecting ROS 2 message structure without using loader.loadInterface directly.
+ * Provides access to message schema, field names, and default values.
+ */
+class MessageIntrospector {
+  #typeClass;
+  #typeName;
+  #defaultsCache;
+
+  /**
+   * Create a new MessageIntrospector for a ROS 2 message type.
+   * @param {string} typeName - The full message type name (e.g., 'geometry_msgs/msg/Twist')
+   * @throws {TypeValidationError} If typeName is not a non-empty string
+   * @throws {Error} If the message type cannot be loaded
+   */
+  constructor(typeName) {
+    if (!typeName || typeof typeName !== 'string') {
+      throw new TypeValidationError('typeName', typeName, 'non-empty string', {
+        entityType: 'MessageIntrospector',
+      });
+    }
+    this.#typeName = typeName;
+    this.#typeClass = loader.loadInterface(typeName);
+    this.#defaultsCache = null;
+  }
+
+  /**
+   * Get the full message type name.
+   * @returns {string} The message type name (e.g., 'geometry_msgs/msg/Twist')
+   */
+  get typeName() {
+    return this.#typeName;
+  }
+
+  /**
+   * Get the underlying ROS message class.
+   * @returns {Function} The message type class constructor
+   */
+  get typeClass() {
+    return this.#typeClass;
+  }
+
+  /**
+   * Get the field names of the message.
+   * @returns {string[]} Array of field names
+   */
+  get fields() {
+    const def = this.#typeClass.ROSMessageDef;
+    return def.fields.map((f) => f.name);
+  }
+
+  /**
+   * Get the ROSMessageDef schema for the message type.
+   * @returns {object} The message definition schema
+   */
+  get schema() {
+    return this.#typeClass.ROSMessageDef;
+  }
+
+  /**
+   * Get the default values for all fields.
+   * Creates a new instance of the message and converts it to a plain object.
+   * Result is cached for performance.
+   * @returns {object} A plain object with all default values
+   */
+  get defaults() {
+    if (this.#defaultsCache === null) {
+      const instance = new this.#typeClass();
+      this.#defaultsCache = toPlainObject(instance);
+    }
+    return this.#deepClone(this.#defaultsCache);
+  }
+
+  /**
+   * Deep clone an object.
+   * @param {any} obj - Object to clone
+   * @returns {any} Cloned object
+   * @private
+   */
+  #deepClone(obj) {
+    if (obj === null || typeof obj !== 'object') {
+      return obj;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.#deepClone(item));
+    }
+
+    if (ArrayBuffer.isView(obj) && !(obj instanceof DataView)) {
+      return obj.slice();
+    }
+
+    const cloned = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        cloned[key] = this.#deepClone(obj[key]);
+      }
+    }
+    return cloned;
+  }
+}
+
+module.exports = MessageIntrospector;

package/lib/message_serialization.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const { ValidationError } = require('./errors.js');
+
 /**
  * Check if a value is a TypedArray
  * @param {*} value - The value to check
@@ -145,8 +147,14 @@ function applySerializationMode(message, serializationMode) {
       return toJSONSafe(message);
 
     default:
-      throw new TypeError(
-        `Invalid serializationMode: ${serializationMode}. Valid modes are: 'default', 'plain', 'json'`
+      throw new ValidationError(
+        `Invalid serializationMode: ${serializationMode}. Valid modes are: 'default', 'plain', 'json'`,
+        {
+          code: 'INVALID_SERIALIZATION_MODE',
+          argumentName: 'serializationMode',
+          providedValue: serializationMode,
+          expectedType: "'default' | 'plain' | 'json'",
+        }
       );
   }
 }