Test case cleanup and documentation update for the JsonId class

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -3511,3 +3511,17 @@ node-oracledb, allowing use of new features.
 
         BLOB columns with the ``IS JSON FORMAT OSON`` check constraint enabled
         can now be fetched as JSON type columns when this property is set.
+
+.. _jsonid:
+
+Oracledb JsonId Class
+=====================
+
+Objects of this class are returned by :ref:`SODA <sodaoverview>` in the
+``_id`` attribute of documents stored in native collections when using
+Oracle Database 23.4 (or later). The JsonId class is a subclass of `Uint8Array
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
+Global_Objects/Uint8Array>`__ and can be instantiated in the same way as an
+Uint8Array datatype object.
+
+.. versionadded:: 6.5

doc/src/user_guide/soda.rst

@@ -299,6 +299,69 @@ operations using :meth:`sodaCollection.save()` and
 are similar to the insertion methods, however if an existing document
 with the same key already exists in the collection, it is replaced.
 
+If you are using Oracle Database 23.4 (or later), you can define the key
+directly in the document content by specifying the key in the ``_id`` field
+as shown below:
+
+.. code-block:: javascript
+
+    try {
+        const myContent = {_id: 1, name: "Sally", address: {city: "Melbourne"}};
+        const newDoc = soda.createDocument(myContent);
+        await collection.insertOne(newDoc);
+    } catch(err) {
+        console.error(err);
+    }
+
+If you do not specify the ``_id`` field, then the :ref:`jsonid` returns an
+automatically generated hex-encoded string as the key value. Once the key is
+automatically generated, it cannot be overwritten with a new value. If you do
+try to update the value, then the following error will be returned::
+
+    ORA-54059:/ // cannot update an immutable column to a different value
+
+The JsonId value from one SODA document collection can be specified in another
+document collection. For example, ``STUDENTS`` collection can have courseID
+set from ``COURSES`` collection _id:
+
+.. code-block:: javascript
+
+    // Create STUDENTS Collection
+    await connection.execute(`CREATE JSON COLLECTION TABLE if not exists STUDENTS`);
+
+    // Create COURSES Collection
+    await connection.execute(`CREATE JSON COLLECTION TABLE if not exists COURSES`);
+
+    // Add a course document
+    const courseDoc = {"department": "Physics", "Professor": "Fred"};
+    let sql = `INSERT INTO COURSES VALUES (:1)`;
+    let result = await connection.execute(sql, [{
+        type: oracledb.DB_TYPE_JSON,
+        val: courseDoc
+    }]);
+
+    // Read the course inserted above which would have _id (JsonId type) populated.
+    sql = `SELECT * FROM COURSES`;
+    result = await connection.execute(sql);
+
+    // Add a student document with foreign key, courseID referring to COURSES collection.
+    const studentDoc = {"name": "Jenny"};
+    studentDoc.courseID = [];
+    studentDoc.courseID.push(result.rows[0][0]._id);
+    sql = `INSERT INTO STUDENTS VALUES (:1)`;
+    result = await connection.execute(sql, [{
+        type: oracledb.DB_TYPE_JSON,
+        val: studentDoc
+    }]);
+
+    // Read the student documents
+    sql = `SELECT * FROM STUDENTS`;
+    result = await connection.execute(sql);
+    console.log('Student Document:', JSON.stringify(result.rows[0][0])) // Student Document:
+                 {"name":"Jenny","courseID":
+                   ["661e0fea4583f699cc6a0b2a"],"_id":"661e105445ac389beaaf05ec"
+                 }
+
 To extract documents from a collection, the
 :meth:`~sodaCollection.find()` method can be used to build a
 :ref:`SodaOperation <sodaoperationclass>` object specifying the keys of

test/aq1.js

@@ -188,20 +188,20 @@ describe('217. aq1.js', function() {
       assert.strictEqual(messages2[0].payload.toString(), messages1[0]);
       assert.strictEqual(messages2.length, messages1.length);
     }
-  });   // 217.4
+  }); // 217.4
 
   it('217.5 deqOne on empty queue', async () => {
     const queue2 = await conn.getQueue(rawQueueName);
     queue2.deqOptions.wait = oracledb.AQ_DEQ_NO_WAIT;
     const message = await queue2.deqOne();
     assert.strictEqual(message, undefined);
-  });
+  }); // 217.5
 
   it('217.6 deqMany on empty queue', async () => {
     const queue2 = await conn.getQueue(rawQueueName);
     queue2.deqOptions.wait = oracledb.AQ_DEQ_NO_WAIT;
     const messages = await queue2.deqMany(1);
     assert.deepStrictEqual(messages, []);
-  });
+  }); // 217.6
 
 });

