Final set of test and document updates for all the new features

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -667,6 +667,67 @@ Connection Methods
         * - Error ``error``
           - If ``createLob()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
 
+.. method:: connection.decodeOSON()
+
+    .. versionadded:: 6.4
+
+    .. code-block:: javascript
+
+        decodeOSON(Buffer buf);
+
+    This synchronous method decodes an OSON Buffer and returns a Javascript
+    value. This method is useful for fetching BLOB columns that have the check
+    constraint ``IS JSON FORMAT OSON`` enabled.
+
+    The parameters of the ``connection.decodeOSON()`` are:
+
+    .. list-table-with-summary:: connection.decodeOSON() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``buf``
+          - Buffer
+          - The OSON buffer that is to be decoded.
+
+    See :ref:`osontype` for an example.
+
+.. method:: connection.encodeOSON()
+
+    .. versionadded:: 6.4
+
+    .. code-block:: javascript
+
+        encodeOSON(Any value);
+
+    This synchronous method encodes a JavaScript value to OSON bytes and
+    returns a Buffer. This method is useful for inserting OSON bytes directly
+    into BLOB columns that have the check constraint ``IS JSON FORMAT OSON``
+    enabled.
+
+    The parameters of the ``connection.encodeOSON()`` are:
+
+    .. list-table-with-summary:: connection.encodeOSON() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 20
+        :summary: The first column displays the name of the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``value``
+          - Any
+          - The JavaScript value that is to be encoded into OSON bytes. The JavaScript value can be any value supported by `JSON <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-FBC22D72-AA64-4B0A-92A2-837B32902E2C>`__.
+
+    See :ref:`osontype` for an example.
+
 .. method:: connection.execute()
 
     **Promise**::

doc/src/api_manual/lob.rst

@@ -161,22 +161,61 @@ Lob Methods
 
     **Promise**::
 
-        promise = getData();
+        promise = getData(Number offset, Number amount);
 
-    Returns all the LOB data. CLOBs and NCLOBs will be returned as strings.
-    BLOBs will be returned as a Buffer. This method is usable for LOBs up to
-    1 GB in length.
+    Returns a portion (or all) of the data in the LOB.
+
+    The parameters of ``lob.getData()`` are:
+
+    .. list-table-with-summary:: lob.getData() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the name of the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``offset``
+          - Number
+          - For LOBs of type CLOB and NCLOB, the offset is the position from which the data is to be fetched, in `UCS-2 code points <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-42BCD57A-A380-4ED9-897F-0500A94803D1>`__. UCS-2 code points are equivalent to characters for all but supplemental characters. If supplemental characters are in the LOB, the offset and amount will have to be chosen carefully to avoid splitting a character.
+
+            For LOBs of type BLOB and BFILE, the offset is the position of the byte from which the data is to be fetched.
+
+            The default is *1*.
+
+            The value of ``offset`` must be greater than or equal to *1*.
+
+            If the ``offset`` specified in :meth:`lob.getData()` exceeds the length of the LOB, then the value *null* is returned.
+        * - ``amount``
+          - Number
+          - For LOBs of type CLOB and NCLOB, the amount is the number of UCS-2 code points to be read from the absolute offset of the CLOB or NCLOB.
+
+            For LOBs of type BLOB and BFILE, the amount is the number of bytes to be read from the absolute offset of the BLOB or BFILE.
+
+            The default is the length of the LOB.
+
+            The value of ``amount`` must be greater than *0*.
+
+            If the ``amount`` specified in :meth:`lob.getData()` exceeds the length of the LOB, then only the data starting from the offset to the end of the LOB is returned.
+
+            If the ``amount`` specified in :meth:`lob.getData()` is *0*, then you will get the error ``NJS-005: invalid value for parameter 2``.
 
     For queries returning LOB columns, it can be more efficient to use
     :attr:`~oracledb.fetchAsString`, :attr:`~oracledb.fetchAsBuffer`, or
     :ref:`fetchInfo <propexecfetchinfo>` instead of ``lob.getData()``.
 
     Note that it is an asynchronous method and requires a round-trip to the
-    database:
+    database.
 
     .. code-block:: javascript
 
-        const data = await myLob.getData();
+        const data = await myLob.getData(offset, amount);
+
+    .. versionchanged:: 6.4
+
+        The ``offset`` and ``amount`` parameters were added.
 
     **Callback**:
 

doc/src/api_manual/oracledb.rst

@@ -3494,9 +3494,20 @@ node-oracledb, allowing use of new features.
     specified when creating VARCHAR2 and LOB columns ensures that only JSON
     data is stored in these columns.
 
+    Also, BLOB columns that were created with the ``IS JSON FORMAT OSON``
+    check constraint are fetched in the same way as
+    :ref:`columns of type JSON <json21fetch>` when this property is set to
+    *true*. The node-oracledb :ref:`Thick mode <enablingthick>` requires
+    Oracle Client 21c (or later).
+
     The default value is *false*.
 
     In a future version of node-oracledb, the setting of this attribute will
     no longer be required since this will be the default behavior.
 
     .. versionadded:: 6.3
