Add support for async iteration of SODA document cursors

Author: sharadraju

doc/src/api_manual/sodacursor.rst

@@ -5,14 +5,18 @@ API: SodaDocumentCursor Class
 *****************************
 
 A SodaDocumentCursor is used to walk through a set of SODA documents
-returned from a :meth:`sodaCollection.find()`
-:meth:`sodaOperation.getCursor()` method.
+returned from :meth:`sodaCollection.find()` and
+:meth:`sodaOperation.getCursor()` methods.
 
 .. note::
 
     In this release, SODA is only supported in the node-oracledb Thick mode.
     See :ref:`enablingthick`.
 
+From node-oracledb 6.4, the SodaDocumentCursor class implements the
+``asyncIterator()`` symbol to support asynchronous iteration. See
+:ref:`accessingsodadocuments` for examples.
+
 .. _sodadoccursormethods:
 
 SodaDocumentCursor Methods

doc/src/release_notes.rst

@@ -94,6 +94,8 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
+#)  Added support for asynchronous iteration of SODA document cursors.
+
 #)  Internal code and memory optimization changes for Advanced Queuing.
 
 node-oracledb `v6.3.0 <https://github.com/oracle/node-oracledb/compare/v6.2.0...v6.3.0>`__ (21 Dec 2023)

doc/src/user_guide/soda.rst

@@ -450,6 +450,31 @@ attribute values, or use
 SodaDocument returned by a :meth:`sodaCollection.find()`
 query.
 
+From node-oracledb 6.4, you can asynchronously iterate over
+:ref:`SodaDocumentCursor object <sodadocumentcursorclass>`:
+
+.. code-block:: javascript
+
+    const soda = connection.getSodaDatabase();
+    // Create a SODA collection
+    const collection = await soda.createCollection("mycollection");
+    const data = [
+        { name: "John", age: 57 },
+        { name: "Sally", age: 53 }
+    ];
+    await collection.insertMany(data);
+    const docCursor = await collection.find().getCursor();
+    // Use the asyncIterator for the SodaDocumentCursor object
+    for await (const doc of docCursor) {
+        console.log(doc.getContent());
+    }
+    await docCursor.close();
+    await collection.drop();
+    await connection.close();
+
+See `soda2.js <https://github.com/oracle/node-oracledb/tree/main/examples/
+soda2.js>`__ for a runnable example.
+
 .. _sodaqbesearches:
 
 SODA Query-by-Example Searches for JSON Documents

doc/src/user_guide/sql_execution.rst

@@ -211,7 +211,7 @@ To fetch multiple rows at a time, use ``getRows()``:
     // always close the ResultSet
     await rs.close();
 
-From node-oracledb 5.5, you can iterate over ResultSets:
+From node-oracledb 5.5, you can asynchronously iterate over ResultSets:
 
 .. code-block:: javascript
 
@@ -223,14 +223,20 @@ From node-oracledb 5.5, you can iterate over ResultSets:
         }
     );
 
+    // Fetch rows from the resultSet object using asyncIterator
     const rs = result.resultSet;
+
+    // Call the asyncIterator for the resultSet object
     for await (const row of rs) {
         console.log(row);
     }
 
     // always close the ResultSet
     await rs.close();
 
+See `resultset3.js <https://github.com/oracle/node-oracledb/tree/main/
+examples/resultset3.js>`__ for a runnable example.
+
 .. _streamingresults:
 
 Query Streaming

examples/soda2.js

