oracledb 5.5.0 → 6.0.0

package/lib/settings.js

@@ -0,0 +1,191 @@
+// 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.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+const constants = require('./constants.js');
+const errors = require('./errors.js');
+const types = require('./types.js');
+
+class Settings {
+
+  constructor() {
+    this.autoCommit = false;
+    this.connectionClass = '';
+    this.dbObjectAsPojo = false;
+    this.edition = '';
+    this.errorOnConcurrentExecute = false;
+    this.events = false;
+    this.externalAuth = false;
+    this.fetchArraySize = 100;
+    this.fetchAsBuffer = [];
+    this.fetchAsString = [];
+    this.lobPrefetchSize = 16384;
+    this.maxRows = 0;
+    this.outFormat = constants.OUT_FORMAT_ARRAY;
+    this.poolIncrement = 1;
+    this.poolMax = 4;
+    this.poolMaxPerShard = 0;
+    this.poolMin = 0;
+    this.poolPingInterval = 60;
+    this.poolTimeout = 60;
+    this.prefetchRows = 2;
+    this.queueTimeout = 60000;
+    this.queueMax = 500;
+    this.stmtCacheSize = 30;
+    this.thin = true;
+    this.thinDriverInitialized = false;
+    this.createFetchTypeMap(this.fetchAsString, this.fetchAsBuffer);
+    this.fetchTypeHandler = undefined;
+  }
+
+  //---------------------------------------------------------------------------
+  // _getDateComponents()
+  //
+  // Returns the components of a date. DATE and TIMESTAMP data from the
+  // database are returned as though they used the JavaScript time zone
+  // setting. TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE data
+  // are returned in native JavaScript format (since they contain time zone
+  // information).
+  //---------------------------------------------------------------------------
+  _getDateComponents(useLocal, date) {
+    if (useLocal) {
+      return [
+        date.getFullYear(),
+        date.getMonth() + 1,
+        date.getDate(),
+        date.getHours(),
+        date.getMinutes(),
+        date.getSeconds(),
+        date.getMilliseconds() * 1000 * 1000
+      ];
+    } else {
+      return [
+        date.getUTCFullYear(),
+        date.getUTCMonth() + 1,
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+        date.getUTCSeconds(),
+        date.getUTCMilliseconds() * 1000 * 1000
+      ];
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // _makeDate()
+  //
+  // Returns a date from the given components. DATE and TIMESTAMP data from the
+  // database are returned as though they used the JavaScript time zone
+  // setting. TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE data
+  // are returned in native JavaScript format (since they contain time zone
+  // 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);
+  }
+
+  //---------------------------------------------------------------------------
+  // addToOptions()
+  //
+  // Adds the named settingsto the options, if no option has already been
+  // specified.
+  //---------------------------------------------------------------------------
+  addToOptions(options) {
+    for (let i = 1; i < arguments.length; i++) {
+      const key = arguments[i];
+      if (options[key] === undefined)
+        options[key] = this[key];
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // createFetchTypeMap()
+  //
+  // Creates the fetch type map. This overrides the default fetch type mapping
+  // used by the driver with the contents of the fetchAsString and
+  // fetchAsBuffer arrays. The error checking is performed here as well in
+  // order to eliminate repeated code.
+  // ---------------------------------------------------------------------------
+  createFetchTypeMap(fetchAsString, fetchAsBuffer) {
+
+    // create a copy of the default fetch type map
+    const map = new Map(types.DB_TYPE_FETCH_TYPE_MAP);
+
+    // adjust map for fetchAsString settings
+    for (const element of fetchAsString) {
+      switch (element) {
+        case types.DB_TYPE_NUMBER:
+          map.set(types.DB_TYPE_BINARY_DOUBLE, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_BINARY_FLOAT, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_BINARY_INTEGER, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_NUMBER, types.DB_TYPE_VARCHAR);
+          break;
+        case types.DB_TYPE_TIMESTAMP:
+          map.set(types.DB_TYPE_DATE, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_TIMESTAMP, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_TIMESTAMP_TZ, types.DB_TYPE_VARCHAR);
+          map.set(types.DB_TYPE_TIMESTAMP_LTZ, types.DB_TYPE_VARCHAR);
+          break;
+        case types.DB_TYPE_CLOB:
+        case types.DB_TYPE_NCLOB:
+          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_RAW:
+          map.set(types.DB_TYPE_RAW, types.DB_TYPE_VARCHAR);
+          break;
+        case types.DB_TYPE_JSON:
+          map.set(types.DB_TYPE_JSON, types.DB_TYPE_VARCHAR);
+          break;
+        default:
+          errors.throwErr(errors.ERR_INVALID_TYPE_FOR_CONVERSION);
+      }
+    }
+
+    // adjust map for fetchAsBuffer settings
+    for (const element of fetchAsBuffer) {
+      switch (element) {
+        case types.DB_TYPE_BLOB:
+          map.set(types.DB_TYPE_BLOB, types.DB_TYPE_LONG_RAW);
+          break;
+        default:
+          errors.throwErr(errors.ERR_INVALID_TYPE_FOR_CONVERSION);
+      }
+    }
+
+    // assign calculated fetchTypeMap for later use
+    this.fetchTypeMap = map;
+
+  }
+
+}
+
+module.exports = new Settings();

package/lib/sodaCollection.js

@@ -1,17 +1,24 @@
-// Copyright (c) 2018, 2022, Oracle and/or its affiliates.
+// Copyright (c) 2018, 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,238 +26,244 @@
 
 'use strict';
 
+const SodaDocument = require('./sodaDocument.js');
+const SodaOperation = require('./sodaOperation.js');
+const errors = require('./errors.js');
 const nodbUtil = require('./util.js');
+const settings = require('./settings.js');
 
-//-----------------------------------------------------------------------------
-// drop()
-//   Drop the collection.
-//-----------------------------------------------------------------------------
-async function drop() {
-  nodbUtil.checkArgCount(arguments, 0, 0);
-  return await this._drop();
-}
-
+class SodaCollection {
 
-//-----------------------------------------------------------------------------
-// insertMany()
-//   Insert an array of documents into the collection in a single round-trip.
-//-----------------------------------------------------------------------------
-async function insertMany(docs) {
-  nodbUtil.checkArgCount(arguments, 1, 1);
-  nodbUtil.assert(Array.isArray(docs), 'NJS-005', 1);
+  //---------------------------------------------------------------------------
+  // createIndex()
+  //
+  // Create an index on the collection.
+  //---------------------------------------------------------------------------
+  async createIndex(spec) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(nodbUtil.isObject(spec), 1);
+    const options = {autoCommit: settings.autoCommit};
+    return await this._impl.createIndex(JSON.stringify(spec), options);
+  }
 
-  if (docs.length == 0) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-005', 1));
+  //---------------------------------------------------------------------------
+  // drop()
+  //
+  // Drop the collection.
+  //---------------------------------------------------------------------------
+  async drop() {
+    errors.assertArgCount(arguments, 0, 0);
+    const options = {autoCommit: settings.autoCommit};
+    return await this._impl.drop(options);
   }
 
-  let actualDocs = Array(docs.length);
-  for (let i = 0; i < docs.length; i++) {
-    let content = docs[i];
-    if (!nodbUtil.isSodaDocument(content)) {
-      content = Buffer.from(JSON.stringify(content));
+  //---------------------------------------------------------------------------
+  // dropIndex()
+  //
+  // Drop an index on the collection.
+  //---------------------------------------------------------------------------
+  async dropIndex(indexName, a2) {
+    const options = {autoCommit: settings.autoCommit};
+
+    errors.assertArgCount(arguments, 1, 2);
+    errors.assertParamValue(typeof indexName === 'string', 1);
+    if (arguments.length == 2) {
+      errors.assertParamValue(typeof a2 === 'object', 2);
+      if (a2.force !== undefined) {
+        errors.assertParamPropValue(typeof a2.force === 'boolean', 2, "force");
+        options.force = a2.force;
+      }
     }
-    actualDocs[i] = content;
+    return await this._impl.dropIndex(indexName, options);
   }
 
-  await this._insertMany(actualDocs);
-}
-
-
-//-----------------------------------------------------------------------------
-// insertManyAndGet()
-//   Insert an array of documents into the collection in a single round-trip
-// and return a set of result documents containing metadata.
-//-----------------------------------------------------------------------------
-async function insertManyAndGet(docs, a2) {
-  let options = {};
-
-  nodbUtil.checkArgCount(arguments, 1, 2);
-  nodbUtil.assert(Array.isArray(docs), 'NJS-005', 1);
-
-  if (arguments.length == 2) {
-    nodbUtil.assert(nodbUtil.isObject(a2), 'NJS-005', 2);
-    options = a2;
+  //---------------------------------------------------------------------------
+  // find()
+  //
+  // Returns a SODA operation associated with the collection.
+  //---------------------------------------------------------------------------
+  find() {
+    errors.assertArgCount(arguments, 0, 0);
+    const op = new SodaOperation();
+    op._impl = this._impl.find();
+    return op;
   }
 
-  if (docs.length == 0) {
-    throw new Error(nodbUtil.getErrorMessage('NJS-005', 1));
+  //---------------------------------------------------------------------------
+  // getDataGuide()
+  //   Return the data guide for the collection.
+  //---------------------------------------------------------------------------
+  async getDataGuide() {
+    errors.assertArgCount(arguments, 0, 0);
+    const doc = new SodaDocument();
+    doc._impl = await this._impl.getDataGuide();
+    return doc;
   }
 
-  let actualDocs = Array(docs.length);
-  for (let i = 0; i < docs.length; i++) {
-    let content = docs[i];
-    if (!nodbUtil.isSodaDocument(content)) {
-      content = Buffer.from(JSON.stringify(content));
+  //---------------------------------------------------------------------------
+  // insertMany()
+  //
+  // Insert an array of documents into the collection in a single round-trip.
+  //---------------------------------------------------------------------------
+  async insertMany(docs) {
+    errors.assertArgCount(arguments, 1, 1);
+    errors.assertParamValue(Array.isArray(docs) && docs.length > 0, 1);
+
+    let actualDocs = Array(docs.length);
+    for (let i = 0; i < docs.length; i++) {
+      actualDocs[i] = nodbUtil.verifySodaDoc(docs[i]);
     }
-    actualDocs[i] = content;
-  }
 
-  return await this._insertManyAndGet(actualDocs, options);
-}
-
-
-//-----------------------------------------------------------------------------
-// insertOne()
-//   Inserts a single document into the collection.
-//-----------------------------------------------------------------------------
-async function insertOne(content) {
-  nodbUtil.checkArgCount(arguments, 1, 1);
-  nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
-
-  if (!nodbUtil.isSodaDocument(content)) {
-    content = Buffer.from(JSON.stringify(content));
+    const options = {autoCommit: settings.autoCommit};
+    await this._impl.insertMany(actualDocs, options);
   }
 
-  await this._insertOne(content);
-}
-
+  //---------------------------------------------------------------------------
+  // insertManyAndGet()
+  //
+  // Insert an array of documents into the collection in a single round-trip
+  // and return a set of result documents containing metadata.
+  //---------------------------------------------------------------------------
+  async insertManyAndGet(docs, a2) {
+    const options = {autoCommit: settings.autoCommit};
+
+    errors.assertArgCount(arguments, 1, 2);
+    errors.assertParamValue(Array.isArray(docs) && docs.length > 0, 1);
+
+    if (arguments.length == 2) {
+      errors.assertParamValue(nodbUtil.isObject(a2), 2);
+      if (a2.hint !== undefined) {
+        errors.assertParamPropValue(typeof a2.hint === 'string', 2, "hint");
+        options.hint = a2.hint;
+      }
+    }
 
-//-----------------------------------------------------------------------------
-// insertOneAndGet()
-//   Inserts a single document into the collection and returns a result
-// document containing metadata.
-//-----------------------------------------------------------------------------
-async function insertOneAndGet(content, a2) {
-  let options = {};
+    const actualDocs = Array(docs.length);
+    for (let i = 0; i < docs.length; i++) {
+      actualDocs[i] = nodbUtil.verifySodaDoc(docs[i]);
+    }
 
-  nodbUtil.checkArgCount(arguments, 1, 2);
-  nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
+    const docImpls = await this._impl.insertManyAndGet(actualDocs, options);
+    for (let i = 0; i < docs.length; i++) {
+      const doc = actualDocs[i] = new SodaDocument();
+      doc._impl = docImpls[i];
+    }
 
-  if (arguments.length == 2) {
-    nodbUtil.assert(nodbUtil.isObject(a2), 'NJS-005', 2);
-    options = a2;
+    return actualDocs;
   }
 
-  if (!nodbUtil.isSodaDocument(content)) {
-    content = Buffer.from(JSON.stringify(content));
+  //---------------------------------------------------------------------------
+  // insertOne()
+  //
+  // Inserts a single document into the collection.
+  //---------------------------------------------------------------------------
+  async insertOne(content) {
+    errors.assertArgCount(arguments, 1, 1);
+    content = nodbUtil.verifySodaDoc(content);
+    const options = {autoCommit: settings.autoCommit};
+    await this._impl.insertOne(content, options);
   }
 
-  return await this._insertOneAndGet(content, options);
-}
-
-
-//-----------------------------------------------------------------------------
-// createIndex()
-//   Create an index on the collection.
-//-----------------------------------------------------------------------------
-async function createIndex(spec) {
-  nodbUtil.checkArgCount(arguments, 1, 1);
-  nodbUtil.assert(nodbUtil.isObject(spec), 'NJS-005', 1);
-  return await this._createIndex(JSON.stringify(spec));
-}
-
-
-//-----------------------------------------------------------------------------
-// dropIndex()
-//   Drop an index on the collection.
-//-----------------------------------------------------------------------------
-async function dropIndex(indexName, a2) {
-  let options = {};
-
-  nodbUtil.checkArgCount(arguments, 1, 2);
-  nodbUtil.assert(typeof indexName === 'string', 'NJS-005', 1);
-  if (arguments.length == 2) {
-    nodbUtil.assert(typeof a2 === 'object', 'NJS-005', 2);
-    options = a2;
-  }
-
-  return await this._dropIndex(indexName, options);
-}
-
-
-//-----------------------------------------------------------------------------
-// getDataGuide()
-//   Return the data guide for the collection.
-//-----------------------------------------------------------------------------
-async function getDataGuide() {
-  nodbUtil.checkArgCount(arguments, 0, 0);
-  return await this._getDataGuide();
-}
-
-
-//-----------------------------------------------------------------------------
-// save()
-//   Saves a single document into the collection.
-//-----------------------------------------------------------------------------
-async function save(content) {
-  nodbUtil.checkArgCount(arguments, 1, 1);
-  nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
+  //---------------------------------------------------------------------------
+  // insertOneAndGet()
+  //
+  // Inserts a single document into the collection and returns a result
+  // document containing metadata.
+  //---------------------------------------------------------------------------
+  async insertOneAndGet(content, a2) {
+    const options = {autoCommit: settings.autoCommit};
+
+    errors.assertArgCount(arguments, 1, 2);
+    content = nodbUtil.verifySodaDoc(content);
+    if (arguments.length == 2) {
+      errors.assertParamValue(nodbUtil.isObject(a2), 2);
+      if (a2.hint !== undefined) {
+        errors.assertParamPropValue(typeof a2.hint === 'string', 2, "hint");
+        options.hint = a2.hint;
+      }
+    }
 
-  if (!nodbUtil.isSodaDocument(content)) {
-    content = Buffer.from(JSON.stringify(content));
+    const doc = new SodaDocument();
+    doc._impl = await this._impl.insertOneAndGet(content, options);
+    return doc;
   }
 
-  await this._save(content);
-}
-
-
-//-----------------------------------------------------------------------------
-// saveAndGet()
-//   Saves a single document into the collection and returns a result
-// document containing metadata.
-//-----------------------------------------------------------------------------
-async function saveAndGet(content, a2) {
-  let options = {};
-
-  nodbUtil.checkArgCount(arguments, 1, 2);
-  nodbUtil.assert(nodbUtil.isObject(content) ||
-      nodbUtil.isSodaDocument(content), 'NJS-005', 1);
-
-  if (arguments.length == 2) {
-    nodbUtil.assert(nodbUtil.isObject(a2), 'NJS-005', 2);
-    options = a2;
+  //---------------------------------------------------------------------------
+  // metaData()
+  //
+  // Property for the metadata associated with the collection.
+  //---------------------------------------------------------------------------
+  get metaData() {
+    return JSON.parse(this._impl.getMetaData());
   }
 
-  if (!nodbUtil.isSodaDocument(content)) {
-    content = Buffer.from(JSON.stringify(content));
+  //---------------------------------------------------------------------------
+  // name()
+  //
+  // Property for the name of the collection.
+  //---------------------------------------------------------------------------
+  get name() {
+    return this._impl.getName();
   }
 
-  return await this._saveAndGet(content, options);
-}
-
-
-//-----------------------------------------------------------------------------
-// truncate()
-//   Remove all of the documents from a collection.
-//-----------------------------------------------------------------------------
-async function truncate() {
-  nodbUtil.checkArgCount(arguments, 0, 0);
-  await this._truncate();
-}
-
-
-class SodaCollection {
-
-  _extend() {
-    this.createIndex = nodbUtil.callbackify(nodbUtil.serialize(createIndex));
-    this.drop = nodbUtil.callbackify(nodbUtil.serialize(drop));
-    this.dropIndex = nodbUtil.callbackify(nodbUtil.serialize(dropIndex));
-    this.getDataGuide = nodbUtil.callbackify(nodbUtil.serialize(getDataGuide));
-    this.insertMany = nodbUtil.callbackify(nodbUtil.serialize(insertMany));
-    this.insertManyAndGet = nodbUtil.callbackify(nodbUtil.serialize(insertManyAndGet));
-    this.insertOne = nodbUtil.callbackify(nodbUtil.serialize(insertOne));
-    this.insertOneAndGet = nodbUtil.callbackify(nodbUtil.serialize(insertOneAndGet));
-    this.save = nodbUtil.callbackify(nodbUtil.serialize(save));
-    this.saveAndGet = nodbUtil.callbackify(nodbUtil.serialize(saveAndGet));
-    this.truncate = nodbUtil.callbackify(nodbUtil.serialize(truncate));
+  //---------------------------------------------------------------------------
+  // save()
+  //
+  // Saves a single document into the collection.
+  //---------------------------------------------------------------------------
+  async save(content) {
+    errors.assertArgCount(arguments, 1, 1);
+    content = nodbUtil.verifySodaDoc(content);
+    const options = {autoCommit: settings.autoCommit};
+    await this._impl.save(content, options);
   }
 
-  _getConnection() {
-    return this._database._connection;
-  }
+  //---------------------------------------------------------------------------
+  // saveAndGet()
+  //
+  // Saves a single document into the collection and returns a result document
+  // containing metadata.
+  //---------------------------------------------------------------------------
+  async saveAndGet(content, a2) {
+    errors.assertArgCount(arguments, 1, 2);
+    content = nodbUtil.verifySodaDoc(content);
+    const options = {autoCommit: settings.autoCommit};
+    if (arguments.length == 2) {
+      errors.assertParamValue(nodbUtil.isObject(a2), 2);
+      if (a2.hint !== undefined) {
+        errors.assertParamPropValue(typeof a2.hint === 'string', 2, "hint");
+        options.hint = a2.hint;
+      }
+    }
 
-  find() {
-    nodbUtil.checkArgCount(arguments, 0, 0);
-    return this._find();
+    const doc = new SodaDocument();
+    doc._impl = await this._impl.saveAndGet(content, options);
+    return doc;
   }
 
-  get metaData() {
-    return JSON.parse(this._metaData);
+  //---------------------------------------------------------------------------
+  // truncate()
+  //
+  // Remove all of the documents from a collection.
+  //---------------------------------------------------------------------------
+  async truncate() {
+    errors.assertArgCount(arguments, 0, 0);
+    await this._impl.truncate();
   }
 
 }
 
+nodbUtil.wrapFns(SodaCollection.prototype,
+  "createIndex",
+  "drop",
+  "dropIndex",
+  "getDataGuide",
+  "insertMany",
+  "insertManyAndGet",
+  "insertOne",
+  "insertOneAndGet",
+  "save",
+  "saveAndGet",
+  "truncate");
+
 module.exports = SodaCollection;