rclnodejs 1.5.2 → 1.7.0

package/types/node.d.ts

@@ -12,6 +12,11 @@ declare module 'rclnodejs' {
         name: string;
       };
 
+  /**
+   * Valid serialization modes for message conversion
+   */
+  type SerializationMode = 'default' | 'plain' | 'json';
+
   /**
    * A filter description similar to a SQL WHERE clause that limits
    * the data wanted by a Subscription.
@@ -56,6 +61,15 @@ declare module 'rclnodejs' {
      */
     isRaw?: boolean;
 
+    /**
+     * Controls message serialization format, default: 'default'.
+     *
+     * - 'default': Use native rclnodejs behavior (respects enableTypedArray setting)
+     * - 'plain': Convert TypedArrays to regular arrays
+     * - 'json': Fully JSON-safe (handles TypedArrays, BigInt, etc.)
+     */
+    serializationMode?: SerializationMode;
+
     /**
      * ROS Middleware "quality of service" setting, default: QoS.profileDefault.
      */
@@ -76,7 +90,8 @@ declare module 'rclnodejs' {
    *   enableTypedArray: true,
    *   qos: QoS.profileDefault,
    *   isRaw: false,
-   *   contentFilter: undefined
+   *   contentFilter: undefined,
+   *   serializationMode: 'default'
    * }
    * ```
    */
@@ -392,6 +407,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.
      *
@@ -439,6 +480,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.
      *

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

package/types/parameter_watcher.d.ts

@@ -0,0 +1,104 @@
+// 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' {
+  import { EventEmitter } from 'events';
+
+  /**
+   * Options for ParameterWatcher constructor.
+   */
+  export interface ParameterWatcherOptions {
+    /**
+     * Default timeout in milliseconds for service calls.
+     * @default 5000
+     */
+    timeout?: number;
+  }
+
+  /**
+   * ParameterWatcher - Watches parameter changes on a remote node.
+   *
+   * Subscribes to /parameter_events and emits 'change' events when
+   * watched parameters on the target node are modified.
+   */
+  class ParameterWatcher extends EventEmitter {
+    /**
+     * Get the remote node name being watched.
+     */
+    readonly remoteNodeName: string;
+
+    /**
+     * Get the list of watched parameter names.
+     */
+    readonly watchedParameters: string[];
+
+    /**
+     * Start watching for parameter changes.
+     * Waits for the remote node's parameter services and subscribes to parameter events.
+     *
+     * @param timeout - Timeout in milliseconds to wait for services.
+     * @returns Promise that resolves to true when watching has started.
+     */
+    start(timeout?: number): Promise<boolean>;
+
+    /**
+     * Get current values of all watched parameters.
+     *
+     * @param options - Optional request options (timeout, signal).
+     * @returns Promise that resolves to an array of Parameter objects.
+     */
+    getCurrentValues(options?: {
+      timeout?: number;
+      signal?: AbortSignal;
+    }): Promise<Parameter[]>;
+
+    /**
+     * Add a parameter name to the watch list.
+     *
+     * @param name - Parameter name to watch.
+     */
+    addParameter(name: string): void;
+
+    /**
+     * Remove a parameter name from the watch list.
+     *
+     * @param name - Parameter name to stop watching.
+     * @returns True if the parameter was in the watch list.
+     */
+    removeParameter(name: string): boolean;
+
+    /**
+     * Check if the watcher has been destroyed.
+     *
+     * @returns True if destroyed.
+     */
+    isDestroyed(): boolean;
+
+    /**
+     * Destroy the watcher and clean up resources.
+     * Unsubscribes from parameter events and destroys the parameter client.
+     */
+    destroy(): void;
+
+    /**
+     * Event emitted when watched parameters change.
+     *
+     * @event change
+     * @param params - Array of changed parameters (ParameterValue messages).
+     */
+    on(event: 'change', listener: (params: any[]) => void): this;
+    once(event: 'change', listener: (params: any[]) => void): this;
+    emit(event: 'change', params: any[]): boolean;
+  }
+}

package/rosidl_gen/templates/CMakeLists.dot

@@ -1,40 +0,0 @@
-# This file is automatically generated by Intel rclnodejs
-#
-# *** DO NOT EDIT directly
-
-cmake_minimum_required(VERSION 3.5)
-
-project({{=it.projectName}})
-
-# Default to C++14
-if(NOT CMAKE_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 14)
-endif()
-if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
-  # we dont use add_compile_options with pedantic in message packages
-  # because the Python C extensions dont comply with it
-  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -Wextra -Wpedantic")
-endif()
-
-{{~ it.dependencies :dependency}}
-find_package({{=dependency}} REQUIRED)
-{{~}}
-find_package(actionlib_msgs REQUIRED)
-find_package(ament_cmake REQUIRED)
-find_package(rosidl_default_generators REQUIRED)
-
-set(msg_files
-{{~ it.msgFiles :msgFile}}
-  "msg/{{=msgFile}}.msg"
-{{~}}
-)
-
-rosidl_generate_interfaces(${PROJECT_NAME}
-  ${msg_files}
-  {{~ it.dependencies :dependency}}
-  DEPENDENCIES {{=dependency}}
-  {{~}}
-  DEPENDENCIES actionlib_msgs
-)
-
-ament_package()

package/rosidl_gen/templates/action.dot

@@ -1,50 +0,0 @@
-// This file is automatically generated by rclnodejs
-//
-// *** DO NOT EDIT directly
-//
-
-'use strict';
-
-{{
-const className = it.actionInfo.pkgName + '__' + it.actionInfo.subFolder + '__' + it.actionInfo.interfaceName;
-}}
-
-class {{=className}} {
-  static get Goal() {
-    return require('./{{=className}}_Goal.js');
-  }
-
-  static get Result() {
-    return require('./{{=className}}_Result.js');
-  }
-
-  static get Feedback() {
-    return require('./{{=className}}_Feedback.js');
-  }
-
-  static get impl() {
-    return {
-      get SendGoalService() {
-        return require('./{{=className}}_SendGoal.js');
-      },
-      get GetResultService() {
-        return require('./{{=className}}_GetResult.js');
-      },
-      get FeedbackMessage() {
-        return require('./{{=className}}_FeedbackMessage.js');
-      },
-      get CancelGoal() {
-        return require('../action_msgs/action_msgs__srv__CancelGoal.js');
-      },
-      get GoalStatusArray() {
-        return require('../action_msgs/action_msgs__msg__GoalStatusArray.js');
-      }
-    };
-  }
-
-  static type() {
-    return {pkgName: '{{=it.actionInfo.pkgName}}', subFolder: '{{=it.actionInfo.subFolder}}', interfaceName: '{{=it.actionInfo.interfaceName}}'};
-  }
-}
-
-module.exports = {{=className}};