@mastra/opensearch 0.0.0-working-memory-per-user-20250620161509 → 0.0.0-zod-v4-compat-part-2-20250820135355

package/src/vector/index.ts

@@ -9,10 +9,11 @@ import type {
   UpdateVectorParams,
   UpsertVectorParams,
 } from '@mastra/core';
+import { MastraError, ErrorDomain, ErrorCategory } from '@mastra/core/error';
 import { MastraVector } from '@mastra/core/vector';
-import type { VectorFilter } from '@mastra/core/vector/filter';
 import { Client as OpenSearchClient } from '@opensearch-project/opensearch';
 import { OpenSearchFilterTranslator } from './filter';
+import type { OpenSearchVectorFilter } from './filter';
 
 const METRIC_MAPPING = {
   cosine: 'cosinesimil',
@@ -26,7 +27,9 @@ const REVERSE_METRIC_MAPPING = {
   innerproduct: 'dotproduct',
 } as const;
 
-export class OpenSearchVector extends MastraVector {
+type OpenSearchVectorParams = QueryVectorParams<OpenSearchVectorFilter>;
+
+export class OpenSearchVector extends MastraVector<OpenSearchVectorFilter> {
   private client: OpenSearchClient;
 
   /**
@@ -49,7 +52,13 @@ export class OpenSearchVector extends MastraVector {
    */
   async createIndex({ indexName, dimension, metric = 'cosine' }: CreateIndexParams): Promise<void> {
     if (!Number.isInteger(dimension) || dimension <= 0) {
-      throw new Error('Dimension must be a positive integer');
+      throw new MastraError({
+        id: 'STORAGE_OPENSEARCH_VECTOR_CREATE_INDEX_INVALID_ARGS',
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        text: 'Dimension must be a positive integer',
+        details: { indexName, dimension },
+      });
     }
 
     try {
@@ -82,8 +91,15 @@ export class OpenSearchVector extends MastraVector {
         await this.validateExistingIndex(indexName, dimension, metric);
         return;
       }
-      console.error(`Failed to create index ${indexName}:`, error);
-      throw error;
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_CREATE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, dimension, metric },
+        },
+        error,
+      );
     }
   }
 
@@ -100,9 +116,15 @@ export class OpenSearchVector extends MastraVector {
         .filter((index: string | undefined) => index !== undefined);
 
       return indexes;
-    } catch (error: any) {
-      console.error('Failed to list indexes:', error);
-      throw new Error(`Failed to list indexes: ${error.message}`);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_LIST_INDEXES_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
     }
   }
 
@@ -137,7 +159,17 @@ export class OpenSearchVector extends MastraVector {
     try {
       await this.client.indices.delete({ index: indexName });
     } catch (error) {
-      console.error(`Failed to delete index ${indexName}:`, error);
+      const mastraError = new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_DELETE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName },
+        },
+        error,
+      );
+      this.logger?.error(mastraError.toString());
+      this.logger?.trackException(mastraError);
     }
   }
 
@@ -154,39 +186,46 @@ export class OpenSearchVector extends MastraVector {
     const vectorIds = ids || vectors.map(() => crypto.randomUUID());
     const operations = [];
 
-    // Get index stats to check dimension
-    const indexInfo = await this.describeIndex({ indexName });
+    try {
+      // Get index stats to check dimension
+      const indexInfo = await this.describeIndex({ indexName });
 
-    // Validate vector dimensions
-    this.validateVectorDimensions(vectors, indexInfo.dimension);
+      // Validate vector dimensions
+      this.validateVectorDimensions(vectors, indexInfo.dimension);
 
-    for (let i = 0; i < vectors.length; i++) {
-      const operation = {
-        index: {
-          _index: indexName,
-          _id: vectorIds[i],
-        },
-      };
+      for (let i = 0; i < vectors.length; i++) {
+        const operation = {
+          index: {
+            _index: indexName,
+            _id: vectorIds[i],
+          },
+        };
 
-      const document = {
-        id: vectorIds[i],
-        embedding: vectors[i],
-        metadata: metadata[i] || {},
-      };
+        const document = {
+          id: vectorIds[i],
+          embedding: vectors[i],
+          metadata: metadata[i] || {},
+        };
 
-      operations.push(operation);
-      operations.push(document);
-    }
+        operations.push(operation);
+        operations.push(document);
+      }
 
-    try {
       if (operations.length > 0) {
         await this.client.bulk({ body: operations, refresh: true });
       }
 
       return vectorIds;
     } catch (error) {
-      console.error('Failed to upsert vectors:', error);
-      throw error;
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_UPSERT_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, vectorCount: vectors?.length || 0 },
+        },
+        error,
+      );
     }
   }
 
