Add MessageIntrospector for message schema inspection (#1346)

MessageIntrospector, a utility class that provides a simplified API for inspecting ROS 2 message structure without directly using loader.loadInterface.

- typeName: Returns the full message type (e.g., geometry_msgs/msg/Twist)
- fields:- Returns an array of top-level field names
- defaults: Returns a deep copy of the message's default values
- schema: Returns the underlying ROSMessageDef object
- typeClass: Returns the underlying constructor

Author: mahmoud-ghalayini

CONTRIBUTORS.md

@@ -45,6 +45,8 @@
   - Add structured error handling with class error hierarchy
   - Add ParameterWatcher for real-time parameter monitoring
   - Enhance Message Validation
+  - Add TypeScript definitions and non-throwing variants for validator
+  - Add MessageIntrospector for message schema inspection
 
 - **[Martins Mozeiko](https://github.com/martins-mozeiko)**
   - QoS new/delete fix

example/message-introspector/README.md

@@ -0,0 +1,47 @@
+# ROS 2 MessageIntrospector Example
+
+This directory contains an example demonstrating the `MessageIntrospector` class for inspecting ROS 2 message structure.
+
+## Overview
+
+The `MessageIntrospector` class provides a simple way to understand the structure of ROS 2 messages without directly using `loader.loadInterface`. It's useful for debugging, generating documentation, and building dynamic UIs based on message structure.
+
+## MessageIntrospector Example (`message-introspector-example.js`)
+
+**Purpose**: Demonstrates how to inspect message structure, fields, and default values.
+
+### Run Command
+
+```bash
+node message-introspector-example.js
+```
+
+### Expected Output
+
+```
+Twist fields: [ 'linear', 'angular' ]
+Twist defaults: { linear: { x: 0, y: 0, z: 0 }, angular: { x: 0, y: 0, z: 0 } }
+String fields: [ 'data' ]
+String defaults: { data: '' }
+JointState fields: [ 'header', 'name', 'position', 'velocity', 'effort' ]
+Twist schema msgName: Twist
+```
+
+## API
+
+```javascript
+const Twist = new rclnodejs.MessageIntrospector('geometry_msgs/msg/Twist');
+
+Twist.typeName; // 'geometry_msgs/msg/Twist'
+Twist.fields; // ['linear', 'angular']
+Twist.defaults; // { linear: { x: 0, y: 0, z: 0 }, angular: { x: 0, y: 0, z: 0 } }
+Twist.schema; // ROSMessageDef object
+Twist.typeClass; // The underlying constructor
+```
+
+## Notes
+
+- Works with any message type including custom packages
+- Default values are cached for performance after the first access
+- The `defaults` getter returns a new deep copy each time to prevent mutation
+- Service request/response types can also be inspected (e.g., `'my_pkg/srv/MyService_Request'`)

example/message-introspector/message-introspector-example.js

@@ -0,0 +1,45 @@
+// 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 rclnodejs = require('../../index.js');
+
+/**
+ * This example demonstrates the MessageIntrospector class for
+ * inspecting ROS 2 message structure without using loader.loadInterface.
+ */
+async function main() {
+  await rclnodejs.init();
+
+  const Twist = new rclnodejs.MessageIntrospector('geometry_msgs/msg/Twist');
+  const String = new rclnodejs.MessageIntrospector('std_msgs/msg/String');
+  const JointState = new rclnodejs.MessageIntrospector(
+    'sensor_msgs/msg/JointState'
+  );
+
+  console.log('Twist fields:', Twist.fields);
+  console.log('Twist defaults:', Twist.defaults);
+
+  console.log('String fields:', String.fields);
+  console.log('String defaults:', String.defaults);
+
+  console.log('JointState fields:', JointState.fields);
+
+  console.log('Twist schema msgName:', Twist.schema.msgName);
+
+  await rclnodejs.shutdown();
+}
+
+main();

index.js

@@ -61,6 +61,7 @@ const {
 const ParameterClient = require('./lib/parameter_client.js');
 const errors = require('./lib/errors.js');
 const ParameterWatcher = require('./lib/parameter_watcher.js');
+const MessageIntrospector = require('./lib/message_introspector.js');
 const { spawn } = require('child_process');
 const {
   ValidationProblem,
@@ -721,3 +722,6 @@ const Lifecycle = require('./lib/lifecycle.js');
 
 /** Lifecycle namespace */
 rcl.lifecycle = Lifecycle;
+
+/** {@link MessageIntrospector} class */
+rcl.MessageIntrospector = MessageIntrospector;

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;

src/rcl_logging_bindings.cpp

@@ -41,7 +41,7 @@ Napi::Value InitRosoutPublisherForNode(const Napi::CallbackInfo& info) {
           .ThrowAsJavaScriptException();
       rcl_reset_error();
     }
-      }
+  }
   return env.Undefined();
 }
 

src/rcl_utilities.cpp

@@ -369,9 +369,8 @@ void ThrowIfUnparsedROSArgs(Napi::Env env, const Napi::Array& jsArgv,
     return;
   }
 
-  RCPPUTILS_SCOPE_EXIT({
-    allocator.deallocate(unparsed_indices_c, allocator.state);
-  });
+  RCPPUTILS_SCOPE_EXIT(
+      { allocator.deallocate(unparsed_indices_c, allocator.state); });
 
   std::string unparsed_args_str = "[";
   for (int i = 0; i < unparsed_ros_args_count; ++i) {