rclnodejs 1.8.3 → 1.9.0

package/tools/jsdoc/tmpl/tutorial.tmpl

@@ -0,0 +1,19 @@
+<section class="doc-section prose-section tutorial-section">
+
+<header class="doc-page-header">
+    <?js if (children.length > 0) { ?>
+    <ul class="tutorial-children"><?js
+        var self = this;
+        children.forEach(function(t) { ?>
+        <li><?js= self.tutoriallink(t.name) ?></li>
+    <?js }); ?></ul>
+    <?js } ?>
+
+    <h2 class="doc-heading"><?js= header ?></h2>
+</header>
+
+<article class="prose-card">
+    <?js= content ?>
+</article>
+
+</section>

package/tools/jsdoc/tmpl/type.tmpl

@@ -0,0 +1,7 @@
+<?js
+    var data = obj;
+    var self = this;
+    data.forEach(function(name, i) { ?>
+<span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>
+<?js if (i < data.length-1) { ?>|<?js } ?>
+<?js }); ?>

package/types/action_client.d.ts

@@ -142,6 +142,14 @@ declare module 'rclnodejs' {
       options?: Options<ActionQoS> & {
         validateGoals?: boolean;
         validationOptions?: MessageValidationOptions;
+        /**
+         * Enable feedback subscription content filter to optimize the handling
+         * of feedback messages. When enabled, the content filter is used to
+         * configure the goal ID for the subscription, avoiding reception of
+         * irrelevant feedback messages. An action client can handle up to 6
+         * goals simultaneously with this optimization. Default: false.
+         */
+        enableFeedbackMsgOptimization?: boolean;
       }
     );
 

package/types/index.d.ts

@@ -2,6 +2,8 @@
 /// <reference path="./clock_event.d.ts" />
 /// <reference path="./clock_change.d.ts" />
 /// <reference path="./message_validation.d.ts" />
+/// <reference path="./parameter_event_handler.d.ts" />
+/// <reference path="./message_info.d.ts" />
 
 import { ChildProcess } from 'child_process';
 
@@ -85,6 +87,38 @@ declare module 'rclnodejs' {
    * @deprecated since 0.18.0, Use Node.spinOnce(timeout)*/
   function spinOnce(node: Node, timeout?: number): void;
 
+  /**
+   * Options for waitForMessage.
+   */
+  interface WaitForMessageOptions {
+    /** Timeout in milliseconds. If omitted, waits indefinitely. */
+    timeout?: number;
+    /** QoS profile for the temporary subscription. */
+    qos?: QoS;
+  }
+
+  /**
+   * Wait for a single message on a topic.
+   *
+   * Creates a temporary subscription, waits for the first message to arrive,
+   * and returns it. The node must be spinning before calling this function.
+   *
+   * This is the rclnodejs equivalent of rclpy's `wait_for_message`.
+   *
+   * @param typeClass - The ROS message type class.
+   * @param node - The node to create the temporary subscription on.
+   * @param topic - The topic name to listen on.
+   * @param options - Options including timeout and QoS.
+   * @returns Resolves with the received message.
+   * @throws Error if timeout expires before a message arrives.
+   */
+  function waitForMessage<T extends TypeClass<MessageTypeClassName>>(
+    typeClass: T,
+    node: Node,
+    topic: string,
+    options?: WaitForMessageOptions
+  ): Promise<MessageType<T>>;
+
   /**
    * Stop all activity, destroy all nodes and node components.
    *

package/types/message_info.d.ts

@@ -0,0 +1,72 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// 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' {
+  /**
+   * Contains metadata about a received message, including timestamps,
+   * sequence numbers, and the publisher's globally unique identifier (GID).
+   *
+   * Passed as the second argument to subscription callbacks when the
+   * callback accepts two parameters.
+   *
+   * @example
+   * ```typescript
+   * node.createSubscription(
+   *   'std_msgs/msg/String',
+   *   'topic',
+   *   (msg: rclnodejs.std_msgs.msg.String, info: MessageInfo) => {
+   *     console.log('Source timestamp:', info.sourceTimestamp);
+   *   }
+   * );
+   * ```
+   */
+  class MessageInfo {
+    /**
+     * The timestamp when the message was published (nanoseconds since epoch).
+     */
+    readonly sourceTimestamp: bigint;
+
+    /**
+     * The timestamp when the message was received by the subscription (nanoseconds since epoch).
+     */
+    readonly receivedTimestamp: bigint;
+
+    /**
+     * The publication sequence number assigned by the publisher.
+     */
+    readonly publicationSequenceNumber: bigint;
+
+    /**
+     * The reception sequence number assigned by the subscriber.
+     */
+    readonly receptionSequenceNumber: bigint;
+
+    /**
+     * The globally unique identifier (GID) of the publisher.
+     * A Buffer containing the raw GID bytes.
+     */
+    readonly publisherGid: Buffer;
+
+    /**
+     * Convert to a plain object representation.
+     */
+    toPlainObject(): {
+      sourceTimestamp: bigint;
+      receivedTimestamp: bigint;
+      publicationSequenceNumber: bigint;
+      receptionSequenceNumber: bigint;
+      publisherGid: Buffer;
+    };
+  }
+}

