@oracle/langchain-oracledb 0.2.0 → 1.1.0

package/dist/vectorstores.cjs

@@ -3,12 +3,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OracleVS = exports.dropTablePurge = exports.createIndex = exports.createTable = exports.DistanceStrategy = exports.VectorElementFormat = exports.VectorType = exports.generateWhereClause = void 0;
+exports.OracleVS = exports.dropTablePurge = exports.createIndex = exports.createTable = exports.DistanceStrategy = exports.VectorElementFormat = exports.VectorType = exports.generateWhereClause = exports.isLangChainOracleError = exports.OracleVSErrorCode = exports.OracleVSError = exports.ErrorCode = exports.LangChainOracleError = void 0;
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const oracledb_1 = __importDefault(require("oracledb"));
 const vectorstores_1 = require("@langchain/core/vectorstores");
 const documents_1 = require("@langchain/core/documents");
 const math_1 = require("@langchain/core/utils/math");
+const errors_js_1 = require("./errors.cjs");
+Object.defineProperty(exports, "LangChainOracleError", { enumerable: true, get: function () { return errors_js_1.LangChainOracleError; } });
+Object.defineProperty(exports, "OracleVSError", { enumerable: true, get: function () { return errors_js_1.LangChainOracleError; } });
+Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return errors_js_1.ErrorCode; } });
+Object.defineProperty(exports, "OracleVSErrorCode", { enumerable: true, get: function () { return errors_js_1.ErrorCode; } });
+Object.defineProperty(exports, "isLangChainOracleError", { enumerable: true, get: function () { return errors_js_1.isLangChainOracleError; } });
+const utils_js_1 = require("./utils.cjs");
+function validateMetadataKey(column) {
+    const pattern = /^[a-zA-Z0-9_.[\],\s*]*$/;
+    if (!column || !pattern.test(column)) {
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.FILTER_INVALID_METADATA_KEY, column);
+    }
+}
 function generateWhereClause(dbFilter, bindValues) {
     // Handle $and
     if ("$and" in dbFilter && Array.isArray(dbFilter.$and)) {
@@ -44,6 +57,7 @@ function generateWhereClause(dbFilter, bindValues) {
 }
 exports.generateWhereClause = generateWhereClause;
 function generateOperatorCondition(column, operator, value, bindValues) {
+    validateMetadataKey(column);
     switch (operator) {
         case "$eq":
             return jsonCompare(column, "=", value, bindValues);
@@ -58,20 +72,23 @@ function generateOperatorCondition(column, operator, value, bindValues) {
         case "$gte":
             return jsonCompare(column, ">=", value, bindValues);
         case "$in": {
-            if (!Array.isArray(value))
-                throw new Error("$in requires array");
+            if (!Array.isArray(value)) {
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.FILTER_INVALID_VALUE, "$in requires array");
+            }
             const inClauses = value.map((v) => jsonCompare(column, "=", v, bindValues));
             return `(${inClauses.join(" OR ")})`;
         }
         case "$nin": {
-            if (!Array.isArray(value))
-                throw new Error("$nin requires array");
+            if (!Array.isArray(value)) {
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.FILTER_INVALID_VALUE, "$nin requires array");
+            }
             const ninClauses = value.map((v) => jsonCompare(column, "!=", v, bindValues));
             return `(${ninClauses.join(" AND ")})`;
         }
         case "$between": {
-            if (!Array.isArray(value) || value.length !== 2)
-                throw new Error("$between requires [low, high]");
+            if (!Array.isArray(value) || value.length !== 2) {
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.FILTER_INVALID_VALUE, "$between requires [low, high]");
+            }
             const [low, high] = value;
             bindValues.push(low, high);
             const posLow = bindValues.length - 1;
@@ -86,7 +103,7 @@ function generateOperatorCondition(column, operator, value, bindValues) {
                 return `NOT JSON_EXISTS(metadata, '$.${column}')`;
             }
         default:
-            throw new Error(`Unsupported operator: ${operator}`);
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.FILTER_UNSUPPORTED_OPERATOR, operator);
     }
 }
 // Helper: build JSON_EXISTS clause for comparison
