@mastra/upstash 0.0.0-vnextWorkflows-20250422142014 → 0.0.0-workflow-deno-20250616130925

package/src/vector/index.test.ts

@@ -1,7 +1,7 @@
 import type { QueryResult } from '@mastra/core/vector';
 import dotenv from 'dotenv';
 
-import { describe, it, expect, beforeAll, afterAll, beforeEach, vi, afterEach } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
 
 import { UpstashVector } from './';
 
@@ -13,7 +13,7 @@ function waitUntilVectorsIndexed(vector: UpstashVector, indexName: string, expec
     let attempts = 0;
     const interval = setInterval(async () => {
       try {
-        const stats = await vector.describeIndex(indexName);
+        const stats = await vector.describeIndex({ indexName });
         if (stats && stats.count >= expectedCount) {
           clearInterval(interval);
           resolve(true);
@@ -59,12 +59,12 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
 
     // Cleanup: delete test index
     try {
-      await vectorStore.deleteIndex(testIndexName);
+      await vectorStore.deleteIndex({ indexName: testIndexName });
     } catch (error) {
       console.warn('Failed to delete test index:', error);
     }
     try {
-      await vectorStore.deleteIndex(filterIndexName);
+      await vectorStore.deleteIndex({ indexName: filterIndexName });
     } catch (error) {
       console.warn('Failed to delete filter index:', error);
     }
@@ -122,7 +122,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
       const testIndexName = 'test-index';
 
       afterEach(async () => {
-        await vectorStore.deleteIndex(testIndexName);
+        await vectorStore.deleteIndex({ indexName: testIndexName });
       });
 
       it('should update the vector by id', async () => {
@@ -140,7 +140,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
           metadata: newMetaData,
         };
 
-        await vectorStore.updateIndexById(testIndexName, idToBeUpdated, update);
+        await vectorStore.updateVector({ indexName: testIndexName, id: idToBeUpdated, update });
 
         await waitUntilVectorsIndexed(vectorStore, testIndexName, 3);
 
@@ -167,7 +167,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
           metadata: newMetaData,
         };
 
-        await expect(vectorStore.updateIndexById(testIndexName, 'id', update)).rejects.toThrow(
+        await expect(vectorStore.updateVector({ indexName: testIndexName, id: 'id', update })).rejects.toThrow(
           'Both vector and metadata must be provided for an update',
         );
       });
@@ -183,7 +183,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
           vector: newVector,
         };
 
-        await vectorStore.updateIndexById(testIndexName, idToBeUpdated, update);
+        await vectorStore.updateVector({ indexName: testIndexName, id: idToBeUpdated, update });
 
         await waitUntilVectorsIndexed(vectorStore, testIndexName, 3);
 
@@ -198,7 +198,9 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
       }, 500000);
 
       it('should throw exception when no updates are given', async () => {
-        await expect(vectorStore.updateIndexById(testIndexName, 'id', {})).rejects.toThrow('No update data provided');
+        await expect(vectorStore.updateVector({ indexName: testIndexName, id: 'id', update: {} })).rejects.toThrow(
+          'No update data provided',
+        );
       });
     });
 