@@ -206,7 +245,7 @@ export class OpenSearchVector extends MastraVector {
     filter,
     topK = 10,
     includeVector = false,
-  }: QueryVectorParams): Promise<QueryResult[]> {
+  }: OpenSearchVectorParams): Promise<QueryResult[]> {
     try {
       const translatedFilter = this.transformFilter(filter);
 
@@ -234,9 +273,16 @@ export class OpenSearchVector extends MastraVector {
       });
 
       return results;
-    } catch (error: any) {
-      console.error('Failed to query vectors:', error);
-      throw new Error(`Failed to query vectors for index ${indexName}: ${error.message}`);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_QUERY_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, topK },
+        },
+        error,
+      );
     }
   }
 
@@ -256,10 +302,10 @@ export class OpenSearchVector extends MastraVector {
   /**
    * Transforms the filter to the OpenSearch DSL.
    *
-   * @param {VectorFilter} filter - The filter to transform.
+   * @param {OpenSearchVectorFilter} filter - The filter to transform.
    * @returns {Record<string, any>} The transformed filter.
    */
-  private transformFilter(filter?: VectorFilter) {
+  private transformFilter(filter?: OpenSearchVectorFilter): any {
     const translator = new OpenSearchFilterTranslator();
     return translator.translate(filter);
   }
@@ -275,13 +321,15 @@ export class OpenSearchVector extends MastraVector {
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
   async updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void> {
-    if (!update.vector && !update.metadata) {
-      throw new Error('No updates provided');
-    }
-
+    let existingDoc;
     try {
+      if (!update.vector && !update.metadata) {
+        throw new Error('No updates provided');
+      }
+
       // First get the current document to merge with updates
-      const { body: existingDoc } = await this.client
+      const { body } = await this.client
+
         .get({
           index: indexName,
           id: id,
@@ -290,25 +338,40 @@ export class OpenSearchVector extends MastraVector {
           throw new Error(`Document with ID ${id} not found in index ${indexName}`);
         });
 
-      if (!existingDoc || !existingDoc._source) {
+      if (!body || !body._source) {
         throw new Error(`Document with ID ${id} has no source data in index ${indexName}`);
       }
+      existingDoc = body;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_UPDATE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: { indexName, id },
+        },
+        error,
+      );
+    }
 
-      const source = existingDoc._source;
-      const updatedDoc: Record<string, any> = {
-        id: source.id || id,
-      };
+    const source = existingDoc._source;
+    const updatedDoc: Record<string, any> = {
+      id: source?.id || id,
+    };
 
+    try {
       // Update vector if provided
       if (update.vector) {
         // Get index stats to check dimension
+        console.log(`1`);
         const indexInfo = await this.describeIndex({ indexName });
 
         // Validate vector dimensions
+        console.log(`2`);
         this.validateVectorDimensions([update.vector], indexInfo.dimension);
 
         updatedDoc.embedding = update.vector;
-      } else if (source.embedding) {
+      } else if (source?.embedding) {
         updatedDoc.embedding = source.embedding;
       }
 
@@ -316,10 +379,11 @@ export class OpenSearchVector extends MastraVector {
       if (update.metadata) {
         updatedDoc.metadata = update.metadata;
       } else {
-        updatedDoc.metadata = source.metadata || {};
+        updatedDoc.metadata = source?.metadata || {};
       }
 
       // Update the document
+      console.log(`3`);
       await this.client.index({
         index: indexName,
         id: id,
@@ -327,8 +391,15 @@ export class OpenSearchVector extends MastraVector {
         refresh: true,
       });
     } catch (error) {
-      console.error(`Failed to update document with ID ${id} in index ${indexName}:`, error);
-      throw error;
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_UPDATE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, id },
+        },
+        error,
+      );
     }
   }
 
@@ -347,11 +418,19 @@ export class OpenSearchVector extends MastraVector {
         refresh: true,
       });
     } catch (error: unknown) {
-      console.error(`Failed to delete document with ID ${id} from index ${indexName}:`, error);
-      // Don't throw error if document doesn't exist, just log it
-      if (error && typeof error === 'object' && 'statusCode' in error && error.statusCode !== 404) {
-        throw error;
+      // Don't throw error if document doesn't exist (404)
+      if (error && typeof error === 'object' && 'statusCode' in error && error.statusCode === 404) {
+        return;
       }
+      throw new MastraError(
+        {
+          id: 'STORAGE_OPENSEARCH_VECTOR_DELETE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, id },
+        },
+        error,
+      );
     }
   }
 }

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": ["./tsconfig.json", "../../tsconfig.build.json"],
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts", "src/**/*.mock.ts"]
+}

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
   "extends": "../../tsconfig.node.json",
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "tsup.config.ts"],
   "exclude": ["node_modules", "**/*.test.ts"]
 }