package/types/node.d.ts

@@ -80,6 +80,13 @@ declare module 'rclnodejs' {
      * inspect and limit messages that it accepts.
      */
     contentFilter?: SubscriptionContentFilter;
+
+    /**
+     * If provided, declares read-only ROS parameters for the specified QoS policies.
+     * These can be overridden at startup via `--ros-args -p` or `--params-file`.
+     * If qos is a profile string, it will be resolved to a mutable QoS object.
+     */
+    qosOverridingOptions?: QoSOverridingOptions;
   }
 
   /**
@@ -97,14 +104,24 @@ declare module 'rclnodejs' {
    */
   const DEFAULT_OPTIONS: Options;
 
+  interface TimerInfo {
+    expectedCallTime: bigint;
+    actualCallTime: bigint;
+  }
+
+  interface TimerOptions {
+    autostart?: boolean;
+  }
+
   /**
    * Callback for receiving periodic interrupts from a Timer.
+   * Receives timer metadata when the underlying ROS distro exposes it.
    *
    * @remarks
    * See {@link Node.createTimer | Node.createTimer}
    * See {@link Timer}
    */
-  type TimerRequestCallback = () => void;
+  type TimerRequestCallback = (timerInfo?: TimerInfo) => void;
 
   /**
    * Callback indicating parameters are about to be declared or set.
@@ -123,6 +140,19 @@ declare module 'rclnodejs' {
     parameters: Parameter[]
   ) => rcl_interfaces.msg.SetParametersResult;
 
+  /**
+   * Callback invoked before parameter validation and setting.
+   * Receives the parameter list, must return a (possibly modified) parameter list.
+   * Returning an empty list rejects the set.
+   */
+  type PreSetParametersCallback = (parameters: Parameter[]) => Parameter[];
+
+  /**
+   * Callback invoked after parameters have been successfully set.
+   * For side effects only (return value is ignored).
+   */
+  type PostSetParametersCallback = (parameters: Parameter[]) => void;
+
   /**
    * Standard result of Node.getXXXNamesAndTypes() queries
    *
@@ -293,15 +323,18 @@ declare module 'rclnodejs' {
     /**
      * Create a Timer.
      *
-     * @param period - Elapsed time between interrupt events (milliseconds).
-     * @param callback - Called on timeout interrupt.
-     * @param clock - Optional clock to use for the timer.
+     * @param period - Elapsed time between interrupt events in nanoseconds.
+     * @param callback - Called when the timer fires. Receives a `TimerInfo` argument when available.
+     * @param optionsOrClock - Optional timer options or clock to use for the timer.
+     *   Supports `{ autostart?: boolean }` when an options object is provided.
+     * @param clock - Optional clock to use for the timer when options are provided.
      * @returns New instance of Timer.
      */
     createTimer(
       period: bigint,
       callback: TimerRequestCallback,
-      clock?: Clock
+      optionsOrClock?: TimerOptions | Clock | null,
+      clock?: Clock | null
     ): Timer;
 
     /**
@@ -511,6 +544,27 @@ declare module 'rclnodejs' {
      */
     destroyParameterWatcher(watcher: ParameterWatcher): void;
 
+    /**
+     * Create a ParameterEventHandler that monitors parameter changes on any node.
+     *
+     * Unlike ParameterWatcher which watches specific parameters on a single
+     * remote node, ParameterEventHandler can register callbacks for parameters
+     * on any node in the ROS 2 graph by subscribing to /parameter_events.
+     *
+     * @param options - Options for the handler.
+     * @returns An instance of ParameterEventHandler.
+     */
+    createParameterEventHandler(
+      options?: ParameterEventHandlerOptions
+    ): ParameterEventHandler;
+
+    /**
+     * Destroy a ParameterEventHandler.
+     *
+     * @param handler - ParameterEventHandler to be destroyed.
+     */
+    destroyParameterEventHandler(handler: ParameterEventHandler): void;
+
     /**
      * Destroy a Timer.
      *
@@ -728,6 +782,37 @@ declare module 'rclnodejs' {
      */
     removeOnSetParametersCallback(call: SetParametersCallback): void;
 
