rclnodejs 1.6.0 → 1.8.0

package/lib/client.js

@@ -17,8 +17,59 @@
 const rclnodejs = require('./native_loader.js');
 const DistroUtils = require('./distro.js');
 const Entity = require('./entity.js');
+const {
+  TypeValidationError,
+  TimeoutError,
+  AbortError,
+} = require('./errors.js');
+const { assertValidMessage } = require('./message_validation.js');
 const debug = require('debug')('rclnodejs:client');
 
+// Polyfill for AbortSignal.any() for Node.js <= 20.3.0
+// AbortSignal.any() was added in Node.js 20.3.0
+// See https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static
+if (!AbortSignal.any) {
+  AbortSignal.any = function (signals) {
+    // Filter out null/undefined values and validate inputs
+    const validSignals = Array.isArray(signals)
+      ? signals.filter((signal) => signal != null)
+      : [];
+
+    // If no valid signals, return a never-aborting signal
+    if (validSignals.length === 0) {
+      return new AbortController().signal;
+    }
+
+    const controller = new AbortController();
+    const listeners = [];
+
+    // Cleanup function to remove all event listeners
+    const cleanup = () => {
+      listeners.forEach(({ signal, listener }) => {
+        signal.removeEventListener('abort', listener);
+      });
+    };
+
+    for (const signal of validSignals) {
+      if (signal.aborted) {
+        cleanup();
+        controller.abort(signal.reason);
+        return controller.signal;
+      }
+
+      const listener = () => {
+        cleanup();
+        controller.abort(signal.reason);
+      };
+
+      signal.addEventListener('abort', listener);
+      listeners.push({ signal, listener });
+    }
+
+    return controller.signal;
+  };
+}
+
 /**
  * @class - Class representing a Client in ROS
  * @hideconstructor
@@ -30,10 +81,43 @@ class Client extends Entity {
     this._nodeHandle = nodeHandle;
     this._serviceName = serviceName;
     this._sequenceNumberToCallbackMap = new Map();
+    this._validateRequests = options.validateRequests || false;
+    this._validationOptions = options.validationOptions || {
+      strict: true,
+      checkTypes: true,
+    };
+  }
+
+  /**
+   * Whether requests will be validated before sending.
+   * @type {boolean}
+   */
+  get willValidateRequest() {
+    return this._validateRequests;
+  }
+
+  /**
+   * Enable or disable request validation for this client.
+   * @param {boolean} value - Whether to validate requests
+   */
+  set willValidateRequest(value) {
+    this._validateRequests = value;
+  }
+
+  /**
+   * Set validation options for this client.
+   * @param {object} options - Validation options
+   * @param {boolean} [options.strict=true] - Throw on unknown fields
+   * @param {boolean} [options.checkTypes=true] - Validate field types
+   */
+  setValidation(options) {
+    if (options && Object.keys(options).length > 0) {
+      this._validationOptions = { ...this._validationOptions, ...options };
+    }
   }
 
   /**
-   * This callback is called when a resopnse is sent back from service
+   * This callback is called when a response is sent back from service
    * @callback ResponseCallback
    * @param {Object} response - The response sent from the service
    * @see [Client.sendRequest]{@link Client#sendRequest}
@@ -43,15 +127,34 @@ class Client extends Entity {
    */
 
   /**
-   * Send the request and will be notified asynchronously if receiving the repsonse.
+   * Send the request and will be notified asynchronously if receiving the response.
    * @param {object} request - The request to be submitted.
    * @param {ResponseCallback} callback - Thc callback function for receiving the server response.
+   * @param {object} [options] - Send options
+   * @param {boolean} [options.validate] - Override validateRequests setting for this call
    * @return {undefined}
+   * @throws {MessageValidationError} If validation is enabled and request is invalid
    * @see {@link ResponseCallback}
    */