@@ -116,42 +133,11 @@ exports.DistanceStrategy = {
     HAMMING: "HAMMING",
     EUCLIDEAN_SQUARED: "EUCLIDEAN_SQUARED",
 };
-function handleError(error) {
-    // Type guard to check if the error is an object and has 'name' and 'message' properties
-    if (typeof error === "object" &&
-        error !== null &&
-        "name" in error &&
-        "message" in error) {
-        const err = error; // Type assertion based on guarded checks
-        // Handle specific error types based on the name property
-        switch (err.name) {
-            case "RuntimeError":
-                throw new Error("Database operation failed due to a runtime error.");
-            case "ValidationError":
-                throw new Error("Operation failed due to a validation error.");
-            default:
-                throw new Error(`An unexpected error occurred during the operation. ${error}`);
-        }
-    }
-    throw new Error(`An unknown and unexpected error occurred. ${error}`);
-}
 function isPool(client) {
     return "getConnection" in client;
 }
-function quoteIdentifier(identifier) {
-    const name = identifier.trim();
-    const validateRegex = /^(?:"[^"]+"|[^".]+)(?:\.(?:"[^"]+"|[^".]+))*$/;
-    if (!validateRegex.test(name)) {
-        throw new Error(`Identifier name ${identifier} is not valid.`);
-    }
-    // extracts parts of the identifier with quoted and unquoted.
-    const matchRegex = /"([^"]+)"|([^".]+)/g;
-    const groups = [];
-    for (const match of name.matchAll(matchRegex)) {
-        groups.push(match[1] || match[2]);
-    }
-    const quotedParts = groups.map((g) => `"${g}"`);
-    return quotedParts.join(".");
+function isClientProvider(client) {
+    return typeof client === "function";
 }
 const isFloat32Array = (value) => 
 // eslint-disable-next-line no-instanceof/no-instanceof
@@ -186,25 +172,26 @@ function normalizeVectorFormat(value, vectorType) {
     const format = validFormats.includes(normalizedValue)
         ? normalizedValue
         : exports.VectorElementFormat.FLOAT32;
-    if (vectorType === exports.VectorType.SPARSE && format === exports.VectorElementFormat.BINARY) {
-        throw new Error("BINARY format is not supported for SPARSE vectors.");
+    if (vectorType === exports.VectorType.SPARSE &&
+        format === exports.VectorElementFormat.BINARY) {
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_CONFIGURATION, "BINARY format is not supported for SPARSE vectors.");
     }
     return format;
 }
 function buildVectorColumnDefinition(embeddingDim, customization) {
     if (embeddingDim === undefined || embeddingDim === null) {
-        throw new Error("Embedding dimension is required to create the vector column.");
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_CONFIGURATION, "Embedding dimension is required to create the vector column.");
     }
     if (!Number.isInteger(embeddingDim) || embeddingDim <= 0) {
-        throw new Error("Embedding dimension must be a positive integer.");
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_CONFIGURATION, "Embedding dimension must be a positive integer.");
     }
     const vectorType = normalizeVectorTypeValue(customization?.vectorType);
     if (vectorType === exports.VectorType.SPARSE && customization?.format === undefined) {
-        throw new Error("Sparse vector type requires a vector format to be specified.");
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_CONFIGURATION, "Sparse vector type requires a vector format to be specified.");
     }
     const format = normalizeVectorFormat(customization?.format, vectorType);
     if (format === exports.VectorElementFormat.BINARY && embeddingDim % 8 !== 0) {
-        throw new Error("BINARY vector format requires dimensions to be a multiple of 8.");
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_CONFIGURATION, "BINARY vector format requires dimensions to be a multiple of 8.");
     }
     const dimensionSegment = String(embeddingDim);
     const formatSegment = format ?? exports.VectorElementFormat.FLOAT32;
