feat: add promise-based service calls

Author: MahmoudGhalayini

example/services/README.md

@@ -48,6 +48,57 @@ ROS 2 services provide a request-response communication pattern where clients se
   - Asynchronous request handling with callbacks
 - **Run Command**: `node example/services/client/client-example.js`
 
+#### Async Service Client (`client/async-client-example.js`)
+
+**Purpose**: Demonstrates modern async/await patterns for service communication, solving callback hell and providing cleaner error handling.
+
+- **Service Type**: `example_interfaces/srv/AddTwoInts`
+- **Service Name**: `add_two_ints`
+- **Functionality**:
+  - Multiple examples showing different async patterns
+  - Simple async/await calls without callbacks
+  - Timeout handling with configurable timeouts
+  - Request cancellation using AbortController
+  - Sequential and parallel service calls
+  - Comprehensive error handling
+- **Features**:
+  - **Modern JavaScript**: Clean async/await syntax instead of callback hell
+  - **Timeout Support**: Built-in timeout handling with `options.timeout`
+  - **Cancellation**: Request cancellation using `AbortController` and `options.signal`
+  - **Error Types**: Specific error types (`TimeoutError`, `AbortError`) for better error handling (async only)
+  - **Backward Compatible**: Works alongside existing callback-based `sendRequest()`
+  - **TypeScript Ready**: Full type safety with comprehensive TypeScript definitions
+- **Run Command**: `node example/services/client/async-client-example.js`
+
+**Key API Differences**:
+
+```javascript
+client.sendRequest(request, (response) => {
+  console.log('Response:', response.sum);
+});
+
+try {
+  const response = await client.sendRequestAsync(request);
+
+  const response = await client.sendRequestAsync(request, { timeout: 5000 });
+
+  const controller = new AbortController();
+  const response = await client.sendRequestAsync(request, {
+    signal: controller.signal,
+  });
+
+  console.log('Response:', response.sum);
+} catch (error) {
+  if (error.name === 'TimeoutError') {
+    console.log('Request timed out');
+  } else if (error.name === 'AbortError') {
+    console.log('Request was cancelled');
+  } else {
+    console.error('Service error:', error.message);
+  }
+}
+```
+
 ### GetMap Service
 
 #### Service Server (`service/getmap-service-example.js`)
