oracledb 3.1.2 → 4.2.0

package/lib/oracledb.js

@@ -1,53 +1,80 @@
-/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
-
-/******************************************************************************
- *
- * You may not use the identified files except in compliance with the Apache
- * License, Version 2.0 (the "License.")
- *
- * You may obtain a copy of the License at
- * http://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.
- *
- *****************************************************************************/
+// Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved
+
+//-----------------------------------------------------------------------------
+//
+// You may not use the identified files except in compliance with the Apache
+// License, Version 2.0 (the "License.")
+//
+// You may obtain a copy of the License at
+// http://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';
 
-var oracledbCLib;
-var oracledbInst;
-var Lob = require('./lob.js').Lob;
-var pool = require('./pool.js');
-var connection = require('./connection.js');
-var nodbUtil = require('./util.js');
-var createPoolPromisified;
-var getConnectionPromisified;
-var poolCache = {};
-var tempUsedPoolAliases = {};
-var defaultPoolAlias = 'default';
+const nodbUtil = require('./util.js');
+const util = require('util');
+
+// This version of node-oracledb works with Node.js 8.16, 10.16 or
+// later.  The test stops hard-to-interpret runtime errors and crashes
+// with older Node.js versions.  Also Node.js 8.16 and 10.16 (and
+// 12.0) contain an important N-API performance regression fix.  If
+// you're using the obsolete Node.js 9 or 11 versions, you're on your
+// own regarding performance and functionality
+let vs = process.version.substring(1).split(".").map(Number);
+if (vs[0] < 8 || (vs[0] === 8 && vs[1] < 16)) {
+  throw new Error(nodbUtil.getErrorMessage('NJS-069', nodbUtil.PACKAGE_JSON_VERSION, "8.16"));
+} else if ((vs[0] === 10 && vs[1] < 16)) {
+  throw new Error(nodbUtil.getErrorMessage('NJS-069', nodbUtil.PACKAGE_JSON_VERSION, "10.16"));
+}
+
+const AqDeqOptions = require('./aqDeqOptions.js');
+const AqEnqOptions = require('./aqEnqOptions.js');
+const AqMessage = require('./aqMessage.js');
+const AqQueue = require('./aqQueue.js');
+const BaseDbObject = require('./dbObject.js');
+const Connection = require('./connection.js');
+const Lob = require('./lob.js');
+const Pool = require('./pool.js');
+const ResultSet = require('./resultset.js');
+const SodaDatabase = require('./sodaDatabase.js');
+const SodaCollection = require('./sodaCollection.js');
+const SodaDocCursor = require('./sodaDocCursor.js');
+const SodaDocument = require('./sodaDocument.js');
+const SodaOperation = require('./sodaOperation.js');
+
+let poolCache = {};
+let tempUsedPoolAliases = {};
+const defaultPoolAlias = 'default';
 
 //  Load the Oracledb binary
 