+    /**
+     * Add a callback invoked before parameter validation.
+     * The callback receives the parameter list and must return a (possibly modified)
+     * parameter list. Returning an empty list rejects the set.
+     *
+     * @param callback - The callback to add.
+     */
+    addPreSetParametersCallback(callback: PreSetParametersCallback): void;
+
+    /**
+     * Remove a pre-set parameters callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    removePreSetParametersCallback(callback: PreSetParametersCallback): void;
+
+    /**
+     * Add a callback invoked after parameters are successfully set.
+     * Useful for triggering side effects (e.g., reconfiguring a component).
+     *
+     * @param callback - The callback to add.
+     */
+    addPostSetParametersCallback(callback: PostSetParametersCallback): void;
+
+    /**
+     * Remove a post-set parameters callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    removePostSetParametersCallback(callback: PostSetParametersCallback): void;
+
     /**
      * Get a remote node's published topics.
      *

package/types/parameter_event_handler.d.ts

@@ -0,0 +1,150 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// 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 ParameterEventHandler constructor.
+   */
+  export interface ParameterEventHandlerOptions {
+    /**
+     * QoS profile for the parameter_events subscription.
+     */
+    qos?: QoS;
+  }
+
+  /**
+   * Opaque handle returned when adding a parameter callback.
+   * Used to remove the callback later via removeParameterCallback().
+   */
+  class ParameterCallbackHandle {
+    readonly parameterName: string;
+    readonly nodeName: string;
+    readonly callback: (parameter: any) => void;
+  }
+
+  /**
+   * Opaque handle returned when adding a parameter event callback.
+   * Used to remove the callback later via removeParameterEventCallback().
+   */
+  class ParameterEventCallbackHandle {
+    readonly callback: (event: any) => void;
+  }
+
+  /**
+   * ParameterEventHandler - Monitors and responds to parameter changes
+   * on any node in the ROS 2 graph.
+   *
+   * Subscribes to `/parameter_events` and dispatches callbacks when
+   * parameters are added, changed, or deleted on any node.
+   *
+   * Two types of callbacks:
+   * - **Parameter callbacks**: for a specific parameter on a specific node
+   * - **Event callbacks**: for every ParameterEvent message received
+   *
+   * @example
+   * ```typescript
+   * const handler = node.createParameterEventHandler();
+   *
+   * const handle = handler.addParameterCallback(
+   *   'my_param', '/my_node',
+   *   (param) => console.log(`Changed: ${param.name}`)
+   * );
+   *
+   * handler.removeParameterCallback(handle);
+   * handler.destroy();
+   * ```
+   */
+  class ParameterEventHandler {
+    /**
+     * Add a callback for a specific parameter on a specific node.
+     *
+     * @param parameterName - Name of the parameter to monitor.
+     * @param nodeName - Fully qualified name of the node (e.g., '/my_node').
+     * @param callback - Called with the parameter message when it changes.
+     * @returns A handle for removing this callback later.
+     */
+    addParameterCallback(
+      parameterName: string,
+      nodeName: string,
+      callback: (parameter: any) => void
+    ): ParameterCallbackHandle;
+
+    /**
+     * Remove a previously added parameter callback.
+     *
+     * @param handle - The handle returned by addParameterCallback.
+     */
+    removeParameterCallback(handle: ParameterCallbackHandle): void;
+
+    /**
+     * Add a callback that is invoked for every parameter event.
+     *
+     * @param callback - Called with the full ParameterEvent message.
+     * @returns A handle for removing this callback later.
+     */
+    addParameterEventCallback(
+      callback: (event: any) => void
+    ): ParameterEventCallbackHandle;
+
+    /**
+     * Configure which node parameter events will be received.
+     *
+     * If nodeNames is omitted or empty, the node filter is cleared.
+     * Relative names are resolved against the handler node namespace.
+     *
+     * @param nodeNames - Node names to filter parameter events from.
+     * @returns True if the filter is active or was successfully cleared.
+     */
+    configureNodesFilter(nodeNames?: string[]): boolean;
+
+    /**
+     * Remove a previously added parameter event callback.
+     *
+     * @param handle - The handle returned by addParameterEventCallback.
+     */
+    removeParameterEventCallback(handle: ParameterEventCallbackHandle): void;
+
+    /**
+     * Check if the handler has been destroyed.
+     */
+    isDestroyed(): boolean;
+
+    /**
+     * Destroy the handler and clean up resources.
+     */
+    destroy(): void;
+
+    /**
+     * Get a specific parameter from a ParameterEvent message.
+     *
+     * @param event - A ParameterEvent message.
+     * @param parameterName - The parameter name to look for.
+     * @param nodeName - The node name to match.
+     * @returns The matching parameter message, or null.
+     */
+    static getParameterFromEvent(
+      event: any,
+      parameterName: string,
+      nodeName: string
+    ): any | null;
+
+    /**
+     * Get all parameters from a ParameterEvent message (new + changed).
+     *
+     * @param event - A ParameterEvent message.
+     * @returns Array of parameter messages.
+     */
+    static getParametersFromEvent(event: any): any[];
+  }
+}

