oracledb 6.3.0 → 6.5.0

package/lib/impl/datahandlers/vector.js

@@ -0,0 +1,137 @@
+// 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 { BaseBuffer, GrowableBuffer } = require('./buffer.js');
+const { Buffer } = require('buffer');
+const constants = require("./constants.js");
+const errors = require("../../errors.js");
+
+/**
+ * Class used for decoding
+ */
+class VectorDecoder extends BaseBuffer {
+
+  //---------------------------------------------------------------------------
+  // decode()
+  //
+  // Decodes the VECTOR image and returns a JavaScript array corresponding to
+  // its contents.
+  //---------------------------------------------------------------------------
+  decode() {
+
+    // parse header
+    const magicByte = this.readUInt8();
+    if (magicByte != constants.TNS_VECTOR_MAGIC_BYTE)
+      errors.throwErr(errors.ERR_UNEXPECTED_DATA,
+        Buffer.from([magicByte]).toString('hex'));
+    const version = this.readUInt8();
+    if (version != constants.TNS_VECTOR_VERSION)
+      errors.throwErr(errors.ERR_VECTOR_VERSION_NOT_SUPPORTED, version);
+    const flags = this.readUInt16BE();
+    const vectorFormat = this.readUInt8();
+    const numElements = this.readUInt32BE();
+    let elementSize, result;
+    if (vectorFormat === constants.VECTOR_FORMAT_FLOAT32) {
+      elementSize = 4;
+      result = new Float32Array(numElements);
+    } else if (vectorFormat === constants.VECTOR_FORMAT_FLOAT64) {
+      elementSize = 8;
+      result = new Float64Array(numElements);
+    } else if (vectorFormat === constants.VECTOR_FORMAT_INT8) {
+      elementSize = 1;
+      result = new Int8Array(numElements);
+    } else {
+      errors.throwErr(errors.ERR_VECTOR_FORMAT_NOT_SUPPORTED, vectorFormat);
+    }
+    if (flags & constants.TNS_VECTOR_FLAG_NORM)
+      this.skipBytes(8);
+
+    // parse data
+    for (let i = 0; i < numElements; i++) {
+      const buf = this.readBytes(elementSize);
+      if (vectorFormat === constants.VECTOR_FORMAT_FLOAT32) {
+        result[i] = this.parseBinaryFloat(buf);
+      } else if (vectorFormat === constants.VECTOR_FORMAT_FLOAT64)  {
+        result[i] = this.parseBinaryDouble(buf);
+      } else {
+        result[i] = buf[0];
+      }
+    }
+
+    return result;
+  }
+
+}
+
+class VectorEncoder extends GrowableBuffer {
+
+  //---------------------------------------------------------------------------
+  // encode()
+  //
+  // Encodes the value as OSON and returns a buffer containing the OSON bytes.
+  //---------------------------------------------------------------------------
+  encode(value) {
+
+    // determine some basic information about the vector
+    let vectorFormat = constants.VECTOR_FORMAT_FLOAT32;
+    let writeFn = this.writeBinaryFloat.bind(this);
+
+    if (Array.isArray(value) || value instanceof Float64Array) {
+      vectorFormat = constants.VECTOR_FORMAT_FLOAT64;
+      writeFn = this.writeBinaryDouble.bind(this);
+    } else if (value instanceof Int8Array) {
+      vectorFormat = constants.VECTOR_FORMAT_INT8;
+      writeFn = this.writeSB1.bind(this);
+    }
+
+    // Let server generate the norm (TNS_VECTOR_FLAG_NORMSRC)
+    const flags = constants.TNS_VECTOR_FLAG_NORM
+      | constants.TNS_VECTOR_FLAG_NORMSRC;
+
+    // write header
+    this.writeUInt8(constants.TNS_VECTOR_MAGIC_BYTE);
+    this.writeUInt8(constants.TNS_VECTOR_VERSION);
+    this.writeUInt16BE(flags);
+    this.writeUInt8(vectorFormat);
+    this.writeUInt32BE(value.length);
+    this.reserveBytes(8);
+
+    // write data
+    value.forEach((element) => {
+      writeFn(element);
+    });
+
+    return this.buf.subarray(0, this.pos);
+  }
+
+}
+
+module.exports = {
+  VectorDecoder,
+  VectorEncoder
+};

