Make sql execute return promise api-877

.eslintignore

@@ -2,3 +2,4 @@ src/codec/*.ts
 src/codec/custom/*.ts
 src/.eslintrc.js
 lib/**
+docs/**

DOCUMENTATION.md

@@ -2599,7 +2599,7 @@ await map.put('key1', 1);
 await map.put('key2', 2);
 await map.put('key3', 3);
 
-const result = client.getSql().execute(`SELECT __key, this FROM my-distributed-map WHERE this > 1`);
+const result = await client.getSql().execute(`SELECT __key, this FROM my-distributed-map WHERE this > 1`);
 
 for await (const row of result) {
     console.log(row); // {__key: 'key3', this: 3} and {__key: 'key2', this: 2}
@@ -2749,7 +2749,7 @@ comparable with `INTEGER`, the query needs a `CAST`. Note that, the cast can fai
 an integer.
 
 ```javascript
-const result = client.getSql().execute('SELECT * FROM myMap WHERE age > CAST(? AS INTEGER) AND age < CAST(? AS INTEGER)',
+const result = await client.getSql().execute('SELECT * FROM myMap WHERE age > CAST(? AS INTEGER) AND age < CAST(? AS INTEGER)',
     [13, 18]
 );
 ```

code_samples/bigdecimal_sample.js

@@ -67,8 +67,7 @@ function portableFactory(classId) {
                 'valueFormat' = 'decimal'
             )
         `;
-        // executions are async, await on update count to wait for execution.
-        await client.getSql().execute(createMappingQuery).getUpdateCount();
+        await client.getSql().execute(createMappingQuery);
 
         // You can use BigDecimals for any operation
         // Let's add some BigDecimals:
@@ -91,7 +90,7 @@ function portableFactory(classId) {
 
         // You can run an SQL query with a BigDecimal:
 
-        const result = client.getSql().execute(
+        const result = await client.getSql().execute(
             'SELECT * FROM decimalMap WHERE this > ?',
             [BigDecimal.fromString('2.22222222222222222')]
         );

code_samples/datetime_classes_sample.js

@@ -77,8 +77,7 @@ function portableFactory(classId) {
                 'valueFormat' = 'timestamp with time zone'
             )
         `;
-        // executions are async, await on update count to wait for execution.
-        await client.getSql().execute(createMappingQuery).getUpdateCount();
+        await client.getSql().execute(createMappingQuery);
 
         // You can use datetime classes for any operation
         // Let's add some timestamp with timezones using `OffsetDatetime`:
@@ -105,7 +104,7 @@ function portableFactory(classId) {
 
         // You can run an SQL query:
 
-        const result = client.getSql().execute('SELECT * FROM timestampWithTimezoneMap WHERE this > ?', [
+        const result = await client.getSql().execute('SELECT * FROM timestampWithTimezoneMap WHERE this > ?', [
             OffsetDateTime.from(2020, 3, 1, 5, 6, 7, 123456789, 3600)
         ]);
 

code_samples/sql-basic-usage.js

@@ -35,16 +35,15 @@ const { Client, SqlColumnType, HazelcastSqlException } = require('hazelcast-clie
                 'valueFormat' = 'double'
             )
         `;
-        // executions are async, await on update count to wait for execution.
-        await client.getSql().execute(createMappingQuery).getUpdateCount();
+        await client.getSql().execute(createMappingQuery);
 
         await map.put('key1', 1);
         await map.put('key2', 2);
         await map.put('key3', 3);
 
         let result;
         try {
-            result = client.getSql().execute('SELECT __key, this FROM myMap WHERE this > ?', [1]);
+            result = await client.getSql().execute('SELECT __key, this FROM myMap WHERE this > ?', [1]);
             const rowMetadata = await result.getRowMetadata();
             const columns = await rowMetadata.getColumns();
 
@@ -70,7 +69,7 @@ const { Client, SqlColumnType, HazelcastSqlException } = require('hazelcast-clie
 
         try {
             // You can set returnRawResult to true to get rows as `SqlRow` objects
-            result = client.getSql().execute('SELECT __key, this FROM myMap WHERE this > ?', [1], {
+            result = await client.getSql().execute('SELECT __key, this FROM myMap WHERE this > ?', [1], {
                 returnRawResult: true
             });
 

code_samples/sql-data-types.js

@@ -54,15 +54,14 @@ const varcharExample = async (client) => {
                 'valueFormat' = 'varchar'
             )
         `;
-    // executions are async, await on update count to wait for execution.
-    await client.getSql().execute(createMappingQuery).getUpdateCount();
+    await client.getSql().execute(createMappingQuery);
 
     for (let key = 0; key < 10; key++) {
         await someMap.set(key, key.toString());
     }
 
     try {
-        const result = client.getSql().execute('SELECT * FROM varcharMap WHERE this = ? OR this = ?', ['7', '2']);
+        const result = await client.getSql().execute('SELECT * FROM varcharMap WHERE this = ? OR this = ?', ['7', '2']);
         const rowMetadata = await result.getRowMetadata();
         const columnIndex = rowMetadata.findColumn('this');
         const columnMetadata = rowMetadata.getColumn(columnIndex);
@@ -102,15 +101,14 @@ const integersExample = async (client) => {
                 'valueFormat' = 'bigint'
             )
         `;
-    // executions are async, await on update count to wait for execution.
-    await client.getSql().execute(createMappingQuery).getUpdateCount();
+    await client.getSql().execute(createMappingQuery);
 
     for (let key = 0; key < 10; key++) {
         await someMap.set(key, long.fromNumber(key * 2));
     }
 
     try {
-        const result = client.getSql().execute(
+        const result = await client.getSql().execute(
             'SELECT * FROM bigintMap WHERE this > ? AND this < ?',
             [long.fromNumber(10), long.fromNumber(18)]
         );
@@ -134,7 +132,7 @@ const integersExample = async (client) => {
 
     try {
         // Casting example. Casting to other integer types is also possible.
-        const result = client.getSql().execute(
+        const result = await client.getSql().execute(
             'SELECT * FROM bigintMap WHERE this > CAST(? AS BIGINT) AND this < CAST(? AS BIGINT)',
             [10, 18]
         );
@@ -173,8 +171,7 @@ const objectExample = async (client, classId, factoryId) => {
                 'valuePortableClassId' = '${classId}'
             )
         `;
-    // executions are async, await on update count to wait for execution.
-    await client.getSql().execute(createMappingQuery).getUpdateCount();
+    await client.getSql().execute(createMappingQuery);
 
     for (let key = 0; key < 10; key++) {
         await someMap.set(key, new Student(long.fromNumber(key), 1.1));
@@ -184,7 +181,7 @@ const objectExample = async (client, classId, factoryId) => {
         // Note: If you do not specify `this` and use *, by default, `age` and `height` columns will be fetched
         // instead of `this`.
         // This is true only for complex custom objects like portable and identified serializable.
-        const result = client.getSql().execute(
+        const result = await client.getSql().execute(
             'SELECT __key, this FROM studentMap WHERE age > CAST(? AS INTEGER) AND age < CAST(? AS INTEGER)',
             [3, 8]
         );

code_samples/sql-order-by-limit-offset-example.js

@@ -34,8 +34,7 @@ const { Client, HazelcastSqlException } = require('hazelcast-client');
                 'valueFormat' = 'double'
             )
         `;
-        // executions are async, await on update count to wait for execution.
-        await client.getSql().execute(createMappingQuery).getUpdateCount();
+        await client.getSql().execute(createMappingQuery);
 
         // populate map
         await map.put('key1', 1);
@@ -45,7 +44,7 @@ const { Client, HazelcastSqlException } = require('hazelcast-client');
         await map.put('key5', 5);
 
         try {
-            const result = client.getSql().execute('SELECT * FROM myMap');
+            const result = await client.getSql().execute('SELECT * FROM myMap');
 
             console.log('Rows from unsorted query:');
             for await (const row of result) {
@@ -79,7 +78,7 @@ const { Client, HazelcastSqlException } = require('hazelcast-client');
 
         try {
             // Expected to see 2 3 4
-            const result = client.getSql().execute('SELECT * FROM myMap ORDER BY this ASC LIMIT 3 OFFSET 1');
+            const result = await client.getSql().execute('SELECT * FROM myMap ORDER BY this ASC LIMIT 3 OFFSET 1');
 
             console.log('Rows from sorted query with limit 3 and offset 1:');
             for await (const row of result) {

src/sql/SqlService.ts

@@ -128,26 +128,24 @@ import {SqlPage} from './SqlPage';
  */
 export interface SqlService {
     /**
-     * Executes SQL and returns an SqlResult.
+     * Executes SQL and returns an {@link SqlResult}.
      * Converts passed SQL string and parameter values into an {@link SqlStatement} object and invokes {@link executeStatement}.
      *
      * @param sql SQL string. SQL string placeholder character is question mark(`?`)
      * @param params Parameter list. The parameter count must be equal to number of placeholders in the SQL string
      * @param options Options that are affecting how the query is executed
      * @throws {@link IllegalArgumentError} if arguments are not valid
      * @throws {@link HazelcastSqlException} in case of an execution error
-     * @returns {@link SqlResult}
      */
-    execute(sql: string, params?: any[], options?: SqlStatementOptions): SqlResult;
+    execute(sql: string, params?: any[], options?: SqlStatementOptions): Promise<SqlResult>;
 
     /**
-     * Executes SQL and returns an SqlResult.
+     * Executes SQL and returns an {@link SqlResult}.
      * @param sql SQL statement object
      * @throws {@link IllegalArgumentError} if arguments are not valid
      * @throws {@link HazelcastSqlException} in case of an execution error
-     * @returns {@link SqlResult}
      */
-    executeStatement(sql: SqlStatement): SqlResult;
+    executeStatement(sql: SqlStatement): Promise<SqlResult>;
 }
 
 /** @internal */
