rclnodejs 1.5.1 → 1.6.0

package/README.md

@@ -31,6 +31,26 @@ npm i rclnodejs
 
 - **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
 
+### Prebuilt Binaries
+
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.
+
+**Supported Platforms:**
+
+- **Ubuntu 22.04 (Jammy)** - ROS 2 Humble
+- **Ubuntu 24.04 (Noble)** - ROS 2 Jazzy, Kilted
+- **Architectures:** x64, arm64
+- **Node.js:** >= 16.20.2 (N-API compatible)
+
+**Force Building from Source:**
+
+If you need to build from source even when a prebuilt binary is available, set the environment variable:
+
+```bash
+export RCLNODEJS_FORCE_BUILD=1
+npm install rclnodejs
+```
+
 ## Documentation
 
 API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.
@@ -73,9 +93,12 @@ See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/t
 
 Create rich, interactive desktop applications using Electron and web technologies like Three.js. Build 3D visualizations, monitoring dashboards, and control interfaces that run on Windows, macOS, and Linux.
 
-Try the `electron_demo/turtle_tf2` demo for real-time coordinate frame visualization with dynamic transforms and keyboard-controlled turtle movement. More examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
+|                                                  Demo                                                   |                                                              Description                                                              |                                                           Screenshot                                                            |
+| :-----------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: |
+|  **🐢 [turtle_tf2](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/turtle_tf2)**  |  Real-time coordinate frame visualization with turtle control. Features TF2 transforms, keyboard control, and dynamic frame updates.  |  ![turtle_tf2](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.png?raw=true)   |
+| **🦾 [manipulator](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo/manipulator)** | Interactive two-joint robotic arm simulation. Features 3D joint visualization, manual/automatic control, and visual movement markers. | ![manipulator](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/manipulator/manipulator-demo.png?raw=true) |
 
-![demo screenshot](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.gif?raw=true)
+Explore more examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
 
 ## License
 

package/binding.gyp

@@ -42,9 +42,11 @@
         './src/rcl_timer_bindings.cpp',
         './src/rcl_utilities.cpp',
         './src/shadow_node.cpp',
+        './third_party/ref-napi/src/ref_napi_bindings.cpp',
       ],
       'include_dirs': [
         '.',
+        './third_party/ref-napi/src',
         '<(ros_include_root)',
         "<!@(node -p \"require('node-addon-api').include\")",
       ],

package/index.js

@@ -18,7 +18,7 @@ const DistroUtils = require('./lib/distro.js');
 const RMWUtils = require('./lib/rmw.js');
 const { Clock, ROSClock } = require('./lib/clock.js');
 const ClockType = require('./lib/clock_type.js');
-const compareVersions = require('compare-versions');
+const { compareVersions } = require('./lib/utils.js');
 const Context = require('./lib/context.js');
 const debug = require('debug')('rclnodejs');
 const Duration = require('./lib/duration.js');
@@ -37,7 +37,7 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
 const Time = require('./lib/time.js');
@@ -47,6 +47,7 @@ const ActionUuid = require('./lib/action/uuid.js');
 const ClientGoalHandle = require('./lib/action/client_goal_handle.js');
 const { CancelResponse, GoalResponse } = require('./lib/action/response.js');
 const ServerGoalHandle = require('./lib/action/server_goal_handle.js');
