rclnodejs 1.7.0 → 1.8.0

package/types/logging.d.ts

@@ -77,6 +77,19 @@ declare module 'rclnodejs' {
      */
     readonly name: string;
 
+    /**
+     * Create a child logger.
+     *
+     * @param name - name of the child logger.
+     * @returns The child logger object.
+     */
+    getChild(name: string): Logging;
+
+    /**
+     * Destroy the logger and remove it from the parent logger if it is a child logger.
+     */
+    destroy(): void;
+
     /**
      * Create a logger by name.
      *
@@ -84,6 +97,25 @@ declare module 'rclnodejs' {
      * @returns New logger.
      */
     static getLogger(name: string): Logging;
+
+    /**
+     * Configure the logging system with the given context.
+     *
+     * @param context - The context to configure logging for.
+     */
+    static configure(context: Context): void;
+
+    /**
+     * Shutdown the logging system.
+     */
+    static shutdown(): void;
+
+    /**
+     * Get the logging directory.
+     *
+     * @returns The logging directory.
+     */
+    static getLoggingDirectory(): string;
   }
 
   namespace Logging {

package/types/message_introspector.d.ts

@@ -0,0 +1,75 @@
+declare module 'rclnodejs' {
+  /**
+   * A utility class for inspecting ROS 2 message structure without using loader.loadInterface directly.
+   * Provides access to message schema, field names, and default values.
+   */
+  export class MessageIntrospector<T = any> {
+    /**
+     * Create a new MessageIntrospector for a ROS 2 message type.
+     * @param 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: string);
+
+    /**
+     * Get the full message type name.
+     */
+    readonly typeName: string;
+
+    /**
+     * Get the underlying ROS message class.
+     */
+    readonly typeClass: new () => T;
+
+    /**
+     * Get the field names of the message.
+     */
+    readonly fields: string[];
+
+    /**
+     * Get the ROSMessageDef schema for the message type.
+     */
+    readonly schema: 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.
+     */
+    readonly defaults: T;
+  }
+
+  /**
+   * ROSMessageDef schema structure.
+   */
+  interface ROSMessageDef {
+    constants: Array<{
+      name: string;
+      type: string;
+      value: any;
+    }>;
+    fields: Array<{
+      name: string;
+      type: {
+        isPrimitiveType: boolean;
+        type: string;
+        pkgName: string | null;
+        isArray: boolean;
+        isDynamicArray: boolean;
+        isFixedSizeArray: boolean | null;
+        arraySize: number | null;
+        stringUpperBound: number | null;
+        isUpperBound: boolean;
+      };
+      default_value: any;
+    }>;
+    msgName: string;
+    baseType: {
+      pkgName: string;
+      type: string;
+      stringUpperBound: number | null;
+      isPrimitiveType: boolean;
+    };
+  }
+}

package/types/message_validation.d.ts

@@ -0,0 +1,183 @@
+// 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.
+
+declare module 'rclnodejs' {
+  /**
+   * Validation issue problem types
+   */
+  export const ValidationProblem: {
+    /** Field exists in object but not in message schema */
+    readonly UNKNOWN_FIELD: 'UNKNOWN_FIELD';
+    /** Field type doesn't match expected type */
+    readonly TYPE_MISMATCH: 'TYPE_MISMATCH';
+    /** Required field is missing */
+    readonly MISSING_FIELD: 'MISSING_FIELD';
+    /** Array length constraint violated */
+    readonly ARRAY_LENGTH: 'ARRAY_LENGTH';
+    /** Value is out of valid range */
+    readonly OUT_OF_RANGE: 'OUT_OF_RANGE';
+    /** Nested message validation failed */
+    readonly NESTED_ERROR: 'NESTED_ERROR';
+  };
+
+  /**
+   * Field type information from message schema
+   */
+  export interface MessageFieldType {
+    /** The type name (e.g., 'string', 'float64', 'Vector3') */
+    type: string;
+    /** Whether this is a primitive ROS type */
+    isPrimitiveType: boolean;
+    /** Whether this field is an array */
+    isArray: boolean;
+    /** For fixed-size arrays, the required size */
+    arraySize?: number;
+    /** Whether this is a fixed-size array */
+    isFixedSizeArray: boolean;
+    /** Whether this has an upper bound (bounded sequence) */
+    isUpperBound: boolean;
+    /** Whether this is a dynamic array */
+    isDynamicArray: boolean;
+    /** Package name for non-primitive types */
+    pkgName?: string;
+    /** String upper bound for bounded strings */
+    stringUpperBound?: number;
+  }
+
+  /**
+   * Field definition from message schema
+   */
+  export interface MessageField {
+    /** Field name */
+    name: string;
+    /** Field type information */
+    type: MessageFieldType;
+    /** Default value if any */
+    default_value?: any;
+  }
+
+  /**
+   * Constant definition from message schema
+   */
+  export interface MessageConstant {
+    /** Constant name */
+    name: string;
+    /** Constant type */
+    type: string;
+    /** Constant value */
+    value: any;
+  }
+
+  /**
+   * Message schema definition
+   */
+  export interface MessageSchema {
+    /** Array of field definitions */
+    fields: MessageField[];
+    /** Array of constant definitions */
+    constants: MessageConstant[];
+    /** Full message type string (e.g., 'std_msgs/msg/String') */
+    messageType: string;
+    /** Base type information */
+    baseType?: {
+      pkgName: string;
+      type: string;
+      isPrimitiveType: boolean;
+    };
+  }
+
+  /**
+   * Options for message validation
+   */
+  export interface MessageValidationOptions {
+    /** If true, unknown fields cause validation failure (default: false) */
+    strict?: boolean;
+    /** If true, validate field types (default: true) */
+    checkTypes?: boolean;
+    /** If true, check for missing fields (default: false) */
+    checkRequired?: boolean;
+  }
+
+  /**
+   * Result of message validation
+   */
+  export interface MessageValidationResult {
+    /** Whether the message is valid */
+    valid: boolean;
+    /** Array of validation issues found */
+    issues: MessageValidationIssue[];
+  }
+
+  /**
+   * Get the schema definition for a message type
+   * @param typeClass - Message type class or identifier
+   * @returns Schema definition with fields and constants, or null if not found
+   */
+  export function getMessageSchema(typeClass: TypeClass): MessageSchema | null;
+
+  /**
+   * Get field names for a message type
+   * @param typeClass - Message type class or identifier
+   * @returns Array of field names
+   */
+  export function getFieldNames(typeClass: TypeClass): string[];
+
+  /**
+   * Get type information for a specific field
+   * @param typeClass - Message type class or identifier
+   * @param fieldName - Name of the field
+   * @returns Field type information or null if not found
+   */
+  export function getFieldType(
+    typeClass: TypeClass,
+    fieldName: string
+  ): MessageFieldType | null;
+
+  /**
+   * Validate a message object against its schema
+   * @param obj - Plain object to validate
+   * @param typeClass - Message type class or identifier
+   * @param options - Validation options
+   * @returns Validation result with valid flag and issues array
+   */
+  export function validateMessage(
+    obj: any,
+    typeClass: TypeClass,
+    options?: MessageValidationOptions
+  ): MessageValidationResult;
+
+  /**
+   * Validate a message and throw if invalid
+   * @param obj - Plain object to validate
+   * @param typeClass - Message type class or identifier
+   * @param options - Validation options
+   * @throws MessageValidationError if validation fails
+   */
+  export function assertValidMessage(
+    obj: any,
+    typeClass: TypeClass,
+    options?: MessageValidationOptions
+  ): void;
+
+  /**
+   * Create a validator function for a specific message type
+   * @param typeClass - Message type class or identifier
+   * @param defaultOptions - Default validation options
+   * @returns Validator function that takes (obj, options?) and returns validation result
+   */
+  export function createMessageValidator(
+    typeClass: TypeClass,
+    defaultOptions?: MessageValidationOptions
+  ): (obj: any, options?: MessageValidationOptions) => MessageValidationResult;
+}

package/types/node.d.ts

@@ -363,6 +363,23 @@ declare module 'rclnodejs' {
       eventCallbacks?: (event: object) => void
     ): Subscription;
 
+    /**
+     * Create a Subscription that returns an RxJS Observable.
+     * This allows using reactive programming patterns with ROS 2 messages.
+     *
+     * @param typeClass - Type of ROS messages the subscription will subscribe to.
+     * @param topic - Name of the topic the subscription will subscribe to.
+     * @param options - Configuration options, see DEFAULT_OPTIONS.
+     * @param eventCallbacks - Optional event callbacks for the subscription.
+     * @returns An ObservableSubscription with an RxJS Observable.
+     */
+    createObservableSubscription<T extends TypeClass<MessageTypeClassName>>(
+      typeClass: T,
+      topic: string,
+      options?: Options,
+      eventCallbacks?: (event: object) => void
+    ): ObservableSubscription<MessageType<T>>;
+
     /**
      * Create a Client for making server requests.
      *
@@ -851,6 +868,56 @@ declare module 'rclnodejs' {
       noDemangle: boolean
     ): Array<object>;
 
+    /**
+     * 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 service - The service on which to find the clients.
+     * @param [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 An array of clients.
+     */
+    getClientsInfoByService(
+      service: string,
+      noDemangle: boolean
+    ): Array<object>;
+
+    /**
+     * 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 service - The service on which to find the servers.
+     * @param [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 An array of servers.
+     */
+    getServersInfoByService(
+      service: string,
+      noDemangle: boolean
+    ): Array<object>;
+
     /**
      * Get the list of nodes discovered by the provided node.
      *

package/types/node_options.d.ts

@@ -32,6 +32,19 @@ declare module 'rclnodejs' {
      */
     automaticallyDeclareParametersFromOverrides: boolean;
 
+    /**
+     * A flag controlling the startup of the rosout logging.
+     * When true a node will start the rosout logging.
+     * Default value = true;
+     * @returns {boolean} -
+     */
+    enableRosout: boolean;
+
+    /**
+     * The QoS profile for the rosout publisher.
+     */
+    rosoutQos: QoS | QoS.ProfileRef;
+
     /**
      * An instance configured with default values.
      */

package/types/observable_subscription.d.ts

@@ -0,0 +1,39 @@
+declare module 'rclnodejs' {
+  /**
+   * A wrapper that provides RxJS Observable support for ROS 2 subscriptions.
+   * This class wraps a standard Subscription and emits messages through an Observable.
+   */
+  class ObservableSubscription<T = any> {
+    /**
+     * Get the RxJS Observable for this subscription.
+     * Use this to pipe operators and subscribe to messages.
+     */
+    readonly observable: import('rxjs').Observable<T>;
+
+    /**
+     * Get the underlying ROS 2 subscription.
+     */
+    readonly subscription: Subscription;
+
+    /**
+     * Get the topic name.
+     */
+    readonly topic: string;
+
+    /**
+     * Check if this observable subscription has been destroyed.
+     */
+    readonly isDestroyed: boolean;
+
+    /**
+     * Complete the observable and clean up resources.
+     * After calling this, no more messages will be emitted.
+     */
+    complete(): void;
+
+    /**
+     * Alias for complete() for consistency with RxJS naming.
+     */
+    destroy(): void;
+  }
+}

package/types/publisher.d.ts

@@ -1,4 +1,12 @@
 declare module 'rclnodejs' {
+  /**
+   * Options for publishing a message
+   */
+  interface PublishOptions {
+    /** Override validateMessages setting for this publish call */
+    validate?: boolean;
+  }
+
   /**
    * A ROS Publisher that publishes messages on a topic.
    */
@@ -8,12 +16,26 @@ declare module 'rclnodejs' {
      * Topic on which messages are published.
      */
     readonly topic: string;
+
+    /**
+     * Whether messages will be validated before publishing.
+     */
+    willValidateMessage: boolean;
+
     /**
      * Publish a message
      *
      * @param message - The message to be sent.
+     * @param options - Publish options (e.g., { validate: true })
+     * @throws MessageValidationError if validation is enabled and message is invalid
+     */
+    publish(message: MessageType<T> | Buffer, options?: PublishOptions): void;
+
+    /**
+     * Set validation options for this publisher.
+     * @param options - Validation options
      */
-    publish(message: MessageType<T> | Buffer): void;
+    setValidation(options: MessageValidationOptions): void;
 
     /**
      * Get the number of subscriptions to this publisher.
@@ -38,6 +60,11 @@ declare module 'rclnodejs' {
      */
     waitForAllAcked(timeout: bigint): boolean;
 
+    /**
+     * Manually assert that this Publisher is alive (for RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC).
+     */
+    assertLiveliness(): void;
+
     /**
      * Get the logger name for this publisher.
      */

package/types/qos.d.ts

@@ -11,6 +11,7 @@ declare module 'rclnodejs' {
      * @param depth - The depth value, default = 0.
      * @param reliability - The reliability value, default = RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT
      * @param durability - The durability value, default = RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT
+     * @param liveliness - The liveliness value, default = RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT
      * @param avoidRosNameSpaceConventions - The avoidRosNameSpaceConventions value, default = false.
      */
     constructor(
@@ -18,6 +19,7 @@ declare module 'rclnodejs' {
       depth?: number,
       reliability?: QoS.ReliabilityPolicy,
       durability?: QoS.DurabilityPolicy,
+      liveliness?: QoS.LivelinessPolicy,
       avoidRosNameSpaceConventions?: boolean
     );
 
@@ -41,6 +43,11 @@ declare module 'rclnodejs' {
      */
     durability: QoS.DurabilityPolicy;
 
+    /**
+     * Get the liveliness value.
+     */
+    liveliness: QoS.LivelinessPolicy;
+
     /**
      * Get the avoidRosNameSpaceConventions value.
      */
@@ -115,5 +122,16 @@ declare module 'rclnodejs' {
       RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL = 1,
       RMW_QOS_POLICY_DURABILITY_VOLATILE = 2,
     }
+
+    /**
+     * LivelinessPolicy
+     */
+    enum LivelinessPolicy {
+      RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT = 0,
+      RMW_QOS_POLICY_LIVELINESS_AUTOMATIC = 1,
+      RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC = 3,
+      RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 4,
+      RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5,
+    }
   }
 }

package/types/subscription.d.ts

@@ -61,6 +61,12 @@ declare module 'rclnodejs' {
      */
     setContentFilter(filter: SubscriptionContentFilter): boolean;
 
+    /**
+     * Get the current content-filter.
+     * @returns The content-filter description {expression: string, parameters: string[]} or undefined if not set/supported.
+     */
+    getContentFilter(): SubscriptionContentFilter | undefined;
+
     /**
      * Clear the current content-filter. No filtering is to be applied.
      * @returns True if successful; false otherwise

package/types/timer.d.ts

@@ -46,6 +46,13 @@ declare module 'rclnodejs' {
      */
     timeUntilNextCall(): bigint;
 
+    /**
+     * Get the absolute time in nanoseconds when the next callback is due.
+     *
+     * @returns The next call time in nanoseconds, or null if the timer is canceled.
+     */
+    getNextCallTime(): bigint | null;
+
     /**
      * Change the timer period.
      * @param period - The new period in nanoseconds.
@@ -58,6 +65,17 @@ declare module 'rclnodejs' {
      */
     timerPeriod(): bigint;
 
+    /**
+     * Set the on reset callback.
+     * @param callback - The callback to be called when the timer is reset.
+     */
+    setOnResetCallback(callback: (events: number) => void): void;
+
+    /**
+     * Clear the on reset callback.
+     */
+    clearOnResetCallback(): void;
+
     /**
      * Call a timer and starts counting again, retrieves actual and expected call time.
      * @return - The timer information.

package/types/validator.d.ts

@@ -0,0 +1,86 @@
+// 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.
+
+declare module 'rclnodejs' {
+  /**
+   * Validator for ROS 2 names (topics, services, nodes, namespaces).
+   */
+  namespace validator {
+    /**
+     * Validate a fully-qualified topic or service name.
+     * The name must be fully-qualified and already expanded.
+     * @param topic - The topic/service name to validate.
+     * @returns Always returns true if valid.
+     * @throws TypeValidationError if topic is not a string.
+     * @throws NameValidationError if the name is invalid.
+     */
+    function validateFullTopicName(topic: string): true;
+
+    /**
+     * Check if a fully-qualified topic name is valid without throwing.
+     * @param topic - The topic/service name to check.
+     * @returns True if valid, false otherwise.
+     */
+    function isValidFullTopicName(topic: string): boolean;
+
+    /**
+     * Validate a node name.
+     * @param name - The node name to validate.
+     * @returns Always returns true if valid.
+     * @throws TypeValidationError if name is not a string.
+     * @throws NameValidationError if the name is invalid.
+     */
+    function validateNodeName(name: string): true;
+
+    /**
+     * Check if a node name is valid without throwing.
+     * @param name - The node name to check.
+     * @returns True if valid, false otherwise.
+     */
+    function isValidNodeName(name: string): boolean;
+
+    /**
+     * Validate a topic or service name.
+     * The name does not have to be fully-qualified and is not expanded.
+     * @param topic - The topic/service name to validate.
+     * @returns Always returns true if valid.
+     * @throws TypeValidationError if topic is not a string.
+     * @throws NameValidationError if the name is invalid.
+     */
+    function validateTopicName(topic: string): true;
+
+    /**
+     * Check if a topic name is valid without throwing.
+     * @param topic - The topic/service name to check.
+     * @returns True if valid, false otherwise.
+     */
+    function isValidTopicName(topic: string): boolean;
+
+    /**
+     * Validate a namespace.
+     * @param namespace - The namespace to validate.
+     * @returns Always returns true if valid.
+     * @throws TypeValidationError if namespace is not a string.
+     * @throws NameValidationError if the namespace is invalid.
+     */
+    function validateNamespace(namespace: string): true;
+
+    /**
+     * Check if a namespace is valid without throwing.
+     * @param namespace - The namespace to check.
+     * @returns True if valid, false otherwise.
+     */
+    function isValidNamespace(namespace: string): boolean;
+  }
+}