rclnodejs 1.7.0 → 1.8.0

package/lib/message_validation.js

@@ -0,0 +1,512 @@
+// 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 { MessageValidationError, TypeValidationError } = require('./errors.js');
+const interfaceLoader = require('./interface_loader.js');
+
+/**
+ * Validation issue problem types
+ * @enum {string}
+ */
+const ValidationProblem = {
+  /** Field exists in object but not in message schema */
+  UNKNOWN_FIELD: 'UNKNOWN_FIELD',
+  /** Field type doesn't match expected type */
+  TYPE_MISMATCH: 'TYPE_MISMATCH',
+  /** Required field is missing */
+  MISSING_FIELD: 'MISSING_FIELD',
+  /** Array length constraint violated */
+  ARRAY_LENGTH: 'ARRAY_LENGTH',
+  /** Value is out of valid range */
+  OUT_OF_RANGE: 'OUT_OF_RANGE',
+  /** Nested message validation failed */
+  NESTED_ERROR: 'NESTED_ERROR',
+};
+
+/**
+ * Map ROS primitive types to JavaScript types
+ */
+const PRIMITIVE_TYPE_MAP = {
+  bool: 'boolean',
+  int8: 'number',
+  uint8: 'number',
+  int16: 'number',
+  uint16: 'number',
+  int32: 'number',
+  uint32: 'number',
+  int64: 'bigint',
+  uint64: 'bigint',
+  float32: 'number',
+  float64: 'number',
+  char: 'number',
+  byte: 'number',
+  string: 'string',
+  wstring: 'string',
+};
+
+/**
+ * Check if value is a TypedArray
+ * @param {any} value - Value to check
+ * @returns {boolean} True if TypedArray
+ */
+function isTypedArray(value) {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+/**
+ * Get the JavaScript type string for a value
+ * @param {any} value - Value to get type of
+ * @returns {string} Type description
+ */
+function getValueType(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (Array.isArray(value)) return 'array';
+  if (isTypedArray(value)) return 'TypedArray';
+  return typeof value;
+}
+
+/**
+ * Resolve a type class from various input formats
+ * @param {string|object|function} typeClass - Type identifier
+ * @returns {function|null} The resolved type class or null
+ */
+function resolveTypeClass(typeClass) {
+  if (typeof typeClass === 'function') {
+    return typeClass;
+  }
+
+  try {
+    return interfaceLoader.loadInterface(typeClass);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get message type string from type class
+ * @param {function} typeClass - Message type class
+ * @returns {string} Message type string (e.g., 'std_msgs/msg/String')
+ */
+function getMessageTypeString(typeClass) {
+  if (typeof typeClass.type === 'function') {
+    const t = typeClass.type();
+    return `${t.pkgName}/${t.subFolder}/${t.interfaceName}`;
+  }
+  return 'unknown';
+}
+
+/**
+ * Get the schema definition for a message type
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @returns {object|null} Schema definition with fields and constants, or null if not found
+ * @example
+ * const schema = getMessageSchema(StringClass);
+ * // Returns: {
+ * //   fields: [{name: 'data', type: {type: 'string', isPrimitiveType: true, ...}}],
+ * //   constants: [],
+ * //   messageType: 'std_msgs/msg/String'
+ * // }
+ */
+function getMessageSchema(typeClass) {
+  const resolved = resolveTypeClass(typeClass);
+  if (!resolved || !resolved.ROSMessageDef) {
+    return null;
+  }
+
+  const def = resolved.ROSMessageDef;
+  return {
+    fields: def.fields || [],
+    constants: def.constants || [],
+    messageType: getMessageTypeString(resolved),
+    baseType: def.baseType,
+  };
+}
+
+/**
+ * Get field names for a message type
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @returns {string[]} Array of field names
+ */
+function getFieldNames(typeClass) {
+  const schema = getMessageSchema(typeClass);
+  if (!schema) return [];
+  return schema.fields.map((f) => f.name);
+}
+
+/**
+ * Get type information for a specific field
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @param {string} fieldName - Name of the field
+ * @returns {object|null} Field type information or null if not found
+ */
+function getFieldType(typeClass, fieldName) {
+  const schema = getMessageSchema(typeClass);
+  if (!schema) return null;
+
+  const field = schema.fields.find((f) => f.name === fieldName);
+  return field ? field.type : null;
+}
+
+/**
+ * Validate a primitive value against its expected type
+ * @param {any} value - Value to validate
+ * @param {object} fieldType - Field type definition
+ * @returns {object|null} Validation issue or null if valid
+ */
+function validatePrimitiveValue(value, fieldType) {
+  const expectedJsType = PRIMITIVE_TYPE_MAP[fieldType.type];
+  const actualType = typeof value;
+
+  if (!expectedJsType) {
+    return null; // Unknown primitive type, skip validation
+  }
+
+  // Allow number for bigint fields (will be converted)
+  if (expectedJsType === 'bigint' && actualType === 'number') {
+    return null;
+  }
+
+  if (actualType !== expectedJsType) {
+    return {
+      problem: ValidationProblem.TYPE_MISMATCH,
+      expected: expectedJsType,
+      received: actualType,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Validate array constraints
+ * @param {any} value - Array value to validate
+ * @param {object} fieldType - Field type definition
+ * @returns {object|null} Validation issue or null if valid
+ */
+function validateArrayConstraints(value, fieldType) {
+  if (!Array.isArray(value) && !isTypedArray(value)) {
+    return {
+      problem: ValidationProblem.TYPE_MISMATCH,
+      expected: 'array',
+      received: getValueType(value),
+    };
+  }
+
+  const length = value.length;
+
+  // Fixed size array
+  if (fieldType.isFixedSizeArray && length !== fieldType.arraySize) {
+    return {
+      problem: ValidationProblem.ARRAY_LENGTH,
+      expected: `exactly ${fieldType.arraySize} elements`,
+      received: `${length} elements`,
+    };
+  }
+
+  // Upper bound array
+  if (fieldType.isUpperBound && length > fieldType.arraySize) {
+    return {
+      problem: ValidationProblem.ARRAY_LENGTH,
+      expected: `at most ${fieldType.arraySize} elements`,
+      received: `${length} elements`,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Validate a message object against its schema
+ * @param {object} obj - Plain object to validate
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @param {object} [options] - Validation options
+ * @param {boolean} [options.strict=false] - If true, unknown fields cause validation failure
+ * @param {boolean} [options.checkTypes=true] - If true, validate field types
+ * @param {boolean} [options.checkRequired=false] - If true, check for missing fields
+ * @param {string} [options.path=''] - Current path for nested validation (internal use)
+ * @returns {{valid: boolean, issues: Array<object>}} Validation result
+ */
+function validateMessage(obj, typeClass, options = {}) {
+  const {
+    strict = false,
+    checkTypes = true,
+    checkRequired = false,
+    path = '',
+  } = options;
+
+  const issues = [];
+  const resolved = resolveTypeClass(typeClass);
+
+  if (!resolved) {
+    issues.push({
+      field: path || '(root)',
+      problem: 'INVALID_TYPE_CLASS',
+      expected: 'valid message type class',
+      received: typeof typeClass,
+    });
+    return { valid: false, issues };
+  }
+
+  const schema = getMessageSchema(resolved);
+  if (!schema) {
+    issues.push({
+      field: path || '(root)',
+      problem: 'NO_SCHEMA',
+      expected: 'message with ROSMessageDef',
+      received: 'class without schema',
+    });
+    return { valid: false, issues };
+  }
+
+  if (obj === null || obj === undefined) {
+    issues.push({
+      field: path || '(root)',
+      problem: ValidationProblem.TYPE_MISMATCH,
+      expected: 'object',
+      received: String(obj),
+    });
+    return { valid: false, issues };
+  }
+
+  const type = typeof obj;
+  if (
+    type === 'string' ||
+    type === 'number' ||
+    type === 'boolean' ||
+    type === 'bigint'
+  ) {
+    if (schema.fields.length === 1 && schema.fields[0].name === 'data') {
+      const fieldType = schema.fields[0].type;
+      if (checkTypes && fieldType.isPrimitiveType) {
+        const typeIssue = validatePrimitiveValue(obj, fieldType);
+        if (typeIssue) {
+          issues.push({
+            field: path ? `${path}.data` : 'data',
+            ...typeIssue,
+          });
+        }
+      }
+      return { valid: issues.length === 0, issues };
+    }
+  }
+
+  if (type !== 'object') {
+    issues.push({
+      field: path || '(root)',
+      problem: ValidationProblem.TYPE_MISMATCH,
+      expected: 'object',
+      received: type,
+    });
+    return { valid: false, issues };
+  }
+
+  const fieldNames = new Set(schema.fields.map((f) => f.name));
+  const objKeys = Object.keys(obj);
+
+  if (strict) {
+    for (const key of objKeys) {
+      if (!fieldNames.has(key)) {
+        issues.push({
+          field: path ? `${path}.${key}` : key,
+          problem: ValidationProblem.UNKNOWN_FIELD,
+        });
+      }
+    }
+  }
+
+  for (const field of schema.fields) {
+    const fieldPath = path ? `${path}.${field.name}` : field.name;
+    const value = obj[field.name];
+    const fieldType = field.type;
+
+    if (field.name.startsWith('_')) continue;
+
+    if (value === undefined) {
+      if (checkRequired) {
+        issues.push({
+          field: fieldPath,
+          problem: ValidationProblem.MISSING_FIELD,
+          expected: fieldType.type,
+        });
+      }
+      continue;
+    }
+
+    if (fieldType.isArray) {
+      const arrayIssue = validateArrayConstraints(value, fieldType);
+      if (arrayIssue) {
+        issues.push({ field: fieldPath, ...arrayIssue });
+        continue;
+      }
+
+      if (checkTypes && Array.isArray(value) && value.length > 0) {
+        if (fieldType.isPrimitiveType) {
+          for (let i = 0; i < value.length; i++) {
+            const elemIssue = validatePrimitiveValue(value[i], fieldType);
+            if (elemIssue) {
+              issues.push({
+                field: `${fieldPath}[${i}]`,
+                ...elemIssue,
+              });
+            }
+          }
+        } else {
+          for (let i = 0; i < value.length; i++) {
+            const nestedResult = validateMessage(
+              value[i],
+              getNestedTypeClass(resolved, field.name),
+              {
+                strict,
+                checkTypes,
+                checkRequired,
+                path: `${fieldPath}[${i}]`,
+              }
+            );
+            if (!nestedResult.valid) {
+              issues.push(...nestedResult.issues);
+            }
+          }
+        }
+      }
+    } else if (fieldType.isPrimitiveType) {
+      if (checkTypes) {
+        const typeIssue = validatePrimitiveValue(value, fieldType);
+        if (typeIssue) {
+          issues.push({ field: fieldPath, ...typeIssue });
+        }
+      }
+    } else {
+      if (value !== null && typeof value === 'object') {
+        const nestedTypeClass = getNestedTypeClass(resolved, field.name);
+        if (nestedTypeClass) {
+          const nestedResult = validateMessage(value, nestedTypeClass, {
+            strict,
+            checkTypes,
+            checkRequired,
+            path: fieldPath,
+          });
+          if (!nestedResult.valid) {
+            issues.push(...nestedResult.issues);
+          }
+        }
+      } else if (checkTypes && value !== null) {
+        issues.push({
+          field: fieldPath,
+          problem: ValidationProblem.TYPE_MISMATCH,
+          expected: 'object',
+          received: getValueType(value),
+        });
+      }
+    }
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+/**
+ * Get the type class for a nested field
+ * @param {function} parentTypeClass - Parent message type class
+ * @param {string} fieldName - Field name
+ * @returns {function|null} Nested type class or null
+ */
+function getNestedTypeClass(parentTypeClass, fieldName) {
+  try {
+    const instance = new parentTypeClass();
+    const fieldValue = instance[fieldName];
+
+    if (
+      fieldValue &&
+      fieldValue.constructor &&
+      fieldValue.constructor.ROSMessageDef
+    ) {
+      return fieldValue.constructor;
+    }
+
+    if (
+      fieldValue &&
+      fieldValue.classType &&
+      fieldValue.classType.elementType
+    ) {
+      return fieldValue.classType.elementType;
+    }
+  } catch {
+    const schema = getMessageSchema(parentTypeClass);
+    if (schema) {
+      const field = schema.fields.find((f) => f.name === fieldName);
+      if (field && !field.type.isPrimitiveType) {
+        const typeName = `${field.type.pkgName}/msg/${field.type.type}`;
+        return resolveTypeClass(typeName);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate a message and throw if invalid
+ * @param {object} obj - Plain object to validate
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @param {object} [options] - Validation options (same as validateMessage)
+ * @throws {MessageValidationError} If validation fails
+ * @returns {void}
+ */
+function assertValidMessage(obj, typeClass, options = {}) {
+  const result = validateMessage(obj, typeClass, options);
+
+  if (!result.valid) {
+    const resolved = resolveTypeClass(typeClass);
+    const messageType = resolved
+      ? getMessageTypeString(resolved)
+      : String(typeClass);
+    throw new MessageValidationError(messageType, result.issues);
+  }
+}
+
+/**
+ * Create a validator function for a specific message type
+ * @param {function|string|object} typeClass - Message type class or identifier
+ * @param {object} [defaultOptions] - Default validation options
+ * @returns {function} Validator function that takes (obj, options?) and returns validation result
+ */
+function createMessageValidator(typeClass, defaultOptions = {}) {
+  const resolved = resolveTypeClass(typeClass);
+  if (!resolved) {
+    throw new TypeValidationError(
+      'typeClass',
+      typeClass,
+      'valid message type class'
+    );
+  }
+
+  return function validator(obj, options = {}) {
+    return validateMessage(obj, resolved, {
+      ...defaultOptions,
+      ...options,
+    });
+  };
+}
+
+module.exports = {
+  ValidationProblem,
+  getMessageSchema,
+  getFieldNames,
+  getFieldType,
+  validateMessage,
+  assertValidMessage,
+  createMessageValidator,
+  getMessageTypeString,
+};

package/lib/node.js

@@ -45,6 +45,7 @@ const QoS = require('./qos.js');
 const Rates = require('./rate.js');
 const Service = require('./service.js');
 const Subscription = require('./subscription.js');
+const ObservableSubscription = require('./observable_subscription.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
@@ -102,7 +103,8 @@ class Node extends rclnodejs.ShadowNode {
       namespace,
       context.handle,
       args,
-      useGlobalArguments
+      useGlobalArguments,
+      options.rosoutQos
     );
     Object.defineProperty(this, 'handle', {
       configurable: false,
@@ -132,6 +134,11 @@ class Node extends rclnodejs.ShadowNode {
     this._setParametersCallbacks = [];
     this._logger = new Logging(rclnodejs.getNodeLoggerName(this.handle));
     this._spinning = false;
+    this._enableRosout = options.enableRosout;
+
+    if (this._enableRosout) {
+      rclnodejs.initRosoutPublisherForNode(this.handle);
+    }
 
     this._parameterEventPublisher = this.createPublisher(
       PARAMETER_EVENT_MSG_TYPE,
@@ -814,6 +821,42 @@ class Node extends rclnodejs.ShadowNode {
     return subscription;
   }
 
+  /**
+   * Create a Subscription that returns an RxJS Observable.
+   * This allows using reactive programming patterns with ROS 2 messages.
+   *
+   * @param {function|string|object} typeClass - The ROS message class,
+   *      OR a string representing the message class, e.g. 'std_msgs/msg/String',
+   *      OR an object representing the message class, e.g. {package: 'std_msgs', type: 'msg', name: 'String'}
+   * @param {string} topic - The name of the topic.
+   * @param {object} [options] - The options argument used to parameterize the subscription.
+   * @param {boolean} [options.enableTypedArray=true] - The topic will use TypedArray if necessary.
+   * @param {QoS} [options.qos=QoS.profileDefault] - ROS Middleware "quality of service" settings.
+   * @param {boolean} [options.isRaw=false] - The topic is serialized when true.
+   * @param {string} [options.serializationMode='default'] - Controls message serialization format.
+   * @param {object} [options.contentFilter] - The content-filter (if supported by RMW).
+   * @param {SubscriptionEventCallbacks} [eventCallbacks] - The event callbacks for the subscription.
+   * @return {ObservableSubscription} - An ObservableSubscription with an RxJS Observable.
+   */
+  createObservableSubscription(typeClass, topic, options, eventCallbacks) {
+    let observableSubscription = null;
+
+    const subscription = this.createSubscription(
+      typeClass,
+      topic,
+      options,
+      (message) => {
+        if (observableSubscription) {
+          observableSubscription._emit(message);
+        }
+      },
+      eventCallbacks
+    );
+
+    observableSubscription = new ObservableSubscription(subscription);
+    return observableSubscription;
+  }
+
   /**
    * Create a Client.
    * @param {function|string|object} typeClass - The ROS message class,
@@ -1016,6 +1059,11 @@ class Node extends rclnodejs.ShadowNode {
 
     this.context.onNodeDestroyed(this);
 
+    if (this._enableRosout) {
+      rclnodejs.finiRosoutPublisherForNode(this.handle);
+      this._enableRosout = false;
+    }
+
     this.handle.release();
     this._clock = null;
     this._timers = [];
@@ -1349,6 +1397,74 @@ class Node extends rclnodejs.ShadowNode {
     );
   }
 
+  /**
+   * Return a list of clients on a given service.
+   *
+   * The returned parameter is a list of ServiceEndpointInfo objects, where each will contain
+   * the node name, node namespace, service type, service endpoint's GID, and its QoS profile.
+   *
+   * When the `no_mangle` parameter is `true`, the provided `service` should be a valid
+   * service name for the middleware (useful when combining ROS with native middleware (e.g. DDS)
+   * apps).  When the `no_mangle` parameter is `false`, the provided `service` should
+   * follow ROS service name conventions.
+   *
+   * `service` may be a relative, private, or fully qualified service name.
+   *  A relative or private service will be expanded using this node's namespace and name.
+   *  The queried `service` is not remapped.
+   *
+   * @param {string} service - The service on which to find the clients.
+   * @param {boolean} [noDemangle=false] - If `true`, `service` needs to be a valid middleware service
+   *                               name, otherwise it should be a valid ROS service name. Defaults to `false`.
+   * @returns {Array} - list of clients
+   */
+  getClientsInfoByService(service, noDemangle = false) {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+      console.warn(
+        'getClientsInfoByService is not supported by this version of ROS 2'
+      );
+      return null;
+    }
+    return rclnodejs.getClientsInfoByService(
+      this.handle,
+      this._getValidatedServiceName(service, noDemangle),
+      noDemangle
+    );
+  }
+
+  /**
+   * Return a list of servers on a given service.
+   *
+   * The returned parameter is a list of ServiceEndpointInfo objects, where each will contain
+   * the node name, node namespace, service type, service endpoint's GID, and its QoS profile.
+   *
+   * When the `no_mangle` parameter is `true`, the provided `service` should be a valid
+   * service name for the middleware (useful when combining ROS with native middleware (e.g. DDS)
+   * apps).  When the `no_mangle` parameter is `false`, the provided `service` should
+   * follow ROS service name conventions.
+   *
+   * `service` may be a relative, private, or fully qualified service name.
+   *  A relative or private service will be expanded using this node's namespace and name.
+   *  The queried `service` is not remapped.
+   *
+   * @param {string} service - The service on which to find the servers.
+   * @param {boolean} [noDemangle=false] - If `true`, `service` needs to be a valid middleware service
+   *                               name, otherwise it should be a valid ROS service name. Defaults to `false`.
+   * @returns {Array} - list of servers
+   */
+  getServersInfoByService(service, noDemangle = false) {
+    if (DistroUtils.getDistroId() < DistroUtils.DistroId.ROLLING) {
+      console.warn(
+        'getServersInfoByService is not supported by this version of ROS 2'
+      );
+      return null;
+    }
+    return rclnodejs.getServersInfoByService(
+      this.handle,
+      this._getValidatedServiceName(service, noDemangle),
+      noDemangle
+    );
+  }
+
   /**
    * Get the list of nodes discovered by the provided node.
    * @return {Array<string>} - An array of the names.
@@ -2142,6 +2258,22 @@ class Node extends rclnodejs.ShadowNode {
     validateFullTopicName(fqTopicName);
     return rclnodejs.remapTopicName(this.handle, fqTopicName);
   }
+
+  _getValidatedServiceName(serviceName, noDemangle) {
+    if (typeof serviceName !== 'string') {
+      throw new TypeValidationError('serviceName', serviceName, 'string', {
+        nodeName: this.name(),
+      });
+    }
+
+    if (noDemangle) {
+      return serviceName;
+    }
+
+    const resolvedServiceName = this.resolveServiceName(serviceName);
+    rclnodejs.validateTopicName(resolvedServiceName);
+    return resolvedServiceName;
+  }
 }
 
 /**