package/tsup.config.ts

@@ -0,0 +1,22 @@
+import { spawn } from 'child_process';
+import { promisify } from 'util';
+import { defineConfig } from 'tsup';
+
+const exec = promisify(spawn);
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  clean: true,
+  dts: false,
+  splitting: true,
+  treeshake: {
+    preset: 'smallest',
+  },
+  sourcemap: true,
+  onSuccess: async () => {
+    await exec('pnpm', ['tsc', '-p', 'tsconfig.build.json'], {
+      stdio: 'inherit',
+    });
+  },
+});

package/dist/_tsup-dts-rollup.d.cts

@@ -1,159 +0,0 @@
-import { BaseFilterTranslator } from '@mastra/core/vector/filter';
-import type { CreateIndexParams } from '@mastra/core';
-import type { DeleteIndexParams } from '@mastra/core';
-import type { DeleteVectorParams } from '@mastra/core';
-import type { DescribeIndexParams } from '@mastra/core';
-import type { IndexStats } from '@mastra/core';
-import { MastraVector } from '@mastra/core/vector';
-import type { OperatorSupport } from '@mastra/core/vector/filter';
-import type { QueryResult } from '@mastra/core';
-import type { QueryVectorParams } from '@mastra/core';
-import type { UpdateVectorParams } from '@mastra/core';
-import type { UpsertVectorParams } from '@mastra/core';
-import type { VectorFilter } from '@mastra/core/vector/filter';
-
-/**
- * Vector store prompt for OpenSearch. This prompt details supported filter operators, syntax, and usage examples.
- * Use this as a guide for constructing valid filters for OpenSearch vector queries in Mastra.
- */
-export declare const OPENSEARCH_PROMPT = "When querying OpenSearch, you can ONLY use the operators listed below. Any other operators will be rejected.\nImportant: Do not explain how to construct the filter\u2014use the specified operators and fields to search the content and return relevant results.\nIf a user tries to use an unsupported operator, reject the filter entirely and let them know that the operator is not supported.\n\nBasic Comparison Operators:\n- $eq: Exact match (default for field: value)\n  Example: { \"category\": \"electronics\" }\n- $ne: Not equal\n  Example: { \"category\": { \"$ne\": \"electronics\" } }\n- $gt: Greater than\n  Example: { \"price\": { \"$gt\": 100 } }\n- $gte: Greater than or equal\n  Example: { \"price\": { \"$gte\": 100 } }\n- $lt: Less than\n  Example: { \"price\": { \"$lt\": 100 } }\n- $lte: Less than or equal\n  Example: { \"price\": { \"$lte\": 100 } }\n\nArray Operators:\n- $in: Match any value in array\n  Example: { \"category\": { \"$in\": [\"electronics\", \"books\"] } }\n- $nin: Does not match any value in array\n  Example: { \"category\": { \"$nin\": [\"electronics\", \"books\"] } }\n- $all: Match all values in array\n  Example: { \"tags\": { \"$all\": [\"premium\", \"sale\"] } }\n\nLogical Operators:\n- $and: Logical AND (implicit when using multiple conditions)\n  Example: { \"$and\": [{ \"price\": { \"$gt\": 100 } }, { \"category\": \"electronics\" }] }\n- $or: Logical OR\n  Example: { \"$or\": [{ \"price\": { \"$lt\": 50 } }, { \"category\": \"books\" }] }\n- $not: Logical NOT\n  Example: { \"$not\": { \"category\": \"electronics\" } }\n\nElement Operators:\n- $exists: Check if field exists\n  Example: { \"rating\": { \"$exists\": true } }\n\nRegex Operator:\n- $regex: Match using a regular expression (ECMAScript syntax)\n  Example: { \"name\": { \"$regex\": \"^Sam.*son$\" } }\n  Note: Regex queries are supported for string fields only. Use valid ECMAScript patterns; invalid patterns will throw an error.\n\nRestrictions:\n- Nested fields are supported using dot notation (e.g., \"address.city\").\n- Multiple conditions on the same field are supported (e.g., { \"price\": { \"$gte\": 100, \"$lte\": 1000 } }).\n- Only logical operators ($and, $or, $not) can be used at the top level.\n- All other operators must be used within a field condition.\n  Valid: { \"field\": { \"$gt\": 100 } }\n  Valid: { \"$and\": [...] }\n  Invalid: { \"$gt\": 100 }\n- Logical operators must contain field conditions, not direct operators.\n  Valid: { \"$and\": [{ \"field\": { \"$gt\": 100 } }] }\n  Invalid: { \"$and\": [{ \"$gt\": 100 }] }\n- $not operator:\n  - Must be an object\n  - Cannot be empty\n  - Can be used at field level or top level\n  - Valid: { \"$not\": { \"field\": \"value\" } }\n  - Valid: { \"field\": { \"$not\": { \"$eq\": \"value\" } } }\n- Array operators work on array fields only.\n- Empty arrays in conditions are handled gracefully.\n- Regex queries are case-sensitive by default; use patterns accordingly.\n\nExample Complex Query:\n{\n  \"$and\": [\n    { \"category\": { \"$in\": [\"electronics\", \"computers\"] } },\n    { \"price\": { \"$gte\": 100, \"$lte\": 1000 } },\n    { \"tags\": { \"$all\": [\"premium\"] } },\n    { \"rating\": { \"$exists\": true, \"$gt\": 4 } },\n    { \"$or\": [\n      { \"stock\": { \"$gt\": 0 } },\n      { \"preorder\": true }\n    ]},\n    { \"name\": { \"$regex\": \"^Sam.*son$\" } }\n  ]\n}";
-
-/**
- * Translator for OpenSearch filter queries.
- * Maintains OpenSearch-compatible syntax while ensuring proper validation
- * and normalization of values.
- */
-export declare class OpenSearchFilterTranslator extends BaseFilterTranslator {
-    protected getSupportedOperators(): OperatorSupport;
-    translate(filter?: VectorFilter): VectorFilter;
-    private translateNode;
-    /**
-     * Handles translation of nested objects with dot notation fields
-     */
-    private translateNestedObject;
-    private translateLogicalOperator;
-    private translateFieldOperator;
-    /**
-     * Translates regex patterns to OpenSearch query syntax
-     */
-    private translateRegexOperator;
-    private addKeywordIfNeeded;
-    /**
-     * Helper method to handle special cases for the $not operator
-     */
-    private handleNotOperatorSpecialCases;
-    private translateOperator;
-    /**
-     * Translates field conditions to OpenSearch query syntax
-     * Handles special cases like range queries and multiple operators
-     */
-    private translateFieldConditions;
-    /**
-     * Checks if conditions can be optimized to a range query
-     */
-    private canOptimizeToRangeQuery;
-    /**
-     * Creates a range query from numeric operators
-     */
-    private createRangeQuery;
-}
-
-declare class OpenSearchVector extends MastraVector {
-    private client;
-    /**
-     * Creates a new OpenSearchVector client.
-     *
-     * @param {string} url - The url of the OpenSearch node.
-     */
-    constructor({ url }: {
-        url: string;
-    });
-    /**
-     * Creates a new collection with the specified configuration.
-     *
-     * @param {string} indexName - The name of the collection to create.
-     * @param {number} dimension - The dimension of the vectors to be stored in the collection.
-     * @param {'cosine' | 'euclidean' | 'dotproduct'} [metric=cosine] - The metric to use to sort vectors in the collection.
-     * @returns {Promise<void>} A promise that resolves when the collection is created.
-     */
-    createIndex({ indexName, dimension, metric }: CreateIndexParams): Promise<void>;
-    /**
-     * Lists all indexes.
-     *
-     * @returns {Promise<string[]>} A promise that resolves to an array of indexes.
-     */
-    listIndexes(): Promise<string[]>;
-    /**
-     * Retrieves statistics about a vector index.
-     *
-     * @param {string} indexName - The name of the index to describe
-     * @returns A promise that resolves to the index statistics including dimension, count and metric
-     */
-    describeIndex({ indexName }: DescribeIndexParams): Promise<IndexStats>;
-    /**
-     * Deletes the specified index.
-     *
-     * @param {string} indexName - The name of the index to delete.
-     * @returns {Promise<void>} A promise that resolves when the index is deleted.
-     */
-    deleteIndex({ indexName }: DeleteIndexParams): Promise<void>;
-    /**
-     * Inserts or updates vectors in the specified collection.
-     *
-     * @param {string} indexName - The name of the collection to upsert into.
-     * @param {number[][]} vectors - An array of vectors to upsert.
-     * @param {Record<string, any>[]} [metadata] - An optional array of metadata objects corresponding to each vector.
-     * @param {string[]} [ids] - An optional array of IDs corresponding to each vector. If not provided, new IDs will be generated.
-     * @returns {Promise<string[]>} A promise that resolves to an array of IDs of the upserted vectors.
-     */
-    upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]>;
-    /**
-     * Queries the specified collection using a vector and optional filter.
-     *
-     * @param {string} indexName - The name of the collection to query.
-     * @param {number[]} queryVector - The vector to query with.
-     * @param {number} [topK] - The maximum number of results to return.
-     * @param {Record<string, any>} [filter] - An optional filter to apply to the query. For more on filters in OpenSearch, see the filtering reference: https://opensearch.org/docs/latest/query-dsl/
-     * @param {boolean} [includeVectors=false] - Whether to include the vectors in the response.
-     * @returns {Promise<QueryResult[]>} A promise that resolves to an array of query results.
-     */
-    query({ indexName, queryVector, filter, topK, includeVector, }: QueryVectorParams): Promise<QueryResult[]>;
-    /**
-     * Validates the dimensions of the vectors.
-     *
-     * @param {number[][]} vectors - The vectors to validate.
-     * @param {number} dimension - The dimension of the vectors.
-     * @returns {void}
-     */
-    private validateVectorDimensions;
-    /**
-     * Transforms the filter to the OpenSearch DSL.
-     *
-     * @param {VectorFilter} filter - The filter to transform.
-     * @returns {Record<string, any>} The transformed filter.
-     */
-    private transformFilter;
-    /**
-     * Updates a vector by its ID with the provided vector and/or metadata.
-     * @param indexName - The name of the index containing the vector.
-     * @param id - The ID of the vector to update.
-     * @param update - An object containing the vector and/or metadata to update.
-     * @param update.vector - An optional array of numbers representing the new vector.
-     * @param update.metadata - An optional record containing the new metadata.
-     * @returns A promise that resolves when the update is complete.
-     * @throws Will throw an error if no updates are provided or if the update operation fails.
-     */
-    updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void>;
-    /**
-     * Deletes a vector by its ID.
-     * @param indexName - The name of the index containing the vector.
-     * @param id - The ID of the vector to delete.
-     * @returns A promise that resolves when the deletion is complete.
-     * @throws Will throw an error if the deletion operation fails.
-     */
-    deleteVector({ indexName, id }: DeleteVectorParams): Promise<void>;
-}
-export { OpenSearchVector }
-export { OpenSearchVector as OpenSearchVector_alias_1 }
-
-export { }