package/types/qos.d.ts

@@ -134,4 +134,59 @@ declare module 'rclnodejs' {
       RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5,
     }
   }
+
+  /**
+   * Enum of overridable QoS policy kinds.
+   */
+  enum QoSPolicyKind {
+    HISTORY = 1,
+    DEPTH = 2,
+    RELIABILITY = 3,
+    DURABILITY = 4,
+    LIVELINESS = 5,
+    AVOID_ROS_NAMESPACE_CONVENTIONS = 6,
+  }
+
+  /**
+   * Options for overriding QoS policies via ROS parameters.
+   *
+   * When passed to `createPublisher()` or `createSubscription()`, the node
+   * declares read-only parameters for each specified policy kind. These
+   * parameters can be overridden at startup via `--ros-args -p` or `--params-file`.
+   *
+   * Parameter naming convention:
+   *   `qos_overrides.<topic>.<publisher|subscription>[_<entityId>].<policy>`
+   */
+  class QoSOverridingOptions {
+    /**
+     * @param policyKinds - Which QoS policies to expose as parameters.
+     * @param opts - Optional callback and entityId.
+     */
+    constructor(
+      policyKinds: QoSPolicyKind[],
+      opts?: {
+        callback?: (qos: QoS) => { successful: boolean; reason?: string };
+        entityId?: string;
+      }
+    );
+
+    /** Which QoS policies are exposed as parameters. */
+    readonly policyKinds: QoSPolicyKind[];
+
+    /** Optional validation callback. */
+    readonly callback:
+      | ((qos: QoS) => { successful: boolean; reason?: string })
+      | null;
+
+    /** Optional entity disambiguation suffix. */
+    readonly entityId: string | null;
+
+    /**
+     * Create options that override history, depth, and reliability.
+     */
+    static withDefaultPolicies(opts?: {
+      callback?: (qos: QoS) => { successful: boolean; reason?: string };
+      entityId?: string;
+    }): QoSOverridingOptions;
+  }
 }

package/types/subscription.d.ts

@@ -1,8 +1,11 @@
 declare module 'rclnodejs' {
   /**
    * A callback for receiving published messages.
+   * If the callback accepts two parameters, the second will be a MessageInfo
+   * containing metadata about the received message.
    *
    * @param message - The published message.
+   * @param messageInfo - Optional metadata about the message (timestamps, publisher GID, etc).
    *
    * @remarks
    * See {@link Node#createSubscription | Node.createSubscription}
@@ -13,12 +16,15 @@ declare module 'rclnodejs' {
    */
   type SubscriptionCallback<T extends TypeClass<MessageTypeClassName>> =
     // * @param message - The published message
-    (message: MessageType<T>) => void;
+    (message: MessageType<T>, messageInfo?: MessageInfo) => void;
 
   /**
    * A callback for receiving published raw messages.
+   * If the callback accepts a second parameter, it will receive a MessageInfo
+   * containing metadata about the received message.
    *
    * @param message - The published message.
+   * @param messageInfo - Optional metadata about the message.
    *
    * @remarks
    * See {@link Node#createSubscription | Node.createSubscription}
@@ -29,7 +35,7 @@ declare module 'rclnodejs' {
    */
   type SubscriptionWithRawMessageCallback =
     // * @param message - The published raw message
-    (message: Buffer) => void;
+    (message: Buffer, messageInfo?: MessageInfo) => void;
 
   /**
    * A ROS Subscription for published messages on a topic.
@@ -45,6 +51,12 @@ declare module 'rclnodejs' {
      */
     readonly isRaw: boolean;
 
+    /**
+     * Check if content filtering is supported for this subscription.
+     * @returns True if the subscription instance supports content filtering; otherwise false.
+     */
+    isContentFilterSupported(): boolean;
+
     /**
      * Test if the RMW supports content-filtered topics and that this subscription
      * is configured with a well formed content-filter.

package/types/timer.d.ts

@@ -78,8 +78,9 @@ declare module 'rclnodejs' {
 
     /**
      * Call a timer and starts counting again, retrieves actual and expected call time.
-     * @return - The timer information.
+     *
+     * @return The timer information with expected and actual call timestamps.
      */
-    callTimerWithInfo(): object;
+    callTimerWithInfo(): TimerInfo;
   }
 }

