rclnodejs 1.6.0 → 1.8.0

package/types/clock_event.d.ts

@@ -0,0 +1,51 @@
+declare module 'rclnodejs' {
+  /**
+   * Class representing a ClockEvent in ROS
+   */
+  class ClockEvent {
+    /**
+     * Create a ClockEvent.
+     */
+    constructor();
+
+    /**
+     * Wait until a time specified by a steady clock.
+     * @param clock - The clock to use for time synchronization.
+     * @param until - The time to wait until.
+     * @returns A promise that resolves when the time is reached.
+     */
+    waitUntilSteady(clock: Clock, until: bigint): Promise<void>;
+
+    /**
+     * Wait until a time specified by a system clock.
+     * @param clock - The clock to use for time synchronization.
+     * @param until - The time to wait until.
+     * @returns A promise that resolves when the time is reached.
+     */
+    waitUntilSystem(clock: Clock, until: bigint): Promise<void>;
+
+    /**
+     * Wait until a time specified by a ROS clock.
+     * @param clock - The clock to use for time synchronization.
+     * @param until - The time to wait until.
+     * @returns A promise that resolves when the time is reached.
+     */
+    waitUntilRos(clock: Clock, until: bigint): Promise<void>;
+
+    /**
+     * Indicate if the ClockEvent is set.
+     * @returns True if the ClockEvent is set.
+     */
+    isSet(): boolean;
+
+    /**
+     * Set the event.
+     */
+    set(): void;
+
+    /**
+     * Clear the event.
+     */
+    clear(): void;
+  }
+}

package/types/errors.d.ts

