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

package/src/vector/index.test.ts

@@ -37,7 +37,7 @@ function waitUntilVectorsIndexed(vector: UpstashVector, indexName: string, expec
  */
 describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_TOKEN)('UpstashVector', () => {
   let vectorStore: UpstashVector;
-  const VECTOR_DIMENSION = 1536;
+  const VECTOR_DIMENSION = 1024;
   const testIndexName = 'default';
   const filterIndexName = 'filter-index';
 
@@ -250,7 +250,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({ indexName: 'mastra_default' });
       expect(stats).toEqual({
-        dimension: 1536,
+        dimension: 1024,
         metric: 'cosine',
         count: 0,
       });
@@ -1146,7 +1146,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
           vectorStore.query({
             indexName: filterIndexName,
             queryVector: createVector(0),
-            filter: { field: { $invalidOp: 'value' } },
+            filter: { field: { $invalidOp: 'value' } as any },
           }),
         ).rejects.toThrow();
       });
@@ -1196,7 +1196,7 @@ describe.skipIf(!process.env.UPSTASH_VECTOR_URL || !process.env.UPSTASH_VECTOR_T
         const results = await vectorStore.query({
           indexName: filterIndexName,
           queryVector: createVector(0),
-          filter: { $and: { not: 'an array' } },
+          filter: { $and: { not: 'an array' } as any },
         });
         expect(results.length).toBeGreaterThan(0);
       });

package/src/vector/index.ts

