rclnodejs 1.5.2 → 1.7.0

package/rosidl_gen/templates/service-event-template.js

@@ -0,0 +1,31 @@
+// 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.
+
+function generateServiceEvent(data) {
+  const serviceInfo = data.serviceInfo;
+
+  return `# This file is automatically generated by rosidl_gen
+#
+# *** DO NOT EDIT directly
+#
+
+service_msgs/ServiceEventInfo info
+
+${serviceInfo.pkgName}/${serviceInfo.interfaceName}_Request[<=1] request
+
+${serviceInfo.pkgName}/${serviceInfo.interfaceName}_Response[<=1] response
+`;
+}
+
+module.exports = generateServiceEvent;

package/rosidl_gen/templates/service-template.js

@@ -0,0 +1,44 @@
+// 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.
+
+function generateService(data) {
+  const serviceInfo = data.serviceInfo;
+  const className = `${serviceInfo.pkgName}__${serviceInfo.subFolder}__${serviceInfo.interfaceName}`;
+
+  return `// This file is automatically generated by rclnodejs
+//
+// *** DO NOT EDIT directly
+//
+
+'use strict';
+
+class ${className} {
+  static get Request() {
+    return require('./${className}_Request.js');
+  }
+
+  static get Response() {
+    return require('./${className}_Response.js');
+  }
+
+  static type() {
+    return {pkgName: '${serviceInfo.pkgName}', subFolder: '${serviceInfo.subFolder}', interfaceName: '${serviceInfo.interfaceName}'};
+  }
+}
+
+module.exports = ${className};
+`;
+}
+
+module.exports = generateService;

package/rosidl_parser/rosidl_parser.js

@@ -14,7 +14,7 @@
 
 'use strict';
 
-const compareVersions = require('compare-versions');
+const { compareVersions } = require('../lib/utils.js');
 const path = require('path');
 const execFile = require('child_process').execFile;
 
@@ -22,7 +22,7 @@ const pythonExecutable = require('./py_utils').getPythonExecutable('python3');
 
 const contextSupportedVersion = '21.0.0.0';
 const currentVersion = process.version;