-var binaryLocations = [
+const binaryLocations = [
   '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,  // pre-built binary
   '../' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node',       // binary built from source
-  '../build/Debug/oracledb.node'                              // debug binary
+  '../build/Debug/oracledb.node',                             // debug binary
+  // Ease Webpack use, see https://github.com/oracle/node-oracledb/issues/1156
+  './node_modules/oracledb/' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,
+  './node_modules/oracledb/' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node'
 ];
 
-for (var i = 0; i < binaryLocations.length; i++) {
+let oracledbCLib;
+for (let i = 0; i < binaryLocations.length; i++) {
   try {
     oracledbCLib = require(binaryLocations[i]);
     break;
   } catch(err) {
     if (err.code !== 'MODULE_NOT_FOUND' || i == binaryLocations.length - 1) {
-      var nodeInfo;
+      let nodeInfo;
       if (err.code === 'MODULE_NOT_FOUND') {
-        // none of the three binaries could be found
+        // a binary was not found in any of the search directories
         nodeInfo = `\n  Looked for ${binaryLocations.map(x => require('path').resolve(__dirname, x)).join(', ')}\n  ${nodbUtil.getInstallURL()}\n`;
       } else {
         nodeInfo = `\n  Node.js require('oracledb') error was:\n  ${err.message}\n  ${nodbUtil.getInstallHelp()}\n`;
@@ -57,30 +84,67 @@ for (var i = 0; i < binaryLocations.length; i++) {
   }
 }
 
+
+class OracleDb {
+
+  constructor() {
+    this.queueTimeout = 60000;
+    this.Promise = global.Promise;
+  }
+
+  // extend class with promisified functions
+  _extend(oracleDbInst) {
+    this.getConnection = nodbUtil.promisify(oracleDbInst, getConnection);
+    this.createPool = nodbUtil.promisify(oracleDbInst, createPool);
+  }
+
+  // temporary method for determining if an object is a date until
+  // napi_is_date() can be used (when N-API v5 can be used)
+  _isDate(val) {
+    return util.isDate(val);
+  }
+
+  // retrieves a pool from the pool cache (synchronous method)
+  getPool(poolAlias) {
+    let pool;
+
+    nodbUtil.checkArgCount(arguments, 0, 1);
+
+    if (poolAlias) {
+      nodbUtil.assert(typeof poolAlias === 'string' || typeof poolAlias === 'number', 'NJS-005', 1);
+    }
+
+    poolAlias = poolAlias || defaultPoolAlias;
+
+    pool = poolCache[poolAlias];
+
+    if (!pool) {
+      throw new Error(nodbUtil.getErrorMessage('NJS-047', poolAlias));
+    }
+
+    return pool;
+  }
+
+}
+
 // Oracledb functions and classes
 
-oracledbCLib.Oracledb.prototype.newLob = function(iLob) {
-  return new Lob(iLob, null, oracledbInst);
-};
+// oracledbCLib.OracleDb.prototype.newLob = function(iLob) {
+//   return new Lob(iLob, null, oracledbInst);
+// };
 
 // This createPool function is used the override the createPool method of the
 // Oracledb class, which is defined in the C layer. The override allows us to do
 // things like extend out the pool instance prior to passing it to the caller.
 function createPool(poolAttrs, createPoolCb) {
-  var self = this;
-  var sessionCallback;
-  var poolAlias;
+  const self = this;
+  let sessionCallback;
+  let poolAlias;
 
   // Initial argument count and type checks are done first and throw in the same
   // call stack.
-  nodbUtil.assert(arguments.length === 2, 'NJS-009');
-  nodbUtil.assert(nodbUtil.isObject(poolAttrs), 'NJS-006', 1);
-  nodbUtil.assert(typeof createPoolCb === 'function', 'NJS-006', 2);
-
-  // Allow user to use connectionString as an alias for connectString.
-  if (poolAttrs.connectString === undefined) {
-    poolAttrs.connectString = poolAttrs.connectionString;
-  }
+  nodbUtil.checkAsyncArgs(arguments, 2, 2);
+  nodbUtil.assert(nodbUtil.isObject(poolAttrs), 'NJS-005', 1);
 
   // Additional validations should pass errors via the callback. Need to ensure
   // that errors are raised prior to actually creating the pool via _createPool.
@@ -110,9 +174,22 @@ function createPool(poolAttrs, createPoolCb) {
   // be called by the database when a connection acquired from the pool doesn't
   // have the requested tag
   sessionCallback = poolAttrs.sessionCallback;
+
+  // create an adjusted set of pool attributes to pass to the C layer; the
+  // session callback must be removed if it is a JavaScript function and the
+  // queue timeout is used to specify the maximum amount of time that the C
+  // layer will wait for a connection to be returned; ordinarily since the
+  // JavaScript layer never calls the C layer to get a connection unless one is
+  // known to be available, this should not be needed, but in some cases (such
+  // as when the maximum for a particular shard is specified) this may not be
+  // known, so this prevents an unnecessarily long wait from taking place
+  const adjustedPoolAttrs = Object.defineProperties({},
+    Object.getOwnPropertyDescriptors(poolAttrs));
   if (typeof poolAttrs.sessionCallback === 'function') {
-    poolAttrs = Object.assign({}, poolAttrs);
-    delete poolAttrs.sessionCallback;
+    delete adjustedPoolAttrs.sessionCallback;
+  }
+  if (adjustedPoolAttrs.queueTimeout === undefined) {
+    adjustedPoolAttrs.queueTimeout = self.queueTimeout;
   }
 
   // Need to prevent another call in the same stack from succeeding, otherwise
@@ -122,7 +199,7 @@ function createPool(poolAttrs, createPoolCb) {
     tempUsedPoolAliases[poolAlias] = true;
   }
 
-  self._createPool(poolAttrs, function(err, poolInst) {
+  self._createPool(adjustedPoolAttrs, function(err, poolInst) {
     if (err) {
       // We need to free this up since the creation of the pool failed.
       if (poolAlias) {
@@ -144,11 +221,10 @@ function createPool(poolAttrs, createPoolCb) {
       delete tempUsedPoolAliases[poolAlias];
     }
 
-    poolAttrs.sessionCallback = sessionCallback;
-    pool.extend(poolInst, poolAttrs, poolAlias, self);
+    poolInst._setup(poolAttrs, poolAlias, self);
 
     poolInst.on('_after_close', function() {
-      var pool = this;
+      const pool = this;
 
       if (pool.poolAlias) {
         delete poolCache[pool.poolAlias];
@@ -159,55 +235,27 @@ function createPool(poolAttrs, createPoolCb) {
   });
 }
 
-createPoolPromisified = nodbUtil.promisify(createPool);
-
-// The getPool function is a synchronous method used to retrieve pools from the
-// pool cache.
-function getPool(poolAlias) {
-  var pool;
-
-  nodbUtil.assert(arguments.length < 2, 'NJS-009');
-
-  if (poolAlias) {
-    nodbUtil.assert(typeof poolAlias === 'string' || typeof poolAlias === 'number', 'NJS-006', 1);
-  }
-
-  poolAlias = poolAlias || defaultPoolAlias;
-
-  pool = poolCache[poolAlias];
-
-  if (!pool) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-047', poolAlias));
-  }
-
-  return pool;
-}
-
 // This getConnection function is used the override the getConnection method of the
 // Oracledb class, which is defined in the C layer. The override allows us to do
 // things like extend out the connection instance prior to passing it to the caller.
 function getConnection(a1, a2) {
-  var self = this;
-  var pool;
-  var poolAlias;
-  var connAttrs = {};
-  var getConnectionCb;
+  const self = this;
+  let pool;
+  let poolAlias;
+  let connAttrs = {};
+  let getConnectionCb;
 
-  nodbUtil.assert(arguments.length < 3, 'NJS-009');
+  nodbUtil.checkAsyncArgs(arguments, 1, 2);
 
   // Verify the number and types of arguments, then initialize the local poolAlias,
   // connAttrs, and getConnectionCb variables based on the arguments.
   switch (arguments.length) {
     case 1:
-      nodbUtil.assert(typeof a1 === 'function', 'NJS-006', 1);
-
       poolAlias = defaultPoolAlias;
       getConnectionCb = a1;
-
       break;
     case 2:
-      nodbUtil.assert(typeof a1 === 'string' || nodbUtil.isObject(a1), 'NJS-006', 1);
-      nodbUtil.assert(typeof a2 === 'function', 'NJS-006', 2);
+      nodbUtil.assert(typeof a1 === 'string' || nodbUtil.isObject(a1), 'NJS-005', 1);
 
       if (typeof a1 === 'string') {
         poolAlias = a1;
@@ -236,11 +284,6 @@ function getConnection(a1, a2) {
 
     pool.getConnection(connAttrs, getConnectionCb);
   } else {
-    // Allow user to use connectionString as an alias for connectString.
-    if (connAttrs.connectString === undefined) {
-      connAttrs.connectString = connAttrs.connectionString;
-    }
-
     self._getConnection(connAttrs, function(err, connInst) {
       if (err) {
         if (err.message.match(/DPI-1047/)) {
@@ -250,397 +293,33 @@ function getConnection(a1, a2) {
         return;
       }
 
-      connection.extend(connInst, self);
-
       getConnectionCb(null, connInst);
     });
   }
 }
 
-getConnectionPromisified = nodbUtil.promisify(getConnection);
-
-// The extend method is used to extend the Oracledb instance from the C layer with
-// custom properties and method overrides. References to the original methods are
-// maintained so they can be invoked by the overriding method at the right time.
-function extend(oracledb) {
-  // Using Object.defineProperties to add properties to the Oracledb instance with
-  // special properties, such as enumerable but not writable. A number of constants
-  // (uppercase names) are added for use in various method calls.
-  Object.defineProperties(
-    oracledb,
-    {
-      _oracledb: { // Known to be used in util.js' promisify function.
-        value: oracledb
-      },
-      DEFAULT: {
-        value: 0,
-        enumerable: true
-      },
-      CQN_OPCODE_ALL_OPS: {
-        value: 0,
-        enumerable: true
-      },
-      CQN_OPCODE_ALL_ROWS: {
-        value: 1,
-        enumerable: true
-      },
-      CQN_OPCODE_ALTER: {
-        value: 16,
-        enumerable: true
-      },
-      CQN_OPCODE_DELETE: {
-        value: 8,
-        enumerable: true
-      },
-      CQN_OPCODE_DROP: {
-        value: 32,
-        enumerable: true
-      },
-      CQN_OPCODE_INSERT: {
-        value: 2,
-        enumerable: true
-      },
-      CQN_OPCODE_UPDATE: {
-        value: 4,
-        enumerable: true
-      },
-      DB_TYPE_VARCHAR: {
-        value: 1,
-        enumerable: true
-      },
-      DB_TYPE_NUMBER: {
-        value: 2,
-        enumerable: true
-      },
-      DB_TYPE_LONG: {
-        value: 8,
-        enumerable: true
-      },
-      DB_TYPE_DATE: {
-        value: 12,
-        enumerable: true
-      },
-      DB_TYPE_RAW: {
-        value: 23,
-        enumerable: true
-      },
-      DB_TYPE_LONG_RAW: {
-        value: 24,
-        enumerable: true
-      },
-      DB_TYPE_CHAR: {
-        value: 96,
-        enumerable: true
-      },
-      DB_TYPE_BINARY_FLOAT: {
-        value: 100,
-        enumerable: true
-      },
-      DB_TYPE_BINARY_DOUBLE: {
-        value: 101,
-        enumerable: true
-      },
-      DB_TYPE_ROWID: {
-        value: 104,
-        enumerable: true
-      },
-      DB_TYPE_CLOB: {
-        value: 112,
-        enumerable: true
-      },
-      DB_TYPE_BLOB: {
-        value: 113,
-        enumerable: true
-      },
-      DB_TYPE_TIMESTAMP: {
-        value: 187,
-        enumerable: true
-      },
-      DB_TYPE_TIMESTAMP_TZ: {
-        value: 188,
-        enumerable: true
-      },
-      DB_TYPE_TIMESTAMP_LTZ: {
-        value: 232,
-        enumerable: true
-      },
-      DB_TYPE_NVARCHAR: {
-        value : 1001,
-        enumerable : true
-      },
-      DB_TYPE_NCHAR: {
-        value : 1096,
-        enumerable : true
-      },
-      DB_TYPE_NCLOB: {
-        value : 1112,
-        enumerable : true
-      },
-      STMT_TYPE_UNKNOWN: {
-        value : 0,
-        enumerable : true
-      },
-      STMT_TYPE_SELECT: {
-        value : 1,
-        enumerable : true
-      },
-      STMT_TYPE_UPDATE: {
-        value : 2,
-        enumerable : true
-      },
-      STMT_TYPE_DELETE: {
-        value : 3,
-        enumerable : true
-      },
-      STMT_TYPE_INSERT: {
-        value : 4,
-        enumerable : true
-      },
-      STMT_TYPE_CREATE: {
-        value : 5,
-        enumerable : true
-      },
-      STMT_TYPE_DROP: {
-        value : 6,
-        enumerable : true
-      },
-      STMT_TYPE_ALTER: {
-        value : 7,
-        enumerable : true
-      },
-      STMT_TYPE_BEGIN: {
-        value : 8,
-        enumerable : true
-      },
-      STMT_TYPE_DECLARE: {
-        value : 9,
-        enumerable : true
-      },
-      STMT_TYPE_CALL: {
-        value : 10,
-        enumerable : true
-      },
-      STMT_TYPE_EXPLAIN_PLAN: {
-        value : 15,
-        enumerable : true
-      },
-      STMT_TYPE_MERGE: {
-        value : 16,
-        enumerable : true
-      },
-      STMT_TYPE_ROLLBACK: {
-        value : 17,
-        enumerable : true
-      },
-      STMT_TYPE_COMMIT: {
-        value : 21,
-        enumerable : true
-      },
-      STRING: {
-        value: 2001,
-        enumerable: true
-      },
-      SUBSCR_EVENT_TYPE_DEREG: {
-        value: 5,
-        enumerable: true
-      },
-      SUBSCR_EVENT_TYPE_OBJ_CHANGE: {
-        value: 6,
-        enumerable: true
-      },
-      SUBSCR_EVENT_TYPE_QUERY_CHANGE: {
-        value: 7,
-        enumerable: true
-      },
-      SUBSCR_EVENT_TYPE_AQ: {
-        value: 100,
-        enumerable: true
-      },
-      SUBSCR_GROUPING_CLASS_TIME: {
-        value: 1,
-        enumerable: true
-      },
-      SUBSCR_GROUPING_TYPE_SUMMARY: {
-        value: 1,
-        enumerable: true
-      },
-      SUBSCR_GROUPING_TYPE_LAST: {
-        value: 2,
-        enumerable: true
-      },
-      SUBSCR_NAMESPACE_AQ: {
-        value: 1,
-        enumerable: true
-      },
-      SUBSCR_NAMESPACE_DBCHANGE: {
-        value: 2,
-        enumerable: true
-      },
-      SUBSCR_QOS_BEST_EFFORT: {
-        value: 16,
-        enumerable: true
-      },
-      SUBSCR_QOS_DEREG_NFY: {
-        value: 2,
-        enumerable: true
-      },
-      SUBSCR_QOS_QUERY: {
-        value: 8,
-        enumerable: true
-      },
-      SUBSCR_QOS_RELIABLE: {
-        value: 1,
-        enumerable: true
-      },
-      SUBSCR_QOS_ROWIDS: {
-        value: 4,
-        enumerable: true
-      },
-      NUMBER: {
-        value: 2002,
-        enumerable: true
-      },
-      DATE: {
-        value: 2003,
-        enumerable: true
-      },
-      CURSOR: {
-        value: 2004,
-        enumerable: true
-      },
-      BUFFER: {
-        value: 2005,
-        enumerable: true
-      },
-      CLOB: {
-        value: 2006,
-        enumerable: true
-      },
-      BLOB: {
-        value: 2007,
-        enumerable: true
-      },
-      SYSDBA: {
-        value: 2,
-        enumerable: true
-      },
-      SYSOPER: {
-        value: 4,
-        enumerable: true
-      },
-      SYSASM: {
-        value: 32768,
-        enumerable: true
-      },
-      SYSBACKUP: {
-        value: 131072,
-        enumerable: true
-      },
-      SYSDG: {
-        value: 262144,
-        enumerable: true
-      },
-      SYSKM: {
-        value: 524288,
-        enumerable: true
-      },
-      SYSRAC: {
-        value: 1048576,
-        enumerable: true
-      },
-      BIND_IN: {
-        value: 3001,
-        enumerable: true
-      },
-      BIND_INOUT: {
-        value: 3002,
-        enumerable: true
-      },
-      BIND_OUT: {
-        value: 3003,
-        enumerable: true
-      },
-      ARRAY: {
-        value: 4001,
-        enumerable: true
-      },
-      OBJECT: {
-        value: 4002,
-        enumerable: true
-      },
-      SODA_COLL_MAP_MODE: {
-        value: 5001,
-        enumerable : true
-      },
-      POOL_STATUS_OPEN: {
-        value: 6000,
-        enumerable: true
-      },
-      POOL_STATUS_DRAINING: {
-        value: 6001,
-        enumerable: true
-      },
-      POOL_STATUS_CLOSED: {
-        value: 6002,
-        enumerable: true
-      },
-      Promise: {
-        value: global.Promise,
-        enumerable: true,
-        writable: true
-      },
-      Oracledb: {
-        value: oracledbCLib.Oracledb,
-        enumerable: true
-      },
-      Connection: {
-        value: oracledbCLib.Connection,
-        enumerable: true
-      },
-      Lob: {
-        value: Lob,
-        enumerable: true
-      },
-      Pool: {
-        value: oracledbCLib.Pool,
-        enumerable: true
-      },
-      ResultSet: {
-        value: oracledbCLib.ResultSet,
-        enumerable: true
-      },
-      queueTimeout: {
-        value: 60000,
-        enumerable: true,
-        writable: true
-      },
-      _createPool: {
-        value: oracledb.createPool
-      },
-      createPool: {
-        value: createPoolPromisified,
-        enumerable: true,
-        writable: true
-      },
-      getPool: {
-        value: getPool,
-        enumerable: true,
-        writable: true
-      },
-      _getConnection: {
-        value: oracledb.getConnection
-      },
-      getConnection: {
-        value: getConnectionPromisified,
-        enumerable: true,
-        writable: true
-      }
-    }
-  );
-}
-
-oracledbInst = new oracledbCLib.Oracledb();
-
-extend(oracledbInst);
-
-module.exports = oracledbInst;
+// create instance which will be exported
+let oracleDbInst = new OracleDb();
+
+// add classes to prototype
+let proto = Object.getPrototypeOf(oracleDbInst);
+proto.OracleDb = OracleDb;
+proto.AqDeqOptions = AqDeqOptions;
+proto.AqEnqOptions = AqEnqOptions;
+proto.AqMessage = AqMessage;
+proto.AqQueue = AqQueue;
+proto.BaseDbObject = BaseDbObject;
+proto.Connection = Connection;
+proto.Lob = Lob;
+proto.Pool = Pool;
+proto.ResultSet = ResultSet;
+proto.SodaDatabase = SodaDatabase;
+proto.SodaCollection = SodaCollection;
+proto.SodaDocCursor = SodaDocCursor;
+proto.SodaDocument = SodaDocument;
+proto.SodaOperation = SodaOperation;
+
+// call C to extend classes
+oracledbCLib.init(oracleDbInst);
+
+module.exports = oracleDbInst;