oracledb 6.7.2 → 6.8.0

package/lib/types.js

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+// Copyright (c) 2022, 2025, Oracle and/or its affiliates.
 
 //-----------------------------------------------------------------------------
 //
@@ -33,6 +33,7 @@ const util = require('util');
 const dbTypeByNum = new Map();
 const dbTypeByOraTypeNum = new Map();
 const dbTypeByColumnTypeName = new Map();
+const MAX_UINT32 = Math.pow(2, 32) - 1;
 
 // define class used for database types
 class DbType {
@@ -145,7 +146,7 @@ const DB_TYPE_INTERVAL_DS = new DbType(2015,
   { oraTypeNum: 183, bufferSizeFactor: 11 });
 const DB_TYPE_INTERVAL_YM = new DbType(2016,
   "DB_TYPE_INTERVAL_YM", "INTERVAL YEAR TO MONTH",
-  { oraTypeNum: 182 });
+  { oraTypeNum: 182, bufferSizeFactor: 5 });
 const DB_TYPE_JSON = new DbType(2027,
   "DB_TYPE_JSON", "JSON",
   { oraTypeNum: 119 });
@@ -339,6 +340,219 @@ class JsonId extends Uint8Array {
   }
 }
 
+// Represents the SparseVector.
+// indices must be an regular Array
+// values can be regular or typedArray.
+class SparseVector {
+  constructor(input) {
+    this._indices = new Uint32Array(0);
+    this._values = new Float64Array(0);
+    this._numDimensions = 0;
+
+    if (!input) {
+      return;
+    }
+    if (typeof input === 'object' &&
+      "numDimensions" in input &&
+      "indices" in input &&
+      "values" in input
+    ) {
+      // Object has valid properties for Sparse.
+      this._fromObject(input);
+    } else if (typeof input === 'string') {
+      // initialize from string.
+      this._fromString(input);
+    } else if (this._validDenseArray(input)) {
+      // dense array
+      this._fromDense(input);
+    } else {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_INVALID_INPUT);
+    }
+  }
+
+  _validDenseArray(value) {
+    return (value instanceof Float32Array ||
+      value instanceof Float64Array ||
+      value instanceof Int8Array || (Object.getPrototypeOf(value)
+        === Uint8Array.prototype) || Array.isArray(value));
+  }
+
+  // Check if indexArray and valuesArray have the same length
+  static _validateLengths(indices, values) {
+    if (indices.length !== values.length) {
+      if (!(values instanceof Uint8Array)) {
+      // Skip for binary vector format
+        errors.throwErr(errors.ERR_VECTOR_SPARSE_INDICES_VALUES_NOT_EQUAL);
+      }
+    }
+  }
+
+  _updateProperties(dims, indices, values) {
+    if (!this._validDenseArray(values)) {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_VALUES_IS_NOT_ARRAY);
+    }
+    if (!(indices instanceof Uint32Array) && !Array.isArray(indices)) {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_INDICES_IS_NOT_ARRAY);
+    }
+    SparseVector._validateLengths(indices, values);
+    if (!(typeof dims === 'number' && Number.isInteger(dims) && dims > 0)) {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_DIMS_IS_NOT_INTEGER);
+    }
+
+    this._numDimensions = dims;
+    this._indices = indices;
+    this._values = values;
+    this._convertToTypedArrays();
+  }
+
+  _fromObject(input) {
+    this._updateProperties(input.numDimensions, input.indices, input.values);
+  }
+
+  _convertToTypedArrays() {
+    // convert to typed arrays.
+    if (!(this._indices instanceof Uint32Array)) {
+      // validate elements are valid uint32 type.
+      const indices = new Uint32Array(this._indices.map((x, index) => {
+        if (typeof x !== 'number' || !Number.isInteger(x)) {
+          errors.throwErr(errors.ERR_VECTOR_SPARSE_INDICES_ELEM_IS_NOT_VALID, index);
+        }
+        if (x < 0 || x > MAX_UINT32 || x > (this.numDimensions - 1)) {
+          errors.throwErr(errors.ERR_VECTOR_SPARSE_INDICES_ELEM_IS_NOT_VALID,
+            index);
+        }
+        return x;
+      }));
+      this._indices = indices;
+    }
+
+    this._values = Array.isArray(this._values) ? new Float64Array(this._values)
+      : this._values;
+  }
+
+  // Initialize the state using the dense array.
+  // The length of input is assumed to be same as
+  // dimensions of sparse Vector column.
+  // values will be an array even if input is a typedArray.
+  _fromDense(input) {
+    this._indices = [];
+    this._values = [];
+
+    for (let i = 0; i < input.length; i++) {
+      if (input[i] !== 0) {
+        this._indices.push(i);
+        this._values.push(input[i]);
+      }
+    }
+    this._numDimensions = input.length;
+    this._convertToTypedArrays();
+  }
+
+  // parse a string input into a sparse vector
+  _fromString(str) {
+    let data;
+
+    // verify it is a valid JSON
+    try {
+      // use simple tokenizer?
+      data = JSON.parse(str);
+    } catch (e) {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_INVALID_JSON);
+    }
+
+    // Check if data is an array with exactly 3 elements
+    if (!Array.isArray(data) || data.length !== 3) {
+      errors.throwErr(errors.ERR_VECTOR_SPARSE_INVALID_STRING);
+    }
+
+    const [dims, indices, values] = data;
+    this._updateProperties(dims, indices, values);
+  }
+
+  // Internal method to create an instance
+  static create(sparseValue) {
+    SparseVector._validateLengths(sparseValue.indices, sparseValue.values);
+    const instance = Object.create(this.prototype);
+    instance._numDimensions = sparseValue.numDimensions;
+    instance._indices = sparseValue.indices;
+    instance._values = sparseValue.values;
+    return instance;
+  }
+
+  get indices() {
+    return this._indices;
+  }
+
+  get values() {
+    return this._values;
+  }
+
+  get numDimensions() {
+    return this._numDimensions;
+  }
+
+  toJSON() {
+    return {
+      numDimensions: this._numDimensions,
+      indices: this._indices,
+      values: this._values,
+    };
+  }
+
+  // It always constructs a typedArray.
+  _createEmptyArray(input, len) {
+    if (Array.isArray(input)) {
+      return new Float64Array(len);
+    } else {
+      // same typedArray of input type.
+      return new input.constructor(len);
+    }
+  }
+
+  // Convert sparse vector to a dense vector
+  // It returns typed array.
+  dense() {
+    if (this._numDimensions === 0) {
+      return null;
+    }
+    const dense = this._createEmptyArray(this._values, this._numDimensions);
+    this._indices.forEach((index, i) => {
+      dense[index] = this._values[i];
+    });
+    return dense;
+  }
+}
+
+// Interval Year-to-Month Class
+class IntervalYM {
+  constructor(obj) {
+    if (obj) {
+      errors.assertParamPropInt(obj, 1, "years");
+      errors.assertParamPropInt(obj, 1, "months");
+    }
+    this.years = obj?.years || 0;
+    this.months = obj?.months || 0;
+  }
+}
+
+// Interval Day-to-Second Class
+class IntervalDS {
+  constructor(obj) {
+    if (obj) {
+      errors.assertParamPropInt(obj, 1, "days");
+      errors.assertParamPropInt(obj, 1, "hours");
+      errors.assertParamPropInt(obj, 1, "minutes");
+      errors.assertParamPropInt(obj, 1, "seconds");
+      errors.assertParamPropInt(obj, 1, "fseconds");
+    }
+    this.days = obj?.days || 0;
+    this.hours = obj?.hours || 0;
+    this.minutes = obj?.minutes || 0;
+    this.seconds = obj?.seconds || 0;
+    this.fseconds = obj?.fseconds || 0;
+  }
+}
+
 module.exports = {
   DbType,
   DB_TYPE_BFILE,
@@ -376,5 +590,8 @@ module.exports = {
   getTypeByColumnTypeName,
   getTypeByNum,
   getTypeByOraTypeNum,
-  JsonId
+  JsonId,
+  SparseVector,
+  IntervalYM,
+  IntervalDS
 };

package/lib/util.js

@@ -501,7 +501,7 @@ function isVectorValue(value) {
   return (value instanceof Float32Array ||
     value instanceof Float64Array ||
     value instanceof Int8Array || (Object.getPrototypeOf(value)
-      === Uint8Array.prototype));
+      === Uint8Array.prototype) || value instanceof types.SparseVector);
 }
 
 //-----------------------------------------------------------------------------

