@mastra/couchbase 0.10.3 → 0.11.0-alpha.1

package/dist/index.js

@@ -1,3 +1,4 @@
+import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import { MastraVector } from '@mastra/core/vector';
 import { connect, SearchRequest, VectorSearch, VectorQuery, MutateInSpec } from 'couchbase';
 
@@ -19,26 +20,45 @@ var CouchbaseVector = class extends MastraVector {
   vector_dimension;
   constructor({ connectionString, username, password, bucketName, scopeName, collectionName }) {
     super();
-    const baseClusterPromise = connect(connectionString, {
-      username,
-      password,
-      configProfile: "wanDevelopment"
-    });
-    const telemetry = this.__getTelemetry();
-    this.clusterPromise = telemetry?.traceClass(baseClusterPromise, {
-      spanNamePrefix: "couchbase-vector",
-      attributes: {
-        "vector.type": "couchbase"
-      }
-    }) ?? baseClusterPromise;
-    this.cluster = null;
-    this.bucketName = bucketName;
-    this.collectionName = collectionName;
-    this.scopeName = scopeName;
-    this.collection = null;
-    this.bucket = null;
-    this.scope = null;
-    this.vector_dimension = null;
+    try {
+      const baseClusterPromise = connect(connectionString, {
+        username,
+        password,
+        configProfile: "wanDevelopment"
+      });
+      const telemetry = this.__getTelemetry();
+      this.clusterPromise = telemetry?.traceClass(baseClusterPromise, {
+        spanNamePrefix: "couchbase-vector",
+        attributes: {
+          "vector.type": "couchbase"
+        }
+      }) ?? baseClusterPromise;
+      this.cluster = null;
+      this.bucketName = bucketName;
+      this.collectionName = collectionName;
+      this.scopeName = scopeName;
+      this.collection = null;
+      this.bucket = null;
+      this.scope = null;
+      this.vector_dimension = null;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_INITIALIZE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            connectionString,
+            username,
+            password,
+            bucketName,
+            scopeName,
+            collectionName
+          }
+        },
+        error
+      );
+    }
   }
   async getCollection() {
     if (!this.cluster) {
@@ -52,11 +72,11 @@ var CouchbaseVector = class extends MastraVector {
     return this.collection;
   }
   async createIndex({ indexName, dimension, metric = "dotproduct" }) {
-    await this.getCollection();
-    if (!Number.isInteger(dimension) || dimension <= 0) {
-      throw new Error("Dimension must be a positive integer");
-    }
     try {
+      await this.getCollection();
+      if (!Number.isInteger(dimension) || dimension <= 0) {
+        throw new Error("Dimension must be a positive integer");
+      }
       await this.scope.searchIndexes().upsertIndex({
         name: indexName,
         sourceName: this.bucketName,
@@ -143,78 +163,129 @@ var CouchbaseVector = class extends MastraVector {
         await this.validateExistingIndex(indexName, dimension, metric);
         return;
       }
-      throw error;
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_CREATE_INDEX_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName,
+            dimension,
+            metric
+          }
+        },
+        error
+      );
     }
   }
   async upsert({ vectors, metadata, ids }) {
-    await this.getCollection();
-    if (!vectors || vectors.length === 0) {
-      throw new Error("No vectors provided");
-    }
-    if (this.vector_dimension) {
-      for (const vector of vectors) {
-        if (!vector || this.vector_dimension !== vector.length) {
-          throw new Error("Vector dimension mismatch");
+    try {
+      await this.getCollection();
+      if (!vectors || vectors.length === 0) {
+        throw new Error("No vectors provided");
+      }
+      if (this.vector_dimension) {
+        for (const vector of vectors) {
+          if (!vector || this.vector_dimension !== vector.length) {
+            throw new Error("Vector dimension mismatch");
+          }
         }
       }
-    }
-    const pointIds = ids || vectors.map(() => crypto.randomUUID());
-    const records = vectors.map((vector, i) => {
-      const metadataObj = metadata?.[i] || {};
-      const record = {
-        embedding: vector,
-        metadata: metadataObj
-      };
-      if (metadataObj.text) {
-        record.content = metadataObj.text;
+      const pointIds = ids || vectors.map(() => crypto.randomUUID());
+      const records = vectors.map((vector, i) => {
+        const metadataObj = metadata?.[i] || {};
+        const record = {
+          embedding: vector,
+          metadata: metadataObj
+        };
+        if (metadataObj.text) {
+          record.content = metadataObj.text;
+        }
+        return record;
+      });
+      const allPromises = [];
+      for (let i = 0; i < records.length; i++) {
+        allPromises.push(this.collection.upsert(pointIds[i], records[i]));
       }
-      return record;
-    });
-    const allPromises = [];
-    for (let i = 0; i < records.length; i++) {
-      allPromises.push(this.collection.upsert(pointIds[i], records[i]));
+      await Promise.all(allPromises);
+      return pointIds;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_UPSERT_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
     }
-    await Promise.all(allPromises);
-    return pointIds;
   }
   async query({ indexName, queryVector, topK = 10, includeVector = false }) {
-    await this.getCollection();
-    const index_stats = await this.describeIndex({ indexName });
-    if (queryVector.length !== index_stats.dimension) {
-      throw new Error(`Query vector dimension mismatch. Expected ${index_stats.dimension}, got ${queryVector.length}`);
-    }
-    let request = SearchRequest.create(
-      VectorSearch.fromVectorQuery(VectorQuery.create("embedding", queryVector).numCandidates(topK))
-    );
-    const results = await this.scope.search(indexName, request, {
-      fields: ["*"]
-    });
-    if (includeVector) {
-      throw new Error("Including vectors in search results is not yet supported by the Couchbase vector store");
-    }
-    const output = [];
-    for (const match of results.rows) {
-      const cleanedMetadata = {};
-      const fields = match.fields || {};
-      for (const key in fields) {
-        if (Object.prototype.hasOwnProperty.call(fields, key)) {
-          const newKey = key.startsWith("metadata.") ? key.substring("metadata.".length) : key;
-          cleanedMetadata[newKey] = fields[key];
-        }
+    try {
+      await this.getCollection();
+      const index_stats = await this.describeIndex({ indexName });
+      if (queryVector.length !== index_stats.dimension) {
+        throw new Error(
+          `Query vector dimension mismatch. Expected ${index_stats.dimension}, got ${queryVector.length}`
+        );
       }
-      output.push({
-        id: match.id,
-        score: match.score || 0,
-        metadata: cleanedMetadata
-        // Use the cleaned metadata object
+      let request = SearchRequest.create(
+        VectorSearch.fromVectorQuery(VectorQuery.create("embedding", queryVector).numCandidates(topK))
+      );
+      const results = await this.scope.search(indexName, request, {
+        fields: ["*"]
       });
+      if (includeVector) {
+        throw new Error("Including vectors in search results is not yet supported by the Couchbase vector store");
+      }
+      const output = [];
+      for (const match of results.rows) {
+        const cleanedMetadata = {};
+        const fields = match.fields || {};
+        for (const key in fields) {
+          if (Object.prototype.hasOwnProperty.call(fields, key)) {
+            const newKey = key.startsWith("metadata.") ? key.substring("metadata.".length) : key;
+            cleanedMetadata[newKey] = fields[key];
+          }
+        }
+        output.push({
+          id: match.id,
+          score: match.score || 0,
+          metadata: cleanedMetadata
+          // Use the cleaned metadata object
+        });
+      }
+      return output;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_QUERY_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName,
+            topK
+          }
+        },
+        error
+      );
     }
-    return output;
   }
   async listIndexes() {
-    await this.getCollection();
-    const indexes = await this.scope.searchIndexes().getAllIndexes();
-    return indexes?.map((index) => index.name) || [];
+    try {
+      await this.getCollection();
+      const indexes = await this.scope.searchIndexes().getAllIndexes();
+      return indexes?.map((index) => index.name) || [];
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_LIST_INDEXES_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
   }
   /**
    * Retrieves statistics about a vector index.
@@ -223,29 +294,60 @@ var CouchbaseVector = class extends MastraVector {
    * @returns A promise that resolves to the index statistics including dimension, count and metric
    */
   async describeIndex({ indexName }) {
-    await this.getCollection();
-    if (!(await this.listIndexes()).includes(indexName)) {
-      throw new Error(`Index ${indexName} does not exist`);
+    try {
+      await this.getCollection();
+      if (!(await this.listIndexes()).includes(indexName)) {
+        throw new Error(`Index ${indexName} does not exist`);
+      }
+      const index = await this.scope.searchIndexes().getIndex(indexName);
+      const dimensions = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.dims;
+      const count = -1;
+      const metric = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.similarity;
+      return {
+        dimension: dimensions,
+        count,
+        metric: Object.keys(DISTANCE_MAPPING).find(
+          (key) => DISTANCE_MAPPING[key] === metric
+        )
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_DESCRIBE_INDEX_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName
+          }
+        },
+        error
+      );
     }
-    const index = await this.scope.searchIndexes().getIndex(indexName);
-    const dimensions = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.dims;
-    const count = -1;
-    const metric = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.similarity;
-    return {
-      dimension: dimensions,
-      count,
-      metric: Object.keys(DISTANCE_MAPPING).find(
-        (key) => DISTANCE_MAPPING[key] === metric
-      )
-    };
   }
   async deleteIndex({ indexName }) {
-    await this.getCollection();
-    if (!(await this.listIndexes()).includes(indexName)) {
-      throw new Error(`Index ${indexName} does not exist`);
+    try {
+      await this.getCollection();
+      if (!(await this.listIndexes()).includes(indexName)) {
+        throw new Error(`Index ${indexName} does not exist`);
+      }
+      await this.scope.searchIndexes().dropIndex(indexName);
+      this.vector_dimension = null;
+    } catch (error) {
+      if (error instanceof MastraError) {
+        throw error;
+      }
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_DELETE_INDEX_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName
+          }
+        },
+        error
+      );
     }
-    await this.scope.searchIndexes().dropIndex(indexName);
-    this.vector_dimension = null;
   }
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
@@ -258,25 +360,41 @@ var CouchbaseVector = class extends MastraVector {
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
   async updateVector({ id, update }) {
-    if (!update.vector && !update.metadata) {
-      throw new Error("No updates provided");
-    }
-    if (update.vector && this.vector_dimension && update.vector.length !== this.vector_dimension) {
-      throw new Error("Vector dimension mismatch");
-    }
-    const collection = await this.getCollection();
     try {
-      await collection.get(id);
-    } catch (err) {
-      if (err.code === 13 || err.message?.includes("document not found")) {
-        throw new Error(`Vector with id ${id} does not exist`);
+      if (!update.vector && !update.metadata) {
+        throw new Error("No updates provided");
       }
-      throw err;
+      if (update.vector && this.vector_dimension && update.vector.length !== this.vector_dimension) {
+        throw new Error("Vector dimension mismatch");
+      }
+      const collection = await this.getCollection();
+      try {
+        await collection.get(id);
+      } catch (err) {
+        if (err.code === 13 || err.message?.includes("document not found")) {
+          throw new Error(`Vector with id ${id} does not exist`);
+        }
+        throw err;
+      }
+      const specs = [];
+      if (update.vector) specs.push(MutateInSpec.replace("embedding", update.vector));
+      if (update.metadata) specs.push(MutateInSpec.replace("metadata", update.metadata));
+      await collection.mutateIn(id, specs);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_UPDATE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            id,
+            hasVectorUpdate: !!update.vector,
+            hasMetadataUpdate: !!update.metadata
+          }
+        },
+        error
+      );
     }
-    const specs = [];
-    if (update.vector) specs.push(MutateInSpec.replace("embedding", update.vector));
-    if (update.metadata) specs.push(MutateInSpec.replace("metadata", update.metadata));
-    await collection.mutateIn(id, specs);
   }
   /**
    * Deletes a vector by its ID.
@@ -286,22 +404,47 @@ var CouchbaseVector = class extends MastraVector {
    * @throws Will throw an error if the deletion operation fails.
    */
   async deleteVector({ id }) {
-    const collection = await this.getCollection();
     try {
-      await collection.get(id);
-    } catch (err) {
-      if (err.code === 13 || err.message?.includes("document not found")) {
-        throw new Error(`Vector with id ${id} does not exist`);
+      const collection = await this.getCollection();
+      try {
+        await collection.get(id);
+      } catch (err) {
+        if (err.code === 13 || err.message?.includes("document not found")) {
+          throw new Error(`Vector with id ${id} does not exist`);
+        }
+        throw err;
       }
-      throw err;
+      await collection.remove(id);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_DELETE_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: {
+            id
+          }
+        },
+        error
+      );
     }
-    await collection.remove(id);
   }
   async disconnect() {
-    if (!this.cluster) {
-      return;
+    try {
+      if (!this.cluster) {
+        return;
+      }
+      await this.cluster.close();
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: "COUCHBASE_VECTOR_DISCONNECT_FAILED",
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
     }
-    await this.cluster.close();
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/couchbase",
-  "version": "0.10.3",
+  "version": "0.11.0-alpha.1",
   "description": "Couchbase vector store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -26,16 +26,16 @@
     "@types/node": "^20.19.0",
     "@vitest/coverage-v8": "3.2.3",
     "@vitest/ui": "3.2.3",
-    "axios": "^1.9.0",
-    "eslint": "^9.28.0",
+    "axios": "^1.10.0",
+    "eslint": "^9.29.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
     "@internal/lint": "0.0.13",
-    "@mastra/core": "0.10.6"
+    "@mastra/core": "0.10.7-alpha.3"
   },
   "peerDependencies": {
-    "@mastra/core": ">=0.10.4-0 <0.11.0"
+    "@mastra/core": ">=0.10.7-0 <0.11.0-0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",