rclnodejs 1.9.0-alpha.0 → 1.9.0

package/index.js

@@ -39,6 +39,10 @@ const {
 } = require('./lib/parameter.js');
 const path = require('path');
 const QoS = require('./lib/qos.js');
+const {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+} = require('./lib/qos_overriding_options.js');
 const rclnodejs = require('./lib/native_loader.js');
 const tsdGenerator = require('./rostsd_gen/index.js');
 const validator = require('./lib/validator.js');
@@ -258,6 +262,12 @@ let rcl = {
   /** {@link QoS} class */
   QoS: QoS,
 
+  /** {@link QoSPolicyKind} enum */
+  QoSPolicyKind: QoSPolicyKind,
+
+  /** {@link QoSOverridingOptions} class */
+  QoSOverridingOptions: QoSOverridingOptions,
+
   /** {@link RMWUtils} */
   RMWUtils: RMWUtils,
 

package/lib/action/server_goal_handle.js

@@ -82,11 +82,26 @@ class ServerGoalHandle {
   }
 
   /**
-   * Updates the goal handle with the execute status and begins exection.
+   * Transitions the goal to the executing state and begins execution.
+   * Has no effect if the goal is already executing, no longer active, or destroyed.
    * @param {function} callback - An optional callback to use instead of the one provided to the action server.
    * @returns {undefined}
    */
   execute(callback) {
+    if (this._destroyed) {
+      return;
+    }
+
+    // Guard: already executing — no-op
+    if (this.status === ActionInterfaces.GoalStatus.STATUS_EXECUTING) {
+      return;
+    }
+
+    // Guard: only transition if goal is still active
+    if (!this.isActive) {
+      return;
+    }
+
     if (!this.isCancelRequested) {
       this._updateState(GoalEvent.EXECUTE);
     }
@@ -105,6 +120,16 @@ class ServerGoalHandle {
       return;
     }
 
+    if (this.status !== ActionInterfaces.GoalStatus.STATUS_EXECUTING) {
+      this._actionServer._node
+        .getLogger()
+        .warn(
+          `publishFeedback() called on goal ${this.goalId.uuid} ` +
+            `in status ${this.status}, not executing; ignoring`
+        );
+      return;
+    }
+
     let feedbackMessage =
       new this._actionServer.typeClass.impl.FeedbackMessage();
     feedbackMessage['goal_id'] = this.goalId;

package/lib/node.js

@@ -48,6 +48,10 @@ const Service = require('./service.js');
 const Subscription = require('./subscription.js');
 const ObservableSubscription = require('./observable_subscription.js');
 const MessageInfo = require('./message_info.js');
+const {
+  declareQosParameters,
+  _resolveQoS,
+} = require('./qos_overriding_options.js');
 const TimeSource = require('./time_source.js');
 const Timer = require('./timer.js');
 const TypeDescriptionService = require('./type_description_service.js');
@@ -157,7 +161,9 @@ class Node extends rclnodejs.ShadowNode {
     this._parameterService = null;
     this._typeDescriptionService = null;
     this._parameterEventPublisher = null;
+    this._preSetParametersCallbacks = [];
     this._setParametersCallbacks = [];
+    this._postSetParametersCallbacks = [];
     this._logger = new Logging(rclnodejs.getNodeLoggerName(this.handle));
     this._spinning = false;
     this._enableRosout = options.enableRosout;
@@ -250,8 +256,14 @@ class Node extends rclnodejs.ShadowNode {
 
     timersReady.forEach((timer) => {
       if (timer.isReady()) {
-        rclnodejs.callTimer(timer.handle);
-        timer.callback();
+        let timerInfo;
+        if (typeof rclnodejs.callTimerWithInfo === 'function') {
+          timerInfo = rclnodejs.callTimerWithInfo(timer.handle);
+          timer.callback(timerInfo);
+        } else {
+          rclnodejs.callTimer(timer.handle);
+          timer.callback();
+        }
       }
     });
 
@@ -622,15 +634,43 @@ class Node extends rclnodejs.ShadowNode {
   /**
    * Create a Timer.
    * @param {bigint} period - The number representing period in nanoseconds.
-   * @param {function} callback - The callback to be called when timeout.
-   * @param {Clock} [clock] - The clock which the timer gets time from.
+   * @param {function} callback - The callback to be called when the timer fires.
+   *   On distros with native support, the callback receives a `TimerInfo` object
+   *   describing the expected and actual call time.
+   * @param {object|Clock} [optionsOrClock] - Timer options or the clock which the timer gets time from.
+   *   Supported options: `{ autostart?: boolean }`.
+   * @param {Clock} [clock] - The clock which the timer gets time from when options are provided.
    * @return {Timer} - An instance of Timer.
    */
-  createTimer(period, callback, clock = null) {
-    if (arguments.length === 3 && !(arguments[2] instanceof Clock)) {
-      clock = null;
-    } else if (arguments.length === 4) {
-      clock = arguments[3];
+  createTimer(period, callback, optionsOrClock = null, clock = null) {
+    let options = {};
+
+    if (optionsOrClock instanceof Clock.Clock) {
+      clock = optionsOrClock;
+    } else if (optionsOrClock === null || optionsOrClock === undefined) {
+      // Keep the 4th argument as the clock when the 3rd argument is omitted or explicitly null.
+    } else {
+      if (typeof optionsOrClock !== 'object' || Array.isArray(optionsOrClock)) {
+        throw new TypeValidationError(
+          'options',
+          optionsOrClock,
+          'object or Clock',
+          {
+            nodeName: this.name(),
+          }
+        );
+      }
+      options = optionsOrClock;
+    }
+
+    if (
+      arguments.length === 4 &&
+      clock !== null &&
+      !(clock instanceof Clock.Clock)
+    ) {
+      throw new TypeValidationError('clock', clock, 'Clock', {
+        nodeName: this.name(),
+      });
     }
 
     if (typeof period !== 'bigint') {
@@ -643,12 +683,27 @@ class Node extends rclnodejs.ShadowNode {
         nodeName: this.name(),
       });
     }
+    if (
+      options.autostart !== undefined &&
+      typeof options.autostart !== 'boolean'
+    ) {
+      throw new TypeValidationError(
+        'options.autostart',
+        options.autostart,
+        'boolean',
+        {
+          nodeName: this.name(),
+        }
+      );
+    }
 
     const timerClock = clock || this._clock;
+    const autostart = options.autostart ?? true;
     let timerHandle = rclnodejs.createTimer(
       timerClock.handle,
       this.context.handle,
-      period
+      period,
+      autostart
     );
     let timer = new Timer(timerHandle, period, callback);
     debug('Finish creating timer, period = %d.', period);
@@ -705,6 +760,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {object} options - The options argument used to parameterize the publisher.
    * @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 publisher, default: QoS.profileDefault.
+   * @param {QoSOverridingOptions} [options.qosOverridingOptions] - If provided, declares read-only ROS parameters
+   *  for the specified QoS policies (e.g. `qos_overrides./topic.publisher.depth`). 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 before overrides are applied.
    * @param {PublisherEventCallbacks} eventCallbacks - The event callbacks for the publisher.
    * @return {Publisher} - An instance of Publisher.
    */
@@ -752,6 +811,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'publisher',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let publisher = publisherClass.createPublisher(
       this,
       typeClass,
@@ -795,6 +869,10 @@ class Node extends rclnodejs.ShadowNode {
    * @param {string[]} [options.contentFilter.parameters=undefined] - Array of strings that give values to
    *  the ‘parameters’ (i.e., "%n" tokens) in the filter_expression. The number of supplied parameters must
    *  fit with the requested values in the filter_expression (i.e., the number of %n tokens). default: undefined.
+   * @param {QoSOverridingOptions} [options.qosOverridingOptions] - If provided, declares read-only ROS parameters
+   *  for the specified QoS policies (e.g. `qos_overrides./topic.subscription.depth`). 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 before overrides are applied.
    * @param {SubscriptionCallback} callback - The callback to be call when receiving the topic subscribed. The topic will be an instance of null-terminated Buffer when options.isRaw is true.
    * @param {SubscriptionEventCallbacks} eventCallbacks - The event callbacks for the subscription.
    * @return {Subscription} - An instance of Subscription.
@@ -848,6 +926,21 @@ class Node extends rclnodejs.ShadowNode {
       );
     }
 
+    // Apply QoS overriding options if provided
+    if (options.qosOverridingOptions) {
+      const resolvedTopic = this.resolveTopicName(topic);
+      if (typeof options.qos === 'string' || !(options.qos instanceof QoS)) {
+        options.qos = _resolveQoS(options.qos);
+      }
+      declareQosParameters(
+        'subscription',
+        this,
+        resolvedTopic,
+        options.qos,
+        options.qosOverridingOptions
+      );
+    }
+
     let subscription = Subscription.createSubscription(
       this,
       typeClass,
@@ -2015,6 +2108,29 @@ class Node extends rclnodejs.ShadowNode {
    * @return {SetParameterResult} - A single collective result.
    */
   _setParametersAtomically(parameters = [], declareParameterMode = false) {
+    // 1) PRE callbacks — pipeline: each callback receives the output of the previous
+    if (this._preSetParametersCallbacks.length > 0) {
+      for (const callback of this._preSetParametersCallbacks) {
+        const result = callback(parameters);
+        if (!Array.isArray(result)) {
+          return {
+            successful: false,
+            reason:
+              'pre-set parameters callback must return an array of Parameters',
+          };
+        }
+        parameters = result;
+        if (parameters.length === 0) {
+          return {
+            successful: false,
+            reason:
+              'parameter list is empty after pre-set callback; set rejected',
+          };
+        }
+      }
+    }
+
+    // 2) Validate
     let result = this._validateParameters(parameters, declareParameterMode);
     if (!result.successful) {
       return result;
@@ -2084,6 +2200,11 @@ class Node extends rclnodejs.ShadowNode {
     // Publish ParameterEvent.
     this._parameterEventPublisher.publish(parameterEvent);
 
+    // POST callbacks — for side effects after successful set
+    for (const callback of this._postSetParametersCallbacks) {
+      callback(parameters);
+    }
+
     return {
       successful: true,
       reason: '',
@@ -2128,6 +2249,82 @@ class Node extends rclnodejs.ShadowNode {
     }
   }
 
+  /**
+   * A callback invoked before parameter validation and setting.
+   * It receives the parameter list and must return a (possibly modified) parameter list.
+   *
+   * @callback PreSetParametersCallback
+   * @param {Parameter[]} parameters - The parameters about to be set.
+   * @returns {Parameter[]} - The modified parameter list to proceed with.
+   *
+   * @see [Node.addPreSetParametersCallback]{@link Node#addPreSetParametersCallback}
+   * @see [Node.removePreSetParametersCallback]{@link Node#removePreSetParametersCallback}
+   */
+
+  /**
+   * Add a callback invoked before parameter validation.
+   * The callback receives the parameter list and must return a (possibly modified)
+   * parameter list. This can be used to coerce, add, or remove parameters before
+   * they are validated and applied. If any pre-set callback returns an empty list,
+   * the set is rejected.
+   *
+   * @param {PreSetParametersCallback} callback - The callback to add.
+   * @returns {undefined}
+   */
+  addPreSetParametersCallback(callback) {
+    this._preSetParametersCallbacks.unshift(callback);
+  }
+
+  /**
+   * Remove a pre-set parameters callback.
+   *
+   * @param {PreSetParametersCallback} callback - The callback to remove.
+   * @returns {undefined}
+   */
+  removePreSetParametersCallback(callback) {
+    const idx = this._preSetParametersCallbacks.indexOf(callback);
+    if (idx > -1) {
+      this._preSetParametersCallbacks.splice(idx, 1);
+    }
+  }
+
+  /**
+   * A callback invoked after parameters have been successfully set.
+   * It receives the final parameter list. For side effects only (return value is ignored).
+   *
+   * @callback PostSetParametersCallback
+   * @param {Parameter[]} parameters - The parameters that were set.
+   * @returns {undefined}
+   *
+   * @see [Node.addPostSetParametersCallback]{@link Node#addPostSetParametersCallback}
+   * @see [Node.removePostSetParametersCallback]{@link Node#removePostSetParametersCallback}
+   */
+
+  /**
+   * Add a callback invoked after parameters are successfully set.
+   * The callback receives the final parameter list. Useful for triggering
+   * side effects (e.g., reconfiguring a component when a parameter changes).
+   *
+   * @param {PostSetParametersCallback} callback - The callback to add.
+   * @returns {undefined}
+   */
+  addPostSetParametersCallback(callback) {
+    this._postSetParametersCallbacks.unshift(callback);
+  }
+
+  /**
+   * Remove a post-set parameters callback.
+   *
+   * @param {PostSetParametersCallback} callback - The callback to remove.
+   * @returns {undefined}
+   */
+  removePostSetParametersCallback(callback) {
+    const idx = this._postSetParametersCallbacks.indexOf(callback);
+    if (idx > -1) {
+      this._postSetParametersCallbacks.splice(idx, 1);
+    }
+  }
+
   /**
    * Get the fully qualified name of the node.
    *

package/lib/parameter_event_handler.js

@@ -16,6 +16,7 @@
 
 const { TypeValidationError, OperationError } = require('./errors');
 const { normalizeNodeName } = require('./utils');
+const validator = require('./validator');
 const debug = require('debug')('rclnodejs:parameter_event_handler');
 
 const PARAMETER_EVENT_MSG_TYPE = 'rcl_interfaces/msg/ParameterEvent';
@@ -210,6 +211,64 @@ class ParameterEventHandler {
     return handle;
   }
 
+  /**
+   * Configure which node parameter events will be received.
+   *
+   * If nodeNames is omitted or empty, the current node filter is cleared.
+   * When a filter is active, parameter and event callbacks only receive
+   * events from the specified nodes.
+   *
+   * @param {string[]} [nodeNames] - Node names to filter parameter events from.
+   *   Relative names are resolved against the handler node namespace.
+   * @returns {boolean} True if the filter is active or was successfully cleared.
+   */
+  configureNodesFilter(nodeNames) {
+    this.#checkNotDestroyed();
+
+    if (nodeNames === undefined || nodeNames === null) {
+      this.#subscription.clearContentFilter();
+      return !this.#subscription.hasContentFilter();
+    }
+
+    if (!Array.isArray(nodeNames)) {
+      throw new TypeValidationError('nodeNames', nodeNames, 'string[]', {
+        entityType: 'parameter event handler',
+      });
+    }
+
+    if (nodeNames.length === 0) {
+      this.#subscription.clearContentFilter();
+      return !this.#subscription.hasContentFilter();
+    }
+
+    const resolvedNodeNames = nodeNames.map((nodeName, index) => {
+      if (typeof nodeName !== 'string' || nodeName.trim() === '') {
+        throw new TypeValidationError(
+          `nodeNames[${index}]`,
+          nodeName,
+          'non-empty string',
+          {
+            entityType: 'parameter event handler',
+          }
+        );
+      }
+
+      const resolvedNodeName = this.#resolvePath(nodeName.trim());
+      this.#validateFullyQualifiedNodePath(resolvedNodeName);
+      return resolvedNodeName;
+    });
+
+    const contentFilter = {
+      expression: resolvedNodeNames
+        .map((_, index) => `node = %${index}`)
+        .join(' OR '),
+      parameters: resolvedNodeNames.map((nodeName) => `'${nodeName}'`),
+    };
+
+    this.#subscription.setContentFilter(contentFilter);
+    return this.#subscription.hasContentFilter();
+  }
+
   /**
    * Remove a previously added parameter callback.
    *
@@ -450,6 +509,45 @@ class ParameterEventHandler {
     return `${paramName}\0${nodeName}`;
   }
 
+  /**
+   * Resolve a node path to the fully qualified name used in ParameterEvent.node.
+   * @private
+   */
+  #resolvePath(nodePath) {
+    // Absolute node paths are already rooted. Relative names are resolved
+    // against the handler node namespace before building the content filter.
+    const unresolvedPath = nodePath.startsWith('/')
+      ? nodePath
+      : `${this.#node.namespace().replace(/\/+$/, '')}/${nodePath}`;
+
+    // Collapse repeated separators for inputs like '/ns//node/' or 'nested//node'.
+    const resolvedPath = unresolvedPath.replace(/\/+/g, '/');
+
+    // Preserve the root namespace as '/' and strip trailing slashes everywhere
+    // else so the filter matches the canonical ParameterEvent.node format.
+    if (resolvedPath === '/') {
+      return resolvedPath;
+    }
+
+    return resolvedPath.replace(/\/+$/, '');
+  }
+
+  /**
+   * Validate a fully qualified node path before using it in a content filter.
+   * @private
+   */
+  #validateFullyQualifiedNodePath(nodePath) {
+    const normalizedPath =
+      nodePath.length > 1 ? nodePath.replace(/\/+$/, '') : nodePath;
+    const separatorIndex = normalizedPath.lastIndexOf('/');
+    const nodeNamespace =
+      separatorIndex === 0 ? '/' : normalizedPath.slice(0, separatorIndex);
+    const nodeName = normalizedPath.slice(separatorIndex + 1);
+
+    validator.validateNamespace(nodeNamespace);
+    validator.validateNodeName(nodeName);
+  }
+
   /**
    * Check if the handler has been destroyed and throw if so.
    * @private

package/lib/qos_overriding_options.js

@@ -0,0 +1,358 @@
+// Copyright (c) 2026 The Robot Web Tools Contributors. 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';
+
+const QoS = require('./qos.js');
+const {
+  Parameter,
+  ParameterType,
+  ParameterDescriptor,
+} = require('./parameter.js');
+
+/**
+ * Enum of overridable QoS policy kinds.
+ * Each value corresponds to a QoS property on the {@link QoS} class.
+ * @enum {number}
+ */
+const QoSPolicyKind = Object.freeze({
+  HISTORY: 1,
+  DEPTH: 2,
+  RELIABILITY: 3,
+  DURABILITY: 4,
+  LIVELINESS: 5,
+  AVOID_ROS_NAMESPACE_CONVENTIONS: 6,
+});
+
+// Maps QoSPolicyKind -> { qosProp, paramKey, paramType, toParam, fromParam }
+const POLICY_MAP = {
+  [QoSPolicyKind.HISTORY]: {
+    qosProp: 'history',
+    paramKey: 'history',
+    enumObj: QoS.HistoryPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DEPTH]: {
+    qosProp: 'depth',
+    paramKey: 'depth',
+    paramType: ParameterType.PARAMETER_INTEGER,
+    toParam: (val) => BigInt(val),
+    fromParam: (val) => Number(val),
+  },
+  [QoSPolicyKind.RELIABILITY]: {
+    qosProp: 'reliability',
+    paramKey: 'reliability',
+    enumObj: QoS.ReliabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.DURABILITY]: {
+    qosProp: 'durability',
+    paramKey: 'durability',
+    enumObj: QoS.DurabilityPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.LIVELINESS]: {
+    qosProp: 'liveliness',
+    paramKey: 'liveliness',
+    enumObj: QoS.LivelinessPolicy,
+    paramType: ParameterType.PARAMETER_STRING,
+    toParam: (val, enumObj) => _enumToString(val, enumObj),
+    fromParam: (val, enumObj) => _stringToEnum(val, enumObj),
+  },
+  [QoSPolicyKind.AVOID_ROS_NAMESPACE_CONVENTIONS]: {
+    qosProp: 'avoidRosNameSpaceConventions',
+    paramKey: 'avoid_ros_namespace_conventions',
+    paramType: ParameterType.PARAMETER_BOOL,
+    toParam: (val) => val,
+    fromParam: (val) => Boolean(val),
+  },
+};
+
+/**
+ * Convert a numeric enum value to a lowercase string name.
+ * @param {number} val - enum numeric value
+ * @param {Object} enumObj - the enum object (e.g. QoS.HistoryPolicy)
+ * @returns {string}
+ */
+function _enumToString(val, enumObj) {
+  for (const [key, v] of Object.entries(enumObj)) {
+    if (v === val) {
+      // Strip the RMW prefix: "RMW_QOS_POLICY_HISTORY_KEEP_LAST" -> "keep_last"
+      const parts = key.split('_');
+      // Find the index after the policy name (HISTORY, RELIABILITY, etc.)
+      // Pattern: RMW_QOS_POLICY_<POLICY>_<VALUE>
+      const policyNames = [
+        'HISTORY',
+        'RELIABILITY',
+        'DURABILITY',
+        'LIVELINESS',
+      ];
+      let valueStart = 4; // default: skip RMW_QOS_POLICY_<X>_
+      for (let i = 3; i < parts.length; i++) {
+        if (policyNames.includes(parts[i])) {
+          valueStart = i + 1;
+          break;
+        }
+      }
+      return parts.slice(valueStart).join('_').toLowerCase();
+    }
+  }
+  return String(val);
+}
+
+/**
+ * Convert a lowercase string back to a numeric enum value.
+ * @param {string} str - the string value (e.g. "keep_last")
+ * @param {Object} enumObj - the enum object
+ * @returns {number}
+ */
+function _stringToEnum(str, enumObj) {
+  const upper = str.toUpperCase();
+  for (const [key, val] of Object.entries(enumObj)) {
+    if (key.endsWith('_' + upper)) {
+      return val;
+    }
+  }
+  throw new Error(`Unknown QoS policy value: "${str}"`);
+}
+
+/**
+ * Options for overriding QoS policies via ROS parameters.
+ *
+ * When passed to `createPublisher()` or `createSubscription()`, the node
+ * will declare read-only parameters for each specified policy kind. These
+ * parameters can be set via command-line arguments, launch files, or
+ * parameter files to override the QoS profile at startup.
+ *
+ * Parameter naming convention:
+ *   `qos_overrides.<topic>.<publisher|subscription>[_<entityId>].<policy>`
+ *
+ * @example
+ * // Override history, depth, and reliability via parameters
+ * const sub = node.createSubscription(
+ *   'std_msgs/msg/String', '/chatter',
+ *   { qos: rclnodejs.QoS.profileDefault,
+ *     qosOverridingOptions: QoSOverridingOptions.withDefaultPolicies() },
+ *   (msg) => console.log(msg.data)
+ * );
+ * // Now you can override via CLI:
+ * //   --ros-args -p "qos_overrides./chatter.subscription.depth:=20"
+ */
+class QoSOverridingOptions {
+  /**
+   * @param {Array<QoSPolicyKind>} policyKinds - Which QoS policies to expose as parameters.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Optional validation callback. Receives the
+   *   final QoS profile after overrides are applied. Should return
+   *   `{successful: true}` or `{successful: false, reason: '...'}`.
+   * @param {string} [opts.entityId] - Optional suffix to disambiguate multiple
+   *   publishers/subscriptions on the same topic.
+   */
+  constructor(policyKinds, opts = {}) {
+    this._policyKinds = Array.from(policyKinds);
+    this._callback = opts.callback || null;
+    this._entityId = opts.entityId || null;
+  }
+
+  get policyKinds() {
+    return this._policyKinds;
+  }
+
+  get callback() {
+    return this._callback;
+  }
+
+  get entityId() {
+    return this._entityId;
+  }
+
+  /**
+   * Create options that override history, depth, and reliability —
+   * the most commonly tuned policies.
+   * @param {Object} [opts]
+   * @param {function} [opts.callback] - Validation callback.
+   * @param {string} [opts.entityId] - Entity disambiguation suffix.
+   * @returns {QoSOverridingOptions}
+   */
+  static withDefaultPolicies(opts = {}) {
+    return new QoSOverridingOptions(
+      [QoSPolicyKind.HISTORY, QoSPolicyKind.DEPTH, QoSPolicyKind.RELIABILITY],
+      opts
+    );
+  }
+}
+
+/**
+ * Resolve QoS profile string to a mutable QoS object.
+ * If already a QoS instance, return as-is.
+ * @param {QoS|string} qos
+ * @returns {QoS}
+ */
+function _resolveQoS(qos) {
+  if (qos instanceof QoS) {
+    return qos;
+  }
+  // Plain object with QoS fields — construct a QoS from its properties
+  if (typeof qos === 'object' && qos !== null && !Array.isArray(qos)) {
+    return new QoS(
+      qos.history,
+      qos.depth,
+      qos.reliability,
+      qos.durability,
+      qos.liveliness,
+      qos.avoidRosNameSpaceConventions
+    );
+  }
+  // Profile string: create a QoS with the corresponding defaults
+  // Values must match the rmw_qos_profile_* definitions in rmw/types.h
+  switch (qos) {
+    case QoS.profileDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileSystemDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_SYSTEM_DEFAULT,
+        0,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT,
+        QoS.LivelinessPolicy.RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT
+      );
+    case QoS.profileSensorData:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        5,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileServicesDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileParameters:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1000,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileParameterEvents:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1000,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+    case QoS.profileActionStatusDefault:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        1,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL
+      );
+    default:
+      return new QoS(
+        QoS.HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST,
+        10,
+        QoS.ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_RELIABLE,
+        QoS.DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE
+      );
+  }
+}
+
+/**
+ * Declare QoS override parameters on the node and apply any overrides
+ * to the QoS profile in-place.
+ *
+ * @param {'publisher'|'subscription'} entityType
+ * @param {Node} node
+ * @param {string} topic - Fully resolved topic name.
+ * @param {QoS} qos - Mutable QoS object (will be modified in-place).
+ * @param {QoSOverridingOptions} options
+ */
+function declareQosParameters(entityType, node, topic, qos, options) {
+  if (!options || options.policyKinds.length === 0) {
+    return;
+  }
+
+  const idSuffix = options.entityId ? `_${options.entityId}` : '';
+  const namePrefix = `qos_overrides.${topic}.${entityType}${idSuffix}`;
+
+  for (const policyKind of options.policyKinds) {
+    const mapping = POLICY_MAP[policyKind];
+    if (!mapping) {
+      continue;
+    }
+
+    const paramName = `${namePrefix}.${mapping.paramKey}`;
+    const currentValue = qos[mapping.qosProp];
+    const paramValue = mapping.toParam(currentValue, mapping.enumObj);
+
+    const descriptor = new ParameterDescriptor(
+      paramName,
+      mapping.paramType,
+      `QoS override for ${mapping.qosProp}`,
+      true // readOnly
+    );
+
+    let param;
+    try {
+      param = node.declareParameter(
+        new Parameter(paramName, mapping.paramType, paramValue),
+        descriptor
+      );
+    } catch (e) {
+      // Already declared (e.g. multiple entities on same topic) — reuse
+      if (node.hasParameter(paramName)) {
+        param = node.getParameter(paramName);
+      } else {
+        throw e;
+      }
+    }
+
+    // Apply the (possibly overridden) parameter value back to QoS
+    if (param && param.value !== paramValue) {
+      qos[mapping.qosProp] = mapping.fromParam(param.value, mapping.enumObj);
+    }
+  }
+
+  // Run validation callback if provided
+  if (options.callback) {
+    const result = options.callback(qos);
+    if (result && !result.successful) {
+      throw new Error(
+        `QoS override validation failed: ${result.reason || 'unknown reason'}`
+      );
+    }
+  }
+}
+
+module.exports = {
+  QoSPolicyKind,
+  QoSOverridingOptions,
+  declareQosParameters,
+  _resolveQoS,
+};

package/lib/timer.js

@@ -150,7 +150,7 @@ class Timer {
 
   /**
    * Call a timer and starts counting again, retrieves actual and expected call time.
-   * @return {object} - The timer information.
+   * @return {{expectedCallTime: bigint, actualCallTime: bigint}} - The timer information.
    */
   callTimerWithInfo() {
     if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rclnodejs",
-  "version": "1.9.0-alpha.0",
+  "version": "1.9.0",
   "description": "ROS2.0 JavaScript client with Node.js",
   "main": "index.js",
   "types": "types/index.d.ts",
@@ -67,7 +67,7 @@
     "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.0",
     "mocha": "^11.0.2",
-    "node-gyp": "^12.1.0",
+    "node-gyp": "^10.3.1",
     "nyc": "^18.0.0",
     "prebuildify": "^6.0.1",
     "rimraf": "^6.0.1",

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/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;
   }
 }