package/lib/impl/pool.js

@@ -147,6 +147,15 @@ class PoolImpl {
     errors.throwNotImplemented("getting the pool ping interval");
   }
 
+  //---------------------------------------------------------------------------
+  // getPoolPingTimeout()
+  //
+  // Returns the pool ping Timeout (milliseconds).
+  //---------------------------------------------------------------------------
+  getPoolPingTimeout() {
+    errors.throwNotImplemented("getting the pool ping Timeout");
+  }
+
   //---------------------------------------------------------------------------
   // getPoolTimeout()
   //

package/lib/impl/resultset.js

@@ -33,6 +33,7 @@ const settings = require('../settings.js');
 const future = require('../future.js');
 const types = require('../types.js');
 const Lob = require('../lob.js');
+const oson = require('./datahandlers/oson.js');
 
 // define implementation class
 class ResultSetImpl {
@@ -105,26 +106,42 @@ class ResultSetImpl {
     let converter;
     const userConverter = metadata.converter;
 
-    // If IsJson is set convert to JSON objects unless
+    // If IsJson or IsOson is set, convert to JSON objects unless
     // user defined output type handler overwrites it.
-    if (future.oldJsonColumnAsObj && metadata.isJson && metadata.dbType !== types.DB_TYPE_JSON
+    if (metadata.dbType !== types.DB_TYPE_JSON && future.oldJsonColumnAsObj
       && userConverter === undefined) {
-      const outConverter = async function(val) {
-        if (!val) {
-          return val;
-        }
+      let outConverter;
+      if (metadata.isOson) {
+        outConverter = async function(val) {
+          if (!val) {
+            return val;
+          }
+          let result = val;
+          if (val instanceof Lob) {
+            result = await val.getData();
+          }
+          const decoder = new oson.OsonDecoder(result);
+          return decoder.decode();
+        };
+        converter = outConverter;
+      } else if (metadata.isJson) {
+        outConverter = async function(val) {
+          if (!val) {
+            return val;
+          }
 
-        let result = val;
-        if (val instanceof Lob) {
-          result = await val.getData();
-        }
-        if (result instanceof Buffer) {
-          result = result.toString();
-        }
-        result = JSON.parse(result);
-        return result;
-      };
-      converter = outConverter;
+          let result = val;
+          if (val instanceof Lob) {
+            result = await val.getData();
+          }
+          if (result instanceof Buffer) {
+            result = result.toString();
+          }
+          result = JSON.parse(result);
+          return result;
+        };
+        converter = outConverter;
+      }
     }
 
     // in thin mode, Oracle NUMBER values are internally fetched as string in

package/lib/lob.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -50,7 +50,7 @@ class Lob extends Duplex {
   // not already been closed (never called directly)
   async _destroy(err, cb) {
     // if LOB was already closed, nothing to do!
-    if (err && err.message.startsWith("NJS-108:"))
+    if (err && err.message.startsWith("NJS-003:"))
       delete this._impl;
     if (this._impl) {
       const lobImpl = this._impl;
@@ -185,12 +185,28 @@ class Lob extends Duplex {
   //---------------------------------------------------------------------------
   // getData()
   //
-  // Returns all of the data in the LOB as a single string or buffer.
+  // Return a portion (or all) of the data in the LOB. Note that the amount
+  // and offset are in bytes for BLOB and BFILE type LOBs and in UCS - 2 code
+  // points for CLOB and NCLOB type LOBs.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.
+  // Returns data in the LOB as a single string or buffer.
   //---------------------------------------------------------------------------
-  async getData() {
-    errors.assertArgCount(arguments, 0, 0);
+  async getData(offset, amount) {
+    errors.assertArgCount(arguments, 0, 2);
+    if (offset === undefined) {
+      offset = 1;
+    } else {
+      errors.assertParamValue(Number.isInteger(offset) && offset > 0, 1);
+    }
+    if (amount === undefined) {
+      amount = 0;
+    } else {
+      errors.assertParamValue(Number.isInteger(amount) && amount > 0, 2);
+    }
     errors.assert(this._impl, errors.ERR_INVALID_LOB);
-    return await this._impl.getData();
+    return await this._impl.getData(offset, amount);
   }
 
   //---------------------------------------------------------------------------

package/lib/oracledb.js

@@ -124,6 +124,16 @@ function _initializeThinDriver() {
 // Returns a boolean indicating if the supplied value is a valid privilege.
 //---------------------------------------------------------------------------
 function _isPrivilege(value) {
+  // Privileges are mutually exclusive and cannot be specified together
+  // except SYSPRELIM, which cannot be specified alone, it is specified in a
+  // combo with SYSOPER or SYSDBA.  SYSPRELIM is used only for
+  // startup/shutdown
+
+  // If SYSPRELIM specified, clear the bit
+  if (value & constants.SYSPRELIM) {
+    value = value ^ constants.SYSPRELIM;
+  }
+
   return (
     value === constants.SYSASM ||
     value === constants.SYSBACKUP ||
@@ -131,7 +141,6 @@ function _isPrivilege(value) {
     value === constants.SYSDG ||
     value === constants.SYSKM ||
     value === constants.SYSOPER ||
-    value === constants.SYSPRELIM ||
     value === constants.SYSRAC
   );
 }
@@ -368,6 +377,13 @@ async function _verifyOptions(options, inCreatePool) {
       outOptions.poolPingInterval = options.poolPingInterval;
     }
 
+    // poolPingTimeout must be an integer (>= 0)
+    if (options.poolPingTimeout !== undefined) {
+      errors.assertParamPropValue(Number.isInteger(options.poolPingTimeout) &&
+    options.poolPingTimeout >= 0, 1, "poolPingTimeout");
+      outOptions.poolPingTimeout = options.poolPingTimeout;
+    }
+
     // homogeneous must be a boolean (and defaults to True)
     outOptions.homogeneous = true;
     if (options.homogeneous !== undefined) {
@@ -558,6 +574,7 @@ async function createPool(options) {
     "poolIncrement",
     "poolTimeout",
     "poolPingInterval",
+    "poolPingTimeout",
     "queueMax",
     "queueTimeout");
 
@@ -824,6 +841,7 @@ module.exports = {
   AqQueue,
   BaseDbObject,
   Connection,
+  JsonId: types.JsonId,
   Lob,
   Pool,
   PoolStatistics,
@@ -880,6 +898,7 @@ module.exports = {
   DB_TYPE_TIMESTAMP_TZ: types.DB_TYPE_TIMESTAMP_TZ,
   DB_TYPE_VARCHAR: types.DB_TYPE_VARCHAR,
   DB_TYPE_XMLTYPE: types.DB_TYPE_XMLTYPE,
+  DB_TYPE_VECTOR: types.DB_TYPE_VECTOR,
 
   // fetchInfo type defaulting
   DEFAULT: constants.DEFAULT,
@@ -1011,6 +1030,11 @@ module.exports = {
   TPC_END_NORMAL: constants.TPC_END_NORMAL,
   TPC_END_SUSPEND: constants.TPC_END_SUSPEND,
 
+  // vector types
+  VECTOR_FORMAT_FLOAT32: constants.VECTOR_FORMAT_FLOAT32,
+  VECTOR_FORMAT_FLOAT64: constants.VECTOR_FORMAT_FLOAT64,
+  VECTOR_FORMAT_INT8: constants.VECTOR_FORMAT_INT8,
+
   // database type aliases
   BLOB: types.DB_TYPE_BLOB,
   BUFFER: types.DB_TYPE_RAW,
@@ -1113,6 +1137,10 @@ module.exports = {
     return settings.poolPingInterval;
   },
 
+  get poolPingTimeout() {
+    return settings.poolPingTimeout;
+  },
+
   get poolTimeout() {
     return settings.poolTimeout;
   },
@@ -1251,6 +1279,12 @@ module.exports = {
     settings.poolPingInterval = value;
   },
 
+  set poolPingTimeout(value) {
+    errors.assertPropValue(Number.isInteger(value) && value >= 0,
+      "poolPingTimeout");
+    settings.poolPingTimeout = value;
+  },
+
   set poolTimeout(value) {
     errors.assertPropValue(Number.isInteger(value) && value >= 0,
       "poolTimeout");

package/lib/pool.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -628,6 +628,15 @@ class Pool extends EventEmitter {
     return this._impl.getPoolPingInterval();
   }
 
+  //---------------------------------------------------------------------------
+  // poolPingTimeout
+  //
+  // Property for the ping timeout associated with the pool.
+  //---------------------------------------------------------------------------
+  get poolPingTimeout() {
+    return this._impl.getPoolPingTimeout();
+  }
+
   //---------------------------------------------------------------------------
   // poolTimeout
   //
@@ -672,7 +681,7 @@ class Pool extends EventEmitter {
     errors.assertParamPropBool(options, 1, "enableStatistics");
     errors.assertParamPropBool(options, 1, "resetStatistics");
     errors.assertParamPropUnsignedInt(options, 1, "poolMin");
-    errors.assertParamPropUnsignedInt(options, 1, "poolMax");
+    errors.assertParamPropUnsignedIntNonZero(options, 1, "poolMax");
     errors.assertParamPropUnsignedInt(options, 1, "poolMaxPerShard");
     errors.assertParamPropUnsignedInt(options, 1, "poolIncrement");
     errors.assertParamPropInt(options, 1, "poolPingInterval");
@@ -680,6 +689,12 @@ class Pool extends EventEmitter {
     errors.assertParamPropUnsignedInt(options, 1, "stmtCacheSize");
     errors.assertParamPropBool(options, 1, "sodaMetaDataCache");
 
+    // poolMax must be greater than or equal to poolMin
+    if (options.poolMin > options.poolMax) {
+      errors.throwErr(errors.ERR_INVALID_NUMBER_OF_CONNECTIONS, options.poolMax,
+        options.poolMin);
+    }
+
     // reconfiguration can happen only when status is OPEN
     this._checkPoolOpen(false);
 

package/lib/poolStatistics.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2021, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2021, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -72,6 +72,7 @@ class PoolStatistics {
     this.poolMaxPerShard = pool.poolMaxPerShard;
     this.poolMin = pool.poolMin;
     this.poolPingInterval = pool.poolPingInterval;
+    this.poolPingTimeout = pool.poolPingTimeout;
     this.poolTimeout = pool.poolTimeout;
     this.queueMax = pool.queueMax;
     this.queueTimeout = pool.queueTimeout;
@@ -124,6 +125,7 @@ class PoolStatistics {
     console.log('...poolMaxPerShard:', this.poolMaxPerShard);
     console.log('...poolMin:', this.poolMin);
     console.log('...poolPingInterval (seconds):', this.poolPingInterval);
+    console.log('...poolPingTimeout (milliseconds):', this.poolPingTimeout);
     console.log('...poolTimeout (seconds):', this.poolTimeout);
     console.log('...queueMax:', this.queueMax);
     console.log('...queueTimeout (milliseconds):', this.queueTimeout);

package/lib/settings.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -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 {
 
@@ -51,6 +53,7 @@ class Settings {
     this.poolMaxPerShard = 0;
     this.poolMin = 0;
     this.poolPingInterval = 60;
+    this.poolPingTimeout = 5000;
     this.poolTimeout = 60;
     this.prefetchRows = 2;
     this.queueTimeout = 60000;
@@ -60,6 +63,7 @@ class Settings {
     this.thinDriverInitialized = false;
     this.createFetchTypeMap(this.fetchAsString, this.fetchAsBuffer);
     this.fetchTypeHandler = undefined;
+    this._JsonId = types.JsonId;
   }
 
   //---------------------------------------------------------------------------
@@ -105,11 +109,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);
   }
 
   //---------------------------------------------------------------------------
@@ -159,6 +181,9 @@ class Settings {
           map.set(types.DB_TYPE_CLOB, types.DB_TYPE_LONG);
           map.set(types.DB_TYPE_NCLOB, types.DB_TYPE_LONG_NVARCHAR);
           break;
+        case types.DB_TYPE_VECTOR:
+          map.set(types.DB_TYPE_VECTOR, types.DB_TYPE_LONG);
+          break;
         case types.DB_TYPE_RAW:
           map.set(types.DB_TYPE_RAW, types.DB_TYPE_VARCHAR);
           break;

package/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,