test/aq4.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2022, 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2022, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -151,7 +151,7 @@ describe('267. aq4.js', function() {
       },
       /ORA-24033:/
     );
-  });
+  }); // 267.1
 
   it('267.2 single element in array', async () => {
     // Enqueue
@@ -179,7 +179,7 @@ describe('267. aq4.js', function() {
     const msg = await queue2.deqOne ();
     assert.strictEqual(msg.payload.NAME, "scott");
     await conn.commit();
-  });
+  }); // 267.2
 
 
   it('267.3 Negative - numbers as recipients ', async () => {
@@ -197,7 +197,7 @@ describe('267. aq4.js', function() {
       },
       /NJS-007:/
     );
-  });
+  }); // 267.3
 
   it('267.4 Negative - number, string, date as recipients ', async () => {
     const queue1 = await conn.getQueue(
@@ -214,7 +214,7 @@ describe('267. aq4.js', function() {
       },
       /NJS-007:/
     );
-  });
+  }); // 267.4
 
   it('267.5 Negative -  null value for recipient', async () => {
     const queue1 = await conn.getQueue(
@@ -231,7 +231,7 @@ describe('267. aq4.js', function() {
       },
       /NJS-007:/
     );
-  });
+  }); // 267.5
 
   it('267.6 Negative - undefined value for recipient', async () => {
     const queue1 = await conn.getQueue(
@@ -248,7 +248,7 @@ describe('267. aq4.js', function() {
       },
       /NJS-007:/
     );
-  });
+  }); // 267.6
 
   it('267.7 Negative - dequeue non-existent name', async () => {
     await assert.rejects(
@@ -279,7 +279,7 @@ describe('267. aq4.js', function() {
       },
       /ORA-25242:/
     );
-  });
+  }); // 267.7
 
 
   it('267.8 empty recipient list with enqMany', async () => {
@@ -297,7 +297,7 @@ describe('267. aq4.js', function() {
       },
       /ORA-24033:/
     );
-  });
+  }); // 267.8
 
   it('267.9 recipient list with enqMany', async () => {
     const msgList = [];
@@ -322,7 +322,7 @@ describe('267. aq4.js', function() {
     );
     const msgs = await queue2.deqMany(5);
     assert.strictEqual(msgs.length, 4);
-  });
+  }); // 267.9
 
 
   it('267.10 recipient list with enqMany non-existent in dequeue', async () => {
@@ -348,7 +348,7 @@ describe('267. aq4.js', function() {
     );
     const msgs = await queue2.deqMany(5);
     assert.strictEqual(msgs.length, 0);
-  });
+  }); // 267.10
 
   it('267.11 recipient list with enqMany invalid datatype in dequeue', async () => {
     const msgList = [];
@@ -366,6 +366,6 @@ describe('267. aq4.js', function() {
       },
       /NJS-007:/
     );
-  });
+  }); // 267.11
 
 });

test/aq5.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -129,6 +129,6 @@ describe('281.aq5.js', function() {
     assert(msg);
 
     await conn.unsubscribe(objQueueName);
-  });
+  }); // 281.1
 
 });