-const isContextSupported = compareVersions.compare(
+const isContextSupported = compareVersions(
   currentVersion.substring(1, currentVersion.length),
   contextSupportedVersion,
   '>='

package/third_party/ref-napi/lib/ref.js

@@ -1471,51 +1471,6 @@ if (Buffer.prototype[inspectSym]) {
   Buffer.prototype[inspectSym] = overwriteInspect(Buffer.prototype[inspectSym]);
 }
 
-// does SlowBuffer inherit from Buffer? (node >= v0.7.9)
-if (!(exports.NULL instanceof Buffer)) {
-  debug(
-    "extending SlowBuffer's prototype since it doesn't inherit from Buffer.prototype"
-  );
-
-  /*!
-   * SlowBuffer convenience methods.
-   */
-
-  var SlowBuffer = require('buffer').SlowBuffer;
-
-  SlowBuffer.prototype.address = Buffer.prototype.address;
-  SlowBuffer.prototype.hexAddress = Buffer.prototype.hexAddress;
-  SlowBuffer.prototype.isNull = Buffer.prototype.isNull;
-  SlowBuffer.prototype.ref = Buffer.prototype.ref;
-  SlowBuffer.prototype.deref = Buffer.prototype.deref;
-  SlowBuffer.prototype.readObject = Buffer.prototype.readObject;
-  SlowBuffer.prototype.writeObject = Buffer.prototype.writeObject;
-  SlowBuffer.prototype.readPointer = Buffer.prototype.readPointer;
-  SlowBuffer.prototype.writePointer = Buffer.prototype.writePointer;
-  SlowBuffer.prototype.readCString = Buffer.prototype.readCString;
-  SlowBuffer.prototype.writeCString = Buffer.prototype.writeCString;
-  SlowBuffer.prototype.reinterpret = Buffer.prototype.reinterpret;
-  SlowBuffer.prototype.reinterpretUntilZeros =
-    Buffer.prototype.reinterpretUntilZeros;
-  SlowBuffer.prototype.readInt64BE = Buffer.prototype.readInt64BE;
-  SlowBuffer.prototype.writeInt64BE = Buffer.prototype.writeInt64BE;
-  SlowBuffer.prototype.readUInt64BE = Buffer.prototype.readUInt64BE;
-  SlowBuffer.prototype.writeUInt64BE = Buffer.prototype.writeUInt64BE;
-  SlowBuffer.prototype.readInt64LE = Buffer.prototype.readInt64LE;
-  SlowBuffer.prototype.writeInt64LE = Buffer.prototype.writeInt64LE;
-  SlowBuffer.prototype.readUInt64LE = Buffer.prototype.readUInt64LE;
-  SlowBuffer.prototype.writeUInt64LE = Buffer.prototype.writeUInt64LE;
-  /**
-   * in node 6.9.1, inspect.custom does not give a correct value; so in this case, don't torch the whole process.
-   * fixed in >6.9.2
-   */
-  if (SlowBuffer.prototype[inspectSym]) {
-    SlowBuffer.prototype[inspectSym] = overwriteInspect(
-      SlowBuffer.prototype[inspectSym]
-    );
-  }
-}
-
 /**
  * ...
  */

package/types/base.d.ts

@@ -8,6 +8,7 @@
 /// <reference path="./distro.d.ts" />
 /// <reference path="./duration.d.ts" />
 /// <reference path="./entity.d.ts" />
+/// <reference path="./errors.d.ts" />
 /// <reference path="./guard_condition.d.ts" />
 /// <reference path="./interfaces.d.ts" />
 /// <reference path="./lifecycle.d.ts" />
@@ -16,6 +17,8 @@
 /// <reference path="./node.d.ts" />
 /// <reference path="./node_options.d.ts" />
 /// <reference path="./parameter.d.ts" />
+/// <reference path="./parameter_client.d.ts" />
+/// <reference path="./parameter_watcher.d.ts" />
 /// <reference path="./publisher.d.ts" />
 /// <reference path="./qos.d.ts" />
 /// <reference path="./rate.d.ts" />

package/types/client.d.ts

@@ -14,6 +14,21 @@ declare module 'rclnodejs' {
       callback: Client.ResponseCallback<T>
     ): void;
 
+    /**
+     * Make a service request and return a Promise that resolves with the response.
+     *
+     * @param request - Request to be submitted.
+     * @param options - Optional parameters for the request.
+     * @returns Promise that resolves with the service response.
+     * @throws TimeoutError if the request times out (when options.timeout is exceeded).
+     * @throws AbortError if the request is manually aborted (via options.signal).
+     * @throws Error if the request fails for other reasons.
+     */
+    sendRequestAsync(
+      request: ServiceRequestMessage<T>,
+      options?: Client.AsyncRequestOptions
+    ): Promise<ServiceResponseMessage<T>>;
+
     /**
      * Checks if the service is ready.
      *
@@ -74,5 +89,26 @@ declare module 'rclnodejs' {
     export type ResponseCallback<T extends TypeClass<ServiceTypeClassName>> = (
       response: ServiceResponseMessage<T>
     ) => void;
+
+    /**
+     * Options for async service requests
+     */
+    export interface AsyncRequestOptions {
+      /**
+       * Timeout in milliseconds for the request.
+       * Internally uses AbortSignal.timeout() for standards compliance.
+       */
+      timeout?: number;
+
+      /**
+       * AbortSignal to cancel the request.
+       * When the signal is aborted, the request will be cancelled
+       * and the promise will reject with an AbortError.
+       *
+       * Can be combined with timeout parameter - whichever happens first
+       * will abort the request.
+       */
+      signal?: AbortSignal;
+    }
   }
 }

package/types/errors.d.ts

