rclnodejs 1.6.0 → 1.8.0

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.
      *
@@ -407,6 +424,32 @@ declare module 'rclnodejs' {
       callback: ServiceRequestHandler<T>
     ): ServiceType<T>;
 
+    /**
+     * Create a ParameterClient for accessing parameters on a remote node.
+     *
+     * @param remoteNodeName - The name of the remote node whose parameters to access.
+     * @param options - Options for parameter client.
+     * @returns An instance of ParameterClient.
+     */
+    createParameterClient(
+      remoteNodeName: string,
+      options?: { timeout?: number }
+    ): ParameterClient;
+
+    /**
+     * Create a ParameterWatcher for watching parameter changes on a remote node.
+     *
+     * @param remoteNodeName - The name of the remote node whose parameters to watch.
+     * @param parameterNames - Array of parameter names to watch.
+     * @param options - Options for parameter watcher.
+     * @returns An instance of ParameterWatcher.
+     */
+    createParameterWatcher(
+      remoteNodeName: string,
+      parameterNames: string[],
+      options?: { timeout?: number }
+    ): ParameterWatcher;
+
     /**
      * Create a guard condition.
      *
@@ -454,6 +497,20 @@ declare module 'rclnodejs' {
      */
     destroyService(service: Service): void;
 
+    /**
+     * Destroy a ParameterClient.
+     *
+     * @param parameterClient - ParameterClient to be destroyed.
+     */
+    destroyParameterClient(parameterClient: ParameterClient): void;
+
+    /**
+     * Destroy a ParameterWatcher.
+     *
+     * @param watcher - ParameterWatcher to be destroyed.
+     */
+    destroyParameterWatcher(watcher: ParameterWatcher): void;
+
     /**
      * Destroy a Timer.
      *
@@ -811,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/parameter_client.d.ts

@@ -0,0 +1,252 @@
+// 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 ParameterClient constructor.
+   */
+  export interface ParameterClientOptions {
+    /**
+     * Default timeout in milliseconds for service calls.
+     * @default 5000
+     */
+    timeout?: number;
+  }
+
+  /**
+   * Options for parameter service calls.
+   */
+  export interface ParameterServiceCallOptions {
+    /**
+     * Timeout in milliseconds for this specific call.
+     */
+    timeout?: number;
+
+    /**
+     * AbortSignal to cancel the request.
+     */
+    signal?: AbortSignal;
+  }
+
+  /**
+   * Result of a parameter set operation.
+   */
+  export interface ParameterSetResult {
+    /**
+     * The name of the parameter.
+     */
+    name: string;
+
+    /**
+     * Whether the operation was successful.
+     */
+    successful: boolean;
+
+    /**
+     * Reason message, typically populated on failure.
+     */
+    reason: string;
+  }
+
+  /**
+   * Result of a list parameters operation.
+   */
+  export interface ListParametersResult {
+    /**
+     * Array of parameter names found.
+     */
+    names: string[];
+
+    /**
+     * Array of parameter prefixes found.
+     */
+    prefixes: string[];
+  }
+
+  /**
+   * Options for listing parameters.
+   */
+  export interface ListParametersOptions extends ParameterServiceCallOptions {
+    /**
+     * Optional array of parameter name prefixes to filter by.
+     */
+    prefixes?: string[];
+
+    /**
+     * Depth of parameter namespace to list.
+     * @default 0 (unlimited)
+     */
+    depth?: number;
+  }
+
+  /**
+   * Parameter to set with name and value.
+   */
+  export interface ParameterToSet {
+    /**
+     * The name of the parameter.
+     */
+    name: string;
+
+    /**
+     * The value to set. Type is automatically inferred.
+     */
+    value: any;
+  }
+
+  /**
+   * Class for accessing parameters on remote ROS 2 nodes.
+   *
+   * Provides promise-based APIs to get, set, list, and describe parameters
+   * on other nodes in the ROS 2 system.
+   */
+  export class ParameterClient {
+    /**
+     * Create a new ParameterClient for accessing parameters on a remote node.
+     *
+     * @param node - The node to use for creating service clients.
+     * @param remoteNodeName - The name of the remote node whose parameters to access.
+     * @param options - Optional configuration for the parameter client.
+     * @throws {TypeError} If node is not provided or remoteNodeName is not a valid string.
+     * @throws {Error} If remoteNodeName is not a valid ROS node name.
+     */
+    constructor(
+      node: Node,
+      remoteNodeName: string,
+      options?: ParameterClientOptions
+    );
+
+    /**
+     * Get the name of the remote node this client is connected to.
+     */
+    readonly remoteNodeName: string;
+
+    /**
+     * Get a single parameter from the remote node.
+     *
+     * @param name - The name of the parameter to retrieve.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with the Parameter object.
+     * @throws {Error} If the parameter is not found or service call fails.
+     */
+    getParameter(
+      name: string,
+      options?: ParameterServiceCallOptions
+    ): Promise<Parameter>;
+
+    /**
+     * Get multiple parameters from the remote node.
+     *
+     * @param names - Array of parameter names to retrieve.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with an array of Parameter objects.
+     * @throws {Error} If the service call fails.
+     * @throws {TypeError} If names is not a non-empty array.
+     */
+    getParameters(
+      names: string[],
+      options?: ParameterServiceCallOptions
+    ): Promise<Parameter[]>;
+
+    /**
+     * Set a single parameter on the remote node.
+     *
+     * @param name - The name of the parameter to set.
+     * @param value - The value to set. Type is automatically inferred.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with the result.
+     * @throws {Error} If the service call fails.
+     */
+    setParameter(
+      name: string,
+      value: any,
+      options?: ParameterServiceCallOptions
+    ): Promise<ParameterSetResult>;
+
+    /**
+     * Set multiple parameters on the remote node.
+     *
+     * @param parameters - Array of parameter objects with name and value.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with an array of results.
+     * @throws {Error} If the service call fails.
+     * @throws {TypeError} If parameters is not a non-empty array.
+     */
+    setParameters(
+      parameters: ParameterToSet[],
+      options?: ParameterServiceCallOptions
+    ): Promise<ParameterSetResult[]>;
+
+    /**
+     * List all parameters available on the remote node.
+     *
+     * @param options - Optional filters, depth, timeout and abort signal.
+     * @returns Promise that resolves with parameter names and prefixes.
+     * @throws {Error} If the service call fails.
+     */
+    listParameters(
+      options?: ListParametersOptions
+    ): Promise<ListParametersResult>;
+
+    /**
+     * Describe parameters on the remote node.
+     *
+     * @param names - Array of parameter names to describe.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with an array of parameter descriptors.
+     * @throws {Error} If the service call fails.
+     * @throws {TypeError} If names is not a non-empty array.
+     */
+    describeParameters(
+      names: string[],
+      options?: ParameterServiceCallOptions
+    ): Promise<any[]>;
+
+    /**
+     * Get the types of parameters on the remote node.
+     *
+     * @param names - Array of parameter names.
+     * @param options - Optional timeout and abort signal.
+     * @returns Promise that resolves with an array of parameter types.
+     * @throws {Error} If the service call fails.
+     * @throws {TypeError} If names is not a non-empty array.
+     */
+    getParameterTypes(
+      names: string[],
+      options?: ParameterServiceCallOptions
+    ): Promise<ParameterType[]>;
+
+    /**
+     * Wait for the parameter services to be available on the remote node.
+     * This is useful to verify the remote node is running before making calls.
+     *
+     * @param timeout - Optional timeout in milliseconds.
+     * @returns Promise that resolves to true if services are available.
+     */
+    waitForService(timeout?: number): Promise<boolean>;
+
+    /**
+     * Check if the parameter client has been destroyed.
+     *
+     * @returns True if destroyed, false otherwise.
+     */
+    isDestroyed(): boolean;
+
+    /**
+     * Destroy the parameter client and clean up all service clients.
+     * After calling this method, the client cannot be used anymore.
+     */
+    destroy(): void;
+  }
+}