+
+    .. versionchanged:: 6.4
+
+        BLOB columns with the ``IS JSON FORMAT OSON`` check constraint enabled
+        can now be fetched as JSON type columns when this property is set.

doc/src/release_notes.rst

@@ -13,30 +13,31 @@ node-oracledb `v6.4.0 <https://github.com/oracle/node-oracledb/compare/v6.3.0...
 Common Changes
 ++++++++++++++
 
-#)  Enhanced :meth:`~lob.getData` method to accept offset and amount arguments.
+#)  Enhanced :meth:`lob.getData()` method to accept ``offset`` and ``amount``
+    arguments.
     See `Issue #1643 <https://github.com/oracle/node-oracledb/issues/1643>`__.
 
-#)  Add support for fetching BLOB columns which have "IS JSON FORMAT OSON"
-    constraint enabled in the same way as columns of type JSON.
-    In node-oracledb :ref:`Thick mode <enablingthick>` this requires
-    Oracle Client 21c or higher. Applications can get this new fetch behaviour
+#)  Added support for fetching BLOB columns which have the
+    ``IS JSON FORMAT OSON`` constraint enabled in the same way as columns of
+    type JSON. In node-oracledb :ref:`Thick mode <enablingthick>` this requires
+    Oracle Client 21c or later. Applications can get this new fetch behaviour
     by setting the oracledb property :attr:`oracledb.future.oldJsonColumnAsObj`
     to `true`. The default value for this property is `false` which retains
     the existing fetch behaviour.
     In a future version, the new fetch behaviour will become default and
     setting this property will no longer be needed.
 
-#)  Added methods :meth:`~Connection.decodeOSON` and
-    :meth:`~Connection.encodeOSON` to support fetching and inserting into
+#)  Added methods :meth:`connection.decodeOSON()` and
+    :meth:`connection.encodeOSON()` to support fetching and inserting into
     columns which have the check constraint ``IS JSON FORMAT OSON``
-    enabled. Refer `Storing and Managing JSON Data <https://docs.oracle.com/en/database/oracle/oracle-database/19/adjsn/overview-of-storage-and-management-of-JSON-data.html#GUID-26AB85D2-3277-451B-BFAA-9DD45355FCC7>`__
+    enabled. See :ref:`osontype` for more information.
 
 #)  Connections to standby database opened `MOUNTED` return
-    `NAN <https://github.com/nodejs/nan>` for :meth:`~connection.maxOpenCursors`
-    Fixed to return 0.
+    `NAN <https://github.com/nodejs/nan>`__ for
+    :attr:`connection.maxOpenCursors`. Fixed to return 0.
 
-#)  Added :meth:`~dbObject.toMap` method to :ref:`DbObject Class<dbobjectclass>`
-    which returns a map object.
+#)  Added :meth:`~dbObject.toMap()` method to
+    :ref:`DbObject Class <dbobjectclass>` which returns a map object.
     See `Issue #1627 <https://github.com/oracle/node-oracledb/issues/1627>`__.
 
 #)  Added support to accept an object as an input parameter in the
@@ -46,18 +47,18 @@ Common Changes
     retrieve SQL string and bind values.
     See `Issue #1629 <https://github.com/oracle/node-oracledb/issues/1629>`__.
 
-#)  Added new extended :ref:`metadata <execmetadata>` information attribute
+#)  Added a new extended :ref:`metadata <execmetadata>` information attribute
     ``isOson`` for a fetched column.
 
 #)  Added :attr:`oracledb.poolPingTimeout` and :attr:`pool.poolPingTimeout`
-    to limit the :meth:`connection.ping()` call time.
+    properties to limit the :meth:`connection.ping()` call time.
     `Issue #1626 <https://github.com/oracle/node-oracledb/issues/1626>`__.
 
 #)  Added the :ref:`warning <execmanywarning>` property to the
     :ref:`result <resultobjproperties>` object of
     :meth:`connection.executeMany()`.
 
-#)  Attribute and element values of :ref:`DbObject Class
+#)  The attribute and element values of :ref:`DbObject Class
     <dbobjectclass>` objects that contain strings or bytes now have their
     maximum size constraints checked. Errors ``NJS-142`` and ``NJS-143`` are
     now raised when the size constraints are violated.
@@ -74,20 +75,21 @@ Common Changes
 Thin Mode Changes
 ++++++++++++++++++
 
-#)  Fix for the intermittent error ``NJS-103`` seen while fetching large number
-    of CLOB columns whose metadata is split across multiple packets.
+#)  Fixed the intermittent error ``NJS-103`` which was seen while fetching
+    large number of CLOB columns whose metadata is split across multiple
+    packets.
     `Issue #1642 <https://github.com/oracle/node-oracledb/issues/1642>`__.
 