@@ -220,7 +207,7 @@ function escapePlSqlLiteral(sql) {
     return sql.replace(/'/g, "''");
 }
 async function createTable(connection, tableName, embeddingDim, customization) {
-    const tableIdentifier = quoteIdentifier(tableName);
+    const tableIdentifier = (0, utils_js_1.quoteIdentifier)(tableName);
     const colsDict = {
         id: "RAW(16) DEFAULT SYS_GUID() PRIMARY KEY",
         external_id: `VARCHAR2(36) UNIQUE`,
@@ -252,7 +239,7 @@ async function createTable(connection, tableName, embeddingDim, customization) {
                 const columnKey = columnName.trim().toLowerCase();
                 if (!(columnKey in colsDict))
                     continue;
-                const normalizedColumnIdentifier = `${tableIdentifier}.${quoteIdentifier(columnKey.toUpperCase())}`;
+                const normalizedColumnIdentifier = `${tableIdentifier}.${(0, utils_js_1.quoteIdentifier)(columnKey.toUpperCase())}`;
                 const escapedNote = escapeCommentText(trimmedNote);
                 statements.push(`EXECUTE IMMEDIATE 'COMMENT ON COLUMN ${normalizedColumnIdentifier} IS ''${escapedNote}''';`);
             }
@@ -261,7 +248,7 @@ async function createTable(connection, tableName, embeddingDim, customization) {
         await connection.execute(block);
     }
     catch (error) {
-        handleError(error);
+        (0, errors_js_1.handleError)(error);
     }
 }
 exports.createTable = createTable;
@@ -296,7 +283,7 @@ function convertDenseVectorForFormat(values, format) {
             for (let i = 0; i < values.length; i += 1) {
                 const rounded = Math.round(values[i]);
                 if (rounded < -128 || rounded > 127) {
-                    throw new Error("INT8 vector values must be within [-128, 127].");
+                    (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_VALUE, "INT8 vector values must be within [-128, 127].");
                 }
                 clamped[i] = rounded;
             }
@@ -336,10 +323,10 @@ async function createHNSWIndex(connection, oraclevs, params = {}) {
         const { idxName = _getIndexName("HNSW"), idxType = "HNSW", neighbors = 32, efConstruction = 200, accuracy = 90, parallel = 8, ...extra } = params;
         const invalidKeys = Object.keys(extra);
         if (invalidKeys.length > 0) {
-            throw new Error(`Invalid parameter(s): ${invalidKeys.join(", ")}`);
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_INDEX_PARAMETERS, invalidKeys);
         }
         const ddl = `
-      CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
+      CREATE VECTOR INDEX IF NOT EXISTS ${(0, utils_js_1.quoteIdentifier)(idxName)}
       ON ${oraclevs.tableName}(embedding)
       ORGANIZATION INMEMORY NEIGHBOR GRAPH
       WITH TARGET ACCURACY ${accuracy}
@@ -352,7 +339,7 @@ async function createHNSWIndex(connection, oraclevs, params = {}) {
         await connection.execute(ddl);
     }
     catch (error) {
-        handleError(error);
+        (0, errors_js_1.handleError)(error);
     }
 }
 async function createIVFIndex(connection, oraclevs, params = {}) {
@@ -360,10 +347,10 @@ async function createIVFIndex(connection, oraclevs, params = {}) {
         const { idxName = _getIndexName("IVF"), idxType = "IVF", neighborPart = 32, accuracy = 90, parallel = 8, ...extra } = params;
         const invalidKeys = Object.keys(extra);
         if (invalidKeys.length > 0) {
-            throw new Error(`Invalid parameter(s): ${invalidKeys.join(", ")}`);
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_INDEX_PARAMETERS, invalidKeys);
         }
         const ddl = `
-      CREATE VECTOR INDEX IF NOT EXISTS ${quoteIdentifier(idxName)}
+      CREATE VECTOR INDEX IF NOT EXISTS ${(0, utils_js_1.quoteIdentifier)(idxName)}
       ON ${oraclevs.tableName}(embedding)
       ORGANIZATION NEIGHBOR PARTITIONS
       WITH TARGET ACCURACY ${accuracy}
@@ -376,16 +363,16 @@ async function createIVFIndex(connection, oraclevs, params = {}) {
         await connection.execute(ddl);
     }
     catch (error) {
-        handleError(error);
+        (0, errors_js_1.handleError)(error);
     }
 }
 async function dropTablePurge(connection, tableName) {
     try {
-        const ddl = `DROP TABLE IF EXISTS ${quoteIdentifier(tableName)} PURGE`;
+        const ddl = `DROP TABLE IF EXISTS ${(0, utils_js_1.quoteIdentifier)(tableName)} PURGE`;
         await connection.execute(ddl);
     }
     catch (error) {
-        handleError(error);
+        (0, errors_js_1.handleError)(error);
     }
 }
 exports.dropTablePurge = dropTablePurge;
@@ -401,6 +388,14 @@ class OracleVS extends vectorstores_1.VectorStore {
             writable: true,
             value: void 0
         });
+        // Tracks connections borrowed from a pool so retConnection() can return them
+        // without closing direct connections owned by the caller.
+        Object.defineProperty(this, "poolConnections", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new WeakSet()
+        });
         Object.defineProperty(this, "embeddingDimension", {
             enumerable: true,
             configurable: true,
@@ -457,7 +452,7 @@ class OracleVS extends vectorstores_1.VectorStore {
         });
         try {
             this.client = dbConfig.client;
-            this.tableName = quoteIdentifier(dbConfig.tableName);
+            this.tableName = (0, utils_js_1.quoteIdentifier)(dbConfig.tableName);
             this.distanceStrategy =
                 dbConfig.distanceStrategy ?? this.distanceStrategy;
             this.query = dbConfig.query;
@@ -470,20 +465,24 @@ class OracleVS extends vectorstores_1.VectorStore {
             this.vectorFormat = dbConfig.format;
         }
         catch (error) {
-            handleError(error);
+            (0, errors_js_1.handleError)(error);
         }
     }
     getActiveVectorType() {
-        return this.vectorType ? normalizeVectorTypeValue(this.vectorType) : exports.VectorType.DENSE;
+        return this.vectorType
+            ? normalizeVectorTypeValue(this.vectorType)
+            : exports.VectorType.DENSE;
     }
     ensureEmbeddingDimension() {
-        if (this.embeddingDimension === undefined || this.embeddingDimension === null) {
-            throw new Error("Embedding dimension is not initialized for this vector store.");
+        if (this.embeddingDimension === undefined ||
+            this.embeddingDimension === null) {
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.STATE_INVALID, "Embedding dimension is not initialized for this vector store.");
         }
         return this.embeddingDimension;
     }
     prepareVectorForStorage(vector) {
-        if (this.embeddingDimension === undefined || this.embeddingDimension === null) {
+        if (this.embeddingDimension === undefined ||
+            this.embeddingDimension === null) {
             this.embeddingDimension = vector.length;
         }
         const dimension = this.ensureEmbeddingDimension();
@@ -493,30 +492,63 @@ class OracleVS extends vectorstores_1.VectorStore {
             : exports.VectorElementFormat.FLOAT32;
         if (vectorType === exports.VectorType.SPARSE) {
             if (vector.length !== dimension) {
-                throw new Error("Sparse vectors must supply full-dimension arrays for conversion.");
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_VALUE, "Sparse vectors must supply full-dimension arrays for conversion.");
             }
-            let sparseInput = vector;
+            // The dense-input SparseVector constructor stores its values as a
+            // Float64Array regardless of the typed array passed in, so FLOAT32 and
+            // INT8 query vectors reach the database as FLOAT64 and VECTOR_DISTANCE()
+            // fails with ORA-51812 against a non-FLOAT64 sparse column. The
+            // object-form constructor preserves the values' typed array, so build
+            // the nonzero indices/values explicitly and use that form.
+            const indices = [];
+            const nonzero = [];
             if (format === exports.VectorElementFormat.INT8) {
-                const clamped = new Int8Array(vector.length);
                 for (let i = 0; i < vector.length; i += 1) {
-                    const rounded = Math.round(vector[i]);
-                    if (rounded < -128 || rounded > 127) {
-                        throw new Error("INT8 sparse vector values must be within [-128, 127].");
+                    const value = vector[i];
+                    const rounded = Math.round(value);
+                    if (!Number.isFinite(value) || rounded < -128 || rounded > 127) {
+                        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_VALUE, "INT8 sparse vector values must be finite and within [-128, 127].");
+                    }
+                    if (rounded !== 0) {
+                        indices.push(i);
+                        nonzero.push(rounded);
+                    }
+                }
+            }
+            else if (format === exports.VectorElementFormat.FLOAT32) {
+                for (let i = 0; i < vector.length; i += 1) {
+                    if (Math.fround(vector[i]) !== 0) {
+                        indices.push(i);
+                        nonzero.push(vector[i]);
                     }
-                    clamped[i] = rounded;
                 }
-                sparseInput = clamped;
+            }
+            else {
+                for (let i = 0; i < vector.length; i += 1) {
+                    if (vector[i] !== 0) {
+                        indices.push(i);
+                        nonzero.push(vector[i]);
+                    }
+                }
+            }
+            let values;
+            if (format === exports.VectorElementFormat.INT8) {
+                values = new Int8Array(nonzero);
             }
             else if (format === exports.VectorElementFormat.FLOAT64) {
-                sparseInput = new Float64Array(vector);
+                values = new Float64Array(nonzero);
             }
-            else if (format === exports.VectorElementFormat.FLOAT32) {
-                sparseInput = new Float32Array(vector);
+            else {
+                values = new Float32Array(nonzero);
             }
-            return new oracledb_1.default.SparseVector(sparseInput);
+            return new oracledb_1.default.SparseVector({
+                values,
+                indices: new Uint32Array(indices),
+                numDimensions: vector.length,
+            });
         }
         if (vector.length !== dimension) {
-            throw new Error("Vector length does not match the embedding dimension.");
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_INVALID_VALUE, "Vector length does not match the embedding dimension.");
         }
         return convertDenseVectorForFormat(vector, format);
     }
@@ -529,7 +561,7 @@ class OracleVS extends vectorstores_1.VectorStore {
         if (isSparseVector(value)) {
             const dense = value.dense?.();
             if (!dense) {
-                throw new Error("Unable to expand sparse vector to dense representation.");
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_UNSUPPORTED_REPRESENTATION, "Unable to expand sparse vector to dense representation.");
             }
             if (isFloat32Array(dense)) {
                 return dense;
@@ -545,13 +577,16 @@ class OracleVS extends vectorstores_1.VectorStore {
             }
             return Float32Array.from(dense);
         }
-        if (isFloat32Array(value) || isFloat64Array(value) || isInt8Array(value) || isUint8Array(value)) {
+        if (isFloat32Array(value) ||
+            isFloat64Array(value) ||
+            isInt8Array(value) ||
+            isUint8Array(value)) {
             return value;
         }
         if (Array.isArray(value)) {
             return value;
         }
-        throw new Error("Received unsupported vector representation from the database.");
+        (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VECTOR_UNSUPPORTED_REPRESENTATION, "Received unsupported vector representation from the database.");
     }
     // Normalizes any supported vector representation into Float32Array so downstream math
     // (MMR, distance calculations) can assume a consistent element type without forcing
@@ -589,34 +624,41 @@ class OracleVS extends vectorstores_1.VectorStore {
                 description: this.description,
                 annotations: this.annotations,
                 vectorType: this.vectorType,
-                format: this.vectorFormat
+                format: this.vectorFormat,
             });
         }
         catch (error) {
-            handleError(error);
+            (0, errors_js_1.handleError)(error);
         }
         finally {
             if (connection)
                 await this.retConnection(connection);
         }
     }
