rclnodejs 1.9.0-alpha.0 → 2.0.0-beta.0

package/src/rcl_action_client_bindings.cpp

@@ -250,7 +250,7 @@ Napi::Value ActionSendCancelRequest(const Napi::CallbackInfo& info) {
   return Napi::Number::New(env, static_cast<double>(sequence_number));
 }
 
-#if ROS_VERSION >= 5000  // ROS2 Rolling
+#if ROS_VERSION >= 2605  // ROS2 Lyrical or newer
 Napi::Value ActionConfigureFeedbackSubFilterAddGoalId(
     const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
@@ -309,7 +309,7 @@ Napi::Value ActionConfigureFeedbackSubFilterRemoveGoalId(
 
   return Napi::Boolean::New(env, true);
 }
-#endif  // ROS_VERSION >= 5000
+#endif  // ROS_VERSION >= 2605
 
 #if ROS_VERSION >= 2505  // ROS2 >= Kilted
 Napi::Value ConfigureActionClientIntrospection(const Napi::CallbackInfo& info) {
@@ -369,14 +369,14 @@ Napi::Object InitActionClientBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("configureActionClientIntrospection",
               Napi::Function::New(env, ConfigureActionClientIntrospection));
 #endif                   // ROS_VERSION >= 2505
-#if ROS_VERSION >= 5000  // ROS2 Rolling
+#if ROS_VERSION >= 2605  // ROS2 Lyrical or newer
   exports.Set(
       "actionConfigureFeedbackSubFilterAddGoalId",
       Napi::Function::New(env, ActionConfigureFeedbackSubFilterAddGoalId));
   exports.Set(
       "actionConfigureFeedbackSubFilterRemoveGoalId",
       Napi::Function::New(env, ActionConfigureFeedbackSubFilterRemoveGoalId));
-#endif  // ROS_VERSION >= 5000
+#endif  // ROS_VERSION >= 2605
   return exports;
 }
 

package/src/rcl_graph_bindings.cpp

@@ -33,12 +33,12 @@ typedef rcl_ret_t (*rcl_get_info_by_topic_func_t)(
     const char* topic_name, bool no_mangle,
     rcl_topic_endpoint_info_array_t* info_array);
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 typedef rcl_ret_t (*rcl_get_info_by_service_func_t)(
     const rcl_node_t* node, rcutils_allocator_t* allocator,
     const char* service_name, bool no_mangle,
     rcl_service_endpoint_info_array_t* info_array);
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
 Napi::Value GetPublisherNamesAndTypesByNode(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
@@ -264,7 +264,7 @@ Napi::Value GetSubscriptionsInfoByTopic(const Napi::CallbackInfo& info) {
                         "subscriptions", rcl_get_subscriptions_info_by_topic);
 }
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 Napi::Value GetInfoByService(
     Napi::Env env, rcl_node_t* node, const char* service_name, bool no_mangle,
     const char* type, rcl_get_info_by_service_func_t rcl_get_info_by_service) {
@@ -300,9 +300,9 @@ Napi::Value GetInfoByService(
 
   return ConvertToJSServiceEndpointInfoList(env, &info_array);
 }
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 Napi::Value GetClientsInfoByService(const Napi::CallbackInfo& info) {
   RclHandle* node_handle = RclHandle::Unwrap(info[0].As<Napi::Object>());
   rcl_node_t* node = reinterpret_cast<rcl_node_t*>(node_handle->ptr());
@@ -322,7 +322,7 @@ Napi::Value GetServersInfoByService(const Napi::CallbackInfo& info) {
   return GetInfoByService(info.Env(), node, service_name.c_str(), no_mangle,
                           "servers", rcl_get_servers_info_by_service);
 }
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
 Napi::Object InitGraphBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("getPublisherNamesAndTypesByNode",
@@ -341,12 +341,12 @@ Napi::Object InitGraphBindings(Napi::Env env, Napi::Object exports) {
               Napi::Function::New(env, GetPublishersInfoByTopic));
   exports.Set("getSubscriptionsInfoByTopic",
               Napi::Function::New(env, GetSubscriptionsInfoByTopic));
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
   exports.Set("getClientsInfoByService",
               Napi::Function::New(env, GetClientsInfoByService));
   exports.Set("getServersInfoByService",
               Napi::Function::New(env, GetServersInfoByService));
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
   return exports;
 }
 

package/src/rcl_lifecycle_bindings.cpp

@@ -71,7 +71,7 @@ Napi::Value CreateLifecycleStateMachine(const Napi::CallbackInfo& info) {
   const rosidl_service_type_support_t* gs =
       GetServiceTypeSupport("lifecycle_msgs", "GetState");
 
-#if ROS_VERSION >= 5000  // ROS2 Rolling
+#if ROS_VERSION >= 2605  // ROS2 Lyrical or newer
   rcl_lifecycle_state_machine_options_t options =
       rcl_lifecycle_get_default_state_machine_options();
   options.enable_com_interface = info[1].As<Napi::Boolean>().Value();

package/src/rcl_subscription_bindings.cpp

@@ -265,7 +265,7 @@ Napi::Value GetSubscriptionTopic(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, topic);
 }
 
-#if ROS_VERSION > 2505  // Rolling only
+#if ROS_VERSION >= 2605  // ROS2 Lyrical or newer
 Napi::Value IsContentFilterSupported(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -491,7 +491,7 @@ Napi::Object InitSubscriptionBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("rclTakeRaw", Napi::Function::New(env, RclTakeRaw));
   exports.Set("getSubscriptionTopic",
               Napi::Function::New(env, GetSubscriptionTopic));
-#if ROS_VERSION > 2505  // Rolling only
+#if ROS_VERSION >= 2605  // ROS2 Lyrical or newer
   exports.Set("isContentFilterSupported",
               Napi::Function::New(env, IsContentFilterSupported));
 #endif

package/src/rcl_timer_bindings.cpp

@@ -78,6 +78,15 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
 
   bool lossless;
   int64_t period_nsec = info[2].As<Napi::BigInt>().Int64Value(&lossless);
+  bool autostart = true;
+  if (info.Length() > 3) {
+    if (!info[3].IsBoolean()) {
+      Napi::TypeError::New(env, "Timer autostart must be a boolean")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+    autostart = info[3].As<Napi::Boolean>().Value();
+  }
   rcl_timer_t* timer =
       reinterpret_cast<rcl_timer_t*>(malloc(sizeof(rcl_timer_t)));
   *timer = rcl_get_zero_initialized_timer();
@@ -85,8 +94,7 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
 #if ROS_VERSION > 2305  // After Iron.
   {
     rcl_ret_t ret = rcl_timer_init2(timer, clock, context, period_nsec, nullptr,
-                                    rcl_get_default_allocator(),
-                                    /*autostart=*/true);
+                                    rcl_get_default_allocator(), autostart);
     if (RCL_RET_OK != ret) {
       std::string error_msg = rcl_get_error_string().str;
       rcl_reset_error();
@@ -106,6 +114,17 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
       Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
       return env.Undefined();
     }
+    if (!autostart) {
+      rcl_ret_t cancel_ret = rcl_timer_cancel(timer);
+      if (RCL_RET_OK != cancel_ret) {
+        std::string error_msg = rcl_get_error_string().str;
+        rcl_reset_error();
+        rcl_timer_fini(timer);
+        free(timer);
+        Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
+        return env.Undefined();
+      }
+    }
   }
 #endif
 

package/src/rcl_utilities.cpp

@@ -124,7 +124,7 @@ Napi::Value ConvertToJSTopicEndpoint(
   return endpoint;
 }
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 Napi::Value ConvertToJSServiceEndpointInfo(
     Napi::Env env, const rmw_service_endpoint_info_t* service_endpoint_info) {
   Napi::Object endpoint = Napi::Object::New(env);
@@ -164,7 +164,7 @@ Napi::Value ConvertToJSServiceEndpointInfo(
 
   return endpoint;
 }
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
 uv_lib_t g_lib;
 Napi::Env g_env = nullptr;
@@ -308,7 +308,7 @@ Napi::Array ConvertToJSTopicEndpointInfoList(
   return list;
 }
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 Napi::Array ConvertToJSServiceEndpointInfoList(
     Napi::Env env, const rmw_service_endpoint_info_array_t* info_array) {
   Napi::Array list = Napi::Array::New(env, info_array->size);
@@ -319,7 +319,7 @@ Napi::Array ConvertToJSServiceEndpointInfoList(
   }
   return list;
 }
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
 char** AbstractArgsFromNapiArray(const Napi::Array& jsArgv) {
   size_t argc = jsArgv.Length();

package/src/rcl_utilities.h

@@ -51,10 +51,10 @@ void ExtractNamesAndTypes(rcl_names_and_types_t names_and_types,
 Napi::Array ConvertToJSTopicEndpointInfoList(
     Napi::Env env, const rmw_topic_endpoint_info_array_t* info_array);
 
-#if ROS_VERSION > 2505
+#if ROS_VERSION >= 2605
 Napi::Array ConvertToJSServiceEndpointInfoList(
     Napi::Env env, const rmw_service_endpoint_info_array_t* info_array);
-#endif  // ROS_VERSION > 2505
+#endif  // ROS_VERSION >= 2605
 
 Napi::Value ConvertToQoS(Napi::Env env, const rmw_qos_profile_t* qos_profile);
 

package/types/distro.d.ts

@@ -3,7 +3,16 @@ declare module 'rclnodejs' {
     /**
      * Valid ROS 2 distro short names
      */
-    type DistroName = 'eloquent' | 'foxy' | 'galactic' | 'humble' | 'rolling';
+    type DistroName =
+      | 'eloquent'
+      | 'foxy'
+      | 'galactic'
+      | 'humble'
+      | 'iron'
+      | 'jazzy'
+      | 'kilted'
+      | 'lyrical'
+      | 'rolling';
 
     /**
      * rclnodejs distro ID numbers
@@ -14,7 +23,12 @@ declare module 'rclnodejs' {
       FOXY = 2006,
       GALACTIC = 2105,
       HUMBLE = 2205,
+      IRON = 2305,
+      JAZZY = 2405,
+      KILTED = 2505,
+      LYRICAL = 2605,
       ROLLING = 5000,
+      FUTURE = 9999,
     }
 
     /**

package/types/node.d.ts

@@ -80,6 +80,13 @@ declare module 'rclnodejs' {
      * inspect and limit messages that it accepts.
      */
     contentFilter?: SubscriptionContentFilter;
+
+    /**
+     * If provided, declares read-only ROS parameters for the specified QoS policies.
+     * These can be overridden at startup via `--ros-args -p` or `--params-file`.
+     * If qos is a profile string, it will be resolved to a mutable QoS object.
+     */
+    qosOverridingOptions?: QoSOverridingOptions;
   }
 
   /**
@@ -97,14 +104,24 @@ declare module 'rclnodejs' {
    */
   const DEFAULT_OPTIONS: Options;
 
+  interface TimerInfo {
+    expectedCallTime: bigint;
+    actualCallTime: bigint;
+  }
+
+  interface TimerOptions {
+    autostart?: boolean;
+  }
+
   /**
    * Callback for receiving periodic interrupts from a Timer.
+   * Receives timer metadata when the underlying ROS distro exposes it.
    *
    * @remarks
    * See {@link Node.createTimer | Node.createTimer}
    * See {@link Timer}
    */
-  type TimerRequestCallback = () => void;
+  type TimerRequestCallback = (timerInfo?: TimerInfo) => void;
 
   /**
    * Callback indicating parameters are about to be declared or set.
@@ -123,6 +140,19 @@ declare module 'rclnodejs' {
     parameters: Parameter[]
   ) => rcl_interfaces.msg.SetParametersResult;
 
+  /**
+   * Callback invoked before parameter validation and setting.
+   * Receives the parameter list, must return a (possibly modified) parameter list.
+   * Returning an empty list rejects the set.
+   */
+  type PreSetParametersCallback = (parameters: Parameter[]) => Parameter[];
+
+  /**
+   * Callback invoked after parameters have been successfully set.
+   * For side effects only (return value is ignored).
+   */
+  type PostSetParametersCallback = (parameters: Parameter[]) => void;
+
   /**
    * Standard result of Node.getXXXNamesAndTypes() queries
    *
@@ -293,15 +323,18 @@ declare module 'rclnodejs' {
     /**
      * Create a Timer.
      *
-     * @param period - Elapsed time between interrupt events (milliseconds).
-     * @param callback - Called on timeout interrupt.
-     * @param clock - Optional clock to use for the timer.
+     * @param period - Elapsed time between interrupt events in nanoseconds.
+     * @param callback - Called when the timer fires. Receives a `TimerInfo` argument when available.
+     * @param optionsOrClock - Optional timer options or clock to use for the timer.
+     *   Supports `{ autostart?: boolean }` when an options object is provided.
+     * @param clock - Optional clock to use for the timer when options are provided.
      * @returns New instance of Timer.
      */
     createTimer(
       period: bigint,
       callback: TimerRequestCallback,
-      clock?: Clock
+      optionsOrClock?: TimerOptions | Clock | null,
+      clock?: Clock | null
     ): Timer;
 
     /**
@@ -749,6 +782,37 @@ declare module 'rclnodejs' {
      */
     removeOnSetParametersCallback(call: SetParametersCallback): void;
 
+    /**
+     * Add a callback invoked before parameter validation.
+     * The callback receives the parameter list and must return a (possibly modified)
+     * parameter list. Returning an empty list rejects the set.
+     *
+     * @param callback - The callback to add.
+     */
+    addPreSetParametersCallback(callback: PreSetParametersCallback): void;
+
+    /**
+     * Remove a pre-set parameters callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    removePreSetParametersCallback(callback: PreSetParametersCallback): void;
+
+    /**
+     * Add a callback invoked after parameters are successfully set.
+     * Useful for triggering side effects (e.g., reconfiguring a component).
+     *
+     * @param callback - The callback to add.
+     */
+    addPostSetParametersCallback(callback: PostSetParametersCallback): void;
+
+    /**
+     * Remove a post-set parameters callback.
+     *
+     * @param callback - The callback to remove.
+     */
+    removePostSetParametersCallback(callback: PostSetParametersCallback): void;
+
     /**
      * Get a remote node's published topics.
      *

package/types/parameter_event_handler.d.ts

@@ -97,6 +97,17 @@ declare module 'rclnodejs' {
       callback: (event: any) => void
     ): ParameterEventCallbackHandle;
 
+    /**
+     * Configure which node parameter events will be received.
+     *
+     * If nodeNames is omitted or empty, the node filter is cleared.
+     * Relative names are resolved against the handler node namespace.
+     *
+     * @param nodeNames - Node names to filter parameter events from.
+     * @returns True if the filter is active or was successfully cleared.
+     */
+    configureNodesFilter(nodeNames?: string[]): boolean;
+
     /**
      * Remove a previously added parameter event callback.
      *

package/types/qos.d.ts

@@ -134,4 +134,59 @@ declare module 'rclnodejs' {
       RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5,
     }
   }
+
+  /**
+   * Enum of overridable QoS policy kinds.
+   */
+  enum QoSPolicyKind {
+    HISTORY = 1,
+    DEPTH = 2,
+    RELIABILITY = 3,
+    DURABILITY = 4,
+    LIVELINESS = 5,
+    AVOID_ROS_NAMESPACE_CONVENTIONS = 6,
+  }
+
+  /**
+   * Options for overriding QoS policies via ROS parameters.
+   *
+   * When passed to `createPublisher()` or `createSubscription()`, the node
+   * declares read-only parameters for each specified policy kind. These
+   * parameters can be overridden at startup via `--ros-args -p` or `--params-file`.
+   *
+   * Parameter naming convention:
+   *   `qos_overrides.<topic>.<publisher|subscription>[_<entityId>].<policy>`
+   */
+  class QoSOverridingOptions {
+    /**
+     * @param policyKinds - Which QoS policies to expose as parameters.
+     * @param opts - Optional callback and entityId.
+     */
+    constructor(
+      policyKinds: QoSPolicyKind[],
+      opts?: {
+        callback?: (qos: QoS) => { successful: boolean; reason?: string };
+        entityId?: string;
+      }
+    );
+
+    /** Which QoS policies are exposed as parameters. */
+    readonly policyKinds: QoSPolicyKind[];
+
+    /** Optional validation callback. */
+    readonly callback:
+      | ((qos: QoS) => { successful: boolean; reason?: string })
+      | null;
+
+    /** Optional entity disambiguation suffix. */
+    readonly entityId: string | null;
+
+    /**
+     * Create options that override history, depth, and reliability.
+     */
+    static withDefaultPolicies(opts?: {
+      callback?: (qos: QoS) => { successful: boolean; reason?: string };
+      entityId?: string;
+    }): QoSOverridingOptions;
+  }
 }

package/types/timer.d.ts

@@ -78,8 +78,9 @@ declare module 'rclnodejs' {
 
     /**
      * Call a timer and starts counting again, retrieves actual and expected call time.
-     * @return - The timer information.
+     *
+     * @return The timer information with expected and actual call timestamps.
      */
-    callTimerWithInfo(): object;
+    callTimerWithInfo(): TimerInfo;
   }
 }

package/tools/jsdoc/Makefile

@@ -1,5 +0,0 @@
-.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

@@ -1,96 +0,0 @@
-# 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.