@@ -1,3 +1,4 @@
+import { MastraError, ErrorDomain, ErrorCategory } from '@mastra/core/error';
 import { MastraVector } from '@mastra/core/vector';
 import type {
   CreateIndexParams,
@@ -6,16 +7,14 @@ import type {
   DescribeIndexParams,
   IndexStats,
   QueryResult,
-  QueryVectorParams,
-  UpdateVectorParams,
-  UpsertVectorParams,
 } from '@mastra/core/vector';
-import type { VectorFilter } from '@mastra/core/vector/filter';
 import { Index } from '@upstash/vector';
 
 import { UpstashFilterTranslator } from './filter';
+import type { UpstashVectorFilter } from './filter';
+import type { UpstashUpsertVectorParams, UpstashQueryVectorParams, UpstashUpdateVectorParams } from './types';
 
-export class UpstashVector extends MastraVector {
+export class UpstashVector extends MastraVector<UpstashVectorFilter> {
   private client: Index;
 
   /**
@@ -37,27 +36,46 @@ export class UpstashVector extends MastraVector {
    * @param {UpsertVectorParams} params - The parameters for the upsert operation.
    * @returns {Promise<string[]>} A promise that resolves to the IDs of the upserted vectors.
    */
-  async upsert({ indexName: namespace, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
+  async upsert({
+    indexName: namespace,
+    vectors,
+    metadata,
+    ids,
+    sparseVectors,
+  }: UpstashUpsertVectorParams): Promise<string[]> {
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
 
     const points = vectors.map((vector, index) => ({
       id: generatedIds[index]!,
       vector,
+      ...(sparseVectors?.[index] && { sparseVector: sparseVectors[index] }),
       metadata: metadata?.[index],
     }));
 
-    await this.client.upsert(points, {
-      namespace,
-    });
-    return generatedIds;
+    try {
+      await this.client.upsert(points, {
+        namespace,
+      });
+      return generatedIds;
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_UPSERT_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace, vectorCount: vectors.length },
+        },
+        error,
+      );
+    }
   }
 
   /**
    * Transforms a Mastra vector filter into an Upstash-compatible filter string.
-   * @param {VectorFilter} [filter] - The filter to transform.
+   * @param {UpstashVectorFilter} [filter] - The filter to transform.
    * @returns {string | undefined} The transformed filter string, or undefined if no filter is provided.
    */
-  transformFilter(filter?: VectorFilter) {
+  transformFilter(filter?: UpstashVectorFilter) {
     const translator = new UpstashFilterTranslator();
     return translator.translate(filter);
   }
@@ -82,25 +100,43 @@ export class UpstashVector extends MastraVector {
     topK = 10,
     filter,
     includeVector = false,
-  }: QueryVectorParams): Promise<QueryResult[]> {
-    const ns = this.client.namespace(namespace);
-
-    const filterString = this.transformFilter(filter);
-    const results = await ns.query({
-      topK,
-      vector: queryVector,
-      includeVectors: includeVector,
-      includeMetadata: true,
-      ...(filterString ? { filter: filterString } : {}),
-    });
+    sparseVector,
+    fusionAlgorithm,
+    queryMode,
+  }: UpstashQueryVectorParams): Promise<QueryResult[]> {
+    try {
+      const ns = this.client.namespace(namespace);
 
-    // Map the results to our expected format
-    return (results || []).map(result => ({
-      id: `${result.id}`,
-      score: result.score,
-      metadata: result.metadata,
-      ...(includeVector && { vector: result.vector || [] }),
-    }));
+      const filterString = this.transformFilter(filter);
+      const results = await ns.query({
+        topK,
+        vector: queryVector,
+        ...(sparseVector && { sparseVector }),
+        includeVectors: includeVector,
+        includeMetadata: true,
+        ...(filterString ? { filter: filterString } : {}),
+        ...(fusionAlgorithm && { fusionAlgorithm }),
+        ...(queryMode && { queryMode }),
+      });
+
+      // Map the results to our expected format
+      return (results || []).map(result => ({
+        id: `${result.id}`,
+        score: result.score,
+        metadata: result.metadata,
+        ...(includeVector && { vector: result.vector || [] }),
+      }));
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_QUERY_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace, topK },
+        },
+        error,
+      );
+    }
   }
 
   /**
@@ -108,8 +144,19 @@ export class UpstashVector extends MastraVector {
    * @returns {Promise<string[]>} A promise that resolves to a list of index names.
    */
   async listIndexes(): Promise<string[]> {
-    const indexes = await this.client.listNamespaces();
-    return indexes.filter(Boolean);
+    try {
+      const indexes = await this.client.listNamespaces();
+      return indexes.filter(Boolean);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_LIST_INDEXES_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
   }
 
   /**
@@ -119,13 +166,25 @@ export class UpstashVector extends MastraVector {
    * @returns A promise that resolves to the index statistics including dimension, count and metric
    */
   async describeIndex({ indexName: namespace }: DescribeIndexParams): Promise<IndexStats> {
-    const info = await this.client.info();
+    try {
+      const info = await this.client.info();
 
-    return {
-      dimension: info.dimension,
-      count: info.namespaces?.[namespace]?.vectorCount || 0,
-      metric: info?.similarityFunction?.toLowerCase() as 'cosine' | 'euclidean' | 'dotproduct',
-    };
+      return {
+        dimension: info.dimension,
+        count: info.namespaces?.[namespace]?.vectorCount || 0,
+        metric: info?.similarityFunction?.toLowerCase() as 'cosine' | 'euclidean' | 'dotproduct',
+      };
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_DESCRIBE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace },
+        },
+        error,
+      );
+    }
   }
 
   /**
@@ -137,7 +196,15 @@ export class UpstashVector extends MastraVector {
     try {
       await this.client.deleteNamespace(namespace);
     } catch (error) {
-      this.logger.error('Failed to delete namespace:', error);
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_DELETE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace },
+        },
+        error,
+      );
     }
   }
 
@@ -151,37 +218,47 @@ export class UpstashVector extends MastraVector {
    * @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: namespace, 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,
-      };
+  async updateVector({ indexName: namespace, id, update }: UpstashUpdateVectorParams): Promise<void> {
+    if (!update.vector && !update.metadata && !update.sparseVector) {
+      throw new MastraError({
+        id: 'STORAGE_UPSTASH_VECTOR_UPDATE_VECTOR_FAILED',
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.THIRD_PARTY,
+        details: { namespace, id },
+        text: 'No update data provided',
+      });
+    }
 
-      await this.client.upsert(points, {
-        namespace,
+    // The upstash client throws an exception as: 'This index requires dense/sparse vectors' when
+    // only metadata is present in the update object.
+    if (!update.vector && !update.sparseVector && update.metadata) {
+      throw new MastraError({
+        id: 'STORAGE_UPSTASH_VECTOR_UPDATE_VECTOR_FAILED',
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.THIRD_PARTY,
+        details: { namespace, id },
+        text: 'Both vector and metadata must be provided for an update',
       });
-    } catch (error: any) {
-      throw new Error(`Failed to update vector by id: ${id} for index name: ${namespace}: ${error.message}`);
+    }
+
+    try {
+      const points: any = { id };
+
+      if (update.vector) points.vector = update.vector;
+      if (update.metadata) points.metadata = update.metadata;
+      if (update.sparseVector) points.sparseVector = update.sparseVector;
+
+      await this.client.upsert(points, { namespace });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_UPDATE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace, id },
+        },
+        error,
+      );
     }
   }
 
@@ -198,7 +275,16 @@ export class UpstashVector extends MastraVector {
         namespace,
       });
     } catch (error) {
-      this.logger.error(`Failed to delete vector by id: ${id} for namespace: ${namespace}:`, error);
+      const mastraError = new MastraError(
+        {
+          id: 'STORAGE_UPSTASH_VECTOR_DELETE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { namespace, id },
+        },
+        error,
+      );
+      this.logger?.error(mastraError.toString());
     }
   }
 }

package/src/vector/types.ts

@@ -0,0 +1,26 @@
+import type { UpsertVectorParams, QueryVectorParams, UpdateVectorParams } from '@mastra/core/vector';
+import type { FusionAlgorithm, QueryMode } from '@upstash/vector';
+import type { UpstashVectorFilter } from './filter';
+
+export interface UpstashSparseVector {
+  indices: number[];
+  values: number[];
+}
+
+export interface UpstashUpsertVectorParams extends UpsertVectorParams {
+  sparseVectors?: UpstashSparseVector[];
+}
+
+export interface UpstashQueryVectorParams extends QueryVectorParams<UpstashVectorFilter> {
+  sparseVector?: UpstashSparseVector;
+  fusionAlgorithm?: FusionAlgorithm;
+  queryMode?: QueryMode;
+}
+
+export interface UpstashUpdateVectorParams extends UpdateVectorParams {
+  update: {
+    vector?: number[];
+    metadata?: Record<string, any>;
+    sparseVector?: UpstashSparseVector;
+  };
+}

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',
+    });
+  },
+});