-#)  Fixed potential cursor issues when using DRCP.
+#)  Fixed potential cursor issues when using :ref:`DRCP <drcp>`.
 
 #)  Fixed bug in reading PLS_INTEGER type when used in PL/SQL records.
 
 #)  Error ``NJS-141: errors in array DML exceed 65535`` is now raised
     when the number of batch errors exceed 65535 when calling
     :meth:`connection.executeMany()` with the parameter ``batchErrors``
-    set to the value `true`. Note that in thick mode, this error is not raised
-    unless the number of batch errors is a multiple of 65536; instead,
-    the number of batch errors returned is modulo 65536.
+    set to the value `true`. Note that in node-oracledb Thick mode, this
+    error is not raised unless the number of batch errors is a multiple of
+    65536; instead, the number of batch errors returned is modulo 65536.
 
 #)  Updated connection pool to scan and remove idle connections from
     the beginning of the free connection list. This will ensure removal of all
@@ -100,9 +102,11 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Added support for asynchronous iteration of SODA document cursors.
+#)  Added support for asynchronous iteration of
+    :ref:`SODA document cursors <sodadocumentcursorclass>`.
 
-#)  Internal code and memory optimization changes for Advanced Queuing.
+#)  Internal code and memory optimization changes for
+    :ref:`Advanced Queuing <aq>`.
 
 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/json_data_type.rst

@@ -148,6 +148,93 @@ If you are using node-oracledb Thick mode, you must use Oracle Client 19c
     const r = await conn.execute(`SELECT po_document FROM j_purchaseorder`);
     console.dir(r.rows, { depth: null });
 
+.. _osontype:
+
+Using BLOB columns with OSON Storage Format in node-oracledb
+============================================================
+
+You can use BLOB columns with Oracle's optimized binary storage format called
+`OSON <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-CBEDC779-
+39A3-43C9-AF38-861AE3FC0AEC>`__ if you want the fastest query and update
+performance. This OSON binary encoding format can be used with BLOB columns in
+both node-oracledb Thin or Thick modes. For Release 19c, BLOB with format OSON
+is supported only for Oracle Autonomous Databases. For Thick mode, you must
+additionally use Oracle Client 21c (or later).
+
+To specify `OSON format for BLOB columns <https://docs.oracle.com/en/database/
+oracle/oracle-database/19/adjsn/overview-of-storage-and-management-of-JSON-
+data.html#GUID-26AB85D2-3277-451B-BFAA-9DD45355FCC7>`__, you can use the check
+constraint with the clause ``IS JSON FORMAT OSON`` when creating a table. This
+check constraint ensures that only binary encoded OSON data is stored in that
+column. For example, to create a table with a BLOB column containing OSON
+data:
+
+.. code-block:: sql
+
+    CREATE TABLE my_table (oson_col BLOB CHECK (oson_col IS JSON FORMAT OSON));
+
+**Inserting into BLOB columns with OSON Data**
+
+To encode the Javascript value into OSON bytes, you can use the
+:meth:`connection.encodeOSON()` method. For example:
+
+.. code-block:: javascript
+
+    const data = {key1: "val1"};
+    // Generate OSON bytes
+    const osonBytes = connection.encodeOSON(data);
+    console.log(osonBytes);
+
+This method returns a Buffer and prints an output such as::
+
+    <Buffer ff 4a 5a 01 21 02 01 00 05 00 0d 00 00 fa 00 00 04 6b 65 79 32 a4 01 01 00 00 00 07 33 04 76 61 6c 32>
+
+To insert the OSON bytes into the table, you can use:
+
+.. code-block:: javascript
+
+    // Insert the OSON bytes
+    const result = await connection.execute(
+      `INSERT INTO my_table (oson_col) VALUES (:1)`,
+      [osonBytes]
+    );
+
+**Fetching BLOB Columns with OSON Data**
+
+You can fetch BLOB columns which have the ``IS JSON FORMAT OSON`` check
+constraint enabled in the same way :ref:`JSON type columns <json21fetch>`
+are fetched when using Oracle Database 21c (or later). This can be done by
+setting :attr:`oracledb.future.oldJsonColumnAsObj` to the value *true* as
+shown below. If you are using node-oracledb Thick mode, you must use Oracle
+Client 21c (or later) for this setting to work. For example:
+
+.. code-block:: javascript
+
+    oracledb.future.oldJsonColumnAsObj = true;
+    const result = await connection.execute(`SELECT oson_col FROM my_table`);
+    console.log(result.rows[0][0]);
+
+This prints an output such as::
+
+    {key1: "val1"}
+
+If you do not set the :attr:`oracledb.future.oldJsonColumnAsObj` to *true*,
+then you can fetch BLOB columns that contain OSON data as shown below:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(
+        `SELECT json_object ('hello' value 'world' returning blob format oson
+         ) FROM dual`
+    );
+    const decodeOsonObj = connection.decodeOSON(result.rows[0][0]);
+    console.log(decodeOsonObj);
+
+The :meth:`connection.decodeOSON()` decodes the OSON Buffer and returns a
+Javascript value. This prints an ouput such as::
+
+    { hello: 'world' }
+
 IN Bind Type Mapping
 ====================