oracledb 5.5.0 → 6.0.0

package/lib/constants.js

@@ -0,0 +1,203 @@
+// Copyright (c) 2022, 2023, 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.
+//
+//-----------------------------------------------------------------------------
+
+// This file contains values for implementation and public constants.
+//
+// All public constants are later exposed to node-oracledb apps via the exports
+// of oracledb.js.
+
+'use strict';
+
+const version = require('./version.js');
+
+const VERSION_STRING =
+  version.VERSION_MAJOR + '.' +
+  version.VERSION_MINOR + '.' +
+  version.VERSION_PATCH +
+  version.VERSION_SUFFIX;
+
+module.exports = {
+
+  // version information
+  VERSION_MAJOR: version.VERSION_MAJOR,
+  VERSION_MINOR: version.VERSION_MINOR,
+  VERSION_PATCH: version.VERSION_PATCH,
+  VERSION_SUFFIX: version.VERSION_SUFFIX,
+  VERSION_STRING: VERSION_STRING,
+
+  // defaults for initOracleClient()
+  DEFAULT_DRIVER_NAME: "node-oracledb : " + VERSION_STRING,
+  DEFAULT_ERROR_URL: "https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html",
+
+  // default for maxSize for OUT and IN/OUT binds
+  DEFAULT_MAX_SIZE_FOR_OUT_BINDS: 200,
+
+  // character set forms (internal use)
+  CSFRM_IMPLICIT: 1,
+  CSFRM_NCHAR: 2,
+
+  // CQN operation codes
+  CQN_OPCODE_ALL_OPS: 0,
+  CQN_OPCODE_ALL_ROWS: 1,
+  CQN_OPCODE_ALTER: 16,
+  CQN_OPCODE_DELETE: 8,
+  CQN_OPCODE_DROP: 32,
+  CQN_OPCODE_INSERT: 2,
+  CQN_OPCODE_UPDATE: 4,
+
+  // fetchInfo type defaulting
+  DEFAULT: 0,
+
+  // statement types
+  STMT_TYPE_UNKNOWN: 0,
+  STMT_TYPE_SELECT: 1,
+  STMT_TYPE_UPDATE: 2,
+  STMT_TYPE_DELETE: 3,
+  STMT_TYPE_INSERT: 4,
+  STMT_TYPE_CREATE: 5,
+  STMT_TYPE_DROP: 6,
+  STMT_TYPE_ALTER: 7,
+  STMT_TYPE_BEGIN: 8,
+  STMT_TYPE_DECLARE: 9,
+  STMT_TYPE_CALL: 10,
+  STMT_TYPE_EXPLAIN_PLAN: 15,
+  STMT_TYPE_MERGE: 16,
+  STMT_TYPE_ROLLBACK: 17,
+  STMT_TYPE_COMMIT: 21,
+
+  // shutdown modes
+  SHUTDOWN_MODE_DEFAULT: 0,
+  SHUTDOWN_MODE_TRANSACTIONAL: 1,
+  SHUTDOWN_MODE_TRANSACTIONAL_LOCAL: 2,
+  SHUTDOWN_MODE_IMMEDIATE: 3,
+  SHUTDOWN_MODE_ABORT: 4,
+  SHUTDOWN_MODE_FINAL: 5,
+
+  // startup modes
+  STARTUP_MODE_DEFAULT: 0,
+  STARTUP_MODE_FORCE: 1,
+  STARTUP_MODE_RESTRICT: 2,
+
+  // subscription event types
+  SUBSCR_EVENT_TYPE_SHUTDOWN: 2,
+  SUBSCR_EVENT_TYPE_SHUTDOWN_ANY: 3,
+  SUBSCR_EVENT_TYPE_STARTUP: 1,
+  SUBSCR_EVENT_TYPE_DEREG: 5,
+  SUBSCR_EVENT_TYPE_OBJ_CHANGE: 6,
+  SUBSCR_EVENT_TYPE_QUERY_CHANGE: 7,
+  SUBSCR_EVENT_TYPE_AQ: 100,
+
+  // subscription grouping classes
+  SUBSCR_GROUPING_CLASS_TIME: 1,
+
+  // subscription grouping types
+  SUBSCR_GROUPING_TYPE_SUMMARY: 1,
+  SUBSCR_GROUPING_TYPE_LAST: 2,
+
+  // subscription namespaces
+  SUBSCR_NAMESPACE_AQ: 1,
+  SUBSCR_NAMESPACE_DBCHANGE: 2,
+
+  // subscription quality of service flags
+  SUBSCR_QOS_BEST_EFFORT: 0x10,
+  SUBSCR_QOS_DEREG_NFY: 0x02,
+  SUBSCR_QOS_QUERY: 0x08,
+  SUBSCR_QOS_RELIABLE: 0x01,
+  SUBSCR_QOS_ROWIDS: 0x04,
+
+  // privileges
+  SYSASM: 0x00008000,
+  SYSBACKUP: 0x00020000,
+  SYSDBA: 0x00000002,
+  SYSDG: 0x00040000,
+  SYSKM: 0x00080000,
+  SYSOPER: 0x00000004,
+  SYSPRELIM: 0x00000008,
+  SYSRAC: 0x00100000,
+
+  // bind directions
+  BIND_IN: 3001,
+  BIND_INOUT: 3002,
+  BIND_OUT: 3003,
+
+  // outFormat values
+  OUT_FORMAT_ARRAY: 4001,
+  OUT_FORMAT_OBJECT: 4002,
+
+  // SODA collection creation modes
+  SODA_COLL_MAP_MODE: 5001,
+
+  // pool statuses
+  POOL_STATUS_OPEN: 6000,
+  POOL_STATUS_DRAINING: 6001,
+  POOL_STATUS_CLOSED: 6002,
+  POOL_STATUS_RECONFIGURING: 6003,
+
+  // purity values
+  PURITY_DEFAULT: 0,
+  PURITY_NEW: 1,
+  PURITY_SELF: 2,
+
+  // AQ dequeue wait options
+  AQ_DEQ_NO_WAIT: 0,
+  AQ_DEQ_WAIT_FOREVER: 4294967295,
+
+  // AQ dequeue modes
+  AQ_DEQ_MODE_BROWSE: 1,
+  AQ_DEQ_MODE_LOCKED: 2,
+  AQ_DEQ_MODE_REMOVE: 3,
+  AQ_DEQ_MODE_REMOVE_NO_DATA: 4,
+
+  // AQ dequeue navigation flags
+  AQ_DEQ_NAV_FIRST_MSG: 1,
+  AQ_DEQ_NAV_NEXT_TRANSACTION: 2,
+  AQ_DEQ_NAV_NEXT_MSG: 3,
+
+  // AQ message delivery modes
+  AQ_MSG_DELIV_MODE_PERSISTENT: 1,
+  AQ_MSG_DELIV_MODE_BUFFERED: 2,
+  AQ_MSG_DELIV_MODE_PERSISTENT_OR_BUFFERED: 3,
+
+  // AQ message states
+  AQ_MSG_STATE_READY: 0,
+  AQ_MSG_STATE_WAITING: 1,
+  AQ_MSG_STATE_PROCESSED: 2,
+  AQ_MSG_STATE_EXPIRED: 3,
+
+  // AQ visibility flags
+  AQ_VISIBILITY_IMMEDIATE: 1,
+  AQ_VISIBILITY_ON_COMMIT: 2,
+
+  // TPC/XA begin flags Constants
+  TPC_BEGIN_JOIN: 0x00000002,
+  TPC_BEGIN_NEW: 0x00000001,
+  TPC_BEGIN_PROMOTE: 0x00000008,
+  TPC_BEGIN_RESUME: 0x00000004,
+
+  // TPC/XA two-phase commit flags
+  TPC_END_NORMAL: 0,
+  TPC_END_SUSPEND: 0x00100000,
+};