@@ -0,0 +1,111 @@
+/* Copyright (c) 2024, Oracle and/or its affiliates. */
+
+/******************************************************************************
+ *
+ * This software is dual-licensed to you under the Universal Permissive License
+ * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+ * 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+ * either license.
+ *
+ * If you elect to accept the software under the Apache License, Version 2.0,
+ * the following applies:
+ *
+ * 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
+ *
+ *    https://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.
+ *
+ * NAME
+ *   soda2.js
+ *
+ * DESCRIPTION
+ *   Simple Oracle Document Access (SODA) example with SodaDocumentCursor
+ *   asyncIterators.
+ *
+ *   Requires Oracle Database and Oracle Client 18.3, or higher.
+ *   The user must have been granted the SODA_APP and CREATE TABLE privileges.
+ *   https://node-oracledb.readthedocs.io/en/latest/user_guide/soda.html#sodaoverview
+ *
+ *****************************************************************************/
+
+'use strict';
+
+Error.stackTraceLimit = 50;
+
+const oracledb = require('oracledb');
+const dbConfig = require('./dbconfig.js');
+
+// This example requires node-oracledb Thick mode.
+//
+// Thick mode requires Oracle Client or Oracle Instant Client libraries.  On
+// Windows and macOS Intel you can specify the directory containing the
+// libraries at runtime or before Node.js starts.  On other platforms (where
+// Oracle libraries are available) the system library search path must always
+// include the Oracle library path before Node.js starts.  If the search path
+// is not correct, you will get a DPI-1047 error.  See the node-oracledb
+// installation documentation.
+let clientOpts = {};
+// On Windows and macOS Intel platforms, set the environment
+// variable NODE_ORACLEDB_CLIENT_LIB_DIR to the Oracle Client library path
+if (process.platform === 'win32' || (process.platform === 'darwin' && process.arch === 'x64')) {
+  clientOpts = { libDir: process.env.NODE_ORACLEDB_CLIENT_LIB_DIR };
+}
+oracledb.initOracleClient(clientOpts);  // enable node-oracledb Thick mode
+
+// The general recommendation for simple SODA usage is to enable autocommit
+oracledb.autoCommit = true;
+
+async function run() {
+  let connection, collection;
+  try {
+    connection = await oracledb.getConnection(dbConfig);
+    if (oracledb.oracleClientVersion < 1803000000) {
+      throw new Error('node-oracledb SODA requires Oracle Client libraries 18.3 or greater');
+    }
+
+    if (connection.oracleServerVersion < 1803000000) {
+      throw new Error('node-oracledb SODA requires Oracle Database 18.3 or greater');
+    }
+
+    const soda = connection.getSodaDatabase();
+    collection = await soda.createCollection("Test");
+    console.log('Created a SODA collection\n');
+    const data = [
+      { name: "John", age: 57 },
+      { name: "Sally", age: 53 }
+    ];
+    await collection.insertMany(data);
+    const cursor = await collection.find().getCursor();
+    console.log('Retrieved SODA document contents as an object using SodaDocumentCursor:');
+    // Use the asyncIterator for the sodaDocumentCursor object
+    for await (const doc of cursor) {
+      console.log(doc.getContent());
+    }
+    await cursor.close();
+  } catch (err) {
+    console.error(err);
+  } finally {
+    if (collection) {
+      // Drop the collection
+      const res = await collection.drop();
+      if (res.dropped) {
+        console.log('\nThe collection was dropped');
+      }
+    }
+
+    if (connection) {
+      await connection.close();
+    }
+
+  }
+
+}
+
+run();

lib/sodaDocCursor.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2018, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2018, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -60,6 +60,19 @@ class SodaDocCursor {
     }
   }
 
+  [Symbol.asyncIterator]() {
+    const cursor = this;
+    return {
+      async next() {
+        const doc = await cursor.getNext();
+        return {value: doc, done: doc === undefined};
+      },
+      return() {
+        return {done: true};
+      }
+    };
+  }
+
 }
 
 nodbUtil.wrapFns(SodaDocCursor.prototype,

test/list.txt

@@ -4300,16 +4300,17 @@ oracledb.OUT_FORMAT_OBJECT and resultSet =  true
     175.3 Negative - limit().count()
     175.4 keys().count()
     175.5 getCursor(), basic case
-    175.6 skip().getCursor()
-    175.7 getCursor(), empty document matched
-    175.8 Negative - close document cursor two times
-    175.9 getDocuments(), basic case
-    175.10 getDocuments(), no documents matched
-    175.11 getOne(), basic case
-    175.12 getOne(), the filter matches multiple documents
-    175.13 remove(), basic case
-    175.14 remove(), remove zero document
-    175.15 remove(), remove multiple times
+    175.6 getCursor(), asyncIterator
+    175.7 skip().getCursor()
+    175.8 getCursor(), empty document matched
+    175.9 Negative - close document cursor two times
+    175.10 getDocuments(), basic case
+    175.11 getDocuments(), no documents matched
+    175.12 getOne(), basic case
+    175.13 getOne(), the filter matches multiple documents
+    175.14 remove(), basic case
+    175.15 remove(), remove zero document
+    175.16 remove(), remove multiple times
 
   176. soda8.js
     176.1 replaceOne(), basic case with document content