@@ -284,7 +282,7 @@ export class SqlServiceImpl implements SqlService {
         );
     }
 
-    executeStatement(sqlStatement: SqlStatement): SqlResult {
+    executeStatement(sqlStatement: SqlStatement): Promise<SqlResult> {
         try {
             SqlServiceImpl.validateSqlStatement(sqlStatement);
         } catch (error) {
@@ -359,21 +357,20 @@ export class SqlServiceImpl implements SqlService {
                 this.connectionManager.getClientUuid()
             );
 
-            this.invocationService.invokeOnConnection(connection, requestMessage).then(clientMessage => {
+            return this.invocationService.invokeOnConnection(connection, requestMessage).then(clientMessage => {
                 SqlServiceImpl.handleExecuteResponse(clientMessage, res);
+                return res;
             }).catch(err => {
-                res.onExecuteError(
-                    this.rethrow(err, connection)
-                );
+                const error = this.rethrow(err, connection);
+                res.onExecuteError(error);
+                throw error;
             });
-
-            return res;
         } catch (error) {
             throw this.rethrow(error, connection);
         }
     }
 
-    execute(sql: string, params?: any[], options?: SqlStatementOptions): SqlResult {
+    execute(sql: string, params?: any[], options?: SqlStatementOptions): Promise<SqlResult> {
         const sqlStatement: SqlStatement = {
             sql: sql
         };

test/TestUtil.js

@@ -346,7 +346,7 @@ exports.createMapping = async (serverVersionNewerThanFive, client, keyFormat, va
             )
         `;
 
-    const result = exports.getSql(client).execute(createMappingQuery);
+    const result = await exports.getSql(client).execute(createMappingQuery);
     // Wait for execution to end.
     await result.getUpdateCount();
 };