@@ -0,0 +1,447 @@
+// Copyright (c) 2025 Mahmoud Alghalayini. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+declare module 'rclnodejs' {
+  /**
+   * Options for RclNodeError constructor
+   */
+  export interface RclNodeErrorOptions {
+    /** Machine-readable error code (e.g., 'TIMEOUT', 'INVALID_ARGUMENT') */
+    code?: string;
+    /** Name of the node where error occurred */
+    nodeName?: string;
+    /** Type of entity (publisher, subscription, client, etc.) */
+    entityType?: string;
+    /** Name of the entity (topic name, service name, etc.) */
+    entityName?: string;
+    /** Original error that caused this error */
+    cause?: Error;
+    /** Additional error-specific details */
+    details?: any;
+  }
+
+  /**
+   * Base error class for all rclnodejs errors.
+   * Provides structured error information with context.
+   */
+  export class RclNodeError extends Error {
+    /** Error code for machine-readable error identification */
+    code: string;
+    /** Name of the node where error occurred */
+    nodeName?: string;
+    /** Type of entity (publisher, subscription, client, etc.) */
+    entityType?: string;
+    /** Name of the entity (topic name, service name, etc.) */
+    entityName?: string;
+    /** Additional error-specific details */
+    details?: any;
+    /** Original error that caused this error */
+    cause?: Error;
+    /** Timestamp when error was created */
+    timestamp: Date;
+
+    /**
+     * @param message - Human-readable error message
+     * @param options - Additional error context
+     */
+    constructor(message: string, options?: RclNodeErrorOptions);
+
+    /**
+     * Returns a detailed error object for logging/serialization
+     */
+    toJSON(): {
+      name: string;
+      message: string;
+      code: string;
+      nodeName?: string;
+      entityType?: string;
+      entityName?: string;
+      details?: any;
+      timestamp: string;
+      stack?: string;
+      cause?: any;
+    };
+
+    /**
+     * Returns a user-friendly error description
+     */
+    toString(): string;
+  }
+
+  /**
+   * Options for ValidationError constructor
+   */
+  export interface ValidationErrorOptions extends RclNodeErrorOptions {
+    /** Name of the argument that failed validation */
+    argumentName?: string;
+    /** The value that was provided */
+    providedValue?: any;
+    /** The expected type or format */
+    expectedType?: string;
+    /** The validation rule that failed */
+    validationRule?: string;
+  }
+
+  /**
+   * Error thrown when validation fails
+   */
+  export class ValidationError extends RclNodeError {
+    /** Name of the argument that failed validation */
+    argumentName?: string;
+    /** The value that was provided */
+    providedValue?: any;
+    /** The expected type or format */
+    expectedType?: string;
+    /** The validation rule that failed */
+    validationRule?: string;
+
+    /**
+     * @param message - Error message
+     * @param options - Additional options
+     */
+    constructor(message: string, options?: ValidationErrorOptions);
+  }
+
+  /**
+   * Type validation error
+   */
+  export class TypeValidationError extends ValidationError {
+    /**
+     * @param argumentName - Name of the argument
+     * @param providedValue - The value that was provided
+     * @param expectedType - The expected type
+     * @param options - Additional options
+     */
+    constructor(
+      argumentName: string,
+      providedValue: any,
+      expectedType: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Range/value validation error
+   */
+  export class RangeValidationError extends ValidationError {
+    /**
+     * @param argumentName - Name of the argument
+     * @param providedValue - The value that was provided
+     * @param constraint - The constraint that was violated
+     * @param options - Additional options
+     */
+    constructor(
+      argumentName: string,
+      providedValue: any,
+      constraint: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * ROS name validation error (topics, nodes, services)
+   */
+  export class NameValidationError extends ValidationError {
+    /** Index where validation failed */
+    invalidIndex: number;
+    /** The validation error message */
+    validationResult: string;
+
+    /**
+     * @param name - The invalid name
+     * @param nameType - Type of name (node, topic, service, etc.)
+     * @param validationResult - The validation error message
+     * @param invalidIndex - Index where validation failed
+     * @param options - Additional options
+     */
+    constructor(
+      name: string,
+      nameType: string,
+      validationResult: string,
+      invalidIndex: number,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Base class for operation/runtime errors
+   */
+  export class OperationError extends RclNodeError {
+    /**
+     * @param message - Error message
+     * @param options - Additional options
+     */
+    constructor(message: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Request timeout error
+   */
+  export class TimeoutError extends OperationError {
+    /** Timeout duration in milliseconds */
+    timeout: number;
+    /** Type of operation that timed out */
+    operationType: string;
+
+    /**
+     * @param operationType - Type of operation that timed out
+     * @param timeoutMs - Timeout duration in milliseconds
+     * @param options - Additional options
+     */
+    constructor(
+      operationType: string,
+      timeoutMs: number,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Request abortion error
+   */
+  export class AbortError extends OperationError {
+    /** Type of operation that was aborted */
+    operationType: string;
+    /** Reason for abortion */
+    abortReason?: string;
+
+    /**
+     * @param operationType - Type of operation that was aborted
+     * @param reason - Reason for abortion
+     * @param options - Additional options
+     */
+    constructor(
+      operationType: string,
+      reason?: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Service not available error
+   */
+  export class ServiceNotFoundError extends OperationError {
+    /** Name of the service */
+    serviceName: string;
+
+    /**
+     * @param serviceName - Name of the service
+     * @param options - Additional options
+     */
+    constructor(serviceName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Remote node not found error
+   */
+  export class NodeNotFoundError extends OperationError {
+    /** Name of the target node */
+    targetNodeName: string;
+
+    /**
+     * @param nodeName - Name of the node
+     * @param options - Additional options
+     */
+    constructor(nodeName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Base error for parameter operations
+   */
+  export class ParameterError extends RclNodeError {
+    /** Name of the parameter */
+    parameterName: string;
+
+    /**
+     * @param message - Error message
+     * @param parameterName - Name of the parameter
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      parameterName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Parameter not found error
+   */
+  export class ParameterNotFoundError extends ParameterError {
+    /**
+     * @param parameterName - Name of the parameter
+     * @param nodeName - Name of the node
+     * @param options - Additional options
+     */
+    constructor(
+      parameterName: string,
+      nodeName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Parameter type mismatch error
+   */
+  export class ParameterTypeError extends ParameterError {
+    /** Expected parameter type */
+    expectedType: string;
+    /** Actual parameter type */
+    actualType: string;
+
+    /**
+     * @param parameterName - Name of the parameter
+     * @param expectedType - Expected parameter type
+     * @param actualType - Actual parameter type
+     * @param options - Additional options
+     */
+    constructor(
+      parameterName: string,
+      expectedType: string,
+      actualType: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Read-only parameter modification error
+   */
+  export class ReadOnlyParameterError extends ParameterError {
+    /**
+     * @param parameterName - Name of the parameter
+     * @param options - Additional options
+     */
+    constructor(parameterName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Base error for topic operations
+   */
+  export class TopicError extends RclNodeError {
+    /** Name of the topic */
+    topicName: string;
+
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Publisher-specific error
+   */
+  export class PublisherError extends TopicError {
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Subscription-specific error
+   */
+  export class SubscriptionError extends TopicError {
+    /**
+     * @param message - Error message
+     * @param topicName - Name of the topic
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      topicName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Base error for action operations
+   */
+  export class ActionError extends RclNodeError {
+    /** Name of the action */
+    actionName: string;
+
+    /**
+     * @param message - Error message
+     * @param actionName - Name of the action
+     * @param options - Additional options
+     */
+    constructor(
+      message: string,
+      actionName: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Goal rejected by action server
+   */
+  export class GoalRejectedError extends ActionError {
+    /** ID of the rejected goal */
+    goalId: string;
+
+    /**
+     * @param actionName - Name of the action
+     * @param goalId - ID of the rejected goal
+     * @param options - Additional options
+     */
+    constructor(
+      actionName: string,
+      goalId: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+
+  /**
+   * Action server not found
+   */
+  export class ActionServerNotFoundError extends ActionError {
+    /**
+     * @param actionName - Name of the action
+     * @param options - Additional options
+     */
+    constructor(actionName: string, options?: RclNodeErrorOptions);
+  }
+
+  /**
+   * Wraps errors from native C++ layer with additional context
+   */
+  export class NativeError extends RclNodeError {
+    /** Error message from C++ layer */
+    nativeMessage: string;
+    /** Operation that failed */
+    operation: string;
+
+    /**
+     * @param nativeMessage - Error message from C++ layer
+     * @param operation - Operation that failed
+     * @param options - Additional options
+     */
+    constructor(
+      nativeMessage: string,
+      operation: string,
+      options?: RclNodeErrorOptions
+    );
+  }
+}

package/types/index.d.ts

@@ -235,4 +235,21 @@ declare module 'rclnodejs' {
     launchFile: string,
     args: string[]
   ): Promise<{ process: ChildProcess }>;
+
+  /**
+   * Convert a message object to be JSON-safe by converting TypedArrays to regular arrays
+   * and handling BigInt, Infinity, NaN, etc. for JSON serialization.
+   * @param obj - The message object to convert
+   * @returns A JSON-safe version of the object
+   */
+  function toJSONSafe(obj: any): any;
+
+  /**
+   * Convert a message object to a JSON string with proper handling of TypedArrays,
+   * BigInt, and other non-JSON-serializable values.
+   * @param obj - The message object to convert
+   * @param space - Space parameter for JSON.stringify formatting
+   * @returns The JSON string representation
+   */
+  function toJSONString(obj: any, space?: number): string;
 }