-  sendRequest(request, callback) {
+  sendRequest(request, callback, options = {}) {
     if (typeof callback !== 'function') {
-      throw new TypeError('Invalid argument');
+      throw new TypeValidationError('callback', callback, 'function', {
+        entityType: 'service',
+        entityName: this._serviceName,
+      });
+    }
+
+    const shouldValidate =
+      options.validate !== undefined
+        ? options.validate
+        : this._validateRequests;
+
+    if (shouldValidate && !(request instanceof this._typeClass.Request)) {
+      assertValidMessage(
+        request,
+        this._typeClass.Request,
+        this._validationOptions
+      );
     }
 
     let requestToSend =
@@ -65,6 +168,117 @@ class Client extends Entity {
     this._sequenceNumberToCallbackMap.set(sequenceNumber, callback);
   }
 
+  /**
+   * Send the request and return a Promise that resolves with the response.
+   * @param {object} request - The request to be submitted.
+   * @param {object} [options] - Optional parameters for the request.
+   * @param {number} [options.timeout] - Timeout in milliseconds for the request.
+   * @param {AbortSignal} [options.signal] - AbortSignal to cancel the request.
+   * @param {boolean} [options.validate] - Override validateRequests setting for this call
+   * @return {Promise<object>} Promise that resolves with the service response.
+   * @throws {module:rclnodejs.TimeoutError} If the request times out (when options.timeout is exceeded).
+   * @throws {module:rclnodejs.AbortError} If the request is manually aborted (via options.signal).
+   * @throws {module:rclnodejs.MessageValidationError} If validation is enabled and request is invalid.
+   * @throws {Error} If the request fails for other reasons.
+   */
+  sendRequestAsync(request, options = {}) {
+    return new Promise((resolve, reject) => {
+      let sequenceNumber = null;
+      let isResolved = false;
+      let isTimeout = false;
+
+      const cleanup = () => {
+        if (sequenceNumber !== null) {
+          this._sequenceNumberToCallbackMap.delete(sequenceNumber);
+        }
+        isResolved = true;
+      };
+
+      let effectiveSignal = options.signal;
+
+      if (options.timeout !== undefined && options.timeout >= 0) {
+        const timeoutSignal = AbortSignal.timeout(options.timeout);
+
+        timeoutSignal.addEventListener('abort', () => {
+          isTimeout = true;
+        });
+
+        if (options.signal) {
+          effectiveSignal = AbortSignal.any([options.signal, timeoutSignal]);
+        } else {
+          effectiveSignal = timeoutSignal;
+        }
+      }
+
+      if (effectiveSignal) {
+        if (effectiveSignal.aborted) {
+          const error = isTimeout
+            ? new TimeoutError('Service request', options.timeout, {
+                entityType: 'service',
+                entityName: this._serviceName,
+              })
+            : new AbortError('Service request', undefined, {
+                entityType: 'service',
+                entityName: this._serviceName,
+              });
+          reject(error);
+          return;
+        }
+
+        effectiveSignal.addEventListener('abort', () => {
+          if (!isResolved) {
+            cleanup();
+            const error = isTimeout
+              ? new TimeoutError('Service request', options.timeout, {
+                  entityType: 'service',
+                  entityName: this._serviceName,
+                })
+              : new AbortError('Service request', undefined, {
+                  entityType: 'service',
+                  entityName: this._serviceName,
+                });
+            reject(error);
+          }
+        });
+      }
+
+      try {
+        const shouldValidate =
+          options.validate !== undefined
+            ? options.validate
+            : this._validateRequests;
+
+        if (shouldValidate && !(request instanceof this._typeClass.Request)) {
+          assertValidMessage(
+            request,
+            this._typeClass.Request,
+            this._validationOptions
+          );
+        }
+
+        let requestToSend =
+          request instanceof this._typeClass.Request
+            ? request
+            : new this._typeClass.Request(request);
+
+        let rawRequest = requestToSend.serialize();
+        sequenceNumber = rclnodejs.sendRequest(this._handle, rawRequest);
+
+        debug(`Client has sent a ${this._serviceName} request (async).`);
+
+        this._sequenceNumberToCallbackMap.set(sequenceNumber, (response) => {
+          if (!isResolved) {
+            cleanup();
+            resolve(response);
+          }
+        });
+      } catch (error) {
+        cleanup();
+        reject(error);
+      }
+    });
+  }
+
   processResponse(sequenceNumber, response) {
     if (this._sequenceNumberToCallbackMap.has(sequenceNumber)) {
       debug(`Client has received ${this._serviceName} response from service.`);

package/lib/clock.js

@@ -17,6 +17,10 @@
 const rclnodejs = require('./native_loader.js');
 const Time = require('./time.js');
 const ClockType = require('./clock_type.js');
+const ClockChange = require('./clock_change.js');
+const Context = require('./context.js');
+const ClockEvent = require('./clock_event.js');
+const { TypeValidationError } = require('./errors.js');
 
 /**
  * @class - Class representing a Clock in ROS
@@ -47,6 +51,71 @@ class Clock {
     return this._clockType;
   }
 
+  /**
+   * Add a clock callback.
+   * @param {object} callbackObject - The object containing callback methods.
+   * @param {Function} [callbackObject._pre_callback] - Optional callback invoked before a time jump. Takes no arguments.
+   * @param {Function} [callbackObject._post_callback] - Optional callback invoked after a time jump.
+   *   Receives a jumpInfo object with properties:
+   *   - clock_change {number}: Type of clock change that occurred.
+   *   - delta {bigint}: Time delta in nanoseconds.
+   * @param {boolean} onClockChange - Whether to call the callback on clock change.
+   * @param {bigint} minForward - Minimum forward jump in nanoseconds to trigger the callback.
+   * @param {bigint} minBackward - Minimum backward jump in nanoseconds to trigger the callback.
+   */
+  addClockCallback(callbackObject, onClockChange, minForward, minBackward) {
+    if (typeof callbackObject !== 'object' || callbackObject === null) {
+      throw new TypeValidationError(
+        'callbackObject',
+        callbackObject,
+        'object',
+        {
+          entityType: 'clock',
+        }
+      );
+    }
+    if (typeof onClockChange !== 'boolean') {
+      throw new TypeValidationError('onClockChange', onClockChange, 'boolean', {
+        entityType: 'clock',
+      });
+    }
+    if (typeof minForward !== 'bigint') {
+      throw new TypeValidationError('minForward', minForward, 'bigint', {
+        entityType: 'clock',
+      });
+    }
+    if (typeof minBackward !== 'bigint') {
+      throw new TypeValidationError('minBackward', minBackward, 'bigint', {
+        entityType: 'clock',
+      });
+    }
+    rclnodejs.clockAddJumpCallback(
+      this._handle,
+      callbackObject,
+      onClockChange,
+      minForward,
+      minBackward
+    );
+  }
+
+  /**
+   * Remove a clock callback.
+   * @param {object} callbackObject - The callback object that was previously registered with addClockCallback().
+   */
+  removeClockCallback(callbackObject) {
+    if (typeof callbackObject !== 'object' || callbackObject === null) {
+      throw new TypeValidationError(
+        'callbackObject',
+        callbackObject,
+        'object',
+        {
+          entityType: 'clock',
+        }
+      );
+    }
+    rclnodejs.clockRemoveJumpCallback(this._handle, callbackObject);
+  }
+
   /**
    * Return the current time.
    * @return {Time} Return the current time.
@@ -55,6 +124,116 @@ class Clock {
     const nowInNanosec = rclnodejs.clockGetNow(this._handle);
     return new Time(0n, nowInNanosec, this._clockType);
   }
+
+  /**
+   * Sleep until a specific time is reached on this Clock.
+   *
+   * When using a ROSClock, this may sleep forever if the TimeSource is misconfigured
+   * and the context is never shut down. ROS time being activated or deactivated causes
+   * this function to cease sleeping and return false.
+   *
+   * @param {Time} until - Time at which this function should stop sleeping.
+   * @param {Context} [context=null] - Context whose validity will be checked while sleeping.
+   *   If context is null, then the default context is used. If the context is found to be
+   *   shut down before or by the time the wait completes, the returned promise resolves to false.
+   * @return {Promise<boolean>} Promise that resolves to true if 'until' was reached without
+   *   detecting a time jump or a shut down context, or false otherwise (for example, if a time
+   *   jump occurred or the context is no longer valid when the wait completes).
+   * @throws {TypeError} if until is specified for a different type of clock than this one.
+   * @throws {Error} if context has not been initialized or is shutdown.
+   */
+  async sleepUntil(until, context = null) {
+    if (!(until instanceof Time)) {
+      throw new TypeValidationError('until', until, 'Time', {
+        entityType: 'clock',
+      });
+    }
+
+    if (!context) {
+      context = Context.defaultContext();
+    }
+
+    if (!context.isValid()) {
+      throw new Error('Context is not initialized or has been shut down');
+    }
+
+    if (until.clockType !== this._clockType) {
+      throw new TypeError(
+        "until's clock type does not match this clock's type"
+      );
+    }
+
+    const event = new ClockEvent();
+    let timeSourceChanged = false;
+
+    // Callback to wake when time jumps and is past target time
+    const callbackObject = {
+      _pre_callback: () => {
+        // Optional pre-callback - no action needed
+      },
+      _post_callback: (jumpInfo) => {
+        // ROS time being activated or deactivated changes the epoch,
+        // so sleep time loses its meaning
+        timeSourceChanged =
+          timeSourceChanged ||
+          jumpInfo.clock_change === ClockChange.ROS_TIME_ACTIVATED ||
+          jumpInfo.clock_change === ClockChange.ROS_TIME_DEACTIVATED;
+
+        if (timeSourceChanged || this.now().nanoseconds >= until.nanoseconds) {
+          event.set();
+        }
+      },
+    };
+
+    // Setup jump callback with minimal forward threshold
+    this.addClockCallback(
+      callbackObject,
+      true, // onClockChange
+      1n, // minForward (1 nanosecond - any forward jump triggers)
+      0n // minBackward (0 disables backward threshold)
+    );
+
+    try {
+      // Wait based on clock type
+      if (this._clockType === ClockType.SYSTEM_TIME) {
+        await event.waitUntilSystem(this, until.nanoseconds);
+      } else if (this._clockType === ClockType.STEADY_TIME) {
+        await event.waitUntilSteady(this, until.nanoseconds);
+      } else if (this._clockType === ClockType.ROS_TIME) {
+        await event.waitUntilRos(this, until.nanoseconds);
+      }
+    } finally {
+      // Always clean up callback
+      this.removeClockCallback(callbackObject);
+    }
+
+    if (!context.isValid() || timeSourceChanged) {
+      return false;
+    }
+
+    return this.now().nanoseconds >= until.nanoseconds;
+  }
+
+  /**
+   * Sleep for a specified duration.
+   *
+   * Equivalent to: clock.sleepUntil(clock.now() + duration, context)
+   *
+   * When using a ROSClock, this may sleep forever if the TimeSource is misconfigured
+   * and the context is never shut down. ROS time being activated or deactivated causes
+   * this function to cease sleeping and return false.
+   *
+   * @param {Duration} duration - Duration of time to sleep for.
+   * @param {Context} [context=null] - Context which when shut down will cause this sleep to wake early.
+   *   If context is null, then the default context is used.
+   * @return {Promise<boolean>} Promise that resolves to true if the full duration was slept,
+   *   or false if it woke for another reason.
+   * @throws {Error} if context has not been initialized or is shutdown.
+   */
+  async sleepFor(duration, context = null) {
+    const until = this.now().add(duration);
+    return this.sleepUntil(until, context);
+  }
 }
 
 /**
@@ -102,7 +281,9 @@ class ROSClock extends Clock {
 
   set rosTimeOverride(time) {
     if (!(time instanceof Time)) {
-      throw new TypeError('Invalid argument, must be type of Time');
+      throw new TypeValidationError('time', time, 'Time', {
+        entityType: 'clock',
+      });
     }
     rclnodejs.setRosTimeOverride(this._handle, time._handle);
   }

package/lib/clock_change.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2025 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';
+
+/**
+ * Enum for ClockChange
+ * Represents the type of clock change that occurred during a time jump.
+ * @readonly
+ * @enum {number}
+ */
+const ClockChange = {
+  /**
+   * The source before and after the jump is ROS_TIME.
+   * @member {number}
+   */
+  ROS_TIME_NO_CHANGE: 1,
+
+  /**
+   * The source switched to ROS_TIME from SYSTEM_TIME.
+   * @member {number}
+   */
+  ROS_TIME_ACTIVATED: 2,
+
+  /**
+   * The source switched to SYSTEM_TIME from ROS_TIME.
+   * @member {number}
+   */
+  ROS_TIME_DEACTIVATED: 3,
+
+  /**
+   * The source before and after the jump is SYSTEM_TIME.
+   * @member {number}
+   */
+  SYSTEM_TIME_NO_CHANGE: 4,
+};
+
+module.exports = ClockChange;

package/lib/clock_event.js

@@ -0,0 +1,88 @@
+// 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 rclnodejs = require('./native_loader.js');
+
+/**
+ * @class - Class representing a ClockEvent in ROS
+ */
+class ClockEvent {
+  constructor() {
+    this._handle = rclnodejs.createClockEvent();
+  }
+
+  /**
+   * Wait until a time specified by a steady clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilSteady(clock, until) {
+    return rclnodejs.clockEventWaitUntilSteady(
+      this._handle,
+      clock.handle,
+      until
+    );
+  }
+
+  /**
+   * Wait until a time specified by a system clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilSystem(clock, until) {
+    return rclnodejs.clockEventWaitUntilSystem(
+      this._handle,
+      clock.handle,
+      until
+    );
+  }
+
+  /**
+   * Wait until a time specified by a ROS clock.
+   * @param {Clock} clock - The clock to use for time synchronization.
+   * @param {bigint} until - The time to wait until.
+   * @return {Promise<void>} - A promise that resolves when the time is reached.
+   */
+  async waitUntilRos(clock, until) {
+    return rclnodejs.clockEventWaitUntilRos(this._handle, clock.handle, until);
+  }
+
+  /**
+   * Indicate if the ClockEvent is set.
+   * @return {boolean} - True if the ClockEvent is set.
+   */
+  isSet() {
+    return rclnodejs.clockEventIsSet(this._handle);
+  }
+
+  /**
+   * Set the event.
+   */
+  set() {
+    rclnodejs.clockEventSet(this._handle);
+  }
+
+  /**
+   * Clear the event.
+   */
+  clear() {
+    rclnodejs.clockEventClear(this._handle);
+  }
+}
+
+module.exports = ClockEvent;

package/lib/context.js

@@ -15,6 +15,7 @@
 'use strict';
 
 const rclnodejs = require('./native_loader.js');
+const { OperationError } = require('./errors.js');
 
 let defaultContext = null;
 
@@ -184,11 +185,20 @@ class Context {
 
   onNodeCreated(node) {
     if (!node) {
-      throw new Error('Node must be defined to add to Context');
+      throw new OperationError('Node must be defined to add to Context', {
+        code: 'NODE_UNDEFINED',
+        entityType: 'context',
+      });
     }
 
     if (this.isShutdown()) {
-      throw new Error('Can not add a Node to a Context that is shutdown');
+      throw new OperationError(
+        'Can not add a Node to a Context that is shutdown',
+        {
+          code: 'CONTEXT_SHUTDOWN',
+          entityType: 'context',
+        }
+      );
     }
 
     if (this._nodes.includes(node)) {