rclnodejs 1.8.2 → 1.9.0-alpha.0

package/src/rcl_subscription_bindings.cpp

@@ -16,11 +16,15 @@
 
 #include <rcl/error_handling.h>
 #include <rcl/rcl.h>
+#include <rcl/subscription.h>
+#include <rmw/types.h>
 
 #include <cstdio>
 #include <memory>
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 #include "macros.h"
 #include "rcl_handle.h"
 #include "rcl_utilities.h"
@@ -51,6 +55,53 @@ Napi::Value RclTake(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+Napi::Value RclTakeWithInfo(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* subscription_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_subscription_t* subscription =
+      reinterpret_cast<rcl_subscription_t*>(subscription_handle->ptr());
+  void* msg_taken = info[1].As<Napi::Buffer<char>>().Data();
+
+  rmw_message_info_t message_info = rmw_get_zero_initialized_message_info();
+  rcl_ret_t ret = rcl_take(subscription, msg_taken, &message_info, nullptr);
+
+  if (ret != RCL_RET_OK && ret != RCL_RET_SUBSCRIPTION_TAKE_FAILED) {
+    std::string error_string = rcl_get_error_string().str;
+    rcl_reset_error();
+    Napi::Error::New(env, error_string).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  if (ret == RCL_RET_SUBSCRIPTION_TAKE_FAILED) {
+    return env.Undefined();
+  }
+
+  // Build JS object with message info fields
+  Napi::Object js_info = Napi::Object::New(env);
+  js_info.Set("source_timestamp",
+              Napi::BigInt::New(env, message_info.source_timestamp));
+  js_info.Set("received_timestamp",
+              Napi::BigInt::New(env, message_info.received_timestamp));
+  js_info.Set(
+      "publication_sequence_number",
+      Napi::BigInt::New(
+          env, static_cast<int64_t>(message_info.publication_sequence_number)));
+  js_info.Set(
+      "reception_sequence_number",
+      Napi::BigInt::New(
+          env, static_cast<int64_t>(message_info.reception_sequence_number)));
+
+  // Publisher GID as Buffer
+  auto gid_buf =
+      Napi::Buffer<uint8_t>::Copy(env, message_info.publisher_gid.data,
+                                  sizeof(message_info.publisher_gid.data));
+  js_info.Set("publisher_gid", gid_buf);
+
+  return js_info;
+}
+
 Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -108,12 +159,6 @@ Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
       rcl_ret_t ret = rcl_subscription_options_set_content_filter_options(
           expression.c_str(), argc, (const char**)argv, &subscription_ops);
 
-      if (ret != RCL_RET_OK) {
-        std::string error_string = rcl_get_error_string().str;
-        rcl_reset_error();
-        Napi::Error::New(env, error_string).ThrowAsJavaScriptException();
-      }
-
       if (argc) {
         for (int i = 0; i < argc; i++) {
           free(argv[i]);
@@ -122,7 +167,10 @@ Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
       }
 
       if (ret != RCL_RET_OK) {
+        std::string error_string = rcl_get_error_string().str;
+        rcl_reset_error();
         free(subscription);
+        Napi::Error::New(env, error_string).ThrowAsJavaScriptException();
         return env.Undefined();
       }
     }
@@ -137,8 +185,8 @@ Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
     if (ret != RCL_RET_OK) {
       std::string error_msg = rcl_get_error_string().str;
       rcl_reset_error();
-      Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
       free(subscription);
+      Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
       return env.Undefined();
     }
 
@@ -157,9 +205,9 @@ Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
 
     return js_obj;
   } else {
-    Napi::Error::New(env, GetErrorMessageAndClear())
-        .ThrowAsJavaScriptException();
+    std::string error_msg = GetErrorMessageAndClear();
     free(subscription);
+    Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
     return env.Undefined();
   }
 }
@@ -194,10 +242,16 @@ Napi::Value RclTakeRaw(const Napi::CallbackInfo& info) {
     return env.Undefined();
   }
 
+  RCPPUTILS_SCOPE_EXIT({
+    rcl_ret_t fini_ret = rmw_serialized_message_fini(&msg);
+    if (fini_ret != RCL_RET_OK) {
+      rcl_reset_error();
+    }
+  });
+
   Napi::Buffer<char> buffer = Napi::Buffer<char>::Copy(
       env, reinterpret_cast<char*>(msg.buffer), msg.buffer_length);
-  THROW_ERROR_IF_NOT_EQUAL(rmw_serialized_message_fini(&msg), RCL_RET_OK,
-                           "Failed to deallocate message buffer");
+
   return buffer;
 }
 
