Code refactoring for OSON encode decode functionality

Author: sharadraju

doc/src/release_notes.rst

@@ -13,6 +13,11 @@ node-oracledb `v6.4.0 <https://github.com/oracle/node-oracledb/compare/v6.3.0...
 Common Changes
 ++++++++++++++
 
+#)  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>`__
+
 #)  Connections to standby database opened `MOUNTED` return
     `NAN <https://github.com/nodejs/nan>` for :meth:`~connection.maxOpenCursors`
     Fixed to return 0.

lib/connection.js

@@ -43,6 +43,7 @@ const constants = require('./constants.js');
 const settings = require('./settings.js');
 const transformer = require('./transformer.js');
 const types = require('./types.js');
+const oson = require('impl/datahandlers/oson.js');
 
 // global mapping of subscriptions; these cannot be tied to a particular
 // connection or pool since subscriptions can be created with one connection
@@ -839,6 +840,29 @@ class Connection extends EventEmitter {
     this._impl.setECID(value);
   }
 
+  //---------------------------------------------------------------------------
+  // decode()
+  //
+  // Decodes OSON Buffer to JS data type.
+  //---------------------------------------------------------------------------
+  decodeOSON(buf) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Buffer.isBuffer(buf), 1);
+    const decoder = new oson.OsonDecoder(buf);
+    return decoder.decode();
+  }
+
+
+  //---------------------------------------------------------------------------
+  // encode()
+  //
+  // Encodes the JS value into OSON bytes.
+  //---------------------------------------------------------------------------
+  encodeOSON(value) {
+    const encoder = new oson.OsonEncoder();
+    return encoder.encode(transformer.transformJsonValue(value));
+  }
+
   //---------------------------------------------------------------------------
   // execute()
   //

lib/thin/protocol/buffer.js renamed to lib/impl/datahandlers/buffer.js

@@ -29,8 +29,8 @@
 const { Buffer } = require('buffer');
 const constants = require("./constants.js");
 const errors = require("../../errors.js");
-const settings = require("../../settings.js");
 const types = require("../../types.js");
