oracledb 3.1.2 → 4.2.0

package/lib/sodaOperation.js

@@ -1,330 +1,174 @@
-/* Copyright (c) 2018, 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) 2018, 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.
+//
+//-----------------------------------------------------------------------------
 
 'use strict';
 
 const nodbUtil = require('./util.js');
-const sodaDocument = require('./sodaDocument.js');
-const sodaDocCursor = require('./sodaDocCursor.js');
-
-var countPromisified;
-var getOnePromisified;
-var replaceOnePromisified;
-var replaceOneAndGetPromisified;
-var removePromisified;
-var getCursorPromisified;
-var getDocumentsPromisified;
-
 
 // to obtain count of documents from find() result
 // This is a terminal function (no further chaining possible)
 function count(cb) {
-  var self = this;
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 1);
+  nodbUtil.checkAsyncArgs(arguments, 1, 1);
 
-  self._count(this._options, cb);
+  this._count(this._options, cb);
 }
 
-countPromisified = nodbUtil.promisify(count);
 
 // To obtain first document object from find() result
 // This is a terminal function (no further chaining possible)
 function getOne(cb) {
-  var self = this;
-
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 1);
+  nodbUtil.checkAsyncArgs(arguments, 1, 1);
 
-  self._getOne(this._options, function(err, doc) {
-    if (doc) {
-      sodaDocument.extend(doc);
-    }
-    cb(err, doc);
-  });
+  this._getOne(this._options, cb);
 }
 
-getOnePromisified = nodbUtil.promisify(getOne);
-
 
 // To replace one document by a given document based from find() result
 // This is a terminal function (no further chaining possible)
 function replaceOne(content, cb) {
-  var self = this;
-
-  nodbUtil.assert(arguments.length === 2, 'NJS-009');
+  nodbUtil.checkAsyncArgs(arguments, 2, 2);
   nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-006', 1);
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 2);
+      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
 
   if (!nodbUtil.isSodaDocument(content)) {
     content = Buffer.from(JSON.stringify(content));
   }
 
-  self._replaceOne(this._options, content, cb);
+  this._replaceOne(this._options, content, cb);
 }
 
-replaceOnePromisified = nodbUtil.promisify(replaceOne);
-
 
 // To replace one document by a given document based from find() result
 // This is a terminal function (no further chaining possible)
 function replaceOneAndGet(content, cb) {
-  var self = this;
-
-  nodbUtil.assert(arguments.length === 2, 'NJS-009');
+  nodbUtil.checkAsyncArgs(arguments, 2, 2);
   nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-006', 1);
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 2);
+      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
 
   if (!nodbUtil.isSodaDocument(content)) {
     content = Buffer.from(JSON.stringify(content));
   }
 
-  self._replaceOneAndGet(this._options, content, function(err, doc) {
-    if (doc) {
-      sodaDocument.extend(doc);
-    }
-    cb(err, doc);
-  });
+  this._replaceOneAndGet(this._options, content, cb);
 }
 
-replaceOneAndGetPromisified = nodbUtil.promisify(replaceOneAndGet);
-
 
 // To remove documents obtained from find() result
 // This is a terminal function (no further chaining possible)
 function remove(cb) {
-  var self = this;
-
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 1);
+  nodbUtil.checkAsyncArgs(arguments, 1, 1);
 
-  self._remove(this._options, cb);
+  this._remove(this._options, cb);
 }
 
-removePromisified = nodbUtil.promisify(remove);
-
 
 // To obtain document-cursor object from find() result
 // This is a terminal function (no further chaining possible)
 function getCursor(cb) {
-  var self = this;
+  nodbUtil.checkAsyncArgs(arguments, 1, 1);
 
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 1);
-
-  self._getCursor(this._options, function(err, cursor) {
-    if (cursor) {
-      sodaDocCursor.extend(cursor, self._oracledb);
-    }
-    cb(err, cursor);
-  });
+  this._getCursor(this._options, cb);
 }
 
-getCursorPromisified = nodbUtil.promisify(getCursor);
-
 
 // to obtain documents from find() result
 // This is a terminal function (no further chaining possible)
 function getDocuments(cb) {
-  var self = this;
-
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof cb === 'function', 'NJS-006', 1);
+  nodbUtil.checkAsyncArgs(arguments, 1, 1);
 
-  self._getDocuments(this._options, function(err, docs) {
-    if (err) {
-      cb(err, null);
-      return;
-    }
-    for (let i = 0; i < docs.length; i++) {
-      sodaDocument.extend(docs[i]);
-    }
-    cb(null, docs);
-  });
+  this._getDocuments(this._options, cb);
 }
 
-getDocumentsPromisified = nodbUtil.promisify(getDocuments);
 
 
-// limit property - a non-terminal function and can chain further
-function _limit (n) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof n === 'number', 'NJS-006', 1);
-  this._options.limit = n;
-  return this;
-}
+class SodaOperation {
 
+  constructor() {
+    this._options = {};
+  }
 
-// skip property - a non-terminal function and can chain further
-function _skip(n) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof n === 'number', 'NJS-006', 1);
-  this._options.skip = n;
-  return this;
-}
+  _extend(oracledb) {
+    this.count = nodbUtil.promisify(oracledb, count);
+    this.getCursor = nodbUtil.promisify(oracledb, getCursor);
+    this.getDocuments = nodbUtil.promisify(oracledb, getDocuments);
+    this.getOne = nodbUtil.promisify(oracledb, getOne);
+    this.remove = nodbUtil.promisify(oracledb, remove);
+    this.replaceOne = nodbUtil.promisify(oracledb, replaceOne);
+    this.replaceOneAndGet = nodbUtil.promisify(oracledb, replaceOneAndGet);
+  }
 
-// version property - a non-terminal function and can chain further
-function _version(v) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof v === 'string', 'NJS-006', 1);
-  this._options.version = v;
-  return this;
-}
+  // filter property - a non-terminal function and can chain further
+  filter(f) {
+    nodbUtil.checkArgCount (arguments, 1, 1);
+    nodbUtil.assert(nodbUtil.isObject(f), 'NJS-005', 1);
+    this._options.filter = JSON.stringify(f);
+    return this;
+  }
 
-// filter property - a non-terminal function and can chain further
-function _filter(f) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(nodbUtil.isObject(f), 'NJS-006', 1);
-  this._options.filter = JSON.stringify(f);
-  return this;
-}
+  // key - a non-terminal function and can chain further
+  key(k) {
+    nodbUtil.checkArgCount(arguments, 1, 1);
+    nodbUtil.assert(typeof k === 'string', 'NJS-005', 1);
+    this._options.key = k;
+    this._options.keys = undefined;
+    return this;
+  }
 
-// key - a non-terminal function and can chain further
-function _key(k) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(typeof k === 'string', 'NJS-006', 1);
-  this._options.key = k;
-  this._options.keys = undefined;
-  return this;
-}
+  // keys - a non-terminal function and can chain further
+  keys(arr) {
+    nodbUtil.checkArgCount(arguments, 1, 1);
+    nodbUtil.assert(Array.isArray(arr), 'NJS-005', 1);
 
-// keys - a non-terminal function and can chain further
-function _keys(arr) {
-  nodbUtil.assert(arguments.length === 1, 'NJS-009');
-  nodbUtil.assert(Array.isArray(arr), 'NJS-006', 1);
+    for (let i = 0; i < arr.length; i++) {
+      nodbUtil.assert(typeof arr[i] === 'string', 'NJS-005', 1);
+    }
 
-  for (let i = 0; i < arr.length; i++) {
-    nodbUtil.assert(typeof arr[i] === 'string', 'NJS-006', 1);
+    this._options.keys = arr;
+    this._options.key = undefined;
+    return this;
   }
 
-  this._options.keys = arr;
-  this._options.key = undefined;
-  return this;
-}
+  // limit property - a non-terminal function and can chain further
+  limit (n) {
+    nodbUtil.checkArgCount(arguments, 1, 1);
+    nodbUtil.assert(typeof n === 'number', 'NJS-005', 1);
+    this._options.limit = n;
+    return this;
+  }
+
+  // skip property - a non-terminal function and can chain further
+  skip(n) {
+    nodbUtil.checkArgCount(arguments, 1, 1);
+    nodbUtil.assert(typeof n === 'number', 'NJS-005', 1);
+    this._options.skip = n;
+    return this;
+  }
 
+  // version property - a non-terminal function and can chain further
+  version(v) {
+    nodbUtil.checkArgCount(arguments, 1, 1);
+    nodbUtil.assert(typeof v === 'string', 'NJS-005', 1);
+    this._options.version = v;
+    return this;
+  }
 
-// The extend method is used to extend the sodaOperation istance from 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(sodaOp, oracledb) {
-  // Using Object.defineProperties to add properties to the soda instance with
-  // special properties
-  Object.defineProperties (
-    sodaOp,
-    {
-      _oracledb: {
-        value: oracledb
-      },
-      limit: {
-        value: _limit,
-        enumerable: true,
-        writable: true
-      },
-      skip: {
-        value: _skip,
-        enumerable: true,
-        writable: true
-      },
-      version: {
-        value: _version,
-        enumerable: true,
-        writable: true
-      },
-      filter: {
-        value: _filter,
-        enumerable: true,
-        writable: true
-      },
-      key: {
-        value: _key,
-        enumerable: true,
-        writable: true
-      },
-      keys: {
-        value: _keys,
-        enumerable: true,
-        writable: true
-      },
-      _options: {
-        value: {}
-      },
-      _count: {
-        value: sodaOp.count
-      },
-      count: {
-        value: countPromisified,
-        enumerable: true,
-        writable: true
-      },
-      _getOne: {
-        value: sodaOp.getOne
-      },
-      getOne: {
-        value: getOnePromisified,
-        enumerable: true,
-        writable: true
-      },
-      _replaceOne: {
-        value: sodaOp.replaceOne
-      },
-      replaceOne: {
-        value: replaceOnePromisified,
-        enumerable: true,
-        writable: true
-      },
-      _replaceOneAndGet: {
-        value: sodaOp.replaceOneAndGet
-      },
-      replaceOneAndGet: {
-        value:  replaceOneAndGetPromisified,
-        enumerable: true,
-        writable: true
-      },
-      _remove: {
-        value:  sodaOp.remove
-      },
-      remove: {
-        value: removePromisified,
-        enumerable: true,
-        writable: true
-      },
-      _getCursor: {
-        value: sodaOp.getCursor
-      },
-      getCursor: {
-        value: getCursorPromisified,
-        enumerable: true,
-        writable: true
-      },
-      _getDocuments: {
-        value: sodaOp.getDocuments
-      },
-      getDocuments: {
-        value: getDocumentsPromisified,
-        enumerable: true,
-        writable: true
-      }
-    }
-  );
 }
 
-module.exports.extend = extend;
+
+module.exports = SodaOperation;

package/lib/util.js

@@ -1,64 +1,66 @@
-/* Copyright (c) 2016, 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) 2016, 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.
+//
+//-----------------------------------------------------------------------------
 
 'use strict';
 
-var util = require('util');
+const util = require('util');
+
+// node-oracledb version number
+let packageJSON;
+try {
+  packageJSON = require('../package.json');
+} catch(err) {
+  throw new Error('package.json is missing');
+}
+const PACKAGE_JSON_VERSION = packageJSON.version;
+module.exports.PACKAGE_JSON_VERSION = PACKAGE_JSON_VERSION;
 
 // Directory containing the node-oracledb add-on binary
 const RELEASE_DIR = 'build/Release';
 module.exports.RELEASE_DIR = RELEASE_DIR;
 
 // The default node-oracledb add-on binary filename for this Node.js
-const BINARY_FILE = 'oracledb-abi' + process.versions.modules + '-' + process.platform + '-' + process.arch + '.node';
+const BINARY_FILE = 'oracledb-' + PACKAGE_JSON_VERSION + '-' + process.platform + '-' + process.arch + '.node';
 module.exports.BINARY_FILE = BINARY_FILE;
 
 // Staging directory used by maintainers building the npm package
 const STAGING_DIR = 'package/Staging';
 module.exports.STAGING_DIR = STAGING_DIR;
 
-var EventEmitter = require('events').EventEmitter;
-var eventEmitterKeys = Object.keys(EventEmitter.prototype);
-var eventEmitterFuncKeys = eventEmitterKeys.filter(function(key) {
-  return typeof EventEmitter.prototype[key] === 'function';
-});
-
 // errorMessages is for NJS error messages used in the JavaScript layer
-var errorMessages = {
+const errorMessages = {
   'NJS-002': 'NJS-002: invalid pool',
   'NJS-004': 'NJS-004: invalid value for property %s',
   'NJS-005': 'NJS-005: invalid value for parameter %d',
-  'NJS-006': 'NJS-006: invalid type for parameter %d',
   'NJS-009': 'NJS-009: invalid number of parameters',
-  'NJS-014': 'NJS-014: %s is a read-only property',
   'NJS-037': 'NJS-037: incompatible type of value provided',
-  'NJS-040': 'NJS-040: connection request timeout',
+  'NJS-040': 'NJS-040: connection request timeout. Request exceeded queueTimeout of %d',
   'NJS-041': 'NJS-041: cannot convert ResultSet to QueryStream after invoking methods',
   'NJS-042': 'NJS-042: cannot invoke ResultSet methods after converting to QueryStream',
   'NJS-043': 'NJS-043: ResultSet already converted to QueryStream',
   'NJS-045': 'NJS-045: cannot load a node-oracledb binary for Node.js ' + process.versions.node + ' (' + process.platform + ' ' + process.arch + ') %s',
   'NJS-046': 'NJS-046: poolAlias "%s" already exists in the connection pool cache',
   'NJS-047': 'NJS-047: poolAlias "%s" not found in the connection pool cache',
-  'NJS-054': 'NJS-054: binary build/Release/oracledb.node was not installed',
   'NJS-064': 'NJS-064: connection pool is closing',
   'NJS-065': 'NJS-065: connection pool was closed',
-  'NJS-067': 'NJS-067: a pre-built node-oracledb binary was not found for Node.js %s'
+  'NJS-067': 'NJS-067: a pre-built node-oracledb binary was not found for %s',
+  'NJS-069': 'NJS-069: node-oracledb %s requires Node.js %s or later',
 };
 
 // getInstallURL returns a string with installation URL
@@ -70,8 +72,8 @@ module.exports.getInstallURL = getInstallURL;
 
 // getInstallHelp returns a string with installation usage tips that may be helpful
 function getInstallHelp() {
-  var arch, url;
-  var mesg = getInstallURL() + '\n';
+  let arch, url;
+  let mesg = getInstallURL() + '\n';
   if (process.platform === 'linux') {
     if (process.arch === 'x64') {
       url = 'http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html\n';
@@ -125,35 +127,20 @@ function getInstallHelp() {
 
 module.exports.getInstallHelp = getInstallHelp;
 
-// makeEventEmitter is used to make class instances inherit from the EventEmitter
-// class. This is needed because we extend instances from the C layer and thus
-// don't have JavaScript constructor functions we can use for more traditional
-// inheritance.
-function makeEventEmitter(instance){
-  eventEmitterFuncKeys.forEach(function(key) {
-    instance[key] = EventEmitter.prototype[key];
-  });
-
-  EventEmitter.call(instance);
-}
-
-module.exports.makeEventEmitter = makeEventEmitter;
-
-// getErrorMessage is used to get and format error messages to make throwing errors
-// a little more convenient.
-function getErrorMessage(errorCode, messageArg1) {
-  if (messageArg1) {
-    return util.format(errorMessages[errorCode], messageArg1);
-  } else {
-    return util.format(errorMessages[errorCode]);
-  }
+// getErrorMessage is used to get and format error messages to make throwing
+// errors a little more convenient.
+function getErrorMessage(errorCode) {
+  let args = Array.prototype.slice.call(arguments);
+  args[0] = errorMessages[errorCode];
+  return util.format.apply(util, args);
 }
 
 module.exports.getErrorMessage = getErrorMessage;
 
-// assert it typically used in the beginning of public functions to assert preconditions
-// for the function to execute. Most commonly it's used to validate arguments lenght
-// and types and throw an error if they don't match what is expected.
+// assert is typically used at the beginning of public functions to assert
+// preconditions for the function to execute. Most commonly it is used to
+// validate the number of arguments and their types and throw an error if they
+// don't match what is expected.
 function assert(condition, errorCode, messageArg1) {
   if (!condition) {
     throw new Error(getErrorMessage(errorCode, messageArg1));
@@ -162,26 +149,46 @@ function assert(condition, errorCode, messageArg1) {
 
 module.exports.assert = assert;
 
+// checkArgCount is used to validate the number of arguments, particularly with
+// optional parameters (range of number of parameters).  If the number of
+// arguments is not within the given range, an error is thrown.
+function checkArgCount(args, minArgCount, maxArgCount) {
+  if (args.length < minArgCount || args.length > maxArgCount)
+    throw new Error(getErrorMessage('NJS-009'));
+}
+
+module.exports.checkArgCount = checkArgCount;
+
+
+// checkAsyncArgs is used to validate number of arguments and last parameter
+// is of type 'function'.  This is used by all asynchronous functions where
+// the last parameter is expected to be a function.
+function checkAsyncArgs (args, minArgCount, maxArgCount) {
+  checkArgCount(args, minArgCount, maxArgCount);
+  assert(typeof args[args.length - 1] === 'function', 'NJS-005', args.length);
+}
+
+module.exports.checkAsyncArgs = checkAsyncArgs;
+
+
 // The promisify function is used to wrap async methods to add optional promise
 // support. If the last parameter passed to a method is a function, then it is
 // assumed that the callback pattern is being used and the method is invoked as
-// usual. Otherwise a promise is returned and later resolved or rejected based on
-// the return of the method.
-function promisify(func) {
+// usual. Otherwise a promise is returned and later resolved or rejected based
+// on the return of the method.
+function promisify(oracledb, func) {
   return function() {
-    var self = this;
-    var args;
+    const self = this;
+    let args;
 
-    // This/self could refer to the base class instance, pool, connection, etc. All
-    // class instances have a private reference to the base class for convenience.
-    if (!self._oracledb.Promise || typeof arguments[arguments.length - 1] === 'function') {
+    if (!oracledb.Promise || typeof arguments[arguments.length - 1] === 'function') {
       return func.apply(self, arguments);
     } else {
       // Converting to an array so we can extend it later with a custom callback
       args = Array.prototype.slice.call(arguments);
 
-      return new self._oracledb.Promise(function(resolve, reject) {
-        var errorCode;
+      return new oracledb.Promise(function(resolve, reject) {
+        let errorCode;
 
         try {
           args[args.length] = function(err, result) {
@@ -194,11 +201,11 @@ function promisify(func) {
 
           func.apply(self, args);
         } catch (err) {
-          errorCode = err.message.substr(0, 7);
+          errorCode = err.message.substr(0, err.message.indexOf(':'));
 
           // Check for invalid number or type of parameter(s) as they should be
           // eagerly thrown.
-          if (errorCode === 'NJS-009' || errorCode === 'NJS-006') {
+          if (errorCode === 'NJS-009' || errorCode === 'NJS-005') {
             // Throwing the error outside of the promise wrapper so that its not
             // swallowed up as a rejection.
             process.nextTick(function() {