Expose MessageInfo metadata on subscription callbacks

[minggangw]

Exposes ROS 2 message metadata (timestamps, sequence numbers, publisher GID) to subscription callbacks, matching rclpy's MessageInfo pattern. When a subscription callback declares two parameters, it automatically receives a MessageInfo object as the second argument containing metadata from the middleware layer. Single-parameter callbacks are unchanged — no performance overhead, full backward compatibility.

New files:

• lib/message_info.js — MessageInfo class wrapping native rmw_message_info_t fields: sourceTimestamp (bigint), receivedTimestamp (bigint), publicationSequenceNumber (bigint), receptionSequenceNumber (bigint), publisherGid (Buffer). Includes toPlainObject() helper.
• types/message_info.d.ts — Full TypeScript declarations for MessageInfo.
• test/test-message-info.js — 6 tests covering: MessageInfo delivery with 2-param callbacks, non-delivery with 1-param callbacks, timestamp validity, timestamp ordering, toPlainObject(), and export verification.

Modified files:

• src/rcl_subscription_bindings.cpp — Added RclTakeWithInfo() native function that calls rcl_take() with rmw_message_info_t (instead of nullptr) and returns a JS object with all metadata fields as BigInts and a GID Buffer. Registered as rclTakeWithInfo binding. Added #include <rmw/types.h>.
• lib/subscription.js — Added _wantsMessageInfo flag detected via callback.length >= 2. Added wantsMessageInfo readonly getter. Updated processResponse() to accept optional messageInfo second parameter and forward it to the callback when the flag is set.
• lib/node.js — Updated subscription spin loop: when subscription.wantsMessageInfo is true, uses rclTakeWithInfo and wraps the result in MessageInfo; otherwise uses the existing rclTake path (zero overhead for 1-param callbacks). Added MessageInfo require.
• index.js — Exported MessageInfo class.
• types/index.d.ts — Added /// <reference> for message_info.d.ts.
• types/subscription.d.ts — Updated SubscriptionCallback and SubscriptionWithRawMessageCallback type aliases to accept optional second MessageInfo parameter via union types.

Fix: #1439

[Copilot]

Pull request overview

This PR adds support for delivering subscription message metadata (“MessageInfo”) to user callbacks when the callback declares two parameters, aligning rclnodejs behavior with similar ROS client APIs.

Changes:

• Introduces a new MessageInfo JS/TS API and exports it from the main module.
• Adds a native rclTakeWithInfo binding to retrieve rmw_message_info_t alongside a taken message.
• Updates subscription callback typings and adds tests validating metadata delivery for 2-arg callbacks.

Reviewed changes

Copilot reviewed 6 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
types/subscription.d.ts	Expands subscription callback types to optionally accept MessageInfo.
types/message_info.d.ts	Adds TypeScript declarations for the new MessageInfo API.
types/index.d.ts	References the new message_info.d.ts so it’s included in published typings.
src/rcl_subscription_bindings.cpp	Adds rclTakeWithInfo native binding returning message metadata.
lib/message_info.js	Adds JS MessageInfo wrapper and toPlainObject().
lib/subscription.js	Detects whether callback wants metadata via callback.length and forwards metadata when present.
lib/node.js	Uses rclTakeWithInfo when metadata is requested and passes MessageInfo into subscription callbacks.
index.js	Exports MessageInfo on the public rclnodejs module.
test/test-message-info.js	Adds tests for presence/absence of metadata based on callback arity and basic field expectations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

coverage: 85.983% (-0.02%) from 85.999%
when pulling 2c745fa on minggangw:fix-1439
into 607e03a on RobotWebTools:develop.