+const nodbUtil = require("../../util.js");
 
 /**
  * Base buffer class used for managing buffered data without unnecessary
@@ -184,7 +184,7 @@ class BaseBuffer {
       fseconds = Math.floor(buf.readUInt32BE(7) / (1000 * 1000));
     }
     const year = (buf[0] - 100) * 100 + buf[1] - 100;
-    return settings._makeDate(useLocalTime, year, buf[2], buf[3], buf[4] - 1,
+    return nodbUtil.makeDate(useLocalTime, year, buf[2], buf[3], buf[4] - 1,
       buf[5] - 1, buf[6] - 1, fseconds, 0);
   }
 
@@ -887,29 +887,6 @@ class BaseBuffer {
 
   }
 
-  //---------------------------------------------------------------------------
-  // writeQLocator()
-  //
-  // Writes a QLocator. QLocators are always 40 bytes in length.
-  //---------------------------------------------------------------------------
-  writeQLocator(numBytes) {
-    this.writeUB4(40);                  // QLocator length
-    this.writeUInt8(40);                // repeated length
-    this.writeUInt16BE(38);             // internal length
-    this.writeUInt16BE(constants.TNS_LOB_QLOCATOR_VERSION);
-    this.writeUInt8(constants.TNS_LOB_LOC_FLAGS_VALUE_BASED |
-      constants.TNS_LOB_LOC_FLAGS_BLOB | constants.TNS_LOB_LOC_FLAGS_ABSTRACT);
-    this.writeUInt8(constants.TNS_LOB_LOC_FLAGS_INIT);
-    this.writeUInt16BE(0);              // additional flags
-    this.writeUInt16BE(1);              // byt1
-    this.writeUInt64BE(numBytes);
-    this.writeUInt16BE(0);              // unused
-    this.writeUInt16BE(0);              // csid
-    this.writeUInt16BE(0);              // unused
-    this.writeUInt64BE(0);              // unused
-    this.writeUInt64BE(0);              // unused
-  }
-
   //---------------------------------------------------------------------------
   // writeStr()
   //

lib/impl/datahandlers/constants.js

@@ -0,0 +1,105 @@
+// 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.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const constants = require('../../constants.js');
+
+module.exports = {
+
+  // vector constants
+  TNS_VECTOR_MAGIC_BYTE: 0xDB,
+  TNS_VECTOR_VERSION: 0,
+
+  // vector flags
+  TNS_VECTOR_FLAG_DIM_UINT8: 0x0001,
+  TNS_VECTOR_FLAG_DIM_UINT32: 0x0002,
+  TNS_VECTOR_FLAG_NORMSRC: 0x0040,
+  TNS_VECTOR_FLAG_NORM: 0x0008,
+
+  // base JSON constants
+  TNS_JSON_MAGIC_BYTE_1: 0xff,
+  TNS_JSON_MAGIC_BYTE_2: 0x4a,       // 'J'
+  TNS_JSON_MAGIC_BYTE_3: 0x5a,       // 'Z'
+  TNS_JSON_VERSION: 1,
+  TNS_JSON_FLAG_HASH_ID_UINT8: 0x0100,
+  TNS_JSON_FLAG_HASH_ID_UINT16: 0x0200,
+  TNS_JSON_FLAG_NUM_FNAMES_UINT16: 0x0400,
+  TNS_JSON_FLAG_FNAMES_SEG_UINT32: 0x0800,
+  TNS_JSON_FLAG_TINY_NODES_STAT: 0x2000,
+  TNS_JSON_FLAG_TREE_SEG_UINT32: 0x1000,
+  TNS_JSON_FLAG_REL_OFFSET_MODE: 0x01,
+  TNS_JSON_FLAG_INLINE_LEAF: 0x02,
+  TNS_JSON_FLAG_LEN_IN_PCODE: 0x04,
+  TNS_JSON_FLAG_NUM_FNAMES_UINT32: 0x08,
+  TNS_JSON_FLAG_IS_SCALAR: 0x10,
+
+  // JSON data types
+  TNS_JSON_TYPE_NULL: 0x30,
+  TNS_JSON_TYPE_TRUE: 0x31,
+  TNS_JSON_TYPE_FALSE: 0x32,
+  TNS_JSON_TYPE_STRING_LENGTH_UINT8: 0x33,
+  TNS_JSON_TYPE_NUMBER_LENGTH_UINT8: 0x34,
+  TNS_JSON_TYPE_BINARY_DOUBLE: 0x36,
+  TNS_JSON_TYPE_STRING_LENGTH_UINT16: 0x37,
+  TNS_JSON_TYPE_STRING_LENGTH_UINT32: 0x38,
+  TNS_JSON_TYPE_TIMESTAMP: 0x39,
+  TNS_JSON_TYPE_BINARY_LENGTH_UINT16: 0x3a,
+  TNS_JSON_TYPE_BINARY_LENGTH_UINT32: 0x3b,
+  TNS_JSON_TYPE_DATE: 0x3c,
+  TNS_JSON_TYPE_INTERVAL_YM: 0x3d,
+  TNS_JSON_TYPE_INTERVAL_DS: 0x3e,
+  TNS_JSON_TYPE_TIMESTAMP_TZ: 0x7c,
+  TNS_JSON_TYPE_TIMESTAMP7: 0x7d,
+  TNS_JSON_TYPE_BINARY_FLOAT: 0x7f,
+  TNS_JSON_TYPE_OBJECT: 0x84,
+  TNS_JSON_TYPE_ARRAY: 0xc0,
+  TNS_JSON_TYPE_EXTENDED: 0x7b,
+  TNS_JSON_TYPE_VECTOR: 0x01,
+
+  // timezone offsets
+  TZ_HOUR_OFFSET: 20,
+  TZ_MINUTE_OFFSET: 60,
+
+  // general constants
+  TNS_MAX_SHORT_LENGTH: 252,
+  TNS_DURATION_MID: 0x80000000,
+  TNS_DURATION_OFFSET: 60,
+  TNS_CHUNK_SIZE: 32767,
+  TNS_HAS_REGION_ID: 0x80,
+  NUMBER_MAX_DIGITS: 40,
+  BUFFER_CHUNK_SIZE: 65536,
+  CSFRM_IMPLICIT: constants.CSFRM_IMPLICIT,
+
+  // vector generic constants
+  VECTOR_FORMAT_FLOAT32: constants.VECTOR_FORMAT_FLOAT32,
+  VECTOR_FORMAT_FLOAT64: constants.VECTOR_FORMAT_FLOAT64,
+  VECTOR_FORMAT_INT8: constants.VECTOR_FORMAT_INT8,
+
+  TNS_NULL_LENGTH_INDICATOR: 255,
+  TNS_LONG_LENGTH_INDICATOR: 254,
+
+};

lib/thin/protocol/oson.js renamed to lib/impl/datahandlers/oson.js

@@ -32,6 +32,8 @@ const constants = require("./constants.js");
 const errors = require("../../errors.js");
 const types = require("../../types.js");
 const util = require("util");
+const vector = require("./vector.js");
+const nodbUtil = require("../../util.js");
 
 /**
  * Class used for decodeing
@@ -106,7 +108,7 @@ class OsonDecoder extends BaseBuffer {
   _decodeNode() {
 
     // if the most significant bit is set the node refers to a container
-    const nodeType = this.readUInt8();
+    let nodeType = this.readUInt8();
     if (nodeType & 0x80) {
       return this._decodeContainerNode(nodeType);
     }
@@ -145,6 +147,13 @@ class OsonDecoder extends BaseBuffer {
       return Buffer.from(this.readBytes(this.readUInt16BE()));
     } else if (nodeType === constants.TNS_JSON_TYPE_BINARY_LENGTH_UINT32) {
       return Buffer.from(this.readBytes(this.readUInt32BE()));
+    } else if (nodeType === constants.TNS_JSON_TYPE_EXTENDED) {
+      nodeType = this.readUInt8();
+      if (nodeType === constants.TNS_JSON_TYPE_VECTOR) {
+        const vecImage = this.readBytes(this.readUInt32BE());
+        const decoder = new vector.VectorDecoder(vecImage);
+        return decoder.decode();
+      }
     }
 
     // handle number/decimal with length stored inside the node itself
@@ -544,6 +553,15 @@ class OsonTreeSegment extends GrowableBuffer {
     } else if (Array.isArray(value)) {
       this._encodeArray(value, fnamesSeg);
 
+    // handle vectors
+    } else if (nodbUtil.isVectorValue(value)) {
+      this.writeUInt8(constants.TNS_JSON_TYPE_EXTENDED);
+      this.writeUInt8(constants.TNS_JSON_TYPE_VECTOR);
+      const encoder = new vector.VectorEncoder();
+      const buf = encoder.encode(value);
+      this.writeUInt32BE(buf.length);
+      this.writeBytes(buf);
+
     // handle objects
     } else {
       this._encodeObject(value, fnamesSeg);

lib/thin/protocol/vector.js renamed to lib/impl/datahandlers/vector.js

@@ -29,6 +29,8 @@
 const constants = require('./constants.js');
 const errors = require('./errors.js');
 const types = require('./types.js');
+const nodbUtil = require("./util.js");
+const vector = require('impl/datahandlers/vector.js');
 
 class Settings {
 
@@ -106,11 +108,29 @@ class Settings {
   // information).
   //---------------------------------------------------------------------------
   _makeDate(useLocal, year, month, day, hour, minute, second, fseconds, offset) {
-    if (useLocal) {
-      return new Date(year, month - 1, day, hour, minute, second, fseconds);
-    }
-    return new Date(Date.UTC(year, month - 1, day, hour, minute, second,
-      fseconds) - offset * 60000);
+    return nodbUtil.makeDate(useLocal, year, month, day, hour, minute, second, fseconds, offset);
+  }
+
+  //---------------------------------------------------------------------------
+  // _decodeVector()
+  //
+  // Returns a typed array by decoding buffer.
+  //
+  //---------------------------------------------------------------------------
+  _decodeVector(buffer) {
+    const decoder = new vector.VectorDecoder(buffer);
+    return decoder.decode();
+  }
+
+  //---------------------------------------------------------------------------
+  // _encodeVector()
+  //
+  // Create a Vector image from typedarray
+  //
+  //---------------------------------------------------------------------------
+  _encodeVector(value) {
+    const encoder = new vector.VectorEncoder();
+    return encoder.encode(value);
   }
 
   //---------------------------------------------------------------------------

lib/settings.js

@@ -31,7 +31,7 @@ const ConnectionImpl = require('../impl/connection.js');
 const ThinResultSetImpl = require('./resultSet.js');
 const ThinLobImpl  = require("./lob.js");
 const Protocol = require("./protocol/protocol.js");
-const { BaseBuffer } = require('./protocol/buffer.js');
+const { BaseBuffer } = require('../impl/datahandlers/buffer.js');
 const {NetworkSession: nsi} = require("./sqlnet/networkSession.js");
 const { Statement } = require("./statement");
 const thinUtil = require('./util');

lib/thin/connection.js

@@ -31,7 +31,7 @@ const constants = require('./protocol/constants.js');
 const errors = require('../errors.js');
 const types = require('../types.js');
 const DbObjectImpl = require('../impl/dbObject.js');
-const { GrowableBuffer } = require('./protocol/buffer.js');
+const { GrowableBuffer } = require('../impl/datahandlers/buffer.js');
 const ThinLobImpl = require('./lob.js');
 
 class DbObjectPickleBuffer extends GrowableBuffer {