@@ -206,7 +208,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
       const testVectors = [createVector(0, 1.0), createVector(1, 1.0), createVector(2, 1.0)];
 
       afterEach(async () => {
-        await vectorStore.deleteIndex(testIndexName);
+        await vectorStore.deleteIndex({ indexName: testIndexName });
       });
 
       it('should delete the vector by id', async () => {
@@ -214,7 +216,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
         expect(ids).toHaveLength(3);
         const idToBeDeleted = ids[0];
 
-        await vectorStore.deleteIndexById(testIndexName, idToBeDeleted);
+        await vectorStore.deleteVector({ indexName: testIndexName, id: idToBeDeleted });
 
         const results: QueryResult[] = await vectorStore.query({
           indexName: testIndexName,
@@ -246,7 +248,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
     });
 
     it('should describe an index correctly', async () => {
-      const stats = await vectorStore.describeIndex('mastra_default');
+      const stats = await vectorStore.describeIndex({ indexName: 'mastra_default' });
       expect(stats).toEqual({
         dimension: 1536,
         metric: 'cosine',
@@ -256,6 +258,15 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
   });
 
   describe('Error Handling', () => {
+    const testIndexName = 'test_index_error';
+    beforeAll(async () => {
+      await vectorStore.createIndex({ indexName: testIndexName, dimension: 3 });
+    });
+
+    afterAll(async () => {
+      await vectorStore.deleteIndex({ indexName: testIndexName });
+    });
+
     it('should handle invalid dimension vectors', async () => {
       await expect(
         vectorStore.upsert({ indexName: testIndexName, vectors: [[1.0, 0.0]] }), // Wrong dimensions
@@ -1191,97 +1202,4 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
       });
     });
   });
-  describe('Deprecation Warnings', () => {
-    const indexName = 'testdeprecationwarnings';
-
-    const indexName2 = 'testdeprecationwarnings2';
-
-    let warnSpy;
-
-    afterAll(async () => {
-      await vectorStore.deleteIndex(indexName);
-      await vectorStore.deleteIndex(indexName2);
-    });
-
-    beforeEach(async () => {
-      warnSpy = vi.spyOn(vectorStore['logger'], 'warn');
-    });
-
-    afterEach(async () => {
-      warnSpy.mockRestore();
-      await vectorStore.deleteIndex(indexName2);
-    });
-
-    const createVector = (primaryDimension: number, value: number = 1.0): number[] => {
-      const vector = new Array(VECTOR_DIMENSION).fill(0);
-      vector[primaryDimension] = value;
-      // Normalize the vector for cosine similarity
-      const magnitude = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
-      return vector.map(val => val / magnitude);
-    };
-
-    it('should show deprecation warning when using individual args for upsert', async () => {
-      await vectorStore.upsert(indexName, [createVector(0, 2)], [{ test: 'data' }]);
-
-      expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Deprecation Warning: Passing individual arguments to upsert() is deprecated'),
-      );
-    });
-
-    it('should show deprecation warning when using individual args for query', async () => {
-      await vectorStore.query(indexName, createVector(0, 2), 5);
-
-      expect(warnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('Deprecation Warning: Passing individual arguments to query() is deprecated'),
-      );
-    });
-
-    it('should not show deprecation warning when using object param for query', async () => {
-      await vectorStore.query({
-        indexName,
-        queryVector: createVector(0, 2),
-        topK: 5,
-      });
-
-      expect(warnSpy).not.toHaveBeenCalled();
-    });
-
-    it('should not show deprecation warning when using object param for createIndex', async () => {
-      await vectorStore.createIndex({
-        indexName: indexName2,
-        dimension: 3,
-        metric: 'cosine',
-      });
-
-      expect(warnSpy).not.toHaveBeenCalled();
-    });
-
-    it('should not show deprecation warning when using object param for upsert', async () => {
-      await vectorStore.upsert({
-        indexName,
-        vectors: [createVector(0, 2)],
-        metadata: [{ test: 'data' }],
-      });
-
-      expect(warnSpy).not.toHaveBeenCalled();
-    });
-
-    it('should maintain backward compatibility with individual args', async () => {
-      // Query
-      const queryResults = await vectorStore.query(indexName, createVector(0, 2), 5);
-      expect(Array.isArray(queryResults)).toBe(true);
-
-      // CreateIndex
-      await expect(vectorStore.createIndex(indexName2, 3, 'cosine')).resolves.not.toThrow();
-
-      // Upsert
-      const upsertResults = await vectorStore.upsert({
-        indexName,
-        vectors: [createVector(0, 2)],
-        metadata: [{ test: 'data' }],
-      });
-      expect(Array.isArray(upsertResults)).toBe(true);
-      expect(upsertResults).toHaveLength(1);
-    });
-  });
 });

package/src/vector/index.ts