+const { toJSONSafe, toJSONString } = require('./lib/message_serialization.js');
 const {
   getActionClientNamesAndTypesByNode,
   getActionServerNamesAndTypesByNode,
@@ -364,8 +365,7 @@ let rcl = {
 
     const version = await getCurrentGeneratorVersion();
     const forced =
-      version === null ||
-      compareVersions.compare(version, generator.version(), '<');
+      version === null || compareVersions(version, generator.version(), '<');
     if (forced) {
       debug(
         'The generator will begin to create JavaScript code from ROS IDL files...'
@@ -539,6 +539,23 @@ let rcl = {
    * @return {Promise<{process: ChildProcess}>} A Promise that resolves with the process.
    */
   ros2Launch: ros2Launch,
+
+  /**
+   * Convert a message object to be JSON-safe by converting TypedArrays to regular arrays
+   * and handling BigInt, Infinity, NaN, etc. for JSON serialization.
+   * @param {*} obj - The message object to convert
+   * @returns {*} A JSON-safe version of the object
+   */
+  toJSONSafe: toJSONSafe,
+
+  /**
+   * Convert a message object to a JSON string with proper handling of TypedArrays,
+   * BigInt, and other non-JSON-serializable values.
+   * @param {*} obj - The message object to convert
+   * @param {number} [space] - Space parameter for JSON.stringify formatting
+   * @returns {string} The JSON string representation
+   */
+  toJSONString: toJSONString,
 };
 
 const _sigHandler = () => {

package/lib/action/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const ClientGoalHandle = require('./client_goal_handle.js');

package/lib/action/graph.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 
 /**
  * Get a list of action names and types for action clients associated with a node.

package/lib/action/server.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const ActionUuid = require('./uuid.js');
 const DistroUtils = require('../distro.js');

package/lib/action/server_goal_handle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('../native_loader.js');
 const ActionInterfaces = require('./interfaces.js');
 const Deferred = require('./deferred.js');
 const { GoalEvent } = require('./response.js');

package/lib/client.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 const debug = require('debug')('rclnodejs:client');

package/lib/clock.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
 

package/lib/context.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 let defaultContext = null;
 

package/lib/duration.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const S_TO_NS = 10n ** 9n;
 
 /**

package/lib/event_handler.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
 

package/lib/guard_condition.js

@@ -12,7 +12,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Entity = require('./entity.js');
 const Context = require('./context.js');
 

package/lib/lifecycle.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const LifecyclePublisher = require('./lifecycle_publisher.js');
 const loader = require('./interface_loader.js');
 const Context = require('./context.js');

package/lib/lifecycle_publisher.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 const Logging = require('./logging.js');
 const Publisher = require('./publisher.js');
 

package/lib/logging.js

@@ -15,7 +15,7 @@
 'use strict';
 
 const path = require('path');
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 /**
  * Enum for LoggingSeverity

package/lib/message_serialization.js

@@ -0,0 +1,171 @@
+// Copyright (c) 2025 Mahmoud Alghalayini. All rights reserved.
+//
+// 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.
+
+'use strict';
+
+/**
+ * Check if a value is a TypedArray
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value is a TypedArray
+ */
+function isTypedArray(value) {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+/**
+ * Check if a value needs JSON conversion (BigInt, functions, etc.)
+ * @param {*} value - The value to check
+ * @returns {boolean} True if the value needs special JSON handling
+ */
+function needsJSONConversion(value) {
+  return (
+    typeof value === 'bigint' ||
+    typeof value === 'function' ||
+    typeof value === 'undefined' ||
+    value === Infinity ||
+    value === -Infinity ||
+    (typeof value === 'number' && isNaN(value))
+  );
+}
+
+/**
+ * Convert a message to plain arrays (TypedArray -> regular Array)
+ * @param {*} obj - The object to convert
+ * @returns {*} The converted object with plain arrays
+ */
+function toPlainArrays(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (isTypedArray(obj)) {
+    return Array.from(obj);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => toPlainArrays(item));
+  }
+
+  if (typeof obj === 'object' && obj !== null) {
+    const result = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        result[key] = toPlainArrays(obj[key]);
+      }
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Convert a message to be fully JSON-safe
+ * @param {*} obj - The object to convert
+ * @returns {*} The JSON-safe converted object
+ */
+function toJSONSafe(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (isTypedArray(obj)) {
+    return Array.from(obj).map((item) => toJSONSafe(item));
+  }
+
+  if (needsJSONConversion(obj)) {
+    if (typeof obj === 'bigint') {
+      // Convert BigInt to string with 'n' suffix to indicate it was a BigInt
+      return obj.toString() + 'n';
+    }
+    if (obj === Infinity) return 'Infinity';
+    if (obj === -Infinity) return '-Infinity';
+    if (typeof obj === 'number' && isNaN(obj)) return 'NaN';
+    if (typeof obj === 'undefined') return null;
+    if (typeof obj === 'function') return '[Function]';
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => toJSONSafe(item));
+  }
+
+  if (typeof obj === 'object' && obj !== null) {
+    const result = {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        result[key] = toJSONSafe(obj[key]);
+      }
+    }
+    return result;
+  }
+
+  return obj;
+}
+
+/**
+ * Convert a message to a JSON string
+ * @param {*} obj - The object to convert
+ * @param {number} [space] - Space parameter for JSON.stringify formatting
+ * @returns {string} The JSON string representation
+ */
+function toJSONString(obj, space) {
+  const jsonSafeObj = toJSONSafe(obj);
+  return JSON.stringify(jsonSafeObj, null, space);
+}
+
+/**
+ * Apply serialization mode conversion to a message object
+ * @param {*} message - The message object to convert
+ * @param {string} serializationMode - The serialization mode ('default', 'plain', 'json')
+ * @returns {*} The converted message
+ */
+function applySerializationMode(message, serializationMode) {
+  switch (serializationMode) {
+    case 'default':
+      // No conversion needed - use native rclnodejs behavior
+      return message;
+
+    case 'plain':
+      // Convert TypedArrays to regular arrays
+      return toPlainArrays(message);
+
+    case 'json':
+      // Convert to fully JSON-safe format
+      return toJSONSafe(message);
+
+    default:
+      throw new TypeError(
+        `Invalid serializationMode: ${serializationMode}. Valid modes are: 'default', 'plain', 'json'`
+      );
+  }
+}
+
+/**
+ * Validate serialization mode
+ * @param {string} mode - The serialization mode to validate
+ * @returns {boolean} True if valid
+ */
+function isValidSerializationMode(mode) {
+  return ['default', 'plain', 'json'].includes(mode);
+}
+
+module.exports = {
+  isTypedArray,
+  needsJSONConversion,
+  toPlainArrays,
+  toJSONSafe,
+  toJSONString,
+  applySerializationMode,
+  isValidSerializationMode,
+};

package/lib/native_loader.js

@@ -0,0 +1,173 @@
+// Copyright (c) 2025, 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.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const bindings = require('bindings');
+const debug = require('debug')('rclnodejs');
+const { detectUbuntuCodename } = require('./utils');
+
+let nativeModule = null;
+
+// Simplified loader: only use prebuilt binaries with exact Ubuntu/ROS2/arch match
+// Note: Prebuilt binaries are only supported on Linux (Ubuntu) platform
+function customFallbackLoader() {
+  // Prebuilt binaries are only for Linux platform
+  if (process.platform !== 'linux') {
+    debug('Prebuilt binaries are only supported on Linux platform');
+    return null;
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const arch = process.arch;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  // Require all three components for exact match
+  if (!rosDistro || !ubuntuCodename || !arch) {
+    debug(
+      `Missing environment info - ROS: ${rosDistro}, Ubuntu: ${ubuntuCodename}, Arch: ${arch}`
+    );
+    return null;
+  }
+
+  const prebuildDir = path.join(
+    __dirname,
+    '..',
+    'prebuilds',
+    `${process.platform}-${arch}`
+  );
+
+  if (!fs.existsSync(prebuildDir)) {
+    debug('No prebuilds directory found');
+    return null;
+  }
+
+  try {
+    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
+    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
+    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
+
+    if (fs.existsSync(exactMatchPath)) {
+      debug(`Found exact match binary: ${exactMatchFilename}`);
+      return require(exactMatchPath);
+    }
+
+    debug(`No exact match found for: ${exactMatchFilename}`);
+    return null;
+  } catch (e) {
+    debug('Error in simplified prebuilt loader:', e.message);
+  }
+
+  return null;
+}
+
+// Simplified prebuilt binary loader: exact match or build from source
+function loadNativeAddon() {
+  if (nativeModule) {
+    return nativeModule;
+  }
+
+  // Environment variable to force building from source
+  if (process.env.RCLNODEJS_FORCE_BUILD === '1') {
+    debug('Forcing build from source (RCLNODEJS_FORCE_BUILD=1)');
+
+    // Trigger actual compilation
+    try {
+      debug('Running forced node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully force compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Forced compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to force build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+
+  const rosDistro = process.env.ROS_DISTRO;
+  const ubuntuCodename = detectUbuntuCodename();
+
+  debug(
+    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+  );
+
+  // Prebuilt binaries are only supported on Linux (Ubuntu)
+  if (process.platform === 'linux') {
+    // Try exact match prebuilt binary first
+    try {
+      const prebuiltModule = customFallbackLoader();
+      if (prebuiltModule) {
+        nativeModule = prebuiltModule;
+        return nativeModule;
+      }
+    } catch (e) {
+      debug('Exact match prebuilt loading failed:', e.message);
+    }
+
+    debug(
+      'No exact match prebuilt binary found, falling back to build from source'
+    );
+  } else {
+    debug(
+      `Platform ${process.platform} does not support prebuilt binaries, will try existing build or compile from source`
+    );
+  }
+
+  try {
+    // Try to find existing built binary first (works on all platforms)
+    // The 'bindings' module will search standard locations like:
+    // - build/Release/rclnodejs.node
+    // - build/Debug/rclnodejs.node
+    // - compiled/{node_version}/{platform}/{arch}/rclnodejs.node
+    // etc.
+    nativeModule = bindings('rclnodejs');
+    debug('Found and loaded existing built binary');
+    return nativeModule;
+  } catch {
+    debug('No existing built binary found, triggering compilation...');
+
+    // Trigger actual compilation
+    try {
+      debug('Running node-gyp rebuild...');
+      execSync('npm run rebuild', {
+        stdio: 'inherit',
+        cwd: path.join(__dirname, '..'),
+        timeout: 300000, // 5 minute timeout
+      });
+
+      // Try to load the newly built binary
+      nativeModule = bindings('rclnodejs');
+      debug('Successfully compiled and loaded from source');
+      return nativeModule;
+    } catch (compileError) {
+      debug('Compilation failed:', compileError.message);
+      throw new Error(
+        `Failed to build rclnodejs from source: ${compileError.message}`
+      );
+    }
+  }
+}
+
+module.exports = loadNativeAddon();

package/lib/node.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const rclnodejs = require('bindings')('rclnodejs');
+const rclnodejs = require('./native_loader.js');
 
 const ActionInterfaces = require('./action/interfaces.js');
 const Client = require('./client.js');
@@ -31,6 +31,7 @@ const {
   Parameter,
   ParameterDescriptor,
 } = require('./parameter.js');
+const { isValidSerializationMode } = require('./message_serialization.js');
 const ParameterService = require('./parameter_service.js');
 const Publisher = require('./publisher.js');
 const QoS = require('./qos.js');
@@ -532,6 +533,14 @@ class Node extends rclnodejs.ShadowNode {
       options = Object.assign(options, { isRaw: false });
     }
 
+    if (options.serializationMode === undefined) {
+      options = Object.assign(options, { serializationMode: 'default' });
+    } else if (!isValidSerializationMode(options.serializationMode)) {
+      throw new TypeError(
+        `Invalid serializationMode: ${options.serializationMode}. Valid modes are: 'default', 'plain', 'json'`
+      );
+    }
+
     return options;
   }
 
@@ -666,6 +675,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {boolean} options.enableTypedArray - The topic will use TypedArray if necessary, default: true.
    * @param {QoS} options.qos - ROS Middleware "quality of service" settings for the subscription, default: QoS.profileDefault.
    * @param {boolean} options.isRaw - The topic is serialized when true, default: false.
+   * @param {string} [options.serializationMode='default'] - Controls message serialization format:
+   *  'default': Use native rclnodejs behavior (respects enableTypedArray setting),
+   *  'plain': Convert TypedArrays to regular arrays,
+   *  'json': Fully JSON-safe (handles TypedArrays, BigInt, etc.).
    * @param {object} [options.contentFilter=undefined] - The content-filter, default: undefined.
    *  Confirm that your RMW supports content-filtered topics before use. 
    * @param {string} options.contentFilter.expression - Specifies the criteria to select the data samples of
@@ -1920,6 +1933,7 @@ class Node extends rclnodejs.ShadowNode {
  *   isRaw: false,
  *   qos: QoS.profileDefault,
  *   contentFilter: undefined,
+ *   serializationMode: 'default',
  * }
  */
 Node.getDefaultOptions = function () {
@@ -1928,6 +1942,7 @@ Node.getDefaultOptions = function () {
     isRaw: false,
     qos: QoS.profileDefault,
     contentFilter: undefined,
+    serializationMode: 'default',
   };
 };