+    async resolveClient() {
+        return isClientProvider(this.client) ? await this.client() : this.client;
+    }
     async getConnection() {
         try {
-            if (isPool(this.client)) {
-                return await this.client.getConnection();
+            const client = await this.resolveClient();
+            if (isPool(client)) {
+                const connection = await client.getConnection();
+                this.poolConnections.add(connection);
+                return connection;
             }
-            return this.client;
+            return client;
         }
         catch (error) {
-            handleError(error);
+            (0, errors_js_1.handleError)(error);
         }
     }
     // Close connection or return it to the pool
     async retConnection(connection) {
         try {
-            // If the client is a pool, close the connection (return it to the pool)
-            if (isPool(this.client)) {
+            // If this public connection came from any pool, close it to return it to the pool.
+            if (this.poolConnections.has(connection)) {
                 await connection.close();
+                this.poolConnections.delete(connection);
             }
         }
         catch (error) {
@@ -634,16 +676,15 @@ class OracleVS extends vectorstores_1.VectorStore {
      */
     async addVectors(vectors, documents, options) {
         if (vectors.length === 0) {
-            throw new Error("Vectors input null. Nothing to add...");
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VALIDATION_INVALID_INPUT, "Vectors input null. Nothing to add...");
         }
         const inputIds = options?.ids;
         let connection = null;
         try {
             // Ensure there are IDs for all documents
             if (inputIds !== undefined && inputIds.length !== vectors.length) {
-                throw new Error("The number of ids must match the number of vectors provided.");
+                (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VALIDATION_INVALID_INPUT, "The number of ids must match the number of vectors provided.");
             }
-            connection = await this.getConnection();
             const finalIds = [];
             const binds = [];
             for (let index = 0; index < documents.length; index += 1) {
@@ -689,13 +730,14 @@ class OracleVS extends vectorstores_1.VectorStore {
                 },
                 autoCommit: false,
             };
+            connection = await this.getConnection();
             await connection.executeMany(sql, binds, executeOptions);
             // Commit once all inserts are queued up
             await connection.commit();
             return finalIds;
         }
         catch (error) {
-            return handleError(error);
+            return (0, errors_js_1.handleError)(error);
         }
         finally {
             if (connection) {
@@ -719,14 +761,22 @@ class OracleVS extends vectorstores_1.VectorStore {
         let connection = null;
         try {
             const bindValues = [this.prepareQueryVector(query)];
+            const hasFilter = !!filter && Object.keys(filter).length > 0;
+            // Keep the vector index hint for unfiltered searches. When a JSON filter
+            // is present, forcing VECTOR_INDEX_TRANSFORM can change result semantics
+            // by doing approximate top-k before the filter is applied.
+            const selectClause = hasFilter
+                ? "SELECT"
+                : `SELECT /*+ VECTOR_INDEX_TRANSFORM(${this.tableName}) */`;
             let sqlQuery = `
-      SELECT external_id,
+      ${selectClause}
+        external_id,
         text,
         metadata,
         vector_distance(embedding, :1, ${this.distanceStrategy}) as distance,
         embedding
       FROM ${this.tableName} `;
-            if (filter && Object.keys(filter).length > 0) {
+            if (hasFilter) {
                 sqlQuery += ` WHERE ${generateWhereClause(filter, bindValues)}`;
             }
             bindValues.push(k);
@@ -754,14 +804,10 @@ class OracleVS extends vectorstores_1.VectorStore {
                     docsScoresAndEmbeddings.push([document, distance, embedding]);
                 }
             }
-            else {
-                // Throw an exception if no rows are found
-                throw new Error("No rows found.");
-            }
         }
         finally {
             if (connection) {
-                await connection.close();
+                await this.retConnection(connection);
             }
         }
         return docsScoresAndEmbeddings;
@@ -839,17 +885,19 @@ class OracleVS extends vectorstores_1.VectorStore {
             }
         }
         catch (error) {
-            handleError(error);
+            (0, errors_js_1.handleError)(error);
         }
         finally {
-            if (connection)
-                await connection.close();
+            if (connection) {
+                await this.retConnection(connection);
+            }
         }
     }
     static async fromDocuments(documents, embeddings, dbConfig, options) {
         const { client } = dbConfig;
-        if (!client)
-            throw new Error("client parameter is required...");
+        if (!client) {
+            (0, errors_js_1.throwError)(errors_js_1.ErrorCode.VALIDATION_MISSING_REQUIRED_PARAMETER, "client");
+        }
         try {
             const vss = new OracleVS(embeddings, dbConfig);
             await vss.initialize();
@@ -860,7 +908,7 @@ class OracleVS extends vectorstores_1.VectorStore {
             return vss;
         }
         catch (error) {
-            handleError(error);
+            (0, errors_js_1.handleError)(error);
         }
     }
     /**
@@ -869,8 +917,8 @@ class OracleVS extends vectorstores_1.VectorStore {
      * inside the pool are terminated.
      */
     async end() {
-        if (isPool(this.client)) {
-            await this.client?.close();
+        if (!isClientProvider(this.client) && isPool(this.client)) {
+            await this.client.close();
         }
     }
 }