test/aq7.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -112,7 +112,7 @@ describe('283. aq7.js', function() {
 
     assert.strictEqual(msg.payload.empName, "Chris");
     assert.strictEqual(msg.payload.empCity, "Melbourne");
-  });
+  }); // 283.1
 
   it('283.2 JSON type in enqMany/deqMany', async () => {
     const queue3 = await conn.getQueue(objQueueName,
@@ -146,7 +146,7 @@ describe('283. aq7.js', function() {
     assert.equal(msgs[0].payload.empId, 101);
     assert.equal(msgs[1].payload.empId, 102);
     assert.equal(msgs[2].payload.empId, 103);
-  });
+  }); // 283.2
 
   it('283.3 Map JS object directly into JSON - enqOne/deqOne', async () => {
     const queue = await conn.getQueue(objQueueName,
@@ -171,7 +171,7 @@ describe('283. aq7.js', function() {
 
     assert.equal(msg.payload.empName, "employee name");
     assert.equal(msg.payload.empCity, "City");
-  });
+  }); // 283.3
 
   it('283.4 Map JS object directly into JSON - enqMany/deqMany', async () => {
     const queue = await conn.getQueue(objQueueName,
@@ -185,7 +185,7 @@ describe('283. aq7.js', function() {
     ];
 
     await queue.enqMany(dataList);
-    await conn.commit ();
+    await conn.commit();
 
     const queue2 = await conn.getQueue(objQueueName,
       {payloadType: oracledb.DB_TYPE_JSON});
@@ -205,7 +205,7 @@ describe('283. aq7.js', function() {
     assert.equal(msgs[0].payload.empCity, "City1");
     assert.equal(msgs[1].payload.empCity, "City2");
     assert.equal(msgs[2].payload.empCity, "City3");
-  });
+  }); // 283.4
 
   it('283.5 enqOne and deqOne Null & Boolean in JSON', async function() {
     const queue = await conn.getQueue(objQueueName,
@@ -229,7 +229,7 @@ describe('283. aq7.js', function() {
 
     assert.equal(msg.payload.empName, null);
     assert.equal(msg.payload.empCity, true);
-  });
+  }); // 283.5
 
   it('283.6 enqMany and deqMany Null & Boolean in JSON', async function() {
     const queue = await conn.getQueue(objQueueName,
@@ -263,7 +263,7 @@ describe('283. aq7.js', function() {
     assert.equal(msgs[0].payload.empCity, true);
     assert.equal(msgs[1].payload.empCity, false);
     assert.equal(msgs[2].payload.empCity, true);
-  });
+  }); // 283.6
 
   it('283.7 enqOne and deqOne with JSON val as array type', async function() {
     const queue = await conn.getQueue(objQueueName,
@@ -278,11 +278,11 @@ describe('283. aq7.js', function() {
     const queue2 = await conn.getQueue(objQueueName,
       {payloadType: oracledb.DB_TYPE_JSON});
     const msg = await queue2.deqOne();
-    await conn.commit ();
+    await conn.commit();
 
     assert.deepStrictEqual(msg.payload.employees,
       [ "Employee1", "Employee2", "Employee3" ]);
-  });
+  }); // 283.7
 
   it('283.8 enqMany and deqMany with JSON val as array type', async function() {
     const queue3 = await conn.getQueue (objQueueName,
@@ -294,8 +294,8 @@ describe('283. aq7.js', function() {
       {payload: { empName3: ["Employee #3", 103] }}
     ];
 
-    await queue3.enqMany (empList);
-    await conn.commit ();
+    await queue3.enqMany(empList);
+    await conn.commit();
 
     const queue4 = await conn.getQueue(objQueueName,
       {payloadType: oracledb.DB_TYPE_JSON});
@@ -311,7 +311,7 @@ describe('283. aq7.js', function() {
     assert.deepStrictEqual(msgs[0].payload.empName1, ["Employee #1", 101]);
     assert.deepStrictEqual(msgs[1].payload.empName2, ["Employee #2", 102]);
     assert.deepStrictEqual(msgs[2].payload.empName3, ["Employee #3", 103]);
-  });
+  }); // 283.8
 
   it('283.9 enqOne and deqOne JSON val as object type', async function() {
     const queue = await conn.getQueue(objQueueName,
@@ -331,7 +331,7 @@ describe('283. aq7.js', function() {
 
     assert.deepStrictEqual(msg.payload.employee,
       { "name": "Employee1", "age": 30, "city": "New City" });
-  });
+  }); // 283.9
 
   it('283.10 enqMany and deqMany with JSON val as object type', async function() {
     const queue3 = await conn.getQueue (objQueueName,
@@ -366,7 +366,7 @@ describe('283. aq7.js', function() {
       { "name": "Employee2", "age": 30, "city": "New York" });
     assert.deepStrictEqual(msgs[2].payload.empDetails3,
       { "name": "Employee3", "age": 28, "city": "New Land" });
-  });
+  }); // 283.10
 
   it('283.11 enqOne and deqOne CLOB value into a JSON key', async function() {
     const inFileName = './test/clobexample.txt';
@@ -391,5 +391,5 @@ describe('283. aq7.js', function() {
     await conn.commit();
 
     assert.deepStrictEqual(msg.payload, jsonDoc);
-  });
+  }); // 283.11
 });

test/instanceof1.js

@@ -73,7 +73,11 @@ describe('45. instanceof1.js', function() {
     const result = await conn.execute('select to_clob(dummy) from dual');
     const lob = result.rows[0][0];
     assert(lob instanceof oracledb.Lob);
-    lob.destroy();
+    await new Promise((resolve, reject) => {
+      lob.on('error', reject);
+      lob.on('close', resolve);
+      lob.destroy();
+    });
     await conn.close();
   }); // 45.4
 

test/jsonDualityViews7.js

@@ -710,7 +710,7 @@ describe('297. jsonDualityViews7.js', function() {
       let lob = await connection.createLob(oracledb.CLOB);
 
       // Write the buffer to the CLOB
-      await lob.write(JSON.stringify (arr));
+      await lob.write(JSON.stringify(arr));
 
       await connection.execute(
         `INSERT INTO vector