package/test_data_integrity.js

@@ -1,108 +0,0 @@
-// Data integrity + throughput test for subscription
-'use strict';
-
-const rclnodejs = require('./index.js');
-
-const PUBLISH_HZ = 50;
-const TEST_DURATION_SEC = 10;
-
-async function main() {
-  await rclnodejs.init();
-
-  const pubNode = new rclnodejs.Node('data_pub_node');
-  const subNode = new rclnodejs.Node('data_sub_node');
-
-  const publisher = pubNode.createPublisher(
-    'std_msgs/msg/Float64MultiArray',
-    '/data_integrity_topic'
-  );
-
-  let msgCount = 0;
-  let errCount = 0;
-  let lastTs = null;
-  const hzSamples = [];
-  const errors = [];
-
-  subNode.createSubscription(
-    'std_msgs/msg/Float64MultiArray',
-    '/data_integrity_topic',
-    (msg) => {
-      const now = Date.now();
-      msgCount++;
-
-      // --- Data validation ---
-      // Each published message has data = [seqNo, seqNo*1.5, seqNo*2.5]
-      // Verify structure and values
-      if (!msg || !msg.data) {
-        errCount++;
-        errors.push(`msg#${msgCount}: missing data field, got: ${JSON.stringify(msg)}`);
-      } else if (!Array.isArray(msg.data) && !(msg.data instanceof Float64Array)) {
-        errCount++;
-        errors.push(`msg#${msgCount}: data is not array-like, type=${typeof msg.data}`);
-      } else if (msg.data.length !== 3) {
-        errCount++;
-        errors.push(`msg#${msgCount}: expected 3 elements, got ${msg.data.length}`);
-      } else {
-        const seqNo = msg.data[0];
-        const expectedB = seqNo * 1.5;
-        const expectedC = seqNo * 2.5;
-
-        if (Math.abs(msg.data[1] - expectedB) > 1e-9) {
-          errCount++;
-          errors.push(
-            `msg#${msgCount}: data[1] expected ${expectedB}, got ${msg.data[1]}`
-          );
-        }
-        if (Math.abs(msg.data[2] - expectedC) > 1e-9) {
-          errCount++;
-          errors.push(
-            `msg#${msgCount}: data[2] expected ${expectedC}, got ${msg.data[2]}`
-          );
-        }
-      }
-
-      if (lastTs) {
-        hzSamples.push(1000 / (now - lastTs));
-      }
-      lastTs = now;
-    }
-  );
-
-  pubNode.spin();
-  subNode.spin();
-
-  let pubSeq = 0;
-  const pubInterval = setInterval(() => {
-    pubSeq++;
-    publisher.publish({ data: [pubSeq, pubSeq * 1.5, pubSeq * 2.5] });
-  }, 1000 / PUBLISH_HZ);
-
-  setTimeout(() => {
-    clearInterval(pubInterval);
-
-    console.log(`\n=== Data Integrity Test Results ===`);
-    console.log(`Published:    ${pubSeq} messages at ${PUBLISH_HZ} Hz`);
-    console.log(`Received:     ${msgCount} messages`);
-    console.log(`Data errors:  ${errCount}`);
-
-    if (errors.length > 0) {
-      console.log(`\nFirst 10 errors:`);
-      errors.slice(0, 10).forEach((e) => console.log(`  ${e}`));
-    }
-
-    if (hzSamples.length > 0) {
-      const avgHz = hzSamples.reduce((a, b) => a + b, 0) / hzSamples.length;
-      console.log(`\nAvg Hz:       ${avgHz.toFixed(2)}`);
-    }
-
-    const pass = errCount === 0 && msgCount > 0;
-    console.log(`\nResult:       ${pass ? 'PASS - all data correct' : 'FAIL'}`);
-
-    pubNode.stop();
-    subNode.stop();
-    rclnodejs.shutdown();
-    process.exit(pass ? 0 : 1);
-  }, TEST_DURATION_SEC * 1000);
-}
-
-main().catch(console.error);