rclnodejs v2.0.0 (2026-05-25)

First stable release in the 2.x series. Aligned with the ROS 2 Lyrical Luth GA (Ubuntu 26.04).

This release rolls up the 2.0.0-beta.0 baseline (Lyrical support, Node.js 20.20.2 minimum, removal of legacy 1.x compatibility code, and the rosocket WebSocket gateway) and adds the headline new capability for the 2.x line: rclnodejs/web — a typed Browser SDK plus a small capability runtime that lets a web page talk to ROS 2 over a single WebSocket, with the same capabilities also reachable over plain HTTP for curl, Postman, and AI agents.

2.0.0 also folds in the full 1.9.0 feature set — ParameterEventHandler, waitForMessage, timer autostart + TimerInfo, QoS overriding options, pre/post-set parameter callbacks, ClockEvent, Observable subscriptions (RxJS), MessageIntrospector, action-client feedback content filters, and the rest. Anything you had on 1.x is still here; upgrades from 1.9.0 are additive aside from the breaking changes called out below.

📣 Important Notes

• rclnodejs 2.0.0 supports ROS 2 Lyrical Luth (Ubuntu 26.04, distro id 2605) in addition to Humble, Jazzy, Kilted, and Rolling.
• Minimum Node.js raised to 20.20.2. Node.js 16.x and 18.x are no longer supported.
• Linux x64 / arm64 ship N-API prebuilds — one artifact built against Node.js 20.20.2 runs unchanged on every Node.js ≥ 20.20.2, including 24.x and 26.x. Electron prebuilds target Electron 34.x.
• Internal compatibility shims and unused utilities have been removed (#1479); downstream code depending on undocumented lib/ internals may need updates.
• rclnodejs/web and rosocket ship side by side as siblings, not layers — they share the monorepo but serve different audiences (typed declarative SDK vs. raw resource-style WebSocket gateway).

✨ Highlights

rclnodejs/web — typed Browser SDK + capability runtime

• rclnodejs/web capability runtime over WebSocket — declarative runtime.expose({...}) allow-list (#1509)
• Typed Browser SDK with single-string-generic API over auto-generated MessagesMap / ServicesMap (#1511)
• HTTP transport for call / publish — POST /capability/call/<name> returns the JSON reply (#1512)
• rclnodejs-web CLI launcher — declarative web.json config (or --call / --publish / --subscribe flags), zero server code (#1513)
• WebSocket and HTTP transports default to a shared /capability path; SDK auto-derives sibling URLs (#1515)
• SDK guide (web/README.md) plus JS-only and TypeScript + Vite demos under demo/web/ (#1514)

Distros, RMW, and runtime

• Add ROS 2 Lyrical Luth support (#1496)
• Add explicit LYRICAL distro identifier (2605) (#1488)
• Add lightweight WebSocket bridge (rosocket) for browser access to ROS 2 (#1495)
• Add rmw_zenoh_cpp as RMW vendor and update distribution metadata (#1487)
• Treat unrecognized ROS_DISTRO as a future distro (#1485)
• Refresh Electron prebuild target and demo apps (#1492)

🛡️ Bug Fixes and Safeguards

• Fix SIGSEGV on ROS 2 Rolling caused by rosidl sequence ABI change (#1480)
• Gate C++ standard by ROS distro (#1477)

🔧 Maintenance

• Raise Node.js minimum to 20.20.2 (#1478)
• Pump to Node 26.x (#1497)
• Remove compatibility and custom utility code carried over from 1.x (#1479)
• Consolidate all demos under demo/ and add rosocket demo (#1503)
• Refine README and npmjs landing page (#1508)
• Surface ROS 2 Lyrical and the 2.0.0-beta.0 baseline in docs (#1507)
• Pump lint-staged and sinon to latest (#1505)
• Reorganize badges on README (#1483)

🚀 CI, Packaging, and Tooling

• Run primary CI lanes on Lyrical instead of Jazzy (#1506)
• Install ROS 2 Lyrical from apt-deb repo instead of dated tarball (#1516)
• Install test-msgs and mrpt-msgs uniformly across all ROS 2 distros (#1518)
• Add Lyrical Luth lane to Linux prebuild workflows (#1498)
• Migrate Rolling build to Ubuntu 26.04 (#1493)
• Add GitHub Actions workflow to deploy JSDoc to GitHub Pages (#1490)
• Use npm install in deploy-docs workflow (#1491)
• Trigger npm-publish on prerelease tags (#1501)

Getting Started with rclnodejs/web

// Browser
import { connect } from 'rclnodejs/web';

const ros = await connect('ws://robot.local:9000/capability');
const reply = await ros.call<'example_interfaces/srv/AddTwoInts'>(
  '/add_two_ints', { a: '2n', b: '40n' }
);
console.log(reply.sum); // '42n'

# Server (no JavaScript needed)
source /opt/ros/lyrical/setup.bash
npx -p rclnodejs rclnodejs-web --port 9000 --http-port 9001 \
  --call /add_two_ints=example_interfaces/srv/AddTwoInts

See the SDK guide and demos.

---

Full Changelog: 1.9.0...2.0.0

rclnodejs v2.0.0-beta.0 (2026-05-06)

Note: This is a pre-release for testing the 2.x line on ROS 2 Lyrical Luth. Install with npm install rclnodejs@2.0.0-beta.0. The latest tag on npm still points to 1.9.0.

This pre-release kicks off the rclnodejs 2.x series. The headline change is first-class support for ROS 2 Lyrical Luth (Ubuntu 26.04, distro id 2605), together with a refreshed toolchain — Node.js 20.20.2 minimum, Node 26.x in CI and prebuilds, and the removal of legacy compatibility code carried over from the 1.x line. A lightweight WebSocket bridge now lets browser apps talk to ROS 2 directly, and the Electron demo apps have been refreshed against current Electron and Node.js.

📣 Important Notes

• rclnodejs 2.0 targets ROS 2 Lyrical Luth as the next supported LTS, in addition to existing distros.
• Minimum Node.js raised to 20.20.2. Node.js 16.x and 18.x are no longer supported.
• Linux prebuilds are now built on Node 26.x (x64 + arm64) and include a dedicated Lyrical Luth lane.
• Internal compatibility shims and unused utilities have been removed; downstream code depending on undocumented lib/ internals may need updates.
• The latest npm tag continues to point to 1.9.0 until 2.0.0 is final.

✨ Highlights

• Add ROS 2 Lyrical Luth support (#1496)
• Add explicit LYRICAL distro identifier (2605) (#1488)
• Add lightweight WebSocket bridge for browser access to ROS 2 (#1495)
• Add rmw_zenoh_cpp as RMW vendor and update distribution metadata (#1487)
• Treat unrecognized ROS_DISTRO as a future distro (#1485)
• Refresh Electron prebuild target and demo apps (#1492)

🛡️ Bug Fixes And Safeguards

• Fix SIGSEGV on ROS 2 Rolling caused by rosidl sequence ABI change (#1480)
• Gate C++ standard by ROS distro (#1477)

🔧 Maintenance

• Raise Node.js minimum to 20.20.2 (#1478)
• Pump to Node 26.x (#1497)
• Remove compatibility and custom utility code carried over from 1.x (#1479)
• Reorganize badges on README (#1483)

🚀 CI, Packaging, And Tooling

• Add Lyrical Luth lane to Linux prebuild workflows (#1498)
• Migrate rolling build to Ubuntu 26.04 (#1493)
• Add GitHub Actions workflow to deploy JSDoc to GitHub Pages (#1490)
• Use npm install in deploy-docs workflow (#1491)
• Trigger npm-publish on prerelease tags (#1501)
• Pump to 2.0.0-beta.0 pre-release (#1499)

Full Changelog: 1.9.0...2.0.0-beta.0

rclnodejs v1.9.0 Release (2026-04-07)

We are pleased to announce rclnodejs v1.9.0. This stable release adds new subscription, timer, parameter, QoS, and action capabilities, along with CI and publishing improvements introduced during the 1.9.0 alpha cycle.

📣 Important Notes

• rclnodejs 1.9.0 is the final release in the 1.x series.
• ROS 2 Lyrical support will begin with rclnodejs 2.x.
• rclnodejs 1.9.0 is the final release with Node.js 16.x support.
• rclnodejs 1.9.0 is the final release with C++17 support.

✨ Highlights

• Add QoS overriding options for publishers and subscriptions (#1468)
• Add pre-set and post-set parameter callbacks (#1470)
• Add timer autostart and TimerInfo callback support (#1472)
• Add ParameterEventHandler node filtering support (#1474)
• Add ParameterEventHandler for cross-node parameter monitoring (#1438)
• Expose MessageInfo metadata on subscription callbacks (#1440)
• Add waitForMessage utility for one-shot message reception (#1444)
• Add support check for content filter feature in subscription (#1451)
• Support feedback subscription content filter for action client (#1457)

🛡️ Bug Fixes And Safeguards

• Guard publishFeedback and execute for valid goal states (#1466)

🚀 CI, Packaging, And Tooling

• Add OIDC trusted publishing and npm provenance support (#1460)
• Skip lifecycle scripts when packing release artifacts (#1461)
• Support pre-release publishing in the npm publish workflow (#1464)
• Add AddressSanitizer memory testing for the native addon (#1430)
• Prevent CI hangs from unbounded subprocess waits (#1434)
• Re-enable tests on Jazzy for Windows (#1435)
• Update TypeScript to 6.0.2 (#1455)
• Clarify README install and quick start guidance (#1453)
• Update README documentation (#1449)
• Move JSDoc tooling under tools/jsdoc and document the publish workflow (#1447)
• Align clang-format include ordering with cpplint rules (#1428)

Full Changelog: 1.8.3...1.9.0

rclnodejs v1.9.0-alpha.0 (2026-04-01)

Note: This is a pre-release for testing purposes. Install with npm install rclnodejs@1.9.0-alpha.0. The latest tag on npm still points to 1.8.3.

This pre-release introduces several new features including action client feedback content filtering, subscription message metadata, cross-node parameter monitoring, and a one-shot message utility. It also debuts automated npm publishing via GitHub Actions with OIDC trusted publishing and SLSA provenance attestation.

✨ New Features

• Support feedback subscription content filter for action client (#1457)
• Add support check for content filter feature in subscription (#1451)
• Add waitForMessage utility for one-shot message reception (#1444)
• Expose MessageInfo metadata on subscription callbacks (#1440)
• Add ParameterEventHandler for cross-node parameter monitoring (#1438)

🚀 CI/CD & Infrastructure

• NPM Publish Workflow with OIDC trusted publishing and provenance (#1460)
• Support pre-release publishing in npm-publish workflow (#1464)
• Skip lifecycle scripts when packing (#1461)
• Add AddressSanitizer (ASan) memory testing for native addon (#1430)

🔧 Maintenance

• Pump TypeScript to 6.0.2 (#1455)
• Clarify README install and quick start guidance (#1453)
• Update README (#1449)
• Move JSDoc tooling under tools/jsdoc and document publish workflow (#1447)
• Re-enable tests on Jazzy for Windows (#1435)
• Prevent CI hangs from unbounded subprocess waits (#1434)
• Align clang-format include ordering with cpplint rules (#1428)

Full Changelog: 1.8.3...1.9.0-alpha.0

rclnodejs v1.8.3 Release (2026-03-09)

We are pleased to announce rclnodejs v1.8.3! This release includes parser and generator updates, multiple native and JavaScript bug fixes, test corrections, documentation updates, and Node options compatibility improvements.

🐛 Bug Fixes

• Fix potential issues in parser.py (#1404)
• Evaluate error message before resetting error state in macros (#1406)
• Resolve memory leaks, use-after-free, and correctness issues in native bindings (#1408)
• Resolve logic bugs, resource leaks, and error handling issues in JavaScript lib/ (#1410)
• Fix bugs in rosidl_gen and index.js, and add tests (#1412)
• Fix bugs in examples and Electron demos (#1414)
• Fix bugs in test files (#1418)
• Fix action server goal expiration and correct broken test assertions (#1420)
• Fix memory leaks, error handling, and type-safety issues in N-API bindings (#1422)
• Fix Node creation crash when using plain object as options (#1424)

✨ Improvements

• Leverage rosidl_parser.parser to parse .idl files directly (#1401)
• Update docs and tutorials (#1416)

🔧 Maintenance

• Pump nyc to 18.0.0 (#1400)

Full Changelog: 1.8.2...1.8.3

rclnodejs v1.8.2 Release (2026-02-24)

We are pleased to announce rclnodejs v1.8.2! This patch release focuses on improving ROS 2 Rolling compatibility, extending ROSIDL message support, and enhancing Electron Forge packaging for all demos.

🐛 Bug Fixes

ROS 2 Rolling Compilation (#1392)

• Fixed a compilation error when building against ROS 2 Rolling caused by a breaking API change in rcl_lifecycle_state_machine_init, which now requires a clock parameter. Added a version-specific code path (ROS_VERSION >= 5000) and updated JavaScript code to pass the node's clock handle to the native lifecycle state machine creation function.

Hyphenated ROSIDL Subdirectory Support (#1390)

• Fixed generate-ros-messages failure for packages with hyphenated subdirectory names (e.g., msg-common, msg-ros2 in mrpt_msgs). Updated getSubFolder() to normalize hyphenated subdirectory names to their base interface types (msg, srv, action).

✨ Improvements

Electron Forge Packaging (#1387)

• Configured Electron Forge packaging across all four Electron demos (topics, turtle_tf2, manipulator, car) to enable distributable application creation.
• Added ASAR unpack configuration for rclnodejs, which requires file system access to generated code and native bindings.
• Migrated manipulator demo from CDN-based Three.js to npm package and added GPU rendering workarounds.
• Added comprehensive packaging documentation to all demo READMEs.

Compiler Warnings (#1385)

• Replaced the broad <node.h> include with the more targeted <node_version.h> in rcl_bindings.cpp to mitigate compiler warnings from unnecessary Node C++ API exposure.

🔧 Infrastructure

• Windows Rolling CI: Re-enabled rolling builds on Windows by updating the download URL to the new GitHub Releases location for ROS 2 Rolling nightly binaries (#1382).
• Dependencies: Updated @eslint/js to ^10.0.1 and eslint to ^10.0.2 (#1396).

Full Changelog: 1.8.1...1.8.2

rclnodejs v1.8.1 Release (2026-01-22)

We are pleased to announce rclnodejs v1.8.1! This patch release focuses on improving stability, fixing critical bugs related to concurrency and Electron compatibility, and significantly enhancing test coverage and reliability.

🐛 Bug Fixes

Critical Race Condition Fix (#1372)

• Resolved a crash (SIGABRT / "pure virtual method called") that occurred when calling setContentFilter() while the node was spinning.
• Solution: The fix enforces a thread-safe pattern. Users should stop the node before modifying content filters and restart it afterwards.

Electron Compatibility (#1375, #1379)

• File System Operations: Replaced fs.access() with fs.stat() for file existence checks. This ensures compatibility with Electron's ASAR packaging system, where fs.access can sometimes fail.
• Demo Updates: Updated Electron demos to use Electron v40.0.0 and fixed type issues in the turtle_tf2 demo by using BigInt for timer periods.

Message Type Correctness (#1371)

• Time.toMsg(): Corrected the return type of Time.toMsg(). It now returns JavaScript numbers instead of BigInts for sec and nanosec fields, aligning correctly with the ROS 2 builtin_interfaces/msg/Time specification.

Stability Improvements

• Content Filtering: Fixed memory allocation bugs (using wrong size calculation) and improved error handling in content filter operations (#1369).
• Flaky Tests: Resolved test flakiness in type-description-service and content filtering tests (#1367, #1369).

🧪 Enhancements & Infrastructure

• Test Coverage: Major effort to improve unit test coverage. Added comprehensive tests for core modules like utils.js, client.js, logging.js, and timer.js, achieving >80% coverage (#1363).
• Windows CI: Fixed GitHub Actions failures on Windows by explicitly configuring Python 3.11 (#1376).
• Dependencies: Updated globals package to v17.0.0 (#1365).

Full Changelog: 1.8.0...1.8.1

rclnodejs v1.8.0 Release (2026-01-07)

Overview

We're excited to announce rclnodejs v1.8.0! This release brings reactive programming support with RxJS, enhanced logging capabilities, comprehensive clock/timer management, and improved message introspection tools.

🎉 Major Features

1. RxJS Observables Support (#1357)

• Observable Subscriptions: You can now use RxJS Observables for subscriptions, enabling powerful reactive programming patterns for handling message streams.

2. Advanced Logging Capabilities (#1336, #1337, #1338)

• Rosout Logging: Added support for publishing log messages to the standard /rosout topic.
• Logging Directory: New getLoggingDirectory() API to programmatically retrieve the current logging location.
• Thread Safety: Improved thread safety for logging operations.

3. Enhanced Time and Clock Management

• Clock Callbacks: Added support for clock callbacks (#1355) and ClockEvent (#1354).
• Timer Improvements:
  • getNextCallTime(): Inspect when a timer is scheduled to fire next (#1356).
  • Reset Callbacks: Support for callbacks when a timer is reset (#1348).

4. Message Introspection and Validation (#1346, #1341)

• MessageIntrospector: New capability to inspect message schemas at runtime.
• Enhanced Validation: Stronger message validation logic with non-throwing variants and better TypeScript definitions (#1345).

✨ New Capabilities

Node & Graph Information

• Service Introspection: Added getServersInfoByService and getClientsInfoByService to query service availability and connectivity (#1335).
• Liveliness Assertion: Added assertLiveliness() method for Publishers, critical for certain QoS configurations (#1331).
• Content Filtering: Added getContentFilter for Subscriptions to inspect filtering rules (#1334).

Utilities

• Argument Handling:
  • removeROSArgs(): Helper to strip ROS-specific arguments from command lines (#1339).
  • Unparsed Arguments: Better handling of unsupported arguments via rcl_arguments_get_unparsed_ros() (#1342).

🔧 Improvements & Fixes

Bug Fixes

• Memory Management: Fixed potential leak by calling rcl_action_goal_status_array_fini() when publishing status fails (#1332).
• Request Handling: Replaced rcl_take_request with rcl_take_request_with_info for more robust service request processing (#1333).

Build System

• Dependencies: Added node-gyp to devDependencies explicitly (#1351).
• CI: Removed 'rolling' distribution from Windows workflows (#1352).

Full Changelog: 1.7.0...1.8.0
Doc: https://robotwebtools.github.io/rclnodejs/docs/1.8.0/index.html

rclnodejs v1.7.0 Release (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!