package/lib/dbObject.js

@@ -1,17 +1,24 @@
-// Copyright (c) 2019, 2022, Oracle and/or its affiliates.
-//
+// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
+
 //----------------------------------------------------------------------------
 //
-// You may not use the identified files except in compliance with the Apache
-// License, Version 2.0 (the "License.")
+// 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
-// 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.
+//    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.
 //
@@ -19,6 +26,10 @@
 
 'use strict';
 
+const Lob = require('./lob.js');
+const impl = require('./impl');
+const errors = require('./errors.js');
+const types = require('./types.js');
 const util = require('util');
 
 // define base database object class; instances of this class are never
@@ -26,27 +37,42 @@ const util = require('util');
 // instantiated; a cache of these classes are maintained on each connection
 class BaseDbObject {
 
-  // extend class with promisified functions
-  _extend(oracledb) {
-    this._oracledb = oracledb;
+  //---------------------------------------------------------------------------
+  // _getAttrValue()
+  //
+  // Returns the value of the given attribute on the object.
+  //---------------------------------------------------------------------------
+  _getAttrValue(attr) {
+    const value = this._impl.getAttrValue(attr);
+    return this._transformValueOut(value, attr.typeClass);
   }
 
-  // initialize object with value
-  _initialize(initialValue) {
-    if (this.isCollection) {
-      for (let i = 0; i < initialValue.length; i++) {
-        this.append(initialValue[i]);
-      }
-    } else {
-      Object.assign(this, initialValue);
-    }
+  //---------------------------------------------------------------------------
+  // _setAttrValue()
+  //
+  // Sets the value of the attribute on the object to the given value.
+  //---------------------------------------------------------------------------
+  _setAttrValue(attr, value) {
+    const info = {
+      fqn: this._objType.fqn,
+      attrName: attr.name,
+      type: attr.type,
+      typeClass: attr.typeClass
+    };
+    const options = {allowArray: false};
+    value = transformer.transformValueIn(info, value, options);
+    this._impl.setAttrValue(attr, value);
   }
 
-  // return as a plain object
+  //---------------------------------------------------------------------------
+  // _toPojo()
+  //
+  // Returns the database object as a plain Javascript object.
+  //---------------------------------------------------------------------------
   _toPojo() {
     if (this.isCollection) {
       const result = this.getValues();
-      if (this.elementType == this._oracledb.DB_TYPE_OBJECT) {
+      if (this.elementType === types.DB_TYPE_OBJECT) {
         for (let i = 0; i < result.length; i++) {
           result[i] = result[i]._toPojo();
         }
@@ -54,7 +80,7 @@ class BaseDbObject {
       return (result);
     }
     const result = {};
-    for (let name in this.attributes) {
+    for (const name in this.attributes) {
       let value = this[name];
       if (value instanceof BaseDbObject) {
         value = value._toPojo();
@@ -64,6 +90,265 @@ class BaseDbObject {
     return (result);
   }
 
+  //---------------------------------------------------------------------------
+  // _transformValueOut()
+  //
+  // Transforms a value going out to the caller from the implementation.
+  //---------------------------------------------------------------------------
+  _transformValueOut(value, cls) {
+    let outValue = value;
+    if (value instanceof impl.LobImpl) {
+      outValue = new Lob();
+      outValue._setup(value, true);
+    } else if (value instanceof impl.DbObjectImpl) {
+      outValue = Object.create(cls.prototype);
+      outValue._impl = value;
+      if (outValue.isCollection) {
+        outValue = new Proxy(outValue, BaseDbObject._collectionProxyHandler);
+      }
+    }
+    return outValue;
+  }
+
+  //---------------------------------------------------------------------------
+  // append()
+  //
+  // Appends an element to the collection.
+  //---------------------------------------------------------------------------
+  append(value) {
+    errors.assertArgCount(arguments, 1, 1);
+    const info = {
+      fqn: this._objType.fqn,
+      type: this._objType.elementType,
+      typeClass: this._objType.elementTypeClass
+    };
+    const options = {allowArray: false};
+    value = transformer.transformValueIn(info, value, options);
+    this._impl.append(value);
+  }
+
+  //---------------------------------------------------------------------------
+  // attributes
+  //
+  // Property for the attributes stored on the object type.
+  //---------------------------------------------------------------------------
+  get attributes() {
+    if (!this._attributes) {
+      const implAttrs = this._objType.attributes || [];
+      const attrs = {};
+      for (let i = 0; i < implAttrs.length; i++) {
+        const implAttr = implAttrs[i];
+        const attr = {
+          type: implAttr.type,
+          typeName: implAttr.typeName
+        };
+        if (implAttr.typeClass) {
+          attr.typeClass = implAttr.typeClass;
+        }
+        attrs[implAttr.name] = attr;
+      }
+      this._attributes = attrs;
+    }
+    return this._attributes;
+  }
+
+  //---------------------------------------------------------------------------
+  // deleteElement()
+  //
+  // Deletes the element in a collection at the specified index.
+  //---------------------------------------------------------------------------
+  deleteElement(index) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    return this._impl.deleteElement(index);
+  }
+
+  //---------------------------------------------------------------------------
+  // elementType
+  //
+  // Property for the element type, if the database object type is a
+  // collection. It will be one of the DB_TYPE_ constants.
+  //---------------------------------------------------------------------------
+  get elementType() {
+    return this._objType.elementType;
+  }
+
+  //---------------------------------------------------------------------------
+  // elementTypeClass
+  //
+  // Property for the element type class, if the database object type is a
+  // collection and the elements in the collection refer to database objects.
+  //---------------------------------------------------------------------------
+  get elementTypeClass() {
+    return this._objType.elementTypeClass;
+  }
+
+  //---------------------------------------------------------------------------
+  // elementTypeName
+  //
+  // Property for the element type name, if the database object type is a
+  // collection.
+  //---------------------------------------------------------------------------
+  get elementTypeName() {
+    return this._objType.elementTypeName;
+  }
+
+  //---------------------------------------------------------------------------
+  // fqn
+  //
+  // Property for the fully qualified name of the database object type in the
+  // form: <schema>.<name>.
+  //---------------------------------------------------------------------------
+  get fqn() {
+    return this._objType.fqn;
+  }
+
+  //---------------------------------------------------------------------------
+  // getElement()
+  //
+  // Returns the element in a collection at the specified index.
+  //---------------------------------------------------------------------------
+  getElement(index) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    const value = this._impl.getElement(index);
+    return this._transformValueOut(value, this.elementTypeClass);
+  }
+
+  //---------------------------------------------------------------------------
+  // getKeys()
+  //
+  // Returns an array of the keys of the collection.
+  //---------------------------------------------------------------------------
+  getKeys() {
+    errors.assertArgCount(arguments, 0, 0);
+    return this._impl.getKeys();
+  }
+
+  //---------------------------------------------------------------------------
+  // getFirstIndex()
+  //
+  // Returns the first index in the collection.
+  //---------------------------------------------------------------------------
+  getFirstIndex() {
+    errors.assertArgCount(arguments, 0, 0);
+    return this._impl.getFirstIndex();
+  }
+
+  //---------------------------------------------------------------------------
+  // getLastIndex()
+  //
+  // Returns the last index in the collection.
+  //---------------------------------------------------------------------------
+  getLastIndex() {
+    errors.assertArgCount(arguments, 0, 0);
+    return this._impl.getLastIndex();
+  }
+
+  //---------------------------------------------------------------------------
+  // getNextIndex()
+  //
+  // Returns the next index in the collection.
+  //---------------------------------------------------------------------------
+  getNextIndex(index) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    return this._impl.getNextIndex(index);
+  }
+
+  //---------------------------------------------------------------------------
+  // getPrevIndex()
+  //
+  // Returns the previous index in the collection.
+  //---------------------------------------------------------------------------
+  getPrevIndex(index) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    return this._impl.getPrevIndex(index);
+  }
+
+  //---------------------------------------------------------------------------
+  // getValues()
+  //
+  // Returns the elements in a collection.
+  //---------------------------------------------------------------------------
+  getValues() {
+    errors.assertArgCount(arguments, 0, 0);
+    const values = this._impl.getValues();
+    for (let i = 0; i < values.length; i++) {
+      values[i] = this._transformValueOut(values[i], this.elementTypeClass);
+    }
+    return values;
+  }
+
+  //---------------------------------------------------------------------------
+  // hasElement()
+  //
+  // Returns a boolean indicating if an element exists at the specified index.
+  //---------------------------------------------------------------------------
+  hasElement(index) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    return this._impl.hasElement(index);
+  }
+
+  //---------------------------------------------------------------------------
+  // isCollection
+  //
+  // Property indicating if the object is a collection or not.
+  //---------------------------------------------------------------------------
+  get isCollection() {
+    return this._objType.isCollection;
+  }
+
+  //---------------------------------------------------------------------------
+  // name
+  //
+  // Property for the name of the database object type.
+  //---------------------------------------------------------------------------
+  get name() {
+    return this._objType.name;
+  }
+
+  //---------------------------------------------------------------------------
+  // schema
+  //
+  // Property for the schema of the database object type.
+  //---------------------------------------------------------------------------
+  get schema() {
+    return this._objType.schema;
+  }
+
+  //---------------------------------------------------------------------------
+  // setElement()
+  //
+  // Sets the element in the collection at the specified index to the given
+  // value.
+  //---------------------------------------------------------------------------
+  setElement(index, value) {
+    errors.assertArgCount(arguments, 2, 2);
+    errors.assertParamValue(Number.isInteger(index), 1);
+    const info = {
+      fqn: this._objType.fqn,
+      type: this._objType.elementType,
+      typeClass: this._objType.elementTypeClass
+    };
+    const options = {allowArray: false};
+    value = transformer.transformValueIn(info, value, options);
+    this._impl.setElement(index, value);
+  }
+
+  //---------------------------------------------------------------------------
+  // trim()
+  //
+  // Trims the specified number of elements from the end of the collection.
+  //---------------------------------------------------------------------------
+  trim(numToTrim) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Number.isInteger(numToTrim) && numToTrim >= 0, 1);
+    this._impl.trim(numToTrim);
+  }
+
   // custom inspection routine
   [util.inspect.custom](depth, options) {
     return ('[' + this.fqn + '] ' + util.inspect(this._toPojo(), options));
@@ -96,6 +381,41 @@ class BaseDbObject {
 
 }
 
+// method for transforming the error
+function transformErr(func) {
+  return function() {
+    try {
+      return func.apply(this, arguments);
+    } catch (err) {
+      throw errors.transformErr(err, errors.transformErr);
+    }
+  };
+}
+
+// method for wrapping the functions so that any errors thrown are transformed
+function wrapFns(proto) {
+  for (let i = 1; i < arguments.length; i++) {
+    const name = arguments[i];
+    proto[name] = transformErr(proto[name]);
+  }
+}
+
+wrapFns(BaseDbObject.prototype,
+  "_getAttrValue",
+  "_setAttrValue",
+  "append",
+  "deleteElement",
+  "getElement",
+  "getKeys",
+  "getFirstIndex",
+  "getLastIndex",
+  "getNextIndex",
+  "getPrevIndex",
+  "getValues",
+  "hasElement",
+  "setElement",
+  "trim"
+);
 
 // define proxy handler used for collections
 BaseDbObject._collectionProxyHandler = {
@@ -112,14 +432,6 @@ BaseDbObject._collectionProxyHandler = {
 
   get(target, prop) {
     if (typeof prop === 'string') {
-
-      // when binding collections, we must be consistent in getting the target
-      // of the proxy, since napi_wrap() called on the proxy will not be
-      // available when calling napi_unwrap() on the target; this property
-      // forces the target to get returned
-      if (prop === '_target') {
-        return (target);
-      }
       const index = +prop;
       if (!isNaN(index)) {
         return (target.getElement(index));
@@ -146,5 +458,7 @@ BaseDbObject._collectionProxyHandler = {
 
 };
 
-
 module.exports = BaseDbObject;
+
+// load this after the module exports are set so that it is available
+const transformer = require('./transformer.js');