package/lib/version.js

@@ -30,7 +30,7 @@
 
 module.exports = {
   VERSION_MAJOR: 6,
-  VERSION_MINOR: 7,
-  VERSION_PATCH: 2,
+  VERSION_MINOR: 8,
+  VERSION_PATCH: 0,
   VERSION_SUFFIX: ''
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracledb",
-  "version": "6.7.2",
+  "version": "6.8.0",
   "description": "A Node.js module for Oracle Database access from JavaScript and TypeScript",
   "license": "(Apache-2.0 OR UPL-1.0)",
   "homepage": "http://oracle.github.io/node-oracledb/",

package/plugins/token/extensionAzure/index.js

@@ -0,0 +1,101 @@
+// Copyright (c) 2025, 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 oracledb = require('oracledb');
+const msal = require('@azure/msal-node');
+
+
+async function getToken(params) {
+  switch (params.authType.toLowerCase()) {
+    case 'azureserviceprincipal':
+      return await servicePrincipalCredentials(params);
+    default:
+      throwErr(`Invalid authentication type ${params.authType} in extensionAzure plugins.`);
+  }
+}
+
+//---------------------------------------------------------------------------
+// throwErr()
+//---------------------------------------------------------------------------
+function throwErr(message) {
+  throw new Error(message);
+}
+
+//---------------------------------------------------------------------------
+// Returns the access token for authentication as a service principal. This
+// authentication method requires a client ID along with either a secret or
+// certificate. These values may be provided as config parameters read by
+// the Azure SDK.
+// ---------------------------------------------------------------------------
+async function servicePrincipalCredentials(params) {
+  const clientId = params.clientId ??
+    throwErr("Token based authentication config parameter clientId is missing for azureServicePrincipal in extensionAzure plugins.");
+  const authority = params.authority ??
+    throwErr("Token based authentication config parameter authority is missing for azureServicePrincipal in extensionAzure plugins.");
+  const clientSecret = params.clientSecret ??
+    throwErr("Token based authentication config parameter clientSecret is missing for azureServicePrincipal in extensionAzure plugins.");
+  const msalConfig = {
+    auth: {
+      clientId: clientId,
+      authority: authority,
+      clientSecret: clientSecret,
+    },
+    system: {
+      // Use it while generating azure tokens behind proxy
+      // Otherwise can remove this option
+      networkClient: params.proxy,
+    },
+  };
+
+  if (!msalConfig.system.networkClient) {
+    delete msalConfig.system.networkClient;
+  }
+
+  const scopes = params.scopes ??
+    throwErr("Token based authentication config parameter scopes is missing for azureServicePrincipal in extensionAzure plugins.");
+  const tokenRequest = {
+    scopes: [scopes],
+  };
+  const cca = new msal.ConfidentialClientApplication(msalConfig);
+  const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
+  return authResponse.accessToken;
+}
+
+// ---------------------------------------------------------------------------
+// hookFn()
+// hookFn is registered to driver while loading plugins.
+// ---------------------------------------------------------------------------
+
+function hookFn(options) {
+  if (options.tokenAuthConfigAzure) {
+    // eslint-disable-next-line no-unused-vars
+    options.accessToken = async function callbackFn(refresh, config) {
+      return await getToken(config);
+    };
+    options.accessTokenConfig = options.tokenAuthConfigAzure;
+  }
+}
+oracledb.registerProcessConfigurationHook(hookFn);

package/plugins/token/extensionOci/index.js

@@ -0,0 +1,174 @@
+// Copyright (c) 2025, 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 oracledb = require('oracledb');
+const identitydataplane = require("oci-identitydataplane");
+const common = require("oci-common");
+const { generateKeyPair } = require('crypto');
+const fs = require('fs');
+
+async function getToken(params) {
+  switch (params.authType.toLowerCase()) {
+    case 'configfilebasedauthentication':
+      return await configFileBasedAuthentication(params);
+    case 'simpleauthentication':
+      return await simpleAuthentication(params);
+    default:
+      throwErr(`Invalid authentication type ${params.authType} in extensionOci plugins.`);
+  }
+}
+
+//---------------------------------------------------------------------------
+// throwErr()
+//---------------------------------------------------------------------------
+function throwErr(message) {
+  throw new Error(message);
+}
+
+//---------------------------------------------------------------------------
+// Generates a public-private key pair for proof of possession when token
+// requested by this provider is presented for validation.
+//---------------------------------------------------------------------------
+async function _getKeyPair() {
+  return await new Promise((resolve, reject) => {
+    generateKeyPair('rsa', {
+      modulusLength: 4096,
+      publicKeyEncoding: {
+        type: 'spki',
+        format: 'pem'
+      },
+      privateKeyEncoding: {
+        type: 'pkcs8',
+        format: 'pem',
+      }
+    }, (err, publicKey, privateKey) => {
+      if (err) return reject(err);
+      resolve({publicKey, privateKey});
+    });
+  });
+}
+
+//---------------------------------------------------------------------------
+//  User defined function for reading token and private key values
+//  generated by the OCI SDK.
+//  Returns the OCI SDK's token request details object for the given
+//  config parameters, where a scope parameter specifies the
+//  scope of requested access. The request will specify a public key
+//  as being paired with a private key that the presenter of the token must
+//  prove to be in possession of.
+//---------------------------------------------------------------------------
+async function configFileBasedAuthentication(accessTokenConfig) {
+  const provider =
+    new common.ConfigFileAuthenticationDetailsProvider(accessTokenConfig.configFileLocation, accessTokenConfig.profile);
+  const client = new identitydataplane.DataplaneClient({authenticationDetailsProvider: provider});
+  const keyPair = await _getKeyPair();
+  const generateScopedAccessTokenDetails = {
+    scope: "urn:oracle:db::id::*",
+    publicKey: keyPair.publicKey
+  };
+
+  const generateScopedAccessTokenRequest = {
+    generateScopedAccessTokenDetails: generateScopedAccessTokenDetails
+  };
+  const generateScopedAccessTokenResponse =
+    await client.generateScopedAccessToken(generateScopedAccessTokenRequest);
+  const obj = {
+    token: generateScopedAccessTokenResponse.securityToken.token,
+    privateKey: keyPair.privateKey
+  };
+  return obj;
+}
+
+//---------------------------------------------------------------------------
+// simpleAuthentication()
+//---------------------------------------------------------------------------
+async function simpleAuthentication(accessTokenConfig) {
+  const tenancy = accessTokenConfig.tenancy ??
+    throwErr("Token based authentication config parameter tenancy is missing for simpleauthentication in extensionOci plugins.");
+  const user = accessTokenConfig.user ??
+    throwErr("Token based authentication config parameter user is missing for simpleauthentication in extensionOci plugins.");
+  const fingerprint = accessTokenConfig.fingerprint ??
+    throwErr("Token based authentication config parameter fingerprint is missing for simpleauthentication in extensionOci plugins.");
+  const passphrase = accessTokenConfig.passphrase |= null; // optional
+  const privateKeyLocation = accessTokenConfig.privateKeyLocation ??
+    throwErr("Token based authentication config parameter privateKeyLocation is missing for simpleauthentication in extensionOci plugins.");
+  const privateKey = fs.readFileSync(privateKeyLocation, 'utf-8'); // ~/.oci/oci_api_key.pem
+  const regionId = accessTokenConfig.regionId ??      // ex : us-ashburn-1
+    throwErr("Token based authentication config parameter regionId is missing for simpleauthentication in extensionOci plugins.");
+
+  let region;
+  const regionsList = common.Region.values();
+  regionsList.forEach(regions => {
+    if (regions.regionId === regionId) {
+      region = regions;
+      return;
+    }
+  });
+  const provider = new common.SimpleAuthenticationDetailsProvider(
+    tenancy,
+    user,
+    fingerprint,
+    privateKey,
+    passphrase,
+    region
+  );
+  const client = new identitydataplane.DataplaneClient({
+    authenticationDetailsProvider: provider
+  });
+  const keyPair = await _getKeyPair();
+  const generateScopedAccessTokenDetails = {
+    scope: "urn:oracle:db::id::*",
+    publicKey: keyPair.publicKey
+  };
+  const generateScopedAccessTokenRequest = {
+    generateScopedAccessTokenDetails: generateScopedAccessTokenDetails
+  };
+
+  const generateScopedAccessTokenResponse = await client.generateScopedAccessToken(
+    generateScopedAccessTokenRequest
+  );
+
+  const obj = {
+    token: generateScopedAccessTokenResponse.securityToken.token,
+    privateKey: keyPair.privateKey
+  };
+  return obj;
+}
+
+//---------------------------------------------------------------------------
+//  hookFn()
+//  hookFn will get registerd to driver while loading plugins.
+//---------------------------------------------------------------------------
+function hookFn(options) {
+  if (options.tokenAuthConfigOci) {
+    // eslint-disable-next-line no-unused-vars
+    options.accessToken = async function callbackFn(refresh, config) {
+      return await getToken(config);
+    };
+    options.accessTokenConfig = options.tokenAuthConfigOci;
+  }
+}
+oracledb.registerProcessConfigurationHook(hookFn);

package/build/Release/oracledb-6.7.2-darwin-arm64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.7.2-darwin-arm64.node v22.2.0 d813e9fe939a65599afab84c08ad9fcea51718d5 ca4b004c471033328549f8b4d461cb5985fe2230 Fri, 07 Feb 2025 13:55:05 GMT

package/build/Release/oracledb-6.7.2-darwin-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.7.2-darwin-x64.node v20.11.1 d813e9fe939a65599afab84c08ad9fcea51718d5 ca4b004c471033328549f8b4d461cb5985fe2230 Fri, 07 Feb 2025 14:37:36 GMT

package/build/Release/oracledb-6.7.2-js-buildinfo.txt

@@ -1 +0,0 @@
-d813e9fe939a65599afab84c08ad9fcea51718d5

package/build/Release/oracledb-6.7.2-linux-arm64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.7.2-linux-arm64.node v20.16.0 d813e9fe939a65599afab84c08ad9fcea51718d5 ca4b004c471033328549f8b4d461cb5985fe2230 Fri, 07 Feb 2025 13:48:03 GMT

package/build/Release/oracledb-6.7.2-linux-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.7.2-linux-x64.node v20.16.0 d813e9fe939a65599afab84c08ad9fcea51718d5 ca4b004c471033328549f8b4d461cb5985fe2230 Fri, 07 Feb 2025 13:47:00 GMT

package/build/Release/oracledb-6.7.2-win32-x64.node-buildinfo.txt

@@ -1 +0,0 @@
-oracledb-6.7.2-win32-x64.node v20.0.0 d813e9fe939a65599afab84c08ad9fcea51718d5 ca4b004c471033328549f8b4d461cb5985fe2230 Fri, 07 Feb 2025 13:46:32 GMT