@@ -1,9 +1,13 @@
 import { MastraVector } from '@mastra/core/vector';
 import type {
   CreateIndexParams,
-  ParamsToArgs,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  DescribeIndexParams,
+  IndexStats,
   QueryResult,
   QueryVectorParams,
+  UpdateVectorParams,
   UpsertVectorParams,
 } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
@@ -22,11 +26,7 @@ export class UpstashVector extends MastraVector {
     });
   }
 
-  async upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]> {
-    const params = this.normalizeArgs<UpsertVectorParams>('upsert', args);
-
-    const { indexName, vectors, metadata, ids } = params;
-
+  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
 
     const points = vectors.map((vector, index) => ({
@@ -46,15 +46,17 @@ export class UpstashVector extends MastraVector {
     return translator.translate(filter);
   }
 
-  async createIndex(..._args: ParamsToArgs<CreateIndexParams>): Promise<void> {
+  async createIndex(_params: CreateIndexParams): Promise<void> {
     console.log('No need to call createIndex for Upstash');
   }
 
-  async query(...args: ParamsToArgs<QueryVectorParams>): Promise<QueryResult[]> {
-    const params = this.normalizeArgs<QueryVectorParams>('query', args);
-
-    const { indexName, queryVector, topK = 10, filter, includeVector = false } = params;
-
+  async query({
+    indexName,
+    queryVector,
+    topK = 10,
+    filter,
+    includeVector = false,
+  }: QueryVectorParams): Promise<QueryResult[]> {
     const ns = this.client.namespace(indexName);
 
     const filterString = this.transformFilter(filter);
@@ -80,7 +82,13 @@ export class UpstashVector extends MastraVector {
     return indexes.filter(Boolean);
   }
 
-  async describeIndex(indexName: 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
+   */
+  async describeIndex({ indexName }: DescribeIndexParams): Promise<IndexStats> {
     const info = await this.client.info();
 
     return {
@@ -90,7 +98,7 @@ export class UpstashVector extends MastraVector {
     };
   }
 
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
     try {
       await this.client.deleteNamespace(indexName);
     } catch (error) {
@@ -98,50 +106,64 @@ export class UpstashVector extends MastraVector {
     }
   }
 
-  async updateIndexById(
-    indexName: string,
-    id: string,
-    update: {
-      vector?: number[];
-      metadata?: Record<string, any>;
-    },
-  ): Promise<void> {
-    if (!update.vector && !update.metadata) {
-      throw new Error('No update data provided');
-    }
-
-    // The upstash client throws an exception as: 'This index requires dense vectors' when
-    // only metadata is present in the update object.
-    if (!update.vector && update.metadata) {
-      throw new Error('Both vector and metadata must be provided for an update');
-    }
-
-    const updatePayload: any = { id: id };
-    if (update.vector) {
-      updatePayload.vector = update.vector;
-    }
-    if (update.metadata) {
-      updatePayload.metadata = update.metadata;
+  /**
+   * 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.
+   */
+  async updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void> {
+    try {
+      if (!update.vector && !update.metadata) {
+        throw new Error('No update data provided');
+      }
+
+      // The upstash client throws an exception as: 'This index requires dense vectors' when
+      // only metadata is present in the update object.
+      if (!update.vector && update.metadata) {
+        throw new Error('Both vector and metadata must be provided for an update');
+      }
+
+      const updatePayload: any = { id: id };
+      if (update.vector) {
+        updatePayload.vector = update.vector;
+      }
+      if (update.metadata) {
+        updatePayload.metadata = update.metadata;
+      }
+
+      const points = {
+        id: updatePayload.id,
+        vector: updatePayload.vector,
+        metadata: updatePayload.metadata,
+      };
+
+      await this.client.upsert(points, {
+        namespace: indexName,
+      });
+    } catch (error: any) {
+      throw new Error(`Failed to update vector by id: ${id} for index name: ${indexName}: ${error.message}`);
     }
-
-    const points = {
-      id: updatePayload.id,
-      vector: updatePayload.vector,
-      metadata: updatePayload.metadata,
-    };
-
-    await this.client.upsert(points, {
-      namespace: indexName,
-    });
   }
 
-  async deleteIndexById(indexName: string, id: string): 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.
+   */
+  async deleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
     try {
       await this.client.delete(id, {
         namespace: indexName,
       });
     } catch (error) {
-      console.error('Failed to delete index by ID:', error);
+      console.error(`Failed to delete vector by id: ${id} for index name: ${indexName}:`, error);
     }
   }
 }

package/src/vector/prompt.ts

@@ -0,0 +1,77 @@
+/**
+ * Vector store specific prompt that details supported operators and examples.
+ * This prompt helps users construct valid filters for Upstash Vector.
+ */
+export const UPSTASH_PROMPT = `When querying Upstash Vector, you can ONLY use the operators listed below. Any other operators will be rejected.
+Important: Don't explain how to construct the filter - use the specified operators and fields to search the content and return relevant results.
+If a user tries to give an explicit operator that is not supported, reject the filter entirely and let them know that the operator is not supported.
+
+Basic Comparison Operators:
+- $eq: Exact match (default when using field: value)
+  Example: { "category": "electronics" }
+- $ne: Not equal
+  Example: { "category": { "$ne": "electronics" } }
+- $gt: Greater than
+  Example: { "price": { "$gt": 100 } }
+- $gte: Greater than or equal
+  Example: { "price": { "$gte": 100 } }
+- $lt: Less than
+  Example: { "price": { "$lt": 100 } }
+- $lte: Less than or equal
+  Example: { "price": { "$lte": 100 } }
+
+Array Operators:
+- $in: Match any value in array
+  Example: { "category": { "$in": ["electronics", "books"] } }
+- $nin: Does not match any value in array
+  Example: { "category": { "$nin": ["electronics", "books"] } }
+
+Logical Operators:
+- $and: Logical AND (can be implicit or explicit)
+  Implicit Example: { "price": { "$gt": 100 }, "category": "electronics" }
+  Explicit Example: { "$and": [{ "price": { "$gt": 100 } }, { "category": "electronics" }] }
+- $or: Logical OR
+  Example: { "$or": [{ "price": { "$lt": 50 } }, { "category": "books" }] }
+
+Element Operators:
+- $exists: Check if field exists
+  Example: { "rating": { "$exists": true } }
+
+Restrictions:
+- Regex patterns are not supported
+- Only $and and $or logical operators are supported at the top level
+- Empty arrays in $in/$nin will return no results
+- Nested fields are supported using dot notation
+- Multiple conditions on the same field are supported with both implicit and explicit $and
+- At least one key-value pair is required in filter object
+- Empty objects and undefined values are treated as no filter
+- Invalid types in comparison operators will throw errors
+- All non-logical operators must be used within a field condition
+  Valid: { "field": { "$gt": 100 } }
+  Valid: { "$and": [...] }
+  Invalid: { "$gt": 100 }
+- Logical operators must contain field conditions, not direct operators
+  Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  Invalid: { "$and": [{ "$gt": 100 }] }
+- Logical operators ($and, $or):
+  - Can only be used at top level or nested within other logical operators
+  - Can not be used on a field level, or be nested inside a field
+  - Can not be used inside an operator
+  - Valid: { "$and": [{ "field": { "$gt": 100 } }] }
+  - Valid: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
+  - Invalid: { "field": { "$and": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$or": [{ "$gt": 100 }] } }
+  - Invalid: { "field": { "$gt": { "$and": [{...}] } } }
+
+Example Complex Query:
+{
+  "$and": [
+    { "category": { "$in": ["electronics", "computers"] } },
+    { "price": { "$gte": 100, "$lte": 1000 } },
+    { "rating": { "$exists": true, "$gt": 4 } },
+    { "$or": [
+      { "stock": { "$gt": 0 } },
+      { "preorder": true }
+    ]}
+  ]
+}`;