@@ -129,6 +180,41 @@ ROS 2 services provide a request-response communication pattern where clients se
    Result: object { sum: 79n }
    ```
 
+### Running the Async AddTwoInts Client Example
+
+1. **Prerequisites**: Ensure ROS 2 is installed and sourced
+
+2. **Start the Service Server**: Use the same service server as above:
+
+   ```bash
+   cd /path/to/rclnodejs
+   node example/services/service/service-example.js
+   ```
+
+3. **Start the Async Client**: In another terminal, run:
+
+   ```bash
+   cd /path/to/rclnodejs
+   node example/services/client/async-client-example.js
+   ```
+
+4. **Expected Output**:
+
+   **Service Server Terminal**: (Same as regular client)
+
+   ```
+   Incoming request: object { a: 42n, b: 37n }
+   Sending response: object { sum: 79n }
+   --
+   ```
+
+   **Async Client Terminal**:
+
+   ```
+   Sending: object { a: 42n, b: 37n }
+   Result: object { sum: 79n }
+   ```
+
 ### Running the GetMap Service Example
 
 1. **Prerequisites**: Ensure ROS 2 is installed and sourced
@@ -236,8 +322,11 @@ This script automatically starts the service, tests the client, and cleans up.
 
 ### Programming Patterns
 
-- **Async/Await**: Modern JavaScript patterns for asynchronous operations
-- **Callback Handling**: Response processing using callback functions
+- **Modern Async/Await**: Clean Promise-based service calls with `sendRequestAsync()`
+- **Traditional Callbacks**: Response processing using callback functions with `sendRequest()`
+- **Error Handling**: Proper error handling with try/catch blocks and specific error types (async only)
+- **Timeout Management**: Built-in timeout support to prevent hanging requests (async only)
+- **Request Cancellation**: AbortController support for user-cancellable operations (async only)
 - **Resource Management**: Proper node shutdown and cleanup
 - **Data Analysis**: Processing and interpreting received data
 - **Visualization**: Converting data to human-readable formats
@@ -331,18 +420,23 @@ int8[] data
 ### Common Issues
 
 1. **Service Not Available**:
-
    - Ensure the service server is running before starting the client
    - Check that both use the same service name (`add_two_ints`)
 
 2. **Type Errors**:
-
    - Ensure you're using `BigInt()` for integer values, not regular numbers
    - Use `response.template` to get the correct response structure
 
 3. **Client Hangs**:
    - The client waits for service availability with a 1-second timeout
    - If the service isn't available, the client will log an error and shut down
+   - For async clients, use timeout options: `client.sendRequestAsync(request, { timeout: 5000 })`
+
+4. **Async/Await Issues** (applies only to `sendRequestAsync()`):
+   - **Unhandled Promise Rejections**: Always use try/catch blocks around `sendRequestAsync()`
+   - **Timeout Errors**: Handle `TimeoutError` specifically for timeout scenarios (async only)
+   - **Cancelled Requests**: Handle `AbortError` when using AbortController cancellation (async only)
+   - **Mixed Patterns**: You can use both `sendRequest()` and `sendRequestAsync()` in the same code
 
 ### Debugging Tips
 
@@ -354,6 +448,10 @@ int8[] data
 
 - Both examples use the standard rclnodejs initialization pattern
 - The service server runs continuously until manually terminated
-- The client performs a single request-response cycle then exits
+- The traditional client performs a single request-response cycle then exits
+- The async client demonstrates multiple patterns and then exits
+- **New async/await support**: Use `sendRequestAsync()` for modern Promise-based patterns
+- **Full backward compatibility**: Existing `sendRequest()` callback-based code continues to work unchanged
+- **TypeScript support**: Full type safety available for async methods
 - Service introspection is only available in ROS 2 Iron and later distributions
 - BigInt is required for integer message fields to maintain precision

example/services/client/async-client-example.js

@@ -0,0 +1,66 @@
+// 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.
+
+'use strict';
+
+const rclnodejs = require('../../../index.js');
+
+async function main() {
+  await rclnodejs.init();
+  const node = rclnodejs.createNode('async_client_example_node');
+  const client = node.createClient(
+    'example_interfaces/srv/AddTwoInts',
+    'add_two_ints'
+  );
+
+  if (
+    rclnodejs.DistroUtils.getDistroId() >
+    rclnodejs.DistroUtils.getDistroId('humble')
+  ) {
+    // To view service events use the following command:
+    //    ros2 topic echo "/add_two_ints/_service_event"
+    client.configureIntrospection(
+      node.getClock(),
+      rclnodejs.QoS.profileSystemDefault,
+      rclnodejs.ServiceIntrospectionStates.METADATA
+    );
+  }
+
+  const request = {
+    a: BigInt(Math.floor(Math.random() * 100)),
+    b: BigInt(Math.floor(Math.random() * 100)),
+  };
+
+  let result = await client.waitForService(1000);
+  if (!result) {
+    console.log('Error: service not available');
+    rclnodejs.shutdown();
+    return;
+  }
+
+  rclnodejs.spin(node);
+
+  console.log(`Sending: ${typeof request}`, request);
+
+  try {
+    const response = await client.sendRequestAsync(request, { timeout: 5000 });
+    console.log(`Result: ${typeof response}`, response);
+  } catch (error) {
+    console.log(`Error: ${error.message}`);
+  } finally {
+    rclnodejs.shutdown();
+  }
+}
+
+main();

lib/client.js

@@ -33,7 +33,7 @@ class Client extends Entity {
   }
 
   /**
-   * 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,7 +43,7 @@ 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.
    * @return {undefined}
@@ -65,6 +65,88 @@ 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.
+   * @return {Promise<object>} Promise that resolves with the service response.
+   * @throws {Error} Throws error if request fails, times out, or is aborted.
+   */
+  sendRequestAsync(request, options = {}) {
+    return new Promise((resolve, reject) => {
+      let sequenceNumber = null;
+      let timeoutId = null;
+      let isResolved = false;
+
+      const cleanup = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        if (sequenceNumber !== null) {
+          this._sequenceNumberToCallbackMap.delete(sequenceNumber);
+        }
+        isResolved = true;
+      };
+
+      if (options.signal) {
+        if (options.signal.aborted) {
+          const error = new Error('Request was aborted');
+          error.name = 'AbortError';
+          reject(error);
+          return;
+        }
+
+        options.signal.addEventListener('abort', () => {
+          if (!isResolved) {
+            cleanup();
+            const error = new Error('Request was aborted');
+            error.name = 'AbortError';
+            reject(error);
+          }
+        });
+      }
+
+      if (options.timeout !== undefined && options.timeout >= 0) {
+        timeoutId = setTimeout(() => {
+          if (!isResolved) {
+            cleanup();
+            const error = new Error(
+              `Service call timeout after ${options.timeout}ms`
+            );
+            error.name = 'TimeoutError';
+            error.code = 'TIMEOUT';
+            reject(error);
+          }
+        }, options.timeout);
+      }
+
+      try {
+        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.`);