@@ -0,0 +1,496 @@
+// 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' {
+  /**
+   * Options for RclNodeError constructor
+   */
+  export interface RclNodeErrorOptions {
+    /** Machine-readable error code (e.g., 'TIMEOUT', 'INVALID_ARGUMENT') */
+    code?: string;
+    /** Name of the node where error occurred */
+    nodeName?: string;
+    /** Type of entity (publisher, subscription, client, etc.) */
+    entityType?: string;
+    /** Name of the entity (topic name, service name, etc.) */
+    entityName?: string;
+    /** Original error that caused this error */
+    cause?: Error;
+    /** Additional error-specific details */
+    details?: any;
+  }
+
+  /**
+   * Base error class for all rclnodejs errors.
+   * Provides structured error information with context.
+   */
+  export class RclNodeError extends Error {
+    /** Error code for machine-readable error identification */
+    code: string;
+    /** Name of the node where error occurred */
+    nodeName?: string;
+    /** Type of entity (publisher, subscription, client, etc.) */
+    entityType?: string;
+    /** Name of the entity (topic name, service name, etc.) */
+    entityName?: string;
+    /** Additional error-specific details */
+    details?: any;
+    /** Original error that caused this error */
+    cause?: Error;
+    /** Timestamp when error was created */
+    timestamp: Date;
+
+    /**
+     * @param message - Human-readable error message
+     * @param options - Additional error context
+     */
+    constructor(message: string, options?: RclNodeErrorOptions);
+
+    /**
+     * Returns a detailed error object for logging/serialization
+     */
+    toJSON(): {
+      name: string;
+      message: string;
+      code: string;
+      nodeName?: string;
+      entityType?: string;
+      entityName?: string;
+      details?: any;
+      timestamp: string;
+      stack?: string;
+      cause?: any;
+    };
+
+    /**
+     * Returns a user-friendly error description
+     */
+    toString(): string;
+  }
+
+  /**
+   * Options for ValidationError constructor
+   */
+  export interface ValidationErrorOptions extends RclNodeErrorOptions {
+    /** Name of the argument that failed validation */
+    argumentName?: string;
+    /** The value that was provided */
+    providedValue?: any;
+    /** The expected type or format */
+    expectedType?: string;
+    /** The validation rule that failed */
+    validationRule?: string;
+  }
+
+  /**
+   * Error thrown when validation fails
+   */
+  export class ValidationError extends RclNodeError {
+    /** Name of the argument that failed validation */
+    argumentName?: string;
+    /** The value that was provided */
+    providedValue?: any;
+    /** The expected type or format */
+    expectedType?: string;
+    /** The validation rule that failed */
+    validationRule?: string;
+
+    /**
+     * @param message - Error message
+     * @param options - Additional options
+     */
+    constructor(message: string, options?: ValidationErrorOptions);
+  }
+
+  /**
+   * Type validation error
+   */
+  export class TypeValidationError extends ValidationError {
+    /**
+     * @param argumentName - Name of the argument
+     * @param providedValue - The value that was provided
+     * @param expectedType - The expected type
+     * @param options - Additional options
+     */
+    constructor(
+      argumentName: string,
+      providedValue: any,
+      expectedType: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Range/value validation error
+   */
+  export class RangeValidationError extends ValidationError {
+    /**
+     * @param argumentName - Name of the argument
+     * @param providedValue - The value that was provided
+     * @param constraint - The constraint that was violated
+     * @param options - Additional options
+     */
+    constructor(
+      argumentName: string,
+      providedValue: any,
+      constraint: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * A single validation issue found during message validation
+   */
+  export interface MessageValidationIssue {
+    /** Field path where issue occurred (e.g., 'linear.x' or 'data') */
+    field: string;
+    /** Problem type (UNKNOWN_FIELD, TYPE_MISMATCH, etc.) */
+    problem: string;
+    /** Expected type or value */
+    expected?: string;
+    /** Actual value received */
+    received?: any;
+  }
+
+  /**
+   * Message validation error for ROS message structure/type issues
+   */
+  export class MessageValidationError extends ValidationError {
+    /** The ROS message type (e.g., 'std_msgs/msg/String') */
+    messageType: string;
+    /** Array of validation issues found */
+    issues: MessageValidationIssue[];
+
+    /**
+     * @param messageType - The ROS message type
+     * @param issues - Array of validation issues
+     * @param options - Additional options
+     */
+    constructor(
+      messageType: string,
+      issues: MessageValidationIssue[],
+      options?: RclNodeErrorOptions
+    );
+
+    /**
+     * Get issues filtered by problem type
+     * @param problemType - Problem type to filter by
+     * @returns Filtered issues
+     */
+    getIssuesByType(problemType: string): MessageValidationIssue[];
+
+    /**
+     * Check if a specific field has validation issues
+     * @param fieldPath - Field path to check
+     * @returns True if field has issues
+     */
+    hasFieldIssue(fieldPath: string): boolean;
+  }
+
+  /**
+   * ROS name validation error (topics, nodes, services)
+   */
+  export class NameValidationError extends ValidationError {
+    /** Index where validation failed */
+    invalidIndex: number;
+    /** The validation error message */
+    validationResult: string;
+
+    /**
+     * @param name - The invalid name
+     * @param nameType - Type of name (node, topic, service, etc.)
+     * @param validationResult - The validation error message
+     * @param invalidIndex - Index where validation failed
+     * @param options - Additional options
+     */
+    constructor(
+      name: string,
+      nameType: string,
+      validationResult: string,
+      invalidIndex: number,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Base class for operation/runtime errors
+   */
+  export class OperationError extends RclNodeError {
+    /**
+     * @param message - Error message
+     * @param options - Additional options
+     */
+    constructor(message: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Request timeout error
+   */
+  export class TimeoutError extends OperationError {
+    /** Timeout duration in milliseconds */
+    timeout: number;
+    /** Type of operation that timed out */
+    operationType: string;
+
+    /**
+     * @param operationType - Type of operation that timed out
+     * @param timeoutMs - Timeout duration in milliseconds
+     * @param options - Additional options
+     */
+    constructor(
+      operationType: string,
+      timeoutMs: number,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Request abortion error
+   */
+  export class AbortError extends OperationError {
+    /** Type of operation that was aborted */
+    operationType: string;
+    /** Reason for abortion */
+    abortReason?: string;
+
+    /**
+     * @param operationType - Type of operation that was aborted
+     * @param reason - Reason for abortion
+     * @param options - Additional options
+     */
+    constructor(
+      operationType: string,
+      reason?: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Service not available error
+   */
+  export class ServiceNotFoundError extends OperationError {
+    /** Name of the service */
+    serviceName: string;
+
+    /**
+     * @param serviceName - Name of the service
+     * @param options - Additional options
+     */
+    constructor(serviceName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Remote node not found error
+   */
+  export class NodeNotFoundError extends OperationError {
+    /** Name of the target node */
+    targetNodeName: string;
+
+    /**
+     * @param nodeName - Name of the node
+     * @param options - Additional options
+     */
+    constructor(nodeName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Base error for parameter operations
+   */
+  export class ParameterError extends RclNodeError {
+    /** Name of the parameter */
+    parameterName: string;
+
+    /**
+     * @param message - Error message
+     * @param parameterName - Name of the parameter
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      parameterName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Parameter not found error
+   */
+  export class ParameterNotFoundError extends ParameterError {
+    /**
+     * @param parameterName - Name of the parameter
+     * @param nodeName - Name of the node
+     * @param options - Additional options
+     */
+    constructor(
+      parameterName: string,
+      nodeName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Parameter type mismatch error
+   */
+  export class ParameterTypeError extends ParameterError {
+    /** Expected parameter type */
+    expectedType: string;
+    /** Actual parameter type */
+    actualType: string;
+
+    /**
+     * @param parameterName - Name of the parameter
+     * @param expectedType - Expected parameter type
+     * @param actualType - Actual parameter type
+     * @param options - Additional options
+     */
+    constructor(
+      parameterName: string,
+      expectedType: string,
+      actualType: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Read-only parameter modification error
+   */
+  export class ReadOnlyParameterError extends ParameterError {
+    /**
+     * @param parameterName - Name of the parameter
+     * @param options - Additional options
+     */
+    constructor(parameterName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Base error for topic operations
+   */
+  export class TopicError extends RclNodeError {
+    /** Name of the topic */
+    topicName: string;
+
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Publisher-specific error
+   */
+  export class PublisherError extends TopicError {
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Subscription-specific error
+   */
+  export class SubscriptionError extends TopicError {
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Base error for action operations
+   */
+  export class ActionError extends RclNodeError {
+    /** Name of the action */
+    actionName: string;
+
+    /**
+     * @param message - Error message
+     * @param actionName - Name of the action
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      actionName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Goal rejected by action server
+   */
+  export class GoalRejectedError extends ActionError {
+    /** ID of the rejected goal */
+    goalId: string;
+
+    /**
+     * @param actionName - Name of the action
+     * @param goalId - ID of the rejected goal
+     * @param options - Additional options
+     */
+    constructor(
+      actionName: string,
+      goalId: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Action server not found
+   */
+  export class ActionServerNotFoundError extends ActionError {
+    /**
+     * @param actionName - Name of the action
+     * @param options - Additional options
+     */
+    constructor(actionName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Wraps errors from native C++ layer with additional context
+   */
+  export class NativeError extends RclNodeError {
+    /** Error message from C++ layer */
+    nativeMessage: string;
+    /** Operation that failed */
+    operation: string;
+
+    /**
+     * @param nativeMessage - Error message from C++ layer
+     * @param operation - Operation that failed
+     * @param options - Additional options
+     */
+    constructor(
+      nativeMessage: string,
+      operation: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+}

package/types/index.d.ts

@@ -1,4 +1,7 @@
 /// <reference path="./base.d.ts" />
+/// <reference path="./clock_event.d.ts" />
+/// <reference path="./clock_change.d.ts" />
+/// <reference path="./message_validation.d.ts" />
 
 import { ChildProcess } from 'child_process';
 
@@ -58,6 +61,13 @@ declare module 'rclnodejs' {
    */
   function init(context?: Context, argv?: string[]): Promise<void>;
 
+  /**
+   * Remove ROS-specific arguments from the given argument list.
+   * @param argv - The argument list to process.
+   * @returns The argument list with ROS arguments removed.
+   */
+  function removeROSArgs(argv: string[]): string[];
+
   /**
    * Start detection and processing of units of work.
    *

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;
+    };
+  }
+}