rclnodejs 1.8.3 → 1.9.0-alpha.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

@@ -511,6 +511,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.
      *

package/types/parameter_event_handler.d.ts

@@ -0,0 +1,139 @@
+// 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;
+
+    /**
+     * 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/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/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);

package/test_repro_exact.js

@@ -1,57 +0,0 @@
-// Thorough latency/throughput test matching the exact issue scenario
-'use strict';
-
-const rclnodejs = require('./index.js');
-
-async function main() {
-  await rclnodejs.init();
-
-  const node = new rclnodejs.Node('test_node');
-
-  let lastTs;
-  let msgCount = 0;
-  const hzSamples = [];
-
-  node.createSubscription(
-    'std_msgs/msg/Float64MultiArray',
-    '/map_to_base_link_pose2d',
-    (msg) => {
-      const now = Date.now();
-      msgCount++;
-      if (lastTs) {
-        const hz = 1000 / (now - lastTs);
-        hzSamples.push(hz);
-        console.log('Raw Hz:', hz.toFixed(2));
-      }
-      lastTs = now;
-    }
-  );
-
-  rclnodejs.spin(node);
-
-  console.log('Waiting for messages on /map_to_base_link_pose2d at ~10Hz...');
-  console.log('Run this in another terminal:');
-  console.log(
-    '  ros2 topic pub -r 10 /map_to_base_link_pose2d std_msgs/msg/Float64MultiArray "{data: [1.0, 2.0, 3.0]}"'
-  );
-
-  setTimeout(() => {
-    if (hzSamples.length > 0) {
-      const avgHz = hzSamples.reduce((a, b) => a + b, 0) / hzSamples.length;
-      console.log(`\n--- Summary ---`);
-      console.log(`Messages: ${msgCount}, Avg Hz: ${avgHz.toFixed(2)}`);
-      if (avgHz < 5) {
-        console.log('*** REGRESSION DETECTED ***');
-      } else {
-        console.log('Performance OK');
-      }
-    } else {
-      console.log('No messages received');
-    }
-    node.stop();
-    rclnodejs.shutdown();
-    process.exit(0);
-  }, 15000);
-}
-
-main().catch(console.error);

package/test_repro_hz.js

@@ -1,86 +0,0 @@
-// Reprocer for https://github.com/RobotWebTools/rclnodejs/issues/1394
-// Tests subscription throughput at ~10Hz publishing rate
-'use strict';
-
-const rclnodejs = require('./index.js');
-
-const PUBLISH_HZ = 10;
-const TEST_DURATION_SEC = 10;
-
-async function main() {
-  await rclnodejs.init();
-
-  const pubNode = new rclnodejs.Node('test_pub_node');
-  const subNode = new rclnodejs.Node('test_sub_node');
-
-  const publisher = pubNode.createPublisher(
-    'std_msgs/msg/Float64MultiArray',
-    '/test_hz_topic'
-  );
-
-  let msgCount = 0;
-  let lastTs = null;
-  const hzSamples = [];
-
-  subNode.createSubscription(
-    'std_msgs/msg/Float64MultiArray',
-    '/test_hz_topic',
-    (msg) => {
-      const now = Date.now();
-      msgCount++;
-      if (lastTs) {
-        const hz = 1000 / (now - lastTs);
-        hzSamples.push(hz);
-      }
-      lastTs = now;
-    }
-  );
-
-  pubNode.spin();
-  subNode.spin();
-
-  // Publish at target Hz
-  let pubCount = 0;
-  const pubInterval = setInterval(() => {
-    publisher.publish({ data: [1.0, 2.0, 3.0] });
-    pubCount++;
-  }, 1000 / PUBLISH_HZ);
-
-  // Wait for test duration then report
-  setTimeout(() => {
-    clearInterval(pubInterval);
-
-    if (hzSamples.length > 0) {
-      const avgHz =
-        hzSamples.reduce((a, b) => a + b, 0) / hzSamples.length;
-      const minHz = Math.min(...hzSamples);
-      const maxHz = Math.max(...hzSamples);
-
-      console.log(`Published:  ${pubCount} messages`);
-      console.log(`Received:   ${msgCount} messages`);
-      console.log(`Avg Hz:     ${avgHz.toFixed(2)}`);
-      console.log(`Min Hz:     ${minHz.toFixed(2)}`);
-      console.log(`Max Hz:     ${maxHz.toFixed(2)}`);
-      console.log(
-        `Expected:   ~${PUBLISH_HZ} Hz`
-      );
-
-      if (avgHz < PUBLISH_HZ * 0.5) {
-        console.log(
-          `\n*** REGRESSION DETECTED: Average Hz (${avgHz.toFixed(2)}) is less than 50% of expected (${PUBLISH_HZ}) ***`
-        );
-      } else {
-        console.log('\nPerformance looks OK.');
-      }
-    } else {
-      console.log('No messages received!');
-    }
-
-    pubNode.stop();
-    subNode.stop();
-    rclnodejs.shutdown();
-    process.exit(0);
-  }, TEST_DURATION_SEC * 1000);
-}
-
-main().catch(console.error);

package/test_repro_pub.js

@@ -1,36 +0,0 @@
-// Publisher for repro test - runs in separate process
-'use strict';
-
-const rclnodejs = require('./index.js');
-
-const PUBLISH_HZ = parseInt(process.argv[2] || '100');
-
-async function main() {
-  await rclnodejs.init();
-
-  const node = new rclnodejs.Node('test_publisher_node');
-  const publisher = node.createPublisher(
-    'std_msgs/msg/Float64MultiArray',
-    '/test_hz_topic'
-  );
-
-  node.spin();
-
-  let pubCount = 0;
-  console.log(`Publishing at ${PUBLISH_HZ} Hz...`);
-
-  const pubInterval = setInterval(() => {
-    publisher.publish({ data: [1.0, 2.0, 3.0] });
-    pubCount++;
-  }, 1000 / PUBLISH_HZ);
-
-  setTimeout(() => {
-    clearInterval(pubInterval);
-    console.log(`Published ${pubCount} messages total`);
-    node.stop();
-    rclnodejs.shutdown();
-    process.exit(0);
-  }, 15000);
-}
-
-main().catch(console.error);