@@ -211,6 +265,20 @@ Napi::Value GetSubscriptionTopic(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, topic);
 }
 
+#if ROS_VERSION > 2505  // Rolling only
+Napi::Value IsContentFilterSupported(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* subscription_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_subscription_t* subscription =
+      reinterpret_cast<rcl_subscription_t*>(subscription_handle->ptr());
+
+  bool is_supported = rcl_subscription_is_cft_supported(subscription);
+  return Napi::Boolean::New(env, is_supported);
+}
+#endif
+
 Napi::Value HasContentFilter(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -369,6 +437,14 @@ Napi::Value GetContentFilter(const Napi::CallbackInfo& info) {
     return env.Undefined();
   }
 
+  RCPPUTILS_SCOPE_EXIT({
+    rcl_ret_t fini_ret =
+        rcl_subscription_content_filter_options_fini(subscription, &options);
+    if (fini_ret != RCL_RET_OK) {
+      rcl_reset_error();
+    }
+  });
+
   // Create result object
   Napi::Object result = Napi::Object::New(env);
   result.Set(
@@ -387,16 +463,6 @@ Napi::Value GetContentFilter(const Napi::CallbackInfo& info) {
   }
   result.Set("parameters", parameters);
 
-  // Cleanup
-  rcl_ret_t fini_ret =
-      rcl_subscription_content_filter_options_fini(subscription, &options);
-  if (fini_ret != RCL_RET_OK) {
-    std::string error_msg = rcl_get_error_string().str;
-    rcl_reset_error();
-    Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
-    return env.Undefined();
-  }
-
   return result;
 }
 
@@ -419,11 +485,16 @@ Napi::Value GetPublisherCount(const Napi::CallbackInfo& info) {
 
 Napi::Object InitSubscriptionBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("rclTake", Napi::Function::New(env, RclTake));
+  exports.Set("rclTakeWithInfo", Napi::Function::New(env, RclTakeWithInfo));
   exports.Set("createSubscription",
               Napi::Function::New(env, CreateSubscription));
   exports.Set("rclTakeRaw", Napi::Function::New(env, RclTakeRaw));
   exports.Set("getSubscriptionTopic",
               Napi::Function::New(env, GetSubscriptionTopic));
+#if ROS_VERSION > 2505  // Rolling only
+  exports.Set("isContentFilterSupported",
+              Napi::Function::New(env, IsContentFilterSupported));
+#endif
   exports.Set("hasContentFilter", Napi::Function::New(env, HasContentFilter));
   exports.Set("setContentFilter", Napi::Function::New(env, SetContentFilter));
   exports.Set("getContentFilter", Napi::Function::New(env, GetContentFilter));

package/src/rcl_timer_bindings.cpp

@@ -19,6 +19,7 @@
 
 #include <memory>
 #include <mutex>
+#include <string>
 #include <unordered_map>
 
 #include "macros.h"
@@ -82,16 +83,30 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
   *timer = rcl_get_zero_initialized_timer();
 
 #if ROS_VERSION > 2305  // After Iron.
-  THROW_ERROR_IF_NOT_EQUAL(
-      RCL_RET_OK,
-      rcl_timer_init2(timer, clock, context, period_nsec, nullptr,
-                      rcl_get_default_allocator(), /*autostart=*/true),
-      rcl_get_error_string().str);
+  {
+    rcl_ret_t ret = rcl_timer_init2(timer, clock, context, period_nsec, nullptr,
+                                    rcl_get_default_allocator(),
+                                    /*autostart=*/true);
+    if (RCL_RET_OK != ret) {
+      std::string error_msg = rcl_get_error_string().str;
+      rcl_reset_error();
+      free(timer);
+      Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+  }
 #else
-  THROW_ERROR_IF_NOT_EQUAL(RCL_RET_OK,
-                           rcl_timer_init(timer, clock, context, period_nsec,
-                                          nullptr, rcl_get_default_allocator()),
-                           rcl_get_error_string().str);
+  {
+    rcl_ret_t ret = rcl_timer_init(timer, clock, context, period_nsec, nullptr,
+                                   rcl_get_default_allocator());
+    if (RCL_RET_OK != ret) {
+      std::string error_msg = rcl_get_error_string().str;
+      rcl_reset_error();
+      free(timer);
+      Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+  }
 #endif
 
   auto js_obj =

package/src/rcl_type_description_service_bindings.cpp

@@ -15,9 +15,12 @@
 #include "rcl_type_description_service_bindings.h"
 
 #include <napi.h>
+#include <rcl/error_handling.h>
 #include <rcl/rcl.h>
 #include <rmw/types.h>
 
+#include <string>
+
 #include "rcl_handle.h"
 
 namespace rclnodejs {
@@ -31,8 +34,13 @@ Napi::Value InitTypeDescriptionService(const Napi::CallbackInfo& info) {
   *service = rcl_get_zero_initialized_service();
   rcl_ret_t ret = rcl_node_type_description_service_init(service, node);
   if (RCL_RET_OK != ret) {
-    Napi::Error::New(env, "Failed to initialize type description service")
+    std::string error_msg = rcl_get_error_string().str;
+    rcl_reset_error();
+    free(service);
+    Napi::Error::New(
+        env, "Failed to initialize type description service: " + error_msg)
         .ThrowAsJavaScriptException();
+    return env.Undefined();
   }
 
   auto service_handle =

package/src/rcl_utilities.cpp

@@ -21,10 +21,10 @@
 
 #include <cstdio>
 #include <memory>
-#include <rcpputils/scope_exit.hpp>
-// NOLINTNEXTLINE
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 namespace {
 
 const rmw_qos_profile_t* GetQoSProfileFromString(const std::string& profile) {

package/tools/jsdoc/Makefile

@@ -0,0 +1,5 @@
+.PHONY: docs
+
+docs:
+	npx jsdoc --package ../../package.json ../../index.js ../../lib/*.js ../../lib/action/*.js -t . -d ../../docs
+	node ./build-index.js

package/tools/jsdoc/README.md

@@ -0,0 +1,96 @@
+# JSDoc Workflow
+
+This directory contains the custom JSDoc template, the landing-page generator,
+and the staging script used to prepare the docs content that is published to the
+`gh-pages` branch.
+
+## Commands
+
+### `npm run docs`
+
+Build local docs for the current workspace version.
+
+Output:
+
+- `docs/<current-version>/`
+- `docs/index.html`
+
+Use this to verify the docs for the version currently declared in
+`package.json`.
+
+### `npm run docs:gh-pages`
+
+Stage the publishable docs tree under `build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the currently published version set from `origin/gh-pages`
+- preserves that published history
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This is the normal command to use for a new release.
+
+If you delete `build/` and rerun `npm run docs:gh-pages`, the staged tree will
+still contain all currently published versions. That command recreates
+`build/gh-pages-docs/` by copying the published docs snapshot from
+`origin/gh-pages`, then regenerating only the current workspace version.
+
+### `npm run docs:gh-pages:full`
+
+Fully rebuild the currently published docs history under
+`build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the published version set from `origin/gh-pages`
+- rebuilds only those published versions from tags
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This does **not** rebuild docs for every historical `rclnodejs` tag. It only
+rebuilds the subset that is actually published online.
+
+## New Release Example
+
+For a new release such as `1.9.0`:
+
+1. Update `package.json` to `1.9.0`.
+2. Run `npm run docs`.
+3. Verify the local output in `docs/1.9.0/` and `docs/index.html`.
+4. Run `npm run docs:gh-pages`.
+5. Verify the staged output in:
+   - `build/gh-pages-docs/docs/1.9.0/`
+   - `build/gh-pages-docs/docs/index.html`
+   - `build/gh-pages-docs/.nojekyll`
+6. Publish the contents of `build/gh-pages-docs/` to the `gh-pages` branch.
+
+## Manual Landing Page Rebuild
+
+If the staged docs tree already exists and you only want to rebuild
+`build/gh-pages-docs/docs/index.html`, run `tools/jsdoc/build-index.js` against
+that docs root and point it at the package metadata for the latest published
+version.
+
+Example for published version `1.8.0`:
+
+```bash
+mkdir -p build/gh-pages-docs/.tmp
+git show 1.8.0:package.json > build/gh-pages-docs/.tmp/package-1.8.0.json
+
+export RCLNODEJS_DOCS_ROOT="$PWD/build/gh-pages-docs/docs"
+export RCLNODEJS_DOCS_INDEX_PATH="$PWD/build/gh-pages-docs/docs/index.html"
+export RCLNODEJS_LOCAL_INDEX_PATH=''
+export RCLNODEJS_PACKAGE_JSON_PATH="$PWD/build/gh-pages-docs/.tmp/package-1.8.0.json"
+
+node tools/jsdoc/build-index.js
+rm -rf build/gh-pages-docs/.tmp
+```
+
+## Notes
+
+- The staged publish output keeps shared assets in `build/gh-pages-docs/docs/_static/`.
+- `.nojekyll` must remain in the staged output because the published docs tree
+  uses an underscore-prefixed directory.
+- The live docs index is the source of truth for which versions should remain
+  published.