rclnodejs 1.6.0 → 1.8.0

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