rclnodejs v1.7.0

rclnodejs v1.7.0 Release Notes (2025-11-26)

Overview

We're excited to announce rclnodejs v1.7.0! This release brings significant improvements to the developer experience with promise-based APIs, comprehensive error handling, and powerful parameter management capabilities.

🎉 Major Features

1. Promise-Based Service Calls (#1311)

• Added sendRequestAsync() method for promise-based service calls
• Support for async/await syntax, making code more readable and maintainable
• Timeout support: Specify request timeouts with { timeout: milliseconds }
• Cancellation support: Use AbortSignal to cancel pending requests
• Full backward compatibility: Existing callback-based API remains unchanged
• Improved error handling with specific error types (TimeoutError, AbortError)

Example:

const response = await client.sendRequestAsync(request, { 
  timeout: 5000,
  signal: abortController.signal 
});

2. ParameterClient for Remote Parameter Access (#1318)

• New ParameterClient class for accessing parameters on remote nodes
• Full API for parameter operations:
  • getParameters() - Retrieve parameter values
  • setParameters() - Modify parameter values
  • listParameters() - List available parameters
  • describeParameters() - Get parameter metadata
• Async/await support with timeout and cancellation
• Clean API: node.createParameterClient(remoteNodeName) / node.destroyParameterClient()
• Exported parameterTypeFromValue() utility for parameter type detection

3. ParameterWatcher for Real-Time Monitoring (#1326)

• New ParameterWatcher class for real-time parameter change notifications
• Monitor specific parameters on remote nodes
• Event-driven architecture using Node.js EventEmitter
• Dynamic parameter management with addParameters() / removeParameters()
• Async/await support for initial parameter retrieval
• Proper lifecycle management and automatic cleanup

Example:

const watcher = node.createParameterWatcher(remoteNodeName);
watcher.on('change', ({ parameterName, value }) => {
  console.log(`${parameterName} changed to:`, value);
});
await watcher.start(['my_param']);

4. Structured Error Handling with Class Hierarchy (#1320)

• 21 new error classes providing rich context and type safety
• Base class: RclNodeError with contextual information (code, nodeName, entityType, timestamp, details)
• Validation Errors: TypeValidationError, RangeValidationError, NameValidationError
• Operation Errors: TimeoutError, AbortError, ServiceNotFoundError, NodeNotFoundError
• Parameter Errors: ParameterNotFoundError, ParameterTypeError, ReadOnlyParameterError
• Topic/Action Errors: PublisherError, SubscriptionError, GoalRejectedError, ActionServerNotFoundError
• Native Errors: NativeError wraps C++ exceptions with additional context
• All errors include toJSON() method for structured logging
• Fully backward compatible: All new errors extend Error

🔧 Improvements

Node.js Compatibility

• AbortSignal.any() polyfill (#1322) for Node.js < 20.3.0
• Fixed AbortSignal.timeout(0) behavior for Node.js < 18.20

CI/CD

• Re-enabled ARM64 platform testing (#1323)
• Updated actions/checkout to v6.0.0 (#1328)

🙏 Acknowledgments

Thanks to @mahmoud-ghalayini who made this release possible!

---

Full Changelog: 1.6.0...1.7.0

rclnodejs v1.6.0

Release Notes for rclnodejs v1.6.0 (2025-10-30)

🚀 Major Features

JSON-Safe Message Serialization (#1308)

• New Public API: Added serializationMode option to createSubscription()
  • 'default' - Native rclnodejs behavior
  • 'plain' - Converts TypedArrays to regular arrays (JSON-compatible)
  • 'json' - Full JSON-safe mode (handles TypedArrays, BigInt, NaN, Infinity)
• New Utility Functions:
  • rclnodejs.toJSONSafe(obj) - Converts objects to JSON-friendly format
  • rclnodejs.toJSONString(obj) - Directly converts to JSON string
• Problem Solved: Sensor messages with TypedArrays now work correctly with JSON.stringify(), web APIs, and logging workflows
• Fully backward compatible - existing code continues to work unchanged

📦 Dependency Cleanup

Removed external dependencies and replaced with native implementations:

• Removed compare-versions (#1303) - Implemented custom version comparison
• Removed fs-extra (#1302) - Using Node.js built-in fs module with custom utilities
• Removed doT template engine (#1297) - Replaced with native JavaScript template literals
• Removed terser (#1293) - Simplified to regex-based whitespace cleanup
• Removed is-close (#1295) - Implemented custom floating-point comparison

Result: Lighter package with fewer third-party dependencies, improved maintainability

🔧 Node.js Compatibility

Node.js v25 Support (#1313, #1314, #1315)

• Removed deprecated SlowBuffer - Eliminated Node.js v6 era compatibility code that was causing errors in v25

🏗️ Code Modernization

Template Engine Migration (#1297)

• Migrated from doT templates to native ES6 template literals
• Benefits: Better performance, improved maintainability, reduced dependencies

🔄 CI/CD Improvements

• GitHub Actions Updates (#1291): Upgraded setup-node action to v6.0.0
• Multi-version Testing: Expanded Node.js version coverage (v24, v25) across different platforms

Full Changelog: 1.5.2...1.6.0

🙏 Acknowledgments

Thanks to all contributors who helped identify issues and improve this release!

rclnodejs v1.5.2

🚀 Prebuilt Binaries Support

We're excited to announce that rclnodejs now ships with prebuilt native binaries for Ubuntu Linux, significantly reducing installation time and eliminating the need for build tools in most cases.

What's New

• Faster Installation: No more waiting for node-gyp compilation—prebuilt binaries are ready to use instantly
• Simplified Setup: No need to install build essentials, Python, or other compilation dependencies
• Multi-Platform Support: Prebuilt binaries available for both x64 and arm64 architectures
• ROS2 Compatibility: Supports Ubuntu 22.04 (Jammy) and 24.04 (Noble) with ROS2 Humble, Jazzy, Kilted

Supported Configurations

Ubuntu Version	ROS2 Distributions	Architectures
22.04 (Jammy)	Humble	x64, arm64
24.04 (Noble)	Jazzy, Kilted	x64, arm64

Force Build from Source

If you need to build from source (for debugging or custom configurations), set the environment variable:

export RCLNODEJS_FORCE_BUILD=1
npm install rclnodejs

Platform Notes

• Linux (Ubuntu): Prebuilt binaries supported ✅
• Windows/macOS: Automatically builds from source (as before)

This enhancement makes rclnodejs more accessible and production-ready, especially for CI/CD pipelines and containerized deployments.

---

These are changes for rclnodejs v1.5.2 (2025-10-13).

• Update outdated Dockerfile (#1262)
• Add a manipulator demo using Electron + rclnodejs (#1264)
• Add tutorial for service introspection (#1266)
• Add tutorial for type description service (#1268)
• Add tutorial for content filtering subscription (#1270)
• Add README for tutorials for indexing (#1272)
• Add README for electron demos for indexing (#1274)
• Add README for typescript demos for indexing (#1276)
• Update depenencies (#1278)
• Update author email (#1280)
• Update README for topics demo (#1282)
• Integrate rclnodejs/ref-napi into rclnodejs (#1285)
• Leverage prebuildify to provide prebuilt addon for npm package (#1287)

rclnodejs v1.5.1

These are changes for rclnodejs v1.5.0 (2025-09-11).

Feature added

• Generate missing messages at runtime (#1257)

Documentation

• Add mis-deleted docs (#1227)
• Add tf2 electron demo (#1229)
• Update the README for npmjs (#1233)
• Add FEATURES.md file (#1235)
• Add tutorial for lifecycle node (#1237)
• Update actionlib.md file (#1239)
• Provide parameter service tutorial (#1242)
• Provide tutorial about basic concepts of ROS2 (#1243)
• Add client/service example using nav_msgs/srv/GetMap (#1247)
• Move the note to the right position (#1259)

CI

• Separate actions for PR/PUSH (#1252)
• Rename actions (#1253)
• Pump setup-node & checkout (#1256)

Others

• Re-enable benchmark (#1245)
• Remove automated.py (#1249)

rclnodejs v1.5.0

These are changes for rclnodejs v1.5.0 (2025-08-18).

Feature added

• Support getting logger name for subscription, publisher, service and client (#1224)
• Add functions to run ros2 run/launch (#1222)

rclnodejs v1.4.2

Bug fix

• Correct exmple errors (#1208)
• Correct the parameter type of ActionServer constructor (#1210)

Documentation

• Add a demo for actions using typescript (#1212)
• Add a car demo for electron (#1215)
• Add demo links to README of npm package (#1217)

rclnodejs v1.4.1

Bug fix

• Fix example errors (#1205)
• Correct the index.js to be required for example/ (#1203)
• Fix test failure on rolling build (#1201)

Documentation

• Add README for each example (#1199)
• Add a client/service demo for typescript (#1195)
• Add a subscriber/publisher demo for typescript (#1194)
• Remove docs/ from develop branch (#1189)
• Restructure current examples (#1188)

Others

• Indicate the usage of generating messages from .idl files (#1185)
• Pump commander (#1197)
• Remove unnecessary files from npm package (#1191)

rclnodejs v1.4.0

Feature added

• Support .idl files for ROS message/service/action (#1181) , like:

Input file JointState.idl:

#include "std_msgs/msg/Header.idl"

module sensor_msgs {
  module msg {
    struct JointState {
      std_msgs::msg::Header header;
      sequence<string> name;
      sequence<double> position;
      sequence<double> velocity;
      sequence<double> effort;
    };
  };
};

Output JointState.msg:

# JointState.msg
# Generated from IDL file

std_msgs/Header header
string[] name
float64[] position
float64[] velocity
float64[] effort

To generate messages from IDL files, use the generate-messages-idl npm script:

npm run generate-messages-idl

Documentation

Reorg the README structure (#1182)

rclnodejs v1.3.0

Feature added

• Support get_type_description service via parameter (#1162)
• Support setting domain id for Context (#1164)
• Support creating node with ros args (#1166)
• Support to log the state machine data (#1168)
• Add RMW serialize and deserialize functions (#1173)
• Support to resolve topic/service (#1175)
• Validate and remap the topic name for publishers/subscriptions (#1177)

Bug fix

• Fix test-type-description-service.js flakiness (#1169)
• Fix flakiness of test-message-type.js (#1171)
• Ensure binding method returns with undefined when error happens (#1179)

rclnodejs v1.2.0

Feature added

• Support to get the RMW implementation identifier (#1148)
• Implement event handler (#1159)

Others

• Include all LTS ROS2 on develop branch (#1151)
• Fix test-type-description-service.js flakiness (#1155)
• Add Humble into arm workflow (#1157)