rclnodejs 1.7.0 → 1.8.0

package/lib/errors.js

@@ -162,6 +162,55 @@ class RangeValidationError extends ValidationError {
   }
 }
 
+/**
+ * Message validation error for ROS message structure/type issues
+ * @class
+ * @extends ValidationError
+ */
+class MessageValidationError extends ValidationError {
+  /**
+   * @param {string} messageType - The ROS message type (e.g., 'std_msgs/msg/String')
+   * @param {Array<object>} issues - Array of validation issues
+   * @param {string} issues[].field - Field path where issue occurred
+   * @param {string} issues[].problem - Problem type (UNKNOWN_FIELD, TYPE_MISMATCH, etc.)
+   * @param {string} [issues[].expected] - Expected type or value
+   * @param {any} [issues[].received] - Actual value received
+   * @param {object} [options] - Additional options
+   */
+  constructor(messageType, issues, options = {}) {
+    const issuesSummary = issues
+      .map((i) => `${i.field}: ${i.problem}`)
+      .join(', ');
+    super(`Invalid message for '${messageType}': ${issuesSummary}`, {
+      code: 'MESSAGE_VALIDATION_ERROR',
+      entityType: 'message',
+      entityName: messageType,
+      details: { issues },
+      ...options,
+    });
+    this.messageType = messageType;
+    this.issues = issues;
+  }
+
+  /**
+   * Get issues filtered by problem type
+   * @param {string} problemType - Problem type to filter by
+   * @returns {Array<object>} Filtered issues
+   */
+  getIssuesByType(problemType) {
+    return this.issues.filter((i) => i.problem === problemType);
+  }
+
+  /**
+   * Check if a specific field has validation issues
+   * @param {string} fieldPath - Field path to check
+   * @returns {boolean} True if field has issues
+   */
+  hasFieldIssue(fieldPath) {
+    return this.issues.some((i) => i.field === fieldPath);
+  }
+}
+
 /**
  * ROS name validation error (topics, nodes, services)
  * @class
@@ -541,6 +590,7 @@ module.exports = {
   ValidationError,
   TypeValidationError,
   RangeValidationError,
+  MessageValidationError,
   NameValidationError,
 
   // Operation errors

package/lib/logging.js

@@ -17,6 +17,7 @@
 const path = require('path');
 const rclnodejs = require('./native_loader.js');
 const { TypeValidationError } = require('./errors.js');
+const Context = require('./context.js');
 
 /**
  * Enum for LoggingSeverity
@@ -89,6 +90,8 @@ class Caller {
 class Logging {
   constructor(name) {
     this._name = name;
+    this._parentName = null;
+    this._subName = null;
   }
 
   /**
@@ -203,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.
@@ -217,6 +264,37 @@ class Logging {
     }
     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;